Claude Code Long-Running Agent Harness

A Claude Code plugin for automated, context-preserving coding sessions with 5-layer memory architecture, failure prevention, test-driven features, and GitHub integration.

Based on Anthropic's engineering article and enhanced with patterns from:

• Context-Engine - Memory architecture
• Agent-Foreman - Task management patterns
• Autonomous-Coding - Test-driven approach

TL;DR - End-to-End Workflow

Quick Start

# Step 1: Add the marketplace (registers the catalog)
/plugin marketplace add panayiotism/claude-harness-marketplace

# Step 2: Install the plugin
/plugin install claude-harness@claude-harness

Or from the terminal:

claude plugin marketplace add panayiotism/claude-harness-marketplace
claude plugin install claude-harness@claude-harness

# Initialize in your project (one-time)
cd your-project && claude
/claude-harness:setup

# Single command for entire workflow (start → do → checkpoint → merge)
/claude-harness:flow "Add user authentication with JWT tokens"
# Auto-compiles context, creates issue/branch, implements, checkpoints, merges

# Or batch-process all active features autonomously with TDD
/claude-harness:flow --autonomous

# Or step-by-step without auto-merge
/claude-harness:flow --no-merge "Add user authentication with JWT tokens"

The /flow command handles the entire lifecycle automatically - from context compilation to PR merge. It enforces test-driven development practices with a RED-GREEN-REFACTOR cycle and acceptance testing. Use --team for ATDD with Agent Teams (tester + implementer + reviewer). Use --autonomous to batch-process all active features. Use --no-merge for step-by-step control, --quick to skip planning for simple tasks.

Complete Workflow (5 Commands Total)

# 1. SETUP (one-time)
/claude-harness:setup                              # Initialize harness in project

# 2. START SESSION (or skip with /flow)
/claude-harness:start                              # Compile context, show status

# 3. DEVELOPMENT (unified /flow command)
/claude-harness:flow "Add dark mode"               # Complete lifecycle in one command
/claude-harness:flow --no-merge "Add feature"      # Stop at checkpoint (don't auto-merge)
/claude-harness:flow --autonomous                   # Batch-process all features
/claude-harness:flow --fix feature-001 "Token bug" # Bug fix linked to feature
/claude-harness:flow feature-001                   # Resume existing feature/fix

# 4. MANUAL CHECKPOINT (optional - /flow includes checkpoint)
/claude-harness:checkpoint               # Commit, push, create PR

# 5. RELEASE
/claude-harness:merge                    # Merge all PRs, close issues

What Happens Behind the Scenes

/setup           → One-time: Creates .claude-harness/ with memory architecture

/start           → Compiles working context from 4 memory layers
                   Shows status, syncs GitHub, displays learned rules

/flow            → UNIFIED END-TO-END WORKFLOW:
                   1. Auto-compiles context (replaces /start)
                   2. Creates feature (GitHub issue + branch)
                   3. Plans implementation (checks past failures)
                   4. Implements feature with TDD enforcement
                   5. Verifies: RED → GREEN → REFACTOR
                   6. Auto-checkpoints when all tests pass
                   7. Auto-merges when PR approved
                   Options: --no-merge, --quick, --autonomous,
                            --plan-only, --fix, --team
                   --autonomous: Batch loop through ALL features
                                 (context-isolated: each feature runs
                                  in a fresh subagent context window)
                   OPTIMIZATIONS: Parallel memory reads, cached GitHub parsing

/checkpoint      → Manual commit + push + PR (when not using /flow)
                   Auto-reflects on user corrections

/merge           → Merges PRs in dependency order
                   Closes linked issues
                   Cleans up branches

v3.0 Memory Architecture

.claude-harness/
├── memory/
│   ├── episodic/    → Rolling window of 50 recent decisions
│   ├── semantic/    → Persistent project architecture & patterns
│   ├── procedural/  → Append-only success/failure logs (never repeat mistakes)
│   └── learned/     → Rules from user corrections (self-improving)
├── features/        → Shared feature registry (active.json, archive.json)
└── sessions/        → Per-session state (gitignored, enables parallel work)
    └── {uuid}/      → Each Claude instance gets isolated loop/context state

Session Cleanup (Automatic)

Session directories are automatically cleaned up at session start. The SessionStart hook detects stale sessions by checking their PID:

• Active sessions (PID still running) are preserved
• Stale sessions (PID no longer running) are deleted
• Current session gets a fresh state directory

This ensures parallel Claude instances don't interfere with each other while preventing disk bloat from accumulated sessions.

Session Start Hook

When you start Claude Code in a harness-enabled project:

┌─────────────────────────────────────────────────────────────────┐
│                  CLAUDE HARNESS v8.0.0                            │
├─────────────────────────────────────────────────────────────────┤
│  P:2 WIP:1 Tests:1 Fixes:1 | Active: feature-001                │
│  Memory: 12 decisions | 3 failures | 8 successes                │
│  GitHub: owner/repo (cached)                                    │
├─────────────────────────────────────────────────────────────────┤
│  /claude-harness:setup          Initialize harness (one-time)   │
│  /claude-harness:start          Compile context + GitHub sync   │
│  /claude-harness:flow           Unified workflow (all flags)    │
│  /claude-harness:checkpoint     Commit + persist memory         │
│  /claude-harness:merge          Merge PRs + close issues        │
└─────────────────────────────────────────────────────────────────┘

Shows:

• Feature status: P (Pending) / WIP (Work-in-progress) / Tests (Needs tests)
• Memory stats: Decisions recorded, failures to avoid, successes to reuse
• Failure prevention: If failures exist, warns before implementing

Memory Architecture (OKF v0.1 Bundle)

Knowledge layers live as an OKF v0.1 bundle: one markdown concept file per entry with YAML frontmatter (required type field), an index.md listing per directory for progressive disclosure, and okf_version declared in the bundle-root index.md. Runtime state stays JSON.

.claude-harness/memory/           # OKF v0.1 bundle root
├── index.md                      # Declares okf_version: "0.1" + layer listing
├── log.md                        # Chronological history (newest first)
├── decisions/                    # type: Decision - rolling window (50 max)
├── failures/                     # type: Failure - append-only
├── successes/                    # type: Success - append-only
├── patterns/                     # type: Pattern - append-only
├── rules/                        # type: Rule - learned from user corrections
│   └── (each: index.md + one .md concept file per entry)
└── semantic/                     # Persistent project knowledge (stays JSON)
    ├── architecture.json
    ├── entities.json
    └── constraints.json

Conformance rules: schemas/okf-memory.md — check with python3 scripts/check-okf.py .claude-harness/memory. setup.sh migrates legacy JSON memory files to the bundle automatically (stamp-gated via memory/.okf-migrated).

Context Compilation

Each session compiles fresh working context by pulling relevant information from memory layers:

/claude-harness:start

→ Compile working context:
  • Pull recent decisions from episodic (last 10 relevant)
  • Pull project patterns from semantic
  • Pull failures to avoid from procedural
  • Pull successful approaches from procedural

→ Result: Clean, relevant context without accumulation

Failure Prevention System

Never repeat the same mistakes. When you try an approach that fails, it's recorded as a Failure concept file:

<!-- .claude-harness/memory/failures/fail-001-direct-dom-manipulation.md -->
---
type: Failure
id: fail-001
title: "Used direct DOM manipulation for state"
timestamp: 2025-01-20T10:30:00Z
feature: feature-001
---

# Used direct DOM manipulation for state

## Errors

- React hydration mismatch

## Root Cause

SSR incompatibility with direct DOM access

## Prevention

Use useState and useEffect instead

## Files

- src/components/Auth.tsx

Before each implementation attempt, /flow automatically checks past failures:

/claude-harness:flow feature-002

⚠️  SIMILAR APPROACH FAILED BEFORE

Failure: Used direct DOM manipulation for state
When: 2025-01-20
Files: src/components/Auth.tsx
Error: React hydration mismatch
Root Cause: SSR incompatibility with direct DOM access

Prevention Tip: Use useState and useEffect instead

✅ SUCCESSFUL ALTERNATIVE
Approach: React hooks with conditional rendering
Files: src/components/User.tsx
Why it worked: Proper SSR hydration

Test-Driven Features

The /flow command enforces test-driven development practices. Every feature follows a RED-GREEN-REFACTOR cycle with acceptance testing:

/claude-harness:flow "Add user authentication"

→ Creates feature entry with status: "pending"
→ Creates GitHub issue (if MCP configured)
→ Creates feature branch
→ Plans implementation (generates tests if needed)
→ Implements until all verification passes

Test Cases Schema

// .claude-harness/features/tests/feature-001.json
{
  "featureId": "feature-001",
  "generatedAt": "2025-01-20T10:30:00Z",
  "framework": "jest",
  "cases": [
    {
      "id": "test-001",
      "type": "unit",
      "description": "Should authenticate user with valid credentials",
      "file": "tests/auth/login.test.ts",
      "status": "pending",
      "code": "test('authenticates with valid credentials', async () => {...})"
    }
  ],
  "coverage": {
    "target": 80,
    "current": 0
  }
}

Two-Phase Pattern

The /flow command separates planning from implementation internally:

Phase 1: Plan (automatic in /flow)

/claude-harness:flow "Add authentication"

→ Planning Phase:
  → Analyzes requirements
  → Identifies files to create/modify
  → Runs impact analysis
  → Checks failure patterns
  → Generates tests (if needed)
  → Creates implementation plan

Output:

Implementation Plan for feature-001:

Steps:
1. Create auth service (src/services/auth.ts)
2. Add login API route (src/app/api/auth/login/route.ts)
3. Create login form component (src/components/LoginForm.tsx)
4. Add protected route wrapper (src/components/ProtectedRoute.tsx)

Impact Analysis:
- High: src/app/layout.tsx (15 dependents)
- Medium: src/lib/api.ts (8 dependents)

Failures to Avoid:
- Don't use direct DOM manipulation (failed in feature-003)

Successful Patterns to Use:
- React hooks with conditional rendering
- Server-side session validation

Phase 2: Implement (automatic in /flow)

→ Implementation Phase:
  → Loads loop state (resume if active)
  → Checks failure patterns before each attempt
  → Verifies tests are generated
  → Implements to pass tests
  → Runs ALL verification commands
  → Records success/failure to procedural memory

Use --quick to skip planning, or --plan-only to stop after planning.

Commands Reference (5 Total)

/flow Command Options

Key Features in /flow:

• TDD enforcement: RED→GREEN→REFACTOR cycle enforced by design
• Acceptance testing: Deterministic E2E tests run after refactoring
• Memory layers read in parallel (30-40% faster startup)
• GitHub repo parsed once and cached for entire flow
• Streaming memory updates after each verification attempt

TDD Phases (always-on):

RED      → Write failing tests
GREEN    → Write minimal code to pass tests
REFACTOR → Validate quality, fix issues

/prd-breakdown Command Options

PRD Breakdown Workflow:

Input         → Read PRD from inline, file, or GitHub
Analyze       → Analyzes requirements from product, architecture, and QA perspectives
Decompose     → Transform requirements into atomic features
  • Resolve dependencies (topological sort)
  • Assign priorities (MVP first)
  • Generate Gherkin acceptance criteria
Review        → Preview breakdown, select features to create
Create        → Add features to active.json with PRD metadata
Issues        → Create rich GitHub issues with cross-references (default)

GitHub Issues from PRD (Default)

The /prd-breakdown command automatically creates one GitHub issue per feature with rich detail:

/prd-breakdown @./prd.md                    # Manual review then create features + issues
/prd-breakdown @./prd.md --auto             # Fully automated
/prd-breakdown @./prd.md --no-issues        # Skip issue creation

Each issue includes:

• Full description with PRD source section and requirement reference
• Gherkin acceptance criteria (Given/When/Then) for ATDD compatibility
• Implementation context (priority, complexity, risk level, MVP flag)
• Related files and implementation hints from architecture analysis
• Verification commands (build, tests, lint, typecheck, acceptance)
• Bidirectional dependency links: "Depends on #X" and "Blocks #Y" with actual issue numbers

Issues are created in two passes:

1. Pass 1: Create all issues in dependency order (dependencies first)
2. Pass 2: Update issues with cross-references once all issue numbers are known

Labels: feature, prd-generated, claude-harness + conditional mvp and high-risk.

Use --no-issues to skip GitHub issue creation (features are still created in active.json).

Note: Requires GitHub CLI (gh) or GitHub MCP integration to be configured.

Directory Structure

.claude-harness/
├── memory/                       # OKF v0.1 bundle (concept .md files)
│   ├── index.md                  # Bundle root, declares okf_version
│   ├── log.md                    # Chronological history
│   ├── decisions/                # type: Decision - rolling window (50 max)
│   ├── failures/                 # type: Failure - append-only
│   ├── successes/                # type: Success - append-only
│   ├── patterns/                 # type: Pattern - learned patterns
│   ├── rules/                    # type: Rule - from user corrections
│   └── semantic/                 # Persistent knowledge (JSON)
│       ├── architecture.json     # Project structure
│       ├── entities.json         # Key components
│       └── constraints.json      # Rules & conventions
├── impact/
│   ├── dependency-graph.json     # File dependencies
│   └── change-log.json           # Recent changes
├── features/
│   ├── active.json               # Current features
│   ├── archive.json              # Completed features
│   └── tests/
│       └── {feature-id}.json     # Test cases per feature
├── agents/
│   └── context.json              # Orchestration state
├── prd/                          # PRD analysis and decomposition
│   ├── input.md                  # Original PRD document
│   ├── metadata.json             # PRD metadata and hash
│   ├── analysis.json             # Analysis results
│   ├── breakdown.json            # Decomposed features
│   └── analyst-prompts.json      # Reusable analysis prompts
├── loops/
│   └── state.json                # Agentic loop state
├── sessions/                     # Per-session state (gitignored)
│   └── {uuid}/                   # Isolated loop/context per session
├── config.json                   # Plugin configuration
└── claude-progress.json          # Session summary

Feature Schema (v3.0)

{
  "id": "feature-001",
  "name": "User Authentication",
  "description": "Add login/logout with session management",
  "priority": 1,
  "status": "pending|needs_tests|in_progress|passing|failing|blocked|escalated",
  "phase": "planning|test_generation|implementation|verification",
  "tests": {
    "generated": true,
    "file": "features/tests/feature-001.json",
    "passing": 0,
    "total": 15
  },
  "verification": {
    "build": "npm run build",
    "tests": "npm run test",
    "lint": "npm run lint",
    "typecheck": "npx tsc --noEmit",
    "custom": []
  },
  "attempts": 0,
  "maxAttempts": 15,
  "relatedFiles": [],
  "github": {
    "issueNumber": 42,
    "prNumber": null,
    "branch": "feature/feature-001"
  },
  "createdAt": "2025-01-20T10:30:00Z",
  "updatedAt": "2025-01-20T10:30:00Z"
}

Fix Schema (v3.1)

Bug fixes are linked to their original features:

{
  "id": "fix-feature-001-001",
  "name": "Token expiry not handled",
  "description": "User gets stuck on expired token",
  "linkedTo": {
    "featureId": "feature-001",
    "featureName": "User Authentication",
    "issueNumber": 42
  },
  "type": "bugfix",
  "status": "pending|in_progress|passing|escalated",
  "verification": {
    "build": "npm run build",
    "tests": "npm run test",
    "lint": "npm run lint",
    "typecheck": "npx tsc --noEmit",
    "custom": [],
    "inherited": true
  },
  "attempts": 0,
  "maxAttempts": 15,
  "relatedFiles": [],
  "github": {
    "issueNumber": 55,
    "prNumber": null,
    "branch": "fix/feature-001-token-expiry"
  },
  "createdAt": "2025-01-20T11:00:00Z",
  "updatedAt": "2025-01-20T11:00:00Z"
}

Key differences from features:

• linkedTo - References the original feature
• type: "bugfix" - Distinguishes from features
• verification.inherited - Indicates commands came from original feature
• Branch format: fix/{feature-id}-{slug} instead of feature/
• Commits use fix: prefix (triggers PATCH version bump)

Agentic Loops

The /flow command runs autonomous implementation loops that continue until ALL tests pass:

/claude-harness:flow feature-001

┌─────────────────────────────────────────────────────────────────┐
│  AGENTIC LOOP: User Authentication                              │
├─────────────────────────────────────────────────────────────────┤
│  Attempt 3/10                                                   │
│  ├─ Failure Prevention: Checked 3 past failures                 │
│  ├─ Implementation: Using React hooks pattern                   │
│  ├─ Verification:                                               │
│  │   ├─ Build:     PASSED                                       │
│  │   ├─ Tests:     PASSED (15/15)                               │
│  │   ├─ Lint:      PASSED                                       │
│  │   └─ Typecheck: PASSED                                       │
│  └─ Result: SUCCESS                                             │
├─────────────────────────────────────────────────────────────────┤
│  Feature complete! Success concept saved to memory/successes/   │
└─────────────────────────────────────────────────────────────────┘

On failure:

• Records the approach as a Failure concept in memory/failures/ with root cause analysis
• Analyzes errors and tries different approach
• Consults Success concepts in memory/successes/ for working patterns
• Up to 10 attempts before escalation

Impact Analysis

Track how changes affect other components:

// .claude-harness/impact/dependency-graph.json
{
  "nodes": {
    "src/lib/auth.ts": {
      "imports": ["src/lib/api.ts", "src/types/user.ts"],
      "importedBy": ["src/app/api/auth/login/route.ts", "src/components/LoginForm.tsx"],
      "tests": ["tests/lib/auth.test.ts"],
      "type": "module"
    }
  },
  "hotspots": ["src/lib/api.ts"],
  "criticalPaths": ["src/app/layout.tsx"]
}

When modifying files:

• Identifies dependent files
• Warns about high-impact changes
• Suggests running related tests

Migration from v2.x

# In your project with existing harness
./setup.sh --migrate

# Creates backup: .claude-harness-backup-{timestamp}/
# Migrates:
#   feature-list.json → features/active.json
#   agent-memory.json → memory/procedural/
#   working-context.json → memory/working/context.json
#   loop-state.json → loops/state.json

Or let it auto-migrate on first run of a harness command.

GitHub MCP Integration

# Setup
claude mcp add github -s user

# Workflow (all in one command!)
/claude-harness:flow "Add dark mode"      # Creates issue + branch, implements, commits, creates PR

# Or step by step
/claude-harness:flow --plan-only "Add dark mode"  # Create + plan only
/claude-harness:flow feature-001                  # Resume and implement
/claude-harness:checkpoint                        # Manual commit + PR if needed
/claude-harness:merge                             # Merge all PRs, auto-version

Configuration

// .claude-harness/config.json
{
  "version": 3,
  "verification": {
    "build": "npm run build",
    "tests": "npm run test",
    "lint": "npm run lint",
    "typecheck": "npx tsc --noEmit"
  },
  "memory": {
    "episodicMaxEntries": 50,
    "contextCompilationEnabled": true
  },
  "failurePrevention": {
    "enabled": true,
    "similarityThreshold": 0.7
  },
  "impactAnalysis": {
    "enabled": true,
    "warnOnHighImpact": true
  },
  "testDriven": {
    "enabled": true,
    "generateTestsBeforeImplementation": true
  }
}

Updating

claude plugin update claude-harness@claude-harness

Or from inside a Claude Code session:

/plugin update claude-harness@claude-harness

Note: The full claude-harness@claude-harness identifier is required. claude plugin update claude-harness (without @claude-harness) will fail with "not found".

Updates are tracked by git commit SHA (same mechanism as official Anthropic plugins), so any change pushed to the marketplace repo is automatically detectable.

Troubleshooting

Plugin Update Not Detected

Force-refresh the marketplace cache, then update:

claude plugin marketplace update claude-harness
claude plugin update claude-harness@claude-harness

Clean Reinstall

If the plugin is in a broken state:

claude plugin uninstall claude-harness@claude-harness
claude plugin marketplace update claude-harness
claude plugin install claude-harness@claude-harness

Then restart Claude Code and run /claude-harness:setup.

Changelog

2026-07-17 - Memory layers migrated to OKF v0.1 bundle format (feature-004)

• Memory knowledge layers are now an OKF v0.1 bundle: decisions.json, failures.json, successes.json, patterns.json, and rules.json are replaced by one markdown concept file per entry with YAML frontmatter (required type: Decision/Failure/Success/Pattern/Rule) under memory/decisions|failures|successes|patterns|rules/. Each directory has an index.md listing (progressive disclosure); the bundle-root index.md declares okf_version: "0.1"; log.md records bundle history. Runtime state (features, sessions, agents, config, progress) and semantic memory stay JSON.
• Stamp-gated migration in setup.sh: legacy JSON memory files are converted to concept files automatically (idempotent, gated by memory/.okf-migrated); fresh projects bootstrap an empty OKF skeleton with no legacy JSON.
• New conformance check: scripts/check-okf.py validates frontmatter/type on every non-reserved .md and the okf_version declaration; conformance rules documented in schemas/okf-memory.md (replaces schemas/memory-entries.schema.json).
• Consumers updated: scripts/compile-briefing.py (with --write to emit session-briefing.md) and the SubagentStart hook read the bundle (legacy-JSON fallback kept for un-migrated projects); flow/checkpoint/start skill instructions now write concept files and maintain index.md listings.

2026-07-09 - Fix hook commands failing with unexpanded ${CLAUDE_PLUGIN_ROOT}

• Fix: PreToolUse:Bash hook error ... ${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd: not found on every tool call: hooks.json wrapped the hook path in single quotes, which blocks shell variable expansion. Current Claude Code provides CLAUDE_PLUGIN_ROOT as an environment variable expanded by /bin/sh (rather than textually substituting it), so the literal unexpanded string reached the shell and every hook failed. All 8 hook commands now use double quotes, which work under both expansion regimes.

2026-07-02 - Modernize for current Claude Code APIs (speed + correctness)

• Fix: session liveness detection was always false: The SessionStart hook recorded its own (immediately-dead) PID, so every other session was treated as stale — concurrent sessions deleted each other's live state and produced false interrupt markers. Sessions are now keyed by Claude Code's native session_id (read from hook stdin), and staleness is judged by transcript-file mtime (24h). Parallel sessions actually work now.
• Fix: interrupt detection moved from Stop to SessionEnd: The Stop hook fires after every assistant turn, writing bogus "interrupted" recovery markers (and killing active team tmux sessions) mid-workflow. A new SessionEnd hook now handles interrupt rescue, orphaned-team cleanup, and session-dir removal at actual session termination. The Stop hook is gone.
• Fix: safety hook no longer fails open: PreToolUse parsed Bash commands with a single-line grep, so multi-line commands bypassed every deny rule. Parsing now uses jq/python3 (multi-line safe). Static deny rules are additionally written to permissions.deny in settings.local.json — they block instantly without spawning a hook process.
• Fix: push-to-main / checkout-main rules are now loop-scoped: The unconditional rules contradicted the flow's own documented "commit harness state to main" step. Both rules now apply only while a feature loop is in progress.
• Speed: setup.sh is stamp-gated: Previously ran in full (project detection, migrations, gitignore reconciliation) on every session start; now only when the plugin SHA changes (.claude-harness/.setup-stamp).
• Speed: lean SessionStart context: The hook now injects a ~15-line summary plus a pointer to session-briefing.md (read on demand) instead of inlining the full briefing, memory stats, and banners into every session.
• Speed: team gates deduplicated + cached: TeammateIdle runs only fast checks (uncommitted work, lint, typecheck); TaskCompleted owns the full suite and caches results per working-tree hash (.claude-harness/.verify-cache), so unchanged trees skip re-verification.
• New: harness-implementer plugin agent: Feature lifecycles are delegated to a dedicated subagent (agents/harness-implementer.md) instead of general-purpose + a 3,000-token inline prompt. Delegation prompts now carry only data. SubagentStart context injection is matcher-scoped to implementer agents.
• New: file-based result contract: Subagents write result-{feature-id}.json instead of relying on parsing a RESULT: text block (kept as fallback).
• New: fresh-context retry policy: 4 attempts per delegation, then escalate; the orchestrator re-delegates a fresh subagent seeded with the failure summary (max 3 delegations = 12 attempts). Replaces 15 attempts grinding inside one degraded context, and replaces the stale Opus 4.6 effort-escalation table.
• GitHub via gh CLI everywhere: All skills now use gh issue/pr commands; the GitHub MCP server is no longer required (removes ~35 tool schemas from context). Branches are created locally (git checkout -b + push -u) instead of via API round-trips.
• Skills modernized: disable-model-invocation: true on merge/setup/checkpoint/prd-breakdown (explicit-invocation commands), argument-hint + allowed-tools added, unsupported compatibility field removed, "Task tool" renamed to Agent tool, ${CLAUDE_SESSION_ID} used directly, /start compiles its memory snapshot via dynamic ! injection (scripts/compile-briefing.py) instead of five model-driven file reads.
• Agent Teams updated: Removed the stale CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env-var gate (teams are built into current Claude Code; setup.sh removes the var from existing settings). tmux cleanup kept as legacy best-effort.
• Plugin manifest enriched: displayName, homepage, repository, license, keywords (still SHA-versioned by design). CI now runs claude plugin validate before marketplace sync.
• Doc drift fixed: loop-state schema v8→v9 in setup skill, 5→6 task references, checkpoint no longer writes the redundant working-context.json, CLAUDE.md startup protocol no longer duplicates hook-injected context.

2026-02-28 - Auto-inject session briefing + context isolation

• Auto-inject working context at session start: The SessionStart hook now automatically injects project context (active features, recent decisions, failures to avoid, learned rules) without requiring a manual /claude-harness:start call. Uses a two-layer approach: (1) reads persistent session-briefing.md compiled at checkpoint time, (2) falls back to cold-start python3 extraction from memory files when no briefing exists. Inspired by patterns from claude-mem, OpenClaw, memsearch, and ContextStream plugins.
• Context isolation for standard flow: /flow now delegates Phases 3-7 (planning through merge) to an isolated general-purpose subagent via the Task tool. After feature creation, the orchestrator compiles a structured prompt with all necessary context and spawns a fresh subagent. The main context window stays clean for subsequent features or user interaction. Exceptions: --plan-only (needs interactive review) and --autonomous (already has its own delegation loop).
• Session briefing generation at checkpoint: New Phase 5.2.5 in /flow and Phase 1.9.5 in /checkpoint compile session-briefing.md with current feature status, recent decisions, patterns, and next steps. This briefing is auto-loaded by the SessionStart hook on the next session.
• Fix: grep -c double output: Fixed grep -c ... || echo "0" producing 0\n0 in the SessionStart hook. grep -c outputs "0" with exit code 1 on zero matches, triggering the || branch to also output "0". Replaced with grep -c ...; true.
• Fix: Marketplace sync wrong SHA: The GitHub Actions workflow ran git rev-parse --short HEAD inside the marketplace directory, embedding the marketplace's own SHA in commit messages instead of the source repo's SHA. Fixed by capturing SOURCE_SHA before cd marketplace.
• Fix: Marketplace rsync nesting: The rsync step copied from ./ which included the marketplace/ checkout directory, causing recursive nesting in synced plugin files. Added --exclude='marketplace/' to the rsync command.
• Known issue documented: claude plugin update has known bugs with third-party marketplaces — fetch without merge (#29071), cache never refreshed (#17361), lastUpdated never updated (#26744). Workaround: manual git pull in ~/.claude/plugins/marketplaces/claude-harness/ followed by cache rebuild.

2026-02-27 - SHA-based update detection

• Dropped semver from plugin.json and marketplace.json: Updates are now tracked by git commit SHA, matching the pattern used by official Anthropic plugins. This eliminates stale-cache version detection issues — any push to the marketplace repo is automatically detectable by claude plugin update.
• Broadened GitHub Actions sync trigger: Workflow now triggers on changes to any plugin file (commands, hooks, schemas, setup.sh, etc.), not just plugin.json version bumps.
• Simplified update flow: Users now only need claude plugin update claude-harness@claude-harness — no separate marketplace refresh step required.

v10.2.0 (2026-02-27) - Seamless native plugin updates

• Monorepo marketplace: Switched from git-URL-based plugin source to embedded local plugin in the marketplace repo. Claude Code now copies plugin files flat instead of git-cloning, eliminating the ENAMETOOLONG recursive cache nesting bug (#19742).
• Automated marketplace sync: Added GitHub Action (.github/workflows/sync-marketplace.yml) that automatically syncs plugin files to the marketplace repo on every version bump. No more manual marketplace updates.
• Removed tracked runtime files: Untracked .claude-harness/config.json and .claude-harness/init.sh from git (created by setup.sh at runtime). Plugin cache no longer contains .claude-harness/ directory.
• Removed ENAMETOOLONG workaround: The session-start recursion cleanup is no longer needed with the monorepo approach.
• Simplified update messaging: Updates now direct users to the native /plugin update claude-harness command.
• Cleaned up .gitignore: Replaced 12 individual exclusions with a single blanket .claude-harness/ ignore.
• Transition note: Existing users with corrupted caches need a one-time rm -rf ~/.claude/plugins/cache/claude-harness/ && claude plugin install claude-harness@claude-harness. All future updates work seamlessly.

v10.1.0 (2026-02-27) - Reduce plugin footprint and improve update reliability

• Reduced plugin footprint by 50%: Removed 31 project-specific state files from git tracking (.claude-harness/memory/, features/, plans/, impact/, agents/, prd/, tests/, RELEASES/). Plugin now ships 31 tracked files, down from 62. Reduces git clone size and avoids ENAMETOOLONG edge cases during claude plugin update.
• Stale cache detection: Session-start hook now checks GitHub for the latest version (cached 24h, 3s timeout). Displays update banner when the plugin is outdated.
• Git cleanup: Pruned 8 stale remote branches and 20 old tags (v1.x-v3.x) to reduce clone object count.
• Updated .gitignore: Added comprehensive exclusion patterns for project-specific state files that should never be part of the plugin package.

v10.0.4 (2026-02-27) - Harden hook JSON parsing and error handling

• Fix: PreToolUse:Bash hook errors: Replaced fragile grep -o "[^"]*" JSON parsing with jq in pre-tool-use, permission-request, and pre-compact hooks. The grep patterns broke on commands containing escaped quotes (e.g., git commit -m "feat: something"), causing hook errors in Claude Code.
• Fix: Pre-compact invalid JSON: The pre-compact hook generated invalid JSON ("loopState": ,) when state variables were empty. Now defaults to null and uses jq for safe JSON construction.
• Safety net: Added trap 'exit 0' ERR to all three hooks, ensuring they never exit non-zero (which triggers "hook error" in Claude Code). Hooks should always allow tool calls on unexpected errors rather than blocking.
• Consistency: Replaced all echo "$VAR" with printf '%s' "$VAR" to avoid escape sequence interpretation issues.

v10.0.3 (2026-02-27) - Auto-run setup on session start

• Auto-migrations on session start: setup.sh now runs automatically from the SessionStart hook when .claude-harness/ already exists. This applies migrations, creates missing state files, and cleans up legacy artifacts transparently — no need to re-run /claude-harness:setup after plugin updates. First-time setup still requires explicit /claude-harness:setup.

v10.0.2 (2026-02-27) - Plugin Cache Recursion Workaround

• Fix: ENAMETOOLONG on plugin update: Added self-healing cleanup to session-start hook that detects and removes recursive directory nesting in Claude Code's plugin cache. Works around anthropics/claude-code#19742 where the cache system infinitely nests the plugin inside its own cache directory until the filesystem path limit is exceeded.

v10.0.1 (2026-02-27) - Autonomous Archival & Branch Cleanup Fix

• Fix: Features not archived in autonomous mode: Added ARCHIVE_FILE path variable to autonomous wrapper (Phase A.1), explicit archival instructions to the subagent prompt (Phase A.4.0 step 9), and detailed step-by-step archival procedure with verification in the orchestrator (Phase A.5 step 22)
• Fix: Stale local branches after merge: Added explicit git branch -d {branch} to Phase 6 (Auto-Merge) and to the autonomous orchestrator's post-merge cleanup (Phase A.5). Local feature branches are now deleted after successful squash merge.

v10.0.0 (2026-02-26) - Separate Marketplace & Native Plugin Updates

• BREAKING: Marketplace moved to separate repo (panayiotism/claude-harness-marketplace). Existing users must re-register: claude plugin marketplace add panayiotism/claude-harness-marketplace
• Repo restructured: Plugin files moved from claude-harness/ subdirectory to repo root. Single .claude-plugin/plugin.json (eliminated dual plugin.json)
• Native updates: Removed all custom update infrastructure from session-start hook (~100 lines). Claude Code's native version-keyed caching now handles updates via URL-based marketplace source
• Cross-platform: Added run-hook.cmd polyglot wrapper (works as both Windows .cmd and Unix shell). Hook scripts renamed to extensionless (e.g., session-start not session-start.sh) to avoid Claude Code's Windows .sh auto-detection
• Removed: fix-plugin-cache.sh (no longer needed), .plugin-version stamp file (no longer needed), custom GitHub API version checking, auto-update tarball downloader
• Simplified migrations: Artifact-based migration detection (checks if legacy files exist) replaces version-number-based detection

v9.3.0 (2026-02-23) - ATDD Always-On

• ATDD always-on: Acceptance Test-Driven Development is now mandatory in all modes (standard, autonomous, team). Acceptance tests are always written first from Gherkin criteria (RED), then implementation makes them pass (GREEN), then refactor.
• Acceptance criteria always generated: Gherkin acceptance criteria are now generated for every feature (removed atdd.requireAcceptanceCriteria config gate).
• --team scope narrowed: The --team flag now only controls whether an Agent Team (tester/implementer/reviewer) is spawned — it no longer controls whether ATDD is followed. ATDD order is enforced regardless.

v9.2.0 (2026-02-23) - Rich GitHub Issues from PRD

• Default issue creation: /prd-breakdown now creates GitHub issues alongside features by default (no flag needed). Use --no-issues to skip.
• Rich issue bodies: Each issue includes full description, PRD source reference, Gherkin acceptance criteria, implementation context (priority/complexity/risk/MVP), related files, implementation hints, and verification commands.
• Bidirectional dependency linking: Two-pass issue creation — Pass 1 creates all issues in dependency order, Pass 2 updates them with actual #issueNumber cross-references ("Depends on #X" / "Blocks #Y").
• Enhanced labels: Issues labeled with feature, prd-generated, claude-harness + conditional mvp and high-risk labels.
• Removed --create-issues flag: Replaced by default-on behavior. --no-issues is the new opt-out flag.

v9.1.0 (2026-02-22) - Autonomous Context Isolation

• Context isolation: Autonomous mode (--autonomous) now delegates each feature to a fresh subagent via the Task tool. Each feature runs in its own context window — zero accumulated context between features.
• Subagent-per-feature: The orchestrator loop stays lean (feature selection, conflict detection, result processing). All feature work (planning, implementation, verification, checkpoint, merge) runs in an isolated subagent.
• Memory continuity: Subagents return structured memory updates (decisions, failures, successes, patterns) which the orchestrator persists between features. Feature B benefits from Feature A's learnings without context pollution.
• Team containment: When --team --autonomous is used, Agent Team lifecycle is fully contained within each subagent — no zombie agents leak to the orchestrator.
• Schema update: autonomous-state schema v3 to v4 (adds contextIsolation and featureResults fields)
• Checkpoint Phase 9 now notes that autonomous mode handles context isolation automatically (no manual /clear needed)

v9.0.0 (2026-02-18) - Agent Teams with ATDD

• Agent Teams: Re-introduces Agent Teams with opt-in --team flag (previously removed in v8.0.0). Teams are no longer mandatory — direct implementation remains the default.
• ATDD workflow: Acceptance Test-Driven Development with Gherkin acceptance criteria (Given/When/Then). Tester writes acceptance tests FIRST (RED), implementer makes them pass (GREEN), reviewer validates.
• 3 new hooks (6 to 9 total): TeammateIdle (quality gate), TaskCompleted (ATDD verification gate), SubagentStart (context injection)
• Structured Gherkin: acceptanceCriteria field on features uses { scenario, given, when, then } objects — machine-readable for the tester teammate, human-readable in GitHub issues
• Team task chain: 6-task ATDD dependency chain (write tests -> plan -> implement -> review -> feedback -> verify)
• Config sections: agentTeams (enabled/roles/planApproval) and atdd (criteriaFormat/acceptanceTestFirst) in config.json
• Schema changes: loop-state v8 to v9 (adds team field), new agents-context schema v2 (adds teamState)
• BREAKING: Loop-state schema version 8 to 9. Existing loop-state files need version bump.
• Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var (auto-injected by setup.sh when agentTeams.enabled is true)

v8.4.0 (2026-02-17) - Schema standardization

• Added claude-harness/schemas/ directory with JSON Schema files for key state files (loop-state, active-features, context, autonomous-state, memory-entries)
• Fixed loop-state version drift: was referenced as v3 in setup.md, v4 in checkpoint.md, v8 in flow.md — now all reference canonical schema
• Removed hardcoded version comments from hook .sh files (version lives only in plugin.json)
• Added schema versioning convention to CLAUDE.md: "version" in JSON files = data schema version, not plugin version
• Updated procedural memory patterns to reflect simplified version bump process
• Command docs now reference schema files instead of embedding inline JSON examples

v8.1.0 (2026-02-15) - Auto-update stale plugin cache

• session-start.sh auto-downloads latest plugin from GitHub when stale cache detected
• Updates cache directory and installed_plugins.json registry automatically
• Works around Claude Code plugin update bug (#19197, #14061, #13799, #15642)
• Added fix-plugin-cache.sh curl-able script for users stuck on older versions

v8.0.0 (2026-02-15) - Remove Agent Teams

• BREAKING: Remove Agent Teams: Direct implementation model replaces 3-specialist team orchestration. Removed SubagentStart, TeammateIdle, TaskCompleted hooks. 9→6 hook registrations. No longer requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS.

v7.0.0 (2026-02-14) - Restructure repo for marketplace compatibility

• BREAKING: Moved plugin files (commands/, hooks/, setup.sh) into claude-harness/ subdirectory
• Fixed: Plugin install fails with "not found in marketplace" and GitHub self-reference causes infinite recursion
• Root cause: Claude Code requires plugins in subdirectories within a marketplace repo. Having marketplace.json and plugin.json in the same .claude-plugin/ at root is unsupported — every working marketplace (Anthropic, gmickel, cbrake, EveryInc) uses source: "./subdirectory"
• Marketplace source now "./claude-harness" pointing to the plugin subdirectory
• Existing users: run claude plugin update claude-harness to get the new structure

v6.0.6 (2026-02-14) - Fix installation instructions

• Fixed: README Quick Start used invalid github:owner/repo syntax for claude plugin install
• Root cause: There is no github: prefix in Claude Code's plugin install command. Plugins must be installed via the marketplace workflow (add marketplace first, then install from it)
• Replaced incorrect "Option B: Direct GitHub install" with correct two-step marketplace commands
• Added terminal CLI equivalent (claude plugin marketplace add / claude plugin install)

v6.0.5 (2026-02-14) - Remove stale cache detection

• Removed: Custom stale cache detection system from session-start.sh
  • Removed version_lt(), check_latest_version(), GitHub API/curl version fetch, 24h TTL cache
  • Removed "STALE CACHE" user warning and "STALE PLUGIN CACHE DETECTED" AI context blocker
• Rationale: No other Claude Code plugin implements custom update detection. Claude Code's native claude plugin update is sufficient.
• Kept: Local plugin-vs-project version mismatch detection (.plugin-version comparison) for /setup migration prompts

v6.0.4 (2026-02-14) - Fix stale SessionEnd hook in settings.local.json

• Fixed: SessionEnd hook [session-end.sh] failed: not found error on session exit
• Root cause: settings.local.json retained a stale SessionEnd hook from pre-v6.0.0, but the hook script was removed during the v6.0.0 consolidation (12 → 6 hooks)
• setup.sh skips existing settings.local.json files, so the stale entry was never cleaned up
• Added cleanup step to setup.sh that strips SessionEnd from existing settings.local.json files

v6.0.3 (2026-02-14) - Fix false-positive stale cache warning

• Fixed: Stale cache warning showing even after plugin update (installed version newer than cached "latest")
• Root cause: version comparison used string != instead of semver less-than — any version difference triggered the warning, including when installed > latest
• Added version_lt() using sort -V for proper semver comparison
• Auto-clears stale .version-check cache when installed version is already up-to-date

v6.0.0 (2026-02-14) - Official Plugin Alignment + Hook Consolidation

Major release: Aligns plugin with official Claude Code plugin guidelines. Commands served from plugin cache, redundant hooks removed, setup.sh simplified.

Plugin Alignment

• Commands served from plugin cache (removed command-copying from setup.sh)
• Deprecated --force-commands flag (use claude plugin update instead)
• setup.sh now cleans up legacy command copies from target projects' .claude/commands/

Hook Consolidation (12 → 6 registrations)

• Removed SessionEnd hook (stale session cleanup already handled by SessionStart)
• Removed UserPromptSubmit hook (active loop context already injected by SessionStart)
• Removed PostToolUse hook (async test-on-edit duplicated verification gates)
• Removed PostToolUseFailure hook (low-value failure recording; gates handled elsewhere)
• Removed SubagentStart hook (no longer needed without team orchestration)
• Removed TeammateIdle hook (no longer needed without team orchestration)
• Removed TaskCompleted hook (no longer needed without team orchestration)
• Removed dead session-start-compact.sh script (not registered in hooks.json)
• Remaining hooks, 6 registrations: SessionStart, PreCompact, Stop, PreToolUse (Bash + Edit|Write), PermissionRequest

Upgrade

claude plugin update claude-harness
/claude-harness:setup

v7.0.0 (2026-02-12) - Hook Compliance, Performance & Trim

Major release: 7 hook compliance fixes, performance optimization, and context trimming across hooks and commands.

Hook Compliance (feature-019)

• SessionStart: Added matcher: "fresh" to prevent double-fire on compaction
• PreCompact: Added hookEventName to hookSpecificOutput
• Stop: Replaced plain text echo with structured output
• PreCompact: Replaced emoji with text in user messages

Context Trimming

• flow.md (feature-020): 1434 → 514 lines (64% reduction). Deduplicated effort tables, loop-state schema, eliminated redundant ASCII boxes
• session-start.sh (feature-021): 633 → 377 lines (40% reduction). Added reusable build_box() function, removed Opus 4.6 capabilities section, condensed workflow listing

Metadata

• All hook version headers updated to v7.0.0
• Plugin version bumped to 7.0.0

v6.5.1 (2026-02-10) - Performance Hotfix

CRITICAL FIX: Resolves 40+ minute agent hang issue in v6.5.0

Fixes

• Performance: Add 10-second timeout wrappers to all eval commands in hooks
  • Prevents indefinite blocking when test suites or verification commands take too long
  • Hook timeouts in hooks.json were not enforced on the actual eval commands
• Performance: Skip TDD validation for non-verification tasks
  • Only verify/checkpoint/review/accept tasks run TDD validation gate
  • Reduces redundant verification runs

Impact

• Hooks now complete in < 10 seconds (was 10+ minutes with slow test suites)
• Eliminates 40+ minute hangs reported in v6.5.0

Upgrade from v6.5.0

This is a critical hotfix. Users experiencing agent hangs should upgrade immediately:

/plugin update claude-harness

v4.1.0 Release Notes: See RELEASES/v4.1.0.md for full details on auto-issue creation and GitHub integration.
v3.0.0 Release Notes: See RELEASE-NOTES-v3.0.0.md for full details with architecture diagrams.

Safe Permissions (Avoiding --dangerously-skip-permissions)

The harness includes a comprehensive permission configuration that allows Claude Code to run without the dangerous --dangerously-skip-permissions flag while maintaining full functionality.

Configuration Location

.claude/settings.local.json    # Personal settings (gitignored)
.claude/settings.json          # Team-shared settings (committed)

Permission Model

Safe Operations (Auto-Allowed)

{
  "allow": [
    "Bash(git status:*)", "Bash(git add:*)", "Bash(git commit:*)",
    "Bash(git checkout:*)", "Bash(git branch:*)", "Bash(git log:*)",
    "Bash(npm run:*)", "Bash(npx tsc:*)", "Bash(npx jest:*)",
    "Bash(mkdir:*)", "Bash(ls:*)", "Bash(cat:*)", "Bash(grep:*)",
    "Bash(./hooks/*)", "Bash(./.claude-harness/*)"
  ]
}

User Confirmation Required

{
  "ask": [
    "Bash(rm:*)",           // All file deletion
    "Bash(rmdir:*)",        // All directory deletion
    "Bash(git push:*)",     // Remote operations
    "Bash(git reset:*)",    // Destructive git
    "Bash(npm install:*)",  // Package installation
    "Bash(chmod:*)"         // Permission changes
  ]
}

Dangerous Operations (Always Blocked)

{
  "deny": [
    // Network (data exfiltration risk)
    "Bash(curl:*)", "Bash(wget:*)", "Bash(nc:*)", "Bash(ssh:*)",

    // Privilege escalation
    "Bash(sudo:*)", "Bash(su:*)", "Bash(doas:*)",

    // Destructive filesystem operations
    "Bash(rm -rf /)", "Bash(rm -rf ~)", "Bash(rm -rf /home:*)",
    "Bash(rm -rf /etc:*)", "Bash(rm -rf /usr:*)", "Bash(rm -rf /var:*)",

    // Low-level system operations
    "Bash(dd:*)", "Bash(mkfs:*)", "Bash(fdisk:*)",
    "Bash(systemctl:*)", "Bash(shutdown:*)", "Bash(reboot:*)",

    // User/group management
    "Bash(useradd:*)", "Bash(userdel:*)", "Bash(passwd:*)",

    // Code execution (potential RCE)
    "Bash(python -c:*)", "Bash(node -e:*)", "Bash(eval:*)",

    // Secrets protection
    "Read(.env)", "Read(.env.*)", "Read(**/credentials*)", "Read(**/*.pem)"
  ]
}

How Precedence Works

1. Deny rules checked first - If matched, command is blocked
2. Ask rules checked second - If matched, user is prompted
3. Allow rules checked last - If matched, command runs

This means dangerous patterns like rm -rf /home/* are blocked even though rm:* is in the ask list.

Using the Configuration

# Run Claude Code normally (no dangerous flag needed)
cd your-project
claude

# The harness commands work with auto-approved safe operations
/claude-harness:start       # Uses git status, cat, grep
/claude-harness:checkpoint  # Uses git add, commit (push prompts)
/claude-harness:flow        # Uses npm run, npx tsc

Extending for Your Project

Add project-specific safe commands to .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(docker compose up:*)",
      "Bash(make build:*)",
      "Bash(cargo test:*)"
    ]
  }
}

Key Principles

1. Never Trust Self-Assessment - All verification is mandatory via commands
2. Learn From Mistakes - Failure prevention system records and warns
3. Test First - Generate tests before implementation
4. Computed Context - Fresh, relevant context each session (no accumulation)
5. Memory Persistence - Knowledge survives context windows
6. Single Feature Focus - One feature at a time prevents scope creep

Sources

• Anthropic: Effective Harnesses for Long-Running Agents
• Context-Engine - Memory architecture inspiration
• Agent-Foreman - Task management patterns
• Autonomous-Coding - Test-driven approach