Stop vibe coding. Ship software that lasts.
Website • Quick Start • Roadmap • Changelog
HumanInLoop is a Claude Code plugin that enforces specification-driven development—ensuring architectural decisions are made by humans before AI writes code.
Instead of letting AI improvise your architecture, you guide it through a structured workflow:
Idea → Specification → Plan → Tasks → Implementation
Every step produces artifacts you can review, refine, and approve before moving forward.
┌──────────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─────────┐ ┌─────────┐ ┌──────┐ ┌───────┐ ┌───────────┐ │
│ │ SETUP │─▶│ SPECIFY │─▶│ PLAN │─▶│ TASKS │─▶│ IMPLEMENT │ │
│ └─────────┘ └─────────┘ └──────┘ └───────┘ └───────────┘ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌──────┐ ┌───────┐ ┌───────────┐ │
│ │ consti- │ │ spec │ │ 6 │ │ tasks │ │ code │ │
│ │ tution │ │ .md │ │ files│ │ .md │ │ changes │ │
│ └─────────┘ └─────────┘ └──────┘ └───────┘ └───────────┘ │
│ │ │ │ │ │ │
│ └────────────┴───────────┴──────────┴────────────┘ │
│ │ │
│ ┌─────▼─────┐ │
│ │ AUDIT │ │
│ │ (review) │ │
│ └───────────┘ │
│ │
│ ○────────○────────○────────○────────○ Human review checkpoints │
│ │
└──────────────────────────────────────────────────────────────────────────────────┘
| Stage | Command | What You Get |
|---|---|---|
| Setup | /humaninloop:setup |
Project constitution with your standards |
| Specify | /humaninloop:specify |
Structured spec with user stories and requirements |
| Plan | /humaninloop:plan |
Technical requirements, constraints, decisions, data models, API contracts |
| Tasks | /humaninloop:tasks |
Ordered task list with TDD cycles |
| Audit | /humaninloop:audit |
Quality analysis across all artifacts |
| Implement | /humaninloop:implement |
Guided implementation with progress tracking |
Each command produces artifacts you review before the next step. You stay in control.
Specify - Create feature specification (DAG-based)
┌─────────────────────────────────────────────────────────────────────┐
│ /humaninloop:specify │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ SUPERVISOR │ ◄─── You invoke the command │
│ └──────┬───────┘ │
│ │ ┌──────────────────┐ ┌──────────────────┐ │
│ ├─▶│ State Analyst │────▶│ briefing + │ │
│ │ │ (analysis + │ │ assembly + │ │
│ │ │ graph ops) │ │ recommendations │ │
│ │ └──────┬───────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ ┌──────────────────┐ ┌───────────────────┐ │
│ │ │ Requirements │────▶│ Devil's │ │
│ │ │ Analyst │ │ Advocate │ │
│ │ └────────┬─────────┘ └─────────┬─────────┘ │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ ┌─────────┐ ┌────────────────────┐ │
│ │ │ spec.md │ │ gaps? → new pass │ │
│ │ └─────────┘ └────────────────────┘ │
│ │ │
│ ▼ Deterministic DAG tracks all nodes, edges, and status │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ StrategyGraph JSON (single DAG, multi-pass iteration) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Output: specs/{feature}/spec.md + StrategyGraph JSON
Agents:
- State Analyst — Strategic analysis + graph mechanics; produces briefings, assembles nodes, freezes passes, and constructs domain agent prompts
- Requirements Analyst — Transforms feature requests into structured specs; no implementation details
- Devil's Advocate — Reviews for gaps and ambiguity; asks clarifying questions
Plan - Unified analysis and design planning
┌─────────────────────────────────────────────────────────────────────┐
│ /humaninloop:plan │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ SUPERVISOR │ ◄─── Reads spec.md │
│ └──────┬───────┘ │
│ │ │
│ ▼ Phase P1 (Analysis) │
│ ┌──────────────────┐ ┌───────────────────┐ ┌─────────────────┐ │
│ │ Technical │─▶│ Principal │─▶│ Devil's │ │
│ │ Analyst │ │ Architect │ │ Advocate │ │
│ └────────┬─────────┘ └───────────────────┘ └────────┬────────┘ │
│ │ (feasibility gate) │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌───────────────────┐ ┌─────────┐ ┌────────┐ │
│ │requirements │ │constraints-and- │ │ nfrs.md │ │ gaps? │ │
│ │ .md │ │ decisions.md │ │ │ └────────┘ │
│ └──────────────┘ └───────────────────┘ └─────────┘ │
│ │
│ │ Phase P2 (Design) │
│ ▼ │
│ ┌──────────────────┐ ┌─────────────────┐ │
│ │ Technical │────▶│ Devil's │ │
│ │ Analyst │ │ Advocate │ │
│ └────────┬─────────┘ └────────┬────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ data- │ │contracts/│ │quickstart│ │ gaps? │ │
│ │ model.md │ │ api.yaml │ │ .md │ └──────────┘ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ └──────────┴───────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ plan.md │ │
│ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Output: specs/{feature}/plan.md + 6 supporting artifacts
Agents:
- Technical Analyst — Produces analysis artifacts (requirements, constraints-and-decisions, NFRs) and design artifacts (data model, API contracts, integration guide)
- Principal Architect — Reviews cross-artifact feasibility after analysis phase (one-time gate)
- Devil's Advocate — Validates completeness, traceability, and cross-artifact consistency
Tasks - Generate implementation tasks
┌─────────────────────────────────────────────────────────────────────┐
│ /humaninloop:tasks │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ SUPERVISOR │ ◄─── Reads plan artifacts │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ ┌───────────────────┐ │
│ │ Task │────▶│ Devil's │ │
│ │ Architect │ │ Advocate │ │
│ └────────┬─────────┘ └─────────┬─────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────┐ ┌──────────┐ │
│ │ task-mapping.md│ │ gaps? │──── yes ──┐ │
│ └────────────────┘ └──────────┘ │ │
│ │ │ ▼ │
│ ▼ no ┌────────────┐ │
│ ┌──────────┐ │ │ clarify w/ │ │
│ │ tasks.md │ ▼ │ user │ │
│ └──────────┘ ┌──────────┐ └─────┬──────┘ │
│ │ done │ │ │
│ └──────────┘ ◄─────┘ (loop) │
│ │
└─────────────────────────────────────────────────────────────────────┘
Output: specs/{feature}/tasks.md with TDD cycles
Agents:
- Task Architect — Maps requirements to vertical slices with TDD structure; no implementation
- Devil's Advocate — Ensures coverage, proper ordering, and testable increments
Setup - Create project constitution
┌─────────────────────────────────────────────────────────────────────┐
│ /humaninloop:setup │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ SUPERVISOR │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ Brownfield? │
│ │ Detect Codebase │────────┬──────────────┐ │
│ └──────────────────┘ │ │ │
│ yes no │
│ │ │ │
│ ▼ │ │
│ ┌──────────────────┐ │ │
│ │ Principal │ │ │
│ │ Architect │ │ │
│ └────────┬─────────┘ │ │
│ │ │ │
│ ┌───────────────────┼───────────────┤ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────────┐ ┌────────────┐ │
│ │ codebase- │ │ constitution │ │constitution│ │
│ │analysis.md │ │ .md │ │ .md │ │
│ └────────────┘ └────────────────┘ └────────────┘ │
│ │ │ │
│ ▼ │ │
│ ┌────────────┐ │ │
│ │ evolution- │ │ │
│ │ roadmap.md │ │ │
│ └────────────┘ │ │
│ └───────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Output: .humaninloop/memory/constitution.md
Agents:
- Principal Architect — Defines governance principles and quality gates; enforces RFC 2119 keywords
Audit - Analyze artifacts for quality
┌─────────────────────────────────────────────────────────────────────┐
│ /humaninloop:audit │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ SUPERVISOR │ ◄─── No agents, direct analysis │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Load Artifacts │ │
│ │ spec.md │ plan.md │ tasks.md │ data-model │ contracts │ │
│ └──────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Spec │ │ Plan │ │ Task │ │
│ │ Analysis │ │ Validation│ │ Validation │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │ │ │ │
│ └───────────────────┴───────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Audit Report │ │
│ │ (stdout/file) │ │
│ └────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Output: Coverage report + flagged issues
Agents: None — direct analysis using validation skills
Implement - Execute the task plan
┌─────────────────────────────────────────────────────────────────────┐
│ /humaninloop:implement │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ SUPERVISOR │ ◄─── Reads tasks.md │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Foundation Cycles (Sequential) │ │
│ │ C1 ──▶ C2 ──▶ C3 ──▶ ... │ │
│ └──────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Feature Cycles (Can Parallel) │ │
│ │ C4 ──┬──▶ C5 │ │
│ │ └──▶ C6 [P] │ │
│ └──────────────────────────┬───────────────────────────────┘ │
│ │ │
│ For each cycle: │ │
│ ┌──────────────────────────┴───────────────────────────────┐ │
│ │ T1 (test) ──▶ T2 (impl) ──▶ T3 (impl) ──▶ Checkpoint │ │
│ │ │ │ │
│ │ ▼ (if TEST: marker) │ │
│ │ ┌─────────────────┐ │ │
│ │ │ QA Engineer │ ──▶ auto-approve or human checkpoint│ │
│ │ └─────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Output: Implemented code + marked tasks
Agents:
- QA Engineer — Executes verification tasks and captures evidence; auto-approves or presents checkpoints
The full specify → plan → tasks → implement lifecycle.
Claude automatically invokes these when relevant—authoring requirements, technical specifications, analyzing codebases, designing APIs, running verification tests, managing GitHub issues, workflow strategy, and more.
Focused responsibilities: requirements analyst, technical analyst, devil's advocate, principal architect, task architect, staff engineer, QA engineer, UI designer, state analyst.
See the plugin documentation for full details.
/plugin marketplace add deepeshBodh/human-in-loop/plugin install humaninloopuv tool install "humaninloop-brain @ git+https://github.com/deepeshBodh/human-in-loop.git#subdirectory=humaninloop_brain"Then configure the MCP server in your Claude Code settings (.claude/settings.json):
{
"mcpServers": {
"hil-dag": {
"command": "hil-dag"
}
}
}To upgrade to the latest version:
uv tool install --force "humaninloop-brain @ git+https://github.com/deepeshBodh/human-in-loop.git#subdirectory=humaninloop_brain"/humaninloop:setupThis creates your project constitution—the standards and conventions that guide all future specifications.
/humaninloop:specify add user authentication with email and password| Resource | Description |
|---|---|
| Roadmap | Vision and planned features |
| Changelog | Release history |
| Plugin README | Detailed command and skill reference |
This repository serves as a reference implementation for Claude Code plugins. If you're building your own plugins, you can learn from:
human-in-loop/
├── humaninloop_brain/ # Deterministic DAG infrastructure (Python)
│ ├── src/humaninloop_brain/ # Package source
│ │ ├── entities/ # Pydantic models (11 enums, 14 models)
│ │ ├── graph/ # NetworkX graph operations
│ │ ├── validators/ # Structural + contract validators
│ │ ├── passes/ # Pass lifecycle management
│ │ ├── mcp/ # MCP server + transport-agnostic operations
│ │ └── cli/ # CLI adapter (delegates to mcp/operations)
│ └── tests/ # 403 tests, ~95% coverage
├── plugins/humaninloop/
│ ├── .claude-plugin/plugin.json # Plugin manifest
│ ├── commands/ # Slash command definitions
│ ├── agents/ # 9 specialized agent definitions
│ ├── skills/ # 29 model-invoked skills
│ ├── catalogs/ # Node catalogs for DAG workflows
│ ├── templates/ # Workflow templates
│ └── scripts/ # Shell utilities
├── docs/
│ ├── decisions/ # Architecture Decision Records (8 ADRs)
│ ├── architecture/ # DAG-first + v3 architecture docs
│ ├── claude-plugin-documentation.md
│ └── agent-skills-documentation.md
└── specs/ # Feature specifications (dogfooding)
- Claude Code Plugin Documentation - Complete technical reference
- Agent Skills Documentation - How skills work
- Architecture Decisions - ADRs explaining design choices
See CONTRIBUTING.md for guidelines.
MIT - See LICENSE