File Structure

Framework Repository

The claude_teamdev repository (the template):

claude_teamdev/
├── README.md                     Quick start guide
├── CHANGELOG.md                  Detailed change history
├── VERSION.md                    Date-based version (YYYYMMDD.patch)
├── TODO.md                       Task tracking
├── MIGRATION.md                  Breaking changes per version
├── mkdocs.yml                    MkDocs site configuration
├── requirements.txt              mkdocs-material dependency
│
├── docs/                         Single source: guidelines + documentation
│   ├── index.md                  Landing page
│   ├── overview.md               Design principles, installation
│   ├── team-structure.md         4 teams, routing, escalation, abbreviations
│   ├── dev-cycle.md              Research → Dev → KB → QA
│   ├── code-to-docs-bridge.md    @code-change tag specification
│   ├── knowledge-base.md         KB structure, cards, API docs, math docs
│   ├── doxygen-site.md           Doxygen HTML site integration (C/C++)
│   ├── sphinx-site.md            Sphinx HTML site integration (Python)
│   ├── scoring.md                Quality/coverage/consistency/freshness/transfer
│   ├── review-protocol.md        Verdicts, severity, adversarial checks
│   ├── qa-team.md                Benchmark agent, regression thresholds
│   ├── manager.md                Coordination, reporting, HALT
│   ├── cross-team-handoffs.md    Explicit handoff mechanisms
│   ├── shadow-validation.md      Shadow protocol, SHADOW macro, transfer score
│   ├── sprint-kanban.md          YAML kanban format, task states
│   ├── git-workflow.md           Branching, commits, workflow
│   ├── rollback-protocol.md      HALT + investigation protocol
│   ├── file-structure.md         This page
│   ├── changelog-protocol.md     Changelog protocol for all agents
│   └── upgrade.md                Base+override architecture, upgrade guide
│
├── skills/                       Agent skill definitions
│   ├── general/
│   │   └── project-config.md     Default configuration template
│   ├── manager/SKILL.md          Sprint coordination
│   ├── onboarding/SKILL.md       Interactive setup walkthrough
│   ├── research-developer/SKILL.md
│   ├── research-reviewer/SKILL.md
│   ├── architect-developer/SKILL.md
│   ├── architect-reviewer/SKILL.md
│   ├── code-developer/SKILL.md
│   ├── code-reviewer/SKILL.md
│   ├── kb-developer/
│   │   ├── SKILL.md              Driver
│   │   ├── cards.md              Card authoring
│   │   ├── doxygen.md            Doxygen annotation style + site generation (C/C++)
│   │   ├── sphinx.md             Sphinx docstring style + site generation (Python)
│   │   ├── tex.md                Math document authoring
│   │   ├── index.md              INDEX + SYNCLOG maintenance
│   │   └── library.md            Reference library catalog
│   ├── kb-reviewer/
│   │   ├── SKILL.md              Board view
│   │   └── scoring.md            Customizable weights
│   ├── benchmark/SKILL.md        QA team — benchmarking
│   ├── shadow-developer/SKILL.md
│   ├── shadow-reviewer/SKILL.md
│   ├── docs-developer/SKILL.md   Documentation + changelog
│   ├── teamdev-developer/SKILL.md Framework self-improvement
│   └── teamdev-installer/SKILL.md Framework installer
│
└── scripts/
    ├── Doxyfile                  Doxygen config with call graphs (C/C++)
    └── sphinx-conf.py            Sphinx config for Python projects

Installed Structure (in a project)

After installation, the project uses a base + override layout:

YOUR_PROJECT/
├── .claude/
│   ├── teamdev/                  CORE layer — safe to overwrite on upgrade
│   │   ├── README.md             Framework index / landing page
│   │   ├── TODO.md               Task tracking
│   │   ├── VERSION.md            Framework version (YYYYMMDD.patch)
│   │   ├── MIGRATION.md
│   │   ├── docs/                 Guidelines + documentation
│   │   ├── skills/               Agent skill definitions
│   │   └── scripts/              Doxyfile, sphinx-conf.py, etc.
│   │
│   └── project/                  PROJECT layer — never overwritten
│       ├── project-config.md     THE ONE FILE to customize
│       ├── docs/                 Project-specific guidelines (additive)
│       ├── skills/               Custom or overridden skills
│       └── scripts/              Project-specific scripts
│
├── doc/
│   └── kb/                       Knowledge base (project-specific)
│       ├── INDEX.md
│       ├── SYNCLOG.md
│       ├── BOARD.md
│       ├── cards/
│       ├── math/
│       └── library/
│           └── INDEX.md
│
├── SPRINT.md                     Current sprint state
├── CHANGELOG.md                  Project changelog
└── ...                           Project source code

Resolution Rule

When an agent looks for a skill or guideline:

Check .claude/project/ first
Fall back to .claude/teamdev/
Same-name file in project/ wins (override)
New files in project/ are additive (extension)

Upgrading

rm -rf .claude/teamdev/
cp -r claude_teamdev/{README.md,TODO.md,VERSION.md,MIGRATION.md,docs,skills,scripts} .claude/teamdev/

The project/ layer is untouched. See Upgrade Guide for details.