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
• 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
• 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, and automatically uses ralph-wiggum for session persistence if installed. If not installed, you'll see a warning but execution continues.

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

ralph-wiggum is prompted during /project-setup, or install manually:

/plugin marketplace add anthropics/claude-code
/plugin install ralph-wiggum@claude-code-plugins

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 Pipeline	Automated	Configurable agents review the plan
Execution	Autonomous	Parallel TDD implementation + post-implementation pipeline

Pipeline

The pipeline system controls which agents run before and after the core TDD implementation. It's configured in .claude/pipeline.md:

# Pipeline

## post-plan
- devils-advocate

## post-implementation
<!-- - standards-enforcer -->

Phases:

Phase	When	Default Agent
post-plan	After plan creation, before user review	devils-advocate
post-implementation	After all TDD workers complete, before commit	none (standards-enforcer available, off by default)

Customizing the pipeline:

Add, remove, or reorder agents at any phase. For example, to add a custom security-reviewer to post-plan, enable the built-in standards-enforcer (off by default), and add a custom doc-updater to post-implementation:

# Pipeline

## post-plan
- devils-advocate
- security-reviewer

## post-implementation
- standards-enforcer
- doc-updater

Creating custom agents:

Create a markdown file in your project's .claude/agents/ directory:

.claude/agents/doc-updater.md

The agent file follows the standard Claude Code agent format with frontmatter:

---
name: doc-updater
description: "Updates documentation when implementation changes."
model: sonnet
tools: Read, Edit, Glob, Grep
---

You are a documentation updater. Your job is to...
{define the agent's behavior, process, and output format}