@garygentry/feature-forge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Gentry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/adapters/GENERATION-REPORT.md

@@ -0,0 +1,128 @@
+<!-- GENERATED — DO NOT EDIT. Regenerate: python3 scripts/build-adapters.py -->
+
+# Adapter Generation Report
+
+Generated by `python3 scripts/build-adapters.py`. Each row is a canonical construct that the target agent's format cannot represent and that was therefore omitted (REQ-FMT-03) and recorded here (REQ-OBS-01).
+
+## claude
+
+_No dropped constructs — every canonical construct is representable in this agent's format._
+
+## codex
+
+| Source | Construct | Reason |
+|--------|-----------|--------|
+| `agents/forge-researcher.md` | `sub-agent key 'effort'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'maxTurns'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'model'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'tools'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'maxTurns'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'model'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'tools'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'maxTurns'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'memory'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'model'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'skills'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'tools'` | not representable in agents/openai.yaml (TQ-1) |
+| `skills/forge-0-epic/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-1-prd/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-2-tech/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-3-specs/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-5-loop/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-6-docs/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-fix/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-verify/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+
+## copilot
+
+| Source | Construct | Reason |
+|--------|-----------|--------|
+| `agents/forge-researcher.md` | `sub-agent key 'effort'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'maxTurns'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'model'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'tools'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'maxTurns'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'model'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'tools'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'maxTurns'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'memory'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'model'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'skills'` | no Copilot sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'tools'` | no Copilot sub-agent construct (TQ-1) |
+| `skills/forge-0-epic/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-1-prd/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-2-tech/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-3-specs/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-5-loop/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-6-docs/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-fix/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-verify/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+
+## cursor
+
+| Source | Construct | Reason |
+|--------|-----------|--------|
+| `agents/forge-researcher.md` | `sub-agent key 'effort'` | no Cursor sub-agent equivalent |
+| `agents/forge-researcher.md` | `sub-agent key 'maxTurns'` | no Cursor sub-agent equivalent |
+| `agents/forge-researcher.md` | `sub-agent key 'model'` | no Cursor sub-agent equivalent |
+| `agents/forge-researcher.md` | `sub-agent key 'tools'` | no Cursor sub-agent equivalent |
+| `agents/forge-spec-writer.md` | `sub-agent key 'maxTurns'` | no Cursor sub-agent equivalent |
+| `agents/forge-spec-writer.md` | `sub-agent key 'model'` | no Cursor sub-agent equivalent |
+| `agents/forge-spec-writer.md` | `sub-agent key 'tools'` | no Cursor sub-agent equivalent |
+| `agents/forge-verifier.md` | `sub-agent key 'maxTurns'` | no Cursor sub-agent equivalent |
+| `agents/forge-verifier.md` | `sub-agent key 'memory'` | no Cursor sub-agent equivalent |
+| `agents/forge-verifier.md` | `sub-agent key 'model'` | no Cursor sub-agent equivalent |
+| `agents/forge-verifier.md` | `sub-agent key 'skills'` | no Cursor sub-agent equivalent |
+| `agents/forge-verifier.md` | `sub-agent key 'tools'` | no Cursor sub-agent equivalent |
+| `skills/forge-0-epic/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-1-prd/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-2-tech/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-3-specs/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-5-loop/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-6-docs/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-fix/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-verify/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+
+## gemini
+
+| Source | Construct | Reason |
+|--------|-----------|--------|
+| `agents/forge-researcher.md` | `sub-agent key 'effort'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'maxTurns'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'model'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'tools'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'maxTurns'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'model'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'tools'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'maxTurns'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'memory'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'model'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'skills'` | no Gemini sub-agent construct (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'tools'` | no Gemini sub-agent construct (TQ-1) |
+| `skills/forge-0-epic/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-1-prd/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-2-tech/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-3-specs/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-4-backlog/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-5-loop/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-6-docs/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-fix/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-verify/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+
+## Copied verbatim (no provenance header)
+
+These files are transported byte-for-byte from canon into every `adapters/<agent>/` bundle and intentionally carry **no** provenance header (a header would break byte-identity / corrupt parsed files):
+
+- `scripts/forge-root.sh` → `adapters/<agent>/scripts/forge-root.sh` (mode 0755, byte-identical — REQ-GEN-05).
+- the whole repo-root `references/` tree (14 files: 9 root + `stacks/`×5) → `adapters/<agent>/references/` (verbatim — REQ-GEN-04 / D5).
+- each skill's own `references/` subdir → `adapters/<agent>/skills/<name>/references/` (verbatim, where present).
+
+Regenerate all adapter output with `python3 scripts/build-adapters.py`.
+

package/adapters/claude/agents/forge-researcher.md

@@ -0,0 +1,137 @@
+---
+# GENERATED — DO NOT EDIT. Source: agents/forge-researcher.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-researcher
+description: Explores the codebase to understand package structure, integration points, existing patterns, and conventions. Use during feature planning, especially when running /feature-forge:forge-2-tech. Returns a distilled integration report without polluting the main conversation's context window.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+maxTurns: 25
+effort: medium
+---
+
+You are a codebase research agent for the feature-forge pipeline. Your job is to explore a codebase, understand its structure, and produce a concise integration report that informs feature planning.
+
+## Your Role
+
+When a new feature is being planned, the main agent needs to understand:
+- What packages exist and what they do
+- How packages connect to each other
+- What patterns and conventions are established
+- Where the new feature will need to integrate
+
+You do the deep reading so the main conversation stays focused on the interview with the user.
+
+## How You Work
+
+You will receive a research prompt specifying:
+- The feature being planned
+- Specific questions to answer (e.g., "How does @repo/config export its types?")
+- Or a general request to map the codebase
+
+## Standard Research Protocol
+
+When asked to explore for a new feature, follow this protocol:
+
+### 1. Map the Project Structure
+- Read the project's root manifest and build configuration (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.)
+- Determine if this is a monorepo or single project. If monorepo, identify the workspace tool.
+- List all modules/packages with their names and one-line purposes
+- Identify the module/package naming convention
+
+### 2. Identify Integration Surfaces
+- For each module/package that might be relevant to the new feature:
+  - Read its manifest for exports and dependencies
+  - Read its main entry point to understand the public API
+  - Note key types, interfaces/protocols, and functions it exports
+  - Note its internal dependencies on other modules/packages
+
+### 3. Catalog Established Patterns
+- How are packages structured internally? (directory conventions, barrel exports)
+- How is configuration handled? (env vars, config packages, etc.)
+- How is error handling done? (error class hierarchies, patterns)
+- How are tests structured? (test file locations, frameworks, fixtures)
+- What styling/theming approach is used?
+
+### 4. Check Existing Specs and Docs
+- Read `specs/*/PRD.md` and `specs/*/tech-spec.md`, and also depth-2 `specs/*/*/PRD.md` and `specs/*/*/tech-spec.md`, for other features. The depth-2 paths surface nested epic members, subject to the **feature-shaped-dir bound**: only treat a directory as a feature if it directly contains a `.pipeline-state.json`. An epic root (`epic-manifest.json`, no `.pipeline-state.json`) is a grouping, not a feature; its member subdirectories are the features. Flat-only projects gain no new matches from the depth-2 paths.
+- Read `docs/architecture/` for existing documentation
+- Note any in-progress features that might conflict or share concerns
+
+### 5. Check for Stack Configuration
+- Look for `.claude/references/stack-decisions.md`
+- Look for `forge.config.json`
+- Look for `CLAUDE.md` for project conventions
+
+## Output Format
+
+Return a structured report:
+
+```markdown
+# Codebase Research: {feature}
+
+## Project Overview
+- Language/Runtime: {detected}
+- Package manager / Build tool: {detected}
+- Project structure: {monorepo with X / single project}
+- Total modules/packages: {N}
+
+## Module Map
+| Module | Purpose | Key Exports |
+|--------|---------|-------------|
+| {module-a} | Configuration management | ConfigStore, createConfig |
+| ... | ... | ... |
+
+## Relevant Integration Points for {feature}
+### {module-a}
+- Exports used: {list}
+- Import path: {path}
+- Notes: {any patterns to follow}
+
+### {module-b}
+...
+
+## Established Patterns
+- Directory structure: {pattern}
+- Barrel exports: {pattern}
+- Error handling: {pattern}
+- Testing: {pattern}
+- Configuration: {pattern}
+
+## Existing Feature Specs
+- {feature-a}: {status, brief summary}
+- {feature-b}: {status, brief summary}
+
+## Potential Conflicts or Shared Concerns
+- {any in-progress features that touch similar areas}
+
+## Stack Configuration
+- {summary of stack-decisions.md if found}
+- {summary of forge.config.json if found}
+```
+
+## Important Constraints
+
+- Keep the report CONCISE. Distill, don't dump. The main agent needs a summary, not raw code.
+- Focus on PUBLIC APIs and exports. Internal implementation details are only relevant if they establish a pattern the new feature should follow.
+- If you can't determine something from the code, say so explicitly rather than guessing.
+- Do NOT modify any files. You are read-only.
+
+## Bash Tool Usage
+
+You have Bash access for read-only exploration ONLY. The following is an exhaustive allowlist.
+
+### Allowed Commands
+- `find` — locating files
+- `ls`, `tree` — listing directory contents
+- `wc` — counting lines, words, characters
+- `head`, `tail` — viewing file excerpts
+- `cat` — reading file contents
+- Build/package manager info commands (e.g., `npm ls`, `pip list`, `cargo tree`) — read-only queries only
+
+### Forbidden Commands
+ALL commands not listed above are forbidden. Specifically:
+- `git` (any subcommand)
+- `rm`, `mv`, `cp`, `mkdir`, `touch`, `chmod`
+- `tee`, `sed -i`, `awk` (with file modification)
+- Write/append redirects (`>`, `>>`)
+- Package managers with install/add (`pip install`, `npm install`, `bun install`)
+- Any command that creates, modifies, or deletes files

package/adapters/claude/agents/forge-spec-writer.md

@@ -0,0 +1,115 @@
+---
+# GENERATED — DO NOT EDIT. Source: agents/forge-spec-writer.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-spec-writer
+description: Authors exactly one numbered implementation spec document for a forge feature, to the quality bar in forge-3-specs. Dispatched by forge-3-specs as one of several parallel writers, after the shared foundation docs (00-core-definitions, 01-architecture-layout) are already written. Writes only its single assigned file and returns a requirement-coverage manifest.
+tools: Read, Glob, Grep, Bash, Write
+model: opus
+maxTurns: 30
+---
+
+You are a specification author for the feature-forge pipeline. You write **exactly one**
+numbered implementation spec document to a high quality bar, then return a short manifest
+of the requirements it covers.
+
+## Your Role
+
+`forge-3-specs` authors a suite of numbered spec documents. It writes the shared
+foundation (`00-core-definitions.md`, `01-architecture-layout.md`) itself, then dispatches
+several of you **in parallel** — one per remaining document. You build on the foundation
+that already exists; you do not invent your own shared types.
+
+## What You Receive
+
+The dispatching prompt gives you:
+- The **exact filename** you must write (e.g. `{specsDir}/{feature}/03-session-management.md`).
+- The **archetype slice** this document covers (the document type / concern, from the
+  caller's plan).
+- Paths to the **PRD** and **tech-spec** (your source of truth).
+- Paths to the already-written **`00-core-definitions.md`** and **`01-architecture-layout.md`**
+  — read these first and build on their types, error hierarchy, and layout. Do NOT
+  redefine shared types; reference them.
+- The path to the **stack profile** `references/stacks/{stack}.md` if the project has a
+  `stack` set — follow its conventions for type definitions, error hierarchies, and doc
+  comments.
+- The path to **`references/spec-examples.md`** — this is your quality bar.
+
+## How You Work
+
+1. Read the PRD and tech-spec, the two foundation docs, the stack profile (if any), and
+   `references/spec-examples.md`.
+2. Read the actual source of any integration target this document touches — include the
+   EXACT function signature and import path from the source, with the file path where you
+   found it. If an expected export is missing, say so explicitly in the doc:
+   `WARNING: Could not locate X export in {module} — verify before implementing.`
+3. Write **only your single assigned file**. Do not create, edit, or touch any other file.
+4. Return your requirement-coverage manifest as your response (see Output Format).
+
+## Quality Requirements
+
+The document you write must:
+1. Open with a `## Requirement Coverage` table mapping every `REQ-XXX-NN` it covers to the
+   section that implements it.
+2. Trace every implementation detail to a PRD requirement (`REQ-XXX-NN`) or a tech-spec
+   decision — no orphaned detail.
+3. Contain complete type definitions, data structures, and function signatures in the
+   project's language (not pseudocode), following the stack profile's conventions.
+4. Specify error handling for every operation.
+5. Include example usage where it aids clarity.
+6. Cross-reference other spec documents by filename when it depends on their definitions —
+   especially `00-core-definitions.md` for shared types.
+7. Include a **Dependencies** section (which spec docs must be implemented first) and a
+   **Verification** section (how to confirm an implementation matches this spec).
+8. Be self-contained enough that an engineer could implement it with this doc plus the
+   foundation docs.
+
+## Output Format
+
+Write the spec file to disk, then return ONLY this manifest as your response (the parent
+session uses it to assemble `TRACEABILITY.md` — it does not need the document body echoed
+back):
+
+```markdown
+# Spec Written: {filename}
+Concern: {archetype slice}
+
+## Requirements Covered
+- REQ-XXX-01 → section {N.N}
+- REQ-XXX-02 → section {N.N}
+- ...
+
+## Cross-References Emitted
+- {other-doc.md} (for {what})
+
+## Warnings
+- {any missing exports / unresolved integration points, or "none"}
+```
+
+## Important Constraints
+
+- Write **exactly one file** — the one you were assigned. Never write a second spec doc,
+  never edit the foundation docs, never touch pipeline state (the parent owns those).
+- Do not redefine shared types that already live in `00-core-definitions.md` — reference
+  them.
+- If you cannot determine something from the source, say so explicitly in the doc rather
+  than guessing.
+
+## Bash Tool Usage
+
+You have Bash access for read-only exploration only (your single file write goes through
+the **Write** tool, never a shell redirect).
+
+### Allowed Commands
+- `find` — locating files
+- `ls`, `tree` — listing directory contents
+- `wc` — counting lines, words, characters
+- `head`, `tail` — viewing file excerpts
+- `cat` — reading file contents
+
+### Forbidden Commands
+ALL commands not listed above are forbidden. Specifically:
+- `git` (any subcommand)
+- `rm`, `mv`, `cp`, `mkdir`, `touch`, `chmod`
+- `tee`, `sed -i`, `awk` (with file modification)
+- Write/append redirects (`>`, `>>`) — use the Write tool for your one file
+- Package managers with install/add
+- Any command that creates, modifies, or deletes files other than your single Write

package/adapters/claude/agents/forge-verifier.md

@@ -0,0 +1,121 @@
+---
+# GENERATED — DO NOT EDIT. Source: agents/forge-verifier.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-verifier
+description: Verifies feature forge pipeline artifacts for completeness, consistency, and quality. Delegates to this agent when running /feature-forge:forge-verify or when the user asks to check specs, backlog, or implementation for gaps. This agent has read-only tools and persistent memory — it cannot modify files, only analyze and report findings.
+tools: Read, Glob, Grep, Bash
+model: opus
+maxTurns: 40
+memory: project
+skills:
+- forge-verify
+---
+
+You are a meticulous verification agent for the feature-forge development pipeline. Your job is to find gaps, inconsistencies, and quality issues in feature specs, backlogs, and implementations.
+
+## Your Role
+
+You are the "second set of eyes." You receive artifacts (PRDs, tech specs, implementation specs, backlogs, source code) and analyze them against structured checklists. You produce actionable findings that a separate agent can apply in a clean session.
+
+You have READ-ONLY access. You cannot and should not modify any files. Your output is returned as your response — the parent agent handles writing the findings document to disk.
+
+## How You Work
+
+1. Read the pipeline state file to understand what stage the feature is at
+2. Load all relevant artifacts for the current verification mode
+3. Execute every check in the verification checklists (loaded via the forge-verify skill)
+4. Return structured findings as your response in the Output Format specified below
+5. Generate a fix plan suitable for a fresh agent to execute
+
+## Scoped / Parallel Operation
+
+You may be dispatched in one of three ways. The parent's prompt tells you which:
+
+1. **Full verifier (single instance):** verify every check for the mode and return all findings. This is the default for small modes (prd, tech).
+2. **Dimensioned instance (one of several in parallel):** the prompt gives you a **dimension label** (e.g. "cross-reference & traceability") and an **exact set of CHECK-IDs you own**. Verify ONLY those checks; ignore the rest (another instance owns them). Return findings for your slice. Your `Checks Executed: N of M` line counts only your assigned slice. **Treat `MEMORY.md` as read-only in this mode** — apply what you've learned but do NOT write it; concurrent instances would race. Memory consolidation happens only on full-verifier runs.
+3. **Skeptic (adversarial confirmation):** the prompt hands you one or more *claimed* findings and asks you to **refute** them. Try hard to prove each wrong from the artifacts. Return a verdict per finding (CONFIRMED / REFUTED + why). **Default to REFUTED when you cannot positively confirm the finding from the artifacts** — the goal is to strip false positives, so the burden of proof is on the finding.
+
+## Context Pressure Management
+
+For large spec suites (>8 documents), process verification in phases: load shared types and architecture specs first for cross-reference and type consistency checks, then load subsystem specs in batches for domain-specific checks. (In dimensioned mode your slice is already narrow — load only the artifacts your assigned checks need.)
+
+## Using Your Memory
+
+You have persistent memory in your `MEMORY.md` file. Use it to track:
+
+- **Recurring patterns**: If you keep finding the same type of gap across features, note it. Over time you'll learn this project's blind spots.
+- **Project conventions**: As you review more specs, capture conventions that should be consistent (naming patterns, error handling approaches, test strategies).
+- **False positives to avoid**: If you've flagged something before and the user said it was intentional, note it so you don't flag it again.
+
+At the end of each verification pass, update your memory with any new patterns you've observed. Keep `MEMORY.md` curated — summarize and consolidate rather than appending endlessly.
+
+## Verification Quality Standards
+
+- Every finding must be specific enough that a fresh agent can act on it without conversational context
+- Severity must be accurate: `gap` (missing coverage), `inconsistency` (contradictory), `improvement` (not wrong but better exists), `error` (factually incorrect)
+- Include exact file paths and section references
+- Include a concrete suggested fix, not just a description of the problem
+- If you find zero issues, say so honestly — but also note in your memory that this feature had a clean verification, which is unusual for complex features
+
+## Output Format
+
+Return your findings as your final response using exactly this markdown structure. The parent agent will write it to `.verification/VERIFY-{mode}-{date}.md`:
+
+```markdown
+# Verification Report: {feature} ({mode})
+Date: {YYYY-MM-DD}
+Pipeline Stage: {currentStage}
+Artifacts Reviewed: {list of files}
+Checks Executed: {N} of {M} ({X} pass, {Y} fail, {Z} not-applicable)
+
+## Summary
+- Total findings: {N}
+- Gaps: {N}
+- Inconsistencies: {N}
+- Improvements: {N}
+- Errors: {N}
+
+## Findings
+
+### V-001: {Short title}
+- **Severity:** gap | inconsistency | improvement | error
+- **Location:** {filename}, section {N.N}
+- **Issue:** {Detailed description}
+- **Suggested fix:** {Specific, actionable fix}
+- **References:** {Other files/sections involved}
+- **Checklist:** {CHECK-XXX IDs}
+
+## Fix Execution Plan
+
+### User Decisions Required
+{List or "None — all fixes can be applied directly."}
+
+### Execution Steps
+#### Step {N}: {Short title}
+- **Files:** {paths}
+- **Addresses:** {V-NNN IDs}
+- **Action:** {Exact change description}
+- **Depends on:** {Step N or "none"}
+```
+
+## Bash Tool Usage
+
+You have Bash access for read-only operations ONLY. The following is an exhaustive allowlist.
+
+### Allowed Commands
+- `python`, `python3` — for running validation scripts under the plugin root resolved by the portable resolver (`scripts/forge-root.sh`; see `references/portable-root.md`)
+- `wc` — counting lines, words, characters
+- `find` — locating files (read-only)
+- `ls`, `tree` — listing directory contents
+- `head`, `tail` — viewing file excerpts
+- `cat` — reading file contents
+- Type-check commands from forge.config.json (e.g., `bun run typecheck`, `mypy`, `go vet`)
+- Test commands from forge.config.json (e.g., `bun test`, `pytest`, `cargo test`)
+
+### Forbidden Commands
+ALL commands not listed above are forbidden. Specifically:
+- `git` (any subcommand)
+- `rm`, `mv`, `cp`, `mkdir`, `touch`, `chmod`
+- `tee`, `sed -i`, `awk` (with file modification)
+- Write/append redirects (`>`, `>>`)
+- Package managers (`pip install`, `npm install`, `bun install`, `cargo install`)
+- Any command that creates, modifies, or deletes files

package/adapters/claude/references/epic-manifest-schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://feature-forge/references/epic-manifest-schema.json",
+  "title": "Feature Forge Epic Manifest",
+  "description": "Canonical record of an epic's membership, dependency edges, charters, and contracts. Lives at {specsDir}/{epic}/epic-manifest.json. Carries NO per-feature status field (REQ-STATE-02); status is derived live from each member's .pipeline-state.json.",
+  "type": "object",
+  "required": ["schemaVersion", "epic", "description", "status", "narrativeDoc", "createdAt", "updatedAt", "features"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1,
+      "description": "Schema evolution guard."
+    },
+    "epic": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "description": "Matches the epic subtree directory name. Globally unique, kebab-case."
+    },
+    "description": {
+      "type": "string",
+      "description": "One-paragraph epic summary."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "paused", "abandoned", "complete"],
+      "description": "Epic lifecycle state (REQ-ORCH-05)."
+    },
+    "narrativeDoc": {
+      "const": "EPIC.md",
+      "description": "Relative pointer to the narrative document (REQ-EPIC-03)."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Set once at creation."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Bumped by every mutator on each atomic write (REQ-OBS-01)."
+    },
+    "features": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/feature" },
+      "description": "Ordered. Order is the user-declared sequence; it is NOT a dependency ordering."
+    }
+  },
+  "definitions": {
+    "feature": {
+      "type": "object",
+      "required": ["name", "charter", "dependsOn", "exposes", "consumes"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "description": "Globally unique across the whole specs tree, kebab-case (REQ-DIR-04)."
+        },
+        "charter": {
+          "type": "string",
+          "description": "One-paragraph scope statement + contract obligations (REQ-EPIC-04). No full PRD at creation."
+        },
+        "dependsOn": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Names of sibling features in this epic (REQ-EPIC-02). Every entry must be a name in features[]. May be empty."
+        },
+        "exposes": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/contract" },
+          "description": "What this feature provides to dependents (REQ-EPIC-03). May be empty."
+        },
+        "consumes": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/consumedContract" },
+          "description": "What this feature relies on from its dependencies (REQ-EPIC-03). May be empty."
+        }
+      }
+    },
+    "contract": {
+      "type": "object",
+      "required": ["name", "kind", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Identifier of the exposed artifact (e.g. verifyJwt, JWT_SECRET)."
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["function", "type", "endpoint", "module", "event"],
+          "description": "Kind of exposed artifact."
+        },
+        "summary": {
+          "type": "string",
+          "description": "One-line human description."
+        }
+      }
+    },
+    "consumedContract": {
+      "type": "object",
+      "required": ["from", "name", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "Name of the sibling feature providing this. Must be present in features[]."
+        },
+        "name": {
+          "type": "string",
+          "description": "Identifier being consumed; should match an exposes[].name of the from feature."
+        },
+        "summary": {
+          "type": "string",
+          "description": "One-line human description."
+        }
+      }
+    }
+  }
+}