HangYu8123/HarnessFlow

HarnessFlow – Portable AI‑coding workflow pack

What it is – A collection of ready‑to‑copy Markdown files that turn Claude Code, Codex CLI, or GitHub Copilot into a multi‑step, self‑reviewing coding assistant. The repo contains no executable code of its own; it only provides instruction templates, agent definitions, and workflow files that the target AI tool reads from the repository.

Key ideas

• Request‑driven – nothing runs until you paste a filled‑in template from request_template/ (e.g., code_request_template.md).
• Parallel analysis – three sub‑agents (Focus, Broad, Free) read the codebase, then a “Senior Engineer” synthesises a plan.
• Self‑challenge – a Devil’s‑Advocate step stress‑tests the plan before any code is written.
• QA & approval – a QA Engineer validates the changes; you can add an approval gate.
• Persistent repo memory – results are stored in repo_info/ so later requests start with context instead of re‑deriving it.
• Three workflow modes – general (thorough), fast (token‑efficient), and skill (uses community‑vetted skills).

Supported platforms

Platform	Entry point created by the setup scripts
Claude Code CLI	CLAUDE.md at repo root
Codex CLI / Codex in VS Code	AGENTS.md at repo root
VS Code + GitHub Copilot	.github/copilot‑instructions.md
Other LLM‑based assistants (e.g., Aider)	Manual reference to workflow files

How to install

1. Clone the repo somewhere and copy its contents into the target repository under .github/HarnessFlow/ (the README gives an rsync command that excludes internal files like repo_info/ and benchmark artefacts).
2. Run the appropriate setup script:

   # For Claude or Codex CLI
   bash .github/HarnessFlow/cli_setup.sh
   
   # For VS Code + Copilot
   bash .github/HarnessFlow/setup.sh
   

   The scripts generate the router files (CLAUDE.md, AGENTS.md, .github/copilot‑instructions.md) and create empty repo_info/ files.

Getting started

1. Initialize repo memory – copy request_template/initialize_request_template.md, fill in the placeholders, and paste it into your AI assistant. This populates repo_info/ with an overview of the codebase.
2. Submit a task – choose the appropriate template (e.g., code_request_template.md, debug_request_template.md, pr_request_template.md), edit the task description, and paste the whole file. The mode: header selects the workflow family (fast is the default; switch to general or skill if desired).

What you can ask it to do – nine request types, each with its own workflow file:

• Implement new functionality
• Refactor existing code
• Debug failures
• Answer questions / generate documentation
• Run correctness checks / tests
• Execute scripts or commands and verify outcomes
• Split a large change into stacked PRs
• Bootstrap or re‑initialize the repo‑memory
• Loop a task until a condition is met

Benchmarks (as reported in the repo)

• Ponytail benchmark (5‑task code‑generation suite) – HarnessFlow‑Fast reduces generated lines of code by 34‑76 % compared with a bare model while keeping 100 % correctness (45/45 passes). It outperforms the fastworkflow baseline, which writes 1.6‑3.4× more code and is less correct.
• Fast vs. General – on a 1 000‑line OpenCV+scikit‑learn project and a SWE‑bench bug‑fix, the fast workflow achieves the same successful outcome as general while using only 39‑50 % of the token budget and producing the leanest code (860 lines vs. 1 173 lines).
• Detailed logs and methodology are stored under experiment/, experiment_swe/, and experiment_ponytail/ (git‑ignored in the source repo).

Repository layout (high‑level)

.github/HarnessFlow/
├─ AGENTS.md / CLAUDE.md          # generated routers
├─ copilot‑instructions.md        # VS Code Copilot router
├─ cli_setup.sh / setup.sh       # install scripts
├─ sync_agent_definitions.py     # regenerates native agent files
├─ _lib/                         # shared contracts, safety rules, utilities
├─ philosophy/                   # behavioural guidance for agents
├─ workflow/                     # three families: general, fast, skill
├─ agents/                       # source agent definitions (MD/TOML)
├─ request_template/             # user‑facing templates
├─ skills/                       # community‑voted skill definitions (used by skill mode)
└─ repo_info/                    # generated memory files (git‑ignored)

Why it matters – By externalising the orchestration logic into plain Markdown, HarnessFlow works with any AI coding assistant that can read repository‑local instruction files. It gives developers a repeatable, auditable pipeline (planning → self‑challenge → QA → memory) without requiring a separate runtime or package installation.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.