@garygentry/feature-forge 0.1.0

package/adapters/cursor/skills/forge-verify/references/verification-checklists.md

@@ -0,0 +1,379 @@
+# Verification Checklists
+
+Detailed checklists for each verification mode. Execute EVERY check — do not skip.
+
+> **Stack-specific details:** When a stack profile exists at `references/stacks/{stack}.md`, load it alongside this checklist for language-specific check criteria (e.g., what "valid syntax" means, what the type check command is, how module exports work).
+
+## PRD Mode Checklist
+
+### Completeness
+- [ ] **CHECK-P01**: All template sections from `references/prd-template.md` are populated
+- [ ] **CHECK-P02**: No TBD or TODO placeholders remain in the document
+- [ ] **CHECK-P03**: Out-of-scope section exists and is specific (not just "everything else")
+- [ ] **CHECK-P04**: Open questions section contains only actionable items (not vague concerns)
+- [ ] **CHECK-P05**: Success criteria are measurable and verifiable
+
+### Requirement Quality
+- [ ] **CHECK-P06**: Every requirement has a unique ID (REQ-XXX-NN format)
+- [ ] **CHECK-P07**: Every requirement has a priority assigned (P0/P1/P2)
+- [ ] **CHECK-P08**: Every requirement is testable/verifiable — could you write an acceptance test for it?
+- [ ] **CHECK-P09**: No requirements contain technology decisions (specific libraries, frameworks, or implementation choices) unless clearly labeled as constraints with justification
+- [ ] **CHECK-P10**: User stories cover all identified actors/personas
+
+### Non-Functional Requirements
+- [ ] **CHECK-P11**: Non-functional requirements are quantified where applicable (latency targets, uptime SLAs, throughput minimums)
+- [ ] **CHECK-P12**: Security requirements are explicit, not assumed
+- [ ] **CHECK-P13**: Constraints section distinguishes mandates (must) from preferences (should/nice-to-have)
+
+### Open-Ended Analysis
+- [ ] **CHECK-P14**: Are there implicit requirements that should be made explicit? (e.g., assumptions about authentication, authorization, data retention)
+- [ ] **CHECK-P15**: Are there requirement conflicts or tensions? (e.g., performance vs. completeness, simplicity vs. flexibility)
+
+## Tech-Spec Mode Checklist
+
+### Requirement Traceability
+- [ ] **CHECK-T01**: Every tech decision traces to at least one PRD requirement (REQ-XXX-NN)
+- [ ] **CHECK-T02**: No tech decisions contradict PRD constraints
+- [ ] **CHECK-T03**: Every P0 PRD requirement has a corresponding tech decision or is explicitly deferred with rationale
+
+### Integration Analysis
+- [ ] **CHECK-T04**: Integration analysis section is complete — all packages identified
+- [ ] **CHECK-T05**: Import paths and function signatures are verified against actual source code
+- [ ] **CHECK-T06**: For each integration point: shared types/contracts are explicitly named
+- [ ] **CHECK-T07**: For each integration point: data flow direction is clear
+- [ ] **CHECK-T08**: Changes required to existing packages are specified
+
+### Design Quality
+- [ ] **CHECK-T09**: Alternatives considered for major decisions (not just "we chose X")
+- [ ] **CHECK-T10**: Error handling strategy is defined (error types, propagation, recovery)
+- [ ] **CHECK-T11**: Testing approach is specified (unit, integration, e2e strategy)
+- [ ] **CHECK-T12**: Data model aligns with PRD data requirements
+
+### Completeness
+- [ ] **CHECK-T13**: Package/module structure is defined with exports map
+- [ ] **CHECK-T14**: Configuration approach is specified
+- [ ] **CHECK-T15**: Migration/deployment considerations are addressed if applicable
+
+### Open-Ended Analysis
+- [ ] **CHECK-T16**: Are there integration points that could cause implementation surprises? (e.g., undocumented behavior, version incompatibilities, missing APIs)
+- [ ] **CHECK-T17**: Are there scalability concerns unaddressed by the current design? (e.g., data growth, concurrent users, resource limits)
+
+## Specs Mode Checklist
+
+### Requirement Coverage
+- [ ] **CHECK-S01**: Every PRD requirement (REQ-XXX-NN) is referenced by at least one implementation spec
+- [ ] **CHECK-S02**: Every P0 (must-have) requirement has detailed implementation guidance, not just a mention
+- [ ] **CHECK-S03**: Every P1 requirement is at least acknowledged with an implementation approach
+- [ ] **CHECK-S04**: No implementation spec sections exist that don't trace to a PRD requirement or tech-spec decision (orphaned specs indicate scope creep)
+
+### Tech Spec ↔ Implementation Spec Consistency
+- [ ] **CHECK-S05**: Every technology decision in the tech spec is reflected in the implementation specs
+- [ ] **CHECK-S06**: Package structure in 01-architecture-layout.md matches what the tech spec describes
+- [ ] **CHECK-S07**: Dependencies listed in the tech spec match those in the architecture spec
+- [ ] **CHECK-S08**: No implementation spec contradicts a tech-spec decision
+
+### Type System Integrity
+- [ ] **CHECK-S09**: All type definitions in 00-core-definitions.md are valid syntax in the project's language (not pseudocode)
+- [ ] **CHECK-S10**: All types referenced in other spec docs are defined in 00-core-definitions.md or an explicit external package
+- [ ] **CHECK-S11**: Error classes form a consistent hierarchy with no gaps
+- [ ] **CHECK-S12**: No duplicate or conflicting type definitions across documents
+- [ ] **CHECK-S13**: Every type/interface/struct has documentation comments on every field (JSDoc, docstrings, godoc, etc.)
+
+### Cross-Reference Consistency
+- [ ] **CHECK-S14**: All file references between spec documents point to actual files
+- [ ] **CHECK-S15**: Section references (e.g., "see section 3.2 of 02-provider-registry.md") point to actual sections
+- [ ] **CHECK-S16**: Dependency ordering between spec docs is consistent (no circular dependencies)
+- [ ] **CHECK-S17**: Import paths referenced in specs are consistent with the exports map in 01-architecture-layout.md
+
+### Error Handling Coverage
+- [ ] **CHECK-S18**: Every operation that can fail has an error type defined
+- [ ] **CHECK-S19**: Error propagation is described: where errors are thrown, caught, transformed, and surfaced
+- [ ] **CHECK-S20**: User-facing error messages are specified (not just error codes)
+- [ ] **CHECK-S21**: Recovery behavior is described for recoverable errors
+
+### Integration Point Completeness
+- [ ] **CHECK-S22**: Every package listed in the tech spec's integration section has corresponding detail in the implementation specs
+- [ ] **CHECK-S23**: For each integration: the shared types/contracts are explicitly named
+- [ ] **CHECK-S24**: For each integration: data flow direction is clear
+- [ ] **CHECK-S25**: If integration requires changes to existing packages, those changes are specified
+- [ ] **CHECK-S26**: Import paths match actual package export maps
+
+### Edge Cases and Non-Functional
+- [ ] **CHECK-S27**: Concurrent access scenarios are addressed if relevant
+- [ ] **CHECK-S28**: Empty/null/undefined inputs are handled
+- [ ] **CHECK-S29**: Performance-sensitive paths are identified
+- [ ] **CHECK-S30**: Security considerations from PRD are reflected in implementation
+- [ ] **CHECK-S31**: Observability (logging, metrics, tracing) approach is specified if PRD requires it
+- [ ] **CHECK-S32**: Each implementation spec has a clear "public API" section that defines what is exported vs internal
+
+### Testing Strategy
+- [ ] **CHECK-S33**: Testing strategy document exists
+- [ ] **CHECK-S34**: Test approach covers unit, integration, and e2e as appropriate
+- [ ] **CHECK-S35**: Mock/fixture strategy is defined for external dependencies
+- [ ] **CHECK-S36**: Coverage targets are stated
+- [ ] **CHECK-S37**: Test fixtures and mocks defined in specs align with real interface shapes from 00-core-definitions.md
+
+### Traceability
+- [ ] **CHECK-S38**: Build a complete traceability matrix from every REQ-XXX-NN to the spec document and section that implements it. Any REQ ID not found in at least one spec is a gap finding.
+
+## Backlog Mode Checklist
+
+### Schema Compliance
+- [ ] **CHECK-B01**: backlog.json is valid JSON
+- [ ] **CHECK-B02**: Every item has all required fields: id, type, priority, title, description, acceptanceCriteria, status, dependsOn, specReferences
+- [ ] **CHECK-B03**: All `id` values are unique
+- [ ] **CHECK-B04**: All `type` values are valid (feature, bugfix, chore, etc.)
+- [ ] **CHECK-B05**: All `priority` values are valid numbers
+- [ ] **CHECK-B06**: All `status` values are valid (pending, in-progress, complete, etc.)
+
+### Spec Coverage
+- [ ] **CHECK-B07**: Every implementation spec document is referenced by at least one backlog item
+- [ ] **CHECK-B08**: Every P0 PRD requirement is covered by at least one backlog item's acceptance criteria
+- [ ] **CHECK-B09**: No backlog item references a spec file that doesn't exist
+- [ ] **CHECK-B10**: specReferences paths are valid relative paths to actual files
+
+### Task Quality
+- [ ] **CHECK-B11**: Each item is scoped to be completable in a single rauf loop iteration
+- [ ] **CHECK-B12**: Descriptions are detailed enough for a fresh agent with no prior context
+- [ ] **CHECK-B13**: Acceptance criteria are objectively verifiable (not subjective like "works well")
+- [ ] **CHECK-B14**: Each item specifies what files to create or modify
+
+### Dependency Ordering
+- [ ] **CHECK-B15**: `dependsOn` references are valid item IDs
+- [ ] **CHECK-B16**: No circular dependencies exist
+- [ ] **CHECK-B17**: Foundation items (types, scaffold) have no dependencies
+- [ ] **CHECK-B18**: Items that depend on types/interfaces reference the item that creates them
+- [ ] **CHECK-B19**: Priority ordering is consistent with dependency ordering (dependencies should have equal or higher priority)
+
+### Completeness
+- [ ] **CHECK-B20**: There is an item for the initial package scaffold
+- [ ] **CHECK-B21**: There is an item for shared types and error hierarchy
+- [ ] **CHECK-B22**: There are items for each major subsystem
+- [ ] **CHECK-B23**: There are items for integration wiring (not just isolated subsystems)
+- [ ] **CHECK-B24**: There are items for tests (or testing is included in each feature item's acceptance criteria)
+- [ ] **CHECK-B25**: No large items that try to do too many things (should be broken down)
+
+## Implementation Mode Checklist
+
+### Spec Compliance
+- [ ] **CHECK-I01**: Every file listed in 01-architecture-layout.md exists
+- [ ] **CHECK-I02**: Package.json exports map matches what the spec describes
+- [ ] **CHECK-I03**: Every type in 00-core-definitions.md is implemented
+- [ ] **CHECK-I04**: Every error class is implemented with correct properties
+
+### Backlog Completion
+- [ ] **CHECK-I05**: Every backlog item marked "complete" has its acceptance criteria met
+- [ ] **CHECK-I06**: No backlog items are still "pending" or "in-progress"
+- [ ] **CHECK-I07**: Acceptance criteria can be verified by reading the code
+
+### Integration
+- [ ] **CHECK-I08**: Import paths work (no broken imports)
+- [ ] **CHECK-I09**: Module exports/entry points re-export everything the spec says they should
+- [ ] **CHECK-I10**: Types shared with other packages are compatible
+- [ ] **CHECK-I11**: Type checking / linting passes for the module (`{typeCheckCommand}` from forge.config.json succeeds)
+- [ ] **CHECK-I12**: Type checking / linting passes for modules that depend on this one
+
+### Code Quality
+- [ ] **CHECK-I13**: No placeholder or TODO comments that should have been resolved
+- [ ] **CHECK-I14**: Error handling matches what the specs describe
+- [ ] **CHECK-I15**: No hardcoded values that should be configurable
+- [ ] **CHECK-I16**: Tests exist and pass
+- [ ] **CHECK-I17**: No obvious missing test cases for documented edge cases
+
+### Documentation
+- [ ] **CHECK-I18**: Package has a README or the docs directory has been populated
+- [ ] **CHECK-I19**: Exported functions/classes have documentation comments (JSDoc, docstrings, godoc, etc.)
+- [ ] **CHECK-I20**: Configuration options are documented
+
+## Epic Mode Checklist
+
+Run `epic-manifest.py validate "{epic}" --specs-dir "{specsDir}" --json` once; map its
+findings to E01/E02/E03/E08. Then perform the judgment checks E04–E07 by reading the
+manifest, EPIC.md, and completed members' specs.
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
+```
+
+### Manifest Integrity (helper-delegated)
+- [ ] **CHECK-E01**: `epic-manifest.json` conforms to `epic-manifest-schema.json`
+  (delegated: `validate` reports `schema` / `corrupt-json` findings).
+- [ ] **CHECK-E02**: the `dependsOn` graph is **acyclic** (delegated: `validate` reports
+  `cycle`).
+- [ ] **CHECK-E03**: no dangling `dependsOn` / `consumes.from` — every reference names a
+  feature in `features[]` (delegated: `validate` reports `dangling-ref`).
+- [ ] **CHECK-E08**: **global name uniqueness** across the specs tree — no feature name
+  resolves to more than one feature-shaped dir (delegated: `validate` / `check-name`
+  report `duplicate-name` / `ambiguous`). Surfaced non-fatally for manual cleanup.
+
+### Charter & Contract Coverage (verifier judgment)
+- [ ] **CHECK-E04**: **charter coverage** — every feature has a non-empty `charter`
+  stating scope **and** contract obligations (REQ-EPIC-04).
+- [ ] **CHECK-E05**: each feature has a meaningful `exposes`/`consumes` declaration — flag
+  a feature with empty contracts that the narrative implies should have them
+  (REQ-EPIC-03). (Empty is *schema-legal* but suspicious for a feature other features
+  depend on.)
+- [ ] **CHECK-E06**: **EPIC.md ⇆ manifest contract drift, for completed features only** —
+  the contracts in `EPIC.md` match the manifest `exposes`/`consumes`, and a completed
+  feature's specs actually deliver what it `exposes`. Drift between EPIC.md prose and the
+  manifest, or between the manifest and the built spec, is a finding (REQ-VERIFY-01).
+- [ ] **CHECK-E07**: **back-pointer ⇆ manifest consistency** — every member's
+  `.pipeline-state.json` `epic` value names this epic, and every `features[]` entry has a
+  matching member directory. On conflict the **manifest wins** (REQ-STATE-01); report, do
+  not auto-repair.
+
+## Findings Document Template (Step 4)
+
+Write findings to `{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`
+(for epic mode, `{specsDir}/{epic}/.verification/VERIFY-epic-{YYYY-MM-DD}.md` — same
+format, with `{mode}=epic`). Ensure the `.verification/` subdirectory exists first.
+
+```markdown
+# Verification Report: {feature} ({mode})
+Date: {YYYY-MM-DD}
+Pipeline Stage: {currentStage}
+Artifacts Reviewed: {list of files}
+
+## 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 of what's wrong}
+- **Suggested fix:** {Specific, actionable fix a fresh agent can apply}
+- **References:** {Other files/sections involved}
+- **Checklist:** {CHECK-XXX IDs that this finding relates to}
+
+### V-002: ...
+
+## Fix Execution Plan
+
+### User Decisions Required
+{List any findings that need user input before fixes can be applied. If none, write "None — all fixes can be applied directly."}
+
+### Execution Steps
+
+Apply these steps in order. Each step is self-contained — a fresh agent can
+execute it without prior context beyond this document.
+
+#### Step {N}: {Short title}
+- **Files:** {exact file paths to edit}
+- **Addresses:** {V-NNN finding IDs}
+- **Checklist:** {CHECK-XXX IDs}
+- **Action:** {Exact description of what to change — specific enough for a fresh agent}
+- **Depends on:** {Step N or "none"}
+- **Rationale:** {Why this order, why grouped this way}
+```
+
+## Example Findings (Step 4)
+
+Here are complete example findings showing the expected quality:
+
+**Gap example:**
+```
+### V-003: Missing retry logic for rate-limited API calls
+- **Severity:** gap
+- **Location:** specs/auth/03-session-management.md, section 3.2 "Token Refresh"
+- **Issue:** PRD.md REQ-ERR-04 requires retry behavior when external auth providers rate-limit requests. The spec only handles rate limits by throwing `ProviderRateLimitError` — no retry logic, backoff strategy, or max-retry count is specified.
+- **Suggested fix:** Add a "Retry Strategy" subsection to section 3.2 specifying: exponential backoff starting at 500ms, max 3 retries, circuit breaker after 5 consecutive failures. Reference the error type from 00-core-definitions.md.
+- **References:** PRD.md REQ-ERR-04, 00-core-definitions.md (ProviderRateLimitError)
+```
+
+**Inconsistency example:**
+```
+### V-007: Conflicting session duration constants
+- **Severity:** inconsistency
+- **Location:** 00-core-definitions.md section 2.3 vs 03-session-management.md section 1.1
+- **Issue:** 00-core-definitions.md defines `SESSION_DURATION_MS = 7 * 24 * 60 * 60 * 1000` (7 days), but 03-session-management.md section 1.1 states "sessions expire after 30 days." These contradict each other.
+- **Suggested fix:** Align both documents to the PRD requirement. PRD.md REQ-SEC-03 says "sessions should have a reasonable expiry" without specifying a duration — use `AskUserQuestion` to ask the user which value is intended, then update both documents.
+- **References:** PRD.md REQ-SEC-03, 00-core-definitions.md section 2.3, 03-session-management.md section 1.1
+```
+
+**Improvement example:**
+```
+### V-012: Testing strategy lacks fixture factory pattern
+- **Severity:** improvement
+- **Location:** specs/auth/08-testing-strategy.md, section 3 "Test Fixtures"
+- **Issue:** The testing strategy describes test data inline in each test file. For a feature with 15+ test files, this leads to duplicated fixture data. A factory pattern would reduce duplication and make tests more maintainable.
+- **Suggested fix:** Add a "Fixture Factories" subsection describing a `createTestSession()`, `createTestUser()` factory pattern in a shared `__fixtures__/` directory, consistent with how @repo/db handles test fixtures.
+- **References:** 01-architecture-layout.md (directory structure), packages/db/src/__fixtures__/ (existing pattern)
+```
+
+## Epic Mode State Write Detail (Step 6)
+
+Epic mode is **epic-scoped**, not per-feature: record its result into the epic-level
+state file `{specsDir}/{epic}/.epic-state.json` — **never** into any member's
+`.pipeline-state.json`. This file holds only epic-scoped stage entries (currently just
+`forge-verify-epic`) and carries **no cached per-feature member status** (so it does not
+violate REQ-STATE-02; per-feature status is always derived live from each member's
+`.pipeline-state.json`).
+
+Set `stages.forge-verify-epic.status` to `findings-reported` (or `passed` if zero
+findings), recording `findingsFile`, `findingsCount`, and `verifiedAt`. The minimal
+shape:
+
+```jsonc
+{
+  "epic": "auth-overhaul",              // matches the manifest `epic`
+  "stages": {
+    "forge-verify-epic": {
+      "status": "findings-reported",     // "findings-reported" | "passed" | "findings-applied"
+      "findingsFile": ".verification/VERIFY-epic-2026-06-12.md",
+      "findingsCount": 3,
+      "verifiedAt": "2026-06-12T00:00:00Z"
+    }
+  }
+}
+```
+
+**Write mechanism.** `epic-manifest.py` exposes no subcommand that writes this file, so
+the skill writes it **directly**, using an atomic temp-file + `os.replace()` pattern
+(mirroring `02-manifest-helper-cli.md §3.3`): serialize the merged state to a sibling
+temp file in `{specsDir}/{epic}/`, flush, then `os.replace()` it into place. Create the
+file **lazily on first write** (a missing file is simply created; an existing file is
+read, its `stages.forge-verify-epic` entry merged/replaced, and rewritten). On any I/O
+failure, **report the error and leave any prior `.epic-state.json` intact** (never a
+partial write). For example:
+
+```bash
+python3 - "$SPECS_DIR/$EPIC" <<'PY'
+import json, os, sys, tempfile
+from pathlib import Path
+epic_dir = Path(sys.argv[1])
+path = epic_dir / ".epic-state.json"
+state = {}
+if path.exists():
+    state = json.loads(path.read_text())
+state.setdefault("epic", epic_dir.name)
+state.setdefault("stages", {})
+state["stages"]["forge-verify-epic"] = {
+    "status": "findings-reported",   # or "passed" when findingsCount == 0
+    "findingsFile": ".verification/VERIFY-epic-2026-06-12.md",
+    "findingsCount": 3,
+    "verifiedAt": "2026-06-12T00:00:00Z",
+}
+fd, tmp = tempfile.mkstemp(dir=str(epic_dir), prefix=".epic-state.", suffix=".tmp")
+try:
+    with os.fdopen(fd, "w") as f:
+        json.dump(state, f, indent=2)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+except OSError as e:
+    try:
+        os.unlink(tmp)
+    except OSError:
+        pass
+    print(f"failed to write .epic-state.json: {e}", file=sys.stderr)
+    raise
+PY
+```

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

@@ -0,0 +1,133 @@
+---
+# 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.
+---
+
+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/gemini/agents/forge-spec-writer.md

@@ -0,0 +1,112 @@
+---
+# 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.
+---
+
+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