/setup

name: setup
license: MIT
description: >-
  First-run experience for the harness. Three modes: Recommended (guided,
  ~3 min), Full Tour (guided + skill walkthrough, ~8 min), and Express
  (zero questions, ~30 sec). Installs hooks first, detects stack, configures
  harness.json, runs a live demo on real code, and prints a reference card.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - setup
  - first run
  - configure harness
  - install citadel
  - getting started
last-updated: 2026-04-06

/do setup — First-Run Experience

Configures the harness for a specific project: installs hooks, detects stack, writes harness.json, and optionally demos the system on real code. Flag: `/do setup --express` skips mode selection and runs Express directly. Reference tables and layouts: docs/SETUP_REFERENCE.md.

Orientation

**Use when:** first-run configuration of Citadel on a new project -- installs hooks, generates harness.json, scaffolds .planning/. **Don't use when:** harness is already configured and you want to verify it (use /verify); adding a single skill to an existing project (copy SKILL.md manually).

Protocol

Step -1: ARCHIVE DETECTION (all modes, before anything else)

Run `ls docs/citadel/ 2>/dev/null`. If `docs/citadel/` exists and contains `.md` files with `citadel-archive: true` in frontmatter, extract the `exported-at` date and prompt once:

Found a Citadel archive from {exported-at date}.
  Campaigns: {N}  Postmortems: {N}  Backlog items: {N}  Research: {N}

Restore history into .planning/ during setup? [Y/n]

Y or Enter → set `restoreArchive = true`, restore after Step 1 (below). n → skip silently. No archive found → skip entirely, no output.

**ARCHIVE RESTORE** (runs after Step 1 if `restoreArchive = true`). Splitting: each `## Section Title` becomes one restored file; strip frontmatter before writing.

| File | Restore to | |---|---| | `campaigns.md` | Split sections → `.planning/campaigns/completed/{name}.md` | | `postmortems.md` | Split sections → `.planning/postmortems/{name}.md` | | `research.md` | Split sections → `.planning/research/{name}.md` | | `backlog.md` | Split sections → `.planning/intake/{name}.md` | | `discoveries.md` | Split sections → `.planning/discoveries/{name}.md` | | `project.md` | Strip frontmatter → `.citadel/project.md` | | `harness.json.md` | Strip frontmatter → `.claude/harness.json` (Citadel's shared config path for all runtimes, including Codex) |

After restore: ` ✓ Archive restored — {N} campaigns, {N} postmortems, {N} backlog items`

Step 0: MODE SELECTION

Welcome to Citadel.

How would you like to get started?

  [1] Recommended  — auto-detect your stack, install hooks, live demo  (~3 min)
  [2] Full Tour    — everything in Recommended + guided skill walkthrough (~8 min)
  [3] Express      — zero questions, auto-detect, hooks installed, done  (~30 sec)

Press Enter for Recommended, or type 1, 2, or 3.

If harness.json already exists with full config, add: ` [4] Update — reconfigure existing setup (current: {language}, {skillCount} skills)`. Default: Recommended. If `--express` flag passed: skip mode selection, run Express.

Step 1: INSTALL HOOKS (all modes, always first)

Hooks must be live before anything else. Run `node {citadel-root}/scripts/install-hooks.js`. Find `{citadel-root}`: read `.citadel/plugin-root.txt`; fallback: directory containing this SKILL.md. The installer resolves the current config (or the bootstrap Standard + Core + Persistence default), writes `.citadel/effective-config/<runtime-id>.json`, installs only hooks owned by effective bundles, preserves non-Citadel settings, and is idempotent.

**On success:** ` ✓ {N} hooks installed (protect-files, external-gate, circuit-breaker, quality-gate + more)` **On failure:** output the error, explain manual install path (`node /path/to/Citadel/scripts/install-hooks.js`), continue — setup must not abort.

Step 2: STACK DETECTION (all modes)

Auto-detect by scanning the project root. Never ask what can be read. (Readable tables: docs/SETUP_REFERENCE.md#stack-detection-tables.)

• **Language** (check in order): `tsconfig.json` → TypeScript; `package.json` without tsconfig → JavaScript; `requirements.txt` or `pyproject.toml` → Python; `go.mod` → Go; `Cargo.toml` → Rust; `pom.xml` or `build.gradle` → Java
• **Framework** (package.json dependencies): `next` → Next.js; `react` (no next) → React; `vue` → Vue; `svelte` → Svelte; `@angular/core` → Angular; `express` → Express; `fastify` → Fastify
• **Package manager**: `pnpm-lock.yaml` → pnpm; `yarn.lock` → yarn; `bun.lockb` → bun; `package-lock.json` → npm; `requirements.txt` → pip; `Pipfile` → pipenv
• **Test framework**: package.json devDependencies for `jest`, `vitest`, `mocha`, `jasmine`; Python: `pytest` in requirements.txt or pyproject.toml
• **Typecheck by language**: TypeScript `npx tsc --noEmit` (per-file: no, project-scope incremental); Python `mypy {file}` or `pyright {file}` (per-file: yes); Go `go vet ./...`, Rust `cargo check`, JavaScript none (per-file: no)

**Confirmation (Recommended + Full Tour only):** output `Detected: {language}{+ framework if any} · {packageManager} · {testFramework if any}`, then `Correct? [y/n/edit]`. y/Enter → proceed; n/edit → ask for corrections inline. Express: skip confirmation, use detected values.

Step 3: GENERATE CONFIG (all modes)

Create `.planning/tmp/citadel-stack.json` with only the detected compatibility fields below. This input is not authoritative and must not contain profile, bundle, consent, trust, or policy fields:

{
  "language": "typescript",
  "framework": "react",
  "packageManager": "npm",
  "typecheck": { "command": "npx tsc --noEmit", "perFile": false, "timeoutMs": 25000 },
  "test": { "command": "npm test", "framework": "vitest" },
  "qualityRules": { "builtIn": ["no-confirm-alert", "no-transition-all"], "custom": [] },
  "protectedFiles": [".claude/harness.json", ".claude/settings.json"],
  "featur