@garygentry/feature-forge 0.1.0

package/adapters/copilot/skills/forge-2-tech/forge-2-tech.md

@@ -0,0 +1,197 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-2-tech/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-2-tech
+description: Create a technical specification from an existing PRD in the forge pipeline. Use when user runs /feature-forge:forge-2-tech or asks to create a tech spec for a forge feature after PRD completion. Do NOT trigger for general technical design discussions, architecture reviews, or tech specs outside the forge pipeline.
+---
+
+# forge-2-tech — Technical Specification Driver
+
+Create a thorough technical specification by interviewing the user about technology decisions, grounded in PRD requirements.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+## Step 1: Validate Prerequisites
+
+**Resolve the feature directory first** via the **Feature Directory Resolution** block in `references/shared-conventions.md`, setting `{resolvedFeatureDir}`.
+
+**Prerequisite check:** Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode and `forge-1-prd` is not `complete`, STOP and tell the user: "The PRD for '{feature}' isn't complete yet. Run `/feature-forge:forge-1-prd {feature}` first."
+
+Read `{resolvedFeatureDir}/PRD.md` into context. This is your foundation — every technology decision must trace back to a PRD requirement.
+
+After reading the PRD, invoke the **Epic Context Injection** block in `references/shared-conventions.md`. It self-gates on the resolved feature's `epic` back-pointer: for a standalone feature it is a no-op; for an epic member it loads EPIC.md, this feature's charter, and the completed direct dependencies' specs into context before the research and interview.
+
+## Step 2: Examine Existing Context
+
+Before interviewing, you need to understand the existing codebase. This involves reading many files across the project, which consumes context.
+
+### Recommended: Delegate to forge-researcher Subagent
+
+Spawn the `forge-researcher` subagent via the Agent tool to scan the codebase. Pass a prompt like: "Research the codebase for planning the {feature} feature. Focus on integration points, established patterns, and relevant packages."
+
+If this feature belongs to an epic, also add to the dispatch prompt: "If this feature belongs to an epic, also account for these epic contracts: {paste this feature's `consumes` and the `exposes` of its direct deps}, and the completed dependency tech-specs at {paths}. Do not re-research transitive deps." This threads epic context into the researcher without changing the agent's behavior.
+
+The researcher runs in its own context window, reads the project structure, and returns a concise integration report. This keeps your main conversation context clean for the interactive interview.
+
+**Single vs. parallel research.** For a small or well-understood codebase, **one**
+researcher is the right default. For a **large codebase or uncertain scope** (many
+packages, several integration surfaces, monorepo), dispatch **multiple `forge-researcher`
+subagents in parallel — a single message with multiple Agent calls** (the
+`superpowers:dispatching-parallel-agents` pattern), each scoped to a **disjoint focus**
+so they don't re-read the same ground:
+- one on **project structure & conventions** (layout, build, naming, error/test patterns),
+- one per **major integration area / subsystem** the feature touches (its exports, types,
+  public API),
+- optionally one on **existing feature specs & in-progress conflicts**.
+
+Each returns its own report; **you merge them** into a single integration picture for the
+interview. This cuts latency and deepens coverage versus one researcher sweeping
+everything serially. No agent change is needed — `forge-researcher` already returns a
+self-contained report; just give each instance a narrower focus.
+
+If the `forge-researcher` subagent is not available, perform the research inline (steps below).
+
+### Manual Research (fallback)
+
+1. **Read the PRD thoroughly**: Understand all requirements and constraints
+2. **Check for project-level stack decisions**: Look for `.claude/references/stack-decisions.md` in the project root. If present, read it — these are established technology choices that should be respected unless there's a strong reason to deviate.
+3. **Read the plugin's default stack reference**: Read `references/stack-discovery-checklist.md` for general stack context (only if no project-level override exists)
+4. **Examine the existing codebase**: Look at `package.json` files, existing packages, directory structure, and established patterns. Understand what conventions are already in place.
+5. **Review other features' tech specs**: Check `{specsDir}/*/tech-spec.md` and `{specsDir}/*/*/tech-spec.md` (depth-2, to find nested epic members) for consistency in approach and to identify shared infrastructure. Apply the **feature-shaped-dir bound**: only treat a directory as a feature if it directly contains a `.pipeline-state.json` (filter matches whose parent directory holds one, or enumerate members via the helper). A flat-only tree has no depth-2 feature dirs, so this gains no new matches there (REQ-COMPAT-01).
+6. **Identify integration points**: For each existing package that this feature touches, read its exports, types, and public API. Document these as constraints.
+
+### Stack Detection and Persistence
+
+After researching the codebase, identify the primary stack (language, build tool, package manager, framework). Read `references/stack-resolution.md` for the full resolution protocol.
+
+1. Check if `forge.config.json` already has a `stack` field — if so, use it
+2. Otherwise, detect from project files and use `AskUserQuestion` to confirm: "I detected this as a {stack} project. Correct?"
+3. Update `forge.config.json` with `stack`, `typeCheckCommand`, and `testCommand`
+4. Verify that a matching stack profile exists at `references/stacks/{stack}.md`. If it does, load it for stack-specific guidance during this and all subsequent stages. If no profile exists, inform the user: "No dedicated profile for {stack}. Using generic fallback — spec conventions, verification checks, and examples will be language-neutral. Consider creating a project-level override at `.claude/references/stack-decisions.md`." Then load `references/stacks/_generic.md`.
+
+## Step 3: Conduct the Interview
+
+Interview the user about technology decisions. Unlike the PRD interview, here you SHOULD discuss specific technologies, libraries, patterns, and architecture.
+
+### Interview Approach
+
+**Turn structure:** Output your research findings, analysis, or technical proposals as regular text. Then use `AskUserQuestion` for the actual questions. NEVER put questions in your text output — they MUST go through `AskUserQuestion`.
+
+**Pacing:** Present 1-2 decision areas per `AskUserQuestion` call and STOP to wait for the user's response before continuing. After receiving answers, probe deeper on anything incomplete before moving to the next topic. Signal progress in your text before the next question batch. Do NOT dump all decision areas in a single message — the interview is a conversation, not a document.
+
+**First message pattern:** Output the research summary as text, then use `AskUserQuestion` to confirm the stack and ask about the first decision area (typically package/module structure). Wait for the user to respond before proceeding to subsequent areas.
+
+**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose):
+- For each PRD requirement, propose a technical approach and ask for confirmation or alternatives
+- Proactively suggest approaches consistent with the established stack
+- Challenge over-engineering: does the feature need this, or is a simpler approach sufficient?
+- Ask about every integration point and how the feature interacts with existing modules
+
+**Parking lot:** If the user raises a concern that belongs to a different pipeline stage (e.g., backlog granularity, documentation format), acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [specs/backlog/docs stage]. Let's continue with the tech spec."
+
+### Key Decision Areas to Cover
+
+Work through these areas across multiple turns, grouping related areas (1-2 per message):
+
+- **Package/module structure**: Where does this live in the project? What are its exports? (For non-monorepo projects, this becomes module organization — where the code lives, how it's organized, and what its exports are.)
+- **Data model**: What are the key entities, their schemas, and storage approach?
+- **API design**: What endpoints or interfaces does this expose?
+- **Dependencies**: What external and internal packages are needed?
+- **Patterns**: Which established patterns from the codebase apply here?
+- **Error handling**: How are errors surfaced, propagated, and recovered from?
+- **Testing strategy**: Unit, integration, e2e — what approach for this feature?
+- **Configuration**: What's configurable? How is it configured?
+- **Migration/deployment**: Any special rollout considerations?
+
+### Requirement Traceability
+
+Every technical decision MUST reference the PRD requirement(s) it addresses. Use the format:
+
+```
+### JWT-based Session Tokens (REQ-AUTH-01, REQ-SEC-02)
+Sessions will use signed JWT tokens with...
+```
+
+If you find yourself writing a technical section that doesn't trace to any PRD requirement, STOP and ask: "I'm about to specify X, but I can't find a PRD requirement for it. Should we add one, or is this unnecessary?"
+
+## Step 4: Integration Analysis (Required)
+
+Before finalizing the tech spec, this section is MANDATORY:
+
+1. List every existing package this feature depends on
+2. List every existing package that will need to import from this feature
+3. For each integration point, document:
+   - Which types or contracts are shared
+   - How data flows between packages
+   - Any patterns established by existing code that must be followed
+   - The EXACT function signatures and import paths verified from source code. If you cannot locate an expected export, note explicitly: "WARNING: Could not locate X export in {module} — verify this exists before implementing."
+4. Check for potential conflicts with in-progress features (other spec directories)
+
+## Step 5: Write the Tech Spec
+
+Write `{resolvedFeatureDir}/tech-spec.md` with this structure:
+
+```markdown
+# {Feature Name} — Technical Specification
+
+## 1. Overview
+Brief technical summary and key architectural decisions.
+
+## 2. Module Structure
+Project location, directory layout, public API surface.
+
+## 3. Technical Decisions
+### 3.1 {Decision Area} (REQ-XXX-NN)
+Decision, rationale, alternatives considered.
+
+## 4. Data Model
+Schemas, types, storage approach.
+
+## 5. API Design
+Endpoints, interfaces, contracts.
+
+## 6. Integration Points
+How this feature connects to existing packages.
+
+## 7. Error Handling
+Error types, propagation, recovery.
+
+## 8. Testing Approach
+Strategy, tooling, coverage targets.
+
+## 9. Dependencies
+External packages, internal packages, version constraints.
+
+## 10. Open Technical Questions
+Unresolved technical decisions.
+```
+
+## Step 6: Review with User
+
+Present the complete tech spec. Ask:
+- "Does this capture all the technical decisions correctly?"
+- "Any patterns from the existing codebase I missed?"
+- "Are the integration points complete?"
+
+Use `AskUserQuestion` to collect this feedback.
+
+## Step 7: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set `currentStage` to `forge-3-specs`
+   - Record `artifacts`, `completedAt`, `version`
+   - Set `stages.forge-2-tech.basedOnVersions` to `{"forge-1-prd": <current forge-1-prd version>}`
+   - Check downstream stages (forge-3-specs, forge-4-backlog, forge-5-loop, forge-6-docs). If any have `basedOnVersions` referencing an older version of forge-2-tech, set their status to `stale`
+2. Use `AskUserQuestion` to ask about notes to persist
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete tech-spec v{n}"`, then set `stages.forge-2-tech.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+5. Tell the user: "Tech spec complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the tech spec\n  - `/feature-forge:forge-3-specs {feature}` to create implementation specs\n  - `/feature-forge:forge {feature}` to see full pipeline status"
+
+## Gotchas
+
+- Don't duplicate the PRD. The tech spec answers HOW, not WHAT. If you find yourself restating requirements, reference them by ID instead.
+- When the user's stack decisions differ from what you'd recommend, document their choice AND note your concern as an "Alternatives Considered" item — don't silently override their preference.
+- Integration points are the #1 source of implementation surprises. Spend extra time here. Read the actual code of packages this feature touches, don't just guess at their APIs.
+- If the existing codebase has inconsistent patterns (it happens), call it out and ask which pattern should be followed for this feature.

package/adapters/copilot/skills/forge-2-tech/references/stack-discovery-checklist.md

@@ -0,0 +1,95 @@
+# Stack Discovery Checklist (Plugin Default)
+
+This file contains a default stack discovery protocol for the feature-forge plugin. Projects can override this by placing a `stack-decisions.md` in `.claude/references/` at the project root.
+
+## Note to Agent
+
+This is a DISCOVERY PROTOCOL — it helps you identify what stack the project uses. It is NOT a set of decisions. Always check `.claude/references/stack-decisions.md` first — if present, it takes precedence.
+
+After discovering the stack, check if `references/stacks/{stack}.md` exists in the plugin for stack-specific guidance. See `references/stack-resolution.md` for the full resolution protocol.
+
+## Purpose
+
+This is a default discovery guide for understanding a project's technology stack. Projects should create `.claude/references/stack-decisions.md` with their actual stack decisions, which takes precedence over this checklist.
+
+## Stack Discovery Protocol
+
+### 1. Identify the Primary Language and Runtime
+
+Check for project manifests:
+- `package.json` → Node.js / Bun (JavaScript/TypeScript)
+- `pyproject.toml`, `setup.py`, `setup.cfg` → Python
+- `go.mod` → Go
+- `Cargo.toml` → Rust
+- `pom.xml`, `build.gradle`, `build.gradle.kts` → Java / Kotlin
+- `*.csproj`, `*.sln` → .NET (C#/F#)
+- `mix.exs` → Elixir
+- `Gemfile` → Ruby
+- `Package.swift` → Swift
+
+### 2. Identify the Package Manager
+
+Check for lock files:
+- `bun.lockb` → Bun
+- `pnpm-lock.yaml` → pnpm
+- `package-lock.json` → npm
+- `yarn.lock` → Yarn
+- `uv.lock` → uv
+- `poetry.lock` → Poetry
+- `go.sum` → Go modules
+- `Cargo.lock` → Cargo
+
+### 3. Identify Project Structure
+
+Check for monorepo/workspace configurations:
+- `turbo.json` → Turborepo
+- `nx.json` → Nx
+- `lerna.json` → Lerna
+- `pnpm-workspace.yaml` → pnpm workspaces
+- `pants.toml` → Pants (Python/Go/Java)
+- `go.work` → Go workspaces
+- `Cargo.toml` with `[workspace]` → Cargo workspaces
+
+If none found, this is likely a single-project repository.
+
+### 4. Identify Frameworks and Libraries
+
+Examine the dependency manifest for:
+- **Web frameworks**: Hono, Express, Fastify, FastAPI, Django, Flask, Gin, Actix, Spring Boot, etc.
+- **Frontend**: React, Vue, Svelte, Solid, etc.
+- **Database/ORM**: Drizzle, Prisma, SQLAlchemy, GORM, Diesel, etc.
+- **Validation**: Zod, Pydantic, etc.
+- **Testing**: Vitest, pytest, go test, etc.
+
+### 5. Identify Build and Type Checking
+
+- Check for CI config (`.github/workflows/`, `Makefile`, `justfile`) to find build, test, and type check commands
+- Check `package.json` scripts, `pyproject.toml` `[tool.*]` sections, or `Makefile` targets
+
+## How to Create a Project-Level Override
+
+Create `.claude/references/stack-decisions.md` in your project root with your specific stack decisions. See `references/stacks/typescript.md` or `references/stacks/python.md` for stack-specific examples of what to include.
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- [Language and version]
+- [Package manager]
+- [Build tool / monorepo orchestration if applicable]
+
+## Backend
+- [Web framework]
+- [Database / ORM]
+- [Validation library]
+
+## Frontend (if applicable)
+- [UI framework]
+- [Component library]
+- [Styling approach]
+
+## Conventions
+- [Testing framework and approach]
+- [Type checking / linting command]
+- [Module organization patterns]
+```

package/adapters/copilot/skills/forge-3-specs/forge-3-specs.md

@@ -0,0 +1,153 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-3-specs/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-3-specs
+description: Generate numbered implementation spec documents from PRD and tech spec in the forge pipeline. Use when user runs /feature-forge:forge-3-specs or asks to create detailed implementation specs for a forge feature after tech spec completion. Do NOT trigger for general specification writing, design docs, or implementation planning outside the forge pipeline.
+---
+
+# forge-3-specs — Implementation Spec Suite Generator
+
+Generate a comprehensive suite of numbered implementation specification documents that provide everything needed to implement a feature.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+
+## Step 1: Validate Prerequisites
+
+**Resolve the feature directory first** via the **Feature Directory Resolution** block in `references/shared-conventions.md`, setting `{resolvedFeatureDir}`.
+
+**Prerequisite check:** Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, both `forge-1-prd` and `forge-2-tech` must be `complete`. If not, STOP and tell the user which prerequisites are missing.
+
+Read both `{resolvedFeatureDir}/PRD.md` and `{resolvedFeatureDir}/tech-spec.md` into context.
+
+After reading the PRD and tech spec, invoke the **Epic Context Injection** block in `references/shared-conventions.md`. It self-gates on the resolved feature's `epic` back-pointer: for a standalone feature it is a no-op; for an epic member it loads EPIC.md, this feature's charter, and the completed direct dependencies' specs into context before the spec suite is planned.
+
+## Step 2: Examine Existing Context
+
+1. **Read the PRD and tech spec thoroughly**: These are your source of truth
+2. **Examine the existing codebase**: Look at how other packages are structured, what patterns they follow, what types they export
+3. **Check other features' implementation specs**: Look at `{specsDir}/*/[0-9][0-9]-*.md` AND `{specsDir}/*/*/[0-9][0-9]-*.md` (depth-2, for epic-nested features) for consistency in format and depth. Subject to the **feature-shaped-dir bound**: only treat a matched directory as a feature if it directly contains a `.pipeline-state.json` (per the Feature Directory Resolution block) — ignore `EPIC.md` directories and other non-feature subtrees. Flat-only trees gain no new matches from the depth-2 glob, so standalone behavior is unchanged (REQ-COMPAT-01).
+4. **Read integration target code**: For every package listed as an integration point in the tech spec, read its actual source — types, exports, patterns. For every integration point, include the EXACT function signature and import path you read from the source code. Include the file path where you found it. If you cannot locate an expected export, say so explicitly: 'WARNING: Could not locate X export in {module} — verify this exists before implementing.'
+5. **Read spec examples**: Read `references/spec-examples.md` for the expected depth and quality of spec sections. These examples are your quality bar.
+
+## Step 3: Plan the Document Suite
+
+Read `references/spec-archetypes.md` for the menu of document types.
+
+Based on the feature's complexity, propose a document plan to the user before writing. Output the document list as text, then use `AskUserQuestion` for the question — do NOT include the question in your text output.
+
+**Example text output (no question here):**
+```
+I'll create the following spec documents for {feature}:
+
+Required:
+  00-core-definitions.md     — Type definitions, error hierarchy, shared contracts
+  01-architecture-layout.md   — Directory structure, exports map, dependency graph
+  NN-testing-strategy.md      — Test approach, coverage targets, fixture patterns
+
+Feature-specific:
+  02-{subsystem-a}.md         — {Brief description}
+  03-{subsystem-b}.md         — {Brief description}
+  04-integration-points.md    — Integration with existing project modules
+```
+
+**Then call `AskUserQuestion`** with: "Does this look right? Should I add or remove any documents?"
+
+**Incremental artifact tracking:** After each spec document is written (by you or a writer subagent), immediately update the `artifacts` array in `.pipeline-state.json` with the new file path. This enables crash recovery if the session is interrupted mid-suite (see shared-conventions.md "Crash Recovery").
+
+## Step 4: Write the Spec Suite
+
+The suite has a hard internal dependency: every domain/integration doc references the
+shared types and layout from `00-core-definitions.md` and `01-architecture-layout.md`.
+So author in two phases — a sequential foundation, then a parallel fan-out.
+
+### 4a. Foundation pass (sequential, you author)
+
+Write `00-core-definitions.md` and `01-architecture-layout.md` yourself, in the main
+session, **before** anything else. Every later document depends on these shared types
+and the directory/exports map, so they must exist and be stable first.
+
+### 4b. Domain fan-out (parallel `forge-spec-writer` subagents)
+
+Once the foundation is written, dispatch the remaining numbered docs in parallel — **one
+`forge-spec-writer` subagent per document, in a single message with multiple Agent
+calls** (the `superpowers:dispatching-parallel-agents` pattern). Each writer is given:
+- the PRD and tech-spec,
+- the just-written `00-core-definitions.md` and `01-architecture-layout.md` (so it builds
+  on the shared types, not its own),
+- the stack profile path `references/stacks/{stack}.md` (if `stack` is set in config),
+- the quality bar in `references/spec-examples.md`,
+- the **exact single filename it must write** and the archetype slice (from
+  `references/spec-archetypes.md`) it covers.
+- **(epic members only — additive context):** the relevant `EPIC.md` Contracts section(s)
+  for this feature, and the `tech-spec.md` of each completed direct dependency at {paths} — so
+  the doc is written against real upstream contracts, not guesses.
+
+Each writer authors **only its one assigned file** and returns a short **manifest** of
+the `REQ-XXX-NN` IDs it covered (feeds Step 5 traceability). Author `NN-testing-strategy.md`
+last (it can be its own writer, or you author it once the others' shapes are known).
+
+**Fallback (no subagents available):** author the documents yourself in batches of 3–5,
+foundation first; after each batch, optionally commit
+(`git add {specsDir}/{feature}/ && git commit -m "{commitPrefix}({feature}): specs batch {n}"`)
+and re-read only `00-core-definitions.md` plus the upstream docs the next batch needs —
+do not reload everything. This keeps quality up under context pressure.
+
+### Quality requirements (every document, whoever writes it)
+
+1. Number sequentially: `00-`, `01-`, `02-`, etc.
+2. Every implementation detail MUST trace to either a PRD requirement (REQ-XXX-NN) or a tech-spec decision
+3. Before the body, include a `## Requirement Coverage` table mapping every REQ-XXX-NN this document covers to the section that implements it
+4. Include complete type definitions, data structures, and function signatures in the project's language — not pseudocode. If a stack profile exists at `references/stacks/{stack}.md` (where `{stack}` comes from `forge.config.json`), follow its conventions for type definitions, error hierarchies, and documentation comments.
+5. Include error handling for every operation
+6. Include example usage where it aids clarity
+7. Cross-reference other spec documents by filename when one document depends on definitions from another
+
+### Document Conventions
+
+- Filename format: `{specsDir}/{feature}/##-<descriptive-name>.md`
+- Each document should be self-contained enough that an engineer could implement it without reading other spec docs (though cross-references help for context)
+- Include a "Dependencies" section listing which other spec docs must be implemented first
+- Include a "Verification" section describing how to confirm the implementation matches the spec
+
+## Step 5: Cross-Reference Validation
+
+After writing all documents, verify:
+
+1. Every PRD requirement has coverage in at least one spec document
+2. Every tech-spec decision is reflected in the implementation specs
+3. Cross-references between spec documents are consistent (no broken references)
+4. Type definitions used across documents are consistent
+5. No orphaned implementation details that don't trace to requirements
+6. Produce a traceability matrix: a markdown table mapping every REQ-XXX-NN from the PRD to the spec document and section that implements it. Write this to `{resolvedFeatureDir}/TRACEABILITY.md`
+
+List any gaps or inconsistencies found and resolve them.
+
+## Step 6: Review with User
+
+Present a summary of all documents created as text, with key decisions highlighted. Then use `AskUserQuestion` to collect feedback — do NOT include these questions in your text output:
+
+"1. Does the level of detail match what you need? 2. Any areas that need more depth? 3. Any missing subsystems or concerns?"
+
+## Step 7: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set `currentStage` to `forge-4-backlog` (or verification if they want to verify first)
+   - Record all created files in `artifacts`, including `TRACEABILITY.md`
+   - Set `stages.forge-3-specs.basedOnVersions` to `{"forge-1-prd": <current version>, "forge-2-tech": <current version>}`
+   - Check downstream stages (forge-4-backlog, forge-5-loop, forge-6-docs). If any have `basedOnVersions` referencing older versions, set their status to `stale`
+2. Use `AskUserQuestion` to ask about notes to persist
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete implementation specs v{n}"`, then set `stages.forge-3-specs.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+5. Tell the user: "Implementation specs complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the specs (strongly recommended)\n  - `/feature-forge:forge-4-backlog {feature}` to generate the backlog\n  - `/feature-forge:forge {feature}` to see full pipeline status"
+
+## Gotchas
+
+- Don't create specs for things that are already fully specified in the tech spec. If the tech spec has complete type definitions, the implementation spec should reference them, not duplicate them.
+- Every spec document should include complete type definitions and function signatures in the project's language with documentation comments. The backlog generator and implementing engineer depend on these being exact, not approximate.
+- Resist the urge to create too many documents. Each document should represent a major concern. If a "document" would be under 50 lines, it probably belongs as a section in another document.
+- Watch for implicit dependencies between subsystems. If subsystem A's types are used by subsystem B, the spec should explicitly state this and ensure the types are defined in the shared types document.
+- If the feature is large, the spec suite might be 8-12 documents. If it's simple, 3-4 is fine. Match complexity to the feature, not a fixed template.

package/adapters/copilot/skills/forge-3-specs/references/spec-archetypes.md

@@ -0,0 +1,106 @@
+# Implementation Spec Archetypes
+
+This reference defines the types of implementation spec documents and their internal structure. Use this to plan which documents a feature needs.
+
+## Always Required
+
+### 00-core-definitions.md
+The shared type system and data contracts for the feature. Every other spec document references definitions here.
+
+**Sections:**
+- Type aliases, union types, enums, or language-equivalent constructs
+- Core types/interfaces/structs with documentation comments on every field
+- Error/exception hierarchy (base error, domain-specific errors, each with typed properties)
+- Constants and enumerations
+- Utility types (if any)
+
+**Rules:**
+- Every type must have documentation comments explaining its purpose (JSDoc, docstrings, godoc, etc.)
+- Error types must include `code`, `message`, and domain-specific context fields
+- Export everything through the module's entry point following project conventions
+
+### 01-architecture-layout.md
+How the feature is structured in the project.
+
+**Sections:**
+- Directory tree (full, not abbreviated)
+- Project manifest: name, exports/entry points, dependencies, build scripts
+- Build/compiler configuration: key options
+- Module export structure: what each entry point exposes
+- Build and deployment considerations
+
+**Rules:**
+- Exports/entry points must be explicit — list every public module or subpath
+- Dependencies should distinguish runtime vs dev dependencies
+- Internal project dependencies must reference exact module/package names
+
+### NN-testing-strategy.md (always last numbered document)
+How to test this feature.
+
+**Sections:**
+- Testing framework and tooling (match project conventions — e.g., vitest, pytest, go test)
+- Unit test approach: what to test, what to mock
+- Integration test approach: how to test cross-package interactions
+- Test fixtures and factories
+- Coverage targets
+- Test file location conventions
+
+## Conditionally Required
+
+### ##-{domain-concern}.md (one per major subsystem)
+Use when the feature has distinct subsystems that warrant separate specification.
+
+**Examples:** `02-provider-registry.md`, `03-streaming-engine.md`, `04-prompt-templates.md`
+
+**Sections:**
+- Purpose and scope (which PRD requirements this covers)
+- Public API: exported functions, classes, or components with full signatures
+- Internal implementation: key algorithms, data flows, state management
+- Configuration: what's configurable, defaults, validation
+- Error handling: what can fail, how errors are typed and surfaced
+- Dependencies: on types from 00, on other subsystems, on external packages
+
+### ##-integration-points.md
+Use when the feature interacts with existing modules or packages.
+
+**Sections:**
+- Integration map: which packages, which direction (depends-on vs depended-upon-by)
+- For each integration point:
+  - Which types/interfaces are shared
+  - Data flow description
+  - Import paths and barrel exports
+  - Any adapter or bridge code needed
+- Migration considerations: does integration require changes to existing packages?
+
+### ##-ui-components.md
+Use when the feature has a frontend surface.
+
+**Sections:**
+- Component tree / hierarchy
+- Props interfaces for each component
+- State management approach
+- Styling approach (consistent with project conventions)
+- Responsive behavior
+- Accessibility requirements (ARIA, keyboard navigation)
+
+### ##-data-migration.md
+Use when the feature involves schema changes or data migration.
+
+**Sections:**
+- Schema definition (using project's ORM/migration tool, or raw SQL — match project conventions)
+- Migration steps
+- Rollback strategy
+- Data seeding / fixtures
+- Zero-downtime migration considerations (if applicable)
+
+## Document Quality Checklist
+
+Before finalizing any spec document, verify:
+
+- [ ] Every section references PRD requirement IDs
+- [ ] All code is valid syntax in the project's language (not pseudocode)
+- [ ] All type references resolve to definitions in 00-core-definitions.md or clearly stated external packages
+- [ ] Error scenarios are covered, not just happy paths
+- [ ] Cross-references to other spec docs use exact filenames
+- [ ] A "Dependencies" section states which other spec docs must be implemented first
+- [ ] A "Verification" section describes how to confirm correct implementation

package/adapters/copilot/skills/forge-3-specs/references/spec-examples.md

@@ -0,0 +1,71 @@
+# Spec Examples — Quality Bar
+
+These examples demonstrate the expected depth and quality for implementation spec sections. Match this level of detail.
+
+> **Note:** The following examples use TypeScript. Adapt the language, idioms, and documentation style to match your project's stack. The STRUCTURE and DEPTH shown here is the quality bar regardless of language. See `references/stacks/{stack}.md` for language-specific conventions.
+
+## Example: Function Specification (from a session management spec)
+
+### 3.2 Token Refresh (REQ-AUTH-05, REQ-SEC-03)
+
+Refresh an expiring session token without requiring re-authentication.
+
+```typescript
+/**
+ * Refresh a session token if it's within the refresh threshold.
+ * Returns a new token with an extended expiry, or null if the session
+ * is not eligible for refresh (expired, revoked, or outside threshold).
+ *
+ * @param currentToken - The JWT string from the session cookie
+ * @param options - Refresh configuration
+ * @returns New session token string, or null if refresh is not possible
+ * @throws {SessionExpiredError} If the token has already expired
+ * @throws {TokenValidationError} If the token signature is invalid
+ */
+export async function refreshSessionToken(
+  currentToken: string,
+  options: RefreshOptions
+): Promise<string | null>;
+
+interface RefreshOptions {
+  /** Maximum age of a token eligible for refresh. Default: SESSION_DURATION_MS */
+  maxAge?: number;
+  /** How close to expiry before refresh is allowed. Default: REFRESH_THRESHOLD_MS */
+  refreshThreshold?: number;
+  /** Secret key for signing the new token */
+  signingKey: CryptoKey;
+}
+```
+
+**Error Handling:**
+- `SessionExpiredError` (code: `SESSION_EXPIRED`): Token's `exp` claim is in the past. Client must re-authenticate.
+- `TokenValidationError` (code: `TOKEN_INVALID`): Signature verification failed. Token may have been tampered with. Log a security warning.
+- Returns `null` (no error): Token is valid but not yet within the refresh threshold. No action needed.
+
+**Dependencies:**
+- Types from `00-core-definitions.md`: `SessionToken`, `SessionExpiredError`, `TokenValidationError`, `RefreshOptions`
+- Constants from `00-core-definitions.md`: `SESSION_DURATION_MS`, `REFRESH_THRESHOLD_MS`
+- `jose` library for JWT verification and signing
+
+**Verification:**
+- [ ] `refreshSessionToken` returns a new token when called with a token within the refresh threshold
+- [ ] Returns `null` for a valid token outside the refresh threshold
+- [ ] Throws `SessionExpiredError` for an expired token
+- [ ] Throws `TokenValidationError` for a token with an invalid signature
+- [ ] New token has an expiry of `SESSION_DURATION_MS` from the current time
+
+## Example: Requirement Coverage Header
+
+Every spec document should begin with a requirement coverage section:
+
+```markdown
+## Requirement Coverage
+
+| REQ ID | Requirement | Section |
+|--------|-------------|---------|
+| REQ-AUTH-05 | Token refresh without re-auth | 3.2 |
+| REQ-SEC-03 | Session expiry management | 3.1, 3.2 |
+| REQ-PERF-02 | Token validation under 10ms | 3.3 |
+```
+
+This makes traceability explicit and auditable.