@soleri/forge 9.0.0 → 9.2.0

package/dist/skills/parallel-execute/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: parallel-execute
+description: >
+  Use when executing a plan where independent tasks can run concurrently. Triggers on "run in
+  parallel", "parallelize", "fan out", "concurrent execution", "run simultaneously", "at the
+  same time", "dispatch subagents", "batch execute", or when a plan has 3+ tasks with no
+  dependency overlap. For sequential task-by-task execution, use executing-plans instead.
+---
+
+# Parallel Execute — Subagent-Driven Plan Execution
+
+Execute plan tasks in parallel by dispatching independent tasks to separate subagents. The controller agent (you) never implements — you dispatch, review, and integrate.
+
+**Announce at start:** "I'm using the parallel-execute skill to run independent tasks concurrently."
+
+<HARD-GATE>
+You MUST have an approved, split plan before using this skill. If no plan exists or it has no tasks, stop and use the writing-plans skill first.
+</HARD-GATE>
+
+## When to Use
+
+- Plan has 3+ tasks
+- At least 2 tasks have no dependency overlap (can run simultaneously)
+- Tasks touch different files/modules (low merge conflict risk)
+
+**Do NOT use when:**
+- All tasks are sequential (each depends on the previous)
+- Tasks modify the same files (high conflict risk)
+- Plan has fewer than 3 tasks (use executing-plans instead)
+
+## The Process
+
+### Step 1: Load Plan and Build Dependency Graph
+
+```
+YOUR_AGENT_core op:get_plan
+YOUR_AGENT_core op:plan_list_tasks params:{ planId: "<id>" }
+```
+
+Map out which tasks are independent by checking `dependsOn` for each task. Group tasks into **waves** — sets of tasks that can run in parallel:
+
+- **Wave 1**: All tasks with no dependencies (or whose dependencies are already complete)
+- **Wave 2**: Tasks whose dependencies are all in Wave 1
+- **Wave N**: Tasks whose dependencies are all in prior waves
+
+Present the wave plan to the user before starting:
+
+```
+## Execution Waves
+
+| Wave | Tasks | Parallel? |
+|------|-------|-----------|
+| 1 | task-1, task-3, task-5 | Yes (3 subagents) |
+| 2 | task-2 (depends on task-1) | Solo |
+| 3 | task-4 (depends on task-2, task-3) | Solo |
+```
+
+### Step 2: Dispatch a Wave
+
+For each task in the current wave:
+
+1. Check readiness:
+   ```
+   YOUR_AGENT_core op:plan_dispatch params:{ planId: "<id>", taskId: "<taskId>" }
+   ```
+   Only dispatch tasks where `ready: true`.
+
+2. Mark as in_progress:
+   ```
+   YOUR_AGENT_core op:update_task params:{ planId: "<id>", taskIndex: <n>, status: "in_progress" }
+   ```
+
+3. Gather vault context for the task:
+   ```
+   YOUR_AGENT_core op:search params:{ query: "<task topic>", mode: "scan" }
+   ```
+
+4. **Launch all ready tasks as parallel Agent calls in a single message.** Each subagent gets:
+
+```
+You are implementing a single task from a plan. Work autonomously.
+
+## Task
+- **ID**: {taskId}
+- **Title**: {title}
+- **Description**: {description}
+- **Acceptance Criteria**: {criteria}
+
+## Context
+- **Plan Objective**: {planObjective}
+- **Vault Patterns to Follow**: {relevantPatterns}
+- **Files Likely Involved**: {fileHints}
+
+## Rules
+- Implement ONLY this task — do not touch files outside your scope
+- Run tests after implementation
+- If blocked, report the blocker and stop — do not guess
+- Do not commit — the controller handles commits
+- When done, report: files changed, tests passing, any concerns
+
+## Self-Review Checklist
+Before reporting completion, verify:
+- [ ] All acceptance criteria met
+- [ ] Tests pass
+- [ ] No files modified outside task scope
+- [ ] No console.log or debug code left behind
+- [ ] No raw colors or hardcoded values (use semantic tokens)
+```
+
+Use the Agent tool with `isolation: "worktree"` when tasks touch nearby files to prevent conflicts.
+
+### Step 3: Collect Results
+
+As subagents complete, collect their results. For each completed task:
+
+1. **Run spec review** — spawn a reviewer subagent:
+   ```
+   YOUR_AGENT_core op:plan_review_spec params:{ planId: "<id>", taskId: "<taskId>" }
+   ```
+   Use the returned prompt to launch a spec-review Agent that reads the ACTUAL code changes (not the implementer's self-report).
+
+2. **Record spec review outcome:**
+   ```
+   YOUR_AGENT_core op:plan_review_outcome params:{
+     planId: "<id>", taskId: "<taskId>",
+     reviewType: "spec", reviewer: "spec-reviewer",
+     outcome: "approved|rejected|needs_changes",
+     comments: "<specific file:line references>"
+   }
+   ```
+
+3. **If spec passes, run quality review:**
+   ```
+   YOUR_AGENT_core op:plan_review_quality params:{ planId: "<id>", taskId: "<taskId>" }
+   ```
+   Launch a quality-review Agent with the returned prompt.
+
+4. **Record quality review outcome:**
+   ```
+   YOUR_AGENT_core op:plan_review_outcome params:{
+     planId: "<id>", taskId: "<taskId>",
+     reviewType: "quality", reviewer: "quality-reviewer",
+     outcome: "approved|rejected|needs_changes",
+     comments: "<severity-tagged feedback>"
+   }
+   ```
+
+5. **Handle outcomes:**
+
+| Spec | Quality | Action |
+|------|---------|--------|
+| Pass | Pass | Mark task completed |
+| Fail | — | Dispatch fix subagent with failure feedback (max 2 retries) |
+| Pass | Critical issues | Dispatch targeted fix subagent (max 2 retries) |
+| Pass | Minor issues only | Mark completed, note issues for later |
+
+6. **Mark completed:**
+   ```
+   YOUR_AGENT_core op:update_task params:{ planId: "<id>", taskIndex: <n>, status: "completed" }
+   ```
+
+### Step 4: Advance to Next Wave
+
+After all tasks in a wave are complete (or failed after retries):
+
+1. Report wave results to the user:
+   ```
+   ## Wave N Complete
+
+   | Task | Status | Review | Notes |
+   |------|--------|--------|-------|
+   | task-1 | Completed | Spec: Pass, Quality: Pass | — |
+   | task-3 | Completed | Spec: Pass, Quality: Minor issues | Noted for cleanup |
+   | task-5 | Failed | Spec: Fail (2 retries exhausted) | Escalated |
+   ```
+
+2. **Wait for user acknowledgment** before proceeding to the next wave.
+
+3. Check which tasks in the next wave are now ready (dependencies met).
+
+4. Repeat from Step 2.
+
+### Step 5: Final Integration Review
+
+After all waves complete:
+
+1. Spawn a final review subagent that checks cross-cutting concerns:
+   - Consistency across all task implementations
+   - Integration points between tasks
+   - No conflicting patterns or duplicate code
+   - Tests pass together (not just individually)
+
+2. Report to user with full execution summary.
+
+### Step 6: Complete Plan Lifecycle
+
+Same as executing-plans — reconcile, capture knowledge, archive:
+
+```
+YOUR_AGENT_core op:plan_reconcile params:{
+  planId: "<id>",
+  actualOutcome: "<what happened>",
+  driftItems: [{ type: "...", description: "...", impact: "...", rationale: "..." }]
+}
+
+YOUR_AGENT_core op:plan_complete_lifecycle params:{
+  planId: "<id>",
+  patterns: ["<patterns discovered>"],
+  antiPatterns: ["<anti-patterns discovered>"]
+}
+
+YOUR_AGENT_core op:session_capture params:{
+  summary: "<execution summary with parallel metrics>"
+}
+```
+
+## Subagent Isolation Rules
+
+| Situation | Isolation |
+|-----------|-----------|
+| Tasks touch completely different directories | No isolation needed |
+| Tasks touch files in the same package | Use `isolation: "worktree"` |
+| Tasks modify the same file | **Do NOT parallelize** — run sequentially |
+
+When using worktree isolation, the controller must merge worktree changes back after review passes.
+
+## Failure Handling
+
+| Failure | Response |
+|---------|----------|
+| Subagent reports blocker | Pause that task, continue others in the wave |
+| Spec review fails | Dispatch fix subagent with feedback (retry 1/2) |
+| Second retry fails | Mark task as `failed`, escalate to user |
+| Merge conflict from worktree | Resolve manually, then re-run quality review |
+| All tasks in wave fail | Stop execution, report to user |
+
+## Capture Learnings
+
+During execution, capture insights about parallelization:
+
+```
+YOUR_AGENT_core op:capture_quick params:{
+  title: "<what you learned about parallel execution>",
+  description: "<context: which tasks parallelized well, which conflicted>"
+}
+```
+
+## When to Fall Back to Sequential
+
+**Switch to executing-plans skill mid-execution when:**
+- Subagents keep conflicting on shared files
+- Merge resolution is taking longer than the parallelization saves
+- User requests sequential execution
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `get_plan` | Load tracked plan |
+| `plan_list_tasks` | List all tasks with dependencies |
+| `plan_dispatch` | Check task readiness (dependencies met?) |
+| `update_task` | Mark tasks in_progress / completed / failed |
+| `plan_review_spec` | Generate spec compliance review prompt |
+| `plan_review_quality` | Generate code quality review prompt |
+| `plan_review_outcome` | Record review pass/fail result |
+| `plan_reconcile` | Post-execution drift analysis |
+| `plan_complete_lifecycle` | Extract knowledge, archive |
+| `session_capture` | Save session context |
+| `capture_quick` | Capture mid-execution learnings |
+| `search` | Vault lookup for task context |
+
+## Integration
+
+**Required skills:**
+- writing-plans — Creates the plan this skill executes
+- verification-before-completion — Verify work before claiming completion
+- executing-plans — Fallback for sequential execution

package/dist/skills/retrospective/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: retrospective
+description: >
+  Use for time-bound reflection on recent WORK — "sprint retro", "weekly summary", "what went
+  well this week", "end of sprint", "monthly report". Reviews sessions and extracts actionable
+  improvements. For brain pattern intelligence and strength scores, use brain-debrief instead.
+---
+
+# Retrospective — Learning Report From Real Data
+
+Generate a data-driven retrospective from session data, vault captures, plan outcomes, and brain intelligence.
+
+## Steps
+
+### 1. Gather Data
+
+```
+YOUR_AGENT_core op:brain_stats
+YOUR_AGENT_core op:brain_stats params: { since: "<start of period>" }
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:vault_recent
+YOUR_AGENT_core op:memory_topics
+YOUR_AGENT_core op:memory_stats
+YOUR_AGENT_core op:plan_stats
+YOUR_AGENT_core op:admin_search_insights
+YOUR_AGENT_core op:admin_vault_analytics
+```
+
+### 2. Analyze Patterns
+
+```
+YOUR_AGENT_core op:vault_age_report
+YOUR_AGENT_core op:curator_detect_duplicates
+YOUR_AGENT_core op:curator_contradictions
+YOUR_AGENT_core op:curator_health_audit
+```
+
+### 3. Present the Retrospective
+
+```
+## Retrospective: [Period]
+
+### By the Numbers
+| Metric | This Period | Previous | Trend |
+|--------|-----------|----------|-------|
+| Patterns captured | X | Y | up/down |
+| Plans completed | X | Y | up/down |
+| Brain strength (avg) | X | Y | up/down |
+| Search misses | X | Y | up/down |
+
+### What Went Well
+[High brain strength patterns, completed plans, growing domains]
+
+### What Didn't Go Well
+[Recurring anti-patterns, failed plans, knowledge gaps]
+
+### Vault Health
+Quality: X/100 | Duplicates: N | Contradictions: N | Stale: N
+
+### Recommendations
+1. [Data-driven action item]
+2. [Data-driven action item]
+```
+
+### 4. Capture the Retrospective
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "Retrospective — [period]",
+    description: "<key findings and action items>",
+    type: "workflow",
+    category: "meta",
+    tags: ["retrospective"]
+  }
+```
+
+### 5. Clean Up (Optional)
+
+If quality issues found: `op:curator_consolidate` then `op:brain_build_intelligence`.
+
+## Common Mistakes
+
+- Presenting AI opinions instead of actual vault/brain metrics
+- Not comparing periods (missing trends)
+- Skipping the capture step (retrospective insights are lost)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `brain_stats` / `brain_strengths` | Metrics and patterns |
+| `vault_recent` | Recent captures |
+| `memory_topics` / `memory_stats` | Knowledge clusters |
+| `plan_stats` | Plan completion |
+| `admin_search_insights` | Search misses |
+| `curator_health_audit` | Vault quality |
+| `capture_knowledge` | Persist retrospective |

package/dist/skills/second-opinion/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: second-opinion
+description: Use when facing a technical decision, comparing approaches, or needing an informed recommendation backed by vault knowledge, brain patterns, and web research.
+---
+
+# Second Opinion — Decision Support From All Sources
+
+Get an informed recommendation that synthesizes vault knowledge, brain patterns, cross-project experience, and web research before making any technical decision.
+
+## Steps
+
+### 1. Understand the Decision
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "<user's question>" }
+```
+
+### 2. Search All Knowledge Sources
+
+**Vault** — previous decisions, patterns, anti-patterns:
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<the decision or options>" }
+```
+
+**Brain** — proven approaches:
+```
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:brain_recommend
+  params: { projectName: "<current project>" }
+```
+
+**Cross-project** — what other projects chose:
+```
+YOUR_AGENT_core op:memory_cross_project_search
+  params: { query: "<topic>", crossProject: true }
+```
+
+**Web** — community consensus, benchmarks, comparison articles.
+
+### 3. Synthesize and Present
+
+```
+## Decision: [Question]
+
+### What the Vault Says
+[Existing decisions, patterns, anti-patterns]
+
+### What the Brain Recommends
+[Proven patterns, cross-project insights]
+
+### What the Web Says
+[Community consensus, benchmarks]
+
+### Options Analysis
+| Criteria | Option A | Option B |
+|----------|----------|----------|
+| [criteria] | ... | ... |
+| Vault support | [patterns?] | [patterns?] |
+
+### Recommendation
+[Clear recommendation with reasoning]
+
+### Risks
+[What could go wrong]
+```
+
+### 4. Capture the Decision
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<decision title>",
+    description: "<chosen option, rationale, rejected alternatives>",
+    type: "decision",
+    category: "<domain>",
+    tags: ["decision"]
+  }
+```
+
+## Common Mistakes
+
+- Giving a generic AI opinion instead of searching vault/brain first
+- Not capturing the final decision (next person faces the same question blind)
+- Skipping cross-project search (another project may have solved this)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify decision type |
+| `search_intelligent` | Find previous decisions |
+| `brain_strengths` / `brain_recommend` | Proven approaches |
+| `memory_cross_project_search` | Other projects' choices |
+| `memory_search` | Session context |
+| `capture_knowledge` | Persist the decision |

package/dist/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: systematic-debugging
+description: >
+  Use as the FIRST response when something is broken — "bug", "failing test", "not working",
+  "debug this", "error", "crash", "unexpected behavior", "weird issue". Diagnoses root cause
+  before proposing fixes. After root cause is found, hand off to fix-and-learn for repair and
+  knowledge capture.
+---
+
+# Systematic Debugging
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+## Phase 0: Search Before Investigating
+
+**BEFORE touching any code:**
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<bug or error message>" }
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:memory_search
+  params: { query: "<error or symptom>" }
+```
+
+If vault has a match — apply it directly. Then search web: exact error message, GitHub issues, Stack Overflow, official docs.
+
+Only if vault and web produce no answer, proceed to Phase 1.
+
+## Start a Debug Loop
+
+```
+YOUR_AGENT_core op:loop_start
+  params: { prompt: "Debug: <bug>", mode: "custom" }
+```
+
+## The Four Phases
+
+### Phase 1: Root Cause Investigation
+
+1. Read error messages carefully
+2. Reproduce consistently
+3. Check recent changes
+4. Gather evidence at component boundaries
+5. Trace data flow backward through call stack
+
+Track each step with `op:loop_iterate`.
+
+### Phase 2: Pattern Analysis
+
+Find working examples, compare against references (read completely), identify differences, understand dependencies. Use `op:search_intelligent` for comparison.
+
+### Phase 3: Hypothesis and Testing
+
+Form single hypothesis, test minimally (one variable at a time), verify before continuing. If unsure — ask for help.
+
+### Phase 4: Implementation
+
+1. Create failing test (use test-driven-development skill)
+2. Implement single fix (root cause only)
+3. Verify fix
+4. If < 3 attempts failed, return to Phase 1. If >= 3, STOP — question architecture with human partner.
+
+## Phase 5: Capture the Learning
+
+```
+YOUR_AGENT_core op:loop_complete
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<bug>",
+    description: "<root cause, solution, what made it hard to find>",
+    type: "anti-pattern",
+    category: "<domain>",
+    tags: ["<relevant>"]
+  }
+YOUR_AGENT_core op:session_capture
+```
+
+## Red Flags — STOP and Return to Phase 1
+
+- "Quick fix for now" / "Just try changing X"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" after 2+ failures
+- Each fix reveals a new problem elsewhere
+
+## Common Mistakes
+
+- Skipping vault search ("I know this one") — 30 seconds saves hours
+- Making multiple changes at once (can't isolate what worked)
+- Skipping the capture step (same bug will recur)
+
+## Quick Reference
+
+| Phase | Key Activities | Tools |
+|-------|---------------|-------|
+| 0. Search | Vault, web, memory | `search_intelligent`, `brain_strengths`, `memory_search` |
+| 1. Root Cause | Read errors, reproduce, trace | `loop_iterate` |
+| 2. Pattern | Find working examples, compare | `search_intelligent` |
+| 3. Hypothesis | Form theory, test minimally | `loop_iterate` |
+| 4. Implementation | Test, fix, verify | `loop_iterate` |
+| 5. Capture | Persist root cause | `capture_knowledge`, `loop_complete` |
+
+**Related skills:** test-driven-development, verification-before-completion, fix-and-learn

package/dist/skills/test-driven-development/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: test-driven-development
+description: Use when implementing any feature or bugfix — write failing tests before implementation code.
+---
+
+# Test-Driven Development (TDD)
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+## Before You Start — Search First
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<what you're about to test>" }
+YOUR_AGENT_core op:brain_strengths
+```
+
+If vault has testing guidance for this domain, follow it.
+
+## Start a TDD Loop
+
+```
+YOUR_AGENT_core op:loop_start
+  params: { prompt: "TDD: <feature>", mode: "custom" }
+```
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over. No exceptions.
+
+## Red-Green-Refactor
+
+### RED — Write Failing Test
+
+One behavior, clear name, real code (no mocks unless unavoidable). Run test, confirm it **fails** for the expected reason (feature missing, not typos). Track: `op:loop_iterate`.
+
+### GREEN — Minimal Code
+
+Simplest code to pass the test. Don't add features beyond the test. Run test, confirm it **passes** and other tests still pass. Track: `op:loop_iterate`.
+
+### REFACTOR — Clean Up
+
+After green only: remove duplication, improve names, extract helpers. Keep tests green. Don't add behavior.
+
+### Repeat
+
+Next failing test for next behavior.
+
+## Verification Checklist
+
+- [ ] Every new function has a test
+- [ ] Watched each test fail before implementing
+- [ ] Failed for expected reason (not typo)
+- [ ] Wrote minimal code to pass
+- [ ] All tests pass, output pristine
+- [ ] Mocks only where unavoidable
+- [ ] Edge cases and errors covered
+
+## After TDD
+
+```
+YOUR_AGENT_core op:loop_complete
+YOUR_AGENT_core op:capture_quick
+  params: { title: "<testing pattern>", description: "<what you learned>" }
+```
+
+## Common Mistakes
+
+- Writing implementation before tests ("I'll test after")
+- Keeping pre-test code as "reference" (delete means delete)
+- Test passes immediately (testing existing behavior, not new)
+- Multiple behaviors in one test ("and" in name means split it)
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write wished-for API first |
+| Must mock everything | Code too coupled — use DI |
+| Test setup huge | Extract helpers or simplify design |
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Find testing patterns |
+| `brain_strengths` | Proven testing approaches |
+| `loop_start` / `loop_iterate` / `loop_complete` | TDD cycle tracking |
+| `capture_quick` | Capture new testing patterns |