{"id":49504329,"url":"https://github.com/markshust/hcf","last_synced_at":"2026-05-01T14:02:13.924Z","repository":{"id":354302785,"uuid":"1170046481","full_name":"markshust/hcf","owner":"markshust","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T01:19:46.000Z","size":78,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T02:35:59.050Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markshust.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T16:12:45.000Z","updated_at":"2026-04-28T01:19:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/markshust/hcf","commit_stats":null,"previous_names":["markshust/hcf"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/markshust/hcf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markshust%2Fhcf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markshust%2Fhcf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markshust%2Fhcf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markshust%2Fhcf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markshust","download_url":"https://codeload.github.com/markshust/hcf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markshust%2Fhcf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32499691,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-01T14:02:13.007Z","updated_at":"2026-05-01T14:02:13.908Z","avatar_url":"https://github.com/markshust.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# HCF (Halt and Catch Fire)\n\nAutonomous development plugin for Claude Code. Define requirements with a PM, then let parallel workers implement everything using TDD.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Getting Started](#getting-started)\n  - [Installation](#installation)\n  - [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n  - [Four Phases](#four-phases)\n  - [Pipeline](#pipeline)\n  - [Dependency Graph](#dependency-graph)\n  - [Parallel Execution](#parallel-execution)\n  - [TDD Methodology](#tdd-methodology)\n- [Reference](#reference)\n  - [Files Created](#files-created)\n  - [Task Format](#task-format)\n  - [Skills](#skills)\n  - [Outputs](#outputs)\n- [Architecture](#architecture)\n- [Design Principles](#design-principles)\n- [Development](#development)\n  - [Local Testing](#local-testing)\n  - [Testing Workflow](#testing-workflow)\n  - [Debugging](#debugging)\n- [Changelog](#changelog)\n- [Contributing](#contributing)\n- [Learn the Workflow](#learn-the-workflow)\n- [License](#license)\n\n## Overview\n\nHCF separates **planning** (human-in-the-loop) from **execution** (fully autonomous):\n\n```\nPlanning → Human + AI collaborate on requirements\nExecution → Parallel TDD workers implement autonomously\n```\n\n## Getting Started\n\n### Installation\n\nAdd the marketplace, install, then reload:\n\n```bash\n/plugin marketplace add markshust/hcf\n/plugin install hcf@hcf\n/reload-plugins\n```\n\n### Quick Start\n\n#### 1. Setup Project (one-time)\n\n```bash\n/project-setup\n```\n\nInteractively configures your project:\n- Auto-detects tech stack (Laravel, React, etc.)\n- Asks about testing, linting, architecture\n- Creates `.claude/` config directory\n\n#### 2. Plan a Feature\n\nJust describe what you want:\n\n```\n\"Help me implement user authentication with JWT\"\n```\n\nThe `plan-create` skill activates automatically to:\n- **Discover \u0026 brainstorm** — explore the codebase and enumerate scope/assumption permutations a senior engineer would catch\n- Create a `feature/{plan-name}` branch for the work\n- Ask grounded clarifying questions categorized as **must-answer** vs **will-default-if-silent**\n- Break down into tasks with dependencies\n- Write requirements as test descriptions\n- Create `.claude/plans/user-auth/` with task files\n- Run **post-plan pipeline** agents (devil's advocate by default) to find gaps before execution\n\nAfter planning completes, you'll be asked:\n\u003e Ready to begin autonomous implementation?\n\u003e 1. Yes, start now\n\u003e 2. No, I'll run it later\n\n#### 3. Execute Autonomously\n\nIf you chose \"later\" or want to re-run, say:\n\n```\n\"Run the user-auth plan\" or \"Execute the plan\"\n```\n\nThe `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.\n\nAfter completion, you'll be prompted to push the branch and create a PR (never done without your permission).\n\nralph-wiggum is prompted during `/project-setup`, or install manually:\n```bash\n/plugin marketplace add anthropics/claude-code\n/plugin install ralph-wiggum@claude-code-plugins\n```\n\n## How It Works\n\n### Four Phases\n\n| Phase | Type | What Happens |\n|-------|------|--------------|\n| Setup | One-time | Configure project for autonomous dev |\n| Planning | Interactive | Discover codebase, brainstorm scope, then define tasks with human guidance |\n| Post-Plan Pipeline | Automated | Configurable agents review the plan |\n| Execution | Autonomous | Parallel TDD implementation + post-implementation pipeline |\n\n### Pipeline\n\nThe pipeline system controls which agents run before and after the core TDD implementation. It's configured in `.claude/pipeline.md`:\n\n```markdown\n# Pipeline\n\n## post-plan\n- devils-advocate\n\n## post-implementation\n\u003c!-- - standards-enforcer --\u003e\n```\n\n**Phases:**\n\n| Phase | When | Default Agent |\n|-------|------|---------------|\n| `post-plan` | After plan creation, before user review | `devils-advocate` |\n| `post-implementation` | After all TDD workers complete, before commit | none (`standards-enforcer` available, off by default) |\n\n**Customizing the pipeline:**\n\nAdd, 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:\n\n```markdown\n# Pipeline\n\n## post-plan\n- devils-advocate\n- security-reviewer\n\n## post-implementation\n- standards-enforcer\n- doc-updater\n```\n\n**Creating custom agents:**\n\nCreate a markdown file in your project's `.claude/agents/` directory:\n\n```\n.claude/agents/doc-updater.md\n```\n\nThe agent file follows the standard Claude Code agent format with frontmatter:\n\n```markdown\n---\nname: doc-updater\ndescription: \"Updates documentation when implementation changes.\"\nmodel: sonnet\ntools: Read, Edit, Glob, Grep\n---\n\nYou are a documentation updater. Your job is to...\n{define the agent's behavior, process, and output format}\n```\n\nThe agent name in `pipeline.md` must match the agent's filename (without `.md`). Local agents in `.claude/agents/` override plugin agents with the same name.\n\n### Dependency Graph\n\nAfter generating a plan, HCF visualizes the task dependency graph so you can verify parallelism and ordering before execution:\n\n```\n001 ─┬─► 002 ─┬─► 005\n     │        │\n     └─► 003 ─┘\n     │\n     └─► 004 ────► 006\n```\n\nThis tells the orchestrator which tasks can run in parallel and which must wait. In this example:\n- **Batch 1:** Task 001 (no dependencies)\n- **Batch 2:** Tasks 002, 003, 004 (all depend only on 001)\n- **Batch 3:** Tasks 005, 006 (005 depends on 002+003; 006 depends on 004)\n\n### Parallel Execution\n\nIndependent tasks within each batch run simultaneously:\n\n```\nBatch 1: Task 001 (no deps)          → 1 worker\nBatch 2: Tasks 002, 003, 004         → 3 parallel workers\nBatch 3: Tasks 005, 006              → 2 parallel workers\n```\n\n100 tasks might complete in 5-10 batches instead of 100 sequential runs.\n\n### TDD Methodology\n\nEach task follows strict Red → Green → Refactor:\n\n1. Write failing test for one requirement\n2. Write minimum code to pass\n3. Refactor while tests stay green\n4. Repeat for next requirement\n5. Commit when task complete\n\n## Reference\n\n### Files Created\n\n#### Project Config (`.claude/`)\n\n| File | Purpose |\n|------|---------|\n| `testing.md` | Test commands, coverage requirements |\n| `code-standards.md` | Linting, formatting rules |\n| `architecture.md` | Directory structure, patterns |\n| `pipeline.md` | Workflow agent configuration |\n\n#### Plans (`.claude/plans/{name}/`)\n\n| File | Purpose |\n|------|---------|\n| `_plan.md` | Plan overview, task table |\n| `001-{task}.md` | First task with requirements |\n| `002-{task}.md` | Second task |\n| ... | More tasks |\n\n### Task Format\n\n```markdown\n# Task 001: Create User Model\n\n**Status**: pending\n**Depends on**: none\n**Retry count**: 0\n\n## Description\nCreate the User model with authentication fields.\n\n## Requirements (Test Descriptions)\n- [ ] `it creates a user with valid email and password`\n- [ ] `it hashes the password before storing`\n- [ ] `it validates email uniqueness`\n```\n\nRequirements become test names directly.\n\n### Skills\n\nAll skills can be invoked directly with `/skill-name` or triggered automatically by Claude when your request matches their description.\n\n| Skill | Invocation | Auto-triggers | Description |\n|-------|------------|---------------|-------------|\n| `project-setup` | `/project-setup` | No | Configure project (one-time) |\n| `project-update` | `/project-update` | No | Sync config with latest plugin defaults |\n| `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 |\n| `plan-orchestrate` | `/plan-orchestrate [plan-name]` | Yes — \"Run the plan\", \"Execute\", \"Start implementation\" | Parallel TDD execution |\n\n### Outputs\n\n| Output | Meaning |\n|--------|---------|\n| `ALL_TASKS_COMPLETE` | Plan finished successfully |\n| `TASKS_BLOCKED: [003, 007]` | Some tasks failed after retries |\n\n## Architecture\n\n```\nhcf/\n├── .claude-plugin/\n│   └── plugin.json           # Plugin manifest\n├── agents/\n│   ├── devils-advocate.md    # Plan reviewer - finds gaps before execution (opus)\n│   ├── tdd-worker.md         # TDD implementation worker (sonnet)\n│   └── standards-enforcer.md # Code standards enforcement (sonnet)\n├── skills/\n│   ├── project-setup/\n│   │   └── SKILL.md          # One-time setup skill (manual invocation only)\n│   ├── project-update/\n│   │   └── SKILL.md          # Sync project config with plugin updates (manual)\n│   ├── plan-create/\n│   │   └── SKILL.md          # Interactive planning skill (auto-triggers)\n│   └── plan-orchestrate/\n│       └── SKILL.md          # Parallel TDD execution skill (auto-triggers)\n├── pipeline.md               # Default pipeline configuration\n├── CLAUDE.md                 # Portable CLAUDE.md template for projects\n└── README.md\n```\n\n## Design Principles\n\n1. **Pure TDD** - No Gherkin/BDD, requirements map directly to test names\n2. **Parallel by default** - Auto-detect independent tasks, maximize concurrency\n3. **100% portable** - CLAUDE.md identical across all projects\n4. **Explicit dependencies** - Tasks declare what they depend on\n5. **Fail gracefully** - Retry 3x, then block and continue with other tasks\n\n## Development\n\n### Requirements\n\n- Claude Code CLI\n- Git repository\n- Test framework configured in project\n\n### Local Testing\n\nTest the plugin locally without publishing using the `--plugin-dir` flag:\n\n```bash\nclaude --plugin-dir /path/to/hcf\n```\n\nSkills are namespaced with the plugin name:\n- `/hcf:project-setup`\n- `/hcf:plan-create [description]`\n- `/hcf:plan-orchestrate [plan-name]`\n\nSkills with `disable-model-invocation: true` (like `project-setup`) require manual invocation. Others auto-trigger based on their descriptions.\n\n### Testing Workflow\n\n1. **Start Claude Code with the plugin:**\n   ```bash\n   cd ~/Sites/your-test-project\n   claude --plugin-dir ~/Sites/hcf\n   ```\n\n2. **Verify plugin loads:**\n   ```\n   /help\n   ```\n   Skills should appear under the `hcf` namespace.\n\n3. **Test each component:**\n   ```bash\n   # Test project setup (direct invocation only)\n   /hcf:project-setup\n\n   # Test plan-create (auto-triggers on feature requests, or invoke directly)\n   \"Create a plan to implement user authentication\"\n   /hcf:plan-create user authentication with JWT\n\n   # Test plan-orchestrate (auto-triggers on execution requests, or invoke directly)\n   \"Run the user-auth plan\"\n   /hcf:plan-orchestrate user-auth\n   ```\n\n### Debugging\n\nRun with debug output to see plugin loading details:\n\n```bash\nclaude --plugin-dir ./hcf --debug\n```\n\nTo load multiple plugins:\n\n```bash\nclaude --plugin-dir ./hcf --plugin-dir ./other-plugin\n```\n\n**Plugin Structure Notes:**\n- Only `plugin.json` goes in `.claude-plugin/`\n- Skills, agents, and other components stay at the plugin root level\n- Each skill is a directory with a `SKILL.md` entrypoint\n- Skills auto-trigger based on their `description` frontmatter (unless `disable-model-invocation: true`)\n\n## Changelog\n\nSee [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.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Test locally with `--plugin-dir`\n4. Add an entry to the `[Unreleased]` section of `CHANGELOG.md` if your change is user-visible\n5. Submit a pull request\n\n## Credits\n\nCreated by [Mark Shust](https://markshust.com)\n\n## Learn the Workflow\n\nHCF is the running case study in my [AI Workflow Cohort](https://shu.st/4kYuIy), a 5-week program to learn how to architect custom workflows for AI-assisted development.\n\n## License\n\nHCF is open-source software licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkshust%2Fhcf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkshust%2Fhcf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkshust%2Fhcf/lists"}