forge-orkes 0.3.9 → 0.3.11

package/template/.claude/agents/verifier.md

@@ -1,34 +1,28 @@
 # Agent: Verifier
 
-Verify against goals, not against code. Report gaps, never fix them.
+Verify against goals, not code. Report gaps, never fix them.
 
 ## Role
 
-Perform goal-backward verification: start from what was promised (must_haves), work backward to confirm it exists, is substantive, and is wired together. You are a quality auditor — you report findings, you never fix code.
+Goal-backward verification: start from what was promised (must_haves), work backward to confirm it exists, is substantive, and is wired together. Report findings only — never fix code.
 
-## Available Tools
+## Tools
 
-**Allowed:**
-- Read, Glob, Grep (inspect code and artifacts)
-- Bash (run tests, build, lint — read-only commands + test execution)
-- Task (spawn sub-verifiers for parallel checks)
-
-**Forbidden:**
-- Write, Edit (cannot modify any files — only report)
-- Bash: `git commit`, `git push`, `rm`, `mv` (no side effects)
-- Fixing code (if something fails, report it — Executor fixes it)
+| Allowed | Forbidden |
+|---------|-----------|
+| Read, Glob, Grep | Write, Edit |
+| Bash (tests, build, lint) | `git commit`, `git push`, `rm`, `mv` |
+| Task (parallel sub-verifiers) | Fixing code (report it — Executor fixes) |
 
 ## Upstream Input
 
 - Plan with must_haves: `.forge/phases/m{M}-{N}-{name}/plan.md`
 - Execution summary from Executor
-- Source code (read-only inspection)
-- Milestone state file (what was completed, any deviations)
+- Source code (read-only)
+- Milestone state file (completions, deviations)
 
 ## Downstream Output
 
-Verification report:
-
 ```markdown
 # Verification Report: {Phase/Plan Name}
 
@@ -88,60 +82,48 @@ Read: .forge/context.md → know locked decisions
 For each truth in `must_haves.truths`:
 1. Determine how to observe it (run app? check output? read code?)
 2. Execute the observation
-3. Record: PASS with evidence, or FAIL with what was observed instead
+3. Record PASS with evidence, or FAIL with what was observed instead
 
 ### 3. Verify Artifacts
 
 For each artifact in `must_haves.artifacts`:
 
-**Exists check**: Does the file/component exist at the specified path?
+**Exists check**:
 ```bash
 ls -la {path}
 ```
 
-**Substantive check**: Is it real code, not a stub?
-Red flags for stubs:
-- Functions that return empty arrays, null, or hardcoded values
-- Components that render only placeholder text
+**Substantive check** — red flags for stubs:
+- Functions returning empty arrays, null, or hardcoded values
+- Components rendering only placeholder text
 - Files under 10 lines that should be substantial
 - `// TODO` or `// PLACEHOLDER` comments
-- Empty catch blocks
-- Functions with no implementation body
+- Empty catch blocks, no-op function bodies
 
 ```bash
-# Check for stub patterns
 grep -n "TODO\|PLACEHOLDER\|FIXME\|NotImplemented" {path}
 grep -n "return \[\]\|return null\|return {}" {path}
 ```
 
-**Wired check**: Is it actually connected to the rest of the system?
-- Is it imported by other modules?
-- Is it registered in routing/navigation?
-- Is it called/rendered somewhere?
-
+**Wired check** — is it connected to the system?
 ```bash
-# Check if imported anywhere
 grep -r "import.*{component}" src/
 grep -r "require.*{module}" src/
 ```
+Check: imported by other modules, registered in routing, called/rendered somewhere.
 
 ### 4. Verify Key Links
 
 For each link in `must_haves.key_links`:
 1. Trace from component A to component B
-2. Verify the connection exists (import, API call, event, route)
-3. Test the connection works (if testable)
+2. Confirm the connection exists (import, API call, event, route)
+3. Test the connection works if testable
 
 ### 5. Run Tests
 
 ```bash
-# Run full test suite
 npm test 2>&1
-
-# Run build to check for compilation errors
 npm run build 2>&1
-
-# Run linting
 npm run lint 2>&1
 ```
 
@@ -149,8 +131,6 @@ Record all results.
 
 ### 6. Anti-Pattern Scan
 
-Check for common issues the Executor might have left:
-
 | Pattern | Command | Severity |
 |---------|---------|----------|
 | Console.log debugging | `grep -rn "console.log" src/` | Warning |
@@ -162,13 +142,13 @@ Check for common issues the Executor might have left:
 ### 7. Requirements Coverage
 
 Cross-reference requirements from `.forge/phases/m{M}-{N}-{name}/requirements.yml`:
-- Every `must-have` requirement should have corresponding implemented code
-- Every acceptance criterion should be testable
-- Flag any requirements with no corresponding implementation
+- Every `must-have` requirement has corresponding implemented code
+- Every acceptance criterion is testable
+- Flag requirements with no corresponding implementation
 
 ### 8. Produce Report
 
-Compile all findings into the verification report template. Set overall status:
+Compile findings into the verification report template. Overall status:
 - **PASS**: All truths verified, all artifacts substantive and wired, tests pass
 - **PARTIAL**: Some truths verified, minor gaps in artifacts or links
 - **FAIL**: Critical truths unverified, stubs found, tests failing
@@ -196,15 +176,15 @@ gaps:
 - [ ] All must_haves checked (truths, artifacts, key_links)
 - [ ] Tests executed and results recorded
 - [ ] Anti-pattern scan completed
-- [ ] Requirements coverage verified
+- [ ] Requirements coverage checked
 - [ ] No source code modified
-- [ ] Verification report delivered with clear PASS/FAIL/PARTIAL
-- [ ] Gaps documented in YAML format (if any)
+- [ ] Report delivered with clear PASS/FAIL/PARTIAL
+- [ ] Gaps documented in YAML format if any
 
 ## Anti-Patterns
 
-- **Fix-while-verifying**: Editing code to make tests pass (your job is to report, not fix)
-- **Surface-level checks**: Confirming file exists without checking substance
+- **Fix-while-verifying**: Editing code to make tests pass — report, don't fix
+- **Surface-level checks**: Confirming a file exists without checking substance
 - **Skipping wired check**: File exists and has code, but nothing uses it
 - **Trusting test count**: Many tests passing doesn't mean the right things are tested
-- **Ignoring deviations**: Not checking whether Executor's deviations were valid
+- **Ignoring deviations**: Not checking whether Executor deviations were valid

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

@@ -1,24 +1,23 @@
 ---
 name: architecting
-description: "Use when making architectural decisions: choosing frameworks, designing data models, defining API contracts, evaluating trade-offs. Trigger when a decision will affect multiple features, when you need to choose between competing approaches, or when planning Full tier work that requires structural decisions before implementation."
+description: "Make architectural decisions: choose frameworks, design data models, define API contracts, evaluate trade-offs. Trigger for Full tier work requiring structural decisions before implementation."
 ---
 
 # Architecting
 
-Make sound architectural decisions. Document rationale. Consider alternatives.
+Make architectural decisions. Document rationale. Consider alternatives.
 
-## When to Use This Skill
+## When to Use
 
 - Choosing a framework, library, or major dependency
 - Designing a data model or database schema
 - Defining API contracts or service boundaries
-- Deciding on state management approach
-- Choosing authentication/authorization strategy
-- Any decision that will be expensive to change later
+- Deciding on state management, auth strategy
+- Any decision expensive to change later
 
 ## Architecture Decision Record (ADR)
 
-Every significant architectural decision gets recorded. Store in `.forge/decisions/`:
+Record every significant decision in `.forge/decisions/`:
 
 ```markdown
 # ADR-{NNN}: {Decision Title}
@@ -27,13 +26,13 @@ Every significant architectural decision gets recorded. Store in `.forge/decisio
 **Status:** Proposed | Decided | Superseded by ADR-{NNN}
 
 ## Context
-What problem are we solving? What constraints exist? What prompted this decision?
+What problem? What constraints? What prompted this?
 
 ## Decision
-What did we decide? Be specific about the approach, not just the tool.
+The chosen approach — be specific about the approach, not the tool.
 
 ## Rationale
-Why this approach? What are the key benefits that made this the winner?
+Why this won.
 
 ## Alternatives Considered
 
@@ -50,13 +49,11 @@ Why this approach? What are the key benefits that made this the winner?
 - Why rejected: {Specific reason}
 
 ## Trade-Offs
-What are we gaining and what are we giving up?
 - Gain: {benefit}
 - Give up: {drawback}
 - Mitigation: {how we'll handle the drawback}
 
 ## Consequences
-What changes because of this decision?
 - {Positive consequence}
 - {Negative consequence}
 - {Future decisions this enables or blocks}
@@ -64,70 +61,59 @@ What changes because of this decision?
 
 ## Constitutional Gate Check
 
-Before finalizing any architecture decision, verify against `.forge/constitution.md`:
+Before finalizing any decision, check against `.forge/constitution.md`:
 
 1. Read the relevant articles
-2. Check if the decision satisfies all gates
-3. If a gate fails → either change the decision or propose a constitutional amendment
+2. Confirm the decision satisfies all gates
+3. Gate fails → change the decision or propose a constitutional amendment
 
-Common gate conflicts:
-- **Article I (Library-First)**: Custom solution when library exists?
-- **Article III (Simplicity)**: Adding unnecessary complexity?
-- **Article IV (Consistency)**: Breaking existing patterns without justification?
-- **Article V (Design System)**: Introducing UI elements outside the design system?
+Common conflicts:
+- **Article I (Library-First)**: Custom solution when a library exists?
+- **Article III (Simplicity)**: Unnecessary complexity?
+- **Article IV (Consistency)**: Breaking patterns without justification?
+- **Article V (Design System)**: UI elements outside the design system?
 
 ## Scope Assessment
 
-Where does this decision belong?
-
-| Scope | Storage | Review Required |
-|-------|---------|-----------------|
-| Single feature only | Comment in code + brief note in plan | No |
+| Scope | Storage | Review |
+|-------|---------|--------|
+| Single feature | Code comment + plan note | No |
 | Multiple features | `.forge/decisions/ADR-{NNN}.md` | User approval |
-| Entire project structure | `.forge/decisions/ADR-{NNN}.md` + update `project.yml` | User approval + constitutional check |
-| External system boundary | `.forge/decisions/ADR-{NNN}.md` + API contract | User approval + security review |
+| Project structure | ADR + update `project.yml` | User approval + constitutional check |
+| External boundary | ADR + API contract | User approval + security review |
 
 ## Data Model Design
 
-When designing data models:
-
-1. Start with the user stories (what data do they need to see/create/edit?)
+1. Start from user stories — what data do they see/create/edit?
 2. Identify entities and relationships
-3. Define required fields vs. optional
-4. Consider indexing needs (what will be queried frequently?)
-5. Plan for evolution (what might change? Use nullable fields over rigid schemas)
+3. Define required vs. optional fields
+4. Consider indexing for frequent queries
+5. Plan for evolution — prefer nullable fields over rigid schemas
 
 Document in `.forge/phases/m{M}-{N}-{name}/data-model.md`.
 
 ## API Contract Design
 
-When designing APIs:
-
 1. Define endpoints with HTTP methods
 2. Specify request/response schemas (TypeScript interfaces or JSON Schema)
 3. Document error responses
-4. Consider pagination for list endpoints
-5. Plan authentication requirements per endpoint
+4. Add pagination for list endpoints
+5. Plan per-endpoint auth requirements
 
 Document in `.forge/phases/m{M}-{N}-{name}/contracts/`.
 
 ## Output
 
-After completing architectural work:
 1. ADR filed in `.forge/decisions/`
 2. Data model documented (if applicable)
 3. API contracts defined (if applicable)
-4. Constitutional gates verified
-5. User has approved significant decisions
+4. Constitutional gates checked
+5. User approved significant decisions
 
 ## Phase Handoff
 
-After architectural decisions are documented:
-
-1. **Verify persistence** — Confirm ADRs are written to `.forge/decisions/`, data models and API contracts to `.forge/phases/m{M}-{N}-{name}/`
+1. **Persist** — Confirm ADRs in `.forge/decisions/`, models and contracts in `.forge/phases/m{M}-{N}-{name}/`
 2. **Update state** — Set `current.status` to `planning` in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 
-*"Architecting phase complete. Decisions are documented in `.forge/decisions/` and phase artifacts. I recommend clearing context (`/clear`) before starting the planning phase — the planner will load ADRs, contracts, and state from disk.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*
+*"Architecture decisions written. `/clear` then `/forge` to continue with planning."*

package/template/.claude/skills/beads-integration/SKILL.md

@@ -1,70 +1,60 @@
 ---
 name: beads-integration
-description: "Use when Beads is installed and you want persistent memory across sessions. Trigger when: starting a session on an existing project (bd prime for context), need to find unblocked work (bd ready), completing tasks (bd complete), or managing long-horizon multi-session projects. Requires Beads CLI to be installed."
+description: "Use when Beads is installed for persistent cross-session memory. Trigger on: session start (bd prime), finding unblocked work (bd ready), completing tasks (bd complete), or managing multi-session projects. Requires Beads CLI."
 ---
 
-# Beads Integration (Optional)
+# Beads Integration
 
-Persistent cross-session memory. Only available when Beads is installed.
+Persistent cross-session memory. Requires Beads CLI.
 
 ## Prerequisites
 
-Before using this skill, verify:
-1. Beads CLI installed: `bd --version` (should return version)
-2. Beads initialized in project: `.beads/` directory exists
+1. Beads CLI installed: `bd --version`
+2. Beads initialized: `.beads/` directory exists
 3. Forge integration enabled: `settings.json → forge.beads_integration: true`
 
-If not installed, Forge works fine without it using `.forge/state/` + Session Memory.
+Without Beads, Forge uses `.forge/state/` + Session Memory.
 
 ## Integration Points
 
-### On Session Start: `bd prime`
+### Session Start: `bd prime`
 
-Run at the beginning of every session:
+Run at every session start:
 
 ```bash
 bd prime
 ```
 
-This injects ~1-2K tokens of context:
-- Open tasks with zero open blockers
-- Recently closed tasks (last 3)
-- Active blockers and their status
+Injects ~1-2K tokens: open unblocked tasks, recently closed tasks (last 3), active blockers.
 
-Combine with Forge state: read `.forge/state/milestone-{id}.yml` for workflow position (where `{id}` is the selected milestone), `bd prime` for project-wide context.
+Combine with Forge state: `.forge/state/milestone-{id}.yml` for workflow position, `bd prime` for project-wide context.
 
 ### Finding Work: `bd ready`
 
-Instead of manually triaging, query what's available:
-
 ```bash
 bd ready                    # All unblocked tasks, sorted by priority
 bd ready --priority 3       # Only priority 3+ tasks
 bd ready --json             # Machine-readable output
 ```
 
-Use `bd ready` output to inform which Forge phase/plan to work on next.
+Use output to decide which Forge phase/plan to work on next.
 
 ### During Work: `bd update`
 
-As you complete Forge tasks, update Beads:
-
 ```bash
-bd complete {task-id}       # Mark task done
-bd block {task-id} --by {blocker-id}   # Record a blocker
-bd unblock {task-id}        # Remove a blocker
+bd complete {task-id}                    # Mark task done
+bd block {task-id} --by {blocker-id}     # Record a blocker
+bd unblock {task-id}                     # Remove a blocker
 ```
 
 ### Memory Hygiene: `bd compact`
 
-Periodically clean up old completed tasks:
-
 ```bash
-bd compact --analyze --json  # See what would be compacted
+bd compact --analyze --json  # Preview what gets compacted
 bd compact --apply           # Summarize old tasks (30+ days closed)
 ```
 
-Compaction replaces detailed task content with LLM-generated summaries, preserving essential context while reducing token cost.
+Compaction replaces detailed task content with LLM-generated summaries, reducing token cost while preserving essential context.
 
 ## Forge + Beads Workflow
 
@@ -83,37 +73,31 @@ bd prime → bd ready (pick task) → researching → discussing → planning
 bd prime → bd ready (pick phase) → researching → discussing → architecting → planning → executing → bd complete → verifying → done
 ```
 
-## Syncing State
-
-Forge's `.forge/state/` and Beads' `.beads/` serve different purposes:
+## State Sync
 
 | Concern | Forge (state/) | Beads (.beads/) |
 |---------|----------------|-----------------|
-| Current workflow position | ✓ (milestone-{id}.yml: phase, plan, task) | |
-| Global framework patterns | ✓ (index.yml: desire_paths, metrics) | |
-| Locked decisions | ✓ (context.md) | |
-| Project-wide task graph | | ✓ (DAG with dependencies) |
-| Cross-session memory | | ✓ (persists in git) |
-| Task prioritization | | ✓ (5-level priority) |
-| Memory compaction | | ✓ (semantic summarization) |
+| Workflow position | milestone-{id}.yml: phase, plan, task | |
+| Framework patterns | index.yml: desire_paths, metrics | |
+| Locked decisions | context.md | |
+| Project-wide task graph | | DAG with dependencies |
+| Cross-session memory | | Persists in git |
+| Task prioritization | | 5-level priority |
+| Memory compaction | | Semantic summarization |
 
-Both are git-tracked. Both survive session boundaries. They complement each other.
+Both are git-tracked and survive session boundaries. They complement each other.
 
 ## Creating Beads from Forge Plans
 
-When Forge creates plans with tasks, optionally create corresponding Beads:
+Optionally create Beads from Forge plan tasks for DAG dependency tracking:
 
 ```bash
 bd create "Implement login form" --priority 3
 bd create "Add auth API endpoint" --priority 3 --blocked-by {login-form-id}
 ```
 
-This gives you the DAG dependency tracking that Forge's flat plan files don't provide.
-
 ## Disabling Beads Integration
 
-If you want Forge without Beads:
-
 ```json
 {
   "forge": {
@@ -122,4 +106,4 @@ If you want Forge without Beads:
 }
 ```
 
-Beads continues working independently. Forge just won't query or update it.
+Beads continues working independently; Forge stops querying/updating it.

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

@@ -1,21 +1,21 @@
 ---
 name: debugging
-description: "Use when code isn't working and you need to investigate systematically. Trigger when: tests fail unexpectedly, features don't work as expected, errors are cryptic or intermittent, or you've been stuck for more than 10 minutes. This skill prevents thrashing by enforcing scientific debugging."
+description: "Systematic debugging when tests fail, features break, errors are cryptic/intermittent, or you've been stuck 10+ minutes. Prevents thrashing via scientific method."
 ---
 
 # Debugging
 
-Debug systematically. Every hypothesis tested, every dead end recorded.
+Every hypothesis tested, every dead end recorded.
 
-## The Scientific Method for Bugs
+## Scientific Method
 
-1. **Observe**: What's the actual behavior? (exact error, steps to reproduce, when it started)
-2. **Hypothesize**: Why might this happen? (max 3 hypotheses)
-3. **Predict**: If hypothesis is correct, what should we observe when we test?
-4. **Test**: Run the test. Capture evidence.
-5. **Eliminate**: Does evidence support or refute? Record result.
-6. **Iterate**: Next hypothesis, or refine current one.
-7. **Conclude**: Root cause identified. Fix it.
+1. **Observe**: Exact behavior — error, repro steps, when it started
+2. **Hypothesize**: Max 3 candidate causes
+3. **Predict**: If hypothesis holds, what should the test show?
+4. **Test**: Run it. Capture evidence.
+5. **Eliminate**: Support or refute? Record result.
+6. **Iterate**: Next hypothesis or refine current one
+7. **Conclude**: Root cause found. Fix it.
 
 ## Persistent Debug File
 
@@ -69,62 +69,61 @@ updated: 2026-02-16T19:30:00Z
 ```
 
 ### Update Rules
-- **Status**: Overwrite (phase transitions only)
-- **Current Focus**: Overwrite (before every action)
+- **Status**: Overwrite on phase transitions only
+- **Current Focus**: Overwrite before every action
 - **Symptoms**: Immutable after gathering phase
-- **Eliminated**: Append only (prevents re-investigating dead ends)
+- **Eliminated**: Append only — prevents re-investigating dead ends
 - **Evidence Log**: Append only
 
 ## Investigation Techniques
 
-Use these in order of effectiveness:
+Use in order of effectiveness:
 
-### 1. Read the Error (seriously)
-Read the ENTIRE error message, stack trace, and surrounding log output. Most bugs are explained by the error — we just don't read carefully enough.
+### 1. Read the Error
+Read the ENTIRE error message, stack trace, and surrounding log output. Most bugs are explained by the error.
 
 ### 2. Binary Search
-Cut the problem space in half. If a function has 10 steps, test after step 5. If it works, bug is in steps 6-10. Repeat.
+Cut the problem space in half. Test after step 5 of 10. Works? Bug is in 6-10. Repeat.
 
 ### 3. Minimal Reproduction
-Strip away everything until only the bug remains. Remove middleware, simplify data, use hardcoded values. The smaller the reproduction, the clearer the cause.
+Strip away everything until only the bug remains. Remove middleware, simplify data, hardcode values.
 
 ### 4. Differential Debugging
-What changed? `git diff`, `git log`, recent dependency updates. If it worked before and doesn't now, something changed.
+What changed? `git diff`, `git log`, recent dependency updates.
 
 ### 5. Working Backwards
-Start from the wrong output. Trace the data backward through the system: which function produced it? What was its input? Where did that come from?
+Start from the wrong output. Trace data backward: which function produced it? What was its input?
 
 ### 6. Comment Out Everything
-Remove all code. Uncomment one piece at a time. When the bug reappears, you found the culprit.
+Remove all code. Uncomment one piece at a time. When the bug reappears, that's the culprit.
 
 ### 7. Add Observability First
-Before changing behavior, add logging. See what's actually happening before guessing.
+Add logging before changing behavior. See what's happening before guessing.
 
 ### 8. Git Bisect
-If you know it worked at some point: `git bisect start`, `git bisect bad` (current), `git bisect good {hash}` (working version). Git finds the exact breaking commit.
+`git bisect start`, `git bisect bad` (current), `git bisect good {hash}` (working version). Git finds the exact breaking commit.
 
-## Cognitive Bias Awareness
+## Cognitive Bias Traps
 
-Watch for these traps:
-- **Confirmation bias**: Seeking evidence that supports your theory, ignoring counter-evidence
-- **Anchoring**: Fixating on the first theory instead of considering alternatives
-- **Availability bias**: Blaming the last thing you changed, even if unrelated
-- **Sunk cost**: Continuing a dead-end investigation because you've spent time on it
+- **Confirmation bias**: Seeking evidence for your theory, ignoring counter-evidence
+- **Anchoring**: Fixating on the first theory
+- **Availability bias**: Blaming the last thing changed, even if unrelated
+- **Sunk cost**: Continuing a dead-end investigation because of time spent
 
-Counter-measure: After 3 failed hypotheses, step back and re-read symptoms from scratch.
+After 3 failed hypotheses, step back and re-read symptoms from scratch.
 
-## When to Escalate
+## Escalation
 
-After 5 hypotheses tested without finding root cause:
-1. Document everything in debug file (what's tried, what's eliminated)
-2. Mark as `[NEEDS PAIR DEBUGGING]` in `.forge/state/milestone-{id}.yml` blockers
+After 5 hypotheses tested without root cause:
+1. Document everything in the debug file
+2. Mark `[NEEDS PAIR DEBUGGING]` in `.forge/state/milestone-{id}.yml` blockers
 3. The debug file saves the next person hours of re-investigation
 
 ## Resolution
 
 When root cause found:
 1. Fix the issue
-2. Add a test that catches this specific bug (regression test)
+2. Add a regression test for this specific bug
 3. Commit: `fix({scope}): {description of root cause and fix}`
 4. Move debug file to `.forge/debug/resolved/`
 5. Update `.forge/state/milestone-{id}.yml` — remove from blockers