Setup

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

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.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"],
  "features": { "intakeScanner": true, "telemetry": true },
  "registeredSkills": ["do", "review"],
  "registeredSkillCount": 2,
  "agentTimeouts": { "skill": 600000, "research": 900000, "build": 1800000 }
}

Substitute the detected values and complete skill list; use JSON null when no framework or test framework is detected.

Preview the deterministic version-2 config migration without writing:

node {citadelRoot}/scripts/citadel-config.js initialize \
  --input .planning/tmp/citadel-stack.json --runtime {claude-code|codex|opencode} --json

Show profile, bundles, source/candidate digests, and changed fields. Apply only after the selected setup mode authorizes this exact plan:

node {citadelRoot}/scripts/citadel-config.js initialize \
  --input .planning/tmp/citadel-stack.json --runtime {claude-code|codex|opencode} --apply --json

Recommended and Express use standard@1.0.0 with Core + Persistence. Full Tour may preview Parallel and Operations, but each bundle needs an explicit enable plan. If the runtime is partial, show the named adapter and require --allow-degraded-runtime; never silently describe degraded support as full. Delivery remains off until the user explicitly enables it.

The apply creates a sibling backup when replacing an existing config, validates the observed digest, rolls back a failed write, and reconciles .citadel/effective-config.json. Re-run install-hooks.js after the final bundle choice so disabled hook families are removed from the generated runtime projection.

Note: perFile applies to Python checkers only; TypeScript always runs a project-scope incremental check and ignores perFile with an advisory.

Skill registry rebuild: populate registeredSkills from every directory under {citadelRoot}/skills/ plus .claude/skills/. Set registeredSkillCount to match.

Routing table regeneration: run node {citadelRoot}/scripts/generate-routing.js, then verify with node {citadelRoot}/scripts/generate-routing.js --check — exit 0 means all routing surfaces are in sync (what it regenerates: docs/SETUP_REFERENCE.md#routing-surfaces). If the script is missing (older Citadel install), skip this step silently.

Dependency pattern suggestions (Recommended + Full Tour only): read package.json for @tanstack/react-query, zustand, date-fns, zod. For each match ask: "I see {package} installed. Warn agents when they use {anti-pattern}? [y/n]" and add accepted patterns to dependencyPatterns in harness.json (anti-pattern and message table: docs/SETUP_REFERENCE.md#dependency-pattern-suggestions).

Step 4: CLAUDE.md + AGENTS.md (all modes)

Run node {citadelRoot}/scripts/bootstrap-project-guidance.js --project-root {projectRoot} — creates .citadel/project.md and compatible CLAUDE.md plus AGENTS.md guidance. Safe to run — it preserves user-authored files.

Claude Code v2.1.277 or later can use only AGENTS.md, but the version alone does not prove the built-in support is available in the current environment. When the operator has confirmed the Project instructions setting or an AGENTS.md loaded startup notice, run node {citadelRoot}/scripts/bootstrap-project-guidance.js --project-root {projectRoot} --claude-agents-md-supported. The script detects the installed Claude Code version, migrates only byte-for-byte unchanged Citadel guidance, and retains CLAUDE.md when the version or capability is unknown or project guidance would take precedence.

Project description (Recommended + Full Tour only): ask "What's this project? One line is fine — or press Enter to use the package name." Skip if CLAUDE.md already exists with content.

CLAUDE.md merge rules:

• Does not exist → generate the starter from docs/SETUP_REFERENCE.md#claudemd-starter-template: project name, description, Stack section (detected values), placeholder Conventions and Architecture sections, and a ## Citadel Harness section noting the harness and .claude/harness.json
• Exists, no ## Citadel Harness section → append that section at bottom only
• Exists with ## Citadel Harness → skip, don't duplicate
• NEVER overwrite or delete existing content

Step 5: OPTIONAL INTEGRATIONS (Recommended + Full Tour only)

Present as one prompt:

Optional integrations — choose any, or press Enter to skip all:
  [g] GitHub    — scaffold Claude triage workflow for issues + PRs
  [m] MCP       — create .mcp.json with common servers pre-configured
  [b] Both
  [s] Skip

GitHub: create .github/workflows/ if missing; copy .planning/_templates/claude-triage.yml → .github/workflows/claude-triage.yml and .planning/_templates/REVIEW.md → REVIEW.md (skip any that already exist). Output: "Add ANTHROPIC_API_KEY to Settings > Secrets > Actions to activate." MCP: copy .planning/_templates/.mcp.json → .mcp.json (skip if exists). Output: "Edit .mcp.json to uncomment the servers you want."

Step 5b: CROSS-CLONE MEMORY (Recommended + Full Tour only)

Run node {citadelRoot}/scripts/repository-memory.js status --project-root {projectRoot} --json.

• Already enabled: report the stored file/version counts and do not prompt.
• unavailable: skip the prompt; this optional capability requires Node.js 22.13+.
• Otherwise ask: "Preserve completed Citadel lessons across disposable clones in a local user-level SQLite database? [y/N]"

On yes, run:

node {citadelRoot}/scripts/repository-memory.js enable --project-root {projectRoot}

State exactly what is stored: completed campaigns, postmortems, research, discoveries, backlog Markdown, and .citadel/project.md. State what is excluded: active work, telemetry, worktrees, consent, runtime config, and credentials. Raw remote URLs and clone paths are excluded as identity metadata, but allowlisted documents are stored verbatim and may mention either. Express mode never opts in automatically, but an already-enabled repository continues to restore and sync through lifecycle hooks.