agent_personal_shopper v1.0.0

name: agent_personal_shopper description: "Run an agent as a personal shopper for one buyer: take a short brief with sizes and fit, budget cap, deadline, and stores to avoid, search across stores instead of one catalog, compare total cost with shipping and return terms side by side, check the return policy before anything is bought, and stop for approval on the exact item and total unless a written budget rule already covers it, with an auditable order log. Triggers on: shop for me, find and buy this, personal shopper, compare stores and buy the best one, reorder this in my size, buy this within my budget, gift shopping for someone."

Agent Personal Shopper

Purpose

Work one real shopping job for one buyer, from brief to delivered order, without the three failures that cost buyers money: buying on sticker price while shipping and fees quietly pass the budget, accepting a store's return terms without reading them, and ordering without a clear yes on the exact item and total.

This skill is store neutral. It does not live inside one retailer's catalog and it does not hold the budget inside a host app. The brief, the comparison, the policy check, and the order log are plain files in the job folder, so the buyer can read, audit, and move them.

Two scripts do the arithmetic and the policy gate:

• scripts/compare.py ranks candidates by true total cost and flags over budget and late candidates.
• scripts/policy_check.py turns one store's return policy into a PASS, WARN, or BLOCK verdict before any money moves.

Workflow

1. Take the brief, in writing

• Start every job with the brief form in references/brief-form.md. Fill it with the buyer: what is needed, must-haves, size and fit, quantity, budget cap on the total (not the sticker price), deadline and why, stores to avoid, acceptable substitutes, and what must never be substituted.
• Ask about missing lines instead of guessing them. Size, deadline, and budget cap are never optional. A job without them is a search, not a shopping job, and it does not end in a purchase.
• Record fit as measurements where the item is worn, not just a label size. Label sizes differ across brands. The measuring method is in the brief form.
• Write down any budget rule the buyer gives, word for word, in the job folder. That rule is the only standing permission to buy without stopping. The brief form lists what counts as a rule and what does not.

2. Search across stores

• Search at least three sellers for the same need, unless the buyer named one store or the item only exists in one place. Say which of those two exceptions applies if you search fewer.
• Skip every store on the brief's avoid list, even when it is cheapest. Note the skip in the comparison so the buyer sees the cost of their own rule.
• For each candidate record: store, item and variant (size, colour, model), product URL, stock wording, sticker price, and the date you read the page. Search results and memory do not confirm price or stock. Only a product or checkout page read in this run does.
• Read condition wording closely. Words such as refurbished, vintage, open box, or close-out change what the buyer is getting, and they go into the shortlist word for word.

3. Compare total cost, side by side

• Build a candidates file and rank it:

python3 ~/workspace/skills/agent-personal-shopper/scripts/compare.py candidates.json --json ranked.json

• Total means price plus shipping plus handling plus tax plus mandatory fees, minus any discount that actually applies to this order. Use the tax figure the store shows at checkout or a figure the buyer supplied. Never invent a tax rate.
• Free shipping with a minimum spend only counts if this order meets the minimum on its own merits. Do not pad a cart to chase a shipping threshold unless the buyer asked for the extra items.
• Candidates flagged OVER_BUDGET or LATE are out, unless the buyer changes the budget or deadline in writing. The cheapest sticker price is often not the cheapest total, as the worked example in references/worked-example.md shows.

4. Check the return policy before anything is bought

• For the leading candidate, and for any close second, open the store's returns page in this run and capture: return window in days, refund method, who pays return shipping, restocking fee, condition requirements, final sale status, policy URL, and the capture date.
• Run the check:

python3 ~/workspace/skills/agent-personal-shopper/scripts/policy_check.py policy.json

• BLOCK means final sale, no stated return window, or no stated refund method. Do not buy a BLOCK candidate on a budget rule. It can only be bought after the buyer sees the block in writing and says yes anyway.
• WARN means a short window, a restocking fee, buyer paid return shipping, or unknown conditions. Quote every warning in the approval request.
• There is no general legal right to return an item just for a change of mind. The posted policy, read before buying, is usually the whole of the buyer's protection on fit and taste, which is why this step sits before the purchase and not after a problem.

5. Stop for approval on the exact item and total

• Unless a written budget rule from step 1 covers this exact buy, stop and send one approval request: item and variant, store, total with its parts broken out, delivery date against the deadline, the return terms including every WARN line, and the best runner-up with why it lost.
• One yes covers one order at the approved total. If the total changes at checkout, the item variant changes, or the store swaps in a substitute, the yes is spent. Stop again.
• Never accept, on the buyer's behalf, a store's delay consent prompt, a substitute item, a store credit instead of a refund, or an extended warranty or add-on at checkout. Each of those is a new decision for the buyer.
• If a budget rule does cover the buy, still log the purchase the same day with the rule quoted, so the buyer can audit it and revoke the rule.

6. Buy, verify the confirmation, and log it

• Buy through the store's normal checkout, with the payment method the buyer approved for this job. Prefer a credit card when the buyer has a choice: FTC guidance notes it carries dispute rights other methods may not, including the right to dispute a charge and have payment withheld while it is investigated.
• Compare the order confirmation against the approval before closing the job: item, variant, quantity, and total must match. Any difference gets reported to the buyer the same day, with the cancel option while cancelling is still simple.
• Note the promised ship date. Under the FTC Mail, Internet, or Telephone Order Merchandise Rule (16 CFR Part 435), a seller must ship within the time it advertised, or within 30 days if it stated no time, and must seek consent or refund if it cannot. If a delay notice arrives, forward it to the buyer instead of consenting for them.
• Append every event to the order log in the format in references/order-log.md, and keep the records pack listed there: seller contact, product description, total breakdown, the captured return policy, promised ship date, and messages with the seller.

7. Close the job on delivery

• Confirm delivery and, for worn items, fit, with the buyer. Start the return inside the window if the buyer wants one, and record who pays return shipping before sending anything back.
• Log the return window closing date. A job is not closed while a return the buyer asked for is still unshipped or a refund is still missing.
• If goods never arrive, arrive materially different, or a refund stalls, hand the buyer the records pack and name the credit card dispute deadline plainly: a billing error notice must reach the card issuer no later than 60 days after the first statement showing the charge was sent, under the Fair Credit Billing Act and Regulation Z, 12 CFR 1026.13.

Output Contract

A finished shopping job delivers:

• The filled brief, kept in the job folder.
• A ranked comparison from compare.py covering at least three sellers, or the named exception, with totals broken into price, shipping, handling, tax, fees, and discount.
• A policy check result for the bought candidate, with the policy URL and capture date, and every BLOCK or WARN line shown to the buyer before purchase.
• The approval record: the exact request sent and the buyer's answer, or the written budget rule that covered the buy, quoted.
• The order log, up to date through delivery, with the confirmation total checked against the approved total and any difference reported.
• A one line summary: item, store, total paid, delivery date, and return window closing date.

Operating Rules

1. No brief, no buy. Missing size, budget cap, or deadline means search and report only.
2. Compare totals, never sticker prices. A candidate with unknown shipping or tax is incomplete, not cheap.
3. Read the return policy in this run, from the store's own page, before buying. A policy remembered from a past job is not a policy check.
4. Approval is for one exact item at one exact total in one store. Any change spends it.
5. Never consent for the buyer: not to a shipping delay, a substitute, store credit in place of a refund, or a checkout add-on.
6. Avoid list beats price. A store the buyer said to avoid is out even when it wins the comparison.
7. Keep personal data in the job folder. Full card numbers, full addresses, and passwords never go in the order log, a chat summary, or a shared file.
8. Do not buy from a seller that only accepts gift cards, wire transfer, or other payment with no dispute route. FTC guidance treats that demand as a warning sign. Report it and pick another seller.
9. If every candidate is over budget, late, or BLOCK, buy nothing. Report the closest misses with their real totals and ask the buyer which constraint moves.
10. Prices, stock, delivery dates, and policies in this skill's examples are illustrative. In a real job, every such fact comes from a page read in that run, dated in the job folder.