# Dev Story > Lee una historia y la implementa: carga el contexto completo (historia, GDD, ADR, manifest), enruta al agente programador correcto e implementa código y test. Fuente: https://skillsagentes.com/skills/donchitos/claude-code-game-studios/dev-story Markdown: https://skillsagentes.com/skills/donchitos/claude-code-game-studios/dev-story.md Repositorio: https://github.com/Donchitos/Claude-Code-Game-Studios Autor: Donchitos Licencia: MIT Actualizado: hace 3 meses Coste de contexto: 88 tok instalada, 4.3k tok al activarse, 4.3k tok con todos los archivos del bundle Bundle: 1 archivo, 17 KB Permisos que pide: read, glob, grep, write, bash, task, askuserquestion ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add Donchitos/Claude-Code-Game-Studios --skill dev-story --agent claude-code # Cursor npx -y skills add Donchitos/Claude-Code-Game-Studios --skill dev-story --agent cursor # Codex npx -y skills add Donchitos/Claude-Code-Game-Studios --skill dev-story --agent codex # Gemini CLI npx -y skills add Donchitos/Claude-Code-Game-Studios --skill dev-story --agent gemini # Windsurf npx -y skills add Donchitos/Claude-Code-Game-Studios --skill dev-story --agent windsurf # Cline npx -y skills add Donchitos/Claude-Code-Game-Studios --skill dev-story --agent cline ``` ## Qué hace - Lee un archivo de historia completo y reúne story, TR-registry, ADR y control-manifest antes de implementar - Enruta la tarea al agente programador adecuado según capa, tipo y motor del juego - Implementa el código y escribe el archivo de test correspondiente en src/ y tests/ - Valida dependencias de la historia y el estado del control-manifest antes de codificar - Actualiza el estado de la sesión y el sprint-status al finalizar ## Cuándo usarla - Después de ejecutar /story-readiness y antes de /code-review y /story-done - Cuando hay que implementar una historia de un sprint de desarrollo de videojuegos ## Cuándo no - Cuando el TR registry o el ADR gobernante no existen - Cuando el ADR está en estado Proposed (debe ejecutarse /architecture-decision primero) ## Qué la activa - "/dev-story production/epics/epic-01/story-03.md" - "Implementa la historia activa de la sesión" - "Continúa con la historia en curso" ## Antes de instalar - Requiere tr-registry.yaml, el ADR gobernante y, opcionalmente, control-manifest.md y technical-preferences.md ya creados en el proyecto. - runs shell commands - writes to your files ## Archivos - SKILL.md — 17 KB ## SKILL.md Reproducido tal cual desde Donchitos/Claude-Code-Game-Studios bajo MIT. Esta sección es el documento original y está en inglés. # Dev Story This skill bridges planning and code. It reads a story file in full, assembles all the context a programmer needs, routes to the correct specialist agent, and drives implementation to completion — including writing the test. **The loop for every story:** ``` /qa-plan sprint ← define test requirements before sprint begins /story-readiness [path] ← validate before starting /dev-story [path] ← implement it (this skill) /code-review [files] ← review it /story-done [path] ← verify and close it ``` **After all sprint stories are done:** run `/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 `src/` and `tests/` directories. --- ## Phase 1: Find the Story **If a path is provided**: read that file directly. **If no argument**: check `production/session-state/active.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 `production/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 | `docs/architecture/tr-registry.yaml` | **STOP** — "TR registry not found at `docs/architecture/tr-registry.yaml`. Run `/architecture-review` to bootstrap the registry from your GDDs and ADRs." | | Governing ADR | path from story's ADR field | **STOP** — "ADR file [path] not found. Run `/architecture-decision` to create it, or correct the filename in the story's ADR field." | | Control manifest | `docs/architecture/control-manifest.md` | **WARN and continue** — "Control manifest not found — layer rules cannot be checked. Run `/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 `docs/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 `docs/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 `docs/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]: edit the story file's `Manifest Version:` field to the current manifest date AND add a `Manifest-Note: Proceeded with old manifest rules on [date] — non-compliance risk accepted.` line to the story header. Read the manifest for new rules anyway. Note the decision in the Phase 6 summary under "Deviations". `/story-done` will include the Manifest-Note in its deviations section without re-checking staleness. If [C]: stop. Do not spawn any agent. Let the user review and re-run `/dev-story`. ### Dependency validation After extracting the **Dependencies** list from the story file, validate each: 1. Glob `production/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 `.claude/docs/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 ### Mark Story In Progress Silently update two things before spawning any agent: 1. **`production/sprint-status.yaml`** (if it exists): find the entry matching this story's file path and set `status: in_progress`. Update the top-level `updated` field to today's date. If the file does not exist, skip silently. 2. **The story file itself**: edit the `Last Updated:` field in the story header to today's date (format: `YYYY-MM-DD`). If the field does not exist in the story header, add it after the `Status:` line. This enables sprint-status staleness detection for this story. --- ## 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 `.claude/docs/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 | |--------|----------------------------| | Godot 4 | `godot-specialist`, `godot-gdscript-specialist`, `godot-shader-specialist` | | Unity | `unity-specialist`, `unity-ui-specialist`, `unity-shader-specialist` | | Unreal Engine | `unreal-specialist`, `ue-gas-specialist`, `ue-blueprint-specialist`, `ue-umg-specialist`, `ue-replication-specialist` | **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: Brief the agent with file paths and targeted reading instructions — do not serialize document content into the Task prompt. The agent reads what it needs directly: 1. **Story file**: `[story-path]` — read in full 2. **GDD requirement**: look up TR-ID `[TR-XXX-NNN]` in `docs/architecture/tr-registry.yaml` — use the `requirement` field as source of truth 3. **ADR**: `docs/architecture/[adr-file].md` — read the **Decision** and **Implementation Guidelines** sections only 4. **Control manifest**: `docs/architecture/control-manifest.md` — read rules for the **[layer]** layer only 5. **Engine preferences**: `.claude/docs/technical-preferences.md` — read naming conventions and performance budgets 6. **Test file path**: `[path from story's Test Evidence section]` — this file must be created as part of implementation 7. **Test requirement** (Logic and Integration stories only): The test file MUST be created at `[path from the story's Test Evidence section]`. Write the test alongside the implementation — do not defer it. The story cannot be closed via `/story-done` without this file present. Each acceptance criterion must have at least one test function covering it. Test file naming: `[system]_[feature]_test.[ext]`. Function naming: `test_[scenario]_[expected_outcome]`. No random seeds, no time-dependent assertions, no external I/O. 8. **Explicit instruction**: implement this story following the ADR guidelines, respect the manifest rules, stay within the story's Out of Scope boundaries. Write clean, doc-commented public APIs. The agent should: - Create or modify files in `src/` 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 ### 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 `/story-done` via manual confirmation. --- ## Phase 5: Test Evidence Requirements The test requirement was included in the Phase 4 programmer agent brief (item 7). This phase summarizes what evidence each story type requires — used when collecting the Phase 6 summary. | Story Type | Required Evidence | Notes | |---|---|---| | **Logic** | Automated unit test at path from story's Test Evidence section | BLOCKING — included in Phase 4 agent brief | | **Integration** | Integration test OR documented playtest record | BLOCKING — included in Phase 4 agent brief | | **Visual/Feel** | Evidence doc at `production/qa/evidence/[slug]-evidence.md` | ADVISORY — note in Phase 6 summary | | **UI** | Manual walkthrough doc or interaction test | ADVISORY — note in Phase 6 summary | | **Config/Data** | None — smoke check serves as evidence | N/A | For Visual/Feel and UI stories, include in the Phase 6 summary: "Manual evidence required at `production/qa/evidence/[slug]-evidence.md` before this story can be fully closed." --- ## 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**: - `src/[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] **Before running `/story-done`:** run your test suite locally and confirm the tests you wrote pass. `/story-done` will re-run them automatically, but a failing test discovered there means returning to implementation context. Ready for: `/code-review [file1] [file2]` then `/story-done [story-path]` ``` --- ## Phase 7: Update Session State Silently append to `production/session-state/active.md`: ``` ## Session Extract — /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: /code-review [files] then /story-done [story-path] ``` Create `active.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 `/architecture-decision` first - Scope too large → split into two stories via `/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 are delegated** — all source code, test files, and evidence docs are written by sub-agents spawned via Task. Each sub-agent enforces the "May I write to [path]?" protocol individually. This orchestrator does not write files directly. - **Load before implementing** — do not start coding until all context is loaded (story, TR-ID, ADR, manifest, engine prefs). Incomplete context produces code that drifts from design. - **The ADR is the law** — implementation must follow the ADR's Implementation Guidelines. If the guidelines conflict with what seems "better," flag it in the summary rather than silently deviating. - **Stay in scope** — the Out of Scope section is a contract. If implementing the story requires touching an out-of-scope file, stop and surface it: "Implementing [criterion] requires modifying [file], which is out of scope. Shall I proceed or create a separate story?" - **Test is not optional for Logic/Integration** — do not mark implementation complete without the test file existing - **Visual/Feel criteria are deferred, not skipped** — mark them as DEFERRED in the summary; they will be manually verified in `/story-done` - **Ask before large structural decisions** — if the story requires an architectural pattern not covered by the ADR, surface it before implementing: "The ADR doesn't specify how to handle [case]. My plan is [X]. Proceed?" --- ## Recommended Next Steps - Run `/code-review [file1] [file2]` to review the implementation before closing the story - Run `/story-done [story-path]` to verify acceptance criteria and mark the story complete - After all sprint stories are done: run `/team-qa sprint` for the full QA cycle before advancing the project stage ## Dónde encaja - Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código. - Creador: [Donchitos](https://skillsagentes.com/creators/donchitos.md) — 73 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Team Qa](https://skillsagentes.com/skills/donchitos/claude-code-game-studios/team-qa.md): Orquesta al equipo de QA (qa-lead y qa-tester) para producir un paquete completo de QA: plan de pruebas, smoke check, casos de prueba, ejecución manual y reporte de sign-off. - [Consistency Check](https://skillsagentes.com/skills/donchitos/claude-code-game-studios/consistency-check.md): Compara todos los GDDs contra el registro de entidades para detectar inconsistencias entre documentos: mismo stat, ítem o fórmula con valores distintos, usando un enfoque grep-first. - [Create Architecture](https://skillsagentes.com/skills/donchitos/claude-code-game-studios/create-architecture.md): Redacción guiada, sección por sección, del documento de arquitectura maestro del juego, consciente de la versión del motor y de sus posibles brechas de conocimiento. - [Day One Patch](https://skillsagentes.com/skills/donchitos/claude-code-game-studios/day-one-patch.md): Prepara un patch day-one para el lanzamiento de un juego: define alcance, prioriza, implementa y valida con un QA gate ligero, como un mini-sprint con plan de rollback. - [Hotfix](https://skillsagentes.com/skills/donchitos/claude-code-game-studios/hotfix.md): Flujo de arreglo urgente que se salta el proceso normal de sprint pero deja rastro de auditoría completo: crea rama hotfix, registra aprobaciones y asegura el backport correcto. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)