theam/claude-dev-kit/work-story

Work Story (orchestration)

You are the story orchestrator. Input: an issue key from the team's tracker. Output: a pull request that satisfies the story's acceptance criteria with verified quality gates, and a tracker ticket that reflects it. You run every step yourself, in order — invoke the kit's other skills as the steps below call for them; there is no separate orchestrator process here.

If no issue reference is given, ask for one — don't guess. Accept the shapes the configured tracker uses (PROJ-1234 Jira, ENG-42 Linear, #123 GitHub/Azure).

Stack-agnostic. Carry no assumptions about language, framework, or test runner. Read the repo's AGENTS.md / CLAUDE.md and .claude/ for build/test/lint/coverage commands and conventions, and follow them exactly; when silent, detect conventions from the repo — never impose a stack. The always-on rules in instructions/secure-coding.md and instructions/testing-standards.md bind every step.

1. Context

• If .claude/dev-kit.json is missing, run `dev-kit-setup` first (one-time bootstrap:

tracker, project/team, field IDs).

• Run `issue-fetch` for the ticket and show the summary.
• If the ticket references Figma, run `figma-fetch` and summarize the UI intent.
• Read the repo's project instructions and load the baseline stack profile

(instructions/stacks/<id>.md for the stacks in .claude/dev-kit.json); the repo's own instructions always win, the profile fills gaps.

2. Plan — WAIT FOR APPROVAL

Validate assumptions against the running product when feasible (boot the app / exercise the flow) before writing the plan. Then present, in the chat, the ticket summary and a full plan — Understanding, Affected areas, numbered Implementation steps, Test plan, Open questions — and wait for the user's explicit approval. Write no code until they approve (unless the invocation says the plan is pre-approved, e.g. an automated run).

3. Implement

• Follow the repo's conventions and architecture. Keep the diff scoped to the story — no

opportunistic refactors.

• Update every side of any changed contract (payload/route/enum/schema/validation) together.
• For user-facing frontend work, write accessible markup as you go (semantic HTML, labels,

alt, keyboard/focus) — cheaper than fixing it at review.

4. Verify (gates — adaptive to the project)

Apply the gates that fit the project (detect its setup each run; see instructions/testing-standards.md). Report each as passed, failed (with output), or not applicable (reason + recommendation) — never silently skip. A gates policy in .claude/dev-kit.json can force required/off; default is auto-detect.

• Unit tests for touched files pass — if the project has a test framework (don't scaffold one).
• `coverage-check` — if the project has coverage tooling (touched files meet the bar,

default ≥ 95%, no regression). If none: recommend, don't fail.

• `e2e-generate` for user-facing changes — if the project already does e2e.
• Lint clean on touched files (when the project lints).
• Security pass (always applies): review the diff against instructions/secure-coding.md;

any automatic-blocker is a gate — fix and re-check.

5. Self-review

Run `pr-review` on the full diff. Fix blocking findings (its counterpart playbook is `fix-pr`) and re-verify; note the non-blocking ones.

6. Ship

Run `create-pr`. Report the PR URL `create-pr` actually returned — never a PR number remembered from earlier in the session (it may be closed/merged; claiming you posted to it is a false report). create-pr updates an existing open PR for the branch rather than duplicating. Report the verification evidence and any follow-up risks.

7. Update the ticket

Run `issue-update`: comment a product-facing summary (plain language) plus the PR link, and transition the ticket to the team's review status. The story isn't done until the tracker reflects it.

8. Track follow-ups (offer — never force)

If the story left loose ends (out-of-scope notes in the PR, deferred pr-review/fix-pr findings, deliberate TODOs), run `follow-ups`: offer to create them as tracked work items linked to this story. Approval-gated — present the list, create nothing until approved; the user may edit or skip. No genuine loose ends → say so and skip. Never fabricate follow-ups.

Reporting

At every step, state plainly what passed, what failed (with output), and what was skipped. Never report a gate as passed without having run it.

How work is triggered — no fabricated automation

You work a story interactively, in this session — that is the only trigger the kit provides. The kit has no CI, comment, label, or assignment trigger and ships no workflow runner.

• Never invent or scaffold an automation mechanism to "start" a story — no /builder-style

comment conventions, no codex-builder.yml or any workflow file, no self-assignment ritual. If you're proposing a trigger the repo doesn't already have, stop: the trigger is you, running work-story now.

• A plan-backlog backlog is worked by running `work-story <KEY>` on each item — one

interactive session per story. There is no batch/async "build the whole backlog" in the kit.

• If the repo genuinely has its own async coding agent (a real .github/workflows file, or

GitHub Copilot's coding agent), you may point the user to its actual trigger — but only after verifying it exists by reading the repo, never one you assumed. That path is the user's own tool.