@soleri/forge 5.14.2 → 5.14.4

package/src/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.

package/src/skills/vault-curate.md

@@ -0,0 +1,107 @@
+---
+name: vault-curate
+description: >
+  Use when the user says "clean vault", "deduplicate", "groom knowledge",
+  "consolidate vault", "vault maintenance", "find duplicates", "merge patterns",
+  "check contradictions", "vault health", or wants to maintain, clean, reorganize,
+  or improve the quality of the agent's knowledge base.
+---
+
+# Vault Curate — Knowledge Maintenance
+
+Maintain vault quality through deduplication, grooming, contradiction detection, and consolidation. A well-curated vault produces better search results and brain recommendations.
+
+## When to Use
+
+Periodically (weekly or after heavy capture sessions), when search quality degrades, when vault health shows warnings, or when the user explicitly requests maintenance.
+
+## Orchestration Sequence
+
+### Step 1: Health Assessment
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+```
+YOUR_AGENT_core op:get_vault_analytics
+```
+
+Present the health summary to the user before proceeding: total entries, quality scores, staleness, coverage gaps.
+
+### Step 2: Detect Duplicates
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+This finds entries with overlapping titles, descriptions, or content. Review the duplicate pairs — some may be intentional (different contexts) while others are true duplicates.
+
+For true duplicates:
+
+```
+YOUR_AGENT_core op:merge_patterns
+  params: { patternIds: ["<id1>", "<id2>"] }
+```
+
+Preserve the best content from each.
+
+### Step 3: Find Contradictions
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+Contradictions erode trust in vault search results. For each contradiction: decide which entry is correct (check dates, context, evidence), then archive or update the incorrect one.
+
+### Step 4: Groom Entries
+
+```
+YOUR_AGENT_core op:curator_groom_all
+```
+
+Runs tag enrichment and metadata cleanup across all entries. This improves searchability and categorization.
+
+For targeted grooming of specific entries:
+
+```
+YOUR_AGENT_core op:curator_groom
+  params: { entryIds: ["<id>"], tags: ["<tag>"] }
+```
+
+### Step 5: GPT Enrichment (Optional)
+
+```
+YOUR_AGENT_core op:curator_gpt_enrich
+```
+
+Adds AI-generated metadata to entries that lack descriptions, examples, or context. Fills in gaps without changing the core content.
+
+### Step 6: Full Consolidation
+
+```
+YOUR_AGENT_core op:curator_consolidate
+```
+
+Runs the complete pipeline: dedup + archive stale entries + resolve contradictions. This is the heavy-duty cleanup.
+
+### Step 7: Knowledge Reorganization
+
+```
+YOUR_AGENT_core op:knowledge_reorganize
+  params: { mode: "preview" }
+```
+
+Preview first, then run again with `mode: "apply"` if the preview looks good.
+
+### Step 8: Verify Results
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+Compare with Step 1 metrics. Vault health should improve: fewer duplicates, no contradictions, better coverage.
+
+## Exit Criteria
+
+Curation is complete when: duplicates merged, contradictions resolved, entries groomed, and health metrics improved compared to Step 1 baseline.

package/src/templates/skills.ts

@@ -8,10 +8,13 @@ const SKILLS_DIR = join(__dirname, '..', 'skills');
 
 /** Skills that use YOUR_AGENT_core placeholder and need agent-specific substitution. */
 const AGENT_SPECIFIC_SKILLS = new Set([
+  'agent-dev',
+  'agent-persona',
   'brain-debrief',
   'brainstorming',
   'code-patrol',
   'context-resume',
+  'deliver-and-ship',
   'executing-plans',
   'fix-and-learn',
   'health-check',
@@ -22,6 +25,7 @@ const AGENT_SPECIFIC_SKILLS = new Set([
   'systematic-debugging',
   'test-driven-development',
   'vault-capture',
+  'vault-curate',
   'vault-navigator',
   'verification-before-completion',
   'writing-plans',