The Solo Developer Who Runs a Team

You give an AI coding tool a task. It builds something. But it built the wrong thing — or it asked you three clarifying questions mid-session — or it contradicted a decision you made last week. You fix it, start fresh, repeat. Sound familiar?

The bottleneck in AI-assisted development is not the AI's ability to write code. It is the quality of what you give it to read. A vague description produces vague code. An incomplete context produces code that makes plausible-sounding assumptions. A missing architectural decision produces a quick workaround that becomes permanent technical debt.

And there is a second, quieter problem: every time a new AI session starts, it begins with zero memory. By the third session on a feature, you have spent more time re-explaining context than the AI has spent building. Microsoft Research measured this: a 39% average performance drop from single-turn to multi-turn AI interactions — the quality cliff hits before you notice it.

The problem is not your AI. The problem is your documentation — or the lack of it. And the BHIL toolkit is the fix.

The problem

Barry Hurd Intelligence Lab's (BHIL) AI-First Development Toolkit is a GitHub template repository containing everything a solo developer needs to direct AI agents with precision: structured templates, step-by-step guides, Claude Code skills, validation scripts, and worked examples.

At its center is the artifact chain: a Product Requirements Document (PRD) captures what to build, a Technical Specification (SPEC) captures how to build it, an Architecture Decision Record (ADR) captures why this approach, and a TASK defines what specifically to implement this session — followed by code, review, and deploy.

When every link is filled, Claude Code — Anthropic's AI coding tool — can implement a feature from start to pull request with minimal human intervention. Every question it might ask is already answered in writing.

The toolkit ships as templates, step-by-step guides, Claude Code skills (on-demand workflow automations), validation scripts, and worked examples — all designed to work together as a cohesive system, not a collection of disconnected documents.

The big idea

Traditional development treats specification as overhead. The BHIL methodology inverts this: specification is the primary human activity, and code is the last-mile output.

Sean Grove's formulation makes this concrete: 'Discarding specs while keeping generated code is like compiling a JAR (a packaged Java executable) and checking in the binary while throwing away the source.' The BHIL toolkit applies this discipline — specifications are version-controlled, linked, and evolved with the same rigor as code.

Every question Claude Code asks during a session is documentation debt. The answer belongs in the artifact, not in the chat history. The BHIL retrospective process captures each gap and feeds it into higher-quality specs for the next sprint. The system compounds over time: the spec becomes progressively more accurate, the agent becomes progressively more autonomous.

Three AI-native decision record categories formalize choices that traditional projects never had to document: which large language model (LLM) to use, which prompting approach to take, and which agent orchestration pattern to deploy — each with evidence and rationale, before a line of code is written.

The aha

If an AI agent needs clarification during implementation, the specification failed.

A sprint is a 2-week cycle that produces a complete artifact chain for each feature. The phases run in parallel across features at different stages.

A feature begins as a PRD slice: user stories in EARS format (WHEN [trigger], the system SHALL [response]), quantified success metrics, and an explicit out-of-scope list. No implementation details — that is the SPEC's job.

The approved PRD generates a SPEC with Claude Code: API contracts, data models, component boundaries. For AI-powered features, the SPEC includes probabilistic acceptance criteria — not 'output matches expected value' but 'achieves ≥85% semantic similarity across 50 runs.' This is the correct specification model for non-deterministic systems.

Before the SPEC is approved, Architecture Decision Records are written: which language model, which prompting strategy, which agent orchestration pattern. These are immutable once accepted — changes require a new superseding ADR, creating a permanent decision audit trail.

The approved SPEC generates TASK files, each sized to fit within one Claude Code context window. Claude Code reads the TASK, writes tests first, implements until tests pass, creates a pull request, and writes a progress.md handoff file. The next session reads progress.md first — the only context carried between sessions, eliminating the 39% quality cliff of repeated re-explanation.

Architecture

Data flow

The methodology was commercially tested by Barry Hurd before being open-sourced as a GitHub template.

In the real world

Prerequisites: Claude Code (npm install -g @anthropic-ai/claude-code — Anthropic's AI coding tool), Node.js 18+, Git, GitHub account. Optionally RuFlo (npm install -g ruflo) for running multiple AI agents in parallel.

1. Use as GitHub template On GitHub, click 'Use this template' → 'Create a new repository'. You get a private copy with all guides, templates, and scripts already structured and linked. Clone it: git clone https://github.com/YOUR-USERNAME/YOUR-PROJECT.git
2. Initialize for your project Run: chmod +x tools/scripts/*.sh && ./tools/scripts/init.sh "My AI App" "TypeScript" "RAG chatbot for enterprise knowledge". You see: ✓ CLAUDE.md updated with your project details, ✓ First sprint folder created at project/sprints/S-01/, ✓ Pre-commit hooks installed.
3. Open Claude Code — it auto-loads everything Run: claude. Claude Code reads CLAUDE.md and loads all three skills (new-sprint, new-feature, new-adr) automatically. Type in the chat: 'Use the new-feature skill to create a PRD for [your feature name]'. The skill asks you 6 structured questions about scope, user, success metrics, and out-of-scope items.
4. Watch Claude Code implement and create the PR After you approve the generated artifacts, start an implementation session: 'Use TASK-001 to implement the feature.' Claude Code reads the TASK, writes tests (which initially fail), implements until all tests pass, opens a pull request, and writes a progress.md summary. You review the PR — a structured 20–30 minute checklist — and merge. Next sprint, the retrospective captures any specification gaps.

Every explainer ships with a downloadable AI knowledge pack — a portable vector knowledge base of this repo that any AI assistant can query locally, with zero cloud dependency. Drop it next to your AI tool and ask questions about the BHIL methodology in natural language.