@garygentry/feature-forge 0.2.12 → 0.2.13

package/adapters/codex/skills/forge/references/pipeline-state-schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Pipeline State",
+  "description": "Tracks pipeline progress for a single feature across sessions. Lives at {specsDir}/{feature}/.pipeline-state.json",
+  "type": "object",
+  "required": ["feature", "createdAt", "updatedAt", "currentStage", "stages", "pipelineStatus"],
+  "properties": {
+    "pipelineStatus": {
+      "type": "string",
+      "enum": ["active", "paused", "abandoned"],
+      "default": "active"
+    },
+    "feature": {
+      "type": "string",
+      "description": "Feature name (matches directory name under specsDir)"
+    },
+    "epic": {
+      "type": "string",
+      "description": "Back-pointer to the owning epic's name. Absent for standalone features. The epic-manifest.json is canonical on conflict (REQ-STATE-01)."
+    },
+    "branch": {
+      "type": "string",
+      "description": "Git branch this feature's pipeline work is intended to land on, recorded by the Branch Setup block (shared-conventions.md) at the entry stage. Absent when the project isn't a git repo or branchPerFeature is false. Downstream stages and forge-5-loop compare the current branch against this to detect drift back onto the default branch before committing."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "currentStage": {
+      "type": "string",
+      "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs", "complete", "forge-verify-prd", "forge-verify-tech", "forge-verify-specs", "forge-verify-backlog", "forge-verify-impl", "forge-0-epic", "forge-verify-epic"],
+      "description": "Where the pipeline IS: the most recently started stage — its `stages[<currentStage>].status` is `in-progress` while that stage is being authored, then `complete` once its artifacts are committed. A stage skill sets this to its own id when it starts. This is deliberately NOT 'the next stage to run': the next stage is DERIVED, never stored — it is the first production stage whose `stages[].status` is not `complete` (see `next_stage()` in forge-session.py, surfaced as the navigator/doctor `nextStage`). Consumers that need 'what runs next' compute it from `stages[].status`, not from this field. `complete` here means the whole pipeline is done. (Legacy/absent value: tools fall back to the derived next stage for display only — `build_rows` in forge-session.py.)"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Free-form notes persisted between sessions (user can add context before stepping away)"
+    },
+    "epicChangeRequests": {
+      "type": "array",
+      "description": "Epic-level change requests raised by a member stage (forge-1-prd/forge-2-tech) when the epic DECOMPOSITION itself must change — distinct from the same-feature `notes` parking lot. Read by forge-0-epic edit mode (which applies them) and by forge-session stage-exit (which routes the exit on `blocksCurrent`). Absent/empty for standalone features. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["kind", "target", "rationale", "blocksCurrent", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["add-feature", "redep", "move-boundary", "split"],
+            "description": "The decomposition change. add-feature/redep map 1:1 onto edit-mode mutators; move-boundary/split are composite (applied guided-manual in v1)."
+          },
+          "target": {
+            "type": "string",
+            "description": "The sibling feature to add, or the feature/boundary affected."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why the epic must change; seeds the edit-mode charter/prompt when applied."
+          },
+          "blocksCurrent": {
+            "type": "boolean",
+            "description": "true → the current feature's next stage would build on a soon-to-change decomposition (pause-now: reconcile before proceeding). false → a peer/downstream change (finish-then-edit). Drives stage-exit routing."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech"],
+            "description": "The stage that detected the epic-level concern."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "applied", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → applied|dismissed. Only forge-0-epic edit mode flips open→applied/dismissed; recording stages only create open entries; navigator/verify only read."
+          }
+        }
+      }
+    },
+    "deferredDecisions": {
+      "type": "array",
+      "description": "Same-feature decisions deliberately postponed to a LATER stage of THIS feature — a structured alternative to burying them in the free-text `notes` string. Distinct from `notes` (unstructured scratch) and from `epicChangeRequests[]` (the epic DECOMPOSITION must change). Use this when a stage would otherwise be tempted to solicit a decision that properly belongs to a downstream stage (e.g. forge-1-prd deferring the concrete cache backend to forge-2-tech): record it here instead of asking now (see the deferred-decisions rule in `references/stage-exit-protocol.md`), and the target stage addresses it. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["question", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "question": {
+            "type": "string",
+            "description": "The decision being deferred, phrased as a concrete question for the target stage to answer."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why it is deferred rather than decided now (e.g. depends on information the target stage produces)."
+          },
+          "targetStage": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs"],
+            "description": "The stage that should resolve this decision. Omit when unknown/any-later-stage."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog"],
+            "description": "The stage that deferred the decision."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "addressed", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → addressed|dismissed. The target stage flips open→addressed when it resolves the decision (or dismissed if it no longer applies); recording stages only create open entries."
+          }
+        }
+      }
+    },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "forge-0-epic": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-epic": { "$ref": "#/definitions/verifyEntry" },
+        "forge-1-prd": { "$ref": "#/definitions/stageEntry" },
+        "forge-2-tech": { "$ref": "#/definitions/stageEntry" },
+        "forge-3-specs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-specs": { "$ref": "#/definitions/verifyEntry" },
+        "forge-4-backlog": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-backlog": { "$ref": "#/definitions/verifyEntry" },
+        "forge-5-loop": { "$ref": "#/definitions/stageEntry" },
+        "forge-6-docs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-impl": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-prd": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-tech": { "$ref": "#/definitions/verifyEntry" }
+      }
+    }
+  },
+  "definitions": {
+    "stageEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in-progress", "complete", "stale"]
+        },
+        "version": {
+          "type": "integer",
+          "description": "Incremented each time this stage's artifacts are revised"
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths to artifacts produced by this stage"
+        },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": {
+          "type": ["string", "null"],
+          "description": "Git commit SHA of this stage's artifact commit (Commit 1 of the two-commit Git Commit Protocol in shared-conventions.md). Written by a small follow-up commit so it points at the artifact commit itself, never at an orphaned amend or the hash-recording commit. null until recorded (or when there was no new artifact commit)."
+        },
+        "basedOnVersions": {
+          "type": "object",
+          "description": "Upstream stage versions this artifact was built against",
+          "additionalProperties": { "type": "integer" }
+        }
+      }
+    },
+    "verifyEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "passed", "findings-reported", "findings-applied", "skipped"]
+        },
+        "findingsFile": {
+          "type": ["string", "null"],
+          "description": "Path to the verification findings document"
+        },
+        "findingsCount": {
+          "type": ["integer", "null"],
+          "description": "Number of findings reported"
+        },
+        "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
+        "fixedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": { "type": ["string", "null"], "description": "Git commit SHA of the verify/fix artifact commit. Recorded via the two-commit Git Commit Protocol (shared-conventions.md) so it points at the artifact commit, never an orphaned amend." },
+        "verifiedStageVersion": { "type": ["integer", "null"], "description": "The production stage's `version` at the moment this verify was resolved. The navigator's freshness ledger compares it to the stage's current `version`: equal means the verify is fresh; a mismatch (artifact revised since) or an absent field (legacy state) means stale, so auto-verify re-fires. Recorded by forge-verify/forge-fix when writing a passed/findings-applied status." }
+      }
+    }
+  }
+}

package/adapters/codex/skills/forge/references/process-overview.md

@@ -0,0 +1,143 @@
+# Feature Forge Pipeline Overview
+
+This document describes the end-to-end feature development pipeline managed by the feature-forge plugin. All forge skills reference this document to understand the overall flow and their position within it.
+
+The pipeline compiles a fuzzy feature idea into a machine-executable `backlog.json`. Each stage narrows the idea down and adds structure, verification gates catch gaps before they reach later stages, and a swappable autonomous loop runner (rauf by default) implements the backlog in fresh per-item sessions.
+
+## Pipeline Stages
+
+```
+[forge-0-epic] → forge-1-prd → forge-2-tech → forge-3-specs → forge-verify → forge-4-backlog → forge-verify → forge-5-loop → forge-verify → forge-6-docs
+   (optional)
+```
+
+### Stage 0: Epic (`/feature-forge:forge-0-epic <epic>`), optional
+**Input:** A change too large for one feature
+**Output:** `{specsDir}/{epic}/epic-manifest.json` + `EPIC.md` + one member-feature dir per feature
+**Method:** Decomposition interview splitting the change into member features with declared dependencies and `exposes`/`consumes` contracts. Purely additive: single-feature flows are unchanged. See [docs/architecture/epic-orchestration/README.md](../docs/architecture/epic-orchestration/README.md).
+
+### Stage 1: PRD (`/feature-forge:forge-1-prd <feature>`)
+**Input:** User's feature idea and domain knowledge
+**Output:** `{specsDir}/{feature}/PRD.md`
+**Method:** Structured interview focused exclusively on requirements. No technology decisions.
+
+### Stage 2: Tech Spec (`/feature-forge:forge-2-tech <feature>`)
+**Input:** PRD.md
+**Output:** `{specsDir}/{feature}/tech-spec.md`
+**Method:** Structured interview for technology decisions, grounded in PRD requirements.
+
+### Stage 3: Implementation Specs (`/feature-forge:forge-3-specs <feature>`)
+**Input:** PRD.md + tech-spec.md
+**Output:** `{specsDir}/{feature}/##-<name>.md` (suite of numbered documents)
+**Method:** Generate detailed implementation documents from spec archetypes.
+
+### Verification Gate (`/feature-forge:forge-verify <feature>`)
+**Input:** All artifacts from current and prior stages
+**Output:** `{specsDir}/{feature}/.verification/VERIFY-<stage>-<timestamp>.md` (includes both findings and a Fix Execution Plan)
+**Method:** Clean-context analysis producing actionable findings with an ordered fix plan.
+
+**Manual or automatic.** By default the navigator offers verification after each stage. Because
+it runs in a fresh, read-only subagent (clean-room by construction, never needs a `/clear`), it is
+safe to automate: set `autoVerify: true` (or per-stage via `autoVerifyStages`) in
+`forge.config.json` and the navigator runs `forge-verify` automatically once a stage completes,
+returning only a compact digest to the session. The freshness ledger (verify entries record the
+artifact `version` they ran against) means a stage is re-verified only when its artifact changes,
+and an explicitly `skipped` verify is respected. Fixing stays human-gated unless `autoFix: true` is
+also set, which chains `forge-fix` only when preconditions hold (zero unresolved decisions, clean
+tree, passing re-verify). See `references/shared-conventions.md` for the config keys.
+
+After verification, fixes can be applied via:
+- `/feature-forge:forge-fix <feature>` — reads the Fix Execution Plan from the findings document and applies changes (works in any session)
+- Plan mode workflow — enter plan mode, run verify, review plan, exit and execute
+- Manual — read findings and apply fixes by hand
+
+### Stage 4: Backlog (`/feature-forge:forge-4-backlog <feature>`)
+**Input:** Full spec suite
+**Output:** `{specsDir}/{feature}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if backlogDir is configured)
+**Method:** Generate structured backlog items with spec references, acceptance criteria, and dependencies. Backlog is collocated with feature specs by default.
+
+### Stage 5: Rauf Loop (`/feature-forge:forge-5-loop <feature>`)
+**Input:** `backlog.json` from Stage 4
+**Output:** Implemented source code (committed per-item by rauf)
+**Method:** Execute the autonomous coding loop against the feature's backlog. Spawns a fresh session per backlog item with full spec context. rauf is the default runner but is swappable via the `loopRunner` block in `forge.config.json`; see [`references/ralph-loop-contract.md`](./ralph-loop-contract.md).
+
+### Stage 6: Documentation (`/feature-forge:forge-6-docs <feature>`)
+**Input:** Specs + implementation
+**Output:** `{docsDir}/{feature}/` documentation suite
+**Method:** Generate developer-focused architecture documentation.
+
+## Pipeline State
+
+State is tracked in `{specsDir}/{feature}/.pipeline-state.json` and persists across session clears. The `/feature-forge:forge <feature>` navigator reads this file to show current progress.
+
+## Git Discipline
+
+Every stage completion should be followed by a git commit:
+- Commit message format: `{commitPrefix}({feature}): <action>`
+- Examples: `forge(auth): complete PRD v1`, `forge(auth): apply spec verification fixes`
+- Before applying verification fixes, commit current state first (so pre-fix state is recoverable)
+- After applying fixes, commit again
+
+## Configuration
+
+Read `forge.config.json` from project root for path overrides. See `references/forge-config-schema.json` for the full schema. If no config file exists, use defaults:
+- specsDir: `./specs`
+- docsDir: `./docs/architecture`
+- backlogDir: (null — backlog defaults to {specsDir}/{feature}/backlog.json)
+- gitCommitAfterStage: `true`
+- commitPrefix: `forge`
+
+## Git Workflow
+
+Recommended: forge work lives on an isolated `forge/{feature}` (or `forge/{epic}`) branch so all commits land together and review as one branch. The entry stages (`forge-1-prd`, `forge-0-epic`) detect whether you're on the default branch (main/master) and **strongly recommend** creating that branch when you are — still letting you decline and stay. The chosen branch is recorded in `.pipeline-state.json`, and `forge-5-loop` re-checks it before the autonomous loop starts committing per item. After implementation, merge to your development branch.
+
+To customize: `branchPrefix` (default `forge/`) sets the branch name, and `branchPerFeature: false` disables the prompt entirely (forge then works on whatever branch is checked out). Branch Setup is gated only on the project using git — independent of `gitCommitAfterStage`.
+
+If you prefer manual commit control, set `gitCommitAfterStage: false` in `forge.config.json`.
+
+## Cross-Cutting Concerns
+
+### Feature Name is Required
+Every forge skill requires a feature name as the first argument. If not provided, STOP and ask. Never guess.
+
+### Reference Existing Code
+When creating specs, always examine the existing codebase for patterns, conventions, and integration points. Check:
+- Other feature specs in `{specsDir}/`
+- Existing documentation in `{docsDir}/`
+- Module/package structure and exports in the project
+- Shared types, utilities, and conventions
+
+### Stack Context
+The project's stack is detected during forge-2-tech and persisted in `forge.config.json` (the `stack`, `typeCheckCommand`, and `testCommand` fields). See `references/stack-resolution.md` for the full resolution protocol. The project may also have a `stack-decisions.md` (preferred at `.feature-forge/`; legacy `.claude/references/`) with established technology decisions — if present, it takes highest precedence.
+
+## Subagents
+
+The plugin includes three specialized subagents in `agents/` that enhance specific
+pipeline steps. They use **model aliases** (`opus`/`sonnet`) rather than pinned IDs, so
+they track the current model tier automatically.
+
+### forge-verifier
+- **Purpose:** Read-only verification of pipeline artifacts
+- **Used by:** `forge-verify` skill (delegation via Agent tool)
+- **Tools:** Read, Glob, Grep, Bash (read-only operations only)
+- **Model:** Opus (judgement-heavy gap/inconsistency analysis)
+- **Memory:** Project-scoped persistent memory — accumulates knowledge about recurring issues and project-specific patterns across sessions
+- **Parallel:** For large modes (specs/backlog/impl), `forge-verify` dispatches several instances in parallel, one per **dimension group** (e.g. types/contracts, traceability, testing), and the parent merges their findings. An opt-in adversarial "deep verify" pass re-checks high-severity findings with a skeptic instance to cut false positives. A purely mechanical dimension (e.g. traceability validation) could run on a cheaper tier (Haiku) if cost matters.
+- **Why a subagent:** Verification reads the entire spec suite, backlog, and potentially source code. Running this in a separate context window prevents context pressure on the main conversation. The read-only tool restriction also makes it impossible to accidentally modify specs during verification.
+
+### forge-researcher
+- **Purpose:** Codebase exploration and integration mapping
+- **Used by:** `forge-2-tech` skill (spawned before the tech-spec interview)
+- **Tools:** Read, Glob, Grep, Bash (read-only)
+- **Model:** Sonnet (cost-efficient for exploration tasks)
+- **Parallel:** For a large codebase or uncertain scope, `forge-2-tech` may dispatch several researchers in parallel, each with a disjoint focus (structure/conventions, per-subsystem integration surfaces), and merge the reports.
+- **Why a subagent:** Tech-spec planning requires reading many files across the project to understand integration points. Running this in a separate context returns a concise report without consuming the main session's context, keeping the interview focused.
+
+### forge-spec-writer
+- **Purpose:** Author exactly one numbered implementation spec document to the forge-3-specs quality bar
+- **Used by:** `forge-3-specs` skill (parallel fan-out after the shared foundation docs are written)
+- **Tools:** Read, Glob, Grep, Bash, **Write** (the only authoring agent — constrained to write its single assigned file)
+- **Model:** Opus (spec authoring is detail- and judgement-heavy)
+- **Why a subagent:** Authoring the whole suite in the main session serializes the work and pressures context. Writing the foundation (00/01) first, then fanning out one writer per remaining doc, parallelizes authoring while the parent keeps the cross-reference + traceability finish in view.
+
+All three subagents are optional. If the agents are not installed or the environment doesn't support subagents, the corresponding skills fall back to running inline (or, for spec authoring, batched in the main session).