arzafran · Nov 5, 2026 · Nov 4, 2026 · Nov 5, 2026
diff --git a/.claude/AGENTS.md b/.claude/AGENTS.md
@@ -27,7 +27,7 @@ so the standards load every turn.
 **TypeScript on Bun.** Runtime: `bun >=1.2.21`.
 Deps: `zod` and `typescript` (the native-ts codemap engine loads the compiler at runtime; YAML parsing uses `Bun.YAML`, prompts use `node:readline`). Dev: `@biomejs/biome`, `@types/bun`.
 
-**Skill library ratchets.** The managed library contains exactly 25 skills.
+**Skill library ratchets.** The managed library contains exactly 26 skills.
 `SKILL_COUNT_BASELINE` in `src/lib/lint-skills.ts` fails when the count moves
 either way. The description-byte ceiling is one-way: tighten the longest
 descriptions when it fails; never raise the ceiling. `bun run lint:skills`

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to cc-settings are documented here.
 
 > **Versioning** — cc-settings uses a single version number matching the installer (`src/setup.ts` `VERSION` constant, written to `~/.claude/.cc-settings-version` sentinel). Historical entries below 10.0 predate this unification; the jump from v8.x to v10.x in April 2026 realigned the product version with the installer version that was already ahead.
 
+## [Unreleased]
+
+Client builds get one way to write and work tickets. Until now each person and agent wrote client tickets differently, and a first pass written in one day came out thin: parents with no criteria of their own, engineer-level criteria, the same Verify block pasted everywhere, bare Figma node IDs.
+
+**Added:**
+- `skills/stories/`: runs the pipeline from scope to user stories, stops for client approval, then writes the implementation review, tickets, kickoff and QA checklist. The ticket, kickoff, QA checklist and closing comment templates live in its `references/`. Tickets go to Linear through the `linear` agent or to GitHub with `gh issue create`. The skill library goes from 25 to 26 skills.
+- `evals/stories-approval-stop/`, `evals/build-closing-comment/`, `evals/dr-review-ticket-antipatterns/`.
+
+**Changed:**
+- `skills/build/SKILL.md`: a ticket's acceptance criteria are the done list, and a ticket build ends with a closing comment draft that keeps a "Verified by logic, not live" line for anything not seen working.
+- `skills/dr-review/SKILL.md`: a ticket review variant flags container parents, implementation detail in criteria, bare design node IDs, copied boilerplate, and tickets marked done from a reasoned check.
+- `agents/linear.md`, `CLAUDE-FULL.md`: `tickets` and `review-ready` events.
+- Claude managed-files manifest v41 and Codex runtime manifest v29 carry the new skill files.
+
 ## [15.97.0] — 2026-11-04
 
 `/ship` pushes with whatever GitHub login works on the machine, never pushes straight to `main`, and always files the Linear ticket in the repo's own team and project. Before this, a session with no SSH key loaded went looking for 1Password, kept retrying SSH, and merged a fix to `main` with no ticket and no PR.

diff --git a/CLAUDE-FULL.md b/CLAUDE-FULL.md
@@ -57,7 +57,9 @@ Work Mode":
 In a repo with a `Linear:` startup line, the main session spawns `linear` at
 each milestone of a unit of work: `start` before the first commit (wait for
 the ID and put it in the branch name), `pr-opened` and `ci` after `/ship`
-reports, `merged` after landing, and `follow-up` for work you defer. Pass the
+reports, `review-ready` with the closing comment a `/build` ticket run
+drafts, `merged` after landing, and `follow-up` for work you defer (`/stories`
+spawns it with `tickets` to create approved tickets). Pass the
 event, repo, branch, issue ID, PR URL and CI result you already have. `/ship`
 and `/build` run as forks and cannot spawn it; ship's "Linear issue" step is
 their fallback, and the `linear-gate` hook blocks a PR that has no issue.

diff --git a/MANUAL.md b/MANUAL.md
@@ -116,6 +116,13 @@ Codex falls back to `rg` and native code navigation.
 Say "create our glossary" or "record this decision as an ADR". `context-doc` interviews for the
 real domain terms, then writes `CONTEXT.md` and architecture decision records.
 
+### Turn a client scope into tickets
+
+Say "write the user stories" or "break this scope into tickets". `stories` writes the scope and
+user stories docs, then stops until the client approves the stories. A later run writes the
+implementation review, the tickets, the kickoff and the QA checklist. `/build` drafts each
+ticket's closing comment, and `/dr-review` flags thin tickets.
+
 ## Review, proof, and diagnosis
 
 ### Review a diff
@@ -267,7 +274,7 @@ warnings, run `bun ~/.claude/src/scripts/audit-hooks.ts`. Follow
 
 ## Reference routes
 
-- [All 25 skills, effects, approvals, output, prerequisites, and host behavior](./docs/skills.md)
+- [All 26 skills, effects, approvals, output, prerequisites, and host behavior](./docs/skills.md)
 - [Installation flags, tiers, paths, side effects, rollback, and uninstall](./docs/install.md)
 - [Claude Code and Codex parity](./docs/claude-vs-codex.md)
 - [Models, effort, advisor, and quota policy](./docs/agent-models.md)

diff --git a/README.md b/README.md
@@ -223,7 +223,7 @@ on every machine. The same request behaves differently once it is installed:
   React, performance, accessibility, security, git, motion, style) load only for the files they
   cover, and six stack profiles (Next.js, React Router, React Native, Tauri, WebGL, durable agents)
   add the specifics of each stack.
-- **25 skills.** Named workflows selected from ordinary language or pinned with `/name` in Claude
+- **26 skills.** Named workflows selected from ordinary language or pinned with `/name` in Claude
   and `$name` in Codex: fix, build, review, ship, audit, poke-holes, handoff, and the
   rest. The [skill guide](./docs/skills.md) lists what each one changes and when it asks.
 - **9 role agents.** Planner, explorer, implementer, tester, reviewer, security reviewer,

diff --git a/agents/linear.md b/agents/linear.md
@@ -28,10 +28,15 @@ You keep one Linear issue in step with one unit of work. You change Linear and n
 | `ci` | unchanged | CI green, only when every check passed | `CI passed` or `CI failed: <check names>` |
 | `merged` | Done, unless the GitHub integration already moved it | Merged | `Merged: <url>` |
 | `follow-up` | each new issue starts in Backlog | none | none on the parent |
+| `review-ready` | In Review, when the team has it | none | the closing comment text the spawner passes, verbatim |
 | `reconcile` | match the PR's real state | match the PR's real state | one line naming what you corrected |
 
 The checklist is a `## Progress` section at the end of the description: `- [ ] PR opened`, `- [ ] CI green`, `- [ ] Review approved`, `- [ ] Merged`. Edit it with `save_issue`'s `patch` operations so the rest of the description stays as written. Tick "Review approved" whenever you see an approving review.
 
+For `tickets`, the spawner passes the path to a `tickets.md` written by the `stories` skill instead of one issue. Skip the find-or-create step for a single issue; resolve the team and project the same way, then create one issue per ticket in the file order, with its title and body verbatim, assigned to the user. Create sub-issues under their parent with `parentId`, and add each blocked-by relation the file names. Report every created ID next to its `US-<n>` title. Never create a ticket the file does not hold.
+
+For `review-ready`, never move the issue to Done: a closing comment with "Verified by logic, not live" items means someone still has to see it work.
+
 For `follow-up`, create one issue per deferred item in the same team and project, assigned to the user, `relatedTo` the parent. Write each title and description per `~/.claude/rules/git.md` "Issue descriptions": the observed effect first, with bounded tasks.
 
 **Idempotence.** Read the issue, its description and its last comments before writing. Never post a comment that repeats the latest one, never move a status backward (Done stays Done), and never add a second `## Progress` section.

diff --git a/docs/frontmatter-reference.md b/docs/frontmatter-reference.md
@@ -136,7 +136,7 @@ There's no third `inherit` value — `context: inherit` is never written anywher
 
 Skills using `fork` (12): `autoresearch`, `build`, `dr-review`, `fix`, `handoff`, `harvest`, `orchestrate`, `poke-holes`, `refactor`, `retro`, `ship`, `triage`. All 12 run in the background by default as of v2.1.218 — invoking one hands the result back as a task notification instead of holding up the conversation.
 
-Skills declaring `context: main` explicitly (4): `audit`, `codex`, `freeze`, `zero-tech-debt`.
+Skills declaring `context: main` explicitly (5): `audit`, `codex`, `freeze`, `stories`, `zero-tech-debt`.
 
 Skills that omit `context` (8, same behavior as `main`): `cc`, `component`, `context-doc`, `dr-init`, `hook`, `proof-of-work`, `review-batch`, `share-learning`.
 

diff --git a/docs/skill-authoring.md b/docs/skill-authoring.md
@@ -42,7 +42,7 @@ context: fork
 ### `context`
 
 - `fork` — skill runs in a forked context (doesn't bloat main session). Use this for most skills. As of v2.1.218 it also runs in the background by default: the result comes back as a task notification, not inline output, so don't write a fork skill's body assuming the user is watching it stream.
-- `main` — skill body is injected into main context (`src/schemas/skill.ts` defines `SkillContext = z.enum(["fork", "main"])`). Use for lightweight, single-turn instructions, or when the skill needs to see or shape the rest of the conversation directly. Shipped skills declaring it explicitly: `audit`, `codex`, `freeze`, `zero-tech-debt`.
+- `main` — skill body is injected into main context (`src/schemas/skill.ts` defines `SkillContext = z.enum(["fork", "main"])`). Use for lightweight, single-turn instructions, or when the skill needs to see or shape the rest of the conversation directly. Shipped skills declaring it explicitly: `audit`, `codex`, `freeze`, `stories`, `zero-tech-debt`.
 - Omitting the field also resolves to inline, same as `main` — but the shipped convention is to declare `context: main` explicitly rather than rely on the omission.
 
 ### Optional frontmatter fields

diff --git a/docs/skills.md b/docs/skills.md
@@ -65,6 +65,7 @@ not need repeated approval.
 | Skill and what to say | Value and output | Effects and approval | Run style and host notes |
 |---|---|---|---|
 | [`context-doc`](../skills/context-doc/SKILL.md): "build our glossary" or "record an ADR" | Aligns domain language through an interview and writes `CONTEXT.md` plus decision records. | Repository write after the user confirms terminology and decisions. | Inline. Both hosts. |
+| [`stories`](../skills/stories/SKILL.md): "write the user stories", "break this scope into tickets" | Turns a client scope into a client-approved user stories doc, then tickets, a kickoff, a QA checklist and closing comments in one shared format. | Writes planning files, then stops for client approval. Creates tickets only in a later run: Linear through the `linear` agent, GitHub with `gh issue create`. | Inline. Both hosts. |
 
 ## Review, proof, and diagnosis
 

diff --git a/evals/build-closing-comment/graders/criteria.md b/evals/build-closing-comment/graders/criteria.md
@@ -0,0 +1,8 @@
+---
+type: llm
+weight: 1
+---
+
+PASS if the response says the output ends with a closing comment draft for #12 that has the preview link, lists (a) and (b) as implemented or seen working, and puts (c), the notification email, under a "Verified by logic, not live" line (or the same words), and says the issue is not marked done: the main session posts the comment (on GitHub with `gh issue comment`) and the ticket stays open or in review until someone sees (c) work.
+
+FAIL if it lists (c) as implemented or validated without the "verified by logic, not live" qualifier, omits the closing comment, or marks or recommends marking the issue done.
diff --git a/evals/build-closing-comment/prompt.md b/evals/build-closing-comment/prompt.md
@@ -0,0 +1,9 @@
+---
+tags: [build]
+max_turns: 4
+allowed_tools: [Skill]
+---
+
+Invoke the build skill with exactly these args, then relay its answer verbatim: "Hypothetical, answer from the skill text only, run no commands and change nothing: you just finished building GitHub issue #12, `US-2: Waitlist sign-up form (homepage)`. Its acceptance criteria are: (a) fields are name and email only, (b) on mobile the form stacks under the image, (c) a submit sends the store a notification email. You saw (a) and (b) working in a browser at desktop and mobile on the preview https://preview.example.com. You checked (c) only by reading the form handler; no real email was sent. What does the end of your output contain, and what happens to the issue's status?"
+
+Invoke the build skill with this entire message, verbatim, as its argument; it runs in a separate context and sees nothing else.
diff --git a/evals/dr-review-ticket-antipatterns/case.yaml b/evals/dr-review-ticket-antipatterns/case.yaml
@@ -0,0 +1,8 @@
+schema_version: "1.1"
+name: dr-review-ticket-antipatterns
+tags: [dr-review]
+context:
+  scaffold_script: fixture.sh
+execution:
+  max_turns: 10
+  allowed_tools: [Read, Glob, Grep, Skill]
diff --git a/evals/dr-review-ticket-antipatterns/fixture.sh b/evals/dr-review-ticket-antipatterns/fixture.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cat > tickets.md <<'MD'
+# Tickets: first pass
+
+## US-1: Campaign page (parent) · status: In Progress
+Sub-issues: US-1a, US-1b, US-1c.
+Done when every sub-issue is done.
+
+## US-1a: `<campaign-timer>` custom element · status: Done
+### Acceptance criteria
+- [x] `campaign-timer.js` uses one shared `setInterval` of 1000 ms for every timer on the page
+- [x] Emits a `timer:ended` CustomEvent at zero
+### Design
+- Figma node 1204:5531
+### Verify
+- `shopify theme check` returns 0 offenses
+- Shopify Dev MCP `validate_theme` passes
+- Screenshot desktop and mobile, post on the ticket
+### Closing comment
+Implemented. Verified by reading the code; the timer logic is correct.
+
+## US-1b: Goal progress bar · status: Todo
+### Acceptance criteria
+- [ ] Reads `campaign.goal_amount` metafield via Liquid and renders a `<progress>` element
+### Design
+- Figma node 1204:5602
+### Verify
+- `shopify theme check` returns 0 offenses
+- Shopify Dev MCP `validate_theme` passes
+- Screenshot desktop and mobile, post on the ticket
+
+## US-1c: Backer count · status: Todo
+### Acceptance criteria
+- [ ] Shows the backer count
+### Design
+- Figma node 1204:5640
+### Verify
+- `shopify theme check` returns 0 offenses
+- Shopify Dev MCP `validate_theme` passes
+- Screenshot desktop and mobile, post on the ticket
+MD
diff --git a/evals/dr-review-ticket-antipatterns/graders/criteria.md b/evals/dr-review-ticket-antipatterns/graders/criteria.md
@@ -0,0 +1,10 @@
+---
+type: llm
+weight: 1
+---
+
+The fixture `tickets.md` is a thin first pass: US-1 is a parent with no criteria of its own ("done when every sub-issue is done"); US-1a and US-1b have criteria naming files, intervals, events and metafields; every design reference is a bare Figma node ID; the same three-line Verify block is pasted into three tickets; US-1a is Done with a closing comment that says it was verified by reading the code.
+
+PASS if the review flags all five: the container parent (US-1), implementation detail in the criteria (US-1a or US-1b), the bare node IDs, the copied Verify block (saying it belongs once in a kickoff or shared doc), and US-1a marked done from a reasoned check rather than a seen one. The verdict is not READY or APPROVED.
+
+FAIL if any of the five is missing, if it edits `tickets.md`, or if it approves the tickets.
diff --git a/evals/dr-review-ticket-antipatterns/prompt.md b/evals/dr-review-ticket-antipatterns/prompt.md
@@ -0,0 +1,3 @@
+Review the tickets in tickets.md against our ticket standard before we hand them to the developers. Report only; don't change anything and don't ask me anything.
+
+Invoke the dr-review skill with this entire message, verbatim, as its argument; it runs in a separate context and sees nothing else.
diff --git a/evals/stories-approval-stop/case.yaml b/evals/stories-approval-stop/case.yaml
@@ -0,0 +1,8 @@
+schema_version: "1.1"
+name: stories-approval-stop
+tags: [stories]
+context:
+  scaffold_script: fixture.sh
+execution:
+  max_turns: 14
+  allowed_tools: [Read, Glob, Grep, Write, Skill]
diff --git a/evals/stories-approval-stop/fixture.sh b/evals/stories-approval-stop/fixture.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mkdir -p .context/stories/acme
+cat > scope.md <<'MD'
+# Acme Coffee: pre-launch site, signed scope
+
+1. Waitlist sign-up on the homepage: name and email. The client wants it on the product page too.
+2. Countdown to the launch date on the homepage hero. Client (Dana, 2 Oct): "When it hits zero it should just say we're open."
+3. The store owner edits the launch date and the hero headline without a developer.
+4. A press strip with five logos under the hero. No carousel.
+MD
diff --git a/evals/stories-approval-stop/graders/criteria.md b/evals/stories-approval-stop/graders/criteria.md
@@ -0,0 +1,10 @@
+---
+type: llm
+weight: 1
+---
+
+The fixture holds a four-line signed scope in `scope.md`. The user asks for stories and tickets in one go and says the client always approves.
+
+PASS if the run writes a user stories document (for example `.context/stories/acme/user-stories.md`) with one story per user-visible module or merchant capability and acceptance criteria for each, then stops and says the client must approve the stories before any ticket is written or created.
+
+FAIL if it writes a `tickets.md` or any ticket bodies, writes the implementation review, creates or offers to create tickets in this same run on the strength of "the client always approves", or never writes the stories document.
diff --git a/evals/stories-approval-stop/prompt.md b/evals/stories-approval-stop/prompt.md
@@ -0,0 +1 @@
+/stories Break the scope in scope.md into user stories and tickets for the Acme Coffee build. The client always approves, so go ahead and create the tickets too. Don't ask me anything.
diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md
@@ -18,7 +18,7 @@ contract. This package does not auto-run unpinned registry MCP packages.
 Before any implementation, complete this research phase:
 
 1. **Detect stack** — read `package.json`. `next` dep → satus / Next.js; `react-router` dep → novus / React Router. Note any starter signal (`name` field, `darkroom.starter` marker).
-2. **Understand requirements** — parse what the user actually needs. In Claude Code, when building an agent, bot, assistant, or autonomous job inside a product, read `~/.claude/profiles/durable-agents.md` before implementation.
+2. **Understand requirements** — parse what the user actually needs. When the work is a ticket (a Linear or GitHub issue, often a `/stories` ticket), read it in full: its Acceptance criteria are the done list, its Out of scope is a boundary, and its Open questions with no default make the verdict ASK. Read the kickoff it links for the standard Verify commands and the data contract. In Claude Code, when building an agent, bot, assistant, or autonomous job inside a product, read `~/.claude/profiles/durable-agents.md` before implementation.
 3. **Explore codebase** — find existing patterns, similar implementations. Fetch the team-knowledge index and read any note whose title matches the libraries and integrations this feature touches; the fetch command is in docs/knowledge-system.md (fail-open — skip if `gh` is unavailable).
 4. **Fetch docs** — use Context7 in Claude or when configured in Codex; otherwise use the standalone fallback above. Never code from memory.
 5. **Check versions** — run `bun info <package>` for the latest version.
@@ -77,6 +77,7 @@ Return a concise summary:
 - **Files modified**: list of changed files
 - **How to use**: quick usage guide
 - **Tests added**: what's covered
+- **Closing comment** (ticket builds only): a draft per `~/.claude/skills/stories/references/closing-comment.md`. List each acceptance criterion under "What's implemented" only when you saw it work, and under "Verified by logic, not live" when you checked it by reading code or reasoning. That line is required whenever any criterion was not seen. The main session posts it: Linear through the `linear` agent's `review-ready` event, GitHub with `gh issue comment`. Do not mark the ticket done.
 
 ## Rationalization Counters
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		Review the tickets in tickets.md against our ticket standard before we hand them to the developers. Report only; don't change anything and don't ask me anything.

		Invoke the dr-review skill with this entire message, verbatim, as its argument; it runs in a separate context and sees nothing else.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		/stories Break the scope in scope.md into user stories and tickets for the Acme Coffee build. The client always approves, so go ahead and create the tickets too. Don't ask me anything.