conductor-harness 1.1.1 → 1.2.0

package/README.md

@@ -6,13 +6,11 @@ A Claude Code harness for [Conductor](https://conductor.build) projects. Install
 
 ## What it does
 
-- **SessionStart hook** — injects branch, recent commits, last session progress, and `WORKFLOW.md` context before every Claude Code session
+- **SessionStart hook** — injects branch, recent commits, and last session progress before every Claude Code session
 - **Linear integration** — reads attached issues directly from Conductor's `+` button; falls back to Linear MCP for comments and history
-- **Hindsight memory** — searches past decisions before starting work; writes memories after `/done`
+- **Native memory** — persists decisions across sessions using Claude Code's built-in memory system; optionally augmented with Hindsight cloud
 - **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
 
 ---
 
@@ -20,11 +18,6 @@ A Claude Code harness for [Conductor](https://conductor.build) projects. Install
 
 ### 1. Install MCP servers (once per machine)
 
-**Hindsight** — persistent cross-session memory for decisions, gotchas, and patterns:
-1. Get an API key at [ui.hindsight.vectorize.io/connect](https://ui.hindsight.vectorize.io/connect)
-2. Add to your `.env`: `HINDSIGHT_API_KEY=your_key_here`
-3. The installer creates `.mcp.json` with the Hindsight config automatically — no CLI command needed.
-
 **Linear** — read and update issues from Claude Code:
 ```bash
 claude mcp add linear -s user -- npx -y @linear/mcp-server
@@ -55,15 +48,7 @@ RAILWAY_ENVIRONMENT_ID=your-environment-id
 RAILWAY_SERVICE_ID=your-service-id
 ```
 
-### 4. Fill in WORKFLOW.md
-
-Either edit `WORKFLOW.md` manually, or open the project in Claude Code and run:
-```
-/setup
-```
-This is a Claude Code slash command — type it in the Claude Code chat, not in the terminal.
-
-### 5. Start working
+### 4. Start working
 
 Open the project in Claude Code via Conductor. The SessionStart hook fires automatically and injects your project context.
 
@@ -84,7 +69,15 @@ Open the project in Claude Code via Conductor. The SessionStart hook fires autom
 
 Or attach a Linear issue via Conductor's `+` button and type `/start` — the harness reads it directly without an MCP fetch.
 
-`/done` closes the Linear issue, writes a Graphiti memory episode, and resets progress state.
+`/done` closes the Linear issue, writes a memory file, and resets progress state.
+
+### Optional: Hindsight cloud memory
+
+For semantic search across large memory sets, you can optionally enable Hindsight cloud memory during install. The installer will prompt you — native Claude Code memory is the default.
+
+1. Get an API key at [ui.hindsight.vectorize.io/connect](https://ui.hindsight.vectorize.io/connect)
+2. Add to your `.env`: `HINDSIGHT_API_KEY=your_key_here`
+3. Re-run the installer and answer "y" to Hindsight
 
 ---
 
@@ -101,15 +94,12 @@ runtime/
       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
+    agents/                  ← Project-specific subagents
     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)
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "conductor-harness",
-  "version": "1.1.1",
-  "description": "Claude Code harness for Conductor projects — hooks, memory, Linear, and workflow context",
+  "version": "1.2.0",
+  "description": "Claude Code harness for Conductor projects — hooks, memory, Linear integration",
   "bin": {
     "conductor-harness": "./bin/conductor-harness.js"
   },
@@ -9,7 +9,14 @@
     "bin",
     "runtime"
   ],
-  "keywords": ["claude-code", "conductor", "ai", "harness", "linear", "railway"],
+  "keywords": [
+    "claude-code",
+    "conductor",
+    "ai",
+    "harness",
+    "linear",
+    "railway"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -2,25 +2,31 @@
 
 > **Stack**: [framework] | [database] | [deployment] | [pkg-manager]
 
----
+## Principles
+
+- Simplicity first — make every change as simple as possible, impact minimal code
+- Find root causes — no temporary fixes, no band-aids
+- Minimal impact — only touch what's necessary
+- Demand elegance — for non-trivial changes, pause and ask "is there a more elegant way?" Skip for obvious fixes
 
 ## 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.
+**Plan first**: Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write detailed specs upfront. 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.
+**Subagents**: Use subagents liberally to keep main context clean. Offload research, exploration, and parallel analysis. One task per subagent.
 
-**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. Run tests, check logs, demonstrate correctness. Ask: "Would a staff engineer approve this?"
 
-**Verify before done**: Never mark complete without proving it works. Ask: "Would a staff engineer approve this?" Run tests, check logs, demonstrate correctness.
+**Autonomous fixing**: When given a bug report or failing test — just fix it. Point at logs, errors, failing tests, then resolve them. Zero hand-holding required.
 
-**Memory over lessons**: After /done, a memory is written to Hindsight. Before non-trivial work, recall past decisions. This is the self-improvement loop.
+**Docs over assumptions**: Before using any framework/library/package API — fetch current docs via Context7. Never assume an API is current. This applies in plan mode too.
 
-**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.
+## Memory
 
----
+After ANY correction: write a memory so the same mistake isn't repeated.
+After /done: write a memory with what was built, decisions, gotchas.
+Before non-trivial work: check MEMORY.md for past decisions.
+This is the self-improvement loop — ruthlessly iterate until mistake rate drops.
 
 ## Harness
 
@@ -28,24 +34,16 @@
 @.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).
+**Linear**: If an issue is attached, read it directly — no MCP fetch needed. Use Linear MCP only for additional detail.
 
-**Startup**: SessionStart hook injects branch, git log, WORKFLOW.md, and last session progress. Read it before responding.
+**Startup**: SessionStart hook injects branch, git log, and last session progress. Read it before responding.
 
 **End of task**: Run /done. Do not update Linear or write memory without it.
 
----
-
 ## MCP Servers
 
 [mcp-servers-table]
 
----
-
 ## Key Docs
 
 [key-docs]
-
----
-
-**Philosophy**: Trust frameworks. Use native tools. Delegate with context. Simplify.

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

@@ -5,7 +5,7 @@ description: "End-of-task ritual — writes memory, updates Linear, confirms PR-
 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 to Hindsight via the memory skill: include what was built, key decisions made, gotchas discovered, patterns worth reusing. Tag with the project name.
+2. Write a memory following the memory skill. Include what was built, key decisions, gotchas discovered, and 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/start.md

@@ -6,7 +6,7 @@ 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.
+2. Check MEMORY.md (already in context) for entries relevant to this task or feature area. Read specific memory files if needed for detail.
 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.

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

@@ -8,4 +8,4 @@ Show current harness status:
 2. Show `.harness/progress.md` contents if it exists.
 3. Show `git log --oneline -5`.
 4. Show `git status --short`.
-5. Check if any Hindsight memory exists for this task (use memory skill to recall by branch name).
+5. Check MEMORY.md for any memory entries related to the current branch or task.

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

@@ -27,23 +27,19 @@ try:
 except Exception:
     git_log = "(no git history)"
 
+# Ensure .harness/ exists (worktrees don't inherit gitignored dirs)
+harness_dir = os.path.join(cwd, ".harness")
+os.makedirs(harness_dir, exist_ok=True)
+
 # Progress file
 progress = ""
-progress_path = os.path.join(cwd, ".harness", "progress.md")
+progress_path = os.path.join(harness_dir, "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
+else:
+    with open(progress_path, "w") as f:
+        f.write("# Harness Progress\n\nstatus: idle\n")
 
 # Build context block
 lines = ["## Harness: Session Context", ""]
@@ -59,11 +55,7 @@ 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 Hindsight memory for context relevant to this branch/task before responding to the user. Use the `memory` skill if needed.")
+lines.append("**Action:** MEMORY.md is loaded automatically. Scan it for entries relevant to this branch/task before responding.")
 
 print(json.dumps({"promptText": "\n".join(lines)}))

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

@@ -1,33 +1,79 @@
 ---
 name: memory
-description: "Search and write to Hindsight cross-session memory for this project"
+description: "Write and recall cross-session memory using Claude Code's native memory system"
 ---
 
 # Memory Skill
 
-Uses Hindsight MCP for persistent cross-session memory.
+Uses Claude Code's built-in memory system. Memories are stored as markdown files in `~/.claude/projects/[project-path]/memory/` with a `MEMORY.md` index that is automatically loaded into every session.
 
-## MCP tool reference
-- `recall(query)` — semantic search across stored memories
-- `retain(content, tags)` — write a new memory (decisions, gotchas, patterns)
-- `reflect(question)` — get an AI answer using your memories as context
-- `create_mental_model(name, description)` — create a living summary document
+## How it works
 
-## 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
+- **MEMORY.md** (the index) is loaded into context at session start — no action needed to recall
+- To **write** a memory: use the Write tool to create a file in the memory directory with YAML frontmatter
+- To **read** a specific memory: use the Read tool on a file listed in MEMORY.md
+- To **update** the index: add a one-line pointer to MEMORY.md after writing a memory file
+
+## Memory file format
+
+```markdown
+---
+name: descriptive name
+description: one-line summary — used for relevance matching in future sessions
+type: project
+---
+
+[Memory content here]
+```
+
+## Types
+
+| Type | Use for |
+|------|---------|
+| `project` | What was built, decisions made, gotchas discovered, patterns worth reusing |
+| `feedback` | How the user wants Claude to work — corrections and confirmed approaches |
+| `user` | User's role, expertise, preferences |
+| `reference` | Pointers to external resources (Linear projects, dashboards, docs) |
 
 ## When to write memory
-- After /done command completes
-- After discovering a non-obvious gotcha
-- After making an architectural decision with lasting implications
 
-## Tagging convention
-Always tag memories with the project name derived from the git remote URL or project root directory name (e.g. `my-project`, `api-service`).
+- After `/done` — what was built, key decisions, gotchas, reusable patterns
+- After discovering a non-obvious gotcha or edge case
+- After architectural decisions with lasting implications
+
+## When NOT to write memory
+
+- Obvious facts or boilerplate decisions
+- Things already in CLAUDE.md
+- Ephemeral state (current git status, in-progress work)
+- Information derivable from code or git history
+
+## Episode structure (for project memories after /done)
+
+```markdown
+---
+name: branch-or-feature-name
+description: one-line summary of what was done
+type: project
+---
+
+## What was built
+[Concrete: filenames, function names, components]
+
+## Key decisions
+- [Decision]: [why]
 
 ## Gotchas
-- If MCP is not connected, add `HINDSIGHT_API_KEY` to `.env` and ensure `.mcp.json` is present
-- Keep memories specific and brief — recall uses semantic search, verbose entries dilute signal
-- Do not write memory for obvious facts, boilerplate decisions, or things already in CLAUDE.md
+- [Non-obvious discovery]
+
+## Reusable patterns
+- [Pattern]: [where in codebase]
+```
+
+## Optional: Hindsight cloud memory
+
+If Hindsight MCP is configured (via `.mcp.json` and `HINDSIGHT_API_KEY`), you may also use:
+- `recall(query)` — semantic search across cloud-stored memories
+- `retain(content, tags)` — write to cloud memory
+
+Native memory is the default. Hindsight is a supplemental option for semantic search across large memory sets.

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

@@ -20,7 +20,7 @@ Run this before creating a PR. Check each item:
 
 ## Harness hygiene
 - [ ] `.harness/progress.md` updated with done status
-- [ ] Memory episode written to Graphiti (run /done if not done)
+- [ ] Memory written (run /done if not done)
 - [ ] No debug/temp files committed
 
 ## Git

package/runtime/install.sh

@@ -56,9 +56,8 @@ cp "$HARNESS_DIR/.claude/commands/done.md"   "$TARGET_DIR/.claude/commands/done.
 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"
+# ── 7. Agents directory (reserved for project-specific agents) ───────────────
+echo "✓ Agents directory ready"
 
 # ── 8. Copy skills ───────────────────────────────────────────────────────────
 cp "$HARNESS_DIR/.claude/skills/linear/SKILL.md"  "$TARGET_DIR/.claude/skills/linear/SKILL.md"
@@ -228,7 +227,7 @@ elif os.path.exists(os.path.join(cwd, "Dockerfile")):
 
 # ── MCP servers ────────────────────────────────────────────────────────────────
 known_purposes = {
-    "hindsight": "Cross-session memory (decisions, gotchas, patterns)",
+    "hindsight": "Cross-session cloud memory — optional supplement to native memory",
     "linear": "Issue tracking — read/update Linear issues",
     "context7": "Up-to-date framework and package documentation",
     "graphiti-memory": "Graph memory",
@@ -353,18 +352,13 @@ 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
+# ── 14. Hindsight cloud memory (optional) ─────────────────────────────────────
+read -r -p "Use Hindsight cloud memory? (default: native Claude Code memory) [y/N] " USE_HINDSIGHT
+USE_HINDSIGHT="$(echo "$USE_HINDSIGHT" | tr '[:upper:]' '[:lower:]')"
 
-# ── 15. .mcp.json — create or append Hindsight MCP entry ─────────────────────
-MCP_JSON="$TARGET_DIR/.mcp.json"
-
-python3 - "$MCP_JSON" <<'PYEOF'
+if [ "$USE_HINDSIGHT" = "y" ] || [ "$USE_HINDSIGHT" = "yes" ]; then
+  MCP_JSON="$TARGET_DIR/.mcp.json"
+  python3 - "$MCP_JSON" <<'PYEOF'
 import sys, json, os
 
 mcp_path = sys.argv[1]
@@ -394,6 +388,9 @@ else:
 with open(mcp_path, "w") as f:
     json.dump(data, f, indent=2)
 PYEOF
+else
+  echo "✓ Using native Claude Code memory (no cloud setup needed)"
+fi
 
 # ── 16. Next steps ────────────────────────────────────────────────────────────
 echo ""
@@ -403,9 +400,14 @@ echo "════════════════════════
 echo ""
 echo "Next steps:"
 echo ""
-echo "1. Add your Hindsight API key to .env:"
-echo "   HINDSIGHT_API_KEY=your_key_here"
-echo "   Get a key at: https://ui.hindsight.vectorize.io/connect"
+echo "1. Memory works out of the box via Claude Code's native memory system."
+echo "   No API key or configuration needed."
+if [ "$USE_HINDSIGHT" = "y" ] || [ "$USE_HINDSIGHT" = "yes" ]; then
+  echo ""
+  echo "   Hindsight cloud memory is also enabled. Add your API key to .env:"
+  echo "   HINDSIGHT_API_KEY=your_key_here"
+  echo "   Get a key at: https://ui.hindsight.vectorize.io/connect"
+fi
 echo ""
 echo "2. Register Linear MCP (once per machine, if not already):"
 echo "   claude mcp add linear -s user -- npx -y @linear/mcp-server"
@@ -416,11 +418,8 @@ echo "4. Start a task: /start LIN-123"
 echo "   End a task:   /done"
 echo "   Check status: /status"
 echo ""
-echo "5. Fill in WORKFLOW.md — injected into every Claude Code session as project context."
-echo "   Or type /setup inside Claude Code to auto-generate it from your project structure."
-echo ""
 if [ "$USE_RAILWAY" = "y" ] || [ "$USE_RAILWAY" = "yes" ]; then
-  echo "6. Add Railway IDs to .env (or .env.local):"
+  echo "5. Add Railway IDs to .env (or .env.local):"
   echo "   RAILWAY_PROJECT_ID=your-project-id"
   echo "   RAILWAY_ENVIRONMENT_ID=your-environment-id"
   echo "   RAILWAY_SERVICE_ID=your-service-id"

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

@@ -1,19 +0,0 @@
----
-name: memory-writer
-description: Writes a structured memory to Hindsight for the current session. Called by /done and by the Stop hook when task is marked complete.
-tools: [mcp__hindsight__retain]
----
-
-You are a memory writer. Your only job is to write a structured memory to Hindsight.
-
-Write one memory using the retain tool. The memory 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
-
-Tag with the project name (lowercase, hyphens for spaces) derived from the current directory.
-
-Format: "[DATE] [Branch/Feature]: [One-line summary]\n\n[Body]"
-
-Be specific and brief. This memory will be recalled in future sessions — write for your future self.

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

@@ -1,25 +0,0 @@
----
-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/WORKFLOW.md.template

@@ -1,31 +0,0 @@
-# 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 -->
--