talisman

/rune:talisman — Configuration Mastery

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

References:

• Talisman sections — top-level sections with key descriptions
• Configuration guide — full schema with types and defaults
• Example template — 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 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 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 for section summaries
• configuration-guide.md for full schema
• 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 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 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 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:

// 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