Recipe · Ship a story end-to-end

Goal: take a single story from "next on the board" through to reviewed code with tests and a paper trail. This is the scale-up route — the default way to ship stays the Quick flow; reach for the story cycle when the work earns a sprint board and the full paper trail.

Time: highly variable — 30 minutes to half a day per story depending on size · Skills: e11-create-story → e11-dev-story → e11-code-review · Phase: 4 — Implementation

Prerequisites

• Phase 3 complete: PRD, architecture spine, epics-and-stories, readiness report in {planning_artifacts}/.
• Sprint board from [SP] e11-sprint-planning, at {implementation_artifacts}/sprint-status.yaml.
• @engineering11/alloy installed — [DS] pre-loads platform docs before writing any code and halts on gaps.

If those aren't done, you're in the wrong recipe. See Phase 4 — Implementation for the full lifecycle, or Quick flow if this doesn't need story ceremony at all.

Walkthrough

1. Prepare the story

You: skill:e11-create-story

Skill: Reading sprint-status.yaml ... first backlog story is 2-3 "Tenant switch UI hook-up".
    Loading epics.md §Epic 2, prd.md §3.2 (multi-tenancy), ARCHITECTURE-SPINE.md.

    Drafting story file:
      - 5 tasks, 14 subtasks — each with explicit file paths
      - 7 acceptance criteria (Given/When/Then)
      - E11 SDKs touched: @engineering11/access, @engineering11/user
      - Dev Notes: architecture requirements, prior-story learnings

    Written: implementation-artifacts/2-3-tenant-switch.md
    Sprint status: 2-3-tenant-switch → ready-for-dev.

    Next: [VS] to validate, or e11-dev-story to implement.

e11-create-story is a context engine, not a copier — it mines the epics, PRD, architecture, and previous stories so Dev never has to guess.

2. Validate (optional but cheap)

You: skill:e11-create-story validate 2-3

Skill: Validating 2-3-tenant-switch.md against the checklist:
      [x] All tasks have explicit files
      [x] All ACs in Given/When/Then
      [x] SDK stamp matches the architecture's composition table
      [x] No undefined references (no "see PRD §X" without a §X)
      [x] Acceptance criteria are mechanically testable
    Validation passed. Hand to Dev.

3. Implement

You: skill:e11-dev-story

Dev: Loaded 2-3-tenant-switch.md. Status → in-progress, baseline_commit stamped.

     Alloy pre-load (capability-driven):
       Task flavor: frontend — React conventions govern capability choices
       SDK docs:
         alloy://sources/sdks-react/sdks/access/frontend-using.md ✓
         alloy://sources/sdks-react/sdks/user/frontend-using.md   ✓
     ✅ Alloy pre-load complete — recorded in Dev Agent Record.

     Task 1/5: Add useTenantSwitch hook in src/hooks/useTenantSwitch.ts
       [red: writes failing test] [green: implements] [refactor]
       [npm test] → 142 passed, 0 failed
       ✓ Task 1 marked [x]. File List updated.

     Task 2/5: Wire hook to TenantSwitcher component
       ...

     Story 2-3 complete. All tests passing (151/151).
     Dev Agent Record:
       - Used TenantSwitch.SetActive() per alloy://sources/sdks-react/sdks/access/frontend-using.md §useTenant
       - Optimistic state update with rollback on error
     File List (8 files): ...
     Status → review (sprint board synced).

     Tip: run code-review with a DIFFERENT LLM than the one that implemented.

Two behaviors worth knowing about the pre-load:

• It's capability-driven, not just import-driven: for backend stories it loads the platform capability map and forbidden-patterns doc first, derives what the tasks need (HTTP, secrets, storage, …), and loads those SDKs' docs even if the story never named them. A raw axios import or process.env secret read fails the self-check at test time.
• An SDK with no alloy doc and no readable source halts the run with [R]ead source / [S]kip (recorded) / [A]scalate to Architect. Skips land in the Change Log, where the review's alloy auditor checks them.

4. Review (fresh context, ideally a different model)

Open a new session and run:

You: skill:e11-code-review story 2-3

Review: Sprint board shows 2-3-tenant-switch in review — reviewing its changes
     against baseline_commit. Spec context: 2-3-tenant-switch.md (full mode).

     Running five layers as parallel subagents:
       blind-hunter · edge-case-hunter · verification-gap ·
       acceptance-auditor · alloy-auditor

     Triage (orchestrator rates severity, dedups):
       decision-needed (0)
       patch (1):  useTenantSwitch.ts:42 — error path doesn't roll back optimistic state
       defer (1):  missing JSDoc on public hook → deferred-work.md
       dismiss (2)

     Review appended to the story file (Senior Developer Review + Action Items).
     Outcome: Changes Requested — 1 item.

5. Address findings

Back in an implementation session, e11-dev-story detects the review and prioritizes the follow-ups:

You: skill:e11-dev-story

Dev: ⏯️ Resuming 2-3 after code review (Changes Requested, 1 item).
     [AI-Review] useTenantSwitch.ts:42 error rollback
       [implements rollback] [updates test] [npm test] → 152 passed
     All review items resolved; Change Log updated. Status → review.

6. Optional extra coverage

• skill:e11-qa-generate-e2e-tests ([QA]) — adds API/E2E scenarios using the project's own test framework.
• skill:e11-checkpoint-preview ([CP]) — a guided human walkthrough of the change when you want eyes-on before merge.

7. Repeat — or close the epic

More stories in the sprint? skill:e11-create-story picks up the next backlog entry. Epic complete?

You: skill:e11-retrospective

Skill: Epic 2 (Multi-tenancy) retrospective — running the roster over what shipped:
    what landed vs estimated, surprises surfaced, platform debt accumulated
    (alloy gaps hit during pre-loads, deferred review items).
    Written: implementation-artifacts/retrospective-epic-2.md

The unattended alternative

Trust the story enough to not watch? skill:e11-dev-auto runs the same iteration — clarify → plan → implement → layered self-review — with no human interaction, HALTing done or blocked and writing e11-dev-auto-result.json for automation callers. From the shell: e11 agent dev "run e11-dev-auto for story 2-3", or e11 pipeline to chain stories. See Unattended runs.

Gotchas

• Don't edit the story file mid-[DS]. Dev reads tasks in order and refuses to skip. If a task is wrong, halt Dev, fix the story, re-run.
• Tests must actually pass. Dev's rules forbid faking — no task gets its [x] until its tests exist and the full suite is green. A checked task with a red suite is a bug worth reporting.
• [CR] in the same context as [DS] is the most common mistake. The reviewer needs cold eyes. New session; different model if you have one.
• Don't bypass the alloy halt. [S]kip exists, but it's recorded and audited — the alloy-auditor layer flags skips that don't appear in the Change Log.
• One story at a time. The story file is the contract; one story = one [DS] invocation.

Source

Workflows: e11-create-story/SKILL.md · e11-dev-story/SKILL.md · e11-code-review/SKILL.md · e11-qa-generate-e2e-tests/SKILL.md · e11-retrospective/SKILL.md

See also: Quick flow (the lighter equivalent) · Run an adversarial review (the review battery, standalone) · Unattended runs.