{"id":35562185,"url":"https://github.com/deepeshbodh/human-in-loop","last_synced_at":"2026-04-01T16:53:51.565Z","repository":{"id":331240512,"uuid":"1125832098","full_name":"deepeshBodh/human-in-loop","owner":"deepeshBodh","description":"SPEC-first multi-agent framework for Claude Code.","archived":false,"fork":false,"pushed_at":"2026-01-21T07:45:27.000Z","size":927,"stargazers_count":7,"open_issues_count":10,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-21T19:06:21.285Z","etag":null,"topics":["ai-agents","claude-code","spec-driven-development"],"latest_commit_sha":null,"homepage":"https://www.humaninloop.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deepeshBodh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-31T13:01:30.000Z","updated_at":"2026-01-21T07:45:22.000Z","dependencies_parsed_at":"2026-01-05T09:02:16.347Z","dependency_job_id":null,"html_url":"https://github.com/deepeshBodh/human-in-loop","commit_stats":null,"previous_names":["deepeshbodh/human-in-loop-marketplace"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/deepeshBodh/human-in-loop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepeshBodh%2Fhuman-in-loop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepeshBodh%2Fhuman-in-loop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepeshBodh%2Fhuman-in-loop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepeshBodh%2Fhuman-in-loop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deepeshBodh","download_url":"https://codeload.github.com/deepeshBodh/human-in-loop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepeshBodh%2Fhuman-in-loop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28750639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T09:00:19.176Z","status":"ssl_error","status_checked_at":"2026-01-25T09:00:04.131Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","spec-driven-development"],"created_at":"2026-01-04T13:10:17.665Z","updated_at":"2026-04-01T16:53:51.553Z","avatar_url":"https://github.com/deepeshBodh.png","language":"Python","readme":"# HumanInLoop\n\n**Stop vibe coding. Ship software that lasts.**\n\n[Website](https://humaninloop.dev) • [Quick Start](#quick-start) • [Roadmap](./ROADMAP.md) • [Changelog](./CHANGELOG.md)\n\n---\n\n## What is HumanInLoop?\n\nHumanInLoop is a Claude Code plugin that enforces **specification-driven development**—ensuring architectural decisions are made by humans before AI writes code.\n\nInstead of letting AI improvise your architecture, you guide it through a structured workflow:\n\n```\nIdea → Specification → Plan → Tasks → Implementation\n```\n\nEvery step produces artifacts you can review, refine, and approve before moving forward.\n\n---\n\n## The Workflow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────────┐\n│                                                                                  │\n│  ┌─────────┐  ┌─────────┐  ┌──────┐  ┌───────┐  ┌───────────┐                   │\n│  │  SETUP  │─▶│ SPECIFY │─▶│ PLAN │─▶│ TASKS │─▶│ IMPLEMENT │                   │\n│  └─────────┘  └─────────┘  └──────┘  └───────┘  └───────────┘                   │\n│       │            │           │          │            │                         │\n│       ▼            ▼           ▼          ▼            ▼                         │\n│  ┌─────────┐  ┌─────────┐  ┌──────┐  ┌───────┐  ┌───────────┐                   │\n│  │ consti- │  │  spec   │  │ 6    │  │ tasks │  │   code    │                   │\n│  │ tution  │  │   .md   │  │ files│  │  .md  │  │  changes  │                   │\n│  └─────────┘  └─────────┘  └──────┘  └───────┘  └───────────┘                   │\n│       │            │           │          │            │                         │\n│       └────────────┴───────────┴──────────┴────────────┘                         │\n│                                    │                                             │\n│                              ┌─────▼─────┐                                       │\n│                              │   AUDIT   │                                       │\n│                              │  (review) │                                       │\n│                              └───────────┘                                       │\n│                                                                                  │\n│  ○────────○────────○────────○────────○  Human review checkpoints                │\n│                                                                                  │\n└──────────────────────────────────────────────────────────────────────────────────┘\n```\n\n| Stage | Command | What You Get |\n|-------|---------|--------------|\n| **Setup** | `/humaninloop:setup` | Project constitution with your standards |\n| **Specify** | `/humaninloop:specify` | Structured spec with user stories and requirements |\n| **Plan** | `/humaninloop:plan` | Technical requirements, constraints, decisions, data models, API contracts |\n| **Tasks** | `/humaninloop:tasks` | Ordered task list with TDD cycles |\n| **Audit** | `/humaninloop:audit` | Quality analysis across all artifacts |\n| **Implement** | `/humaninloop:implement` | Guided implementation with progress tracking |\n\nEach command produces artifacts you review before the next step. You stay in control.\n\n### Command Details\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eSpecify\u003c/strong\u003e - Create feature specification (DAG-based)\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                         /humaninloop:specify                        │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌──────────────┐                                                   │\n│  │  SUPERVISOR  │ ◄─── You invoke the command                       │\n│  └──────┬───────┘                                                   │\n│         │  ┌──────────────────┐     ┌──────────────────┐            │\n│         ├─▶│  State Analyst   │────▶│  briefing +      │            │\n│         │  │  (analysis +     │     │  assembly +      │            │\n│         │  │   graph ops)     │     │  recommendations │            │\n│         │  └──────┬───────────┘     └────────┬─────────┘            │\n│         │         │                          │                      │\n│         │         ▼                          ▼                      │\n│         │  ┌──────────────────┐     ┌───────────────────┐           │\n│         │  │   Requirements   │────▶│   Devil's         │           │\n│         │  │   Analyst        │     │   Advocate        │           │\n│         │  └────────┬─────────┘     └─────────┬─────────┘           │\n│         │           │                         │                     │\n│         │           ▼                         ▼                     │\n│         │      ┌─────────┐         ┌────────────────────┐           │\n│         │      │ spec.md │         │ gaps? → new pass   │           │\n│         │      └─────────┘         └────────────────────┘           │\n│         │                                                           │\n│         ▼  Deterministic DAG tracks all nodes, edges, and status    │\n│  ┌──────────────────────────────────────────────────────────┐       │\n│  │  StrategyGraph JSON  (single DAG, multi-pass iteration)  │       │\n│  └──────────────────────────────────────────────────────────┘       │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**Output**: `specs/{feature}/spec.md` + StrategyGraph JSON\n\n**Agents**:\n- **State Analyst** — Strategic analysis + graph mechanics; produces briefings, assembles nodes, freezes passes, and constructs domain agent prompts\n- **Requirements Analyst** — Transforms feature requests into structured specs; no implementation details\n- **Devil's Advocate** — Reviews for gaps and ambiguity; asks clarifying questions\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePlan\u003c/strong\u003e - Unified analysis and design planning\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                          /humaninloop:plan                          │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌──────────────┐                                                   │\n│  │  SUPERVISOR  │ ◄─── Reads spec.md                                │\n│  └──────┬───────┘                                                   │\n│         │                                                           │\n│         ▼                Phase P1 (Analysis)                       │\n│  ┌──────────────────┐  ┌───────────────────┐  ┌─────────────────┐   │\n│  │   Technical      │─▶│   Principal       │─▶│   Devil's       │   │\n│  │   Analyst        │  │   Architect       │  │   Advocate      │   │\n│  └────────┬─────────┘  └───────────────────┘  └────────┬────────┘   │\n│           │            (feasibility gate)               │           │\n│           ▼                                            ▼           │\n│  ┌──────────────┐ ┌───────────────────┐ ┌─────────┐ ┌────────┐     │\n│  │requirements  │ │constraints-and-   │ │ nfrs.md │ │ gaps?  │     │\n│  │    .md       │ │  decisions.md     │ │         │ └────────┘     │\n│  └──────────────┘ └───────────────────┘ └─────────┘                │\n│                                                                     │\n│         │                Phase P2 (Design)                         │\n│         ▼                                                           │\n│  ┌──────────────────┐     ┌─────────────────┐                       │\n│  │   Technical      │────▶│   Devil's       │                       │\n│  │   Analyst        │     │   Advocate      │                       │\n│  └────────┬─────────┘     └────────┬────────┘                       │\n│           │                        │                               │\n│           ▼                       ▼                               │\n│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐               │\n│  │  data-   │ │contracts/│ │quickstart│ │  gaps?   │               │\n│  │ model.md │ │ api.yaml │ │   .md    │ └──────────┘               │\n│  └──────────┘ └──────────┘ └──────────┘                             │\n│           │          │           │                                  │\n│           └──────────┴───────────┘                                  │\n│                      │                                              │\n│                      ▼                                              │\n│                ┌──────────┐                                         │\n│                │ plan.md  │                                         │\n│                └──────────┘                                         │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**Output**: `specs/{feature}/plan.md` + 6 supporting artifacts\n\n**Agents**:\n- **Technical Analyst** — Produces analysis artifacts (requirements, constraints-and-decisions, NFRs) and design artifacts (data model, API contracts, integration guide)\n- **Principal Architect** — Reviews cross-artifact feasibility after analysis phase (one-time gate)\n- **Devil's Advocate** — Validates completeness, traceability, and cross-artifact consistency\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTasks\u003c/strong\u003e - Generate implementation tasks\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                         /humaninloop:tasks                          │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌──────────────┐                                                   │\n│  │  SUPERVISOR  │ ◄─── Reads plan artifacts                         │\n│  └──────┬───────┘                                                   │\n│         │                                                           │\n│         ▼                                                           │\n│  ┌──────────────────┐     ┌───────────────────┐                     │\n│  │     Task         │────▶│   Devil's         │                     │\n│  │     Architect    │     │   Advocate        │                     │\n│  └────────┬─────────┘     └─────────┬─────────┘                     │\n│           │                         │                               │\n│           ▼                         ▼                               │\n│  ┌────────────────┐          ┌──────────┐                           │\n│  │ task-mapping.md│          │  gaps?   │──── yes ──┐               │\n│  └────────────────┘          └──────────┘           │               │\n│           │                       │                 ▼               │\n│           ▼                      no          ┌────────────┐         │\n│     ┌──────────┐                  │          │ clarify w/ │         │\n│     │ tasks.md │                  ▼          │    user    │         │\n│     └──────────┘            ┌──────────┐     └─────┬──────┘         │\n│                             │   done   │           │                │\n│                             └──────────┘     ◄─────┘ (loop)         │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**Output**: `specs/{feature}/tasks.md` with TDD cycles\n\n**Agents**:\n- **Task Architect** — Maps requirements to vertical slices with TDD structure; no implementation\n- **Devil's Advocate** — Ensures coverage, proper ordering, and testable increments\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSetup\u003c/strong\u003e - Create project constitution\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                         /humaninloop:setup                          │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌──────────────┐                                                   │\n│  │  SUPERVISOR  │                                                   │\n│  └──────┬───────┘                                                   │\n│         │                                                           │\n│         ▼                                                           │\n│  ┌──────────────────┐     Brownfield?                               │\n│  │ Detect Codebase  │────────┬──────────────┐                       │\n│  └──────────────────┘        │              │                       │\n│                             yes             no                      │\n│                              │              │                       │\n│                              ▼              │                       │\n│                    ┌──────────────────┐     │                       │\n│                    │    Principal     │     │                       │\n│                    │    Architect     │     │                       │\n│                    └────────┬─────────┘     │                       │\n│                             │               │                       │\n│         ┌───────────────────┼───────────────┤                       │\n│         ▼                   ▼               ▼                       │\n│  ┌────────────┐    ┌────────────────┐  ┌────────────┐               │\n│  │  codebase- │    │  constitution  │  │constitution│               │\n│  │analysis.md │    │     .md        │  │    .md     │               │\n│  └────────────┘    └────────────────┘  └────────────┘               │\n│         │                   │                                       │\n│         ▼                   │                                       │\n│  ┌────────────┐             │                                       │\n│  │ evolution- │             │                                       │\n│  │ roadmap.md │             │                                       │\n│  └────────────┘             │                                       │\n│         └───────────────────┘                                       │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**Output**: `.humaninloop/memory/constitution.md`\n\n**Agents**:\n- **Principal Architect** — Defines governance principles and quality gates; enforces RFC 2119 keywords\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAudit\u003c/strong\u003e - Analyze artifacts for quality\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                         /humaninloop:audit                          │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌──────────────┐                                                   │\n│  │  SUPERVISOR  │ ◄─── No agents, direct analysis                   │\n│  └──────┬───────┘                                                   │\n│         │                                                           │\n│         ▼                                                           │\n│  ┌──────────────────────────────────────────────────────────┐       │\n│  │                    Load Artifacts                         │       │\n│  │  spec.md │ plan.md │ tasks.md │ data-model │ contracts   │       │\n│  └──────────────────────────┬───────────────────────────────┘       │\n│                             │                                       │\n│         ┌───────────────────┼───────────────────┐                   │\n│         ▼                   ▼                   ▼                   │\n│  ┌────────────┐      ┌────────────┐      ┌────────────┐             │\n│  │   Spec     │      │   Plan     │      │   Task     │             │\n│  │  Analysis  │      │  Validation│      │ Validation │             │\n│  └────────────┘      └────────────┘      └────────────┘             │\n│         │                   │                   │                   │\n│         └───────────────────┴───────────────────┘                   │\n│                             │                                       │\n│                             ▼                                       │\n│                    ┌────────────────┐                               │\n│                    │  Audit Report  │                               │\n│                    │ (stdout/file)  │                               │\n│                    └────────────────┘                               │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**Output**: Coverage report + flagged issues\n\n**Agents**: None — direct analysis using validation skills\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eImplement\u003c/strong\u003e - Execute the task plan\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                       /humaninloop:implement                        │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ┌──────────────┐                                                   │\n│  │  SUPERVISOR  │ ◄─── Reads tasks.md                               │\n│  └──────┬───────┘                                                   │\n│         │                                                           │\n│         ▼                                                           │\n│  ┌──────────────────────────────────────────────────────────┐       │\n│  │               Foundation Cycles (Sequential)              │       │\n│  │   C1 ──▶ C2 ──▶ C3 ──▶ ...                               │       │\n│  └──────────────────────────┬───────────────────────────────┘       │\n│                             │                                       │\n│                             ▼                                       │\n│  ┌──────────────────────────────────────────────────────────┐       │\n│  │                Feature Cycles (Can Parallel)              │       │\n│  │   C4 ──┬──▶ C5                                           │       │\n│  │        └──▶ C6 [P]                                       │       │\n│  └──────────────────────────┬───────────────────────────────┘       │\n│                             │                                       │\n│  For each cycle:            │                                       │\n│  ┌──────────────────────────┴───────────────────────────────┐       │\n│  │  T1 (test) ──▶ T2 (impl) ──▶ T3 (impl) ──▶ Checkpoint    │       │\n│  │       │                                                   │       │\n│  │       ▼ (if TEST: marker)                                │       │\n│  │  ┌─────────────────┐                                     │       │\n│  │  │   QA Engineer   │ ──▶ auto-approve or human checkpoint│       │\n│  │  └─────────────────┘                                     │       │\n│  └──────────────────────────────────────────────────────────┘       │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**Output**: Implemented code + marked tasks\n\n**Agents**:\n- **QA Engineer** — Executes verification tasks and captures evidence; auto-approves or presents checkpoints\n\n\u003c/details\u003e\n\n---\n\n## What's Included\n\n### 6 Commands\nThe full specify → plan → tasks → implement lifecycle.\n\n### 29 Skills\nClaude automatically invokes these when relevant—authoring requirements, technical specifications, analyzing codebases, designing APIs, running verification tests, managing GitHub issues, workflow strategy, and more.\n\n### 9 Specialized Agents\nFocused responsibilities: requirements analyst, technical analyst, devil's advocate, principal architect, task architect, staff engineer, QA engineer, UI designer, state analyst.\n\nSee the [plugin documentation](./plugins/humaninloop/README.md) for full details.\n\n---\n\n## Quick Start\n\n### 1. Add the marketplace\n\n```bash\n/plugin marketplace add deepeshBodh/human-in-loop\n```\n\n### 2. Install the plugin\n\n```bash\n/plugin install humaninloop\n```\n\n### 3. Install and configure the `hil-dag` MCP server (required for specify and implement)\n\n```bash\nuv tool install \"humaninloop-brain @ git+https://github.com/deepeshBodh/human-in-loop.git#subdirectory=humaninloop_brain\"\n```\n\nThen configure the MCP server in your Claude Code settings (`.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"hil-dag\": {\n      \"command\": \"hil-dag\"\n    }\n  }\n}\n```\n\n**To upgrade to the latest version:**\n\n```bash\nuv tool install --force \"humaninloop-brain @ git+https://github.com/deepeshBodh/human-in-loop.git#subdirectory=humaninloop_brain\"\n```\n\n### 4. Set up your project\n\n```bash\n/humaninloop:setup\n```\n\nThis creates your project constitution—the standards and conventions that guide all future specifications.\n\n### 5. Create your first spec\n\n```bash\n/humaninloop:specify add user authentication with email and password\n```\n\n---\n\n## Documentation\n\n| Resource | Description |\n|----------|-------------|\n| [Roadmap](./ROADMAP.md) | Vision and planned features |\n| [Changelog](./CHANGELOG.md) | Release history |\n| [Plugin README](./plugins/humaninloop/README.md) | Detailed command and skill reference |\n\n---\n\n## For Plugin Developers\n\nThis repository serves as a reference implementation for Claude Code plugins. If you're building your own plugins, you can learn from:\n\n### Repository Structure\n\n```\nhuman-in-loop/\n├── humaninloop_brain/                # Deterministic DAG infrastructure (Python)\n│   ├── src/humaninloop_brain/        # Package source\n│   │   ├── entities/                 # Pydantic models (11 enums, 14 models)\n│   │   ├── graph/                    # NetworkX graph operations\n│   │   ├── validators/               # Structural + contract validators\n│   │   ├── passes/                   # Pass lifecycle management\n│   │   ├── mcp/                      # MCP server + transport-agnostic operations\n│   │   └── cli/                      # CLI adapter (delegates to mcp/operations)\n│   └── tests/                        # 403 tests, ~95% coverage\n├── plugins/humaninloop/\n│   ├── .claude-plugin/plugin.json    # Plugin manifest\n│   ├── commands/                     # Slash command definitions\n│   ├── agents/                       # 9 specialized agent definitions\n│   ├── skills/                       # 29 model-invoked skills\n│   ├── catalogs/                     # Node catalogs for DAG workflows\n│   ├── templates/                    # Workflow templates\n│   └── scripts/                      # Shell utilities\n├── docs/\n│   ├── decisions/                    # Architecture Decision Records (8 ADRs)\n│   ├── architecture/                 # DAG-first + v3 architecture docs\n│   ├── claude-plugin-documentation.md\n│   └── agent-skills-documentation.md\n└── specs/                            # Feature specifications (dogfooding)\n```\n\n### Key Resources\n\n- [Claude Code Plugin Documentation](./docs/claude-plugin-documentation.md) - Complete technical reference\n- [Agent Skills Documentation](./docs/agent-skills-documentation.md) - How skills work\n- [Architecture Decisions](./docs/decisions/) - ADRs explaining design choices\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n---\n\n## License\n\nMIT - See [LICENSE](./LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepeshbodh%2Fhuman-in-loop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepeshbodh%2Fhuman-in-loop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepeshbodh%2Fhuman-in-loop/lists"}