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.

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

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 reads hooks/hooks-template.json, resolves absolute paths, writes into .claude/settings.json, preserves non-Citadel settings, 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)

Write .claude/harness.json using Node (not Write tool — harness.json is protected after first install):

node -e "
const fs = require('fs');
const existing = fs.existsSync('.claude/harness.json') ? JSON.parse(fs.readFileSync('.claude/harness.json', 'utf8')) : {};
const skillDirs = fs.readdirSync('{citadelRoot}/skills', { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name);
const config = {
  language: '{detected}', framework: '{detected or null}', packageManager: '{detected}',
  typecheck: { command: '{command}', perFile: {bool}, timeoutMs: 25000 },
  test: { command: '{testCommand}', framework: '{testFramework}' },
  qualityRules: { builtIn: ['no-confirm-alert', 'no-transition-all'], custom: [] },
  protectedFiles: ['.claude/harness.json', '.claude/settings.json'],
  features: { intakeScanner: true, telemetry: true },
  registeredSkills: skillDirs, registeredSkillCount: skillDirs.length,
  agentTimeouts: { skill: 600000, research: 900000, build: 1800000 },
  trust: { sessionCount: existing.trust?.sessionCount || 0, campaignCount: existing.trust?.campaignCount || 0, level: existing.trust?.level || 'novice' },
  ...existing  // preserve consent, storage, policy
};
fs.writeFileSync('.claude/harness.json', JSON.stringify(config, null, 2));
"

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 generates CLAUDE.md and AGENTS.md. Safe to run — only creates files that don't exist.

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 6: LIVE DEMO (Recommended + Full Tour only)

Find target file: git diff --name-only HEAD~1 HEAD 2>/dev/null | head -5, filter for source files, use the most recently changed. If no git history, use find for recently modified files.

Pain point question:

What's your biggest frustration with AI coding tools right now?

  [a] Repetitive context — I keep re-explaining my codebase
  [b] Quality — the agent breaks things or misses issues
  [c] Context loss — every new session starts from zero
  [d] Scale — fine for small tasks, falls apart on big ones
  [e] Something else / skip demo

Demo by pain point — execute on real code, show output:

• (a) run /review on target file — "This review uses the harness.json config you just set up — it already knows your stack, conventions, and quality rules."
• (b) run /review on target file — "The quality-gate hook just ran on every edit made during setup. Here's what that looks like on your code:"
• (c) show .planning/ structure, explain campaigns — "Sessions now persist. Start a campaign today, close your laptop, resume tomorrow."
• (d) run /review on largest source file — "For bigger work: /marshal for multi-step sessions, /archon for multi-day campaigns, /fleet for parallel agents."
• (e) skip demo, continue to reference card

Step 7: FULL TOUR WALKTHROUGH (Full Tour only)

Present the five skill families in order, using the per-skill one-liners and timings from docs/SETUP_REFERENCE.md#full-tour-walkthrough:

1. Code Quality (2 min): /review, /test-gen, /systematic-debugging — show by running /review on the Step 6 file if not already done
2. Building (2 min): /scaffold, /refactor, /create-skill
3. Research (1 min): /research (add --parallel for multi-scout), /infra-audit
4. Orchestration (1 min): /marshal, /archon, /fleet
5. Observability (1 min): /do next, /dashboard, /cost, /learn

After walkthrough: That's the system. Everything routes through /do — you never have to choose the right tool.

Step 8: REFERENCE CARD (all modes)

Print the reference card using the canonical boxed layout at docs/SETUP_REFERENCE.md#reference-card, filled with actual counts from the detected config. It must contain, in order:

• Header: CITADEL READY — {N} skills · {N} hooks live · {language}{+ framework}
• THE ONE COMMAND: /do [anything] — describe what you want in plain English, the router handles the rest
• COMMON STARTING POINTS: /do review [file], /do fix [description], /do why is [thing] broken, /do build [feature], /do test [file], /do next, /do status, /do continue
• WHEN TASKS GET BIGGER: /marshal (multi-step, one session), /archon (multi-session campaign), /fleet (parallel agents)
• WHAT'S NOW PROTECTING YOUR SESSION: protect-files, external-gate, circuit-breaker, quality-gate, telemetry
• NEXT STEPS: add conventions to CLAUDE.md, /do --list, /create-skill, /improve [target]
• Footer: docs/SKILLS.md · INSTALL.md · /do --list

Express mode: print abbreviated card (THE ONE COMMAND + WHAT'S NOW PROTECTING only).

Step 9: CLOSING LINE (all modes)

Express:      Done. {N} hooks live, {N} skills registered.
              Type /do [anything] to start.

Recommended:  Setup complete. Citadel is configured for {language}{+ framework}.
              {N} hooks are protecting this session. {N} skills are registered.
              Type /do [anything] to get started — or /do --list to browse all skills.

Full Tour:    Tour complete. You've seen the full system.
              {N} hooks live · {N} skills registered · trust level: {level}
              The best next thing: /do "review the most important file in this codebase"

Update:       Configuration updated. {N} hooks reinstalled, {N} skills re-registered.
              Changes: {list what changed vs previous config}

Fringe Cases

Plugin not found (.citadel/plugin-root.txt missing): Prompt for Citadel install path. Write answer to .citadel/plugin-root.txt.

Project has no source files: Skip demo. Output: "Once you have code, try /review [file] to see the harness in action."

harness.json is protected and Write tool is blocked: Use node -e "..." via Bash — Node script bypasses the Write hook, which is correct since setup is the authorized path.

Existing CLAUDE.md with no blank line at end: Append newline before ## Citadel Harness section.

Stack detection fails entirely: Fall back to: "What's your primary language? (typescript / javascript / python / go / rust / other)"

Re-running setup on configured project (Update mode): Show diff of what would change. Don't silently overwrite. Confirm each change.

bootstrap-project-guidance.js not found: Skip silently — fall back to manual CLAUDE.md template.

Contextual Gates

Disclosure: "Configuring Citadel for this project. Will modify .claude/settings.json and install hooks." Reversibility: amber — writes .claude/settings.json, installs hooks, creates .planning/; undo by running /unharness Trust gates:

• Any: first-run configuration; expected to modify settings and install hooks

Quality Gates

• Hooks must be installed before any other step completes
• harness.json must contain registeredSkillCount matching actual skill count
• CLAUDE.md must not lose existing content
• Demo must run on real user code, not a canned example
• Reference card must show accurate skill and hook counts
• Closing line must confirm hooks are live

Exit Protocol

Do not output a HANDOFF block. Setup is the beginning. After the closing line, wait for the user's next command.