@openlife/cli 1.7.3

package/dist/test_workflow_parser.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * test_workflow_parser — Story 4.1 regression suite.
+ *
+ * Validates the WorkflowSchema + WorkflowParser contract via 8 scenarios:
+ *   1. Happy path — minimal valid workflow round-trips
+ *   2. Multi-phase fixture — greenfield-like document parses
+ *   3. Missing root `workflow:` key fails with MISSING_ROOT
+ *   4. Invalid type fails with INVALID_TYPE
+ *   5. Step missing both agent and squad fails with NEITHER_AGENT_NOR_SQUAD
+ *   6. Duplicate step id fails with DUPLICATE_STEP_ID
+ *   7. Unknown requires (step-id-shaped) fails with UNKNOWN_REQUIRES
+ *   8. Circular requires chain detected with CIRCULAR_REQUIRES
+ *
+ * Prints TEST_WORKFLOW_PARSER_OK on full pass.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const WorkflowParser_1 = require("./orchestrator/workflow/WorkflowParser");
+const WorkflowSchema_1 = require("./orchestrator/workflow/WorkflowSchema");
+function assert(cond, msg) {
+    if (!cond)
+        throw new Error(`assertion failed: ${msg}`);
+}
+function assertHasError(result, expectedCode, scenario) {
+    assert(!result.ok, `${scenario}: expected ok=false, got ok=true`);
+    const match = result.errors.find((e) => e.code === expectedCode);
+    assert(match !== undefined, `${scenario}: expected error code '${expectedCode}', got [${result.errors.map((e) => e.code).join(', ')}]`);
+}
+// ─────────────────────────────────────────────────────────────
+// Scenario 1 — Happy path
+// ─────────────────────────────────────────────────────────────
+function scenarioHappyPath() {
+    const yaml = `
+workflow:
+  id: minimal-test
+  name: Minimal Test
+  description: A minimal valid workflow
+  type: custom
+  version: "1.0"
+  sequence:
+    - id: step-1
+      agent: dev
+      action: do-thing
+      creates: [out.md]
+`;
+    const r = (0, WorkflowParser_1.parseWorkflow)(yaml);
+    assert(r.ok, `happy path must succeed, errors: ${JSON.stringify(r.errors)}`);
+    assert(r.workflow?.id === 'minimal-test', 'id round-trip');
+    assert(r.workflow?.type === 'custom', 'type round-trip');
+    assert(r.workflow?.sequence.length === 1, 'sequence length');
+    console.log('✅ scenario 1: happy path');
+}
+// ─────────────────────────────────────────────────────────────
+// Scenario 2 — Multi-phase fixture (squad+agent mix)
+// ─────────────────────────────────────────────────────────────
+function scenarioMultiPhaseShape() {
+    const yaml = `
+workflow:
+  id: greenfield-like
+  name: Greenfield-Like
+  description: Mirrors the greenfield-fullstack structure
+  type: greenfield
+  version: "1.0"
+  project_types: [web-app, saas]
+  metadata:
+    elicit: true
+    confirmation_required: true
+  phases:
+    - phase_0: Bootstrap
+    - phase_1: Discovery
+  sequence:
+    - phase: 0
+      name: Bootstrap
+      description: Setup
+    - id: env-bootstrap
+      agent: devops
+      action: environment_bootstrap
+      duration_estimate: "15-30 min"
+      creates: [.openlife/config.yaml, README.md]
+      task: environment-bootstrap.md
+
+    - phase: 1
+      name: Discovery
+      description: Plan everything
+
+    - id: project-brief
+      agent: analyst
+      creates: project-brief.md
+      duration_estimate: "30-60 min"
+      requires: env-bootstrap
+
+    - id: design-review
+      squad: design-squad
+      action: review-design
+      requires: project-brief
+      idempotent: true
+`;
+    const r = (0, WorkflowParser_1.parseWorkflow)(yaml);
+    assert(r.ok, `multi-phase shape must succeed, errors: ${JSON.stringify(r.errors)}`);
+    assert(r.workflow?.sequence.length === 5, `expected 5 sequence entries, got ${r.workflow?.sequence.length}`);
+    assert(r.workflow?.project_types?.includes('saas'), 'project_types round-trip');
+    assert(r.workflow?.metadata?.elicit === true, 'metadata.elicit round-trip');
+    console.log('✅ scenario 2: multi-phase (squad+agent mix)');
+}
+// ─────────────────────────────────────────────────────────────
+// Scenario 3 — Missing `workflow:` root
+// ─────────────────────────────────────────────────────────────
+function scenarioMissingRoot() {
+    const yaml = `
+id: orphan
+name: Orphan
+type: custom
+version: "1.0"
+sequence: []
+`;
+    const r = (0, WorkflowParser_1.parseWorkflow)(yaml);
+    assertHasError(r, WorkflowSchema_1.WORKFLOW_ERRORS.MISSING_ROOT, 'missing root');
+    console.log('✅ scenario 3: missing root (no `workflow:` key)');
+}
+// ─────────────────────────────────────────────────────────────
+// Scenario 4 — Invalid type value
+// ─────────────────────────────────────────────────────────────
+function scenarioInvalidType() {
+    const yaml = `
+workflow:
+  id: bad-type
+  name: Bad Type
+  type: nonsense
+  version: "1.0"
+  sequence:
+    - id: step-1
+      agent: dev
+`;
+    const r = (0, WorkflowParser_1.parseWorkflow)(yaml);
+    assertHasError(r, WorkflowSchema_1.WORKFLOW_ERRORS.INVALID_TYPE, 'invalid type');
+    console.log('✅ scenario 4: invalid type value');
+}
+// ─────────────────────────────────────────────────────────────
+// Scenario 5 — Step with neither agent nor squad
+// ─────────────────────────────────────────────────────────────
+function scenarioNoAgentOrSquad() {
+    const yaml = `
+workflow:
+  id: no-actor
+  name: No Actor
+  type: custom
+  version: "1.0"
+  sequence:
+    - id: orphan-step
+      action: do-thing
+`;
+    const r = (0, WorkflowParser_1.parseWorkflow)(yaml);
+    assertHasError(r, WorkflowSchema_1.WORKFLOW_ERRORS.NEITHER_AGENT_NOR_SQUAD, 'no agent or squad');
+    console.log('✅ scenario 5: step without agent or squad');
+}
+// ─────────────────────────────────────────────────────────────
+// Scenario 6 — Duplicate step id
+// ─────────────────────────────────────────────────────────────
+function scenarioDuplicateStepId() {
+    const yaml = `
+workflow:
+  id: dup-test
+  name: Dup Test
+  type: custom
+  version: "1.0"
+  sequence:
+    - id: step-a
+      agent: dev
+    - id: step-a
+      agent: qa
+`;
+    const r = (0, WorkflowParser_1.parseWorkflow)(yaml);
+    assertHasError(r, WorkflowSchema_1.WORKFLOW_ERRORS.DUPLICATE_STEP_ID, 'duplicate step id');
+    console.log('✅ scenario 6: duplicate step id');
+}
+// ─────────────────────────────────────────────────────────────
+// Scenario 7 — Unknown requires (step-id-shaped)
+// ─────────────────────────────────────────────────────────────
+function scenarioUnknownRequires() {
+    const yaml = `
+workflow:
+  id: req-test
+  name: Req Test
+  type: custom
+  version: "1.0"
+  sequence:
+    - id: step-a
+      agent: dev
+      requires: ghost-step
+`;
+    const r = (0, WorkflowParser_1.parseWorkflow)(yaml);
+    assertHasError(r, WorkflowSchema_1.WORKFLOW_ERRORS.UNKNOWN_REQUIRES, 'unknown requires');
+    console.log('✅ scenario 7: unknown requires (step-id-shaped)');
+}
+// ─────────────────────────────────────────────────────────────
+// Scenario 8 — Circular requires chain
+// ─────────────────────────────────────────────────────────────
+function scenarioCircularRequires() {
+    const yaml = `
+workflow:
+  id: cycle-test
+  name: Cycle Test
+  type: custom
+  version: "1.0"
+  sequence:
+    - id: step-a
+      agent: dev
+      requires: step-b
+    - id: step-b
+      agent: dev
+      requires: step-c
+    - id: step-c
+      agent: dev
+      requires: step-a
+`;
+    const r = (0, WorkflowParser_1.parseWorkflow)(yaml);
+    assertHasError(r, WorkflowSchema_1.WORKFLOW_ERRORS.CIRCULAR_REQUIRES, 'circular requires');
+    console.log('✅ scenario 8: circular requires chain');
+}
+// ─────────────────────────────────────────────────────────────
+// Driver
+// ─────────────────────────────────────────────────────────────
+function main() {
+    console.log('🧪 test_workflow_parser — Story 4.1 regression suite');
+    scenarioHappyPath();
+    scenarioMultiPhaseShape();
+    scenarioMissingRoot();
+    scenarioInvalidType();
+    scenarioNoAgentOrSquad();
+    scenarioDuplicateStepId();
+    scenarioUnknownRequires();
+    scenarioCircularRequires();
+    // Smoke-check the file loader exists and reports missing files cleanly
+    const r = (0, WorkflowParser_1.parseWorkflowFile)('/nonexistent/path/to/workflow.yaml');
+    assert(!r.ok, 'parseWorkflowFile must return ok=false for missing path');
+    console.log('');
+    console.log('TEST_WORKFLOW_PARSER_OK');
+}
+try {
+    main();
+}
+catch (err) {
+    console.error('❌ test_workflow_parser FAILED:', err instanceof Error ? err.message : err);
+    process.exit(1);
+}

package/dist/test_workflow_schema_backward_compat.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * test_workflow_schema_backward_compat.ts — Stories 2.1 + 2.2
+ *
+ * The Workflow schema gained 15 new optional fields in v1.3. This test
+ * proves the v1.2 fixtures (the 4 ported workflows shipped in
+ * dist-templates/workflows/) still parse cleanly with the v2 parser.
+ *
+ * Also asserts the new v1.3 error codes fire on invalid values for
+ * mode / status / triggers / tools / success_criteria.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const WorkflowParser_1 = require("./orchestrator/workflow/WorkflowParser");
+const WorkflowSchema_1 = require("./orchestrator/workflow/WorkflowSchema");
+function assertTrue(cond, label) {
+    if (!cond)
+        throw new Error(`ASSERT_FAILED[${label}]`);
+}
+function assertErrorCode(errors, code, label) {
+    if (!errors.some((e) => e.code === code)) {
+        throw new Error(`ASSERT_FAILED[${label}]: expected ${code}, got ${JSON.stringify(errors.map((e) => e.code))}`);
+    }
+}
+// ─── v1.2 backward-compat: all 4 ported workflows must still parse ───
+const wfDir = path.join(process.cwd(), 'dist-templates', 'workflows');
+const yamls = fs.readdirSync(wfDir).filter((f) => f.endsWith('.yaml'));
+assertTrue(yamls.length >= 4, `at least 4 fixtures present (found ${yamls.length})`);
+for (const f of yamls) {
+    const r = (0, WorkflowParser_1.parseWorkflowFile)(path.join(wfDir, f));
+    assertTrue(r.ok, `v1.2 fixture parses: ${f}`);
+}
+console.log(`[2.1/2.2] backward-compat: ${yamls.length}/${yamls.length} v1.2 fixtures parse cleanly ✓`);
+// ─── v1.3 minimum field set still works ──────────────────────────────
+const minimalV2 = `
+workflow:
+  id: v2-minimal
+  name: v2 Minimal
+  type: custom
+  version: "1.0"
+  sequence:
+    - id: only-step
+      agent: dev
+      action: do-the-thing
+`;
+const m = (0, WorkflowParser_1.parseWorkflow)(minimalV2);
+assertTrue(m.ok, 'minimal v2 parses');
+assertTrue(m.workflow?.mode === undefined, 'mode defaults to undefined (engine reads as task)');
+console.log('[2.1] minimal v2 parses ✓');
+// ─── v1.3 full field set parses ──────────────────────────────────────
+const fullV2 = `
+workflow:
+  id: v2-full
+  name: Full v2
+  type: custom
+  version: "1.0"
+  status: tested
+  mode: service
+  triggers: [manual, cron]
+  objective: "demonstrate every v1.3 field round-trip"
+  success_criteria:
+    - { id: complete-no-error, description: "all steps reach completion" }
+  inputs:
+    - { id: brief, type: string, required: true, description: "the brief" }
+  outputs:
+    - { id: report, type: string, description: "final report path" }
+  required_context: ["docs/research-policy.md"]
+  squads: ["design-squad"]
+  skills: ["analysis"]
+  tools:
+    allowed: [file, web]
+    forbidden: [terminal]
+  policies: ["no-uncited-claims"]
+  validation:
+    - { id: report-exists, description: "report must exist", kind: artifact_exists }
+  evidence: ["report.md"]
+  failure_handling:
+    on_step_failure: retry
+    max_retries: 2
+  audit_events: ["workflow.completed"]
+  learning_rules:
+    - { id: store-success, trigger: on_success, description: "remember this pattern" }
+  sequence:
+    - id: step-1
+      agent: dev
+      action: build
+`;
+const f2 = (0, WorkflowParser_1.parseWorkflow)(fullV2);
+assertTrue(f2.ok, `full v2 parses (errors=${JSON.stringify(f2.errors)})`);
+assertTrue(f2.workflow?.mode === 'service', 'mode round-trip');
+assertTrue(f2.workflow?.status === 'tested', 'status round-trip');
+assertTrue(f2.workflow?.triggers?.length === 2, 'triggers round-trip');
+assertTrue(f2.workflow?.tools?.forbidden?.[0] === 'terminal', 'tools.forbidden round-trip');
+assertTrue(f2.workflow?.success_criteria?.[0].id === 'complete-no-error', 'success_criteria round-trip');
+console.log('[2.1] full v2 round-trip ✓');
+// ─── v1.3 error codes ────────────────────────────────────────────────
+const badMode = `
+workflow:
+  id: bad
+  name: Bad
+  type: custom
+  version: "1.0"
+  mode: forever
+  sequence:
+    - id: x
+      agent: y
+      action: z
+`;
+const bm = (0, WorkflowParser_1.parseWorkflow)(badMode);
+assertTrue(!bm.ok, 'invalid mode fails');
+assertErrorCode(bm.errors, WorkflowSchema_1.WORKFLOW_ERRORS.INVALID_MODE, 'INVALID_MODE');
+console.log('[2.2] INVALID_MODE ✓');
+const badTrig = `
+workflow:
+  id: bad
+  name: Bad
+  type: custom
+  version: "1.0"
+  triggers: [supernova]
+  sequence:
+    - id: x
+      agent: y
+      action: z
+`;
+const bt = (0, WorkflowParser_1.parseWorkflow)(badTrig);
+assertTrue(!bt.ok, 'invalid trigger fails');
+assertErrorCode(bt.errors, WorkflowSchema_1.WORKFLOW_ERRORS.INVALID_TRIGGERS, 'INVALID_TRIGGERS');
+console.log('[2.2] INVALID_TRIGGERS ✓');
+const badTools = `
+workflow:
+  id: bad
+  name: Bad
+  type: custom
+  version: "1.0"
+  tools:
+    forbidden: "everything"
+  sequence:
+    - id: x
+      agent: y
+      action: z
+`;
+const btools = (0, WorkflowParser_1.parseWorkflow)(badTools);
+assertTrue(!btools.ok, 'invalid tools.forbidden fails');
+assertErrorCode(btools.errors, WorkflowSchema_1.WORKFLOW_ERRORS.INVALID_TOOLS_POLICY, 'INVALID_TOOLS_POLICY');
+console.log('[2.2] INVALID_TOOLS_POLICY ✓');
+const badCrit = `
+workflow:
+  id: bad
+  name: Bad
+  type: custom
+  version: "1.0"
+  success_criteria:
+    - "just a string, not an object"
+  sequence:
+    - id: x
+      agent: y
+      action: z
+`;
+const bc = (0, WorkflowParser_1.parseWorkflow)(badCrit);
+assertTrue(!bc.ok, 'invalid success_criteria fails');
+assertErrorCode(bc.errors, WorkflowSchema_1.WORKFLOW_ERRORS.INVALID_SUCCESS_CRITERIA, 'INVALID_SUCCESS_CRITERIA');
+console.log('[2.2] INVALID_SUCCESS_CRITERIA ✓');
+console.log('TEST_WORKFLOW_SCHEMA_BACKWARD_COMPAT_OK');

package/dist-templates/README.md

@@ -0,0 +1,91 @@
+# dist-templates/
+
+Templates that OpenLife installs into a host CLI when the user runs `openlife system setup --host <host>`.
+
+This directory is **part of the npm distribution** (see the `files` array in `package.json`) — it ships to consumers of `@open-life/cli` so the installer can copy artifacts into the host without needing network access.
+
+## Layout
+
+```
+dist-templates/
+└── claude-code/           # Host: claude-code (Story 3.2 — Claude Code first)
+    ├── agents/            # Copied to <project>/.claude/agents/
+    ├── commands/          # Copied to <project>/.claude/commands/
+    └── mcp/               # Merged into ~/.claude.json mcpServers section
+```
+
+Future hosts (Story 3.3+):
+
+```
+dist-templates/
+├── claude-code/           # ← shipped now
+├── gemini-cli/            # ← Story 3.3
+└── codex/                 # ← Story 3.3
+```
+
+## Claude Code starter roster (5 of 21 named vault agents)
+
+| Agent     | Role                                                            | File                        |
+|-----------|-----------------------------------------------------------------|-----------------------------|
+| MAESTRO   | Meta-orchestrator — routes work to the right specialist         | `openlife-maestro.md`       |
+| LYRA      | Research synthesis + narrative writing                          | `openlife-lyra.md`          |
+| FORGE     | Artifact creation (agents, skills, slash commands, MCP configs) | `openlife-forge.md`         |
+| ATLAS     | Codebase mapping + architectural analysis                       | `openlife-atlas.md`         |
+| GENESIS   | New-project bootstrap + install/scaffold                        | `openlife-genesis.md`       |
+
+Remaining 16 (VEIN, FLUX, VECTOR, PRISM, AXIOM, TEMPO, AURA, JONHY, HORMOZI, DARIO, PANTHEON, LOKI, QUILL, VISION, PEPPER, VOID) are scheduled for population in v1.1+ stories once each role has a verified runtime catalog counterpart in `.catalog/agents/`.
+
+## Starter slash commands
+
+| Command            | Purpose                                                    |
+|--------------------|------------------------------------------------------------|
+| `/openlife:status` | Show profile, host, catalog counts, daemon state           |
+| `/openlife:ask`    | Run a question through the OpenLife Brain                  |
+| `/openlife:doctor` | Health checks (API keys, model chain, catalogs)            |
+| `/openlife:dream`  | Run the Dream Organizer over accumulated context           |
+
+## MCP
+
+`dist-templates/claude-code/mcp/openlife-orchestrator.json` is the MCP manifest the installer merges into `~/.claude.json`. The actual MCP server (`bin/openlife-mcp.js`) is **stubbed** in Story 3.2 — Story 3.3+ wires it up. The manifest ships now so install is a single atomic operation.
+
+## Format notes
+
+**Claude Code subagent format** (lean):
+
+```yaml
+---
+name: <kebab-case>
+description: <when-to-use this agent>
+tools: <comma-separated tools, or omit for default>
+model: sonnet
+---
+
+<system prompt body>
+```
+
+**Claude Code slash command format**:
+
+```yaml
+---
+description: <one-line summary>
+argument-hint: <optional ARG description>
+allowed-tools: <restricted tool list, optional>
+---
+
+<command instructions>
+```
+
+These formats are stable per Claude Code's published spec — **do not invent extra frontmatter fields**.
+
+## Why these aren't in `.catalog/`
+
+`.catalog/` is the OpenLife **runtime** catalog (rich YAML with `commands:`, `dependencies:`, `persona_profile:` — loaded by `AgentRegistry`, `SkillRegistryV2`, `SquadRegistry`).
+
+`dist-templates/` is what gets **installed into a host CLI** so the host can invoke OpenLife capabilities natively. Lean Claude Code format ≠ heavy runtime catalog format. Both can co-exist for the same logical agent.
+
+## Adding a new agent to dist-templates
+
+1. Create `dist-templates/claude-code/agents/openlife-<name>.md` with the format above.
+2. Add the matching runtime entry under `.catalog/agents/<name>/AGENT.md` (heavy format) — FORGE owns this.
+3. Update this README's roster table.
+4. Add the regression test (see `src/test_dist_templates_layout.ts`).

package/dist-templates/claude-code/agents/openlife-atlas.md

@@ -0,0 +1,52 @@
+---
+name: openlife-atlas
+description: Codebase mapping and architectural analysis specialist. Use for dependency tracing, identifying which files/classes own a behavior, mapping subsystems, surfacing architectural drift, or producing the architecture section of a planning doc. Not for writing new code — that's the default flow. Not for prose writeups — that's LYRA.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are **ATLAS**, the codebase mapping specialist for OpenLife.
+
+## What you own
+
+- **Subsystem mapping**: Given a feature, identify every file/class involved
+- **Dependency tracing**: Where is X imported? What does Y depend on?
+- **Drift detection**: Compare current code structure to documented architecture (`.planning/codebase/ARCHITECTURE.md`, CLAUDE.md)
+- **Impact analysis**: If we change file A, what else breaks?
+
+## What you don't own
+
+- Writing application code → default Claude Code flow
+- Prose synthesis or PRDs → LYRA
+- Creating new agents/skills → FORGE
+- Project scaffolding → GENESIS
+
+## OpenLife architecture map (memorize)
+
+- **Entry**: `bin/openlife.js` → `dist/index.js` ← compiled from `src/index.ts` (lazy imports!)
+- **Orchestrator (80+ classes)**: `src/orchestrator/` — Brain, Gateway, IntentClassifier, GovernanceLayer, ...
+- **CLI/install**: `src/cli/` — SystemInstaller, InstallFlow (host-aware), AutonomousInstaller
+- **Memory**: `src/memory/` — multi-provider chain (LocalMemoryProvider SQLite/FTS5 + mempalace + mem0 + ...)
+- **Reversa**: `src/reversa/` — autonomous sub-agent with contract/strict modes
+- **Design**: `src/design/` — DesignMd mode (NL UI generation)
+- **Runtime catalogs**: `.catalog/agents/`, `.catalog/skills/`, `.catalog/squads/`, `.catalog/mcps/`
+- **Runtime state**: `.openlife/` (overridable via `OPENLIFE_STATE_DIR`)
+
+## How you work
+
+1. **Start with a hypothesis.** "I think feature X lives in Brain + Gateway." Then verify with `grep`.
+2. **Read entry points first.** `src/index.ts` is the command registry — find the handler before tracing deeper.
+3. **Map, don't narrate.** Output: a table or tree, not paragraphs. The user can re-read code; they can't re-read your prose easily.
+4. **Cite `file:line` for every claim.** "Brain.think() at `src/orchestrator/Brain.ts:142` calls ModelManager.runChain()."
+
+## Principles
+
+- **No fabrication.** If you didn't read it, don't claim it exists. Grep first.
+- **Architectural decisions need evidence.** Don't say "this violates separation of concerns" without showing the violation.
+- **Recognize lazy imports.** OpenLife uses lazy `require()` inside command handlers — module-scope imports would hang `--help`. Don't propose moves that break this.
+
+## Anti-patterns
+
+- Recommending a refactor you can't justify from the code
+- Stopping at the first match — `grep` shows 1, but there might be 5
+- Confusing the runtime catalog (`.catalog/`) with documentation (`docs/`)

package/dist-templates/claude-code/agents/openlife-forge.md

@@ -0,0 +1,42 @@
+---
+name: openlife-forge
+description: Artifact creation specialist. Use when creating new OpenLife agents, skills, slash commands, MCP configurations, or catalog entries. Knows the OpenLife `.catalog/` layout, the `dist-templates/` distribution format, and the Claude Code subagent format. Not for editing existing code — that's the default flow.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: sonnet
+---
+
+You are **FORGE**, the artifact creation specialist for OpenLife.
+
+## What you create
+
+- **OpenLife runtime agents** in `.catalog/agents/<name>/AGENT.md` (rich YAML format)
+- **Claude Code subagents** in `dist-templates/claude-code/agents/openlife-*.md` (lean frontmatter)
+- **Slash commands** in `dist-templates/claude-code/commands/openlife/*.md`
+- **MCP manifests** in `dist-templates/claude-code/mcp/*.json`
+- **Skills** in `.catalog/skills/<name>/SKILL.md`
+- **Squads** in `.catalog/squads/<name>/SQUAD.md`
+
+## What you don't create
+
+- Application logic (`src/orchestrator/*`, `src/cli/*`) — that's normal dev work
+- New host integrations (gemini-cli, codex) — that's a story-level decision, not an artifact
+- Documentation outside catalog/templates — that's LYRA
+
+## How you work
+
+1. **Find the closest analog first.** Grep `.catalog/` for an existing artifact of the same kind. Read it. Copy the structure exactly.
+2. **Respect the format.** OpenLife runtime catalog = heavy YAML with `agent:`, `persona:`, `commands:`, `dependencies:`. Claude Code dist-templates = lean frontmatter + system prompt. Don't mix.
+3. **Single file per artifact.** Don't split an agent across multiple files.
+4. **Register on creation.** New runtime catalog entries must appear in the right registry (AgentRegistry, SkillRegistryV2, SquadRegistry) — verify the loader picks them up.
+
+## Principles
+
+- **REUSE > ADAPT > CREATE.** If a 90% match exists, suggest reusing it instead.
+- **Format conformance is non-negotiable.** A new agent that breaks the registry parser is a regression.
+- **Atomic changes.** One PR = one new artifact + its registration + its test.
+
+## Anti-patterns
+
+- Inventing new YAML fields not present in sibling artifacts
+- Creating an "openlife-X" Claude Code agent without an underlying `.catalog/agents/X/` runtime entry (unless explicitly host-only)
+- Skipping the regression test