AI Development Team

A framework for distributed AI team collaboration using Claude Code. Multiple Claude Code sessions operate as distinct team roles, communicating through shared markdown files committed to git.

Roles

Role	Responsibility	Key Permissions
Manager	Project management, tasks, approvals	Create CRs/tasks, approve work
Architect	System design, code review	Modify architecture docs, create tasks
Developer	Feature implementation, bug fixes	Modify source code
Integrator	Testing, git commits	Commit/push to feature/dev branches
DevOp	Infrastructure, CI/CD	Modify infra configs
Production Engineer	Release management	Merge to main branch

Quick Start

1. Clone this repository
2. Start Claude Code in the repo directory
3. Initialize your session:

   /init-session <role> <project>
   

4. Check your queue and tasks:

   /check-queue
   /get-tasks
   

Creating a New Project

./scripts/init_project.sh <project_name>

Available Commands

Command	Description	Available To
/init-session <role> <project>	Start a session	All roles
/check-queue	Check incoming messages	All roles
/send-message <role> <msg>	Send a message	All roles
/get-tasks	View assigned tasks	All roles
/update-task <id> <status>	Update task status	All roles
/create-task	Create a new task	Manager, Architect
/create-cr	Create change request	Manager
/assign-task <id> <role>	Assign a task	Manager
/approve-task <id>	Approve a task	Manager
/submit-for-review <id>	Submit for review	Developer, Architect
/commit-work [id]	Test and commit	Integrator
/run-tests	Run project tests	All roles
/merge-to-master <branch>	Merge to main	Production Engineer
/daily-report	Generate daily report	Manager

Skills (auto-activated expertise)

Each role has 3 skills that activate automatically based on conversation context:

Role	Skills
Manager	project-management, change-request-analysis, stakeholder-communication
Architect	system-design, code-review-standards, task-decomposition
Developer	clean-code-practices, debugging-methodology, implementation-patterns
Integrator	test-engineering, git-workflow, dependency-management
DevOp	infrastructure-ops, cicd-pipelines, environment-troubleshooting
Production Engineer	release-validation, rollback-procedures, production-monitoring

Skills provide domain expertise that Claude applies while working. Unlike commands (user-invoked actions), skills activate automatically when the conversation context matches their domain.

Architecture

• Communication: Markdown queue files in queue/ directory
• Enforcement: Python hook (hooks/role_enforcer.py) validates operations via PreToolUse hooks
• Configuration: .claude/settings.json wires hooks, .claude/commands/ defines slash commands
• Roles: Per-role instructions in roles/<role>/CLAUDE.md
• Projects: Multi-project support under projects/<name>/

Documentation

• Onboarding Guide
• Team Workflow
• Conventions
• Queue Format
• Context Graph integration — optional decision-aware layer
• Illustrated docs site: docs/site/index.html

Context Graph (optional)

The team can optionally run on Context Graph — a decision-aware knowledge graph that becomes the team's shared memory and management system: the six roles become RBAC, the workflow becomes governed + audited actions, task/CR states become enforced state machines, and every decision's why is queryable.

It's opt-in and config-gated — with cg/config.json → "enabled": false (the default), nothing changes and the team runs on markdown as usual. To turn it on:

./scripts/cg_setup.sh      # start (or clone + start) a Context Graph server
./scripts/cg_onboard.sh    # install the preset + backfill the repo's history
cp cg/.mcp.json.example .mcp.json   # wire MCP, then set cg/config.json enabled:true

See docs/CONTEXT_GRAPH.md, the cg/ kit, and the illustrated walkthrough in docs/site/.

Restriction Rules

• Only Production Engineer can merge into main
• Only Integrator can commit/push to feature/development branches
• Only Manager can approve tasks as done
• Only Architect reviews significant code changes

Restrictions are enforced as warnings (not hard blocks) to maintain flexibility while promoting proper workflow.