HCF (Halt and Catch Fire)

Autonomous development plugin for Claude Code. Define requirements with a PM, then let parallel workers implement everything using TDD.

Table of Contents

• Overview
• Getting Started
  • Installation
  • Quick Start
• How It Works
  • Four Phases
  • Pipeline
  • Dependency Graph
  • Parallel Execution
  • TDD Methodology
• Reference
  • Files Created
  • Task Format
  • Skills
  • Outputs
• Architecture
• Advanced Configuration
  • Plans Directory
• Design Principles
• Development
  • Local Testing
  • Testing Workflow
  • Debugging
• Changelog
• Contributing
• License

Overview

HCF separates planning (human-in-the-loop) from execution (fully autonomous):

Planning → Human + AI collaborate on requirements
Execution → Parallel TDD workers implement autonomously

Getting Started

Installation

Add the marketplace, install, then reload:

/plugin marketplace add markshust/hcf
/plugin install hcf@hcf
/reload-plugins

Quick Start

1. Setup Project (one-time)

/project-setup

Interactively configures your project:

• Auto-detects tech stack (Laravel, React, etc.)
• Asks about testing, linting, architecture
• Creates .claude/ config directory

2. Plan a Feature

Just describe what you want:

"Help me implement user authentication with JWT"

The plan-create skill activates automatically to:

• Discover & brainstorm — explore the codebase and enumerate scope/assumption permutations a senior engineer would catch
• Create a feature/{plan-name} branch for the work
• Ask grounded clarifying questions categorized as must-answer vs will-default-if-silent
• Break down into tasks with dependencies
• Write requirements as test descriptions
• Create .claude/plans/user-auth/ with task files (or your configured plans directory)
• Run post-plan pipeline agents (devil's advocate by default) to find gaps before execution

After planning completes, you'll be asked:

Ready to begin autonomous implementation?

1. Yes, start now
2. No, I'll run it later

3. Execute Autonomously

If you chose "later" or want to re-run, say:

"Run the user-auth plan" or "Execute the plan"

The plan-orchestrate skill auto-triggers. It verifies you're on the correct feature/{plan-name} branch before starting.

Session persistence is native to Claude Code — no plugin required. Auto-compaction handles context limits, and all run state (task statuses, requirement checkboxes, retry counts) lives in the plan files, so an interrupted run resumes by re-running the plan. For large plans, you can optionally set a goal first so execution completes unattended:

/goal the user-auth plan run reached a terminal state: plan-orchestrate output ALL_TASKS_COMPLETE or TASKS_BLOCKED

After completion, you'll be prompted to push the branch and create a PR (never done without your permission).

How It Works

Four Phases

| Phase | Type | What Happens | |-------|------|--------------| | Setup | One-time | Configure project for autonomous dev | | Planning | Interactive | Discover codebase, brainstorm scope, then define tasks with human guidance | | Post-Plan Hooks | Automated | Agents enrolled at the post-plan hook review the plan | | Execution | Autonomous | Parallel TDD implementation, with agents enrolled at the implementation hooks |

Pipeline

The pipeline controls which agents run at fixed points in the plan/implementation flow. HCF uses convention over configuration: there is no central registry — each agent enrolls itself by declaring a phase in its own YAML frontmatter. If an agent declares a phase, it runs at that hook; if it has no phase, it never runs via a hook.

Hook points:

There are exactly 8 hook points where enrolled agents can run:

| Hook | Fires | |------|-------| | pre-plan | Before planning Discovery begins | | post-plan | After the plan is built and validated, before user review | | pre-implementation | Before the first implementation batch | | pre-batch | Before each batch of TDD workers is spawned | | post-batch | After each batch of TDD workers completes | | post-implementation | After all tasks complete | | pre-commit | After the full test suite passes, before the commit | | post-commit | After the commit, before the push/PR prompt |

By default, only devils-advocate is enrolled (at post-plan). See HOOKS.md for the authoritative reference — the full frontmatter schema, the deterministic discovery routine, and tie-break/ordering rules.

Enrollment frontmatter:

An agent enrolls by adding three keys to its frontmatter:

---
name: devils-advocate
description: "..."
model: opus
tools: Read, Write, Edit, Glob, Grep
# --- hook enrollment ---
phase: post-plan   # one of the 8 hook points above
order: 10          # lower runs first within a hook; default 100
mode: single       # "single" | "batch"; default "single"
---

Customizing the pipeline:

Enable, add, remove, or reorder agents by editing frontmatter — never a central file.

• Enable a built-in agent. standards-enforcer ships with its enrollment commented out. Uncomment its phase (and optional order / mode) to turn it on:

  ---
  name: standards-enforcer
  description: "..."
  model: opus
  tools: Read, Edit, Glob, Grep
  # To enable code-standards enforcement after implementation, uncomment:
  phase: post-implementation
  order: 50
  mode: batch
  ---
  

• Add a custom gate. Drop an agent file into your project's .claude/agents/ directory with a phase, and it is enrolled automatically:

  ---
  name: doc-updater
  description: "Updates documentation when implementation changes."
  model: sonnet
  tools: Read, Edit, Glob, Grep
  phase: post-implementation
  order: 100
  mode: single
  ---
  
  You are a documentation updater. Your job is to...
  {define the agent's behavior, process, and output format}
  

• Disable an agent. Remove (or comment out) its phase key — there is no condition to toggle.

The agent's filename (without .md) should match its frontmatter name. Local agents in .claude/agents/ override plugin agents with the same name (the local file wins entirely) — the override is keyed on the frontmatter name, not the filename.

Check what's actually enrolled. After editing frontmatter, run the discovery script to confirm it took effect. This is the first thing to try when an agent doesn't fire:

$(claude plugin path hcf)/hooks/discover-hooks.sh

# hook: pre-plan
  (empty — no agents enrolled at this hook)

# hook: post-plan
  order=10    name=devils-advocate                          mode=single
...

Add --hook=post-plan for one hook, or --json for machine-readable output. HCF's planning skills run this exact script rather than enumerating agent files themselves, so what it prints is what will run.

A non-zero exit means discovery genuinely failed — it is not the same as a hook being empty. Exit 3 means an agent file declares an invalid phase or mode (the message names the file and the fix); exit 4 means enrollment changed partway through a run. Both halt HCF deliberately, rather than quietly running a different pipeline than you configured.

Upgrading from pipeline.md: Earlier versions of HCF configured the pipeline in a central .claude/pipeline.md file. That file is no longer read — agent frontmatter is now the only source of pipeline configuration. If a leftover .claude/pipeline.md is present, HCF blocks plan-create and plan-orchestrate (you'll see a prompt on session start and when you try to plan) until you run /project-update, which migrates your configuration into agent frontmatter and removes the file. /project-update is never blocked, and the gate clears automatically once the file is gone.

Dependency Graph

After generating a plan, HCF visualizes the task dependency graph so you can verify parallelism and ordering before execution:

001 ─┬─► 002 ─┬─► 005
     │        │
     └─► 003 ─┘
     │
     └─► 004 ────► 006

This tells the orchestrator which tasks can run in parallel and which must wait. In this example:

• Batch 1: Task 001 (no dependencies)
• Batch 2: Tasks 002, 003, 004 (all depend only on 001)
• Batch 3: Tasks 005, 006 (005 depends on 002+003; 006 depends on 004)

Parallel Execution

Independent tasks within each batch run simultaneously:

Batch 1: Task 001 (no deps)          → 1 worker
Batch 2: Tasks 002, 003, 004         → 3 parallel workers
Batch 3: Tasks 005, 006              → 2 parallel workers

100 tasks might complete in 5-10 batches instead of 100 sequential runs.

TDD Methodology

Each task follows strict Red → Green → Refactor:

1. Write failing test for one requirement
2. Write minimum code to pass
3. Refactor while tests stay green
4. Repeat for next requirement
5. Commit when task complete

Reference

Files Created

Project Config (.claude/)

| File | Purpose | |------|---------| | testing.md | Test commands, coverage requirements | | code-standards.md | Linting, formatting rules | | architecture.md | Directory structure, patterns |

Plans (.claude/plans/{name}/, configurable — see Plans Directory)

| File | Purpose | |------|---------| | _plan.md | Plan overview, task table | | 001-{task}.md | First task with requirements | | 002-{task}.md | Second task | | ... | More tasks |

Task Format

# Task 001: Create User Model

**Status**: pending
**Depends on**: none
**Retry count**: 0

## Description
Create the User model with authentication fields.

## Requirements (Test Descriptions)
- [ ] `it creates a user with valid email and password`
- [ ] `it hashes the password before storing`
- [ ] `it validates email uniqueness`

Requirements become test names directly.

Skills

All skills can be invoked directly with /skill-name or triggered automatically by Claude when your request matches their description.

| Skill | Invocation | Auto-triggers | Description | |-------|------------|---------------|-------------| | project-setup | /project-setup | No | Configure project (one-time) | | project-update | /project-update | No | Sync config with latest plugin defaults | | plan-create | /plan-create [description] | Yes — "Build a...", "Let's start building...", "I want an app that...", "Help me implement...", capability lists, etc. | Interactive planning with codebase discovery and grounded clarification | | plan-orchestrate | /plan-orchestrate [plan-name] | Yes — "Run the plan", "Execute", "Start implementation" | Parallel TDD execution |

Outputs

| Output | Meaning | |--------|---------| | ALL_TASKS_COMPLETE | Plan finished successfully | | TASKS_BLOCKED: [003, 007] | Some tasks failed after retries |

Architecture

hcf/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── agents/
│   ├── devils-advocate.md    # Plan reviewer - finds gaps before execution (opus)
│   ├── tdd-worker.md         # TDD implementation worker (sonnet)
│   └── standards-enforcer.md # Code standards enforcement (sonnet)
├── hooks/
│   ├── discover-hooks.sh     # Deterministic hook-agent discovery (see HOOKS.md)
│   ├── detect-legacy-pipeline.sh # SessionStart warning for a legacy pipeline.md
│   ├── gate-skill.sh         # PreToolUse gate on the planning sk