@soleri/forge 5.14.2 → 5.14.4

package/dist/skills/skills/code-patrol.md

@@ -0,0 +1,178 @@
+---
+name: code-patrol
+description: Use when the user asks "review this code", "check this against patterns", "code patrol", "does this follow our rules", "validate against vault", "check for anti-patterns", or wants code reviewed not against generic lint rules but against the project's own captured patterns, anti-patterns, and conventions.
+---
+
+# Code Patrol — Review Code Against Your Own Knowledge
+
+Review code against the vault's patterns, anti-patterns, and project conventions — not generic lint rules, but YOUR team's captured knowledge applied to new code. Catches violations that no linter knows about.
+
+## When to Use
+
+- Before committing or creating a PR
+- "Does this follow our patterns?"
+- "Check this code against our rules"
+- Code review with institutional knowledge
+- After writing implementation code
+
+## The Magic: Project-Specific Code Intelligence
+
+### Step 1: Understand the Code's Domain
+
+Classify what domain this code belongs to:
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "Code review: <brief description of the code>" }
+```
+
+Determine which vault domains are relevant:
+
+```
+YOUR_AGENT_core op:vault_domains
+```
+
+### Step 2: Load Relevant Patterns
+
+Search for patterns in the code's domain:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<what this code does>" }
+```
+
+Search specifically for anti-patterns to check against:
+
+```
+YOUR_AGENT_core op:search
+  params: { type: "anti-pattern" }
+```
+
+Search for critical rules that must not be violated:
+
+```
+YOUR_AGENT_core op:search
+  params: { severity: "critical" }
+```
+
+Load project-specific rules:
+
+```
+YOUR_AGENT_core op:project_list_rules
+```
+
+```
+YOUR_AGENT_core op:get_behavior_rules
+```
+
+Get proven approaches from the brain:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+### Step 3: Review the Code
+
+With vault patterns loaded, review the code checking for:
+
+| Check                                  | Source                        | Severity      |
+| -------------------------------------- | ----------------------------- | ------------- |
+| Violates a critical rule               | `search (severity: critical)` | Must fix      |
+| Matches a known anti-pattern           | `search (type: anti-pattern)` | Must fix      |
+| Doesn't follow a proven pattern        | `brain_strengths`             | Should fix    |
+| Breaks project conventions             | `project_list_rules`          | Should fix    |
+| Misses an opportunity to use a pattern | `search_intelligent`          | Could improve |
+
+### Step 4: Present the Review
+
+```
+## Code Patrol Report
+
+### Must Fix (Critical)
+- **[Rule name]**: [What's wrong and why]
+  Vault ref: [entry title] (severity: critical)
+  Fix: [How to fix it]
+
+### Should Fix (Warning)
+- **[Anti-pattern name]**: [What's wrong]
+  Vault ref: [entry title] (type: anti-pattern)
+  Better approach: [The pattern to follow]
+
+### Could Improve (Suggestion)
+- **[Pattern opportunity]**: [The code works but could benefit from...]
+  Vault ref: [entry title] (type: pattern)
+
+### Looks Good
+- [What the code does well — patterns it follows correctly]
+
+### Summary
+X critical issues, Y warnings, Z suggestions
+Patterns followed: [list]
+Patterns missed: [list]
+```
+
+### Step 5: Learn From the Review
+
+If the review reveals a new pattern or anti-pattern not in the vault, capture it:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: {
+    title: "<new pattern or anti-pattern discovered>",
+    description: "<what it is, when it applies>"
+  }
+```
+
+If the review reveals a knowledge gap, note it:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<missing convention>",
+    description: "<this should be documented as a project rule>",
+    type: "principle",
+    category: "<domain>",
+    tags: ["convention", "code-review"]
+  }
+```
+
+### Step 6: Verify After Fixes
+
+After the user applies fixes, re-run the patrol to confirm clean:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<re-check the specific violations>" }
+```
+
+Check system health:
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+## The Magic
+
+This feels like magic because:
+
+1. It's not ESLint — it catches things like "we decided not to use inheritance here" or "this API pattern caused production issues last month"
+2. The rules come from YOUR team's experience, not a generic config file
+3. It gets smarter over time — every captured pattern becomes a new check
+4. It catches institutional knowledge violations that no static analyzer can
+
+A linter checks syntax. Code patrol checks wisdom.
+
+## Agent Tools Reference
+
+| Op                   | When to Use                                   |
+| -------------------- | --------------------------------------------- |
+| `route_intent`       | Classify the code's domain                    |
+| `vault_domains`      | See which domains are relevant                |
+| `search_intelligent` | Find relevant patterns for this code          |
+| `search`             | Find anti-patterns and critical rules         |
+| `project_list_rules` | Project-specific conventions                  |
+| `get_behavior_rules` | Behavioral rules                              |
+| `brain_strengths`    | Proven patterns to check against              |
+| `capture_quick`      | Capture new patterns discovered during review |
+| `capture_knowledge`  | Capture new conventions                       |
+| `admin_health`       | Post-review health check                      |

package/dist/skills/skills/context-resume.md

@@ -0,0 +1,146 @@
+---
+name: context-resume
+description: Use when starting a new session, returning to work, or when the user asks "what was I working on", "where did I leave off", "catch me up", "morning standup", "resume", "what's the status". Reconstructs full working context from memory, plans, and sessions.
+---
+
+# Context Resume — Pick Up Where You Left Off
+
+Reconstruct your full working context in seconds. Chains memory, plans, sessions, and brain to rebuild exactly where you left off — even across session boundaries and context compactions.
+
+## When to Use
+
+- Starting a new Claude Code session
+- Returning after a break
+- "What was I working on?"
+- "Morning standup"
+- After context compaction (session_capture fires automatically, this reads it back)
+
+## The Magic: Full Context Reconstruction
+
+### Step 1: Load Active Plans
+
+Check for plans in progress — these are your active work streams:
+
+```
+YOUR_AGENT_core op:plan_stats
+```
+
+For each active plan, load its details and task status:
+
+```
+YOUR_AGENT_core op:get_plan
+YOUR_AGENT_core op:plan_list_tasks
+  params: { planId: "<id>" }
+```
+
+Present:
+
+- Plan objective and current status
+- Which tasks are completed, in progress, or pending
+- What's next to do
+
+### Step 2: Search Recent Memory
+
+Load the latest session summaries — these capture what happened before:
+
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "session summary" }
+```
+
+```
+YOUR_AGENT_core op:memory_list
+```
+
+Also check recent vault captures — what knowledge was added recently?
+
+```
+YOUR_AGENT_core op:vault_recent
+```
+
+### Step 3: Check Active Loops
+
+See if there's a validation loop in progress:
+
+```
+YOUR_AGENT_core op:loop_is_active
+```
+
+If active:
+
+```
+YOUR_AGENT_core op:loop_status
+```
+
+This tells you if an iterative workflow (TDD, debugging, migration) was mid-flight.
+
+### Step 4: Brain Snapshot
+
+Get the latest brain insights relevant to current work:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+### Step 5: System Health
+
+Quick health check to make sure everything is working:
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+## Presenting the Resume
+
+Format as a concise standup:
+
+```
+## Where You Left Off
+
+**Active Plans:**
+- [Plan name] — X/Y tasks complete, next: [task description]
+
+**Last Session:**
+- [Summary from memory — what was done, key decisions]
+
+**Recent Captures:**
+- [New patterns/anti-patterns added to vault]
+
+**Active Loops:**
+- [Any in-progress validation loops]
+
+**Brain Says:**
+- [Top relevant patterns for current work]
+
+**Health:** [OK / Issues found]
+
+## Recommended Next Step
+[Based on active plans and last session context]
+```
+
+## The Magic
+
+This feels like magic because the user just says "catch me up" and the agent:
+
+1. Knows what plans are active and where they stand
+2. Remembers what happened last session (even across context compactions)
+3. Shows what knowledge was recently captured
+4. Detects in-flight loops
+5. Recommends what to work on next
+
+No other tool does this — the agent has genuine persistent memory.
+
+## Agent Tools Reference
+
+| Op                | When to Use                 |
+| ----------------- | --------------------------- |
+| `plan_stats`      | Find active plans           |
+| `get_plan`        | Load plan details           |
+| `plan_list_tasks` | See task status within plan |
+| `memory_search`   | Find session summaries      |
+| `memory_list`     | Browse recent memories      |
+| `vault_recent`    | Recently captured knowledge |
+| `loop_is_active`  | Check for in-flight loops   |
+| `loop_status`     | Get loop details            |
+| `brain_strengths` | Relevant proven patterns    |
+| `admin_health`    | System health check         |

package/dist/skills/skills/deliver-and-ship.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/skills/env-setup.md

@@ -0,0 +1,151 @@
+---
+name: env-setup
+description: >
+  Use when a developer needs to set up, fix, or restore a local development environment.
+  Triggers on post-clone setup, project onboarding, first-time running a repo, pulled changes
+  that broke the build, missing or misconfigured dependencies, MODULE_NOT_FOUND or Cannot find
+  module errors, gyp ERR or native module build failures, missing .env files or unknown required
+  environment variables, database setup, Docker compose issues, or connection refused during
+  local dev. Covers Node.js, Python, Rust, Go, Ruby, PHP, and Docker-based projects.
+---
+
+# Environment Setup
+
+Detect what a project needs, diagnose what's missing, and produce an actionable setup checklist.
+
+## Overview
+
+Scan the project root for configuration files, detect the tech stack and dependencies, identify gaps between what's required and what's present, then generate ordered setup steps. Offer to execute each step.
+
+## When to Use
+
+- Just cloned a repo and need to get it running
+- Getting errors after pulling changes (missing deps, env vars, DB migrations)
+- Onboarding to an unfamiliar project
+- Setting up a project on a new machine
+- Docker/container environment not starting
+- Missing `.env` file or environment variables
+
+## Detection Phase
+
+Scan the project root and identify:
+
+### Package Managers & Dependencies
+
+| File | Stack | Install Command |
+|------|-------|-----------------|
+| `package.json` | Node.js | `npm install` / `yarn` / `pnpm install` (check for lockfile) |
+| `requirements.txt` | Python | `pip install -r requirements.txt` |
+| `pyproject.toml` | Python | `pip install -e .` or `poetry install` or `uv sync` |
+| `Pipfile` | Python | `pipenv install` |
+| `Cargo.toml` | Rust | `cargo build` |
+| `go.mod` | Go | `go mod download` |
+| `Gemfile` | Ruby | `bundle install` |
+| `composer.json` | PHP | `composer install` |
+
+**Lockfile priority:** If a lockfile exists (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Pipfile.lock`, `poetry.lock`), use the matching package manager. Don't mix.
+
+### Environment Variables
+
+1. Check for `.env.example`, `.env.sample`, `.env.template`
+2. Check for existing `.env` — if missing, copy from template
+3. Parse template for required variables (lines without defaults or with placeholder values)
+4. Flag variables that need real values (API keys, secrets, database URLs)
+5. **If no template exists:** grep source for `process.env.`, `os.environ`, `env::var`, `os.Getenv` to discover env vars the project actually uses.
+
+### Native Dependencies
+
+| Indicator | What It Means |
+|-----------|--------------|
+| `better-sqlite3`, `sqlite3` in deps | Needs C++ compiler |
+| `node-gyp` in deps or scripts | Needs Python 3 + C++ toolchain |
+| `sharp` in deps | Needs `libvips` |
+| `Cargo.toml` with `[build-dependencies]` | Needs Rust toolchain for build scripts |
+| `setup.py` with `ext_modules` | Needs C compiler for Python extensions |
+
+### Databases
+
+| File/Config | Database | Setup Needed |
+|-------------|----------|-------------|
+| `docker-compose.yml` with postgres/mysql | PostgreSQL/MySQL | Container + migrations |
+| `prisma/schema.prisma` | Prisma-managed | `npx prisma migrate dev` |
+| `drizzle.config.*` | Drizzle-managed | `npx drizzle-kit push` |
+| `alembic.ini` | SQLAlchemy | `alembic upgrade head` |
+| `config/database.yml` | Rails | `rails db:create db:migrate` |
+
+### Infrastructure
+
+| File | What It Means |
+|------|--------------|
+| `docker-compose.yml` | Services to start with `docker compose up` |
+| `Dockerfile` | Can build container locally |
+| `Makefile` | Check for `setup`, `install`, `dev` targets |
+| `.tool-versions` / `.node-version` / `.nvmrc` | Required runtime version |
+| `turbo.json` / `nx.json` / `lerna.json` | Monorepo setup |
+
+### IDE & Tool Integration
+
+| File | Integration |
+|------|------------|
+| `.vscode/` | VS Code settings, extensions |
+| `.mcp.json` / `mcp.json` | MCP server config |
+| `.editorconfig` | Cross-editor formatting |
+
+## Diagnosis Phase
+
+After detection, check what's present vs needed:
+
+1. **Runtime version** — does installed version match version files?
+2. **Dependencies installed?** — does `node_modules/`, `venv/`, `vendor/` exist?
+3. **Native build tools?** — are compilers available?
+4. **Env file present?** — does `.env` exist when a template does?
+5. **Database reachable?** — can the configured DB URL connect?
+6. **Docker running?** — is Docker daemon running if needed?
+7. **Build artifacts** — does the project need an initial build step?
+
+## Checklist Generation
+
+Produce steps in dependency order:
+
+```
+## Setup Checklist
+
+1. [ ] Install runtime (Node 20.x via nvm)
+2. [ ] Install dependencies (pnpm install)
+3. [ ] Copy environment file (cp .env.example .env)
+4. [ ] Fill in required env vars: DATABASE_URL, API_KEY
+5. [ ] Start Docker services (docker compose up -d)
+6. [ ] Run database migrations (npx prisma migrate dev)
+7. [ ] Build the project (pnpm build)
+8. [ ] Start dev server (pnpm dev)
+```
+
+**Order matters:** runtime → deps → env → infrastructure → migrations → build → run.
+
+After presenting the checklist, offer: "Want me to run these steps for you?"
+
+## Execution Phase
+
+If the user says yes, execute steps sequentially. Stop and ask if:
+
+- A step fails
+- A step requires manual input (API keys, passwords)
+- A step would modify system-level config (global installs, PATH changes)
+
+## Monorepo Handling
+
+If monorepo detected (turbo.json, nx.json, pnpm-workspace.yaml):
+
+1. Install root dependencies first
+2. Ask which package/app the user wants to work on
+3. Check for package-specific setup
+4. Run package-specific setup after root
+
+## Common Mistakes
+
+- **Wrong package manager** — using `npm install` when `yarn.lock` exists. Always check lockfiles first.
+- **Skipping env file** — project crashes on first API call. Always check for templates.
+- **Missing native build tools** — `npm install` fails with gyp errors. Check before installing.
+- **Missing runtime version** — subtle bugs from wrong Node/Python version.
+- **Docker not running** — cryptic "connection refused" errors.
+- **Stale dependencies** — after `git pull`, always re-install if lockfile changed.