| name | deliver-story |
| description | Drive ONE SciAgent backlog story from docs/reference/core.md to verified, gate-green, committed code — goal-directed end-to-end. The controller (Opus) takes the next story off the execution order, branches, gathers the contract (story + CLAUDE.md invariants + Context7 for any SDK), then executes it subagent-driven — implementation ALWAYS on cheaper models (Sonnet default, Haiku for fully-pinned mechanical tasks), Opus NEVER writes code. When ruff + pyright + pytest and the story's acceptance criteria are all green (verified by the verification-gate agent), it commits and reports. Use when the user runs /deliver-story or asks to build/ship/deliver a story (e.g. "AGT-12", "the gap-finder story", "the next story") from docs/reference/core.md. |
| disable-model-invocation | true |
Deliver a SciAgent story
Take ONE story from docs/reference/core.md (the highest-authority backlog)
and drive it goal-directed to verified, committed code:
branch → gather contract → execute TDD subagent-driven → all gates green → commit → report.
docs/reference/core.md already holds the acceptance criteria, so this is disciplined execution, not fresh
design. The controller stays on Opus and never writes implementation code — cheap subagents do
all the coding.
Announce at start: "Using deliver-story to ship <story>."
Args
<story> — a story id (AGT-12), a name (gap-finder), or next (default).
next = the topmost story in docs/reference/core.md's execution order whose dependencies are all done.
Run stories in the documented execution order; if a dependency isn't done, say so and stop
before branching.
Live state (check before branching)
- Branch + tree:
git -C "$CLAUDE_PROJECT_DIR" status -sb | head -1
- Confirm a clean working tree and that you are on
main before branching. If a feature branch
for this story already exists with work on it, resume rather than restart.
Goal mode (the operating stance)
Run the story to its acceptance criteria autonomously — branch, all TDD tasks, all gates,
commit — without pausing for per-step approval. Surface to the user only for:
- a genuine blocker (a gate two subagent attempts can't fix; missing key/secret/infra),
- an open design decision the story genuinely leaves ambiguous, or
- the final report.
Commit per task as you go; the work is always recoverable. Don't narrate every step — act.
Model policy (the point of this skill)
The expensive controller plans, dispatches, and judges; cheap subagents write the code.
- Controller (you): Opus. Read, plan, dispatch, review diffs, do git. Never write
implementation or test code yourself.
- Implementer subagents — default
model: sonnet via the matching specialist
(python-backend-engineer for src/agt/** + tests/**, zotero-frontend for the add-on,
settings-bootstrap for tooling/CI). All real coding.
- Mechanical tasks — drop to
model: haiku. Use Haiku only when the story pins the work
completely and no judgment is left. Test: "Could a careful junior do this from the task alone,
inventing nothing?" If yes → Haiku. Typical here: a Pydantic model whose fields are listed, a
pure deterministic helper fully specified by its test, fixtures, config scaffolding.
- Keep on
sonnet anything needing provider-API nuance (the federated search adapters, LLM
provider router, LangGraph workflow state), or typed-invariant judgment (the Zotero upsert path).
- Reviewer / gate —
verification-gate agent on model: haiku for running gates;
python-backend-engineer (sonnet) for code-quality review of higher-risk diffs. The
api-contract-guardian (sonnet) reviews any change to src/agt/api/** or src/agt/models.py.
- Escalation: if a Haiku implementer fails the gate twice, re-dispatch the fix on
sonnet.
Don't thrash the cheap tier on something it can't do.
State the chosen tier per task in the task list, so the cost split is visible.
Workflow
Create a TaskCreate item per phase below, then work them in order.
1. Branch (no subagent)
2. Gather the story contract (no subagent)
From docs/reference/core.md and the supporting docs, read and restate:
Restate the binding rules before any coding: TDD red→green→refactor; no live network in tests
(vcrpy cassettes, --vcr-record=none); _env_file=None in every settings fixture; deterministic;
idempotent writes; approval-gated writes; zero pyright.
3. Plan the tasks (no subagent)
Turn the story's acceptance criteria into an ordered TaskCreate list: each code task is
failing test → run-it-red → minimal code → green → commit. Assign each task its model tier.
Carry the Context7-verified call shapes into each SDK-touching task. The final task = the story's
acceptance criteria run green. Show the full list before executing.
4. Execute — subagent-driven
5. All gates green (verification-gate agent)
6. Commit / integrate (no subagent)
7. Report
Summarize: gates met (with evidence — test names, file paths, the acceptance command + its output),
the commits on the story branch, and the next story in execution order plus any dependency it
still waits on. State the model cost split (which tasks ran Sonnet vs Haiku).
Definition of done
