{"id":29942788,"url":"https://github.com/vanzan01/claude-code-sub-agent-collective","last_synced_at":"2025-08-18T02:08:31.031Z","repository":{"id":297947213,"uuid":"997410148","full_name":"vanzan01/claude-code-sub-agent-collective","owner":"vanzan01","description":"  🧠 Context Engineering Research - Not just another agent collection, but using research and context engineering to function as a collective. Hub-and-spoke coordination through Claude   Code.","archived":false,"fork":false,"pushed_at":"2025-08-17T04:06:54.000Z","size":3222,"stargazers_count":119,"open_issues_count":1,"forks_count":14,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-08-18T02:02:03.900Z","etag":null,"topics":["agents","ai-development","autonomous-programming","claude","claude-code","context-engineering","multi-agent","playwright","sub-agents","task-master","taskmaster","yolo"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/vanzan01.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":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-06T13:34:09.000Z","updated_at":"2025-08-17T18:08:25.000Z","dependencies_parsed_at":"2025-08-18T02:01:49.631Z","dependency_job_id":null,"html_url":"https://github.com/vanzan01/claude-code-sub-agent-collective","commit_stats":null,"previous_names":["vanzan01/taskmaster-agent-claude-code"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vanzan01/claude-code-sub-agent-collective","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanzan01%2Fclaude-code-sub-agent-collective","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanzan01%2Fclaude-code-sub-agent-collective/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanzan01%2Fclaude-code-sub-agent-collective/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanzan01%2Fclaude-code-sub-agent-collective/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vanzan01","download_url":"https://codeload.github.com/vanzan01/claude-code-sub-agent-collective/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanzan01%2Fclaude-code-sub-agent-collective/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270932698,"owners_count":24670250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agents","ai-development","autonomous-programming","claude","claude-code","context-engineering","multi-agent","playwright","sub-agents","task-master","taskmaster","yolo"],"created_at":"2025-08-03T02:03:19.035Z","updated_at":"2025-08-18T02:08:31.022Z","avatar_url":"https://github.com/vanzan01.png","language":"JavaScript","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# Claude Code Sub-Agent Collective\n\n[![npm version](https://badge.fury.io/js/claude-code-collective.svg)](https://badge.fury.io/js/claude-code-collective)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Experimental NPX installer for TDD-focused AI agents**\n\nThis installs a collection of AI agents designed for Test-Driven Development and rapid prototyping. It's experimental, opinionated, and I built it to speed up my own MVP development work.\n\n## What this installs\n\n```bash\nnpx claude-code-collective init\n```\n\nYou get 30+ specialized agents that enforce TDD methodology and try to be smarter about using real documentation instead of guessing.\n\n## Why this exists\n\nI got tired of:\n- AI giving me code without tests\n- Having to manually look up library documentation\n- Inconsistent development approaches across projects\n- Breaking down complex features manually\n\nSo I built agents that:\n1. Write tests first, always (RED → GREEN → REFACTOR)\n2. Use Context7 to pull real documentation\n3. Route work to specialists based on what needs doing\n4. Break down complex requests intelligently\n\n## What you get after installation\n\n### Core Implementation Agents (TDD-enforced)\n- **@component-implementation-agent** - UI components with tests and modern patterns\n- **@feature-implementation-agent** - Business logic with comprehensive testing\n- **@infrastructure-implementation-agent** - Build systems with testing setup\n- **@testing-implementation-agent** - Test suites that actually test things\n- **@polish-implementation-agent** - Performance optimization with preserved tests\n\n### Quality \u0026 Validation\n- **@quality-agent** - Code review and standards checking\n- **@devops-agent** - Deployment and CI/CD setup\n- **@functional-testing-agent** - Browser testing with Playwright\n- **@enhanced-quality-gate** - Comprehensive validation gates\n- **@completion-gate** - Task validation and completion checks\n\n### Research \u0026 Intelligence (Experimental)\n- **@research-agent** - Context7-powered documentation lookup\n- **@prd-research-agent** - Intelligent requirement breakdown\n- **@task-orchestrator** - Smart task parallelization\n\n### System \u0026 Coordination\n- **`/van` command** - Entry point that routes to @task-orchestrator\n- **@task-orchestrator** - Central routing hub that picks the right specialist\n- **@behavioral-transformation-agent** - System behavioral setup\n- **@hook-integration-agent** - TDD enforcement automation\n- **@van-maintenance-agent** - System maintenance and updates\n\n**Plus 20+ other specialized agents** for specific development tasks.\n\n## Installation options\n\n### Quick install (recommended for trying it out)\n```bash\nnpx claude-code-collective init\n```\n\n### Other options if you want to be selective\n```bash\n# Just core agents for lightweight projects\nnpx claude-code-collective init --minimal\n\n# Focus on testing framework only\nnpx claude-code-collective init --testing-only\n\n# Just the behavioral system and hooks\nnpx claude-code-collective init --hooks-only\n\n# Interactive setup with choices\nnpx claude-code-collective init --interactive\n```\n\n## What actually gets installed\n\n```\nyour-project/\n├── CLAUDE.md                    # Behavioral rules for agents\n├── .claude/\n│   ├── settings.json           # Hook configuration\n│   ├── agents/                 # Agent definitions (30+ files)\n│   │   ├── prd-research-agent.md\n│   │   ├── task-orchestrator.md\n│   │   ├── lib/\n│   │   │   └── research-analyzer.js  # Complexity analysis engine\n│   │   └── ... (lots more agents)\n│   └── hooks/                  # TDD enforcement scripts\n│       ├── test-driven-handoff.sh\n│       └── collective-metrics.sh\n└── .claude-collective/\n    ├── tests/                  # Test framework templates\n    ├── metrics/                # Usage tracking (for development)\n    └── package.json           # Testing setup (Vitest)\n```\n\n## How it works\n\n1. **`/van` command** routes to **@task-orchestrator** (the routing hub) which analyzes requests and delegates to specialists\n2. **Research phase** - agents use Context7 for real documentation  \n3. **Tests written first** - before any implementation\n4. **Implementation** - minimal code to make tests pass\n5. **Refactoring** - clean up while keeping tests green\n6. **Delivery** - you see what tests were added and results\n\n### The TDD contract every agent follows\n\n```\n## DELIVERY COMPLETE\n✅ Tests written first (RED phase)\n✅ Implementation passes tests (GREEN phase)\n✅ Code refactored for quality (REFACTOR phase)\n📊 Test Results: X/X passing\n```\n\n## Management commands\n\n```bash\n# Check what's installed and working\nnpx claude-code-collective status\n\n# Validate installation integrity\nnpx claude-code-collective validate\n\n# Fix broken installations\nnpx claude-code-collective repair\n\n# Remove everything\nnpx claude-code-collective clean\n\n# Get help\nnpx claude-code-collective --help\n```\n\n## Current state (honest assessment)\n\n### What works well\n- TDD enforcement prevents a lot of bugs\n- Context7 integration is much better than agents guessing\n- Routing usually picks the right agent for the job\n- Breaking down complex tasks is genuinely helpful\n\n### What's experimental/rough\n- Some agents are still being refined\n- Research phase can be slow sometimes\n- Hook system requires restart (Claude Code limitation)\n- Documentation is scattered across files\n\n### Known limitations\n- Requires Node.js \u003e= 16\n- Need to restart Claude Code after installation\n- Opinionated about TDD (if you don't like tests, skip this)\n- Some agents might be too thorough/slow for simple tasks\n\n## Testing your installation\n\nAfter installing:\n\n```bash\n# 1. Validate everything installed correctly\nnpx claude-code-collective validate\n\n# 2. Check status\nnpx claude-code-collective status\n\n# 3. Restart Claude Code (required for hooks)\n\n# 4. Try it out\n# In Claude Code: \"Build a simple todo app with React\"\n# Expected: routes to research → breaks down task → writes tests → implements\n```\n\n## Troubleshooting\n\n### Installation fails\n- Check Node.js version: `node --version` (need \u003e= 16)\n- Clear npm cache: `npm cache clean --force`\n- Try force install: `npx claude-code-collective init --force`\n\n### Agents don't work\n- Restart Claude Code (hooks need to load)\n- Check `.claude/settings.json` exists\n- Run `npx claude-code-collective validate`\n\n### Tests don't run\n- Make sure your project has a test runner (Jest, Vitest, etc.)\n- Check if tests are actually being written to files\n- Look at the TDD completion reports from agents\n\n### Research is slow\n- Context7 might be having connectivity issues\n- Agent might be being thorough (this varies)\n- Check `.claude-collective/metrics/` for timing data\n\n## Requirements\n\n- **Node.js**: \u003e= 16.0.0\n- **NPM**: \u003e= 8.0.0\n- **Claude Code**: With MCP support and hook system\n- **Restart**: Required after installation (hooks limitation)\n\n## What this is and isn't\n\n### What it is\n- Experimental development aid for rapid prototyping\n- Collection of TDD-focused AI agents\n- Personal project that I use for my own MVPs\n- Opinionated about test-first development\n\n### What it isn't\n- Production-ready enterprise software\n- Guaranteed to work perfectly\n- Following any official standards\n- A replacement for thinking or understanding code\n\n## Why TDD?\n\nBecause in my experience:\n- Writing tests first forces better design thinking\n- Tests catch bugs when they're cheap to fix\n- Refactoring is safe with good test coverage\n- Code with tests is easier to change later\n\nThe agents enforce this because I believe it leads to better outcomes. If you disagree with TDD philosophy, this tool probably isn't for you.\n\n## Research features (experimental)\n\nTo make agents smarter about modern development:\n\n- **Context7 integration** - real, current library documentation\n- **ResearchDrivenAnalyzer** - intelligent complexity assessment\n- **Smart task breakdown** - only creates subtasks when actually needed\n- **Best practice application** - research-informed patterns\n\nThis stuff is experimental and sometimes overthinks things, but generally helpful.\n\n## Solutions to common agent problems\n\nAI agents can be unreliable. Here's what I built to deal with that:\n\n**Agents ignoring TDD rules**: Hook system enforces test-first development before any code gets written.\n\n**Agents bypassing directives**: CLAUDE.md behavioral operating system with prime directives that override default behavior.\n\n**Agents stopping mid-task**: Test-driven handoff validation ensures work gets completed or explicitly handed off.\n\n**Agents making up APIs**: Context7 integration forces agents to use real, current documentation.\n\n**Agents taking wrong approach**: Central routing through **@task-orchestrator** hub prevents agents from self-selecting incorrectly.\n\n**Agents breaking coordination**: Hub-and-spoke architecture eliminates peer-to-peer communication chaos.\n\n**Agents skipping quality steps**: Quality gates that block completion until standards are met.\n\n**Agents losing context**: Handoff contracts preserve required information across agent transitions.\n\n**Agents providing inconsistent output**: Standardized TDD completion reporting from every implementation agent.\n\n**Agents working on wrong priorities**: ResearchDrivenAnalyzer scores complexity to focus effort appropriately.\n\nMost of these are enforced automatically through hooks and behavioral constraints, not just hoping agents follow instructions.\n\n## Support\n\nThis is a personal project, but:\n- **Issues welcome** if you find bugs or have suggestions\n- **PRs welcome** for small fixes or better agent prompts  \n- **Don't expect rapid responses** - this is a side project\n\n**Get help**: Run `npx claude-code-collective validate` for diagnostics\n\n## License\n\nMIT License - Use it, break it, fix it, whatever works for you.\n\n---\n\n**Experimental** | **TDD-Focused** | **Personal Project** | **Use At Your Own Risk**\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanzan01%2Fclaude-code-sub-agent-collective","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanzan01%2Fclaude-code-sub-agent-collective","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanzan01%2Fclaude-code-sub-agent-collective/lists"}