# Bhil Methodology

> AI-first development methodology with specification-driven artifact traceability. PRD → SPEC → ADR → TASK → CODE → REVIEW → DEPLOY pipeline with AI-native ADRs (model selection, prompt strategy, agent orchestration), LLM evaluation suites, guardrails specifications, and sprint-driven workflows. Optimised for Claude Code and Ruflo/RuVector. Use when you need SPEC/ADR/TASK artifact chain traceability, AI-native ADR categories, or sprint scaffolding.

- Skill: `dreamlab-ai/bhil-methodology` (Agent Skill, multi-file: 30 files)
- Install (CLI): `npx skillmds@latest add dreamlab-ai/bhil-methodology`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dreamlab-ai/bhil-methodology/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: dreamlab-ai (https://skillmd.com/u/dreamlab-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dreamlab-ai/bhil-methodology

---


# BHIL AI-First Development Methodology

Specification-driven development methodology where artifacts flow through a traceable chain: **PRD → SPEC → ADR → TASK → CODE → REVIEW → DEPLOY**, with retrospectives feeding back into planning.

Core premise: *The bottleneck in AI-assisted development is not code generation — it is specification quality.*

## When to Use This Skill

- **Starting a new feature**: "create a PRD for X", "scaffold a feature", "new feature"
- **Architecture decisions**: "should we use model X or Y", "document this decision"
- **Sprint planning**: "plan the next sprint", "break this into tasks"
- **AI-specific decisions**: model selection, prompt strategy, agent orchestration patterns
- **Quality gates**: evaluation suites, guardrails specs, artifact validation
- **Traceability**: "trace this bug back to requirements", "impact analysis"

## When Not to Use

- For single-file quick fixes — use direct editing
- For code quality/testing execution — use `build-with-quality` (complementary, not competing)
- For pure code review without methodology — use `code-review-quality` or `sherlock-review`
- For SEO content — use `toprank`

## Artifact Chain

```
PRD-NNN (Product Requirement)
  └── SPEC-NNN (Technical Specification)
        ├── ADR-NNN (Architecture Decision — standard, model, prompt, or agent)
        └── TASK-NNN (Implementable Work Unit)
              └── Sprint S-NN (Planned Execution)
                    └── Code + Review + Deploy
                          └── Retrospective → next PRD cycle
```

Every artifact carries YAML frontmatter with parent/child IDs for machine-actionable traceability.

## Templates

| Template | Purpose | ID Format |
|----------|---------|-----------|
| `PRD-TEMPLATE.md` | Product requirements document | PRD-NNN |
| `SPEC-TEMPLATE.md` | Technical specification | SPEC-NNN |
| `ADR-MODEL-SELECTION.md` | LLM model choice with benchmarks, cost, re-eval triggers | ADR-NNN |
| `ADR-PROMPT-STRATEGY.md` | Prompting approach, versioning, quality thresholds | ADR-NNN |
| `ADR-AGENT-ORCHESTRATION.md` | Agent architecture patterns (swarm, mesh, pipeline) | ADR-NNN |
| `TASK-TEMPLATE.md` | Implementable work unit with acceptance criteria | TASK-NNN |
| `SPRINT-PLAN-TEMPLATE.md` | Sprint planning with velocity and capacity | S-NN |
| `EVAL-SUITE-TEMPLATE.yaml` | LLM evaluation configuration | — |
| `GUARDRAILS-SPEC-TEMPLATE.md` | Safety and guardrails specification | — |
| `PROMPT-REGISTRY.md` | Prompt versioning and tracking | PV-NNN |

## Guides

| Guide | Content |
|-------|---------|
| `00-getting-started.md` | 5-minute setup |
| `01-methodology-overview.md` | Philosophy and principles |
| `03-sprint-workflow.md` | Step-by-step sprint execution |
| `04-context-management.md` | Preventing context fragmentation |
| `05-ai-native-patterns.md` | LLM-specific development patterns |
| `07-ruflo-ruvector-setup.md` | Ruflo/RuVector integration |

## Tools

Run from the skill directory (paths are skill-relative; the baked copy lives at `/opt/agentbox/skills/bhil-methodology/tools/`).

```bash
# Initialise a new project with BHIL structure
bash tools/init.sh

# Create a new ADR
bash tools/new-adr.sh "Adopt bge-small-en-v1.5 for RuVector embeddings"

# Validate all artifacts for completeness and traceability
bash tools/validate-artifacts.sh
```

## Integration with Other Skills

| Skill | Relationship |
|-------|-------------|
| `build-with-quality` | BWQ executes the code/test/review phases; BHIL provides the spec/ADR/traceability wrapper |
| `sparc-methodology` | SPARC's 5-phase model maps to BHIL's artifact chain (Spec=PRD+SPEC, Arch=ADR, Code=TASK) |
| `prd2build` | Generates docs from PRD; BHIL provides the PRD template and traceability |
| `wardley-maps` | Strategic analysis feeds into PRD and ADR context |
| `lazy-fetch` | Context management complements BHIL's context fragmentation prevention |

## Quality Framework

- **Specification quality** is the primary quality lever, not test coverage alone
- **Evaluation suites** (EVAL-SUITE-TEMPLATE.yaml) define LLM quality thresholds
- **Guardrails specs** separate safety concerns from functional requirements
- **Artifact validation** scripts check frontmatter completeness and link integrity
- **Retrospective feedback** closes the loop from deployment back to requirements

## Attribution

BHIL AI-First Development Toolkit by Barry Hurd (barryhurd.com). MIT License.