Skip to content
Back to search

hcf

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/markshust--hcf/badge.svg)](/listings/markshust--hcf)

HTML

<a href="/listings/markshust--hcf"><img src="/api/listings/markshust--hcf/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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)

  1. {
  2. "name": "hcf",
  3. "owner": {
  4. "name": "Mark Shust",
  5. "email": "mark@shust.com",
  6. "url": "https://github.com/markshust"
  7. },
  8. "plugins": [
  9. {
  10. "name": "hcf",
  11. "source": "./",
  12. "description": "Autonomous development orchestration with parallel TDD execution",
  13. "version": "2.4.0",
  14. "homepage": "https://github.com/markshust/hcf",
  15. "license": "MIT",
  16. "keywords": ["tdd", "autonomous", "orchestration", "planning", "agents"]
  17. }
  18. ]
  19. }
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)

  1. # HCF (Halt and Catch Fire)
  2. Autonomous development plugin for Claude Code. Define requirements with a PM, then let parallel workers implement everything using TDD.
  3. ## Table of Contents
  4. - [Overview](#overview)
  5. - [Getting Started](#getting-started)
  6. - [Installation](#installation)
  7. - [Quick Start](#quick-start)
  8. - [How It Works](#how-it-works)
  9. - [Four Phases](#four-phases)
  10. - [Pipeline](#pipeline)
  11. - [Dependency Graph](#dependency-graph)
  12. - [Parallel Execution](#parallel-execution)
  13. - [TDD Methodology](#tdd-methodology)
  14. - [Reference](#reference)
  15. - [Files Created](#files-created)
  16. - [Task Format](#task-format)
  17. - [Skills](#skills)
  18. - [Outputs](#outputs)
  19. - [Architecture](#architecture)
  20. - [Advanced Configuration](#advanced-configuration)
  21. - [Plans Directory](#plans-directory)
  22. - [Design Principles](#design-principles)
  23. - [Development](#development)
  24. - [Local Testing](#local-testing)
  25. - [Testing Workflow](#testing-workflow)
  26. - [Debugging](#debugging)
  27. - [Changelog](#changelog)
  28. - [Contributing](#contributing)
  29. - [License](#license)
  30. ## Overview
  31. HCF separates **planning** (human-in-the-loop) from **execution** (fully autonomous):
  32. ```
  33. Planning → Human + AI collaborate on requirements
  34. Execution → Parallel TDD workers implement autonomously
  35. ```
  36. ## Getting Started
  37. ### Installation
  38. Add the marketplace, install, then reload:
  39. ```bash
  40. /plugin marketplace add markshust/hcf
  41. /plugin install hcf@hcf
  42. /reload-plugins
  43. ```
  44. ### Quick Start
  45. #### 1. Setup Project (one-time)
  46. ```bash
  47. /project-setup
  48. ```
  49. Interactively configures your project:
  50. - Auto-detects tech stack (Laravel, React, etc.)
  51. - Asks about testing, linting, architecture
  52. - Creates `.claude/` config directory
  53. #### 2. Plan a Feature
  54. Just describe what you want:
  55. ```
  56. "Help me implement user authentication with JWT"
  57. ```
  58. The `plan-create` skill activates automatically to:
  59. - **Discover & brainstorm** — explore the codebase and enumerate scope/assumption permutations a senior engineer would catch
  60. - Create a `feature/{plan-name}` branch for the work
  61. - Ask grounded clarifying questions categorized as **must-answer** vs **will-default-if-silent**
  62. - Break down into tasks with dependencies
  63. - Write requirements as test descriptions
  64. - Create `.claude/plans/user-auth/` with task files (or your configured [plans directory](#plans-directory))
  65. - Run **post-plan pipeline** agents (devil's advocate by default) to find gaps before execution
  66. After planning completes, you'll be asked:
  67. > Ready to begin autonomous implementation?
  68. > 1. Yes, start now
  69. > 2. No, I'll run it later
  70. #### 3. Execute Autonomously
  71. If you chose "later" or want to re-run, say:
  72. ```
  73. "Run the user-auth plan" or "Execute the plan"
  74. ```
  75. The `plan-orchestrate` skill auto-triggers. It verifies you're on the correct `feature/{plan-name}` branch before starting.
  76. 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:
  77. ```
  78. /goal the user-auth plan run reached a terminal state: plan-orchestrate output ALL_TASKS_COMPLETE or TASKS_BLOCKED
  79. ```
  80. After completion, you'll be prompted to push the branch and create a PR (never done without your permission).
  81. ## How It Works
  82. ### Four Phases
  83. | Phase | Type | What Happens |
  84. |-------|------|--------------|
  85. | Setup | One-time | Configure project for autonomous dev |
  86. | Planning | Interactive | Discover codebase, brainstorm scope, then define tasks with human guidance |
  87. | Post-Plan Hooks | Automated | Agents enrolled at the `post-plan` hook review the plan |
  88. | Execution | Autonomous | Parallel TDD implementation, with agents enrolled at the implementation hooks |
  89. ### Pipeline
  90. 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.
  91. **Hook points:**
  92. There are exactly **8** hook points where enrolled agents can run:
  93. | Hook | Fires |
  94. |------|-------|
  95. | `pre-plan` | Before planning Discovery begins |
  96. | `post-plan` | After the plan is built and validated, before user review |
  97. | `pre-implementation` | Before the first implementation batch |
  98. | `pre-batch` | Before each batch of TDD workers launches |
  99. | `post-batch` | When the last task of a batch finishes |
  100. | `post-implementation` | After all tasks complete |
  101. | `pre-commit` | After the full test suite passes, before the commit |
  102. | `post-commit` | After the commit, before the push/PR prompt |
  103. 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.
  104. **Enrollment frontmatter:**
  105. An agent enrolls by adding three keys to its frontmatter:
  106. ```yaml
  107. ---
  108. name: devils-advocate
  109. description: "..."
  110. model: opus
  111. tools: Read, Write, Edit, Glob, Grep
  112. # --- hook enrollment ---
  113. phase: post-plan # one of the 8 hook points above
  114. order: 10 # lower runs first within a hook; default 100
  115. mode: single # "single" | "batch"; default "single"
  116. ---
  117. ```
  118. **Customizing the pipeline:**
  119. Enable, add, remove, or reorder agents by editing frontmatter — never a central file.
  120. - **Enable a built-in agent.** `standards-enforcer` ships with its enrollment commented out. Uncomment its `phase` (and optional `order` / `mode`) to turn it on:
  121. ```yaml
  122. ---
  123. name: standards-enforcer
  124. description: "..."
  125. model: opus
  126. tools: Read, Edit, Glob, Grep
  127. # To enable code-standards enforcement after implementation, uncomment:
  128. phase: post-implementation
  129. order: 50
  130. mode: batch
  131. ---
  132. ```
  133. - **Add a custom gate.** Drop an agent file into your project's `.claude/agents/` directory with a `phase`, and it is enrolled automatically:
  134. ```markdown
  135. ---
  136. name: doc-updater
  137. description: "Updates documentation when implementation changes."
  138. model: sonnet
  139. tools: Read, Edit, Glob, Grep
  140. phase: post-implementation
  141. order: 100
  142. mode: single
  143. ---
  144. You are a documentation updater. Your job is to...
  145. {define the agent's behavior, process, and output format}
  146. ```
  147. - **Disable an agent.** Remove (or comment out) its `phase` key — there is no condition to toggle.
  148. 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.
  149. **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:
  150. ```bash
  151. $(claude plugin path hcf)/hooks/discover-hooks.sh
  152. ```
  153. ```
  154. # hook: pre-plan
  155. (empty — no agents enrolled at this hook)
  156. # hook: post-plan
  157. order=10 name=devils-advocate mode=single
  158. ...
  159. ```
  160. 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.
  161. 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.
  162. > **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.
  163. ### Dependency Graph
  164. After generating a plan, HCF visualizes the task dependency graph so you can verify parallelism and ordering before execution:
  165. ```
  166. 001 ─┬─► 002 ─┬─► 005
  167. │ │
  168. └─► 003 ─┘
  169. │
  170. └─► 004 ────► 006
  171. ```
  172. This tells the orchestrator which tasks can run in parallel and which must wait. In this example:
  173. - Task 001 starts first (no dependencies)
  174. - Tasks 002, 003, 004 start together when 001 finishes
  175. - Task 006 starts as soon as 004 finishes, even if 002 and 003 are still running
  176. - Task 005 starts when both 002 and 003 have finished
  177. ### Parallel Execution
  178. Tasks start the moment their own dependencies finish. Nothing waits for an
  179. unrelated task that happened to start at the same time:
  180. ```
  181. t=0 001 starts → 1 worker
  182. 001 done → 002, 003, 004 start → 3 workers
  183. 004 done → 006 starts → 002, 003 still running
  184. 002 + 003 done → 005 starts
  185. ```
  186. Total time follows the plan's longest dependency chain rather than the slowest
  187. task of each step. HCF sets no limit on how many workers run at once; Claude
  188. Code does, at 20 subagents per session by default. To run more, raise it in your
  189. shell or in the `env` block of your Claude Code settings:
  190. ```bash
  191. export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=40
  192. ```
  193. ### TDD Methodology
  194. Each task follows strict Red → Green → Refactor:
  195. 1. Write failing test for one requirement
  196. 2. Write minimum code to pass
  197. 3. Refactor while tests stay green
  198. 4. Repeat for next requirement
  199. 5. Commit when task complete
  200. ## Reference
  201. ### Files Created
  202. #### Project Config (`.claude/`)
  203. | File | Purpose |
  204. |------|---------|
  205. | `testing.md` | Test commands, coverage requirements |
  206. | `code-standards.md` | Linting, formatting rules |
  207. | `architecture.md` | Directory structure, patterns |
  208. #### Plans (`.claude/plans/{name}/`, configurable — see [Plans Directory](#plans-directory))
  209. | File | Purpose |
  210. |------|---------|
  211. | `_plan.md` | Plan overview, task table |
  212. | `001-{task}.md` | First task with requirements |
  213. | `002-{task}.md` | Second task |
  214. | ... | More tasks |
  215. ### Task Format
  216. ```markdown
  217. # Task 001: Create User Model
  218. **Status**: pending
  219. **Depends on**: none
  220. **Retry count**: 0
  221. ## Description
  222. Create the User model with authentication fields.
  223. ## Requirements (Test Descriptions)
  224. - [ ] `it creates a user with valid email and password`
  225. - [ ] `it hashes the password before storing`
  226. - [ ] `it validates email uniqueness`
  227. ```
  228. Requirements become test names directly.
  229. ### Skills
  230. All skills can be invoked directly with `/skill-name` or triggered automatically by Claude when your request matches their description.
  231. | Skill | Invocation | Auto-triggers | Description |
  232. |-------|------------|---------------|-------------|
  233. | `project-setup` | `/project-setup` | No | Configure project (one-time) |
  234. | `project-update` | `/project-update` | No | Sync config with latest plugin defaults |
  235. | `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 |
  236. | `plan-orchestrate` | `/plan-orchestrate [plan-name]` | Yes — "Run the plan", "Execute", "Start implementation" | Parallel TDD execution |
  237. ### Outputs
  238. | Output | Meaning |
  239. |--------|---------|
  240. | `ALL_TASKS_COMPLETE` | Plan finished successfully |
  241. | `TASKS_BLOCKED: [003, 007]` | Some tasks failed after retries |
  242. ## Architecture
  243. ```
  244. hcf/
  245. ├── .claude-plugin/
  246. │ └── plugin.json # Plugin manifest
  247. ├── agents/
  248. │ ├── devils-advocate.md # Plan reviewer - finds gaps before execution (opus)
  249. │ ├── tdd-worker.md # TDD implementation worker (sonnet)
  250. │ └── standards-enforcer.md # Code standards enforcement (sonnet)
  251. ├── hooks/
  252. │ ├── discover-hooks.sh # Deterministic hook-agent discovery (see HOOKS.md)
  253. │ ├── detect-legacy-pipeline.sh # SessionStart warning for a legacy pipeline.md
  254. │ ├── gate-skill.sh # PreToolUse gate on the planning skills
  255. │ ├── gate-command.sh # UserPromptExpansion gate on the planning skills
  256. │ ├── pipeline-status.sh # Shared helper sourced by the gates
  257. │ └── hooks.json # Lifecycle hook registrations
  258. ├── skills/
  259. │ ├── project-setup/
  260. │ │ └── SKILL.md # One-time setup skill (manual invocation only)
  261. │ ├── project-update/
  262. │ │ └── SKILL.md # Sync project config with plugin updates (manual)
  263. │ ├── plan-create/
  264. │ │ └── SKILL.md # Interactive planning skill (auto-triggers)
  265. │ └── plan-orchestrate/
  266. │ └── SKILL.md # Parallel TDD execution skill (auto-triggers)
  267. ├── tests/
  268. │ ├── run-tests.sh # Test suite entry point (no dependencies)
  269. │ ├── lib.sh # Assertions and fixture helpers
  270. │ ├── test-*.sh # Suites, auto-discovered by run-tests.sh
  271. │ └── fixtures/ # Agent files exercising parser edge cases
  272. ├── .claude/
  273. │ └── CLAUDE.md # HCF's own project config (not shipped to users)
  274. ├── HOOKS.md # Authoritative hook/frontmatter reference
  275. └── README.md
  276. ```
  277. The `CLAUDE.md` template that `/project-setup` generates for **your** project
  278. lives inline in `skills/project-setup/SKILL.md` — `.claude/CLAUDE.md` above is
  279. this repo's own config and has no effect on what users get.
  280. ## Advanced Configuration
  281. HCF works with no configuration. Everything below is opt-in, and the defaults
  282. are what you get by leaving it alone.
  283. ### Plans Directory
  284. Plans live in `.claude/plans/` by default. To put them somewhere else — beside
  285. your other docs, or at the repo root — create `.claude/hcf.json`:
  286. ```json
  287. {
  288. "plansDir": "docs/plans"
  289. }
  290. ```
  291. `plansDir` is a path **relative to the project root**. Absolute paths and any
  292. `..` segment are rejected, because plan folders belong inside the repo they
  293. document.
  294. **No skill ever creates or modifies `.claude/hcf.json`.** `/hcf:project-setup`
  295. does not ask about it and `/hcf:project-update` only validates it if you have
  296. already written one. Its absence is the normal case, not an incomplete setup.
  297. **A malformed value stops the run rather than falling back.** If `plansDir` is
  298. absolute, escapes the project, or is set to an empty string, HCF reports it and
  299. refuses. Quietly writing plans to `.claude/plans` when you asked for
  300. `docs/plans` would be the worse outcome: you would find out much later, from
  301. the wrong directory filling up.
  302. **Changing it after plans exist means moving the folders yourself.** HCF does
  303. not migrate them; `/hcf:project-update` warns when `.claude/plans` still holds
  304. plan folders after a move.
  305. **Plans are ephemeral.** A plan is the working state of a single run, not
  306. documentation. `/hcf:plan-orchestrate` never commits plan files: it stages the
  307. implementation and leaves the plans directory out. Once the work is committed,
  308. the code and its tests are the source of truth. A plan kept around goes stale as
  309. soon as the feature changes, and an agent that later reads it will be misled.
  310. Keep the folder while the run is in progress, since that's what lets an
  311. interrupted run resume, and delete it once the branch is merged. To keep plans
  312. out of git entirely, add the directory to `.gitignore`:
  313. ```gitignore
  314. .claude/plans/
  315. ```
  316. To see what a project resolves to:
  317. ```bash
  318. $(claude plugin path hcf)/hooks/resolve-plans-dir.sh
  319. ```
  320. ## Design Principles
  321. 1. **Pure TDD** - No Gherkin/BDD, requirements map directly to test names
  322. 2. **Parallel by default** - Auto-detect independent tasks, maximize concurrency
  323. 3. **100% portable** - the generated CLAUDE.md is identical across all projects
  324. 4. **Explicit dependencies** - Tasks declare what they depend on
  325. 5. **Fail gracefully** - Retry 3x, then block and continue with other tasks
  326. ## Development
  327. ### Requirements
  328. - Claude Code CLI
  329. - Git repository
  330. - Test framework configured in project
  331. ### Local Testing
  332. Test the plugin locally without publishing using the `--plugin-dir` flag:
  333. ```bash
  334. claude --plugin-dir /path/to/hcf
  335. ```
  336. Skills are namespaced with the plugin name:
  337. - `/hcf:project-setup`
  338. - `/hcf:plan-create [description]`
  339. - `/hcf:plan-orchestrate [plan-name]`
  340. Skills with `disable-model-invocation: true` (like `project-setup`) require manual invocation. Others auto-trigger based on their descriptions.
  341. ### Testing Workflow
  342. 1. **Start Claude Code with the plugin:**
  343. ```bash
  344. cd ~/Sites/your-test-project
  345. claude --plugin-dir ~/Sites/hcf
  346. ```
  347. 2. **Verify plugin loads:**
  348. ```
  349. /help
  350. ```
  351. Skills should appear under the `hcf` namespace.
  352. 3. **Test each component:**
  353. ```bash
  354. # Test project setup (direct invocation only)
  355. /hcf:project-setup
  356. # Test plan-create (auto-triggers on feature requests, or invoke directly)
  357. "Create a plan to implement user authentication"
  358. /hcf:plan-create user authentication with JWT
  359. # Test plan-orchestrate (auto-triggers on execution requests, or invoke directly)
  360. "Run the user-auth plan"
  361. /hcf:plan-orchestrate user-auth
  362. ```
  363. ### Debugging
  364. Run with debug output to see plugin loading details:
  365. ```bash
  366. claude --plugin-dir ./hcf --debug
  367. ```
  368. To load multiple plugins:
  369. ```bash
  370. claude --plugin-dir ./hcf --plugin-dir ./other-plugin
  371. ```
  372. **Plugin Structure Notes:**
  373. - Only `plugin.json` goes in `.claude-plugin/`
  374. - Skills, agents, and other components stay at the plugin root level
  375. - Each skill is a directory with a `SKILL.md` entrypoint
  376. - Skills auto-trigger based on their `description` frontmatter (unless `disable-model-invocation: true`)
  377. ## Changelog
  378. 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.
  379. ## Contributing
  380. 1. Fork the repository
  381. 2. Create a feature branch
  382. 3. Test locally with `--plugin-dir`
  383. 4. Add an entry to the `[Unreleased]` section of `CHANGELOG.md` if your change is user-visible
  384. 5. Submit a pull request
  385. ## Credits
  386. Created by [Mark Shust](https://markshust.com)
  387. ## License
  388. HCF is open-source software licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.