---
name: work-story
description: Work a user story end to end — fetch the ticket, plan (with approval), implement, verify the applicable gates, self-review, open the PR, and update the tracker. Use when given an issue key like PROJ-1234, ENG-42, or #123. This is the orchestration playbook for hosts without a dedicated orchestrator subagent (Codex, and other Agent-Plugins clients); on Claude Code the `/work-story` command + `coding-agent` subagent do this instead.
---

# 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.