Why Hepha
A long agent session leaves you with a big diff, a transcript and a confident "all tests pass". Afterwards, you can only check the diff and what the agent said.
Hepha changes what is left on disk. The agent still writes the Spec, the code and the notes. The CLI runs your test commands and records the results, records the reviews, and refuses to move a task forward while evidence is missing.
| After the run, can you check… | One long agent session | A Hepha run |
|---|
| …what behaviour was agreed? | The prompt, maybe | specs/SPEC-*.md with scenario IDs. Each task has Given/When/Then acceptance criteria, fingerprinted when work starts |
| …that a test failed before the fix? | Only if it happened and you find it in the transcript | evidence/TASK-*.json holds the RED command, its non-zero exit code and output |
| …that tests pass now? | The agent's statement | GREEN and regression records, plus test_plan.commands you can rerun |
| …that Spec and code were reviewed? | Usually mixed into one pass, or skipped | Separate spec, code and human review records with reviewer and notes |
| …which commit did what? | One large diff | One small commit per task, and assets linked Spec → Task → Test → Commit |
| …what is worth reusing? | Buried in the transcript | A dated summary plus reviewed Wiki assets, searchable across projects |
What Hepha does not do: it cannot judge whether a test is meaningful or a review was thorough. It proves that commands ran with the recorded results and that each review step was explicitly recorded. Treat it as an audit trail and a guard rail, not a substitute for judgement.
See it work
examples/slugify is a small library built from an empty folder using only the Hepha CLI: three tasks, two full and one lite. Its .hepha/ folder is the real output of that run, including two gate refusals. Dogfooding it also found and fixed a bug in Hepha itself. CI re-checks the example's gates on every run.
Screenshots of hepha-server running on examples/slugify. The UI labels are in Chinese; your content can be in any language.
Quick start
1. Install the skill: clone once, then link it where your agent looks for skills.
git clone https://github.com/melonlee/hepha-skill.git
cd hepha-skill
# Claude Code: personal skill, available in all your projects
mkdir -p ~/.claude/skills && ln -s "$PWD/skills/hepha" ~/.claude/skills/hepha
# Codex: user-level skill
mkdir -p ~/.agents/skills && ln -s "$PWD/skills/hepha" ~/.agents/skills/hepha
- Claude Code, one project only: put the skill in the project's
.claude/skills/ and commit it so your team gets it too:
mkdir -p .claude/skills && cp -R /path/to/hepha-skill/skills/hepha .claude/skills/hepha
- Copy instead of symlink:
cp -R skills/hepha ~/.claude/skills/hepha. Claude Code also accepts symlinked skill folders in the personal and project locations.
- Guard rule (optional, recommended):
rules/hepha-guard.mdc restates the hard stops in a short form. For Claude Code, copy it to .claude/rules/hepha-guard.md. For Cursor, copy it to .cursor/rules/. For Codex, paste it into AGENTS.md.
- Skill paths in the docs:
<skill-root> in SKILL.md means wherever you installed skills/hepha, e.g. ~/.claude/skills/hepha.
2. Ask your agent to run it. The skill is never triggered implicitly. Invoke it explicitly: /hepha in Claude Code, $hepha in Codex.
/hepha Build CSV export for the orders page.
Use English for specs and summaries. Ask me before marking any task done.
The agent initialises .hepha/, writes the Spec and a validated backlog, then works one task per loop. It calls the CLI to record evidence and to request state changes.
3. Review what happened.
node ~/.claude/skills/hepha/scripts/hepha-server.js --root . --port 3000 # open http://localhost:3000
The server is read-only. It binds to 127.0.0.1 by default.
package.json already declares the hepha and hepha-server bins, and a tarball built with npm pack passes a smoke test. The package is not on npm yet. Once it is published, you will be able to run:
npx -p hepha-skill hepha init --root . --requirement "..." # one-off
npm i -g hepha-skill # or global: `hepha`, `hepha-server`
ln -s "$(npm root -g)/hepha-skill/skills/hepha" ~/.claude/skills/hepha
How it works
Each loop runs one ready task through:
SPEC → PLAN → RESEARCH → RED → GREEN → REGRESSION → REVIEW → SUMMARY → WIKI → COMMIT
- SPEC / PLAN: goals, non-goals, scenarios with stable IDs. Every task needs
spec_refs, Given/When/Then acceptance, risk, test_plan.commands and a knowledge.asset_policy. hepha validate checks the schema, the references and the dependency DAG.
- RESEARCH: only for a new tool, an architecture change, a security or migration risk, or a real multi-option choice. Trade-offs go into
decision-log.md.
- RED → GREEN → REGRESSION:
hepha record-check executes the command and stores the command, exit code and output. A RED run must fail.
- REVIEW: Spec review and code review are recorded separately, plus human approval by default. If the host allows sub-agents, they run in isolated contexts.
- SUMMARY / WIKI: a factual summary per task. Reusable conclusions become Wiki candidates and are published only after review and a secret scan.
- COMMIT: one small conventional commit per task, then the indexes are rebuilt and assets synced.
The gates
hepha transition enforces todo → doing → review → done (plus blocked/skipped) and checks evidence at every step:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
