@soleri/forge 9.3.1 → 9.5.0

package/dist/skills/agent-guide/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: agent-guide
+description: >
+  Use when the user asks "what can you do", "help me", "how do I use this",
+  "what features do you have", "what tools are available", "how does this work",
+  "show me your capabilities", "what are you", "who are you", or any question
+  about the agent's identity, capabilities, available tools, or how to use them.
+  Not needed for proactive tool suggestions — those are handled by engine rules.
+---
+
+# Agent Guide — Capability Discovery
+
+Help users understand what this agent can do, how to use it effectively, and what makes it different from a raw LLM. This skill handles the deep discovery flow — proactive tool suggestions during normal work are handled by the engine rules (Tool Advocacy section).
+
+## When to Use
+
+- "What can you do?" / "What are your capabilities?"
+- "How do I search for X?" / "How do I capture knowledge?"
+- "What tools do you have?" / "Show me your features"
+- "Who are you?" / "What is this agent?"
+- "Help" / "I'm stuck" / "How does this work?"
+- First-time users, onboarding, or anyone unfamiliar with the agent
+
+## Capability Discovery Sequence
+
+### Step 1: Identity
+
+```
+YOUR_AGENT_core op:activate
+  params: { projectPath: "." }
+```
+
+This returns the agent's persona: name, role, description, tone, principles, and domains. Present the identity first — who the agent is and what it specializes in.
+
+### Step 2: Health & Status
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+Shows what subsystems are active: vault (how many entries), brain (vocabulary size), LLM availability, cognee status. This tells the user what the agent currently has to work with.
+
+### Step 3: Available Tools
+
+```
+YOUR_AGENT_core op:admin_tool_list
+```
+
+Lists all facades and operations. Present them grouped by category with plain-language descriptions.
+
+### Step 4: Present by What Users Can DO
+
+Organize capabilities by user goals, not technical names:
+
+**Knowledge & Memory**
+
+- Search the vault for patterns, anti-patterns, and architectural decisions
+- Capture new knowledge from the current session
+- Search across sessions and projects for relevant context
+- Curate: deduplicate, groom, resolve contradictions
+
+**Planning & Execution**
+
+- Create structured plans with vault context and brain recommendations
+- Split plans into tasks with complexity estimates
+- Track execution with drift detection
+- Complete with knowledge capture and session recording
+
+**Intelligence & Learning**
+
+- Brain learns from every session — patterns get stronger with use
+- Recommendations based on similar past work
+- Strength tracking: which patterns are proven vs experimental
+- Feedback loop: brain improves based on what works
+
+**Quality & Validation**
+
+- Health checks across all subsystems
+- Iterative validation loops with configurable targets
+- Governance: policies, proposals, quotas
+
+**Identity & Control**
+
+- Persona activation and deactivation
+- Intent routing: the agent classifies what you want and routes to the right workflow
+- Project registration and cross-project linking
+
+**Domain Knowledge** (varies by agent)
+
+- Each domain has: `get_patterns`, `search`, `get_entry`, `capture`, `remove`
+- Call `op:activate` to discover which domains are configured
+
+## Common Questions
+
+### "What makes you different from regular Claude?"
+
+You have persistent knowledge (vault), learned patterns (brain), structured planning with grading, iterative validation loops, and domain-specific intelligence. Regular Claude starts fresh every conversation — this agent accumulates knowledge and gets smarter over time.
+
+### "How do I get the most out of you?"
+
+1. **Use the vault** — search before deciding, capture after learning
+2. **Use planning** — structured plans beat ad-hoc work for anything non-trivial
+3. **Trust the brain** — pattern recommendations come from real usage data
+4. **Capture everything** — every bug fix, every pattern, every anti-pattern. The vault grows smarter with use.
+5. **Use loops for quality** — iterative validation catches issues that single-pass work misses
+
+### "How do I add new capabilities?"
+
+Extensions can add new ops, facades, middleware, and hooks. Domain packs add domain-specific knowledge and validation. Use `soleri pack install <name>` or `soleri extend add-op <name>`.
+
+## Anti-Patterns
+
+- **Listing raw op names without context** — always explain what the op does in plain language
+- **Claiming capabilities that do not exist** — only reference ops the agent actually has. When unsure, call `op:admin_tool_list` first
+- **Dumping the entire tool catalog** — answer the specific question, show relevant tools, not all tools
+- **Repeating what the user already knows** — if they ask about a specific feature, answer that, don't give the full tour

package/dist/skills/agent-issues/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: agent-issues
+description: >
+  Use when creating GitHub issues, bugs, tasks, or milestones that will be
+  worked on by AI coding agents. Triggers on: "create issue", "file bug",
+  "gh issue", "add milestone", "create task", "report bug", "gh tasks",
+  "create tasks", "create tickets", "file tickets", or when generating
+  structured work items from conversation context.
+---
+
+# Agent-Optimized Issue Creation
+
+Create GitHub issues that AI agents can parse, execute, and verify without ambiguity. Every issue is a self-contained work order — an agent reading it has everything needed to start, execute, and prove completion.
+
+## Core Principle
+
+**Human issues describe problems. Agent issues describe solutions as testable outcomes.**
+
+An agent cannot act on "improve avatar handling." It can act on: "Add PNG upload to `POST /v1/avatar` in `apps/api/src/routes/avatar.ts`, return `{ avatarUrl }`, reject files > 2MB with 413."
+
+## When to Use
+
+- Creating any GitHub issue via `gh issue create`
+- Filing bugs from conversation context or error logs
+- Breaking plans into trackable work items
+- Creating milestones with sub-issues
+- Converting vault patterns or anti-patterns into actionable fixes
+
+## Issue Template by Type
+
+### Bug
+
+```markdown
+# Objective
+
+<one sentence: what's broken and what "fixed" looks like>
+
+## Type: bug
+
+## Component: <package or module name>
+
+## Priority: P0 | P1 | P2 | P3
+
+## Context
+
+- Impact: <who/what is affected>
+- Related: <links to issues, PRs, vault entries>
+- First seen: <date or commit>
+
+## Steps to Reproduce
+
+1. <exact command or action>
+2. <exact command or action>
+3. Observe: <what happens>
+
+## Expected vs Actual
+
+|              | Behavior           |
+| ------------ | ------------------ |
+| **Expected** | <correct behavior> |
+| **Actual**   | <broken behavior>  |
+
+## Error Output
+```
+
+<paste exact error, stack trace, or log output>
+
+````
+
+## Root Cause (if known)
+- File: `path/to/file.ts` — `functionName()` or line reference
+- Why: <brief technical explanation>
+
+## Scope
+| In | Out |
+|----|-----|
+| Fix the specific bug | Refactoring surrounding code |
+| Add regression test | Performance optimization |
+
+## Code Locations
+- Bug site: `path/to/file.ts` — `symbolName`
+- Test file: `path/to/file.test.ts`
+- Related: `path/to/related.ts` — `relatedSymbol`
+
+## Acceptance Criteria
+- [ ] Bug no longer reproduces with steps above
+- [ ] Regression test added that fails without fix, passes with fix
+- [ ] No new lint/type errors
+- [ ] Existing tests pass
+
+## Verification
+```bash
+<exact test command>
+<exact build/lint command>
+````
+
+````
+
+### Feature
+
+```markdown
+# Objective
+<one sentence: what capability is added and why>
+
+## Type: feature
+## Component: <package or module name>
+## Priority: P0 | P1 | P2 | P3
+
+## Context
+- Why: <user need or business reason>
+- Related: <links to issues, PRs, vault entries, specs>
+
+## Scope
+| In | Out |
+|----|-----|
+| <specific deliverable> | <what NOT to touch> |
+
+## Constraints
+- Backward compatibility: <requirements>
+- Dependencies: <allowed/forbidden>
+- Performance: <budgets if any>
+- Security: <requirements if any>
+
+## Code Locations
+- Entry point: `path/to/file.ts` — `functionOrClass`
+- Integration point: `path/to/other.ts` — `symbol`
+- Test location: `path/to/test.ts`
+
+## Proposed Approach (optional)
+1. <step>
+2. <step>
+
+## Acceptance Criteria
+- [ ] Given <precondition>, when <action>, then <result>
+- [ ] Given <precondition>, when <action>, then <result>
+- [ ] Tests added for new behavior
+- [ ] Types exported if public API
+
+## Verification
+```bash
+<exact test command>
+<exact build command>
+````
+
+## Definition of Done
+
+- [ ] Acceptance criteria satisfied
+- [ ] `npm test` passes
+- [ ] `npm run typecheck` passes
+- [ ] Changes scoped to "In Scope" only
+
+````
+
+### Milestone
+
+```markdown
+# Milestone: <short title>
+
+## Objective
+<one sentence: what this milestone achieves>
+
+## Timeline
+- Target: <date>
+- Depends on: <blocking milestones or external factors>
+
+## Sub-Issues
+
+| # | Type | Title | Priority | Depends On |
+|---|------|-------|----------|------------|
+| 1 | feature | <title> | P1 | — |
+| 2 | feature | <title> | P1 | #1 |
+| 3 | bug | <title> | P2 | — |
+
+## Completion Criteria
+- [ ] All sub-issues closed
+- [ ] Integration test passes end-to-end
+- [ ] <milestone-level verification>
+````
+
+## Field Guide
+
+### Writing Good Objectives
+
+| Bad                   | Good                                                                            |
+| --------------------- | ------------------------------------------------------------------------------- |
+| "Fix the login"       | "Login returns 401 instead of session token when OAuth callback has valid code" |
+| "Add dark mode"       | "Add `prefers-color-scheme` media query support to all semantic color tokens"   |
+| "Improve performance" | "Reduce cold-start vault search from 800ms to <200ms by lazy-loading FTS index" |
+
+### Writing Good Acceptance Criteria
+
+Use Given/When/Then for behavioral criteria. Use plain checkboxes for structural criteria.
+
+**Behavioral:**
+
+- [ ] Given a user with valid OAuth code, when POST /auth/callback, then returns 200 with session token
+
+**Structural:**
+
+- [ ] Unit test covers happy path + error case
+- [ ] No new `any` types introduced
+- [ ] Public API documented in JSDoc
+
+### Writing Good Code Locations
+
+Always include:
+
+1. **File path** — repo-root relative
+2. **Anchor** — function name, class name, route, or config key
+3. **Context** — what the agent should look at there
+
+```
+- Handler: `packages/core/src/auth/callback.ts` — `handleOAuthCallback()`
+- Token logic: `packages/core/src/auth/session.ts` — `createSession()`
+- Test: `packages/core/src/__tests__/auth.test.ts` — "OAuth callback" describe block
+```
+
+### Constraints That Prevent Agent Overreach
+
+Be explicit about boundaries. Agents optimize globally unless told not to.
+
+```
+## Constraints
+- Do NOT modify the public API surface of `@soleri/core`
+- Do NOT add new npm dependencies
+- Do NOT refactor surrounding code — fix only the bug
+- Backward compatible: existing agent.yaml files must still work
+```
+
+## Workflow
+
+1. **Gather context** — search vault, read error logs, check git blame
+2. **Identify code locations** — grep codebase for relevant symbols
+3. **Choose template** — bug, feature, or milestone
+4. **Fill template** — every field. Skip none.
+5. **Create issue** — `gh issue create --title "..." --body "..." --label "..."`
+
+## Integration with Planning
+
+When creating issues from a plan, the plan is the source of truth — GitHub issues are the projection. Each task becomes a lean issue pointing back to the plan.
+
+### Plan-Sourced Task Template
+
+````markdown
+# Objective
+
+<one sentence: what this task delivers>
+
+## Plan: `<plan-id>` | Task <N> of <total>
+
+## Parent: #<epic-issue-number>
+
+## Complexity: Low | Medium | High
+
+## Depends on: <task dependencies or "nothing">
+
+## Code Locations
+
+- `path/to/file.ts` — `symbolOrFunction`
+
+## Acceptance Criteria
+
+- [ ] <testable outcome>
+- [ ] <testable outcome>
+- [ ] Tests pass
+
+## Verification
+
+```bash
+<exact command>
+```
+````
+
+```
+
+### Rules for Plan-Sourced Issues
+
+1. **Plan ID is mandatory** — every task issue must include `## Plan: \`<plan-id>\`` so the full plan is one API call away
+2. **Keep issues lean** — task description + code locations + acceptance criteria
+3. **One issue per task** — don't bundle multiple plan tasks into one issue
+4. **Parent/epic issue** — create a parent issue that lists all task issues
+5. **Map complexity to priority** — High → P1, Medium → P2, Low → P3
+6. **Include task number** — "Task 3 of 11" helps track progress
+
+## Labels
+
+Always apply at least:
+- Type: `bug`, `feature`, `refactor`, `chore`
+- Priority: `P0`, `P1`, `P2`, `P3` (if using priority labels)
+- Component: package or module name (if using component labels)
+```

package/dist/skills/agent-persona/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: agent-persona
+description: >
+  Use when the user activates the agent's persona via its greeting phrase, or says
+  "activate persona", "be yourself", "stay in character", or any activation phrase
+  defined in the agent's persona configuration. Reinforces character persistence
+  through the session and survives context compaction.
+---
+
+# Agent Persona — Stay in Character
+
+This skill reinforces persona persistence. The MCP activation loads the runtime payload — this skill ensures the character sticks across the full session, including after context compaction.
+
+## How It Works
+
+Every agent has a persona defined in `agent.yaml`. The persona contains:
+
+- **name** — the agent's display name
+- **role** — what the agent does
+- **tone** — `precise`, `mentor`, or `pragmatic`
+- **greeting** — the activation response
+- **principles** — core values that guide behavior
+
+## Activation
+
+When the user triggers activation (greeting phrase or explicit request):
+
+```
+YOUR_AGENT_core op:activate
+  params: { projectPath: "." }
+```
+
+The activation response contains the full persona payload. Adopt it immediately.
+
+## Rules
+
+1. **Stay in character for EVERY response** until the user explicitly deactivates
+2. **Technical accuracy is the priority** — persona is the wrapper, not a replacement for correctness
+3. **Tone consistency** — match the configured tone (`precise` = concise and exact, `mentor` = educational and encouraging, `pragmatic` = direct and practical)
+4. If character drifts after context compaction, the persona information in the compacted summary should restore it — follow it
+
+## Context Compaction Survival
+
+Long sessions trigger context compaction. To survive:
+
+- The persona activation state is included in compaction summaries
+- After compaction, check if persona was active and re-adopt the character
+- Never break character just because the conversation was compacted
+
+## Deactivation
+
+When the user says "deactivate", "stop persona", "be normal", or uses the agent's deactivation phrase:
+
+```
+YOUR_AGENT_core op:activate
+  params: { deactivate: true }
+```
+
+Return to neutral assistant mode.
+
+## Anti-Patterns
+
+- **Dropping character mid-session** — if activated, stay activated
+- **Over-persona, under-substance** — character adds flavor, not replaces technical depth
+- **Forcing persona on unwilling users** — only activate when explicitly triggered
+- **Ignoring tone setting** — a `precise` agent should not use flowery language; a `mentor` agent should not be terse

package/dist/skills/deep-review/SKILL.md

@@ -188,6 +188,18 @@ Only capture if genuinely reusable — not every review finding is vault-worthy.
 - Skipping git history (temporal smells are the most actionable)
 - Treating all smells as equal severity (prioritize by impact)
 
+## Rationalization Prevention
+
+Do NOT rationalize away findings. If a smell or issue is detected, report it honestly.
+
+- **HARD-GATE: All three passes must complete before presenting the report. Do not skip a pass.**
+- **HARD-GATE: Critical (red) findings must be flagged -- never downgrade severity to avoid difficult conversations.**
+- Do not say "this is probably fine" to dismiss a code smell you detected.
+- Do not omit findings because "the code works" -- working code can still be poorly architected.
+- Do not soften severity because the code is recent or written by the user.
+- If git history shows high churn, report it. Do not skip temporal smells for convenience.
+- Present the full picture. A review that hides problems is worse than no review.
+
 ## Quick Reference
 
 | Pass            | Focus            | Key Activities                                              |

package/dist/skills/deliver-and-ship/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: deliver-and-ship
+description: >
+  Use when the user says "ship it", "ready to deploy", "package", "release",
+  "pre-PR check", "delivery checklist", "is this ready", "final review", or mentions
+  shipping, deploying, packaging, or releasing work. Runs pre-delivery quality gates
+  to ensure nothing ships without passing stability, knowledge capture, and code quality checks.
+---
+
+# Deliver & Ship — Quality Gate Runner
+
+Run all pre-delivery quality gates before shipping. This ensures nothing leaves without passing stability checks, knowledge capture, and code quality verification.
+
+## When to Use
+
+When work is considered "done" and ready to be committed, PR'd, or deployed. This is the last checkpoint before code leaves the developer's hands.
+
+## Orchestration Sequence
+
+### Step 1: Code Quality
+
+Run the project's linter, formatter, and type checker on all modified files:
+
+1. Check for lint/format scripts in `package.json` (or equivalent)
+2. Run `typecheck` / `tsc --noEmit` if TypeScript
+3. Run any project-specific quality gates (clippy for Rust, mypy for Python, etc.)
+
+Any type error or lint failure is a blocker.
+
+### Step 2: Test Suite
+
+Run the full test suite to catch regressions:
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+Verify the agent itself is healthy, then run project tests. All tests must pass.
+
+### Step 3: Stability Assessment
+
+Classify the changes as safe or breaking:
+
+- **Safe**: Internal refactors, bug fixes, additive features (new exports, new ops)
+- **Breaking**: Removed exports, changed signatures, renamed public APIs, schema migrations
+- Breaking changes need migration guidance in the commit/PR description
+
+### Step 4: Knowledge Audit
+
+Check if patterns discovered during this work session should be captured before shipping:
+
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "current session" }
+```
+
+```
+YOUR_AGENT_core op:brain_stats
+```
+
+Look for:
+
+- Bug fixes that reveal an anti-pattern worth capturing
+- New patterns that should be in the vault for next time
+- Architectural decisions that need documenting
+
+Uncaptured knowledge is lost knowledge. If something should be captured:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<what was learned>",
+    description: "<the pattern or anti-pattern>",
+    type: "pattern",
+    tags: ["<relevant-tags>"]
+  }
+```
+
+### Step 5: Commit Quality
+
+Verify commit messages follow conventional commits:
+
+- `feat:` for new features
+- `fix:` for bug fixes
+- `refactor:` for refactors
+- `chore:` for maintenance
+- No AI attribution (blocked by engine rules)
+
+### Step 6: Delivery Report
+
+Present a checklist:
+
+- [ ] Code quality: pass/fail (Step 1)
+- [ ] Tests: pass/fail (Step 2)
+- [ ] Stability: safe change / breaking change (Step 3)
+- [ ] Knowledge: captured / needs capture (Step 4)
+- [ ] Commits: clean / needs cleanup (Step 5)
+
+All items must pass before recommending "ship it."
+
+## Domain-Specific Gates
+
+Agents with domain-specific facades may add extra gates. For example:
+
+- **Design system agents**: token validation, contrast checks, accessibility audit
+- **API agents**: schema validation, backward compatibility checks
+- **Security agents**: dependency audit, secret scanning
+
+These are additive — they don't replace the generic gates above.
+
+## Exit Criteria
+
+Delivery is approved when all gates pass. If any gate fails, report the failure and recommend fixes before shipping. Never approve delivery with blocking issues.
+
+## Agent Tools Reference
+
+| Op                  | When to Use                            |
+| ------------------- | -------------------------------------- |
+| `admin_health`      | Verify agent/system health             |
+| `memory_search`     | Check for uncaptured session knowledge |
+| `brain_stats`       | Review learning state                  |
+| `capture_knowledge` | Persist patterns before shipping       |
+| `capture_quick`     | Fast capture for simple learnings      |

package/dist/skills/discovery-phase/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: discovery-phase
+description: >
+  Use for structured exploration before committing to a plan — "I don't know where to start",
+  "what are our options", "investigate", "research this", "explore options", "discovery". Ideal
+  when requirements are unclear, entering a new domain, or facing architectural decisions. Produces
+  a discovery document with options, tradeoffs, and a recommendation.
+---
+
+# Discovery Phase
+
+Structured exploration before committing to a plan. Define the question, research prior art, explore the codebase, identify constraints, draft options with tradeoffs, and recommend a path forward.
+
+<HARD-GATE>
+Do NOT create a plan, write code, or take any implementation action until the discovery document is complete and the user has reviewed it. Discovery produces knowledge, not artifacts.
+</HARD-GATE>
+
+## Checklist
+
+1. **Define the question** — restate what we're exploring as one specific, answerable sentence
+2. **Search vault for prior art** — `YOUR_AGENT_core op:search_intelligent params: { query: "<question>", mode: "scan" }`. Also `op:memory_search` with `crossProject: true`.
+3. **Explore codebase** — read relevant files, configs, architecture, recent commits
+4. **Identify constraints** — hard (must-haves) vs soft (nice-to-haves), unknowns that block a decision
+5. **Draft 2-4 options** — each with pros, cons, risk, and effort (S/M/L)
+6. **Recommend** — pick one, state the primary reason, note what would change the answer
+7. **Capture to vault** — persist the discovery finding
+8. **Transition** — hand off to brainstorming or writing-plans skill
+
+## Option Format
+
+For each option:
+
+| Field        | Content              |
+| ------------ | -------------------- |
+| **Approach** | One-sentence summary |
+| **Pros**     | What it gives us     |
+| **Cons**     | What it costs        |
+| **Risk**     | What could go wrong  |
+| **Effort**   | S / M / L            |
+
+## After Discovery
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<topic> — discovery finding",
+    description: "<question, options considered, recommendation, rationale>",
+    type: "decision",
+    category: "<domain>",
+    tags: ["discovery", "decision"]
+  }
+```
+
+Save to `docs/discoveries/YYYY-MM-DD-<topic>.md` and commit. Then transition to the next skill.
+
+## Anti-Patterns
+
+- **Skipping discovery** — jumping to implementation when the problem space is unclear
+- **Analysis paralysis** — timebox to 30-60 min; if no clear winner, pick the most reversible option
+- **Boiling the ocean** — scope to one question; split compound questions into separate discoveries
+
+## Quick Reference
+
+| Op                   | When to Use                        |
+| -------------------- | ---------------------------------- |
+| `search_intelligent` | Search vault for prior art         |
+| `memory_search`      | Check session history and projects |
+| `capture_knowledge`  | Persist discovery finding          |
+| `route_intent`       | Classify what comes after          |