diff --git a/README.md b/README.md index 50b3a98..b96db6f 100644 --- a/README.md +++ b/README.md @@ -183,6 +183,17 @@ template/epicspec/ → epicspec/ Then use `/epicspec-create-spec` in Cursor chat. +**GitHub Copilot** + +Copy these into your project root: + +``` +template/.github/prompts/epicspec-*.prompt.md → .github/prompts/ +template/epicspec/ → epicspec/ +``` + +Then use `/epicspec-create-spec` in Copilot Chat (VS Code, Visual Studio, or JetBrains). + ### npm install ```bash @@ -282,6 +293,7 @@ epicspec/ |---|---| | Claude Code | Available — `/epicspec:create-spec` | | Cursor | Available — `/epicspec-create-spec` | +| GitHub Copilot | Available — `/epicspec-create-spec` | | Windsurf | Planned | --- @@ -310,6 +322,7 @@ Files you'll most likely edit: |---|---| | `template/.claude/commands/epicspec/` | Claude Code commands | | `template/.cursor/commands/` | Cursor commands | +| `template/.github/prompts/` | GitHub Copilot prompt files | | `template/epicspec/` | Spec and story templates | | `README.md` | Docs | diff --git a/bin/epicspec.js b/bin/epicspec.js index a58b475..4f0a7ff 100644 --- a/bin/epicspec.js +++ b/bin/epicspec.js @@ -11,6 +11,7 @@ const TEMPLATE_DIR = join(__dirname, '..', 'template'); const AGENTS = [ { value: 'claude', label: 'Claude Code' }, { value: 'cursor', label: 'Cursor' }, + { value: 'copilot', label: 'GitHub Copilot' }, ]; // ── argument parsing ────────────────────────────────────────────────────────── @@ -113,6 +114,18 @@ async function init(targetPath, force) { } s.stop('.cursor/commands/ ✓'); } + + // GitHub Copilot + if (agents.includes('copilot')) { + s.start('Setting up GitHub Copilot...'); + const dest = join(targetPath, '.github', 'prompts'); + mkdirSync(dest, { recursive: true }); + const src = join(TEMPLATE_DIR, '.github', 'prompts'); + for (const file of readdirSync(src).filter(f => f.startsWith('epicspec'))) { + cpSync(join(src, file), join(dest, file)); + } + s.stop('.github/prompts/ ✓'); + } } catch (err) { s.stop('Failed.'); log.error(`Could not copy files: ${err.message}`); diff --git a/package-lock.json b/package-lock.json index c79f770..42af198 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "epicspec", - "version": "1.1.1", + "version": "1.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "epicspec", - "version": "1.1.1", + "version": "1.2.0", "license": "MIT", "dependencies": { "@clack/prompts": "^0.7.0" diff --git a/package.json b/package.json index 146faee..84d7fee 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@epicspec/epicspec", - "version": "1.1.1", + "version": "1.2.0", "description": "Spec-first development for AI-assisted engineering", "author": "Eduardo Brunaldi", "license": "MIT", diff --git a/template/.claude/commands/epicspec/create-spec.md b/template/.claude/commands/epicspec/create-spec.md index 0b15553..0c665f2 100644 --- a/template/.claude/commands/epicspec/create-spec.md +++ b/template/.claude/commands/epicspec/create-spec.md @@ -4,7 +4,7 @@ You are a product engineering expert. Your job is to lead a structured conversat ## Goal -Gather enough context — through conversation and codebase exploration — to produce a spec rich enough for `/create-stories` to generate detailed, actionable stories without losing context between phases. +Gather enough context — through conversation and codebase exploration — to produce a spec rich enough for `/epicspec:create-stories` to generate detailed, actionable stories without losing context between phases. The final spec will be saved at `epicspec/epics//spec.md`, using `epicspec/spec-template.md` as the base. @@ -121,7 +121,7 @@ Confirm to draft the spec, or adjust the approach. Once the approach is validated, create `epicspec/epics//` if it doesn't exist, then draft the spec using `epicspec/spec-template.md` as the structure. -Fill every section using what you gathered in Phases 1–3. The following guidance ensures each section has the depth that `/create-stories` needs downstream. +Fill every section using what you gathered in Phases 1–3. The following guidance ensures each section has the depth that `/epicspec:create-stories` needs downstream. ### Section-by-section guidance @@ -192,7 +192,7 @@ Once approved: Spec saved: epicspec/epics//spec.md Sections filled: N/N -Next step: run /create-stories to break this into implementable stories. +Next step: run /epicspec:create-stories to break this into implementable stories. ``` --- diff --git a/template/.cursor/commands/epicspec-archive.md b/template/.cursor/commands/epicspec-archive.md index 5744f13..c889d14 100644 --- a/template/.cursor/commands/epicspec-archive.md +++ b/template/.cursor/commands/epicspec-archive.md @@ -1,4 +1,4 @@ -# Command: /archive +# Command: /epicspec-archive You are a project engineer. Your job is to archive a completed epic — moving it out of active development so the project stays clean and focused. diff --git a/template/.cursor/commands/epicspec-create-spec.md b/template/.cursor/commands/epicspec-create-spec.md index 0fc7305..a636166 100644 --- a/template/.cursor/commands/epicspec-create-spec.md +++ b/template/.cursor/commands/epicspec-create-spec.md @@ -4,7 +4,7 @@ You are a product engineering expert. Your job is to lead a structured conversat ## Goal -Gather enough context — through conversation and codebase exploration — to produce a spec rich enough for `/create-stories` to generate detailed, actionable stories without losing context between phases. +Gather enough context — through conversation and codebase exploration — to produce a spec rich enough for `/epicspec-create-stories` to generate detailed, actionable stories without losing context between phases. The final spec will be saved at `epicspec/epics//spec.md`, using `epicspec/spec-template.md` as the base. @@ -121,7 +121,7 @@ Confirm to draft the spec, or adjust the approach. Once the approach is validated, create `epicspec/epics//` if it doesn't exist, then draft the spec using `epicspec/spec-template.md` as the structure. -Fill every section using what you gathered in Phases 1–3. The following guidance ensures each section has the depth that `/create-stories` needs downstream. +Fill every section using what you gathered in Phases 1–3. The following guidance ensures each section has the depth that `/epicspec-create-stories` needs downstream. ### Section-by-section guidance @@ -192,7 +192,7 @@ Once approved: Spec saved: epicspec/epics//spec.md Sections filled: N/N -Next step: run /create-stories to break this into implementable stories. +Next step: run /epicspec-create-stories to break this into implementable stories. ``` --- diff --git a/template/.cursor/commands/epicspec-implement-story.md b/template/.cursor/commands/epicspec-implement-story.md index 2b4a48e..d26af88 100644 --- a/template/.cursor/commands/epicspec-implement-story.md +++ b/template/.cursor/commands/epicspec-implement-story.md @@ -286,7 +286,7 @@ After producing the completion summary, check whether the full epic is done: ───────────────────────────────────── All N stories in this epic are complete. -Run /epicspec:archive to archive and move it out of active development. +Run /epicspec-archive to archive and move it out of active development. ───────────────────────────────────── ``` @@ -342,6 +342,6 @@ To resume: start from Task 3 after resolving . - **Never mark the story done if any acceptance criterion is unverified** — the Phase 4 sweep must pass before the completion summary - **Never silently skip unavailable verification** — if you can't run a verification, tell the user and ask how to proceed - **Always update story Status in the file** — set `In Progress` when implementation begins (Phase 1), set `Done` when the story is fully verified (Phase 5); never leave the file with a stale status -- **Always check for epic completion after story completion** — if all stories in the epic are Done, suggest /epicspec:archive +- **Always check for epic completion after story completion** — if all stories in the epic are Done, suggest /epicspec-archive - **Never implement without establishing architectural ground truth** — always run Phase 0 before touching any code; discovering the architecture after writing code is too late - **Architecture mismatches are blockers** — treat a task description that violates the discovered architecture the same as a missing file: stop and ask, never improvise a pattern diff --git a/template/.github/prompts/epicspec-archive.prompt.md b/template/.github/prompts/epicspec-archive.prompt.md new file mode 100644 index 0000000..23ad728 --- /dev/null +++ b/template/.github/prompts/epicspec-archive.prompt.md @@ -0,0 +1,109 @@ +--- +description: "Archive a completed epic, moving it out of active development" +agent: "agent" +--- + +# Command: /epicspec-archive + +You are a project engineer. Your job is to archive a completed epic — moving it out of active development so the project stays clean and focused. + +--- + +## Phase 1 — Detect active epics + +Scan `epicspec/epics/` for subdirectories, excluding `archive/`. Each subdirectory is a candidate epic. + +**If zero epics found:** + +``` +No active epics found in epicspec/epics/. Nothing to archive. +``` + +Stop. + +**If one epic found:** + +``` +Ready to archive: + +Confirm? (yes / no) +``` + +Wait for the user to confirm before proceeding. + +**If two or more epics found:** + +``` +Active epics: + +1. +2. +... + +Which epic should be archived? Reply with the number or name. +``` + +Wait for the user's answer before proceeding. + +--- + +## Phase 2 — Pre-archive summary + +Read the story files in `epicspec/epics//stories/`. For each file, check its `Status:` field. + +Present a summary: + +``` +Ready to archive: + +Stories: + ✓ — Done + ✓ — Done + ⚠ — In Progress + +Location: epicspec/epics// → epicspec/epics/archive// + +Confirm to proceed, or reply "no" to cancel. +``` + +If any story is not `Done`, include a warning before asking for confirmation: + +``` +⚠ Warning: stories are not marked Done. Archiving will move the epic as-is — no data is lost, but the stories will remain unfinished in the archive. +Continue anyway? (yes / no) +``` + +Do not proceed until the user confirms. + +--- + +## Phase 3 — Archive + +1. Create `epicspec/epics/archive/` if it doesn't exist +2. Move `epicspec/epics//` to `epicspec/epics/archive//` +3. Open every `.md` file in `epicspec/epics/archive//stories/` and update its `Status:` field to `Archived` + +--- + +## Phase 4 — Confirm + +``` +Archived: + +Moved to: epicspec/epics/archive// +Stories marked Archived: N + +To review: + epicspec/epics/archive//spec.md + epicspec/epics/archive//stories/ +``` + +--- + +## Rules + +- **Never archive without user confirmation** — always present the pre-archive summary and wait for an explicit yes +- **Never silently skip stories that aren't Done** — warn the user and require an explicit "yes" to continue with incomplete stories +- **Never delete files** — archiving is a move operation only; nothing is lost +- **Always update story statuses to Archived after moving** — the Status field must reflect the epic's archived state +- **Always create `archive/` if it doesn't exist** — do not fail if the directory is missing diff --git a/template/.github/prompts/epicspec-create-spec.prompt.md b/template/.github/prompts/epicspec-create-spec.prompt.md new file mode 100644 index 0000000..a3b137a --- /dev/null +++ b/template/.github/prompts/epicspec-create-spec.prompt.md @@ -0,0 +1,216 @@ +--- +description: "Create a feature spec through structured conversation before any code is written" +agent: "agent" +--- + +# Command: /epicspec-create-spec + +You are a product engineering expert. Your job is to lead a structured conversation to create a complete feature spec before any implementation begins. + +## Goal + +Gather enough context — through conversation and codebase exploration — to produce a spec rich enough for `/epicspec-create-stories` to generate detailed, actionable stories without losing context between phases. + +The final spec will be saved at `epicspec/epics//spec.md`, using `epicspec/spec-template.md` as the base. + +--- + +## Phase 1 — Initial understanding + +When the user provides a task description, ask as many questions as needed to fully understand: + +- **What** — the expected behavior in product and user terms +- **Why** — the real problem being solved and the desired outcome +- **Constraints** — what is explicitly out of scope + +Do not move to Phase 2 until you have clear answers to all three dimensions. If any answer raises new questions, follow up before proceeding. + +Before confirming, determine the epic number: +1. Scan `epicspec/epics/` and `epicspec/epics/archive/` for subdirectories +2. For each directory whose name starts with three digits followed by a hyphen, extract that number +3. If none exist, use `001` +4. Otherwise use the highest number found + 1, zero-padded to 3 digits +5. Combine with the kebab-case feature name to form the epic directory name: `NNN-feature-name` + +Before moving to Phase 2, confirm understanding in this format: + +``` +Understanding confirmed: + +Epic directory: epicspec/epics// +What: +Why: +Constraints: + +Moving to technical exploration. Let me know if anything needs adjusting. +``` + +Example opening: +> "Got it. Before exploring the code, I need to understand what you're trying to achieve. Let me ask a few things..." + +--- + +## Phase 2 — Technical exploration + +With a solid understanding of the feature, explore the codebase to discover: + +- Files and modules directly involved +- Architectural and code patterns already established +- Existing dependencies the feature will touch +- Non-obvious impact points that could be affected + +Be explicit about what you find: +> "Found X, which seems to be the central point. Also noticed Y uses Z, which could be affected." + +If something is unclear after exploring, ask the user to clarify rather than making assumptions. Run as many rounds as needed until you have full technical confidence. + +When exploration is complete, present findings before proceeding: + +``` +Exploration findings: + +Files involved: +- — +- — + +Patterns observed: +- + +Impact points: +- + +Unknowns: +- + +Ready to propose an approach. Confirm or ask questions. +``` + +--- + +## Phase 3 — Approach validation + +Before writing the spec, present your proposed implementation approach clearly: + +- The technical approach and why it fits the codebase +- The main trade-offs of that approach +- Alternatives worth considering, with a recommendation when relevant +- Any remaining ambiguous decisions that need user input + +Wait for confirmation or adjustment before proceeding. If the user's response raises new questions, continue the discussion until the approach is fully aligned. + +Present the approach in this format: + +``` +Proposed approach: + +Approach: <2–4 sentences on the technical approach and why it fits the codebase> + +Trade-offs: +- Pro: +- Con: + +Alternatives considered: +- — +[or "No strong alternatives identified."] + +Open decisions (needs your input): +- — +[or "None — all decisions are clear."] + +Confirm to draft the spec, or adjust the approach. +``` + +--- + +## Phase 4 — Spec generation + +Once the approach is validated, create `epicspec/epics//` if it doesn't exist, then draft the spec using `epicspec/spec-template.md` as the structure. + +Fill every section using what you gathered in Phases 1–3. The following guidance ensures each section has the depth that `/epicspec-create-stories` needs downstream. + +### Section-by-section guidance + +**Section 1 — Context and Goal:** +Translate Phase 1 answers into a clear problem statement. The success metric must be measurable — if Phase 1 didn't surface one, propose one based on what you learned. + +**Section 2 — Expected Behavior:** +Write the happy path as numbered steps from the user's or system's perspective. Derive alternative scenarios from Phase 1 constraints and Phase 2 findings. "What does NOT change" comes from your codebase exploration — list existing behaviors that must survive this feature. + +**Section 3 — Data Model:** +Based on Phase 2 exploration, formalize any new entities, fields, or state changes into the table. Reference existing models you found in the codebase. If the feature has no data model impact, write "N/A — [reason]." + +**Section 4 — Interface Contract:** +Translate Phase 1's "what the user does and sees" into structured input/output/error tables. Source and Destination must be specific (not "the frontend" — say which component, endpoint, or event). If purely internal, write "N/A — [reason]." + +**Section 5 — Technical Context:** +This is where Phase 2 pays off. List real file paths you found. Reference real patterns you observed — not generic best practices. Carry forward Phase 3's technical decisions and trade-offs. "Things to avoid" should include anti-patterns you actually spotted in the codebase. + +**Section 6 — Dependencies and Impact:** +Map blockers from Phase 2 findings (migrations, services, other features). Trace ripple effects by following what depends on the files you identified. Out of scope must include anything discussed in Phase 1 that was explicitly excluded. + +**Section 7 — Edge Cases and Failure Modes:** +Ground every edge case in what you observed — not generic assumptions. For every input from Section 4, ask: empty? malformed? duplicated? concurrent? For every dependency from Section 6, ask: unavailable? slow? erroring? Assign severity. + +**Section 8 — Acceptance Criteria:** +Every criterion must be independently verifiable by a test or a human. Include at least one criterion per main scenario from Section 2. Add performance and observability criteria if the feature has non-trivial load or error surface. Never write "should work correctly." + +**Section 9 — Testing Strategy:** +Based on the feature's complexity, define what needs unit tests (isolated logic), integration tests (flows across modules), and manual testing (visual/UX). Reference specific functions or flows from Sections 2 and 5. + +**Section 10 — References:** +Link any mockups, designs, or documentation referenced during Phases 1–3. If design mockups, ADRs, or related specs exist, link them here. + +--- + +## Phase 5 — Review + +Do not save the file yet. Present the full draft to the user in conversation: + +``` +Spec draft for: + + + +--- + +Please review. Specifically: +- Is the scope correct? Anything missing or over-scoped? +- Are the technical decisions in Section 5 sound? +- Are the edge cases in Section 7 complete? +- Any acceptance criteria to add or adjust? + +Reply with changes or "approved" to save. +``` + +Iterate until the user approves. A spec saved without review contaminates everything downstream — stories, tasks, and implementation will all inherit its mistakes. + +--- + +## Phase 6 — Save + +Once approved: + +1. Write the final spec to `epicspec/epics//spec.md` +2. Print confirmation: + +``` +Spec saved: epicspec/epics//spec.md + +Sections filled: N/N +Next step: run /epicspec-create-stories to break this into implementable stories. +``` + +--- + +## Rules + +- **Never skip codebase exploration** — specs without real technical context generate shallow stories +- **Never assume** — if something is unclear, ask the user instead of guessing +- **Never save without user approval** — always present the draft and wait for explicit confirmation +- **Be upfront about gaps** — if you didn't find something, say so: "Didn't find X, it may not exist yet" +- **Edge cases must be concrete** — derived from what you observed in the code, not invented +- **Acceptance criteria must be verifiable** — never write "should work correctly" +- **Never leave placeholder text** — every section gets filled or gets "N/A — [reason]" +- **Always use `NNN-kebab-case` for the epic directory name** — three-digit zero-padded number prefix followed by a hyphen and the kebab-case name (e.g., `001-notification-preferences`). Determine the number by scanning existing epics (including `epicspec/epics/archive/`) and incrementing the highest found. +- **Always confirm the feature name with the user before creating the directory** — the name becomes the path and cannot be easily changed later +- **Never reference the spec as done until the user says "approved"** — iterate on the draft as many times as needed diff --git a/template/.github/prompts/epicspec-create-stories.prompt.md b/template/.github/prompts/epicspec-create-stories.prompt.md new file mode 100644 index 0000000..4e4e6be --- /dev/null +++ b/template/.github/prompts/epicspec-create-stories.prompt.md @@ -0,0 +1,200 @@ +--- +description: "Break an approved spec into dependency-ordered, implementable stories" +agent: "agent" +--- + +# Command: /epicspec-create-stories + +You are a product engineering expert. Your job is to read a feature spec and break it down into well-defined stories, each with detailed, self-contained tasks that an agent can implement without needing additional context. + +## Goal + +Read `epicspec/epics//spec.md`, decompose it into the right number of stories, and generate one `.md` file per story inside `epicspec/epics//stories/`, using `epicspec/story-template.md` as the base for each file. + +Every task in every story must be detailed enough that an agent reading only that story file can implement it correctly — with no ambiguity about what to do, where to do it, and how to verify it's done. + +--- + +## Phase 1 — Read and understand the spec + +Start by reading the full spec at the path provided by the user (e.g., `epicspec/epics/user-auth/spec.md`). + +Before proposing anything, make sure you understand: +- The full scope and goal of the feature (Sections 1 and 2) +- The data model changes, if any (Section 3) +- The interface contract — inputs, outputs, errors (Section 4) +- The files, patterns, and technical decisions involved (Section 5) +- Dependencies, ripple effects, and what's out of scope (Section 6) +- All edge cases and failure modes (Section 7) +- Every acceptance criterion (Section 8) +- The testing strategy — what needs unit, integration, or manual testing (Section 9) + +If the spec is ambiguous or incomplete in any section, ask the user to clarify before proceeding. Do not generate stories based on incomplete understanding. + +--- + +## Phase 1.5 — Codebase architecture discovery + +Before proposing a story breakdown, establish the project's architectural ground truth. This ensures the tasks you write in Phase 3 reference real files and real patterns — not generic descriptions that will break the architecture during implementation. + +### Step 1 — Look for explicit rules files + +Check for these files at the project root (in order): +- `CLAUDE.md` +- `.cursorrules` +- `.cursor/rules/*.md` +- `.github/copilot-instructions.md` + +If found, read them. Then **still perform Step 2** — rules files can be outdated. If the rules file describes patterns that contradict what you find in the codebase, do not update the rules file. Instead, flag it: + +``` +⚠ Rules file may be outdated: + + says: +Codebase shows: + +Which should I follow? +``` + +Wait for the user to decide before continuing. + +### Step 2 — Explore the codebase + +Regardless of whether a rules file was found: + +- Map the project's layer structure from directory names and file names (e.g., `/Controllers/`, `/Services/`, `/Repositories/`, `/Domain/`) +- Find 1–2 existing features similar to what the spec describes +- Trace each from the entry point (route/controller) all the way through to data access — record exact file paths, class names, and function signatures +- If no similar implementation exists yet (greenfield project), note it in the proposal block under `Reference implementation used: none — greenfield project` and proceed. + +### Step 3 — Use findings when writing tasks + +When writing `Where` and `How` sections for tasks in Phase 3: + +- `Where` must reference **actual existing file paths** — not hypothetical or generic ones +- `How` must say "follow the pattern in ``" and reference real class/method names from the codebase +- If the task creates a new file or class, name it following the naming convention observed in the codebase +- If the task adds a layer (e.g., a new service), the `How` must specify which existing file to model it after + +### Step 4 — Surface architecture findings in the Phase 2 proposal + +Add this block to the Phase 2 proposal output so the user can catch any wrong assumptions before approving: + +``` +Architecture discovered: +Reference implementation used: +Rules source: <"CLAUDE.md" | "explored codebase" | "none found — patterns inferred from structure"> +``` + +--- + +## Phase 2 — Propose the story breakdown + +Before creating any files, present the proposed story breakdown to the user: + +``` +Proposed stories for : + +1. 01- — [one sentence: what slice of the spec this covers] +2. 02- — [one sentence: what slice of the spec this covers] +3. 03- — [one sentence: what slice of the spec this covers] + +Dependency order: 01-story-1 → 02-story-2 → 03-story-3 (story 2 depends on 1, etc.) + +Shared files: [list any files touched by more than one story] +``` + +**Rules for a good breakdown:** +- Each story must be independently testable — you can verify it works on its own, even if it's not useful to a user until later stories are complete +- Stories must be ordered by dependency — data model before logic, logic before interface, infrastructure before consumers +- No story should duplicate work covered by another story +- A story should not be so large it can't be completed in a single focused session (guideline: 2–6 tasks per story) +- A story should not be so small it's just a single trivial task +- A single story is valid for small, focused features — do not force decomposition where none is needed +- For typical features, 2–5 stories is a healthy range; for larger or more complex features, 6–8 stories is acceptable and expected +- If you need more than 10 stories, the spec may be too broad — flag this to the user and suggest splitting it into two separate epics +- If multiple stories touch the same file, surface this in the proposal so the user can decide whether to restructure + +Wait for the user to confirm or adjust the breakdown before generating any files. + +--- + +## Phase 3 — Generate story files + +Once the breakdown is approved, generate each story file in order: + +Before generating files, determine the NN prefix for each story: +1. Scan `epicspec/epics//stories/` for existing files whose name starts with two digits followed by a hyphen +2. Extract those numbers +3. If none exist, assign `01` to the first story in the approved breakdown +4. Otherwise, continue from the highest number found + 1, zero-padded to 2 digits +5. Assign numbers sequentially in the dependency order approved in Phase 2 + +1. Create `epicspec/epics//stories/` if it doesn't exist +2. For each story: + a. Copy `epicspec/story-template.md` to `epicspec/epics//stories/.md` + - Use kebab-case for the file name (e.g., `01-create-user-schema.md`, not `Create User Schema.md`) + b. Fill in the template completely — no section left with placeholder text + c. Set the story's `Status:` field to `Ready` — a generated story is ready to be implemented immediately + d. Generate all tasks for that story before moving to the next + +After generating all files, print a summary: +``` +Generated N stories for : + +- epicspec/epics//stories/.md (N tasks) +- epicspec/epics//stories/.md (N tasks) +- epicspec/epics//stories/.md (N tasks) + +Suggested implementation order: 01-story-1 → 02-story-2 → 03-story-3 + +Review the generated stories. Reply with adjustments or "looks good" to finalize. +``` + +--- + +## How to write tasks + +This is the most critical part. Each task must be self-contained. An agent reading only the story file and the task description must be able to implement it without asking questions. + +**A task must always include:** + +- **What** — one sentence on what needs to be done +- **Why** — one sentence on why it's needed in this story's context +- **Where** — specific file paths with a description of what changes in each file +- **How** — step-by-step implementation detail, including: + - Which functions, classes, or modules to create or modify + - Which existing patterns to follow, with real references from the codebase + - Any non-obvious logic, edge case, or constraint to handle +- **Verification** — concrete way to confirm the task is done (test command, expected output, UI state, etc.) + +**A task must never be:** +- Just a title or one-liner (e.g., "Add migration for users table") +- Vague about location (e.g., "update the service layer") +- Missing verification (the agent must know when it's done) +- Dependent on context only available in another task or story + +**Testing as a task:** +- If the spec's Testing Strategy (Section 9) calls for unit or integration tests relevant to a story, include a dedicated task for writing those tests +- The test task should reference the exact functions or flows being tested and the edge cases from Section 7 that apply +- Do not bundle "write tests" into implementation tasks — keep them separate so they can be verified independently + +**Cross-story awareness:** +- If a task produces an artifact (a function, a type, a migration) that another story depends on, say so explicitly in the task's **How** section: "Note: this [artifact] is consumed by story ``, task N" +- If a task modifies a file that another story also touches, flag it: "Note: story `` also modifies this file — coordinate to avoid conflicts" +- Surface all shared files in the Phase 2 proposal so the user sees them before approving + +--- + +## Rules + +- **Never generate files before the breakdown is approved** — getting the story structure wrong wastes everything that follows +- **Never leave a template section with placeholder text** — if a section doesn't apply to a story, write "N/A — [one sentence explaining why]" rather than leaving the placeholder +- **Never write vague tasks** — if you find yourself writing a task without a **Where** or **How**, stop and gather more information from the spec or ask the user +- **Never duplicate work across stories** — each piece of logic, each file change, belongs to exactly one story +- **Always use `NN-kebab-case` for story file names** (e.g., `01-schema.md`) — the NN prefix ensures sortable, ordered file names; spaces and uppercase cause issues in scripts and CI +- **Always determine the NN prefix by scanning existing stories** — never hardcode or guess numbers; follow the same scan-and-increment logic used for epic directories +- **Always respect dependency order** — generate and list stories in the order they should be implemented +- **Always include testing tasks** — a story without verification is not done +- **Never write tasks without codebase exploration** — generic `Where`/`How` sections that don't reference real files produce architecture-breaking implementations +- **Always reference a real existing implementation in task `How` sections** — "follow the pattern in `X`" is always more reliable than describing the pattern abstractly diff --git a/template/.github/prompts/epicspec-implement-story.prompt.md b/template/.github/prompts/epicspec-implement-story.prompt.md new file mode 100644 index 0000000..45f167f --- /dev/null +++ b/template/.github/prompts/epicspec-implement-story.prompt.md @@ -0,0 +1,352 @@ +--- +description: "Implement a single story task-by-task with verification at every step" +agent: "agent" +--- + +# Command: /epicspec-implement-story + +You are a senior software engineer. Your job is to implement a story completely, correctly, and verifiably — one task at a time — without losing context or skipping steps. + +--- + +## Phase 0 — Architecture discovery + +Before reading the story, establish the project's architectural ground truth. This step ensures you implement in the correct layers — even if the project has no CLAUDE.md or rules file. + +### Step 1 — Look for explicit rules files + +Check for these files at the project root (in order): +- `CLAUDE.md` +- `.cursorrules` +- `.cursor/rules/*.md` +- `.github/copilot-instructions.md` + +If found, read them. Then **still perform Step 2** — rules files can be outdated. If the rules file describes patterns that contradict what you find in the codebase, do not update the rules file. Instead, flag it: + +``` +⚠ Rules file may be outdated: + + says: +Codebase shows: + +Which should I follow? +``` + +Wait for the user to decide before continuing. + +### Step 2 — Explore the codebase + +Regardless of whether a rules file was found: + +- Identify the project's language and framework (e.g., C# + ASP.NET, TypeScript + NestJS, Go + Chi) +- Map the layer structure from directory names and file names (e.g., `/Controllers/`, `/Services/`, `/Repositories/`, `/Domain/`) +- Find 1–2 existing implementations similar to what this story will build. If the story adds an endpoint, find an existing endpoint and trace it from entry point to data access — note real file paths, class names, and function signatures +- If no similar implementation exists yet (greenfield project), note it in the Architecture Context block under `Reference implementation: none — greenfield project` and proceed. + +### Step 3 — Produce an Architecture Context block + +Document what you found. This block is your internal reference throughout implementation: + +``` +Architecture: + +Layers: +- : → +- : → + +Conventions: +- + +Reference implementation: +Rules source: <"CLAUDE.md" | "explored codebase" | "none found — patterns inferred"> +``` + +### Step 4 — Validate story tasks against discovered architecture + +Before proceeding to Phase 1, scan through the story's task `Where` and `How` sections. + +If any task description would result in implementing in the wrong layer — for example, putting business logic or database calls in a controller when the project uses a service layer — flag it as a blocker: + +``` +⚠ Architecture mismatch on Task N: + +Task says: "" +Project pattern: +Reference: + +Proceeding as written would break the project's architecture. +Suggested correction: + +Confirm which approach to follow before I start. +``` + +Wait for the user to decide before proceeding to Phase 1. + +If no mismatches are found, proceed silently to Phase 1. + +--- + +## Phase 1 — Full story comprehension + +Read the entire story file provided by the user before doing anything else. + +Build a mental model of: +- **What this story is about** — the specific slice of the feature it covers +- **Where it starts** — the Current State section describes the exact starting point +- **Where it ends** — the Solution and Acceptance Criteria define the finish line +- **What could go wrong** — the Warnings section contains things that must actively influence how you work, not just things to be aware of +- **What the tasks are** — read all tasks in full, not just their titles, so you understand how they connect and what each one produces for the next +- **What depends on what** — check the Dependencies section; if this story depends on another that isn't done, stop and tell the user before proceeding +- **What tests are required** — read the Testing section so you know what verification is expected at the end + +After reading, confirm your understanding to the user in this format: + +``` +Ready to implement: + +Summary: +- +- +- + +Warnings — how they affect implementation: +- → +[or "No warnings flagged."] + +I'll implement one task at a time and verify each before moving on. +Confirm to start, or ask questions first. +``` + +Do not proceed until the user confirms. + +Once the user confirms, update the `Status:` field in the story file from its current value to `In Progress` before writing any code. This ensures the file accurately reflects that implementation has started, even if the session is interrupted. + +--- + +## Phase 2 — Task-by-task implementation + +Work through each task in order. For every task, follow Steps 1 through 4 exactly. + +### Step 1 — Re-read and announce + +Re-read the full task description from the story file (do not work from memory or your earlier summary). Then state: + +``` +--- Task N of M: --- + +What I'm about to do: + + +Files I'll touch: +- — + +Warnings that apply to this task: +- +[or "None."] +``` + +**Before writing any code**, verify that the codebase matches what the task expects. Check that files exist, functions have the expected signatures, and patterns match what the story describes. + +If anything contradicts the task's **Where** or **How** — a file doesn't exist, a function has a different signature, a pattern differs from what the story described — **stop immediately**. Do not improvise. Report the discrepancy: + +``` +⚠ Blocker on Task N: + +Expected: +Found: + +Options: +1. +2. + +Which should I follow? +``` + +Wait for the user to resolve it before continuing. + +### Step 2 — Implement + +Make the changes described in the task. Follow the **How** section precisely. + +- Do not add scope beyond what the task describes +- Do not refactor adjacent code, even if it's tempting +- If you notice something unrelated that could be improved, add it to your running notes (see below) — do not implement it now + +### Step 3 — Verify + +Run the verification described in the task's **Verification** section. This is not optional. + +- If the verification is a test command, run it and show the output +- If it's a behavioral check, describe exactly what you observed and why it satisfies the criterion +- If the verification requires infrastructure that isn't available (database, external service, running server), tell the user what's needed and ask how to proceed — do not silently skip it + +**If verification fails:** +1. Diagnose and fix the issue +2. Re-run the current task's verification +3. Re-run verification for any previously completed task that touches the same files — a fix can introduce regressions +4. Only proceed once all verifications pass + +### Step 4 — Confirm and continue + +Report the result: + +``` +✓ Task N complete: +Verification: + +Progress: N/M tasks done +Moving to Task N+1. +``` + +Then proceed to the next task. + +--- + +## Phase 3 — Testing + +After all tasks are complete, implement the tests described in the story's **Testing** section. + +Use the same step structure as Phase 2 for each test category: + +### For each test group (unit, integration, etc.): + +**Announce:** +``` +--- Tests: --- + +What I'm writing: +- + +File: +``` + +**Implement** the tests. + +**Run them** and show the output. + +**Report:** +``` +✓ tests passing: N tests, N assertions +``` + +If a test category from the story's Testing section doesn't apply, explain why in one sentence — do not silently skip it. + +If any test fails, fix the underlying code (not the test, unless the test itself is wrong), then re-verify affected tasks before continuing. + +--- + +## Phase 4 — Acceptance criteria sweep + +This is a dedicated verification pass, separate from the summary. Go through each acceptance criterion from the story and verify it explicitly against the current state of the codebase. + +``` +Acceptance criteria check: + +✓ [criterion] — verified: +✓ [criterion] — verified: +✗ [criterion] — FAILED: +``` + +If any criterion fails, fix it before proceeding. Do not produce the completion summary with unverified or failing criteria. + +--- + +## Phase 5 — Story completion + +Once all tasks, tests, and acceptance criteria are verified, produce a final summary: + +``` +Story complete: + +Tasks: +✓ Task 1: — +✓ Task 2: — +✓ Task N: — + +Tests: +✓ Unit: +✓ Integration: +- Manual: + +Acceptance criteria: all passing (see sweep above) + +Files changed: +- — +- — + +Notes for next story: +- +- +``` + +Before checking epic completion, update the `Status:` field in the story file to `Done`. This must happen before reading other stories' statuses — the current story counts toward the epic-complete check. + +After producing the completion summary, check whether the full epic is done: + +1. Count all `.md` files in `epicspec/epics//stories/` +2. Read the `Status:` field in each file +3. If every story is `Done`, append to the output: + +``` +───────────────────────────────────── +All N stories in this epic are complete. + +Run /epicspec-archive to archive and move it out of active development. +───────────────────────────────────── +``` + +If any story is not yet `Done`, say nothing — only surface this nudge when the entire epic is complete. + +--- + +## Running notes + +Throughout implementation, maintain a running list of observations that don't belong to the current task but matter for later: + +- Out-of-scope improvements you noticed +- Patterns that differ from what the spec assumed +- Anything relevant to other stories in the epic + +Surface these in the "Notes for next story" section of the completion summary. Do not act on them during implementation. + +--- + +## Handling failure mid-story + +If a task cannot be completed and the user decides to stop: + +``` +Story paused: + +Completed: +✓ Task 1: +✓ Task 2: + +Blocked at: +✗ Task 3: — + +State of the codebase: +- +- + +To resume: start from Task 3 after resolving . +``` + +--- + +## Rules + +- **Never skip Warnings** — read them, understand how they affect your work, and reference them when they apply to a task +- **Never implement more than one task at a time** — complete and verify each task before starting the next +- **Never work from memory on long stories** — re-read the task description before implementing it +- **Never assume when blocked** — if the codebase doesn't match what the story describes, stop and ask +- **Never skip verification** — a task without a passing verification is not done +- **Never skip regression checks after a fix** — re-verify previously completed tasks that share affected files +- **Never add out-of-scope changes** — note them, do not implement them +- **Never skip the Testing phase** — tests are part of the story, not optional extras +- **Never mark the story done if any acceptance criterion is unverified** — the Phase 4 sweep must pass before the completion summary +- **Never silently skip unavailable verification** — if you can't run a verification, tell the user and ask how to proceed +- **Always update story Status in the file** — set `In Progress` when implementation begins (Phase 1), set `Done` when the story is fully verified (Phase 5); never leave the file with a stale status +- **Always check for epic completion after story completion** — if all stories in the epic are Done, suggest /epicspec-archive +- **Never implement without establishing architectural ground truth** — always run Phase 0 before touching any code; discovering the architecture after writing code is too late +- **Architecture mismatches are blockers** — treat a task description that violates the discovered architecture the same as a missing file: stop and ask, never improvise a pattern