hcf

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 launches
post-batch	When the last task of a batch finishes
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:

• Task 001 starts first (no dependencies)
• Tasks 002, 003, 004 start together when 001 finishes
• Task 006 starts as soon as 004 finishes, even if 002 and 003 are still running
• Task 005 starts when both 002 and 003 have finished

Parallel Execution

Tasks start the moment their own dependencies finish. Nothing waits for an unrelated task that happened to start at the same time:

t=0    001 starts                          → 1 worker
       001 done → 002, 003, 004 start      → 3 workers
       004 done → 006 starts               → 002, 003 still running
       002 + 003 done → 005 starts

Total time follows the plan's longest dependency chain rather than the slowest task of each step. HCF sets no limit on how many workers run at once; Claude Code does, at 20 subagents per session by default. To run more, raise it in your shell or in the env block of your Claude Code settings:

export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=40

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