Hepha

English | 中文

Turn large requirements into small, safe, continuously shippable tasks — through autonomous iterative delivery loops.

Features · Quick Start · How It Works · Workflow Demo · Documentation · Changelog

---

⭐ Why Hepha?

Tackles two core problems with AI coding:

1. AI goes rogue on large tasks — The bigger the requirement, the more unpredictable the output, often breaking things that worked fine

2. Humans get lazy — Relying on AI to write and fix everything erodes your own skills over time

Hepha fixes #1 with structured loop discipline, and #2 with a reflection mechanism.

---

Structured Loop: PLAN → EXECUTE → CHECK → REVIEW → COMMIT

• One minimal task per loop
• Must pass validation before commit
• Auto-corrects when going off track

Reflection Mechanism: Keep Your Edge

Every loop requires documented evidence:

• Why did we approach it this way?
• What did we research?
• What decisions were made? What was rejected?

These logs (.hepha/decision-log.md) are your assets. As AI gets smarter, so do you — Hepha ensures you're learning and growing, not just riding along.

"Less talk, show me code. Leave a trail." — Hepha's philosophy

What you get

• 🚀 Autonomous delivery — One prompt, continuous commits until done
• 🛡️ Risk-controlled — Each loop ships one minimal, validated task
• 📊 Visible progress — Real-time task graph and progress bar
• 🔍 Evidence-driven — Every commit requires checks + browser review
• 🔄 Self-correcting — Auto-replans when blocked, asks only when truly necessary
• ✍️ Sharp thinking — Forces you to document decisions and stay independent

---

Features

Feature	What it does
Auto-Decomposition	Breaks large requirements into validated task graphs with dependency tracking
Schema Validation	Forces complete task definitions with required fields (id, title, state, depends_on, acceptance, risk, files_hint)
Research Decision Matrix	Explicit rules: research only when truly needed (new lib, arch change, >2 options), skip for CRUD/bugfix/style
Decision Log	Forces documentation of research, trade-offs, and reasoning — your knowledge grows alongside AI
Progress Visualization	Live progress bars, status tables, and task dependency graphs in Markdown
Two-layer Control	Skill handles strategy; Rule enforces hard constraints and stop conditions
Deterministic Stop Policy	Stops on repeated failures or no executable tasks; reports blockers clearly

---

Quick Start

# 1. Clone or copy the skill into your Claude Code/OpenClaw skills directory
cp -r skills/hepha ~/.claude/skills/

# 2. Activate Hepha mode with a single prompt
Enable hepha mode.
Run loop: plan -> execute -> check -> review -> commit.
Continue until backlog is complete.
Requirement: <paste your requirement here>

That's it. Hepha will:

1. Analyze your requirement and auto-decompose it into a task graph
2. Execute one task at a time through the validated loop
3. Commit after each successful loop
4. Stop when all tasks are done or a stop condition is hit

---

How It Works

flowchart LR
    U[User Requirement] --> S[Skill Engine]
    S --> P[Auto-Decomposition]
    P --> T[Task Graph + Schema Validation]
    T --> E[Execute One Task]
    E --> C[Check: lint/test/build]
    C --> R[Review: browser validation]
    R --> V{Pass?}
    V -- No --> E
    V -- Yes --> G[Commit]
    G --> M{More Tasks?}
    M -- Yes --> E
    M -- No --> D[Delivery Summary]

    V -- Blocked --> B[Auto-Replan]
    B --> P

Loading

The Loop: PLAN → EXECUTE → CHECK → REVIEW → COMMIT

1. PLAN

• Auto-Decomposition: If no backlog exists, automatically break down requirements into tasks using patterns (CRUD, Authentication, UI Components, API Integration)
• Schema Validation: Every task must have: id, title, state, depends_on, acceptance, risk, files_hint
• Select Task: Pick from ready queue (all dependencies done)

2. RESEARCH

Research is ONLY required for:

• ✅ New library/framework/tool
• ✅ Architecture changes
• ✅ Implementation uncertainty (>2 options)
• ❌ NOT for: CRUD, bug fixes, style changes

3. EXECUTE

• Keep changes focused on required files only
• Avoid speculative refactors
• Keep functions small and reusable

4. CHECK

Run all relevant project checks:

lint → tests → build/typecheck

Fix and retry until pass.

5. REVIEW (For UI/flow changes)

Use MCP browser tools or Playwright to validate:

• Page load success
• Key interaction path works
• Expected state is visible

6. COMMIT

Commit only when:

• ✅ checks passed
• ✅ review passed
• ✅ acceptance criteria met

---

Workflow Demo

Before & After

Without Hepha	With Hepha
One big prompt, unpredictable output	One prompt, structured autonomous loops
No visibility into progress	Real-time task graph + progress bar
Large, risky commits	Small, validated commits after each loop
Goes off rails easily	Auto-replans when blocked
No evidence of quality	Every commit has check + review evidence

Live Progress Example

Overall Progress: [████████░░] 80% (4/5 tasks complete)

Status Summary:
| Status        | Count | Tasks                            |
|---------------|-------|----------------------------------|
| ✅ Done        | 4     | TASK-001, 002, 004, 005          |
| 🔄 In Progress| 1     | TASK-003                         |
| ⏳ Todo        | 0     | -                                |
| 🚫 Blocked    | 0     | -                                |

Task Dependency Graph:
TASK-001 (✅) ──► TASK-002 (✅) ──► TASK-003 (🔄)
     │
     └──────────────► TASK-004 (✅)

Usage Example

# Prompt:
Enable hepha mode.
Run autonomous loops until complete.
Requirement: Implement user authentication with JWT.

The skill will:

1. Auto-decompose into 4-6 tasks (e.g., TASK-001: DB schema, TASK-002: auth middleware, TASK-003: login API, TASK-004: frontend login form, TASK-005: JWT validation)
2. Execute each task through the validated loop
3. Commit after each successful loop
4. Stop when complete or blocked

---

Project Structure

skills/hepha/
├── SKILL.md                           # Main skill definition (for Claude Code/OpenClaw)
├── references/                        # Documentation
│   ├── decomposition-patterns.md      # Task breakdown patterns
│   ├── planning_task-decomposition.md # Task schema reference
│   ├── progress-template.md           # Progress visualization guide
│   └── validation_quality-gates.md    # Quality gate definitions
└── templates/                         # Runtime file templates
    ├── backlog.md.template             # Task graph template
    ├── progress.md.template           # Progress log template
    └── decision-log.md.template        # Research log template

Runtime Artifacts

Hepha creates and maintains these files in your project's .hepha/ directory:

File	Purpose
backlog.md	Task graph with states, dependencies, and risk levels
progress.md	Per-loop execution log with evidence and progress visualization
decision-log.md	Research and technical decisions with trade-off analysis

---

Technical Approach

• Two-layer control model
  • Skill handles strategy and execution orchestration
  • Rule enforces hard constraints and stop conditions
• Small-batch delivery: Each loop handles one minimal sub-task — no "big-bang" refactors
• Evidence-driven quality: Every loop includes verification output; commit only after check + review pass
• Deterministic stop policy: Stop after repeated failures or no executable tasks; report blockers and current state

Scope and Non-goals

• ✅ This is an execution protocol for autonomous coding
• ✅ Optimizes continuous delivery speed under controlled risk
• ❌ Does NOT replace product decisions when requirements conflict
• ❌ Is NOT a full external workflow scheduler

---

Documentation

• Skill Definition
• Decomposition Patterns
• Progress Visualization Guide
• Quality Gates
• ClawHub Listing

---

Changelog

v1.0.0 (2026-03-28)

• Initial release
• Auto-decomposition with task graph generation
• PLAN → EXECUTE → CHECK → REVIEW → COMMIT loop
• Schema validation for all tasks
• Research decision matrix
• Progress visualization with Markdown bars and dependency graphs
• Runtime artifacts: backlog.md, progress.md, decision-log.md
• Dual language support (English + 中文)

---

License

MIT

Hepha — Built for developers who believe in evidence over promises.