# 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`).
