hcf
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/markshust/hcf with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/markshust/hcf'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/markshust--hcf)HTML
<a href="/listings/markshust--hcf"><img src="/api/listings/markshust--hcf/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](#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).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 19 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "hcf",
- "owner": {
- "name": "Mark Shust",
- "email": "mark@shust.com",
- "url": "https://github.com/markshust"
- },
- "plugins": [
- {
- "name": "hcf",
- "source": "./",
- "description": "Autonomous development orchestration with parallel TDD execution",
- "version": "2.4.0",
- "homepage": "https://github.com/markshust/hcf",
- "license": "MIT",
- "keywords": ["tdd", "autonomous", "orchestration", "planning", "agents"]
- }
- ]
- }
README.md · README · 517 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.