---
name: talisman
description: |
  Deep talisman.yml configuration expertise — init, audit, update, guide, status,
  split, merge. Scaffolds project-specific talisman.yml from canonical template,
  detects missing sections, explains every config key.
  Use for: "init/setup/create talisman", "talisman audit/check/guide/status",
  "configure rune", "mcp integration", "untitledui setup".
user-invocable: true
disable-model-invocation: false
argument-hint: "[init|audit|update|guide|status|split|merge]"
---

# /rune:talisman — Configuration Mastery

Deep expertise for `.rune/talisman.yml` — the project-level configuration
that controls all Rune agent behavior.

**References**:
- [Talisman sections](references/talisman-sections.md) — top-level sections with key descriptions
- [Configuration guide](../../references/configuration-guide.md) — full schema with types and defaults
- [Example template](../../talisman.example.yml) — canonical 950+ line example

## Subcommand Routing

Parse `$ARGUMENTS` to determine subcommand:

| First Word | Subcommand | Action |
|-----------|-----------|--------|
| `init` | INIT | Scaffold new talisman.yml |
| `audit` | AUDIT | Compare existing vs template |
| `update` | UPDATE | Add missing sections |
| `guide` | GUIDE | Explain configuration |
| `status` | STATUS | Show talisman summary |
| `split` | SPLIT | Split into 3 companion files |
| `merge` | MERGE | Merge companions back to single file |
| (empty) | STATUS | Default to status |

## INIT — Scaffold New Talisman

### Phase 1: Pre-flight Check

```
1. Check if .rune/talisman.yml already exists
   → If exists: warn and offer AUDIT instead
   → If not: proceed

2. Check if .claude/ directory exists
   → If not: create it
```

### Phases 2-5: Stack Detection, Template Read, Generate, Write

Detects project stack from manifest files (10 languages + CI/Docker/ORM signals), queries agent-search MCP for stack-relevant agents (Phase 2.3), reads canonical `talisman.example.yml`, generates stack-customized talisman with core + optional sections, detects MCP integrations from `.mcp.json`, scaffolds `stack_awareness.priority` from detected stack, writes to `.rune/talisman.yml`, and shows summary with next steps.

See [init-protocol.md](references/init-protocol.md) for the full Phase 2-5 pseudocode (stack signals, agent recommendations, customization table, MCP detection).

## AUDIT — Compare Against Template

### Phase 1: Read Both Files

```
1. Read project talisman: .rune/talisman.yml
   → If missing: suggest INIT instead
2. Read example template: ${RUNE_PLUGIN_ROOT}/talisman.example.yml
```

### Phases 2-4: Deep Comparison, Integration Validation, Gap Report

Classifies each section as MISSING/OUTDATED/PARTIAL/DIVERGENT/OK. Validates MCP integration entries (6 checks: server existence, tool categories, phase keys, skill bindings, rule files, trigger configuration). Runs semantic consistency validation (Phase 2.7: 6 cross-field checks via `validate-talisman-consistency.sh` — max_ashes capacity, source resolution, context budget totals, dimension agent caps, dedup hierarchy orphans). Presents gaps in priority order (CRITICAL → RECOMMENDED → OPTIONAL → DIVERGENT) with suggested actions.

See [audit-protocol.md](references/audit-protocol.md) for the full comparison and gap report pseudocode.

## UPDATE — Add Missing Sections

### Phase 1: Run AUDIT internally

Same as AUDIT Phase 1-3, but automated.

### Phase 2: Present Changes

```
Show what will be added/changed:
  - New sections to add
  - Keys to update
  - Deprecated keys to remove

AskUserQuestion: "Apply these changes?"
  - "Apply all"
  - "Apply critical only"
  - "Review each section"
```

### Phase 3: Apply Changes

```
Use Edit tool to modify .rune/talisman.yml:
  - Add missing sections at appropriate positions
  - Update deprecated keys
  - Preserve existing project-specific values
  - Add YAML comments for context
```

### Phase 4: Verify

```
Re-read the file to verify YAML validity
Show summary of changes applied
```

## GUIDE — Expert Configuration Guidance

### Routing

Parse remaining args after "guide":

```
/rune:talisman guide              → Overview of all sections
/rune:talisman guide codex        → Codex integration keys
/rune:talisman guide arc          → Arc pipeline configuration
/rune:talisman guide review       → Review/sharding/convergence
/rune:talisman guide work         → Work/strive settings
/rune:talisman guide ashes        → Custom Ashes configuration
/rune:talisman guide goldmask     → Goldmask per-workflow integration
/rune:talisman guide mend         → Mend settings
/rune:talisman guide integrations → MCP tool integrations (aliases: mcp, mcp-integration)
/rune:talisman guide reactions    → Declarative reaction engine policies (v2.5.1+)
/rune:talisman guide [topic]      → Match to closest section
```

### Response Format

For each topic:
1. What it controls
2. Key configuration keys with types and defaults
3. When to change from defaults
4. Common pitfalls
5. Example configuration snippet

Load details from:
- [talisman-sections.md](references/talisman-sections.md) for section summaries
- [configuration-guide.md](../../references/configuration-guide.md) for full schema
- [talisman.example.yml](../../talisman.example.yml) for canonical values

### Integrations Topic

Covers 3 integration levels (Basic `.mcp.json` only → Talisman phase routing + triggers → Full companion skill + builder protocol metadata), YAML examples for generic Level 2 and UntitledUI Level 3 canonical, all configuration fields, UntitledUI setup steps, and the `resolveMCPIntegrations()` triple-gate pipeline.

See [integrations-guide.md](references/integrations-guide.md) for the full integrations topic guide.

## STATUS — Talisman Summary

### Phase 1: Locate Talisman

```
1. Check .rune/talisman.yml (project)
2. Check ${CHOME}/talisman.yml (global) where CHOME="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
3. Report which level is active
```

### Phase 2: Parse and Summarize

```
For each top-level section present:
  - Section name
  - Key count
  - Notable overrides from defaults

Also report:
  - Total sections: N/[schema total]
  - Codex workflows enabled: [list]
  - Cost tier: [tier]
  - Custom Ashes: [count]
  - Ward commands: [list]
```

### Phase 2.5: Integration Status

```
If integrations.mcp_tools exists:
  For each integration:
    Show: namespace, server_name, tool count, phase bindings
    Show: trigger summary (extensions/paths/keywords or "always")
    Check: server_name found in .mcp.json? (✓ connected / ✗ not in .mcp.json)
    Check: skill_binding exists? (✓ loaded / ✗ missing / — not configured)

  Example output:
    MCP Integrations: 2 configured
      untitledui  → 5 tools, phases: devise/strive/forge
                    triggers: .tsx,.ts,.jsx | keywords: frontend,ui
                    server: ✓ connected | skill: untitledui-mcp ✓
      my-api      → 2 tools, phases: strive/arc
                    triggers: always
                    server: ✗ not in .mcp.json | skill: — not configured
```

### Phase 3: Health Check

```
Quick health indicators:
  ✓ codex.workflows includes arc
  ✓ file_todos uses schema v2 (no deprecated keys)
  ✓ dedup_hierarchy has stack-appropriate prefixes
  ✓ arc.timeouts defined
  ✓ integrations: N configured, N connected (if present)
  ✗ Missing: [sections not present]
```

## SPLIT — Split Into Companion Files

Splits a single `talisman.yml` into 3 files organized by audience. Uses text-based line processing to preserve YAML comments and key ordering.

See [split-merge-protocol.md](references/split-merge-protocol.md) for the full algorithm — section mapping, split/merge procedures, comment preservation strategy, and safety guarantees.

### Algorithm

```
1. Read .rune/talisman.yml
   → If missing: suggest INIT instead
2. Identify top-level sections by regex (^key: at column 0)
3. Map each section to its companion file (main / ashes / integrations)
4. Present extraction preview via AskUserQuestion:
   "Moving N sections to talisman.ashes.yml, M sections to talisman.integrations.yml"
5. If confirmed:
   a. Write companion files (ashes first, then integrations)
   b. Remove extracted sections from main file
   c. Run talisman-resolve.sh to verify shards are identical
   d. If verification fails: rollback (restore main, delete companions)
6. Report: "Split complete. X sections → ashes, Y sections → integrations"
```

### Safety Guarantees

- `version:` key NEVER moves — stays in main file only
- Atomic: companions written first, main modified second
- Shard verification: pre-split vs post-split shards must be identical
- Rollback on any failure: restore original, delete companions

## MERGE — Merge Companions Back

Inverse of SPLIT — rejoins companion files into a single `talisman.yml`.

See [split-merge-protocol.md](references/split-merge-protocol.md) for the full algorithm.

### Algorithm

```
1. Discover companion files (.rune/talisman.ashes.yml, .rune/talisman.integrations.yml)
   → If none found: "No companion files to merge."
2. Read all files
3. Concatenate sections: main first, then ashes, then integrations
4. Write merged .rune/talisman.yml
5. Delete companion files
6. Run talisman-resolve.sh to verify shards unchanged
7. Report: "Merge complete. Single-file talisman.yml restored."
```

## readTalisman Pattern

Always use SDK Read() — NEVER Bash for talisman access:

```javascript
// Primary: .rune/talisman.yml
try { return parseYaml(Read(".rune/talisman.yml")) } catch {}
// Legacy fallback: .claude/talisman.yml
try { return parseYaml(Read(".claude/talisman.yml")) } catch {}

// Global level (fallback)
Read("${CLAUDE_CONFIG_DIR:-$HOME/.claude}/talisman.yml")

// NEVER: Bash("cat ~/.claude/talisman.yml") — ZSH tilde bug
```

## Persona

Use Rune's Elden Ring-inspired tone:

```
The Tarnished studies the Talisman...
  Section map loaded, 17 active in your project.
  4 gaps detected — 1 critical, 2 recommended, 1 optional.
```

```
A new Talisman is forged for this project.
  Stack detected: Python + FastAPI
  Ward commands: pytest, mypy --strict
  Codex enabled for: review, audit, plan, forge, work, arc
```