setup

---
name: setup
description: Initialize, upgrade, or migrate the claude-harness plugin in a project. Use for first-time setup, plugin installation, version migration, memory directory configuration, legacy file cleanup, and project harness initialization.
disable-model-invocation: true
---

# Setup - Initialize or Upgrade Claude Harness

Initialize or upgrade claude-harness in the current project directory.

## Auto-Detection

This command automatically detects what needs to be done:
- **Fresh install**: Creates v3.0 structure from scratch
- **v2.x upgrade**: Migrates existing files to v3.0 memory architecture
- **Cleanup**: Removes legacy command copies from `.claude/commands/` (commands are now served from plugin cache)

**Note**: Commands and hooks are served from the plugin cache. `setup.sh` only initializes project-level state (memory directories, CLAUDE.md, .gitignore, migrations).

## Phase 0: Run setup.sh (Handles ALL Cases)

`setup.sh` handles fresh installs, v2.x migrations, and cleanup in a single script. **Always run it.**

**Steps:**
1. Find the plugin root path from the session context (look for "Plugin Root:" in the session start context)
2. Run: `bash {plugin-root}/setup.sh`
   - **Fresh install**: Creates v3.0 structure, `.gitignore` patterns, CLAUDE.md
   - **v2.x migration**: Detects legacy files, migrates to v3.0 structure, then creates missing files
   - **Cleanup**: Removes stale command copies from `.claude/commands/` and legacy hooks
   - Existing project files are **NEVER overwritten** (skipped automatically)
   - `.gitignore` patterns are added if missing
3. Report what was created vs what was skipped
4. **Skip Phase 3** -- `setup.sh` handles it

**Fallback**: If the plugin root path is not available in the session context, fall through to Phase 1 -> Phase 4 (manual setup).

**Plugin updates**: Run `claude plugin update claude-harness` to update the plugin itself.

## Phase 3: Update Project .gitignore (FALLBACK -- only if setup.sh unavailable)

**CRITICAL**: You MUST update the project's `.gitignore` to exclude harness ephemeral files. This prevents uncommitted file clutter after `/checkpoint`.

**Execute these steps:**

1. Read the current `.gitignore` file (create if missing)

2. Check if `.claude-harness/sessions/` pattern exists in the file

3. If the pattern is NOT present, append these lines to `.gitignore`:
   ```
   # Claude Harness - Ephemeral/Per-Session State
   .claude-harness/sessions/
   .claude-harness/memory/compaction-backups/

   # Claude Code - Local settings
   .claude/settings.local.json
   ```

4. Use the Edit tool to append these patterns to `.gitignore`

5. Report: "Updated .gitignore with harness ephemeral patterns"

**DO NOT SKIP THIS PHASE** - it is required for proper harness operation.

## File Schemas

Canonical schemas are defined in the plugin's `schemas/` directory (JSON Schema format). Key state files:

| File | Schema | Created By |
|------|--------|------------|
| `sessions/{id}/context.json` | `schemas/context.schema.json` (v3) | Phase 1 context compilation |
| `sessions/{id}/loop-state.json` | `schemas/loop-state.schema.json` (v9) | Phase 4 implementation |
| `sessions/{id}/autonomous-state.json` | `schemas/autonomous-state.schema.json` (v4) | `--autonomous` mode |
| `features/active.json` | `schemas/active-features.schema.json` (v3) | Phase 2 feature creation |

Memory knowledge layers (`memory/decisions/`, `failures/`, `successes/`, `patterns/`, `rules/`) are an **OKF v0.1 bundle** -- markdown concept files with YAML frontmatter, not JSON. Their conformance rules are documented in `schemas/okf-memory.md` and checked by `scripts/check-okf.py`; `setup.sh` migrates legacy JSON memory files to the bundle automatically (stamp-gated). Semantic memory (`memory/semantic/*.json`) and runtime state stay JSON with v3 schemas as created by `setup.sh`.

## After Setup

Report:
- What was done (fresh install / migration / version update)
- Files created or migrated
- Current plugin version
- Next steps:
  1. Run `/claude-harness:start` to compile context and sync GitHub
  2. For new projects: Run `/claude-harness:prd-breakdown @./prd.md` to analyze PRD and extract features
  3. Use `/claude-harness:flow "description"` for end-to-end automated workflow (recommended)
  4. Use `/claude-harness:flow --no-merge "description"` for step-by-step control
  5. Use `/claude-harness:flow --fix feature-XXX "bug"` to create bug fixes