conductor-harness 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blaesild
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# conductor-harness
+
+A Claude Code harness for [Conductor](https://conductor.build) projects. Installs session hooks, memory integration, Linear workflow, and project context injection into any git repo in under a minute.
+
+---
+
+## What it does
+
+- **SessionStart hook** — injects branch, recent commits, last session progress, and `WORKFLOW.md` context before every Claude Code session
+- **Linear integration** — reads attached issues directly from Conductor's `+` button; falls back to Linear MCP for comments and history
+- **Graphiti memory** — searches past decisions before starting work; writes episodes after `/done`
+- **Context7 docs** — fetches up-to-date framework and package documentation before planning or implementing
+- **`/start`, `/done`, `/status`** — task kickoff and closeout rituals that keep progress state and memory in sync
+- **`/setup`** — analyzes your project and auto-generates `WORKFLOW.md`
+- **`WORKFLOW.md`** — a project north star (what you're building, current phase, constraints) injected into every session
+
+---
+
+## Requirements
+
+- [Claude Code](https://claude.ai/code)
+- [Conductor](https://conductor.build)
+- Node.js 18+
+- A git repository
+
+**Recommended MCP servers** (register once per machine):
+
+```bash
+# Graphiti memory (Zep Cloud)
+claude mcp add graphiti-memory \
+  --transport sse \
+  --url https://mcp.getzep.com/sse \
+  --header "Authorization: Api-Key $ZEP_API_KEY"
+
+# Linear
+claude mcp add linear -s user -- npx -y @linear/mcp-server
+
+# Context7 (up-to-date docs)
+claude mcp add context7 -s user -- npx -y @upstash/context7-mcp
+```
+
+---
+
+## Install
+
+Run from your project root:
+
+```bash
+npx conductor-harness
+```
+
+The installer will:
+
+1. Detect your package manager (pnpm / yarn / bun / npm)
+2. Ask if the project uses Railway
+3. Copy hooks, commands, skills, and agents into `.claude/`
+4. Merge harness hooks and permissions into `.claude/settings.local.json`
+5. Write `CLAUDE.md` with orchestration principles and harness configuration
+6. Write `conductor.json` with setup, run, and archive commands
+7. Create `WORKFLOW.md` for project context
+8. Create `.harness/progress.md` for session state
+
+Re-running is safe — `settings.local.json` is always merged, never overwritten.
+
+---
+
+## Railway projects
+
+If your project uses Railway, add these to your `.env`:
+
+```env
+RAILWAY_PROJECT_ID=your-project-id
+RAILWAY_ENVIRONMENT_ID=your-environment-id
+RAILWAY_SERVICE_ID=your-service-id
+```
+
+The generated `conductor.json` setup command will pick them up automatically via `source .env`.
+
+---
+
+## After install
+
+**Fill in `WORKFLOW.md`** — or let Claude generate it:
+
+```
+/setup
+```
+
+**Start a task:**
+
+```
+/start LIN-123
+```
+
+Or attach a Linear issue via Conductor's `+` button and type `/start` — the harness reads it directly without an MCP fetch.
+
+**End a task:**
+
+```
+/done
+```
+
+Closes the Linear issue, writes a Graphiti memory episode, and resets progress state.
+
+---
+
+## Project structure
+
+```
+runtime/
+  .claude/
+    CLAUDE.md.template      ← Orchestration principles + harness config
+    hooks/
+      session-start.sh      ← Injects context before every session
+      stop.sh               ← Saves progress on session end
+    commands/
+      start.md              ← Task kickoff ritual
+      done.md               ← Task closeout ritual
+      status.md             ← Current task status
+      setup.md              ← Project analysis + WORKFLOW.md generation
+    skills/
+      linear/SKILL.md       ← Linear issue read/write
+      memory/SKILL.md       ← Graphiti memory search/write
+      review/SKILL.md       ← Code review checklist
+    agents/
+      memory-writer.md      ← Subagent for writing memory episodes
+    settings.json.template  ← Base permissions and hook registration
+  WORKFLOW.md.template      ← Project north star template
+  conductor.json.template   ← Conductor setup/run/archive commands
+  install.sh                ← The installer (called by npx)
+```
+
+---
+
+## License
+
+MIT

package/bin/conductor-harness.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+const script = path.join(__dirname, "..", "runtime", "install.sh");
+
+try {
+  execFileSync("bash", [script], { stdio: "inherit" });
+} catch {
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "conductor-harness",
+  "version": "1.0.0",
+  "description": "Claude Code harness for Conductor projects — hooks, memory, Linear, and workflow context",
+  "bin": {
+    "conductor-harness": "./bin/conductor-harness.js"
+  },
+  "files": [
+    "bin",
+    "runtime"
+  ],
+  "keywords": ["claude-code", "conductor", "ai", "harness", "linear", "railway"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blaesild/conductor-harness.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/runtime/.claude/CLAUDE.md.template

@@ -0,0 +1,53 @@
+# [Project Name]
+
+> **Stack**: [framework] | [database] | [deployment] | [pkg manager]
+
+---
+
+## Orchestration
+
+**Plan first**: Enter plan mode for any non-trivial task (3+ steps or architectural decisions). If something goes sideways, stop and re-plan — don't push through.
+
+**Subagents**: Keep the main context clean — delegate to subagents for specialized domains. One task per subagent. Subagents cannot spawn subagents.
+
+**Delegate vs handle directly**:
+- Handle directly: < 3 files, known pattern, trivial change
+- Delegate: specialized domain, deep implementation, debugging, review
+
+**Verify before done**: Never mark complete without proving it works. Ask: "Would a staff engineer approve this?" Run tests, check logs, demonstrate correctness.
+
+**Memory over lessons**: After /done, a Graphiti episode is written. Before non-trivial work, search memory for past decisions. This is the self-improvement loop.
+
+**Docs over assumptions**: AI knowledge has a cutoff. Before using any framework, library, or package API — fetch current docs via Context7 (`mcp__claude_ai_Context7__resolve-library-id` then `mcp__claude_ai_Context7__query-docs`). Never assume an API is current. This applies in plan mode too.
+
+---
+
+## Harness
+
+@.claude/skills/linear/SKILL.md
+@.claude/skills/memory/SKILL.md
+@.claude/skills/review/SKILL.md
+
+**Linear**: If an issue is attached to the current message, read it directly — no MCP fetch needed. Use the Linear MCP tool only for additional detail (comments, history, linked issues).
+
+**Startup**: SessionStart hook injects branch, git log, WORKFLOW.md, and last session progress. Read it before responding.
+
+**End of task**: Run /done. Do not update Linear or write memory without it.
+
+---
+
+## MCP Servers
+
+<!-- Add project-specific MCP servers here -->
+| Server | Purpose |
+|--------|---------|
+
+---
+
+## Key Docs
+
+<!-- Add: architecture docs, golden rules, README -->
+
+---
+
+**Philosophy**: Trust frameworks. Use native tools. Delegate with context. Simplify.

package/runtime/.claude/agents/memory-writer.md

@@ -0,0 +1,19 @@
+---
+name: memory-writer
+description: Writes a structured memory episode to Graphiti for the current session. Called by /done and by the Stop hook when task is marked complete.
+tools: [mcp__graphiti-memory__add_episode]
+---
+
+You are a memory writer. Your only job is to write a structured episode to Graphiti.
+
+Write one episode using the add_episode tool. The episode should contain:
+- What was built or changed (concrete, specific)
+- Key decisions made and why
+- Gotchas, edge cases, or surprising discoveries
+- Patterns or utilities that could be reused in other contexts
+
+Group ID: use the project name from the current directory (lowercase, hyphens for spaces).
+
+Episode name format: "[DATE] [Branch/Feature]: [One-line summary]"
+
+Be specific and brief. This episode will be recalled in future sessions — write for your future self.

package/runtime/.claude/commands/done.md

@@ -0,0 +1,11 @@
+---
+description: "End-of-task ritual — writes memory, updates Linear, confirms PR-ready state"
+---
+
+Task completion for the current Linear issue:
+
+1. Run the type checker and any available tests. Fix any failures before continuing.
+2. Write a memory episode to Graphiti via the memory skill: include what was built, key decisions made, gotchas discovered, patterns worth reusing.
+3. Update `.harness/progress.md`: status: done, completed: [date], PR: [branch].
+4. Update the Linear issue status to "In Review" using the Linear MCP tool. Add a comment with a one-sentence summary of what was done.
+5. Confirm: "Ready for PR. Run ⌘⇧P in Conductor to create the PR."

package/runtime/.claude/commands/setup.md

@@ -0,0 +1,25 @@
+---
+description: "One-time project setup — analyze project context, generate WORKFLOW.md, tailor harness"
+---
+
+Analyze this project and generate a WORKFLOW.md:
+
+1. Read `package.json` (if exists): extract name, scripts, key dependencies.
+2. Read existing `CLAUDE.md` for any stated conventions or architecture notes.
+3. Check for: `railway.toml`, `vercel.json`, `fly.toml`, `.env.example` — detect deployment platform.
+4. Run `git log --oneline -20` — summarize the recent direction of work.
+5. Check `.claude/` for existing skills, hooks, commands — note what's already configured.
+6. Check `docs/` or `README.md` for architecture documentation.
+
+Then write `WORKFLOW.md` at the project root with:
+- **What We're Building**: 1-3 sentences from package.json name/description + README context
+- **Current Phase**: inferred from git log and feature names (MVP / scaling / maintenance / etc.)
+- **Stack**: detected framework, database, deployment, package manager
+- **Architecture Notes**: 3-5 non-obvious decisions derived from the codebase structure
+- **Active Constraints**: any rules found in CLAUDE.md or docs
+- **What We're NOT Building**: leave blank — ask Sebastian to fill this in
+
+After writing WORKFLOW.md:
+- Print "WORKFLOW.md created. Review it and fill in 'What We're NOT Building'."
+- Suggest any MCP servers not yet configured that would help this project (based on detected stack).
+- If the project uses Railway and `conductor.json` is missing, suggest running install.sh.

package/runtime/.claude/commands/start.md

@@ -0,0 +1,14 @@
+---
+description: "Task kickoff ritual — loads Linear issue, checks memory, sets progress"
+---
+
+Load task context for $ARGUMENTS:
+
+0. Check if a Linear issue is already provided in the current message context (attached via Conductor's + button). If so, read it directly — skip the MCP fetch. Only use the Linear MCP tool if additional detail is needed (comments, linked issues, acceptance criteria not shown).
+1. If $ARGUMENTS contains a Linear issue ID (e.g. LIN-123) and no issue was attached: fetch it now using the Linear MCP tool. Read the description, comments, and acceptance criteria.
+2. Search Graphiti memory for notes related to this task, feature area, or any mentioned components. Use the memory skill.
+3. Identify the primary frameworks/packages this task touches. Fetch current docs for each via Context7 — resolve the library ID first, then query for the relevant API surface. Do this before planning, not after.
+4. Run `git status` and `git log --oneline -5`.
+5. Read `.harness/progress.md` if it exists.
+6. Write a 3-5 line summary of: what you're building, what you know from memory, and the first concrete action you'll take.
+7. Update `.harness/progress.md` with: Linear issue, task summary, status: in-progress, started: [date].

package/runtime/.claude/commands/status.md

@@ -0,0 +1,11 @@
+---
+description: "Show current session state — branch, Linear issue, progress, recent commits"
+---
+
+Show current harness status:
+
+1. Print current git branch and any detected Linear issue ID.
+2. Show `.harness/progress.md` contents if it exists.
+3. Show `git log --oneline -5`.
+4. Show `git status --short`.
+5. Check if any Graphiti memory exists for this task (use memory skill to search by branch name).

package/runtime/.claude/hooks/session-start.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# SessionStart hook — injects structured context before first user message
+# Receives JSON event on stdin, returns {"promptText": "..."} on stdout
+import sys, json, subprocess, os, re
+
+event = json.load(sys.stdin)
+cwd = event.get("cwd", os.getcwd())
+
+# Get branch name → extract Linear issue ID
+try:
+    branch = subprocess.check_output(
+        ["git", "-C", cwd, "branch", "--show-current"],
+        stderr=subprocess.DEVNULL, text=True
+    ).strip()
+except Exception:
+    branch = "unknown"
+
+linear_match = re.search(r'([A-Z]+-\d+)', branch.upper())
+linear_id = linear_match.group(1) if linear_match else None
+
+# Recent git log
+try:
+    git_log = subprocess.check_output(
+        ["git", "-C", cwd, "log", "--oneline", "-8"],
+        stderr=subprocess.DEVNULL, text=True
+    ).strip()
+except Exception:
+    git_log = "(no git history)"
+
+# Progress file
+progress = ""
+progress_path = os.path.join(cwd, ".harness", "progress.md")
+if os.path.exists(progress_path):
+    with open(progress_path) as f:
+        progress = f.read().strip()
+
+# WORKFLOW.md — project north star
+workflow = ""
+for workflow_path in [
+    os.path.join(cwd, "WORKFLOW.md"),
+    os.path.join(cwd, ".harness", "WORKFLOW.md"),
+]:
+    if os.path.exists(workflow_path):
+        with open(workflow_path) as f:
+            workflow = f.read().strip()
+        break
+
+# Build context block
+lines = ["## Harness: Session Context", ""]
+lines.append(f"**Branch:** `{branch}`")
+if linear_id:
+    lines.append(f"**Linear issue detected:** `{linear_id}` — fetch details with the Linear MCP tool before starting work.")
+lines.append("")
+lines.append("**Recent commits:**")
+lines.append("```")
+lines.append(git_log or "(none)")
+lines.append("```")
+if progress:
+    lines.append("")
+    lines.append("**Last session progress:**")
+    lines.append(progress)
+if workflow:
+    lines.append("")
+    lines.append("**Project context (WORKFLOW.md):**")
+    lines.append(workflow)
+lines.append("")
+lines.append("**Action:** Search Graphiti memory for context relevant to this branch/task before responding to the user. Use the `memory` skill if needed.")
+
+print(json.dumps({"promptText": "\n".join(lines)}))

package/runtime/.claude/hooks/stop.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# Stop hook — runs after Claude finishes each response
+# Runs type checker. If errors: exit 2 (blocks, Claude sees stderr and fixes).
+# Non-blocking: memory writes happen via the /done command, not on every stop.
+import sys, json, subprocess, os
+
+event = json.load(sys.stdin)
+cwd = event.get("cwd", os.getcwd())
+
+# Detect project type and run appropriate type checker
+errors = []
+if os.path.exists(os.path.join(cwd, "tsconfig.json")):
+    try:
+        result = subprocess.run(
+            ["npx", "--no-install", "tsc", "--noEmit"],
+            cwd=cwd, capture_output=True, text=True, timeout=30
+        )
+        if result.returncode != 0:
+            errors.append(result.stdout + result.stderr)
+    except subprocess.TimeoutExpired:
+        pass  # Don't block on timeout
+    except FileNotFoundError:
+        pass  # npx not available, skip
+
+if errors:
+    # exit 2 = block, stderr is shown to Claude
+    print("\n".join(errors), file=sys.stderr)
+    sys.exit(2)
+
+sys.exit(0)

package/runtime/.claude/settings.json.template

@@ -0,0 +1,31 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": ".claude/hooks/session-start.sh"
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": ".claude/hooks/stop.sh",
+        "timeout": 30
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(<PKG_MANAGER> *)",
+      "Bash(npx *)",
+      "Bash(tsc *)"
+    ],
+    "deny": [
+      "Bash(git push --force *)",
+      "Bash(git push -f *)"
+    ]
+  }
+}
+
+Note: install.sh substitutes <PKG_MANAGER> with the detected package manager before writing settings.json.

package/runtime/.claude/skills/linear/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: linear
+description: "Fetch and update Linear issues for the current task"
+---
+
+# Linear Skill
+
+Use the Linear MCP tool to interact with issues.
+
+## Common operations
+
+**Fetch issue:**
+Use `linear_get_issue` with the issue ID (e.g. LIN-123). Read title, description, comments, and acceptance criteria.
+
+**Update status:**
+Use `linear_save_issue` to update the status field. Valid transitions: Todo → In Progress → In Review → Done.
+
+**Add comment:**
+Use `linear_save_comment` to add a progress note or completion summary.
+
+## Gotchas
+- Issue IDs in branch names are uppercase (LIN-123); Linear API accepts both cases
+- Always check acceptance criteria before marking done — it's often in the description
+- If no Linear MCP is connected, instruct the user to run: `claude mcp add linear -s user -- npx -y @linear/mcp-server`

package/runtime/.claude/skills/memory/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: memory
+description: "Search and write to Graphiti cross-session memory for this project"
+---
+
+# Memory Skill
+
+Uses Graphiti MCP (Zep Cloud) for persistent cross-session memory.
+
+## MCP tool reference
+- `search_facts(query, group_id)` — semantic search for facts/edges
+- `search_nodes(query, group_id)` — semantic search for entities
+- `add_episode(name, episode_body, group_id, source_description)` — write new memory
+- `get_episodes(group_id, last_n)` — get recent episodes
+
+## group_id convention
+Use the project name: `nerdic-next`, `monomos`, `openfang`, `data-agent`, etc.
+Derive from the git remote URL or project root directory name.
+
+## When to search memory
+- At session start (automatically via SessionStart hook)
+- Before implementing any non-trivial feature
+- When encountering an error that might have been seen before
+- Before making architectural decisions
+
+## When to write memory
+- After /done command completes
+- After discovering a non-obvious gotcha
+- After making an architectural decision with lasting implications
+
+## Gotchas
+- If MCP is not connected, instruct: `claude mcp add graphiti-memory --transport sse --url https://mcp.getzep.com/sse --header "Authorization: Api-Key $ZEP_API_KEY"`
+- Keep episodes specific and brief — Graphiti retrieves by semantic similarity, verbose episodes dilute signal
+- Do not write memory for obvious facts, boilerplate decisions, or things already in CLAUDE.md

package/runtime/.claude/skills/review/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: review
+description: "Pre-PR code review checklist for harness-engineered projects"
+---
+
+# Review Skill
+
+Run this before creating a PR. Check each item:
+
+## Code quality
+- [ ] TypeScript: `tsc --noEmit` passes with zero errors
+- [ ] No `console.log` debug statements committed
+- [ ] No hardcoded secrets, API keys, or environment-specific values
+- [ ] All new files follow existing naming conventions
+
+## Correctness
+- [ ] The Linear acceptance criteria are met (re-read them now)
+- [ ] Edge cases handled (empty states, error paths, loading states)
+- [ ] No obvious N+1 queries or unnecessary re-renders
+
+## Harness hygiene
+- [ ] `.harness/progress.md` updated with done status
+- [ ] Memory episode written to Graphiti (run /done if not done)
+- [ ] No debug/temp files committed
+
+## Git
+- [ ] Commits are clean and descriptive (not "fix stuff" or "wip")
+- [ ] Branch is up to date with main (run `git fetch && git rebase origin/main` if needed)
+
+If anything fails, fix it before creating the PR.

package/runtime/.gitignore.append

@@ -0,0 +1,2 @@
+# Harness local state
+.harness/

package/runtime/WORKFLOW.md.template

@@ -0,0 +1,31 @@
+# WORKFLOW.md — [Project Name]
+
+<!--
+North star for Claude Code sessions in this project.
+Injected by the SessionStart hook into every session.
+Update when: goals shift, architecture changes, or constraints change.
+Keep it short — this is injected into every session context.
+-->
+
+## What We're Building
+<!-- 1-3 sentences: what this is and who it's for -->
+
+## Current Phase
+<!-- MVP / feature-build / scaling / maintenance / migration -->
+
+## Stack
+<!-- Framework | Database | Deployment | Package manager -->
+
+## Architecture Notes
+<!-- 3-5 bullet points: non-obvious decisions that shape this codebase -->
+-
+-
+-
+
+## Active Constraints
+<!-- Rules Claude must follow for this project -->
+-
+
+## What We're NOT Building
+<!-- Explicit out-of-scope to prevent scope creep -->
+-

package/runtime/conductor.json.template

@@ -0,0 +1,5 @@
+{
+  "setup": "ln -s \"$CONDUCTOR_ROOT_PATH/.env\" .env && source .env && <PKG_MANAGER> install && <PKG_MANAGER> run generate:types 2>/dev/null || true && railway link --project $RAILWAY_PROJECT_ID --environment $RAILWAY_ENVIRONMENT_ID --service $RAILWAY_SERVICE_ID",
+  "run": "<PKG_MANAGER> dev --port $CONDUCTOR_PORT",
+  "archive": "rm -rf .next node_modules .turbo"
+}

package/runtime/install.sh

@@ -0,0 +1,258 @@
+#!/usr/bin/env bash
+# Harness install.sh — installs Claude Code harness into any project root
+# Usage: cd /path/to/your-project && bash /path/to/Harness/runtime/install.sh
+set -euo pipefail
+
+HARNESS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET_DIR="$(pwd)"
+
+# ── 1. Must be in a git repo ─────────────────────────────────────────────────
+if ! git -C "$TARGET_DIR" rev-parse --git-dir > /dev/null 2>&1; then
+  echo "ERROR: Not a git repository. Run install.sh from your project root." >&2
+  exit 1
+fi
+
+echo "Installing Harness into: $TARGET_DIR"
+echo ""
+
+# ── 2. Detect package manager ────────────────────────────────────────────────
+if [ -f "$TARGET_DIR/pnpm-lock.yaml" ]; then
+  PKG_MANAGER="pnpm"
+elif [ -f "$TARGET_DIR/yarn.lock" ]; then
+  PKG_MANAGER="yarn"
+elif [ -f "$TARGET_DIR/bun.lockb" ]; then
+  PKG_MANAGER="bun"
+elif [ -f "$TARGET_DIR/package-lock.json" ]; then
+  PKG_MANAGER="npm"
+else
+  echo "WARNING: No lockfile found. Defaulting to npm."
+  PKG_MANAGER="npm"
+fi
+echo "Detected package manager: $PKG_MANAGER"
+
+# ── 3. Railway prompt ────────────────────────────────────────────────────────
+read -r -p "Does this project use Railway? [y/N] " USE_RAILWAY
+USE_RAILWAY="${USE_RAILWAY,,}"
+
+# ── 4. Create .claude subdirs ────────────────────────────────────────────────
+mkdir -p \
+  "$TARGET_DIR/.claude/hooks" \
+  "$TARGET_DIR/.claude/commands" \
+  "$TARGET_DIR/.claude/agents" \
+  "$TARGET_DIR/.claude/skills/linear" \
+  "$TARGET_DIR/.claude/skills/memory" \
+  "$TARGET_DIR/.claude/skills/review"
+
+# ── 5. Copy hook scripts ─────────────────────────────────────────────────────
+cp "$HARNESS_DIR/.claude/hooks/session-start.sh" "$TARGET_DIR/.claude/hooks/session-start.sh"
+cp "$HARNESS_DIR/.claude/hooks/stop.sh" "$TARGET_DIR/.claude/hooks/stop.sh"
+chmod +x "$TARGET_DIR/.claude/hooks/session-start.sh"
+chmod +x "$TARGET_DIR/.claude/hooks/stop.sh"
+echo "✓ Hooks installed"
+
+# ── 6. Copy commands ─────────────────────────────────────────────────────────
+cp "$HARNESS_DIR/.claude/commands/start.md"  "$TARGET_DIR/.claude/commands/start.md"
+cp "$HARNESS_DIR/.claude/commands/done.md"   "$TARGET_DIR/.claude/commands/done.md"
+cp "$HARNESS_DIR/.claude/commands/status.md" "$TARGET_DIR/.claude/commands/status.md"
+echo "✓ Commands installed (/start, /done, /status)"
+
+# ── 7. Copy agents ───────────────────────────────────────────────────────────
+cp "$HARNESS_DIR/.claude/agents/memory-writer.md" "$TARGET_DIR/.claude/agents/memory-writer.md"
+echo "✓ Agents installed"
+
+# ── 8. Copy skills ───────────────────────────────────────────────────────────
+cp "$HARNESS_DIR/.claude/skills/linear/SKILL.md"  "$TARGET_DIR/.claude/skills/linear/SKILL.md"
+cp "$HARNESS_DIR/.claude/skills/memory/SKILL.md"  "$TARGET_DIR/.claude/skills/memory/SKILL.md"
+cp "$HARNESS_DIR/.claude/skills/review/SKILL.md"  "$TARGET_DIR/.claude/skills/review/SKILL.md"
+echo "✓ Skills installed (linear, memory, review)"
+
+# ── 9. settings.local.json — always merge (never overwrite) ──────────────────
+SETTINGS_FILE="$TARGET_DIR/.claude/settings.local.json"
+
+if [ -f "$SETTINGS_FILE" ]; then
+  echo "Merging hooks into existing .claude/settings.local.json..."
+  python3 - "$SETTINGS_FILE" "$PKG_MANAGER" <<'PYEOF'
+import sys, json
+
+settings_path = sys.argv[1]
+pkg_manager = sys.argv[2]
+
+with open(settings_path) as f:
+    existing = json.load(f)
+
+harness_hooks = {
+    "SessionStart": [{"type": "command", "command": ".claude/hooks/session-start.sh"}],
+    "Stop": [{"type": "command", "command": ".claude/hooks/stop.sh", "timeout": 30}]
+}
+
+harness_allow = [
+    f"Bash(git *)",
+    f"Bash({pkg_manager} *)",
+    "Bash(npx *)",
+    "Bash(tsc *)"
+]
+
+harness_deny = [
+    "Bash(git push --force *)",
+    "Bash(git push -f *)"
+]
+
+# Merge hooks
+if "hooks" not in existing:
+    existing["hooks"] = {}
+for event, entries in harness_hooks.items():
+    if event not in existing["hooks"]:
+        existing["hooks"][event] = []
+    existing_cmds = [h.get("command") for h in existing["hooks"][event]]
+    for entry in entries:
+        if entry.get("command") not in existing_cmds:
+            existing["hooks"][event].append(entry)
+
+# Merge permissions
+if "permissions" not in existing:
+    existing["permissions"] = {}
+if "allow" not in existing["permissions"]:
+    existing["permissions"]["allow"] = []
+if "deny" not in existing["permissions"]:
+    existing["permissions"]["deny"] = []
+
+for item in harness_allow:
+    if item not in existing["permissions"]["allow"]:
+        existing["permissions"]["allow"].append(item)
+for item in harness_deny:
+    if item not in existing["permissions"]["deny"]:
+        existing["permissions"]["deny"].append(item)
+
+with open(settings_path, "w") as f:
+    json.dump(existing, f, indent=2)
+print("✓ settings.local.json merged")
+PYEOF
+else
+  # Create fresh settings.local.json from template with PKG_MANAGER substituted
+  python3 - "$HARNESS_DIR/.claude/settings.json.template" "$SETTINGS_FILE" "$PKG_MANAGER" <<'PYEOF'
+import sys, json, re
+
+template_path = sys.argv[1]
+out_path = sys.argv[2]
+pkg_manager = sys.argv[3]
+
+with open(template_path) as f:
+    content = f.read()
+
+content = content.replace("<PKG_MANAGER>", pkg_manager)
+
+# Strip the trailing Note comment before parsing JSON
+content = re.sub(r'\n\nNote:.*', '', content, flags=re.DOTALL)
+
+data = json.loads(content)
+with open(out_path, "w") as f:
+    json.dump(data, f, indent=2)
+print("✓ settings.local.json created")
+PYEOF
+fi
+
+# ── 10. CLAUDE.md — always overwrite ─────────────────────────────────────────
+CLAUDE_MD="$TARGET_DIR/CLAUDE.md"
+cp "$HARNESS_DIR/.claude/CLAUDE.md.template" "$CLAUDE_MD"
+echo "✓ CLAUDE.md written (overwritten)"
+
+# ── 11. conductor.json — always overwrite ─────────────────────────────────────
+CONDUCTOR_FILE="$TARGET_DIR/conductor.json"
+
+if true; then
+  if [ "$USE_RAILWAY" = "y" ] || [ "$USE_RAILWAY" = "yes" ]; then
+    SETUP_CMD="ln -s \"\$CONDUCTOR_ROOT_PATH/.env\" .env && source .env && ${PKG_MANAGER} install && ${PKG_MANAGER} run generate:types 2>/dev/null || true && railway link --project \$RAILWAY_PROJECT_ID --environment \$RAILWAY_ENVIRONMENT_ID --service \$RAILWAY_SERVICE_ID"
+  else
+    SETUP_CMD="ln -s \"\$CONDUCTOR_ROOT_PATH/.env\" .env && ${PKG_MANAGER} install && ${PKG_MANAGER} run generate:types 2>/dev/null || true"
+  fi
+
+  python3 - "$CONDUCTOR_FILE" "$PKG_MANAGER" "$SETUP_CMD" <<'PYEOF'
+import sys, json
+
+out_path = sys.argv[1]
+pkg_manager = sys.argv[2]
+setup_cmd = sys.argv[3]
+
+data = {
+    "setup": setup_cmd,
+    "run": f"{pkg_manager} dev --port $CONDUCTOR_PORT",
+    "archive": "rm -rf .next node_modules .turbo"
+}
+with open(out_path, "w") as f:
+    json.dump(data, f, indent=2)
+print("✓ conductor.json written (overwritten)")
+PYEOF
+  if [ "$USE_RAILWAY" = "y" ] || [ "$USE_RAILWAY" = "yes" ]; then
+    echo "  → Add RAILWAY_PROJECT_ID, RAILWAY_ENVIRONMENT_ID, RAILWAY_SERVICE_ID to your .env"
+  fi
+fi
+
+# ── 12. .gitignore — append .harness/ if missing ─────────────────────────────
+GITIGNORE="$TARGET_DIR/.gitignore"
+if [ -f "$GITIGNORE" ]; then
+  if grep -qF ".harness/" "$GITIGNORE"; then
+    echo "✓ .gitignore already ignores .harness/ (skipped)"
+  else
+    echo "" >> "$GITIGNORE"
+    echo "# Harness local state" >> "$GITIGNORE"
+    echo ".harness/" >> "$GITIGNORE"
+    echo "✓ .harness/ added to .gitignore"
+  fi
+else
+  printf "# Harness local state\n.harness/\n" > "$GITIGNORE"
+  echo "✓ .gitignore created with .harness/"
+fi
+
+# ── 13. Create .harness/ with progress stub ───────────────────────────────────
+mkdir -p "$TARGET_DIR/.harness"
+if [ ! -f "$TARGET_DIR/.harness/progress.md" ]; then
+  cat > "$TARGET_DIR/.harness/progress.md" <<'EOF'
+# Harness Progress
+
+<!-- Updated automatically by /start and /done commands -->
+
+status: idle
+EOF
+  echo "✓ .harness/progress.md created"
+fi
+
+# ── 14. WORKFLOW.md — copy template if not already present ───────────────────
+if [ ! -f "$TARGET_DIR/WORKFLOW.md" ]; then
+  cp "$HARNESS_DIR/WORKFLOW.md.template" "$TARGET_DIR/WORKFLOW.md"
+  echo "✓ WORKFLOW.md created — fill in your project context"
+else
+  echo "✓ WORKFLOW.md already exists (skipped)"
+fi
+
+# ── 15. Next steps ────────────────────────────────────────────────────────────
+echo ""
+echo "══════════════════════════════════════════════════"
+echo "  Harness installed successfully!"
+echo "══════════════════════════════════════════════════"
+echo ""
+echo "Next steps:"
+echo ""
+echo "1. Register Zep Cloud memory MCP (once per machine):"
+echo "   export ZEP_API_KEY=your_zep_api_key_here"
+echo "   claude mcp add graphiti-memory \\"
+echo "     --transport sse \\"
+echo "     --url https://mcp.getzep.com/sse \\"
+echo "     --header \"Authorization: Api-Key \$ZEP_API_KEY\""
+echo ""
+echo "2. Register Linear MCP (once per machine, if not already):"
+echo "   claude mcp add linear -s user -- npx -y @linear/mcp-server"
+echo ""
+echo "3. Open this project in Claude Code — hooks will fire automatically."
+echo ""
+echo "4. Start a task: /start LIN-123"
+echo "   End a task:   /done"
+echo "   Check status: /status"
+echo ""
+echo "5. Fill in WORKFLOW.md — this is injected into every Claude Code session as project context."
+echo "   Or run /setup to auto-generate it from your project structure."
+echo ""
+if [ "$USE_RAILWAY" = "y" ] || [ "$USE_RAILWAY" = "yes" ]; then
+  echo "6. Edit conductor.json and replace the RAILWAY_* placeholders."
+  echo ""
+fi
+echo "Docs: https://github.com/blaesild/conductor-harness"