# 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](#overview)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [How It Works](#how-it-works)
- [Four Phases](#four-phases)
- [Pipeline](#pipeline)
- [Dependency Graph](#dependency-graph)
- [Parallel Execution](#parallel-execution)
- [TDD Methodology](#tdd-methodology)
- [Reference](#reference)
- [Files Created](#files-created)
- [Task Format](#task-format)
- [Skills](#skills)
- [Outputs](#outputs)
- [Architecture](#architecture)
- [Advanced Configuration](#advanced-configuration)
- [Plans Directory](#plans-directory)
- [Design Principles](#design-principles)
- [Development](#development)
- [Local Testing](#local-testing)
- [Testing Workflow](#testing-workflow)
- [Debugging](#debugging)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [License](#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:
```bash
/plugin marketplace add markshust/hcf
/plugin install hcf@hcf
/reload-plugins
```
### Quick Start
#### 1. Setup Project (one-time)
```bash
/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](#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](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:
```yaml
---
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:
```yaml
---
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:
```markdown
---
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:
```bash
$(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:
```bash
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](#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
```markdown
# 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 skills
โ โโโ gate-command.sh # UserPromptExpansion gate on the planning skills
โ โโโ pipeline-status.sh # Shared helper sourced by the gates
โ โโโ hooks.json # Lifecycle hook registrations
โโโ skills/
โ โโโ project-setup/
โ โ โโโ SKILL.md # One-time setup skill (manual invocation only)
โ โโโ project-update/
โ โ โโโ SKILL.md # Sync project config with plugin updates (manual)
โ โโโ plan-create/
โ โ โโโ SKILL.md # Interactive planning skill (auto-triggers)
โ โโโ plan-orchestrate/
โ โโโ SKILL.md # Parallel TDD execution skill (auto-triggers)
โโโ tests/
โ โโโ run-tests.sh # Test suite entry point (no dependencies)
โ โโโ lib.sh # Assertions and fixture helpers
โ โโโ test-*.sh # Suites, auto-discovered by run-tests.sh
โ โโโ fixtures/ # Agent files exercising parser edge cases
โโโ .claude/
โ โโโ CLAUDE.md # HCF's own project config (not shipped to users)
โโโ HOOKS.md # Authoritative hook/frontmatter reference
โโโ README.md
```
The `CLAUDE.md` template that `/project-setup` generates for **your** project
lives inline in `skills/project-setup/SKILL.md` โ `.claude/CLAUDE.md` above is
this repo's own config and has no effect on what users get.
## Advanced Configuration
HCF works with no configuration. Everything below is opt-in, and the defaults
are what you get by leaving it alone.
### Plans Directory
Plans live in `.claude/plans/` by default. To put them somewhere else โ beside
your other docs, or at the repo root โ create `.claude/hcf.json`:
```json
{
"plansDir": "docs/plans"
}
```
`plansDir` is a path **relative to the project root**. Absolute paths and any
`..` segment are rejected, because plan folders belong inside the repo they
document.
**No skill ever creates or modifies `.claude/hcf.json`.** `/hcf:project-setup`
does not ask about it and `/hcf:project-update` only validates it if you have
already written one. Its absence is the normal case, not an incomplete setup.
**A malformed value stops the run rather than falling back.** If `plansDir` is
absolute, escapes the project, or is set to an empty string, HCF reports it and
refuses. Quietly writing plans to `.claude/plans` when you asked for
`docs/plans` would be the worse outcome: you would find out much later, from
the wrong directory filling up.
**Changing it after plans exist means moving the folders yourself.** HCF does
not migrate them; `/hcf:project-update` warns when `.claude/plans` still holds
plan folders after a move.
**Plans are ephemeral.** A plan is the working state of a single run, not
documentation. `/hcf:plan-orchestrate` never commits plan files: it stages the
implementation and leaves the plans directory out. Once the work is committed,
the code and its tests are the source of truth. A plan kept around goes stale as
soon as the feature changes, and an agent that later reads it will be misled.
Keep the folder while the run is in progress, since that's what lets an
interrupted run resume, and delete it once the branch is merged. To keep plans
out of git entirely, add the directory to `.gitignore`:
```gitignore
.claude/plans/
```
To see what a project resolves to:
```bash
$(claude plugin path hcf)/hooks/resolve-plans-dir.sh
```
## Design Principles
1. **Pure TDD** - No Gherkin/BDD, requirements map directly to test names
2. **Parallel by default** - Auto-detect independent tasks, maximize concurrency
3. **100% portable** - the generated CLAUDE.md is identical across all projects
4. **Explicit dependencies** - Tasks declare what they depend on
5. **Fail gracefully** - Retry 3x, then block and continue with other tasks
## Development
### Requirements
- Claude Code CLI
- Git repository
- Test framework configured in project
### Local Testing
Test the plugin locally without publishing using the `--plugin-dir` flag:
```bash
claude --plugin-dir /path/to/hcf
```
Skills are namespaced with the plugin name:
- `/hcf:project-setup`
- `/hcf:plan-create [description]`
- `/hcf:plan-orchestrate [plan-name]`
Skills with `disable-model-invocation: true` (like `project-setup`) require manual invocation. Others auto-trigger based on their descriptions.
### Testing Workflow
1. **Start Claude Code with the plugin:**
```bash
cd ~/Sites/your-test-project
claude --plugin-dir ~/Sites/hcf
```
2. **Verify plugin loads:**
```
/help
```
Skills should appear under the `hcf` namespace.
3. **Test each component:**
```bash
# Test project setup (direct invocation only)
/hcf:project-setup
# Test plan-create (auto-triggers on feature requests, or invoke directly)
"Create a plan to implement user authentication"
/hcf:plan-create user authentication with JWT
# Test plan-orchestrate (auto-triggers on execution requests, or invoke directly)
"Run the user-auth plan"
/hcf:plan-orchestrate user-auth
```
### Debugging
Run with debug output to see plugin loading details:
```bash
claude --plugin-dir ./hcf --debug
```
To load multiple plugins:
```bash
claude --plugin-dir ./hcf --plugin-dir ./other-plugin
```
**Plugin Structure Notes:**
- Only `plugin.json` goes in `.claude-plugin/`
- Skills, agents, and other components stay at the plugin root level
- Each skill is a directory with a `SKILL.md` entrypoint
- Skills auto-trigger based on their `description` frontmatter (unless `disable-model-invocation: true`)
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for the full release history. New user-visible changes are added to the `[Unreleased]` section as they land and moved into a versioned section at release time.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Test locally with `--plugin-dir`
4. Add an entry to the `[Unreleased]` section of `CHANGELOG.md` if your change is user-visible
5. Submit a pull request
## Credits
Created by [Mark Shust](https://markshust.com)
## License
HCF is open-source software licensed under the [MIT License](LICENSE).