Built before we called it a harness...
Enterprise work environments are often under strict business agreements and regulations (eg. SOC2) which makes adopting external tools off the shelf a difficult approval process. Cursor, Claude Code Desktop, and most other "harnesses" were restricted so I ended up having to write my own. FRACTAL was written in early 2026 (before we started calling these harnesses) out of necessity since most tools were restricted in strict work environments. You can check it out at github.com/shi503/fractal-agent-system.
The basic building blocks of FRACTAL:
Before loops and harness engineering, these were some of the basic necessities I needed for our AI-assisted workflow:
1. Separate agents for separate tasks.
Fractal comes with 4 tiers of agents and sub-agents but the key insight was to separate "planning" vs "implementation" agents. Strategist captures intent with the human. Architect decomposes into a blueprint and PRDs and never writes implementation. Feature Leads own one workstream, one file manifest, one build gate. Sub-agents do one atomic task and stop. Work and verification travel up and down the hierarchy via HANDOFFs and routing.
2. Deterministic orchestration.
Never trust an LLM for deterministic routing tasks. Flow control lives in router.py, not in a prompt. The router reads a YAML blueprint, tracks workstream state in .state.json, and returns what is allowed to run next. Agents do not get to decide on the graph.
3. Manage sub-agent delegation with context and evals.
FRACTAL is meant to be used by providing guides and the team's context as a config to planning agents which construct strict PRDs and TDD evals for each task at hand. This gives each coding agent exactly what it needs to know, what it can touch, and what tests must pass before it can move on.
4. Make the work observable.
FRACTAL mainly uses a HANDOFF.md to track all the acceptance criteria, tests, evals, and makes it easy to extend with artifacts such as screenshots (playwright) or other heuristics.
Whats next for FRACTAL?
As FRACTAL continued to grow, it followed many other integrations from modern harnesses such as a shared decision ledger, opinionated workspace setup, code review and PR management, and hooks with scheduling. However, onboarding and distributing to a team proved to be a mixed bag depending on each individual's usage of AI tools (some worked in narrow tab-completion bands and few worked from a feature end-to-end). Here's some other common headaches I ran into along the way:
Common mistakes from building your own harness:
- Haiku hallucinated on typed angular code, so sub-agents were upgraded to Sonnet mid-flight. Cost-model routing by default quickly transitioned to the complexity of the task.
- Agent overhead requires cache optimization and became an educational effort to help users understand that evolving aspects of context windows.
- Model judges produce false positives, so qual evals need sets of deterministic test cases and get checked at the PR gate by a human.
- Interactive sessions leave no trail. Run the pipeline by hand in one conversation and there is no PULSE, no HANDOFF, no escalation record. The harness only keeps its promise when the tiers run as agents. A caveat for users with multiple harnesses in their environments.
Now outside the restricted environment, it's time to see what other modern harness design has to offer. What was interesting about using FRACTAL with Claude Code was that it was quite self-conscious of it's shelf-life as our workflow continued getting absorbed into the Claude Code harness as the industry continued to converge on what a harness needs to become autonomous.
Outcomes
Published
Open source, MIT
Installed as a .claude folder. The router, four tier agents, eval templates and a fictional fixture project to run it against.
Used in production
Rules written after losses
Every rule in BEST-PRACTICES.md names the failure that produced it, from a pilot on a typed framework codebase.
Legible first, autonomous second
Published at github.com/shi503/fractal-agent-system.
