@soleri/forge 5.14.2 → 5.14.4

package/dist/skills/skills/writing-plans.md

@@ -0,0 +1,215 @@
+---
+name: writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+<!-- Adapted from superpowers (MIT License) -->
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Before Writing — Search First, Plan Second
+
+**Never write a plan from scratch.** Always search for existing knowledge first.
+
+### 1. Vault First
+
+Check the vault for relevant implementation patterns:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<feature being planned>" }
+```
+
+Look for:
+
+- **Implementation patterns** — proven approaches for similar features
+- **Anti-patterns** — approaches that failed and should be avoided
+- **Testing patterns** — how similar features were tested
+
+Also check brain strengths for what's worked:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+Browse related knowledge domains for additional context:
+
+```
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
+```
+
+### 2. Web Search Second
+
+If the vault doesn't have implementation guidance, search the web:
+
+- **Libraries and tools** — is there a package that does this already?
+- **Reference implementations** — how did other projects solve this?
+- **API documentation** — official docs for libraries you'll use
+- **Known issues** — pitfalls others ran into
+
+### 3. Then Write the Plan
+
+Incorporate vault insights and web findings into the plan. Reference specific vault entries and documentation links when they inform a step. A plan informed by existing knowledge is dramatically better than one written from first principles.
+
+## Create a Tracked Plan
+
+Use the agent's planning system to create a tracked, resumable plan:
+
+```
+YOUR_AGENT_core op:create_plan
+  params: {
+    objective: "<one-sentence goal>",
+    scope: { included: [...], excluded: [...] },
+    steps: [
+      { title: "Step 1 title", description: "details" },
+      ...
+    ]
+  }
+```
+
+This makes the plan persistent across sessions — if context compacts or sessions change, the plan survives.
+
+## Grade the Plan
+
+After drafting, grade the plan for quality before presenting to the user:
+
+```
+YOUR_AGENT_core op:plan_grade
+  params: { planId: "<id from create_plan>" }
+```
+
+If the grade is below target, auto-improve:
+
+```
+YOUR_AGENT_core op:plan_auto_improve
+  params: { planId: "<id>" }
+```
+
+This iterates on the plan — filling gaps, adding missing test steps, clarifying ambiguous instructions. Repeat until the grade meets the target:
+
+```
+YOUR_AGENT_core op:plan_meets_grade
+  params: { planId: "<id>", targetGrade: "A" }
+```
+
+### Iterate on Drafts
+
+For complex plans, iterate before finalizing:
+
+```
+YOUR_AGENT_core op:plan_iterate
+  params: { planId: "<id>", feedback: "<what needs improvement>" }
+```
+
+This creates a new version of the plan incorporating the feedback, preserving version history.
+
+## Split into Tasks
+
+Once the plan is approved, split it into trackable tasks:
+
+```
+YOUR_AGENT_core op:plan_split
+  params: { planId: "<id>" }
+```
+
+This generates individual tasks from the plan steps, ready for execution tracking.
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+## Task Structure
+
+Each task uses this format:
+
+- Files: Create / Modify / Test paths
+- Step 1: Write the failing test (with code)
+- Step 2: Run test to verify it fails (with expected output)
+- Step 3: Write minimal implementation (with code)
+- Step 4: Run test to verify it passes (with expected output)
+- Step 5: Commit (with exact git commands)
+
+## Remember
+
+- Exact file paths always
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- DRY, YAGNI, TDD, frequent commits
+
+## After Plan Approval
+
+Once the user approves the plan, register it for tracking:
+
+```
+YOUR_AGENT_core op:approve_plan
+  params: { planId: "<id from create_plan>" }
+```
+
+Check plan stats for an overview:
+
+```
+YOUR_AGENT_core op:plan_stats
+```
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+Which approach?"
+
+## Agent Tools Reference
+
+| Op                             | When to Use                            |
+| ------------------------------ | -------------------------------------- |
+| `search_intelligent`           | Find relevant patterns before planning |
+| `brain_strengths`              | Check proven approaches                |
+| `vault_domains` / `vault_tags` | Browse knowledge landscape             |
+| `create_plan`                  | Create tracked, persistent plan        |
+| `plan_grade`                   | Grade plan quality                     |
+| `plan_auto_improve`            | Auto-fix plan weaknesses               |
+| `plan_meets_grade`             | Verify grade target reached            |
+| `plan_iterate`                 | Iterate on draft with feedback         |
+| `plan_split`                   | Split plan into trackable tasks        |
+| `approve_plan`                 | Lock in approved plan                  |
+| `plan_stats`                   | Overview of plan metrics               |

package/dist/templates/skills.js

@@ -5,10 +5,13 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 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',
@@ -19,6 +22,7 @@ const AGENT_SPECIFIC_SKILLS = new Set([
     'systematic-debugging',
     'test-driven-development',
     'vault-capture',
+    'vault-curate',
     'vault-navigator',
     'verification-before-completion',
     'writing-plans',

package/dist/templates/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/templates/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAEnD,wFAAwF;AACxF,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,eAAe;IACf,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,iBAAiB;IACjB,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,YAAY;IACZ,eAAe;IACf,gBAAgB;IAChB,sBAAsB;IACtB,yBAAyB;IACzB,eAAe;IACf,iBAAiB;IACjB,gCAAgC;IAChC,eAAe;CAChB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,UAAoB,CAAC;IAEzB,IAAI,CAAC;QACH,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2DAA2D;IAC3D,gEAAgE;IAChE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,uCAAuC;IAE5G,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAE1C,IAAI,aAAa,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,SAAS;QACX,CAAC;QAED,IAAI,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAE5D,IAAI,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,SAAS,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/templates/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAEnD,wFAAwF;AACxF,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,WAAW;IACX,eAAe;IACf,eAAe;IACf,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,YAAY;IACZ,eAAe;IACf,gBAAgB;IAChB,sBAAsB;IACtB,yBAAyB;IACzB,eAAe;IACf,cAAc;IACd,iBAAiB;IACjB,gCAAgC;IAChC,eAAe;CAChB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,UAAoB,CAAC;IAEzB,IAAI,CAAC;QACH,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2DAA2D;IAC3D,gEAAgE;IAChE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,uCAAuC;IAE5G,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAE1C,IAAI,aAAa,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,SAAS;QACX,CAAC;QAED,IAAI,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAE5D,IAAI,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,SAAS,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleri/forge",
-  "version": "5.14.2",
+  "version": "5.14.4",
   "description": "Scaffold AI agents that learn, remember, and grow with you.",
   "keywords": [
     "agent",

package/src/__tests__/scaffolder.test.ts

@@ -262,7 +262,7 @@ describe('Scaffolder', () => {
         .filter((e) => e.isDirectory())
         .map((e) => e.name);
 
-      expect(skillDirs).toHaveLength(17);
+      expect(skillDirs).toHaveLength(22);
 
       // Verify each skill dir has a SKILL.md
       for (const dir of skillDirs) {
@@ -276,10 +276,14 @@ describe('Scaffolder', () => {
       const skillDirs = readdirSync(skillsDir).sort();
 
       expect(skillDirs).toEqual([
+        'agent-dev',
+        'agent-persona',
         'brain-debrief',
         'brainstorming',
         'code-patrol',
         'context-resume',
+        'deliver-and-ship',
+        'env-setup',
         'executing-plans',
         'fix-and-learn',
         'health-check',
@@ -290,6 +294,7 @@ describe('Scaffolder', () => {
         'systematic-debugging',
         'test-driven-development',
         'vault-capture',
+        'vault-curate',
         'vault-navigator',
         'verification-before-completion',
         'writing-plans',

package/src/skills/agent-dev.md

@@ -0,0 +1,122 @@
+---
+name: agent-dev
+description: >
+  Use when extending the agent itself — adding facades, tools, vault operations,
+  brain features, new skills, or modifying agent internals. Triggers on "add a facade",
+  "new tool", "extend vault", "add brain feature", "new skill", "add operation",
+  "extend agent", or when the work target is the agent's own codebase rather than
+  a project the agent assists with. Enforces vault-first knowledge gathering before
+  any code reading or planning.
+---
+
+# Agent Dev — Vault-First Internal Development
+
+Develop the agent's own internals with the vault as the primary source of truth. The vault knows more about the agent than any code scan or model training data. Always search the vault first, extract maximum context, and only then touch code.
+
+## When to Use
+
+Any time the work target is the agent's own codebase: adding tools, extending facades, modifying vault operations, brain features, skills, or transport. Not for projects that merely *use* the agent.
+
+## Core Principle
+
+**Vault first. Before code. Before training data. Always.**
+
+The vault is the authoritative source for how the agent works. Do not rely on general knowledge from training data — it is outdated and lacks project-specific decisions. Do not scan the codebase to understand architecture — the vault already has it.
+
+## Orchestration Sequence
+
+### Step 1: Search the Vault (MANDATORY — before anything else)
+
+Before reading any source file, before making any plan, before offering any advice:
+
+```
+YOUR_AGENT_core op:search_vault_intelligent
+  params: { query: "<description of planned work>", options: { intent: "pattern" } }
+```
+
+Search again with architecture-specific terms: the facade name, tool name, or subsystem being modified.
+
+```
+YOUR_AGENT_core op:query_vault_knowledge
+  params: { type: "workflow", category: "<relevant category>" }
+```
+
+If initial results are sparse, search again with broader terms — synonyms, related subsystem names, parent concepts. Exhaust the vault before moving on.
+
+Review all results. Extract file paths, module names, function references, conventions, and constraints. These become the foundation for every step that follows.
+
+### Step 2: Check Brain for Proven Patterns
+
+```
+YOUR_AGENT_core op:strengths
+  params: { days: 30, minStrength: 60 }
+```
+
+```
+YOUR_AGENT_core op:recommend
+  params: { projectPath: "." }
+```
+
+Check if the brain has learned anything relevant from recent sessions.
+
+### Step 3: Targeted Code Reading (Only What Vault Pointed To)
+
+By now the vault has provided architecture context, file paths, and module references. Only read code when the vault describes the subsystem but lacks implementation detail (e.g., method signatures, exact line numbers).
+
+**Read only what the vault pointed to.** Open the specific files referenced in vault results — not the surrounding codebase, not the parent directory, not "let me explore the project structure."
+
+**Fallback: Codebase scan.** Only when vault search returned zero relevant results for the subsystem — meaning the vault genuinely has no knowledge about it — fall back to `Grep` with targeted terms. This is the last resort, not the default.
+
+### Step 4: Plan with Vault Context
+
+Create the implementation plan referencing vault findings explicitly:
+
+- Which patterns apply (cite vault entry titles)
+- Which anti-patterns to avoid (cite the specific anti-pattern)
+- Which conventions to follow (naming, facade structure, tool registration)
+
+Every plan must trace its decisions back to vault knowledge. If a decision has no vault backing, flag it as a new architectural choice that should be captured after implementation (Step 7).
+
+### Step 5: Implement
+
+Follow the plan. Key conventions for agent internals:
+
+- **Facades**: Thin routing layer — delegate to domain modules. No business logic in facades.
+- **Tools**: Follow `op:operation_name` naming, return structured responses.
+- **Vault writes**: All writes go through the vault intelligence layer.
+- **Tests**: Colocated test files. Run with vitest.
+- **Build**: Must compile without errors before considering done.
+
+### Step 6: Validate and Self-Correct
+
+Run the relevant test suite. Rebuild — must complete without errors.
+
+**Self-correction loop:** If tests fail or build breaks, do NOT ask the user what to do. Read the error, trace the cause in the code just written, fix it, and re-run. Repeat until green. The agent owns the code it wrote — if something fails, the agent fixes its own implementation. Only escalate to the user when the failure is outside the agent's control (missing infrastructure, permissions, unclear requirements).
+
+### Step 7: Capture What Was Learned
+
+If this work revealed new architectural knowledge, a useful pattern, or a surprising anti-pattern:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<what was learned>",
+    description: "<the pattern or anti-pattern>",
+    type: "pattern",
+    tags: ["<relevant-tags>"]
+  }
+```
+
+This ensures future sessions benefit from today's discovery — making the vault smarter for the next developer.
+
+## Anti-Patterns to Avoid
+
+- **Code-first exploration**: Reading source files before searching the vault. The vault already has the architecture — scanning code is slower and gives less context.
+- **Training-data advice**: Offering general guidance from model training data instead of searching the vault for project-specific knowledge.
+- **Skipping vault search**: The vault contains all architecture knowledge. Not searching it means reinventing knowledge that already exists.
+- **Planning without vault context**: Plans created without vault knowledge miss conventions, duplicate existing patterns, or violate architectural boundaries.
+- **Broad codebase scanning**: Exploring directories and reading files "to understand the project" instead of using vault results as a targeted map.
+
+## Exit Criteria
+
+Development is complete when: vault was searched exhaustively first (Step 1), implementation follows discovered patterns, tests pass, build succeeds, and any new learning is captured back to vault (Step 7).

package/src/skills/agent-persona.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 `src/identity/persona.ts` (or `src/activation/persona.ts` in older agents). This file 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/src/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 |