ags-dev-story

name	ags-dev-story
description	Read a story file and implement it. Loads the full context (story, GDD requirement, ADR guidelines, control manifest), routes to the right programmer agent for the system and engine, implements the code and test, and confirms each acceptance criterion. The core implementation skill — run after /ags-story-readiness, before /ags-code-review and /ags-story-done.
argument-hint	[story-path]
user-invocable	true
allowed-tools	Read, Glob, Grep, Write, Bash, Task, AskUserQuestion

Language: Talk to user in language from .ags/project/user-interaction.md. Fall back to English if file missing. Files on disk always English per .ags/rules/user-interaction.md.

Dev Story

Bridges planning and code. Reads story file, assembles full context, routes to correct specialist, drives implementation to completion — including writing the test.

The loop for every story:

/ags-qa-plan sprint           ← define test requirements before sprint begins
/ags-story-readiness [path]   ← validate before starting
/ags-dev-story [path]         ← implement it  (this skill)
/ags-code-review [files]      ← review it
/ags-story-done [path]        ← verify and close it

After all sprint stories are done: run /ags-team-qa sprint to execute the full QA cycle and get a sign-off verdict before advancing the project stage.

Output: Source code + test file in the project's Assets/Scripts/ and tests/ directories.

---

Phase 0: Prerequisites

Verify required artifacts before any work. STOP on first missing item with redirect.

Artifact	Created by	If missing
.ags/project/stage.md (Phase = production)	/ags-gate-check production	STOP. "Not in production phase. Run /ags-gate-check production to advance."
Active .ags/project/epics/[slug]/EPIC.md	/ags-create-epics	STOP. "No active epic. Run /ags-create-epics first."
At least one story file under .ags/project/epics/[slug]/stories/	/ags-create-stories	STOP. "No stories in active epic. Run /ags-create-stories [slug] first."
design/architecture/control-manifest.md	/ags-create-control-manifest	STOP. "Control manifest missing. Run /ags-create-control-manifest seed."

If any STOP triggers, exit with verdict BLOCKED — missing prerequisite.

---

Phase 1: Find the Story

If a path is provided: read that file directly.

If no argument: check .ags/project/state.md for the active story. If found, confirm: "Continuing work on [story title] — is that correct?" If not found, ask: "Which story are we implementing?" Glob .ags/project/epics/**/*.md and list stories with Status: Ready.

---

Phase 2: Load Full Context

Before loading any context, verify required files exist. Extract the ADR path from the story's ADR Governing Implementation field, then check:

File	Path	If missing
TR registry	design/architecture/tr-registry.yaml	STOP — "TR registry not found. Run /ags-create-epics to generate it."
Governing ADR	path from story's ADR field	STOP — "ADR file [path] not found. Run /ags-architecture-decision to create it, or correct the filename in the story's ADR field."
Control manifest	design/architecture/control-manifest.md	WARN and continue — "Control manifest not found — layer rules cannot be checked. Run /ags-create-control-manifest."

If the TR registry or governing ADR is missing, set the story status to BLOCKED in the session state and do not spawn any programmer agent.

Read all of the following simultaneously — these are independent reads. Do not start implementation until all context is loaded:

The story file

Extract and hold:

• Story title, ID, layer, type (Logic / Integration / Visual/Feel / UI / Config/Data)
• TR-ID — the GDD requirement identifier
• Governing ADR reference
• Manifest Version embedded in story header
• Acceptance Criteria — every checkbox item, verbatim
• Implementation Notes — the ADR guidance section in the story
• Out of Scope boundaries
• Test Evidence — the required test file path
• Dependencies — what must be DONE before this story

The TR registry

Read design/architecture/tr-registry.yaml. Look up the story's TR-ID. Read the current requirement text — this is the source of truth for what the GDD requires now. Do not rely on any inline text in the story file (may be stale).

The governing ADR

Read design/architecture/[adr-file].md. Extract:

• The full Decision section
• The Implementation Guidelines section (this is what the programmer follows)
• The Engine Compatibility section (post-cutoff APIs, known risks)
• The ADR Dependencies section

The control manifest

Read design/architecture/control-manifest.md. Extract the rules for this story's layer:

• Required patterns
• Forbidden patterns
• Performance guardrails

Check: does the story's embedded Manifest Version match the current manifest header date? If they differ, use AskUserQuestion before proceeding:

• Prompt: "Story was written against manifest v[story-date]. Current manifest is v[current-date]. New rules may apply. How do you want to proceed?"
• Options:
  • [A] Update story manifest version and implement with current rules (Recommended)
  • [B] Implement with old rules — I accept the risk of non-compliance
  • [C] Stop here — I want to review the manifest diff first

If [A]: edit the story file's Manifest Version: field to the current manifest date before spawning the programmer. Then read the manifest carefully for new rules. If [B]: read the manifest carefully for new rules anyway, and note the version mismatch in the Phase 6 summary under "Deviations". If [C]: stop. Do not spawn any agent. Let the user review and re-run /ags-dev-story.

Dependency validation

After extracting the Dependencies list from the story file, validate each:

1. Glob .ags/project/epics/**/*.md to find each dependency story file.
2. Read its Status: field.
3. If any dependency has Status other than Complete or Done:
   • Use AskUserQuestion:
     • Prompt: "Story '[current story]' depends on '[dependency title]' which is currently [status], not Complete. How do you want to proceed?"
     • Options:
       • [A] Proceed anyway — I accept the dependency risk
       • [B] Stop — I'll complete the dependency first
       • [C] The dependency is done but status wasn't updated — mark it Complete and continue
   • If [B]: set story status to BLOCKED in session state and stop. Do not spawn any programmer agent.
   • If [C]: ask "May I update [dependency path] Status to Complete?" before continuing.
   • If [A]: note in Phase 6 summary under "Deviations": "Implemented with incomplete dependency: [dependency title] — [status]."

If a dependency file cannot be found: warn "Dependency story not found: [path]. Verify the path or create the story file."

---

Engine reference

Read .ags/rules/technical-preferences.md:

• Engine: value — determines which programmer agents to use
• Naming conventions (class names, file names, signal/event names)
• Performance budgets (frame budget, memory ceiling)
• Forbidden patterns

---

Phase 3: Route to the Right Programmer

Based on the story's Layer, Type, and system name, determine which specialist to spawn via Task.

Config/Data stories — skip agent spawning entirely: If the story's Type is Config/Data, no programmer agent or engine specialist is needed. Jump directly to Phase 4 (Config/Data note). The implementation is a data file edit — no routing table evaluation, no engine specialist.

Primary agent routing table

Story context	Primary agent
Foundation layer — any type	engine-programmer
Any layer — Type: UI	ui-programmer
Any layer — Type: Visual/Feel	gameplay-programmer (implements)
Core or Feature — gameplay mechanics	gameplay-programmer
Core or Feature — AI behaviour, pathfinding	ai-programmer
Core or Feature — networking, replication	network-programmer
Config/Data — no code	No agent needed (see Phase 4 Config note)

Engine specialist — always spawn as secondary for code stories

Read the Engine Specialists section of .ags/rules/technical-preferences.md to get the configured primary specialist. Spawn them alongside the primary agent when the story involves engine-specific APIs, patterns, or the ADR has HIGH engine risk.

Engine	Specialist agents available
Unity	unity-specialist (general + shader/addressables/UI), unity-dots-specialist (ECS/Jobs/Burst)

When engine risk is HIGH (from the ADR or VERSION.md): always spawn the engine specialist, even for non-engine-facing stories. High risk means the ADR records assumptions about post-cutoff engine APIs that need expert verification.

---

Phase 4: Implement

Spawn the chosen programmer agent(s) via Task with the full context package:

Provide the agent with:

1. The complete story file content
2. The current GDD requirement text (from TR registry)
3. The ADR Decision + Implementation Guidelines (verbatim — do not summarise)
4. The control manifest rules for this layer
5. The engine naming conventions and performance budgets
6. Any engine-specific notes from the ADR Engine Compatibility section
7. The test file path that must be created
8. Explicit instruction: implement this story and write the test

The agent should:

• Create or modify files in Assets/Scripts/ following the ADR guidelines
• Respect all Required and Forbidden patterns from the control manifest
• Stay within the story's Out of Scope boundaries (do not touch unrelated files)
• Write clean, doc-commented public APIs
• Apply .ags/rules/design-principles.md:
  • §1 YAGNI — implement only what story acceptance criteria require; no speculative abstractions, helpers, or "while we're here" refactors
  • §6 Fail Fast — validate content / config / data on load; raise loud structured error on missing-ref, out-of-range, or schema mismatch; no silent fallback
  • §7 Observability — add structured logs / counters for perf-sensitive or gameplay-critical paths per coding.md §9

Config/Data stories (no agent needed)

For Type: Config/Data stories, no programmer agent is required. The implementation is editing a data file. Read the story's acceptance criteria and make the specified changes to the data file directly. Note which values were changed and what they changed from/to.

Visual/Feel stories

Spawn gameplay-programmer to implement the code/animation calls. Note that Visual/Feel acceptance criteria cannot be auto-verified — the "does it feel right?" check happens in /ags-story-done via manual confirmation.

---

Phase 5: Write the Test

For Logic and Integration stories, the test must be written as part of this implementation — not deferred to later.

Remind the programmer agent:

"The test file for this story is required at: [path from Test Evidence section]. The story cannot be closed via /ags-story-done without it. Write the test alongside the implementation, not after."

Test requirements (from coding-standards.md):

• File name: [system]_[feature]_test.[ext]
• Function names: test_[scenario]_[expected_outcome]
• Each acceptance criterion must have at least one test function covering it
• No random seeds, no time-dependent assertions, no external I/O
• Test the formula bounds from the GDD Formulas section

For Visual/Feel and UI stories: no automated test. Remind the agent to note in the implementation summary what manual evidence will be needed: "Evidence doc required at .ags/project/qa/evidence/[slug]-evidence.md."

For Config/Data stories: no test file. A smoke check will serve as evidence.

---

Phase 6: Collect and Summarise

After the programmer agent(s) complete, collect:

• Files created or modified (with paths)
• Test file created (path and number of test functions written)
• Any deviations from the story's Out of Scope boundary (flag these)
• Any questions or blockers the agent surfaced
• Any engine-specific risks the specialist flagged

Present a concise implementation summary:

## Implementation Complete: [Story Title]

**Files changed**:
- `Assets/Scripts/[path]` — created / modified ([brief description])
- `tests/[path]` — test file ([N] test functions)

**Acceptance criteria covered**:
- [x] [criterion] — implemented in [file:function]
- [x] [criterion] — covered by test [test_name]
- [ ] [criterion] — DEFERRED: requires playtest (Visual/Feel)

**Deviations from scope**: [None] or [list files touched outside story boundary]
**Engine risks flagged**: [None] or [specialist finding]
**Blockers**: [None] or [describe]

Ready for: `/ags-code-review [file1] [file2]` then `/ags-story-done [story-path]`

---

Phase 6b: Internal Review Loop (Code Review)

Spawn lead-programmer via Task to perform code review on the changeset (files + test). Pass: changed file paths, story acceptance criteria, ADR references, project coding rules.

Loop exit condition. Single iteration where the reviewer returns clean (no critical/high/medium findings; ACs covered; tests pass on a quick mental walkthrough or by Bash test runner if configured). Non-clean → user (or further programmer agents) revises code, re-spawn lead-programmer review. No iteration cap.

Record iteration count.

Combined Review Loop (parallel external Codex)

Per .ags/rules/review-workflow.md. The internal review section above runs in parallel with external Codex inside one loop. Each iteration:

1. Resolve severity floor: iter 1-2 → keep all severities; iter 3-4 → critical/high; iter 5+ → critical only.
2. Persist current draft to .ags/project/reviews/.tmp/[type]-[slug]-iter[N]-draft.md.
3. Spawn in one message, in parallel (multiple Task calls + one Bash invocation):
   • All internal reviewer Tasks listed above.
   • /ags-external-review [type] [draft-path] --embedded-parallel --iteration [N] --min-severity [floor] — Codex unavailable returns skipped: codex-unavailable; aggregator logs skip in decisions-log and continues with internal pool only.
4. Aggregator (producer by default; skill-designated lead where the skill specifies one) merges findings from internal + external, drops nitpicks + below-floor.
5. Loop exit: filtered set empty → proceed to write approval. Non-empty → surface aggregated kept findings, user revises draft, N++, repeat.

No iteration cap. No user-confirm gate before external — it runs every iteration automatically. Record final iteration count for the decisions-log entry written at skill completion.

---

Phase 7: Update Session State

Silently append to .ags/project/state.md:

## Session Extract — /ags-dev-story [date]
- Story: [story-path] — [story title]
- Files changed: [comma-separated list]
- Test written: [path, or "None — Visual/Feel/Config story"]
- Blockers: [None, or description]
- Next: /ags-code-review [files] then /ags-story-done [story-path]

Create state.md if it does not exist. Confirm: "Session state updated."

---

Error Recovery Protocol

If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:

1. Surface immediately: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
2. Assess dependencies: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
3. Offer options via AskUserQuestion with choices:
   • Skip this agent and note the gap in the final report
   • Retry with narrower scope
   • Stop here and resolve the blocker first
4. Always produce a partial report — output whatever was completed. Never discard work because one agent blocked.

Common blockers:

• Input file missing (story not found, GDD absent) → redirect to the skill that creates it
• ADR status is Proposed → do not implement; run /ags-architecture-decision first
• Scope too large → split into two stories via /ags-create-stories
• Conflicting instructions between ADR and story → surface the conflict, do not guess
• Manifest version mismatch → show diff to user, ask whether to proceed with old rules or update story first

Collaborative Protocol

• File writes delegated — source code, test files, evidence docs written by sub-agents via Task. This orchestrator does not write files directly.
• Load before implementing — all context (story, TR-ID, ADR, manifest, engine prefs) loaded before coding. Incomplete context → code drifts from design.
• ADR is the law — follow ADR Implementation Guidelines. Conflict with "better" approach → flag in summary, don't silently deviate.
• Stay in scope — Out of Scope is a contract. Need out-of-scope file → stop and surface: "Implementing [criterion] requires [file], which is out of scope. Proceed or create separate story?"
• Test not optional for Logic/Integration — don't mark complete without test file
• Visual/Feel criteria deferred, not skipped — mark DEFERRED; manually verified in /ags-story-done
• Ask before structural decisions — ADR doesn't cover [case] → "My plan is [X]. Proceed?"

---

Recommended Next Steps

• Run /ags-code-review [file1] [file2] to review the implementation before closing the story
• Run /ags-story-done [story-path] to verify acceptance criteria and mark the story complete
• After all sprint stories are done: run /ags-team-qa sprint for the full QA cycle before advancing the project stage