forge-orkes 0.3.6 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.3.1",
+    "version": "0.1.0",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {
@@ -17,7 +17,11 @@
       "refactor",
       "chore",
       "docs"
-    ]
+    ],
+    "verification": {
+      "auto_fix": true,
+      "max_retries": 2
+    }
   },
   "hooks": {
     "PostToolUse": [

package/template/.claude/skills/executing/SKILL.md

@@ -92,7 +92,8 @@ For each task in the plan:
 5. **Verify** using the verify step (run tests, inspect output)
 6. **Confirm** done criteria are met
 7. **Commit** atomically
-8. **Mark complete** — `TaskUpdate` the native task to `completed`
+8. **Run verification gate** — execute configured verification commands (see Verification Gate below)
+9. **Mark complete** — `TaskUpdate` the native task to `completed`
 
 ## TDD Flow (When task type="tdd")
 
@@ -127,6 +128,73 @@ feat(auth-01): implement JWT-based login
 - Include integration test for login flow
 ```
 
+## Verification Gate
+
+After each task commit, run the project's configured verification commands to catch regressions immediately. This is mechanical enforcement — not optional, not agent-directed.
+
+### Load Config
+
+Read `.forge/project.yml → verification`. If `verification.commands` is empty or missing, skip this section entirely.
+
+```yaml
+# Example from project.yml:
+verification:
+  commands:
+    - cmd: "npm run lint"
+      advisory: false
+    - cmd: "npm test"
+      advisory: false
+    - cmd: "npx tsc --noEmit"
+      advisory: true          # pre-existing failures — warn only
+  auto_fix: true
+  max_retries: 2
+```
+
+### Execution Flow
+
+For each verification command, in order:
+
+1. **Run the command** via Bash
+2. **If it passes** → move to next command
+3. **If it fails:**
+   - **Advisory command?** → Log warning: *"Advisory: `{cmd}` failed (pre-existing issue, not blocking)."* Move to next command.
+   - **Non-advisory + `auto_fix: false`?** → Log failure and continue to next task. Don't block.
+   - **Non-advisory + `auto_fix: true`?** → Enter auto-fix loop (below)
+
+### Auto-Fix Loop
+
+When a non-advisory verification command fails with `auto_fix: true`:
+
+```
+Attempt 1:
+  1. Read the command output (error messages, failing tests, lint errors)
+  2. Identify the issue — is it caused by the current task's changes?
+     - YES → fix the code, stage fixes, amend the commit
+     - NO (pre-existing) → mark this command as advisory for this session, log warning, continue
+  3. Re-run the verification command
+  4. If passes → continue to next command
+  5. If fails → attempt 2 (up to max_retries)
+
+After max_retries exhausted:
+  → Log the failure in the execution summary
+  → Continue to next task (don't block the whole plan)
+  → The verifying skill will catch persistent failures later
+```
+
+### Integration with 3-Strike Rule
+
+Verification auto-fix attempts count toward the task's 3-strike limit. If a task has already used 2 strikes on implementation issues, it gets 1 verification retry max.
+
+### What NOT to Fix in Verification
+
+- **Pre-existing failures** not caused by the current task → mark advisory
+- **Flaky tests** that pass on re-run without code changes → note in summary, don't count as a strike
+- **Unrelated warnings** (deprecation notices, non-blocking lint info) → ignore
+
+### Quick Tier
+
+Verification gates also run for Quick tier tasks (`quick-tasking` skill). After the commit, run all non-advisory verification commands once. If they fail, show the output and let the agent fix — but limit to 1 retry (Quick tier shouldn't spend time in fix loops).
+
 ## Context Engineering
 
 ### When to Spawn Fresh Agent

package/template/.claude/skills/forge/SKILL.md

@@ -30,12 +30,11 @@ Check for state files in this order:
 5. **If no active milestones:** Proceed to init or ask user to create one.
 6. Load the selected milestone's state file (`.forge/state/milestone-{id}.yml`)
 7. **Route based on `current.status`, NOT on `overall_percent`.** The `current.status` field is the authoritative workflow position. A milestone is only complete when `current.status` equals `complete`. Even if `overall_percent` is 100%, the milestone still needs to go through any remaining workflow steps (verifying, auditing, refactoring) before it is truly done.
-8. Report position from the milestone-specific state:
+8. Report position briefly, then **immediately route to the next skill** (see Step 3: Mandatory Auto-Routing):
    - **Workflow status** (`current.status`) — this is the primary indicator of where you are
-   - Current phase, plan, task
+   - Phase progress using precise terminology: "Executed" (code done, not verified), "Verified", "Pending", "In progress" — **never say "Complete" for a phase that hasn't been verified**
    - Task progress percentage (`overall_percent`) — this measures task completion, not workflow completion
-   - Active blockers
-   - Recent decisions
+   - **Do NOT present a menu of options.** State the position, state the next action, invoke the skill.
 
 If Beads is installed and enabled (`settings.json → forge.beads_integration: true`), also run `bd prime` for cross-session context. See `beads-integration` skill for details. This is optional — Forge works fully without it.
 
@@ -61,393 +60,7 @@ If state exists → go to **Step 2B: Detect Tier**.
 
 ## Step 2A: Project Init
 
-This interactive workflow runs once when Forge doesn't find an existing project. First, detect whether this is a **brownfield** (existing codebase) or **greenfield** (new project) — then run the appropriate init path.
-
-### Detect Project Type
-
-Check for signals of an existing codebase:
-
-```
-Check: package.json OR requirements.txt OR go.mod OR Cargo.toml (dependency manifest)
-Check: .git/ (version control history)
-Check: src/ OR app/ OR lib/ (source directories)
-Check: existing config files (tsconfig.json, .eslintrc, vite.config, etc.)
-```
-
-- **2+ signals found** → **Brownfield path** (existing codebase)
-- **0-1 signals** → **Greenfield path** (new project)
-
-Ask user to confirm: *"This looks like an [existing project / new project]. Is that right?"*
-
----
-
-### Brownfield Path: Discover Existing Project
-
-For existing codebases, **scan first, confirm with user second.** Don't ask the user to describe what you can discover.
-
-#### Discovery Step 0: Framework Detection
-
-Before scanning the tech stack, check for two things: (1) existing meta-prompting frameworks with project knowledge to absorb, and (2) companion tools that should be preserved alongside Forge.
-
-**Meta-Framework Signatures** (contain project knowledge — candidates for absorption):
-
-```
-# GSD (Get Shit Done)
-Check: agents/gsd-*.md OR commands/gsd/ directory
-Check: Root-level PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md
-Check: get-shit-done/ directory
-Check: CONTEXT.md with "NON-NEGOTIABLE" or "DEFERRED" sections
-
-# Spec-Kit
-Check: spec-driven.md
-Check: templates/ with spec-template.md
-Check: extensions/catalog.json
-Check: constitution-template.md
-
-# BMAD
-Check: agents/ with 20+ agent files
-Check: workflows/ directory
-Check: bmad-* prefixed files
-
-# Generic / Unknown
-Check: .claude/agents/ or .claude/skills/ (someone else's custom framework)
-Check: CLAUDE.md with framework-like routing tables
-Check: Any structured agent/workflow system
-```
-
-**Companion Tool Signatures** (not frameworks — independent tools that work alongside Forge):
-
-```
-# Beads (persistent cross-session memory)
-Check: .beads/ directory
-Check: beads.jsonl or beads.db
-Check: bd CLI available (Bash: which bd)
-→ If found: Enable forge.beads_integration in settings.json. Do NOT absorb or archive.
-→ Beads is independent — it runs alongside Forge, not inside it.
-```
-
-**If a meta-framework is detected**, present the finding and offer three options:
-
-*"I found an existing [{framework name}] setup in this project. It contains project documentation and decisions that are valuable. How would you like to handle it?"*
-
-**Option A: Absorb & Convert** (recommended)
-Read all existing framework documentation, extract the project knowledge, and convert it into Forge's format. This means:
-- Project descriptions → `.forge/project.yml`
-- Requirements → `.forge/requirements.yml`
-- Roadmaps/plans → `.forge/roadmap.yml`
-- Context/decisions → `.forge/context.md`
-- Current state/progress → `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml`
-- Constitutional rules (if any) → `.forge/constitution.md`
-- Design system rules (if any) → `.forge/design-system.md`
-
-→ Go to **Framework Absorption** below.
-
-**Option B: Archive & Start Fresh**
-Move existing framework files into `.forge/archive/{framework-name}/` for reference, then run the standard brownfield discovery (which will still scan the codebase itself). The archive is preserved and can be consulted later.
-
-**Option C: Keep Both (Transition Period)**
-Initialize Forge alongside the existing framework. Forge reads from `.forge/` while old framework files remain in place. Useful when you want to try Forge without committing. Remove the old framework later when confident.
-
----
-
-#### Framework Absorption (Option A)
-
-When absorbing an existing framework, read its documentation and convert systematically.
-
-**GSD Absorption Map:**
-
-| GSD Source | Read | Extract | Write to Forge |
-|-----------|------|---------|---------------|
-| `PROJECT.md` | Project name, description, tech stack, goals | Structured project info | `.forge/project.yml` |
-| `REQUIREMENTS.md` | Feature requirements, acceptance criteria | Convert prose to YAML with IDs | `.forge/requirements.yml` |
-| `ROADMAP.md` | Phases, milestones, dependencies | Convert to YAML with dependency refs | `.forge/roadmap.yml` |
-| `STATE.md` | Current phase, progress, blockers | Machine-readable state | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
-| `CONTEXT.md` | NON-NEGOTIABLE decisions, DEFERRED ideas | Locked decisions, deferred items | `.forge/context.md` |
-| `references/ui-brand.md` | Design system rules, brand guidelines | Component mappings, style rules | `.forge/design-system.md` |
-| `references/verification-patterns.md` | Verification approach | Inform `verifying` skill config | Constitution articles |
-| `references/tdd.md` | Testing approach | Inform constitution Article II | Constitution articles |
-| Agent customizations | Custom agent behaviors, tool restrictions | Map to Forge agent definitions | `.claude/agents/*.md` (if custom) |
-
-**Spec-Kit Absorption Map:**
-
-| Spec-Kit Source | Read | Extract | Write to Forge |
-|----------------|------|---------|---------------|
-| `spec-driven.md` | Core methodology | Governance patterns | `.forge/constitution.md` |
-| `templates/spec-template.md` | Spec structure | Requirements format | `.forge/requirements.yml` |
-| `templates/constitution-template.md` | Constitutional articles | Immutable gates | `.forge/constitution.md` |
-| `extensions/` | Extension configs | Specialized skills | `.claude/skills/` (if relevant) |
-| Project specs (if filled in) | Project-specific decisions | Locked decisions | `.forge/context.md` |
-
-**Generic Framework Absorption:**
-
-For unknown frameworks, use the `researching` skill to:
-1. Read all markdown and config files in the framework directory
-2. Identify: project descriptions, requirements, decisions, state, design rules
-3. Map each to the closest Forge equivalent
-4. Present the mapping to the user for confirmation before writing
-
-**Absorption Process:**
-
-1. Read all source files from the existing framework
-2. For each Forge target file, synthesize content from the relevant sources
-3. Convert prose to YAML where Forge expects YAML (project, requirements, roadmap, state)
-4. Preserve markdown where Forge expects markdown (constitution, context, design-system)
-5. **Never discard information** — if something doesn't map to a Forge file, note it in `.forge/context.md` under a "Carried Forward" section
-6. Move original framework files to `.forge/archive/{framework-name}/`
-7. Present a diff-style summary: *"Here's what I converted: [list]. And here's what I archived for reference: [list]. Anything I should handle differently?"*
-
-After absorption, **always** continue with the standard brownfield steps below (tech stack scan, design system detection, etc.). This is critical — see the verification step next.
-
-#### Documentation vs. Codebase Verification
-
-**Never trust framework documentation at face value.** Documentation drifts. The codebase is the source of truth.
-
-After reading existing framework docs, **cross-reference every claim against the actual code**:
-
-```
-For each claim in the documentation:
-  1. Find the corresponding code (Glob, Grep, Read)
-  2. Verify the claim matches reality
-  3. Flag any discrepancies
-```
-
-**Common drift patterns to check:**
-
-| Documentation Says | Verify Against |
-|-------------------|----------------|
-| "Tech stack: React + PostgreSQL" | `package.json` dependencies, actual imports in `src/` |
-| "Uses PrimeReact for all UI" | `Grep: src/ for "from 'primereact"` — are there also raw HTML tables, custom modals? |
-| "Tests written for all features" | `Glob: src/**/*.test.*` — actual coverage vs. claimed coverage |
-| "Auth uses Clerk/Auth0/etc." | `Grep: src/ for auth imports` — is there also custom auth code? |
-| "State management via Redux" | `package.json` + actual imports — did they switch to Zustand mid-project? |
-| "API uses REST" | `Grep: src/ for GraphQL, tRPC, WebSocket` — mixed protocols? |
-| Requirements list features A, B, C | Do routes/components for A, B, C actually exist? Are any partially implemented? |
-| Roadmap says "Phase 2 complete" | Are Phase 2 features actually wired and working, or are there stubs? |
-
-**When discrepancies are found:**
-
-Present them to the user clearly:
-
-*"I found some differences between the GSD documentation and the actual codebase:*
-
-- *PROJECT.md says 'PostgreSQL' but I only see SQLite in dependencies*
-- *REQUIREMENTS.md lists a 'notifications' feature but I can't find any notification code*
-- *STATE.md says Phase 2 is complete, but the dashboard component looks like a stub (returns placeholder text)*
-- *The docs mention PrimeReact exclusively, but I found 3 files using raw HTML tables instead of DataTable*
-
-*Should I update the Forge config to match what's actually in the code, or are some of these features that were removed/deferred?"*
-
-**Priority order for truth:**
-1. **What the code actually does** — highest authority
-2. **What the user confirms** — resolves ambiguity
-3. **What the documentation says** — useful context, but may be stale
-
-Write the verified state to Forge files. For any unresolved discrepancies, add them to `.forge/context.md` under a "Needs Resolution" section so they get addressed during planning.
-
----
-
-#### Discovery Step 1: Tech Stack Scan
-
-```bash
-# Package manifest
-Read: package.json → name, dependencies, devDependencies, scripts
-# Or: requirements.txt, go.mod, Cargo.toml, etc.
-
-# Config files
-Glob: tsconfig.json, .eslintrc*, vite.config.*, next.config.*, webpack.config.*
-Glob: .env.example, docker-compose.yml
-
-# Source structure
-Bash: find src/ -type f | head -50  # understand file organization
-Bash: wc -l src/**/*.{ts,tsx,js,jsx} 2>/dev/null | tail -1  # codebase size
-```
-
-From this, auto-detect:
-- Language and framework
-- Build tools and test framework
-- Database (from dependencies or config)
-- Project name and description (from package.json or README)
-
-#### Discovery Step 2: Design System Detection
-
-```bash
-# Check dependencies for known UI libraries
-Grep: package.json for: primereact, @mui/, @chakra-ui/, @radix-ui/, antd, @headlessui/
-Grep: package.json for: tailwindcss, primeflex, @emotion/, styled-components
-
-# Check actual usage in source
-Grep: src/ for import patterns: "from 'primereact", "from '@mui/", "from '@/components/ui"
-Grep: src/ for icon usage: "pi pi-", "Material", "lucide-react"
-
-# Check for theme files
-Glob: **/*theme*, **/*variables.scss, **/tailwind.config*, **/globals.css
-```
-
-From this, auto-detect:
-- Component library (and version from package.json)
-- Icon set in use
-- Layout system (PrimeFlex, Tailwind, MUI Grid, etc.)
-- Theme approach (SCSS variables, CSS-in-JS, Tailwind config, design tokens)
-
-#### Discovery Step 3: Pattern Analysis
-
-```bash
-# Existing conventions
-Glob: src/**/*.test.* OR src/**/*.spec.*  # test patterns
-Grep: src/ for error handling patterns
-Grep: src/ for auth/session patterns
-Bash: git log --oneline -20  # commit style
-
-# Architecture patterns
-Bash: ls -la src/  # top-level structure (pages, components, services, etc.)
-Glob: src/**/index.{ts,tsx,js}  # barrel exports
-Grep: src/ for "import.*from.*@/"  # path aliases
-```
-
-#### Discovery Step 4: Present Findings
-
-Present a structured summary to the user:
-
-*"I've scanned your codebase. Here's what I found:*
-
-*Project: {name} — {description from README or package.json}*
-*Stack: {language} + {framework} + {database}*
-*UI: {component library} with {icon set}, layout via {layout system}*
-*Testing: {test framework}, {X} existing test files*
-*Size: ~{N} source files, ~{N}K lines*
-*Patterns: {commit style}, {folder structure approach}, {key conventions}*
-
-*Does this look right? Anything I missed or got wrong?"*
-
-#### Discovery Step 5: Design System Mapping
-
-If a component library was detected:
-1. Check `.forge/templates/design-systems/` for an existing example config
-2. If found (e.g., PrimeReact) → copy it as starting point for `.forge/design-system.md`
-3. If not found → use `researching` skill to build a component mapping from docs
-4. **Cross-reference with actual usage**: scan the codebase for which components are already in use and prioritize those in the mapping
-5. Present mapping to user for validation
-
-If no component library detected but UI files exist:
-- Ask: *"I see UI code but no component library. Are you using a design system, or is this custom HTML/CSS?"*
-
-#### Discovery Step 6: Constitutional Inference
-
-Based on discovered patterns, **suggest** which articles to enable:
-
-| Discovery | Suggested Articles |
-|-----------|-------------------|
-| Test files found | Article II: Test-First (already practicing) |
-| Component library detected | Article V: Design System Fidelity |
-| Auth/session patterns found | Article VI: Security by Default |
-| Established conventions detected | Article IV: Consistency (preserve them) |
-| package-lock.json or yarn.lock | Article I: Library-First (already using libraries) |
-| Logging/monitoring deps | Article IX: Observability |
-
-Present grouped recommendations and let user confirm, add, or remove articles.
-
----
-
-### Greenfield Path: Build from Description
-
-For new projects, ask the user to describe what they're building.
-
-#### Greenfield Step 1: Project Basics
-
-Ask the user to describe the project. From their description, fill in `.forge/project.yml`:
-
-- Project name and description
-- Primary goal
-- Tech stack (language, framework, database, testing)
-- Time and scope constraints
-- Success criteria
-- Known risks
-
-Present a summary: *"Does this capture your project correctly? Anything to add or change?"*
-
-#### Greenfield Step 2: Design System Setup
-
-Ask: *"Does this project use a UI component library or design system?"*
-
-**If yes**, ask which one and configure `design_system` in `project.yml`:
-
-```yaml
-design_system:
-  library: ""           # e.g., PrimeReact, Material-UI, shadcn/ui, Ant Design, Chakra UI
-  version: ""           # e.g., 10.x, 5.x
-  icon_set: ""          # e.g., PrimeIcons, Material Icons, Lucide, none
-  layout_system: ""     # e.g., PrimeFlex, MUI Grid, Tailwind, CSS Grid
-  theme_approach: ""    # e.g., SCSS variables, CSS-in-JS, Tailwind config, design tokens
-  docs_url: ""          # e.g., https://primereact.org/datatable/
-```
-
-Then:
-1. Check `.forge/templates/design-systems/` for a starter config
-2. If found → copy and customize for the project
-3. If not → use `researching` skill to build a component mapping from docs
-4. Write the mapping to `.forge/design-system.md`
-
-**If no** (plain HTML/CSS, utility-only, or non-UI project):
-- Set `design_system.library: none` in project.yml
-- Skip design-system.md creation
-- Disable Article V in the constitution
-
-#### Greenfield Step 3: Constitutional Setup
-
-Present the 9 constitutional articles grouped by domain:
-
-**Code quality** (recommended for most projects):
-- Article I: Library-First — prefer proven libraries over custom code
-- Article II: Test-First — tests before or alongside implementation
-- Article III: Simplicity — simplest solution wins
-- Article IV: Consistency — follow existing project patterns
-
-**Design & UI** (enable if project has UI):
-- Article V: Design System Fidelity — use the design system, don't fight it
-
-**Security & data** (enable if auth, user data, or APIs involved):
-- Article VI: Security by Default — auth, validation, secrets are requirements
-
-**Architecture** (enable based on project complexity):
-- Article VII: Integration-First — real dependencies before mocks
-- Article VIII: Documentation-Driven — decisions documented where code lives
-- Article IX: Observability — logging, error reporting, health checks
-
-Ask: *"Which of these articles apply? I'd recommend [suggest based on stack and project type]. You can also add project-specific articles."*
-
----
-
-### Finalize Init (Both Paths)
-
-1. Write `.forge/project.yml` with all gathered/discovered info
-2. Write `.forge/constitution.md` with selected articles
-3. Write `.forge/design-system.md` (if design system configured)
-4. Initialize milestone-aware state:
-   - Create `.forge/state/` directory
-   - Write `.forge/state/index.yml`:
-     ```yaml
-     milestones:
-       - id: 1
-         name: "{project name}"
-         status: active
-         last_updated: "{date}"
-     ```
-   - Write `.forge/state/milestone-1.yml`:
-     ```yaml
-     milestone:
-       id: 1
-       name: "{project name}"
-     current:
-       tier: null
-       phase: null
-       phase_name: ""
-       plan: null
-       task: null
-       status: not_started
-     ```
-5. Copy remaining templates as needed
-
-Confirm: *"Project initialized. Here's what's set up: [summary]. Ready to start working?"*
+If no `.forge/project.yml` exists, invoke the `initializing` skill via `Skill(initializing)`. It handles brownfield/greenfield detection, framework absorption, tech stack scanning, design system setup, and constitutional configuration. After init completes, return here for tier detection.
 
 ## Step 2B: Detect Tier
 
@@ -502,9 +115,23 @@ Based on detected tier and current state, tell the user which skill comes next a
 
 **CRITICAL: NEVER use `EnterPlanMode` or Claude Code's native plan mode.** All Forge phases are handled by Forge skills invoked via the `Skill` tool. When the workflow says "planning", that means invoke `Skill(planning)` — not enter native plan mode. Native plan mode writes to a different file format and bypasses Forge's constitutional gates, state management, and structured plan output.
 
-If resuming mid-workflow:
-- Read the selected milestone's state file (`.forge/state/milestone-{id}.yml`) for current position
-- **Use `current.status` to determine the next skill** — this is the authoritative workflow position:
+### Mandatory Auto-Routing on Resume
+
+**When resuming mid-workflow, DO NOT present a menu of options or ask "What would you like to do?".** Routing is deterministic. Give a brief status briefing, then route automatically. The only time to ask the user for a choice is when `current.status == complete` (milestone done) or when state is ambiguous/corrupted.
+
+Resume steps:
+1. Read the selected milestone's state file (`.forge/state/milestone-{id}.yml`) for current position
+2. **Check for status advancement** (see below)
+3. **Use `current.status` to determine the next skill** — this is the authoritative workflow position
+4. **Brief the user, then route.** Show a compact status summary so the user can orient, then immediately invoke the next skill. Format:
+
+*"Resuming Milestone {id}: {name}*
+*Workflow: {current.status} — next step: {next skill name}*
+*Phases: {compact phase list with statuses using correct wording — Executed/Verified/Pending/In progress}*
+*Progress: {overall_percent}% of tasks executed*
+*Routing to {skill}..."*
+
+This is a **briefing, not a prompt** — the user sees where they are and what's happening next. They can interrupt if they want to do something different, but the default is forward motion.
 
 | `current.status` | Next Action (invoke via `Skill` tool) |
 |-------------------|-------------|
@@ -522,6 +149,27 @@ If resuming mid-workflow:
 - Skip completed phases (phases before `current.status`)
 - Resume from current phase
 
+### Status Advancement Check
+
+Sometimes a session ends before the executing skill advances `current.status`. On resume, detect and fix this:
+
+- **If `current.status == executing`**: Check if all phases in the roadmap have been executed (all plans completed, commits made). If YES → advance `current.status` to `verifying` in the state file, then route to verifying. If NO → route to executing for the next unexecuted phase.
+- **If `current.status == verifying`**: Check if verification report exists. If YES and it passed → advance to `auditing`. If NO → route to verifying.
+- **General rule**: If the work for the current status is done but the status wasn't advanced (session ended mid-handoff), advance it now and route to the next skill.
+
+### Phase Status Wording
+
+When reporting phase progress on resume, use precise terminology to avoid confusion:
+
+| Phase State | Display As | Meaning |
+|------------|-----------|---------|
+| All tasks executed, commits made | **"Executed"** | Code is written and committed, but NOT yet verified |
+| Verified by verifying skill | **"Verified"** | Passed goal-backward verification |
+| Not yet started | **"Pending"** | No work done yet |
+| Currently in progress | **"In progress"** | Partially executed |
+
+**Never say a phase is "Complete" unless it has passed through the full workflow** (executed + verified + audited). Use "Executed" for phases where code is done but verification hasn't run. This prevents users from thinking a phase is fully done when it still needs verification.
+
 ### On-Demand Discussion
 
 The `discussing` skill can be invoked at any time, regardless of current workflow position. If the user says "discuss Phase 2", "let's talk through the plan", "I want to rethink this", or similar — route to `discussing` immediately. After the discussion concludes, return to whatever skill was active (or re-plan if the discussion changed direction).

package/template/.claude/skills/initializing/SKILL.md

@@ -0,0 +1,475 @@
+---
+name: initializing
+description: "Run once per project to detect brownfield/greenfield, scan tech stack, absorb existing frameworks, configure design system, and set up constitutional gates. Invoked by the forge skill when no .forge/project.yml exists."
+---
+
+# Initializing: Project Setup
+
+This interactive workflow runs once when Forge doesn't find an existing project (no `.forge/project.yml`). First, detect whether this is a **brownfield** (existing codebase) or **greenfield** (new project) — then run the appropriate init path.
+
+## Detect Project Type
+
+Check for signals of an existing codebase:
+
+```
+Check: package.json OR requirements.txt OR go.mod OR Cargo.toml (dependency manifest)
+Check: .git/ (version control history)
+Check: src/ OR app/ OR lib/ (source directories)
+Check: existing config files (tsconfig.json, .eslintrc, vite.config, etc.)
+```
+
+- **2+ signals found** → **Brownfield path** (existing codebase)
+- **0-1 signals** → **Greenfield path** (new project)
+
+Ask user to confirm: *"This looks like an [existing project / new project]. Is that right?"*
+
+---
+
+## Brownfield Path: Discover Existing Project
+
+For existing codebases, **scan first, confirm with user second.** Don't ask the user to describe what you can discover.
+
+### Discovery Step 0: Framework Detection
+
+Before scanning the tech stack, check for two things: (1) existing meta-prompting frameworks with project knowledge to absorb, and (2) companion tools that should be preserved alongside Forge.
+
+**Meta-Framework Signatures** (contain project knowledge — candidates for absorption):
+
+```
+# GSD (Get Shit Done)
+Check: agents/gsd-*.md OR commands/gsd/ directory
+Check: Root-level PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md
+Check: get-shit-done/ directory
+Check: CONTEXT.md with "NON-NEGOTIABLE" or "DEFERRED" sections
+
+# Spec-Kit
+Check: spec-driven.md
+Check: templates/ with spec-template.md
+Check: extensions/catalog.json
+Check: constitution-template.md
+
+# BMAD
+Check: agents/ with 20+ agent files
+Check: workflows/ directory
+Check: bmad-* prefixed files
+
+# Generic / Unknown
+Check: .claude/agents/ or .claude/skills/ (someone else's custom framework)
+Check: CLAUDE.md with framework-like routing tables
+Check: Any structured agent/workflow system
+```
+
+**Companion Tool Signatures** (not frameworks — independent tools that work alongside Forge):
+
+```
+# Beads (persistent cross-session memory)
+Check: .beads/ directory
+Check: beads.jsonl or beads.db
+Check: bd CLI available (Bash: which bd)
+→ If found: Enable forge.beads_integration in settings.json. Do NOT absorb or archive.
+→ Beads is independent — it runs alongside Forge, not inside it.
+```
+
+**If a meta-framework is detected**, present the finding and offer three options:
+
+*"I found an existing [{framework name}] setup in this project. It contains project documentation and decisions that are valuable. How would you like to handle it?"*
+
+**Option A: Absorb & Convert** (recommended)
+Read all existing framework documentation, extract the project knowledge, and convert it into Forge's format. This means:
+- Project descriptions → `.forge/project.yml`
+- Requirements → `.forge/requirements.yml`
+- Roadmaps/plans → `.forge/roadmap.yml`
+- Context/decisions → `.forge/context.md`
+- Current state/progress → `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml`
+- Constitutional rules (if any) → `.forge/constitution.md`
+- Design system rules (if any) → `.forge/design-system.md`
+
+→ Go to **Framework Absorption** below.
+
+**Option B: Archive & Start Fresh**
+Move existing framework files into `.forge/archive/{framework-name}/` for reference, then run the standard brownfield discovery (which will still scan the codebase itself). The archive is preserved and can be consulted later.
+
+**Option C: Keep Both (Transition Period)**
+Initialize Forge alongside the existing framework. Forge reads from `.forge/` while old framework files remain in place. Useful when you want to try Forge without committing. Remove the old framework later when confident.
+
+---
+
+### Framework Absorption (Option A)
+
+When absorbing an existing framework, read its documentation and convert systematically.
+
+**GSD Absorption Map:**
+
+| GSD Source | Read | Extract | Write to Forge |
+|-----------|------|---------|---------------|
+| `PROJECT.md` | Project name, description, tech stack, goals | Structured project info | `.forge/project.yml` |
+| `REQUIREMENTS.md` | Feature requirements, acceptance criteria | Convert prose to YAML with IDs | `.forge/requirements.yml` |
+| `ROADMAP.md` | Phases, milestones, dependencies | Convert to YAML with dependency refs | `.forge/roadmap.yml` |
+| `STATE.md` | Current phase, progress, blockers | Machine-readable state | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
+| `CONTEXT.md` | NON-NEGOTIABLE decisions, DEFERRED ideas | Locked decisions, deferred items | `.forge/context.md` |
+| `references/ui-brand.md` | Design system rules, brand guidelines | Component mappings, style rules | `.forge/design-system.md` |
+| `references/verification-patterns.md` | Verification approach | Inform `verifying` skill config | Constitution articles |
+| `references/tdd.md` | Testing approach | Inform constitution Article II | Constitution articles |
+| Agent customizations | Custom agent behaviors, tool restrictions | Map to Forge agent definitions | `.claude/agents/*.md` (if custom) |
+
+**Spec-Kit Absorption Map:**
+
+| Spec-Kit Source | Read | Extract | Write to Forge |
+|----------------|------|---------|---------------|
+| `spec-driven.md` | Core methodology | Governance patterns | `.forge/constitution.md` |
+| `templates/spec-template.md` | Spec structure | Requirements format | `.forge/requirements.yml` |
+| `templates/constitution-template.md` | Constitutional articles | Immutable gates | `.forge/constitution.md` |
+| `extensions/` | Extension configs | Specialized skills | `.claude/skills/` (if relevant) |
+| Project specs (if filled in) | Project-specific decisions | Locked decisions | `.forge/context.md` |
+
+**Generic Framework Absorption:**
+
+For unknown frameworks, use the `researching` skill to:
+1. Read all markdown and config files in the framework directory
+2. Identify: project descriptions, requirements, decisions, state, design rules
+3. Map each to the closest Forge equivalent
+4. Present the mapping to the user for confirmation before writing
+
+**Absorption Process:**
+
+1. Read all source files from the existing framework
+2. For each Forge target file, synthesize content from the relevant sources
+3. Convert prose to YAML where Forge expects YAML (project, requirements, roadmap, state)
+4. Preserve markdown where Forge expects markdown (constitution, context, design-system)
+5. **Never discard information** — if something doesn't map to a Forge file, note it in `.forge/context.md` under a "Carried Forward" section
+6. Move original framework files to `.forge/archive/{framework-name}/`
+7. Present a diff-style summary: *"Here's what I converted: [list]. And here's what I archived for reference: [list]. Anything I should handle differently?"*
+
+After absorption, **always** continue with the standard brownfield steps below (tech stack scan, design system detection, etc.). This is critical — see the verification step next.
+
+### Documentation vs. Codebase Verification
+
+**Never trust framework documentation at face value.** Documentation drifts. The codebase is the source of truth.
+
+After reading existing framework docs, **cross-reference every claim against the actual code**:
+
+```
+For each claim in the documentation:
+  1. Find the corresponding code (Glob, Grep, Read)
+  2. Verify the claim matches reality
+  3. Flag any discrepancies
+```
+
+**Common drift patterns to check:**
+
+| Documentation Says | Verify Against |
+|-------------------|----------------|
+| "Tech stack: React + PostgreSQL" | `package.json` dependencies, actual imports in `src/` |
+| "Uses PrimeReact for all UI" | `Grep: src/ for "from 'primereact"` — are there also raw HTML tables, custom modals? |
+| "Tests written for all features" | `Glob: src/**/*.test.*` — actual coverage vs. claimed coverage |
+| "Auth uses Clerk/Auth0/etc." | `Grep: src/ for auth imports` — is there also custom auth code? |
+| "State management via Redux" | `package.json` + actual imports — did they switch to Zustand mid-project? |
+| "API uses REST" | `Grep: src/ for GraphQL, tRPC, WebSocket` — mixed protocols? |
+| Requirements list features A, B, C | Do routes/components for A, B, C actually exist? Are any partially implemented? |
+| Roadmap says "Phase 2 complete" | Are Phase 2 features actually wired and working, or are there stubs? |
+
+**When discrepancies are found:**
+
+Present them to the user clearly:
+
+*"I found some differences between the GSD documentation and the actual codebase:*
+
+- *PROJECT.md says 'PostgreSQL' but I only see SQLite in dependencies*
+- *REQUIREMENTS.md lists a 'notifications' feature but I can't find any notification code*
+- *STATE.md says Phase 2 is complete, but the dashboard component looks like a stub (returns placeholder text)*
+- *The docs mention PrimeReact exclusively, but I found 3 files using raw HTML tables instead of DataTable*
+
+*Should I update the Forge config to match what's actually in the code, or are some of these features that were removed/deferred?"*
+
+**Priority order for truth:**
+1. **What the code actually does** — highest authority
+2. **What the user confirms** — resolves ambiguity
+3. **What the documentation says** — useful context, but may be stale
+
+Write the verified state to Forge files. For any unresolved discrepancies, add them to `.forge/context.md` under a "Needs Resolution" section so they get addressed during planning.
+
+---
+
+### Discovery Step 1: Tech Stack Scan
+
+```bash
+# Package manifest
+Read: package.json → name, dependencies, devDependencies, scripts
+# Or: requirements.txt, go.mod, Cargo.toml, etc.
+
+# Config files
+Glob: tsconfig.json, .eslintrc*, vite.config.*, next.config.*, webpack.config.*
+Glob: .env.example, docker-compose.yml
+
+# Source structure
+Bash: find src/ -type f | head -50  # understand file organization
+Bash: wc -l src/**/*.{ts,tsx,js,jsx} 2>/dev/null | tail -1  # codebase size
+```
+
+From this, auto-detect:
+- Language and framework
+- Build tools and test framework
+- Database (from dependencies or config)
+- Project name and description (from package.json or README)
+
+### Discovery Step 1.5: Verification Command Detection
+
+Auto-detect verification commands from the project's package manifest and config:
+
+```bash
+# Node.js projects — scan package.json scripts
+Read: package.json → scripts
+
+# Look for these common script names:
+#   test, test:unit, test:integration, test:e2e
+#   lint, lint:fix, eslint
+#   typecheck, type-check, tsc, check-types
+#   check (often runs multiple checks)
+#   build (catches type errors in compiled languages)
+
+# Python projects
+Check: Makefile, tox.ini, pyproject.toml for test/lint commands
+# e.g., pytest, ruff check, mypy
+
+# Go projects
+# Standard: go test ./..., go vet ./...
+
+# Rust projects
+# Standard: cargo test, cargo clippy
+```
+
+**Auto-detection rules for Node.js (most common):**
+
+| `package.json` script | Maps to verification command |
+|----------------------|------------------------------|
+| `test` or `test:unit` | `npm test` or `npm run test:unit` |
+| `lint` | `npm run lint` |
+| `typecheck` or `type-check` or `check-types` | `npm run typecheck` (etc.) |
+| `tsc` in scripts or `typescript` in devDeps | `npx tsc --noEmit` |
+| `eslint` in devDeps but no `lint` script | `npx eslint .` |
+
+**Advisory mode detection:** After identifying commands, run each one once silently to check baseline health. Commands that fail on the current codebase (before Forge changes anything) are marked `advisory: true` — they'll run but won't block execution. This prevents Forge from being blocked by pre-existing tech debt.
+
+```yaml
+# Example auto-detected config:
+verification:
+  commands:
+    - cmd: "npm run lint"
+      advisory: false        # passes on current codebase
+    - cmd: "npm test"
+      advisory: false        # passes on current codebase
+    - cmd: "npx tsc --noEmit"
+      advisory: true         # FAILED on current codebase — pre-existing type errors
+  auto_fix: true
+  max_retries: 2
+```
+
+Present findings to user:
+
+*"I detected these verification commands from your project:*
+- *`npm run lint` — passes currently*
+- *`npm test` — passes currently*
+- *`npx tsc --noEmit` — currently failing (pre-existing type errors, will run in advisory mode)*
+
+*These will run automatically after each task to catch regressions. Want to add, remove, or adjust any?"*
+
+### Discovery Step 2: Design System Detection
+
+```bash
+# Check dependencies for known UI libraries
+Grep: package.json for: primereact, @mui/, @chakra-ui/, @radix-ui/, antd, @headlessui/
+Grep: package.json for: tailwindcss, primeflex, @emotion/, styled-components
+
+# Check actual usage in source
+Grep: src/ for import patterns: "from 'primereact", "from '@mui/", "from '@/components/ui"
+Grep: src/ for icon usage: "pi pi-", "Material", "lucide-react"
+
+# Check for theme files
+Glob: **/*theme*, **/*variables.scss, **/tailwind.config*, **/globals.css
+```
+
+From this, auto-detect:
+- Component library (and version from package.json)
+- Icon set in use
+- Layout system (PrimeFlex, Tailwind, MUI Grid, etc.)
+- Theme approach (SCSS variables, CSS-in-JS, Tailwind config, design tokens)
+
+### Discovery Step 3: Pattern Analysis
+
+```bash
+# Existing conventions
+Glob: src/**/*.test.* OR src/**/*.spec.*  # test patterns
+Grep: src/ for error handling patterns
+Grep: src/ for auth/session patterns
+Bash: git log --oneline -20  # commit style
+
+# Architecture patterns
+Bash: ls -la src/  # top-level structure (pages, components, services, etc.)
+Glob: src/**/index.{ts,tsx,js}  # barrel exports
+Grep: src/ for "import.*from.*@/"  # path aliases
+```
+
+### Discovery Step 4: Present Findings
+
+Present a structured summary to the user:
+
+*"I've scanned your codebase. Here's what I found:*
+
+*Project: {name} — {description from README or package.json}*
+*Stack: {language} + {framework} + {database}*
+*UI: {component library} with {icon set}, layout via {layout system}*
+*Testing: {test framework}, {X} existing test files*
+*Size: ~{N} source files, ~{N}K lines*
+*Patterns: {commit style}, {folder structure approach}, {key conventions}*
+
+*Does this look right? Anything I missed or got wrong?"*
+
+### Discovery Step 5: Design System Mapping
+
+If a component library was detected:
+1. Check `.forge/templates/design-systems/` for an existing example config
+2. If found (e.g., PrimeReact) → copy it as starting point for `.forge/design-system.md`
+3. If not found → use `researching` skill to build a component mapping from docs
+4. **Cross-reference with actual usage**: scan the codebase for which components are already in use and prioritize those in the mapping
+5. Present mapping to user for validation
+
+If no component library detected but UI files exist:
+- Ask: *"I see UI code but no component library. Are you using a design system, or is this custom HTML/CSS?"*
+
+### Discovery Step 6: Constitutional Inference
+
+Based on discovered patterns, **suggest** which articles to enable:
+
+| Discovery | Suggested Articles |
+|-----------|-------------------|
+| Test files found | Article II: Test-First (already practicing) |
+| Component library detected | Article V: Design System Fidelity |
+| Auth/session patterns found | Article VI: Security by Default |
+| Established conventions detected | Article IV: Consistency (preserve them) |
+| package-lock.json or yarn.lock | Article I: Library-First (already using libraries) |
+| Logging/monitoring deps | Article IX: Observability |
+
+Present grouped recommendations and let user confirm, add, or remove articles.
+
+---
+
+## Greenfield Path: Build from Description
+
+For new projects, ask the user to describe what they're building.
+
+### Greenfield Step 1: Project Basics
+
+Ask the user to describe the project. From their description, fill in `.forge/project.yml`:
+
+- Project name and description
+- Primary goal
+- Tech stack (language, framework, database, testing)
+- Time and scope constraints
+- Success criteria
+- Known risks
+
+Present a summary: *"Does this capture your project correctly? Anything to add or change?"*
+
+### Greenfield Step 2: Design System Setup
+
+Ask: *"Does this project use a UI component library or design system?"*
+
+**If yes**, ask which one and configure `design_system` in `project.yml`:
+
+```yaml
+design_system:
+  library: ""           # e.g., PrimeReact, Material-UI, shadcn/ui, Ant Design, Chakra UI
+  version: ""           # e.g., 10.x, 5.x
+  icon_set: ""          # e.g., PrimeIcons, Material Icons, Lucide, none
+  layout_system: ""     # e.g., PrimeFlex, MUI Grid, Tailwind, CSS Grid
+  theme_approach: ""    # e.g., SCSS variables, CSS-in-JS, Tailwind config, design tokens
+  docs_url: ""          # e.g., https://primereact.org/datatable/
+```
+
+Then:
+1. Check `.forge/templates/design-systems/` for a starter config
+2. If found → copy and customize for the project
+3. If not → use `researching` skill to build a component mapping from docs
+4. Write the mapping to `.forge/design-system.md`
+
+**If no** (plain HTML/CSS, utility-only, or non-UI project):
+- Set `design_system.library: none` in project.yml
+- Skip design-system.md creation
+- Disable Article V in the constitution
+
+### Greenfield Step 2.5: Verification Commands
+
+Ask: *"What verification commands should run after each task? Common options:"*
+
+| If your stack includes... | Suggested commands |
+|--------------------------|-------------------|
+| TypeScript | `npx tsc --noEmit` |
+| ESLint / Biome | `npm run lint` |
+| Jest / Vitest / Mocha | `npm test` |
+| Python + pytest | `pytest` |
+| Python + ruff | `ruff check .` |
+| Go | `go test ./...`, `go vet ./...` |
+| Rust | `cargo test`, `cargo clippy` |
+
+Pre-fill based on the tech stack chosen in Step 1. User confirms or adjusts. Write to the `verification` section of `project.yml`.
+
+If the user doesn't want verification gates: set `verification.commands: []` — the executing skill will skip the gate entirely.
+
+### Greenfield Step 3: Constitutional Setup
+
+Present the 9 constitutional articles grouped by domain:
+
+**Code quality** (recommended for most projects):
+- Article I: Library-First — prefer proven libraries over custom code
+- Article II: Test-First — tests before or alongside implementation
+- Article III: Simplicity — simplest solution wins
+- Article IV: Consistency — follow existing project patterns
+
+**Design & UI** (enable if project has UI):
+- Article V: Design System Fidelity — use the design system, don't fight it
+
+**Security & data** (enable if auth, user data, or APIs involved):
+- Article VI: Security by Default — auth, validation, secrets are requirements
+
+**Architecture** (enable based on project complexity):
+- Article VII: Integration-First — real dependencies before mocks
+- Article VIII: Documentation-Driven — decisions documented where code lives
+- Article IX: Observability — logging, error reporting, health checks
+
+Ask: *"Which of these articles apply? I'd recommend [suggest based on stack and project type]. You can also add project-specific articles."*
+
+---
+
+## Finalize Init (Both Paths)
+
+1. Write `.forge/project.yml` with all gathered/discovered info (including `verification` section with detected/configured commands)
+2. Write `.forge/constitution.md` with selected articles
+3. Write `.forge/design-system.md` (if design system configured)
+4. Initialize milestone-aware state:
+   - Create `.forge/state/` directory
+   - Write `.forge/state/index.yml`:
+     ```yaml
+     milestones:
+       - id: 1
+         name: "{project name}"
+         status: active
+         last_updated: "{date}"
+     ```
+   - Write `.forge/state/milestone-1.yml`:
+     ```yaml
+     milestone:
+       id: 1
+       name: "{project name}"
+     current:
+       tier: null
+       phase: null
+       phase_name: ""
+       plan: null
+       task: null
+       status: not_started
+     ```
+5. Copy remaining templates as needed
+
+Confirm: *"Project initialized. Here's what's set up: [summary]. Ready to start working?"*
+
+After init completes, return control to the `forge` skill for tier detection and routing.

package/template/.forge/templates/project.yml

@@ -30,6 +30,17 @@ constraints:
     - ""                            # e.g., "No custom auth — use Clerk"
     - ""                            # e.g., "No server-side rendering"
 
+verification:
+  commands:                           # Shell commands run after each task commit
+    - ""                              # e.g., "npm run lint"
+    - ""                              # e.g., "npm test"
+    - ""                              # e.g., "npx tsc --noEmit"
+  auto_fix: true                      # On failure, agent fixes and retries
+  max_retries: 2                      # Max auto-fix attempts per command (0 = fail immediately)
+  # Commands are auto-detected during init from package.json scripts.
+  # Advisory mode: commands that were already failing before Forge started
+  # run but don't block — they log warnings only.
+
 success_criteria:                   # How do we know we're done?
   - ""                              # e.g., "User can create and edit posts"
   - ""                              # e.g., "All tests pass with >80% coverage"

package/template/CLAUDE.md

@@ -41,6 +41,7 @@ Forge auto-detects complexity. Override with: "Use Quick/Standard/Full tier."
 | When you need to... | Use skill | Tier |
 |---------------------|-----------|------|
 | Start any task (entry point) | `forge` | All |
+| Set up a new project (brownfield or greenfield) | `initializing` | First run only |
 | Investigate codebase, tech, or requirements | `researching` | Standard, Full |
 | Talk through approach, trade-offs, or revisit a plan | `discussing` | Standard, Full (also on-demand) |
 | Make architectural decisions with rationale | `architecting` | Full |
@@ -114,7 +115,7 @@ For Quick tier tasks, init is skipped — just do the work.
 ## State Management
 
 Project state lives in `.forge/`:
-- `project.yml` — Vision, stack, design system, constraints (< 5 KB)
+- `project.yml` — Vision, stack, design system, verification commands, constraints (< 5 KB)
 - `constitution.md` — Active architectural gates (selected during init)
 - `design-system.md` — Component mapping table (generated during init)
 - `requirements.yml` — Structured requirements with `[NEEDS CLARIFICATION]` markers
@@ -145,6 +146,27 @@ When the executor encounters issues during building:
 
 Priority: Rule 4 first (stop if architectural). Then Rules 1-3 (auto-fix). Uncertain? → Rule 4 (ask).
 
+## Verification Gates
+
+After each task commit, the executor runs configured verification commands from `project.yml`:
+
+```yaml
+verification:
+  commands:
+    - cmd: "npm run lint"
+    - cmd: "npm test"
+    - cmd: "npx tsc --noEmit"
+      advisory: true           # pre-existing failures — warn only
+  auto_fix: true               # agent fixes and retries on failure
+  max_retries: 2               # max auto-fix attempts per command
+```
+
+- **Auto-detected during init** from `package.json` scripts (test, lint, typecheck)
+- **Advisory mode**: commands that were already failing before Forge started run but don't block
+- **Auto-fix loop**: on failure, agent reads output, fixes code, amends commit, re-runs (up to max_retries)
+- **3-strike integration**: verification retries count toward the task's 3-strike limit
+- Empty `commands` list = no verification gate (opt-out)
+
 ## Beads Integration (Optional)
 
 When Beads is installed, Forge gains persistent cross-session memory: