code-copilot-team

Code Copilot Team

Reusable, opinionated configuration for AI-assisted coding with multi-agent team delegation. Ships with templates for ML/AI, Enterprise Java, and Web projects.

Built for Claude Code as the reference implementation, with portable conventions for Cursor, GitHub Copilot, Windsurf, Aider, and local LLMs.

📖 Deep dive: Stop Fighting AI Agents and Build a Reusable Multi-Agent Dev Environment — the full story behind this project, lessons learned from 13+ real build sessions, and why every rule exists.

---

Why This Exists

Every rule in this repo is failure-driven — it exists because we hit the specific failure it prevents, often more than once. After analyzing 13 sessions of a real project build, we identified six recurring patterns: dependency breaks, agents ignoring conventions, context window exhaustion, schema drift during parallel builds, agents not asking clarifying questions, and commit granularity issues. This setup prevents all of them.

Framework Compliance

Evaluated against the two leading AI coding agent frameworks (February 2026):

OpenAI Harness Engineering — 5.0 / 5.0

Claude Code Best Practice — 10.0 / 10.0

Sources: OpenAI Harness Engineering · Claude Code Best Practice

Further Reading

• Spec-Driven Development vs Code Copilot Team — Side-by-side comparison with GitHub's Spec Kit. TL;DR: SDD defines what to build; Code Copilot Team defines how to behave while building it. They're complementary, not competing.

Spec-Driven Development (SDD)

Code Copilot Team includes a built-in Spec-Driven Development layer that prevents "vibe coding" — the tendency of AI agents to start writing code before requirements are clear. SDD ensures every feature goes through a structured specification process, with the rigor scaled to match the risk.

How It Works

Every task is classified into one of three spec modes based on risk:

spec_mode	When	What's Required
full	Security, schema changes, integration, features touching >2 files	plan.md + spec.md + tasks.md
lightweight	Features touching 1–2 files, non-critical changes	plan.md + spec.md
none	Bug fixes (non-security), docs, trivial changes	plan.md only

The Plan agent writes plan.md with a YAML frontmatter block that declares spec_mode, feature_id, risk_category, and justification. The Build agent reads this frontmatter and gates itself accordingly — it won't proceed on a full task without a complete spec.md, and it won't proceed on any task that has unresolved [NEEDS CLARIFICATION] markers.

The Four Artifacts

SDD uses exactly four artifact types (no checklists, no extra process):

Artifact	Purpose	When Created
plan.md	Implementation plan with frontmatter gating	Always (all modes)
spec.md	Requirements, user scenarios, constraints	full and lightweight only
tasks.md	Task breakdown with story and priority markers	full only
lessons-learned.md	Cross-project learnings for future sessions	End of project

Templates for all four live in shared/templates/sdd/ and are available across all adapters.

Three-Layer Gating

SDD enforcement operates at three levels:

1. Agent-level — The Build agent reads plan.md frontmatter and conditionally requires spec.md and resolves [NEEDS CLARIFICATION] markers before proceeding.
2. CI validation — scripts/validate-spec.sh runs on every PR touching specs/. It validates frontmatter fields, checks for required files per spec_mode, and enforces justification for spec_mode: none.
3. Hooks — Existing hooks remain untouched; SDD gating is additive, not intrusive.

Spec Artifacts Location

All SDD artifacts live in the versioned specs/ directory, organized by feature:

specs/
└── <feature-id>/
    ├── plan.md              ← Always present
    ├── spec.md              ← full / lightweight
    ├── tasks.md             ← full only
    ├── lessons-learned.md   ← End of project
    └── collaboration/       ← Peer review artifacts (dual mode)
        ├── plan-consult.md  ← Peer review of plan phase
        └── build-review.md  ← Peer review of build phase

Risk Classification

The spec-workflow.md rule defines risk categories that map directly to spec_mode: