forge-orkes 0.3.9 → 0.3.11

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

@@ -5,11 +5,11 @@ description: "Run once per project to detect brownfield/greenfield, scan tech st
 
 # 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.
+Runs once when no `.forge/project.yml` exists. Detect **brownfield** vs **greenfield**, then run the matching init path.
 
 ## Detect Project Type
 
-Check for signals of an existing codebase:
+Check for existing codebase signals:
 
 ```
 Check: package.json OR requirements.txt OR go.mod OR Cargo.toml (dependency manifest)
@@ -18,22 +18,22 @@ 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)
+- **2+ signals** → **Brownfield path**
+- **0-1 signals** → **Greenfield path**
 
-Ask user to confirm: *"This looks like an [existing project / new project]. Is that right?"*
+Confirm with user: *"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.
+Scan first, confirm with user second. Don't ask 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.
+Check for: (1) meta-prompting frameworks with project knowledge to absorb, (2) companion tools to preserve.
 
-**Meta-Framework Signatures** (contain project knowledge — candidates for absorption):
+**Meta-Framework Signatures:**
 
 ```
 # GSD (Get Shit Done)
@@ -59,7 +59,7 @@ 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):
+**Companion Tool Signatures:**
 
 ```
 # Beads (persistent cross-session memory)
@@ -70,57 +70,58 @@ Check: bd CLI available (Bash: which bd)
 → Beads is independent — it runs alongside Forge, not inside it.
 ```
 
-**If a meta-framework is detected**, present the finding and offer three options:
+**If a meta-framework is detected**, 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?"*
+*"I found [{framework name}] in this project with valuable project documentation. 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`
+Read existing framework docs, extract project knowledge, convert to Forge format:
 
-→ Go to **Framework Absorption** below.
+| Source | Target |
+|--------|--------|
+| Project descriptions | `.forge/project.yml` |
+| Requirements | `.forge/requirements.yml` |
+| Roadmaps/plans | `.forge/roadmap.yml` |
+| Context/decisions | `.forge/context.md` |
+| State/progress | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
+| Constitutional rules | `.forge/constitution.md` |
+| Design system rules | `.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.
+Move framework files to `.forge/archive/{framework-name}/` for reference, then run standard brownfield discovery.
 
 **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.
+Initialize Forge alongside the existing framework. 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) |
+| GSD Source | Extract | Write to Forge |
+|-----------|---------|---------------|
+| `PROJECT.md` | Project name, description, tech stack, goals | `.forge/project.yml` |
+| `REQUIREMENTS.md` | Feature requirements, acceptance criteria → YAML with IDs | `.forge/requirements.yml` |
+| `ROADMAP.md` | Phases, milestones, dependencies → YAML with refs | `.forge/roadmap.yml` |
+| `STATE.md` | Current phase, progress, blockers | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
+| `CONTEXT.md` | NON-NEGOTIABLE decisions, DEFERRED ideas | `.forge/context.md` |
+| `references/ui-brand.md` | Design system rules, brand guidelines | `.forge/design-system.md` |
+| `references/verification-patterns.md` | Verification approach | Constitution articles |
+| `references/tdd.md` | Testing approach | Constitution articles |
+| Agent customizations | Custom behaviors, tool restrictions | `.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` |
+| Spec-Kit Source | Extract | Write to Forge |
+|----------------|---------|---------------|
+| `spec-driven.md` | Governance patterns | `.forge/constitution.md` |
+| `templates/spec-template.md` | Requirements format | `.forge/requirements.yml` |
+| `templates/constitution-template.md` | Immutable gates | `.forge/constitution.md` |
+| `extensions/` | Specialized skills | `.claude/skills/` (if relevant) |
+| Project specs (if filled in) | Locked decisions | `.forge/context.md` |
 
 **Generic Framework Absorption:**
 
@@ -136,17 +137,17 @@ For unknown frameworks, use the `researching` skill to:
 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?"*
+5. If something doesn't map to a Forge file, note it in `.forge/context.md` under "Carried Forward"
+6. Move originals to `.forge/archive/{framework-name}/`
+7. Present a diff-style summary: *"Here's what I converted: [list]. Archived for reference: [list]. Anything to 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.
+After absorption, **always** continue with the standard brownfield steps below — 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.
+**Never trust framework documentation at face value.** The codebase is the source of truth.
 
-After reading existing framework docs, **cross-reference every claim against the actual code**:
+After reading framework docs, cross-reference every claim against actual code:
 
 ```
 For each claim in the documentation:
@@ -155,38 +156,24 @@ For each claim in the documentation:
   3. Flag any discrepancies
 ```
 
-**Common drift patterns to check:**
+**Common drift patterns:**
 
 | 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? |
+| "Tech stack: React + PostgreSQL" | `package.json` deps, actual imports in `src/` |
+| "Uses PrimeReact for all UI" | `Grep: src/ for "from 'primereact"` — any raw HTML tables, custom modals? |
+| "Tests written for all features" | `Glob: src/**/*.test.*` — actual vs. claimed coverage |
+| "Auth uses Clerk/Auth0/etc." | `Grep: src/ for auth imports` — custom auth code too? |
+| "State management via Redux" | `package.json` + imports — switched 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:
+| Requirements list features A, B, C | Do routes/components for A, B, C exist? Partially implemented? |
+| Roadmap says "Phase 2 complete" | Are Phase 2 features wired and working, or stubs? |
 
-*"I found some differences between the GSD documentation and the actual codebase:*
+**When discrepancies are found**, present them clearly and ask whether Forge config should match the code or whether features were removed/deferred.
 
-- *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*
+**Truth priority:** (1) What the code does, (2) What the user confirms, (3) What the docs say.
 
-*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.
+Write verified state to Forge files. Unresolved discrepancies go in `.forge/context.md` under "Needs Resolution".
 
 ---
 
@@ -206,11 +193,7 @@ 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)
+Auto-detect: language, framework, build tools, test framework, database, project name/description.
 
 ### Discovery Step 1.5: Verification Command Detection
 
@@ -220,35 +203,28 @@ Auto-detect verification commands from the project's package manifest and config
 # 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)
+# Look for: test, test:unit, test:integration, test:e2e,
+#   lint, lint:fix, eslint, typecheck, type-check, tsc,
+#   check-types, check, build
 
 # 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
+# Go projects — go test ./..., go vet ./...
+# Rust projects — cargo test, cargo clippy
 ```
 
-**Auto-detection rules for Node.js (most common):**
+**Node.js auto-detection rules:**
 
-| `package.json` script | Maps to verification command |
-|----------------------|------------------------------|
+| `package.json` script | 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.) |
+| `typecheck` / `type-check` / `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.
+**Advisory mode detection:** Run each command once to check baseline health. Commands that fail on the current codebase (before Forge changes anything) get `advisory: true` — they run but don't block. This prevents pre-existing tech debt from blocking execution.
 
 ```yaml
 # Example auto-detected config:
@@ -264,14 +240,7 @@ verification:
   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?"*
+Present findings to user with pass/fail status and advisory flags. Ask if they want to add, remove, or adjust commands.
 
 ### Discovery Step 2: Design System Detection
 
@@ -288,11 +257,7 @@ Grep: src/ for icon usage: "pi pi-", "Material", "lucide-react"
 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)
+Auto-detect: component library (+ version), icon set, layout system, theme approach.
 
 ### Discovery Step 3: Pattern Analysis
 
@@ -304,59 +269,54 @@ 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.)
+Bash: ls -la src/  # top-level structure
 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:*
+Present a structured summary:
 
-*Project: {name} — {description from README or package.json}*
+*"Project: {name} — {description}*
 *Stack: {language} + {framework} + {database}*
 *UI: {component library} with {icon set}, layout via {layout system}*
-*Testing: {test framework}, {X} existing test files*
+*Testing: {test framework}, {X} test files*
 *Size: ~{N} source files, ~{N}K lines*
-*Patterns: {commit style}, {folder structure approach}, {key conventions}*
+*Patterns: {commit style}, {folder structure}, {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
+1. Check `.forge/templates/design-systems/` for a starter config
+2. If found → copy as starting point for `.forge/design-system.md`
+3. If not → use `researching` skill to build a component mapping from docs
+4. Cross-reference with actual usage: scan for which components are already used
 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?"*
+If no library detected but UI files exist, ask: *"I see UI code but no component library. Are you using a design system, or custom HTML/CSS?"*
 
 ### Discovery Step 6: Constitutional Inference
 
-Based on discovered patterns, **suggest** which articles to enable:
+Suggest articles based on discovered patterns:
 
 | Discovery | Suggested Articles |
 |-----------|-------------------|
-| Test files found | Article II: Test-First (already practicing) |
+| Test files found | Article II: Test-First |
 | 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) |
+| Established conventions detected | Article IV: Consistency |
+| package-lock.json or yarn.lock | Article I: Library-First |
 | Logging/monitoring deps | Article IX: Observability |
 
-Present grouped recommendations and let user confirm, add, or remove articles.
+Present grouped recommendations. User confirms, adds, or removes.
 
 ---
 
 ## 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`:
@@ -368,7 +328,7 @@ Ask the user to describe the project. From their description, fill in `.forge/pr
 - Success criteria
 - Known risks
 
-Present a summary: *"Does this capture your project correctly? Anything to add or change?"*
+Confirm: *"Does this capture your project correctly? Anything to add or change?"*
 
 ### Greenfield Step 2: Design System Setup
 
@@ -388,9 +348,9 @@ design_system:
 
 Then:
 1. Check `.forge/templates/design-systems/` for a starter config
-2. If found → copy and customize for the project
+2. If found → copy and customize
 3. If not → use `researching` skill to build a component mapping from docs
-4. Write the mapping to `.forge/design-system.md`
+4. Write 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
@@ -399,10 +359,10 @@ Then:
 
 ### Greenfield Step 2.5: Verification Commands
 
-Ask: *"What verification commands should run after each task? Common options:"*
+Ask: *"What verification commands should run after each task?"*
 
-| If your stack includes... | Suggested commands |
-|--------------------------|-------------------|
+| Stack | Suggested commands |
+|-------|-------------------|
 | TypeScript | `npx tsc --noEmit` |
 | ESLint / Biome | `npm run lint` |
 | Jest / Vitest / Mocha | `npm test` |
@@ -411,13 +371,13 @@ Ask: *"What verification commands should run after each task? Common options:"*
 | 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`.
+Pre-fill based on the chosen tech stack. 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.
+If the user doesn't want verification gates: set `verification.commands: []`.
 
 ### Greenfield Step 3: Constitutional Setup
 
-Present the 9 constitutional articles grouped by domain:
+Present the 9 articles grouped by domain:
 
 **Code quality** (recommended for most projects):
 - Article I: Library-First — prefer proven libraries over custom code
@@ -425,24 +385,24 @@ Present the 9 constitutional articles grouped by domain:
 - Article III: Simplicity — simplest solution wins
 - Article IV: Consistency — follow existing project patterns
 
-**Design & UI** (enable if project has UI):
+**Design & UI** (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):
+**Security & data** (if auth, user data, or APIs involved):
 - Article VI: Security by Default — auth, validation, secrets are requirements
 
-**Architecture** (enable based on project complexity):
+**Architecture** (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."*
+Ask: *"Which articles apply? I'd recommend [suggest based on stack]. 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)
+1. Write `.forge/project.yml` with all gathered/discovered info (including `verification` section)
 2. Write `.forge/constitution.md` with selected articles
 3. Write `.forge/design-system.md` (if design system configured)
 4. Initialize milestone-aware state:
@@ -470,6 +430,6 @@ Ask: *"Which of these articles apply? I'd recommend [suggest based on stack and
      ```
 5. Copy remaining templates as needed
 
-Confirm: *"Project initialized. Here's what's set up: [summary]. Ready to start working?"*
+Confirm: *"Project initialized: [summary]. Ready to start working?"*
 
-After init completes, return control to the `forge` skill for tier detection and routing.
+Return control to the `forge` skill for tier detection and routing.