by Ido-Levi
Semi-Structured Agentic Framework. Workflows build themselves as agents discover what needs to be done, not what you predicted upfront.
# Add to your Claude Code skills
git clone https://github.com/Ido-Levi/Hephaestus
What if AI workflows could write their own instructions as agents discover what needs to be done?
Quick Start • Documentation • Examples • Join our discord • Hephaestus Dev
https://github.com/user-attachments/assets/7b021611-2c09-494b-9da1-2ce05176dc51
Watch how Hephaestus coordinates multiple AI agents, monitors their trajectories, and builds workflows dynamically
Ready to use Hephaestus as a development tool? We've built Hephaestus Dev - a pre-configured setup with 5 production-ready workflows for software development:
| Workflow | What it does | |----------|--------------| | PRD to Software Builder | Build complete software from a Product Requirements Document | | Bug Fix | Analyze, fix, and verify bugs systematically | | Index Repository | Scan and index a codebase to build knowledge in memory | | Feature Development | Add features to existing codebases following patterns | | Documentation Generation | Generate comprehensive docs for existing codebases |
No comments yet. Be the first to share your thoughts!
python run_hephaestus_dev.py --path /path/to/project
I was trying to build a system where AI agents could handle complex software projects. You know the kind: "Build me an authentication system with OAuth, JWT, rate limiting, and comprehensive tests."
Traditional agentic frameworks can branch and loop, but they have a limitation: every branch needs predefined instructions. You must write the task descriptions upfront for every scenario you anticipate.
But what about discoveries you didn't anticipate? When a testing agent finds an optimization opportunity, a security issue, or a better architectural pattern?
Here's what I tried instead: Define logical phase types that are needed to solve problems - like "Plan → Implement → Test" - and let agents create tasks in ANY phase based on what they discover.
Instead of a rigid sequence, I set up phase types:
The key insight: Agents can spawn tasks in any phase they want.
A validation agent testing your auth system might discover an elegant caching pattern. Instead of being stuck (or following predefined branching logic you wrote), the agent:
The workflow just branched itself. Not because you predicted "if optimization found, spawn investigation task" - but because the agent discovered something worth exploring and had the freedom to create work for it.
This creates a branching tree of tasks that grows based on actual discoveries, not anticipated scenarios.
Let me show you what this looks like in practice:
I give Hephaestus a product requirements document: "Build a web application with authentication, REST API, and a React frontend."
Phase 1 agent reads the PRD and identifies 5 major components:
It spawns 5 Phase 2 tasks — one for each component. Now I have 5 agents building in parallel, each focused on one piece.
One of the Phase 2 agents finishes the REST API and spawns a Phase 3 validation task: "Test the REST API endpoints."
The Phase 3 agent starts testing. Everything passes. But then it notices something:
"The auth endpoints use a caching pattern that reduces database queries by 60%. This could speed up all API routes significantly."
Here's where it gets interesting.
The Phase 3 agent doesn't just log this observation and move on. It doesn't get stuck because there's no "investigate optimizations" in the workflow plan.
Instead, it spawns a new Phase 1 investigation task: "Analyze auth caching pattern — could apply to other API routes for major performance gain."
A new Phase 1 agent spawns, investigates the caching pattern, confirms it's viable, and spawns a Phase 2 implementation task: "Apply caching pattern to all API routes."
Another agent implements it. Another agent validates it.
The workflow just branched itself. No one planned for this optimization. An agent discovered it during testing and created new work to explore it.
Meanwhile, a different Phase 3 agent is testing the authentication component. Tests fail. So it spawns a Phase 2 bug fix task: "Fix auth token expiry validation — current implementation allows expired tokens."
The fix agent implements the solution and spawns Phase 3 retest: "Validate auth fixes."
Look at what emerged:
graph TB
P1[Phase 1: Analyze PRD<br/>Creates 5 tickets] --> P2A[Phase 2: Build Auth]
P1 --> P2B[Phase 2: Build API]
P1 --> P2C[Phase 2: Build Frontend]
P2B --> P3B[Phase 3: Test API]
P3B -->|discovers optimization| P1New[Phase 1: Investigate Caching<br/>NEW BRANCH]
P3B -->|testing continues| P3Done[API Validated]
P1New --> P2New[Phase 2: Implement Caching]
P2New --> P3New[Phase 3: Validate Optimization]
P2A --> P3A[Phase 3: Test Auth]
P3A -->|tests fail| P2Fix[Phase 2: Fix Auth Bug]
P2Fix --> P3Retest[Phase 3: Retest Auth]
style P3B fill:#fff3e0
style P1New fill:#e1f5fe
style P2Fix fill:#ffebee
This workflow built itself:
Traditional workflows: Predict every scenario upfront → rigid plan → breaks when reality diverges
Hephaestus approach: Define work types → agents discover → workflow adapts in real-time
The workflow adapts in real-time based on what agents actually discover, not what we predicted upfront.
Here's why this is "semi-structured" and why that matters:
Fully structured workflows (traditional frameworks):
Fully unstructured agents (chaos):
Semi-structured (Hephaestus):
You get structure where it matters:
And flexibility where you need it:
Before starting, validate that everything is installed and configured correctly:
python check_setup_macos.py
This script checks:
.env file