[xyos]

Problem

The scaffolded AGENTS.md listed KVStore and DistributedTable without saying which to use for ordinary app records, so agents picked inconsistently for the same list-of-records task.

Changes

• The storage bullet now gives an access-pattern rule: default to DistributedTable for app records you list or query as a collection (todos, notes, orders); use KVStore for values you read and write by one key, structured or not (settings, flags, caches, sessions, per-user preferences). This follows the AWS Blocks guide's DistributedTable default for most data and the KVStore README's key-lookup guidance.
• Changeset: @aws-blocks/create-blocks-app patch.

Validation

• npx tsx scripts/changeset-guard.ts verify-coverage: passes.

• Root npm run build, then npm test -w @aws-blocks/create-blocks-app: 207/207 pass.

• Docs-only change.

• Changeset added

• Docs only, no code changes

[changeset-bot]

🦋 Changeset detected

Latest commit: 8faf175

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@aws-blocks/create-blocks-app	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Harbor agent check — advisory

20 todo-app trajectories per arm. Pass rates carry Wilson 95% intervals; metric differences are candidate − baseline medians over passed phases with a seeded bootstrap 95% interval, shown only when both arms have at least 3 passes. The primary metric is cache-neutral cost; the storage section compares arms within one storage block. Local mock mode only; nothing is deployed.

• Baseline: b16e5b68fe1726e89b09d848f79ed18b84c54879 (merge-base with the PR base).
• Candidate: 8faf1759d3993dbe18cb1d20beca59d1c7cfbed3 (PR head).
• Harness: 50b8c94c125f78b1d5ec1afa99e117b891f779cf (trusted workflow revision, both arms).
• Workflow and evidence
• baseline: 20/20 counted trials passed every phase.
• candidate: 20/20 counted trials passed every phase.

Packed packages differ between arms.

Trials

Trial	Baseline	Candidate
1	passed	passed
2	passed	passed
3	passed	passed
4	passed	passed
5	passed	passed
6	passed	passed
7	passed	passed
8	passed	passed
9	passed	passed
10	passed	passed
11	passed	passed
12	passed	passed
13	passed	passed
14	passed	passed
15	passed	passed
16	passed	passed
17	passed	passed
18	passed	passed
19	passed	passed
20	passed	passed

Pass rate

Phase	Baseline	Candidate	Baseline skill	Candidate skill
create	20/20 (100%; 84–100%)	20/20 (100%; 84–100%)	skill_tool 20	skill_tool 20
due-dates	20/20 (100%; 84–100%)	20/20 (100%; 84–100%)	none 20	none 20
labels	20/20 (100%; 84–100%)	20/20 (100%; 84–100%)	none 20	none 20
total	20/20 (100%; 84–100%)	20/20 (100%; 84–100%)	—	—

Passed-phase medians (IQR)

Phase	Arm	Cache-neutral cost (primary)	Input processed	Output	Turns	Tools	Seconds	List-price cost	New input†	Cache read†
create	baseline	$0.5838 ($0.5572–$0.6492)	844,925 (768,008–998,093)	9,658 (9,244–10,760)	25 (23.8–28.2)	23 (21.8–26.2)	376 (310–478)	$0.5063 ($0.4789–$0.5885)	30,242 (28,317–32,608)	806,178 (738,605–965,346)
create	candidate	$0.5673 ($0.5295–$0.6114)	821,908 (716,526–882,328)	9,286 (8,731–10,058)	24 (22–26)	22 (20–24)	382 (344–442)	$0.4942 ($0.4557–$0.5339)	29,427 (28,133–32,028)	791,928 (688,994–851,546)
due-dates	baseline	$0.1778 ($0.1699–$0.1949)	287,684 (258,204–357,887)	4,468 (4,268–4,706)	6 (5–7)	5 (4–6)	88.1 (77.3–95.1)	$0.1778 ($0.1700–$0.1949)	6,226 (5,743–7,702)	281,960 (251,580–350,682)
due-dates	candidate	$0.1771 ($0.1655–$0.2215)	291,009 (242,717–385,965)	4,471 (4,286–5,006)	6 (5–7)	5 (4–6)	83.8 (79.6–98.0)	$0.1772 ($0.1655–$0.2216)	6,458 (6,113–8,332)	285,054 (236,216–377,344)
labels	baseline	$0.1728 ($0.1654–$0.1919)	238,136 (222,243–302,496)	4,688 (4,418–5,060)	4 (4–5)	3 (3–4)	82.4 (77.4–96.2)	$0.1729 ($0.1654–$0.1919)	6,608 (6,128–8,132)	231,034 (215,243–295,616)
labels	candidate	$0.1666 ($0.1554–$0.1809)	229,028 (215,673–286,833)	4,368 (4,132–4,594)	4 (4–5)	3 (3–4)	75.4 (67.9–83.5)	$0.1666 ($0.1555–$0.1809)	5,988 (5,535–6,646)	222,480 (209,027–280,150)
total	baseline	$0.9568 ($0.9203–$1.0745)	1,455,130 (1,330,474–1,572,818)	19,588 (18,529–21,074)	36.5 (34.8–38.2)	32.5 (30.8–34.2)	585 (472–693)	$0.8925 ($0.8428–$0.9971)	45,001 (42,445–47,812)	1,411,131 (1,276,192–1,526,992)
total	candidate	$0.9216 ($0.8451–$0.9803)	1,333,813 (1,217,445–1,510,776)	18,540 (17,073–20,020)	34 (31.8–36.2)	30 (27.8–32.2)	553 (520–656)	$0.8429 ($0.8020–$0.9028)	42,806 (41,134–45,795)	1,292,438 (1,178,594–1,467,480)

† Descriptive, not comparable across arms: new input (uncached input + cache writes) and cache read depend on prompt-cache warm-up order, so no difference is reported for them.

Candidate − baseline

Phase	Cache-neutral cost (primary) Δ	Input processed Δ	Output Δ	Turns Δ	Tools Δ	Seconds Δ	List-price cost Δ
create	-$0.0165 (-2.8%) [-$0.0763, +$0.0235]	-23,018 (-2.7%) [-171,734, +65,280]	-372 (-3.9%) [-1,518, +364]	-1 (-4.0%) [-5, +1]	-1 (-4.3%) [-5, +1]	+6.5 (+1.7%) [-82.9, +76.8]	-$0.0121 (-2.4%) [-$0.0836, +$0.0328]
due-dates	-$0.0006 (-0.4%) [-$0.0180, +$0.0431]	+3,324 (+1.2%) [-79,635, +81,880]	+3.5 (+0.1%) [-286, +546]	+0 (+0.0%) [-2, +1.5]	+0 (+0.0%) [-2, +1.5]	-4.3 (-4.9%) [-14.2, +11.2]	-$0.0007 (-0.4%) [-$0.0180, +$0.0432]
labels	-$0.0063 (-3.6%) [-$0.0247, +$0.0080]	-9,107 (-3.8%) [-46,970, +45,818]	-320 (-6.8%) [-697, +7.5]	+0 (+0.0%) [-0.5, +1]	+0 (+0.0%) [-0.5, +1]	-7.0 (-8.5%) [-16.7, +0]	-$0.0063 (-3.6%) [-$0.0247, +$0.0080]
total	-$0.0352 (-3.7%) [-$0.1374, +$0.0278]	-121,316 (-8.3%) [-250,916, +55,396]	-1,048 (-5.4%) [-2,721, +325]	-2.5 (-6.8%) [-5.5, +0]	-2.5 (-7.7%) [-5.5, +0]	-32.6 (-5.6%) [-126, +82.7]	-$0.0496 (-5.6%) [-$0.1387, +$0.0254]

Δ is the difference of medians (percent of the baseline median) [bootstrap 95% interval]. A phase passes when it and every earlier phase passed with complete accounting in one session. Trials without a result or with an infrastructure error are excluded from rates. Cache-neutral cost is the primary metric: each phase at the pinned model’s list prices as if its own session wrote every context token to the prompt cache once (context growth at the cache-write rate, the rest of the input processed at the cache-read rate, output at the output rate), so it does not depend on which concurrent session warmed the cache. Input processed = uncached input + cache writes + cache reads. List-price cost is Claude Code’s estimate, not AWS billing, and is secondary: it moves with cache hits from other sessions. Failed or incomplete work is excluded from metrics: less usage there is not an efficiency win. skill shows how the agent reached the installed aws-blocks skill.

Storage block

Storage	Baseline trials	Candidate trials	Baseline cache-neutral cost	Candidate cache-neutral cost	Candidate − baseline
kv_store	5	0	$0.9390 (5 passed)	—	not comparable (0 passes)
distributed_table	15	20	$0.9619 (15 passed)	$0.9216 (20 passed)	-$0.0403 (-4.2%) [-$0.1871, +$0.0251]

The storage block the create phase constructed, read from its snapshot. It moves cost by itself, so a different storage mix between arms shifts the pooled medians above. Costs here are whole-run medians over trials that passed every phase; a difference is shown only when both arms have at least 3 such passes in that storage.