install-garura

name	install-garura
description	Install Garura into a target project or repository so its skills, agents, and plays become discoverable by a host coding tool — Claude Code or the OpenAI Codex CLI. Reads this garura checkout's core/components and runs a per-tool ADAPTER that lays them down in the host's native shape: for claude, .claude/ skills + agents with model tiers resolved to Claude models; for codex, .agents/skills Agent Skills plus AGENTS.md and ~/.codex model/sandbox/approval profiles. Always writes a .garura/ tooling tree (config + STM scaffold) and copies shared memory to the machine-global ~/.garura, and records an install manifest so uninstall-garura can reverse exactly what was placed. Use when the user wants to install, set up, bootstrap, add, or enable Garura in another folder or repo for claude or codex — "install garura into X", "set up garura in this repo for codex", "bootstrap garura", "make codex see the garura skills". Takes the target path, an optional --tool, and an optional --scope (full = everything, the default; harness = meta plays + change chain + their workers only). For the reverse, see uninstall-garura.
user-invocable	true

install-garura

Install this garura checkout into a target project so a host coding tool can discover and run its skills, agents, and plays there. You run this from the garura repo (where the source lives); the target is some other folder or repo the user names. The host tool is chosen with --tool: claude (Claude Code, the default) or codex (the OpenAI Codex CLI).

After a successful install the target has a .garura/ tooling tree (config + an STM scaffold) and — depending on the tool — either a .claude/ tree (Claude Code) or a .agents/skills/ tree plus an AGENTS.md (Codex). Shared memory (the standards/KB) always goes to the machine-global ~/.garura.

How this play is built (read this first)

This is a bootstrap meta-play — like play-creator, it is hand-authored, not compiled from an ICE source, and it is harness-led: the play decides and reports, a bundled script does the deterministic file work. The orchestrator scripts/install.py walks the source, handles the tool-agnostic work (shared memory, garura's own config, the STM scaffold, the manifest), and delegates the host surface to a per-tool adapter under scripts/adapters/. Don't re-implement that work in prose; call the script and reason about its result.

The adapter is the seam. Garura's components carry a model: hint (best / opus / sonnet / haiku). That value is a tier signal, not a literal host model id. adapters/common.py folds it to a neutral tier (deep / standard / fast), and each adapter maps the tier onto its host's real model selection. If you find yourself special-casing a host's model names or file layout in the orchestrator, stop — that belongs in the adapter.

What "installed" means

install.py --tool claude produces, in the target:

• .claude/agents/<id>.md — one per garura agent, with its model tier resolved and kept (best → opus; the opus/sonnet/haiku shorthands pass through) so the agent runs on the intended tier.
• .claude/skills/<id>/ — one per garura skill, and one per garura play (Claude Code has no separate play type), copied whole with their own references//scripts/. The model: line is dropped on skills (a Claude skill has no model field).

install.py --tool codex produces, in the target:

• .agents/skills/<id>/ — one Codex Agent Skill per garura skill, play, and agent (Codex has no separate agent type), carrying only name + description frontmatter, with the recommended tier noted in the body (Codex can't pin a model per skill).
• AGENTS.md — garura's instruction surface, retitled for the target (Codex's equivalent of CLAUDE.md). Written as AGENTS.md.new if one already exists.
• ~/.codex/config.toml + ~/.codex/{deep,standard,fast}.config.toml — base defaults and the three tier profiles (model + reasoning effort + sandbox + approval), so the model and the "forking"/sandbox settings the tier implies are actually selectable via codex --profile. Existing files are kept, never clobbered; only files this run creates are recorded.

Both tools also get:

• .garura/core/config.yaml — garura's config transformed for the target (name, type Project, component paths pointed at the tool's install location, memory at ~/.garura/core/memory/, the platform/github lines dropped). Kept on re-run unless --force-config.
• .garura/project/specs/ — an empty STM scaffold.
• .garura/.gitignore — keeps status/resume markers (**/status/, **/_status/) machine-local and out of git; they sit on disk for resume and are never committed (ADR 021).
• .garura/install-manifest.json — the exact list of what was placed (including the tool and any machine-global files), so uninstall-garura can reverse precisely this set.

Direct-edit deviation note (#441/ADR 021): the .garura/.gitignore scaffold artifact and its manifest record were added directly to scripts/install.py (and its reversal to uninstall-garura/scripts/uninstall.py) as a mechanical scaffold detail within the play's existing "writes the .garura tooling tree" intent — no ICE guarantee, eval, or decision changed, so this was not routed through a recompile.

Shared memory goes to --memory-dest (default ~/.garura/core/memory), machine-global and shared across projects; the manifest records the resolved path. Source artifacts whose name starts with _ or ., and folders with no SKILL.md, are skipped.

Pre-flight

Before running, confirm:

1. A target is named. The user must say which folder/repo to install into. If they didn't, ask — don't guess. The target is created if absent.
2. The tool is known. Default is claude. Install for Codex with --tool codex. If the user said "for codex" (or "for claude"), pass it through.
3. You're in (or can point at) the garura checkout. The script auto-derives the source by walking up until it finds core/components/ and .garura/core/config.yaml. When run detached from source, pass --source <garura-checkout>.
4. Python 3 is available. The script is Python 3, no third-party packages.

If a pre-flight fails, say what's missing in plain words and stop.

Run it

From the garura repo root the source is auto-derived; you normally only pass --target and, for Codex, --tool codex:

python3 core/components/plays/install-garura/scripts/install.py --target <path> [--tool claude|codex]

Options:

• --tool claude|codex — which host tool to target (default claude).
• --scope full|harness — which component set the target receives (default full, everything). harness installs only the meta plays (play-creator, play-editor), the five *change plays, and the worker skills/agents those plays dispatch — for harness-type repos (garura itself) that must not carry product plays. The scope filters components only; shared memory, config, the STM scaffold, and the manifest are written the same either way. The manifest records the scope, and since retirement is manifest-driven, re-running with --scope harness over a previously full install retires the out-of-scope components cleanly. The harness membership list lives in scripts/install.py (SCOPES) — when a kept play gains a new worker, add it there in the same change.
• --source <garura-checkout> — point at the garura checkout explicitly (needed only when the script can't sit beside the source).
• --memory-dest <path> — where shared memory goes (default ~/.garura/core/memory). Point it at a temp dir for a dry test so you never touch the real machine KB. For a Codex dry test, also set CODEX_HOME=<tempdir> in the environment so the profile writes are isolated.
• --force-config — overwrite an existing target .garura/core/config.yaml instead of keeping it.
• --quiet — less output.

The script is idempotent: re-running re-lays the components in place and refreshes shared memory, but preserves an existing config unless forced. Re-running never produces duplicates.

Re-running also retires: any component the previous install's manifest placed that this install did not re-place (renamed or retired in source) is removed from the target and reported as retired:. Only manifest-recorded paths are candidates — the user's own skills/files are never touched. So a rename like sud-install-garura → install-garura, or a play retirement, cleans itself up on the next install instead of leaving a stale copy.

Report back

After the script returns, read the printed summary and the written .garura/install-manifest.json, then tell the user in plain language:

• which target it installed into and for which tool,
• how many agents and skills/plays were installed,
• for Codex: that the tier profiles were written (or kept) under ~/.codex and the next step is codex --profile deep|standard|fast,
• whether a config was written fresh or an existing one was kept,
• where the shared memory went,
• the one next step: open the target in the host tool and the garura skills/agents are now discoverable.

Keep it short. The detail lives in the manifest; your job is the human summary.

Boundaries

• Never hand-edit an installed copy under a target's .claude/ or .agents/. It is generated — edit the garura source and re-install.
• Don't delete the user's own files. Install only writes the Garura artifacts named above (and never clobbers an existing CLAUDE.md / AGENTS.md / ~/.codex config). Removing install artifacts is uninstall-garura's job, and even that reverses only what the manifest records.
• Protect the shared memory and the Codex home. ~/.garura/core/memory and any existing ~/.codex/* are machine-global and merged into, never wiped, on install. When testing, redirect --memory-dest and CODEX_HOME to temp dirs.

Direct-edit deviation note (#434): this bootstrap meta-play is hand-authored (no intent.yaml); the adapter split, the --tool parameter, and the Codex adapter were added by direct edit to this SKILL.md and scripts/.

Direct-edit deviation note (#478): the --scope option (named component subsets: full default, harness = meta plays + change chain + their workers) was added by direct edit to this SKILL.md, scripts/install.py (the SCOPES table, the manifest scope field), and both adapters' lay_components (an allow filter) — same bootstrap-meta-play path as #434; no ICE source exists to recompile. Uninstall needs no change: it reverses what the manifest records, and a scoped manifest records exactly what was placed.

Level 3 note (#466): bootstrap meta-play — exempt from the goal-loop recompile (no ICE source, like play-creator); runs are session-stamped by the host play when invoked through the pipeline.