Skip to content

Upgrading teamdev

Base + Override Architecture

When installed in a project, teamdev uses a two-layer directory structure that separates core framework files from project customizations:

.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)
│   ├── docs/              # Guidelines + documentation (single source)
│   ├── skills/            # Agent skill definitions
│   └── scripts/           # Doxyfile, sphinx-conf.py, etc.
│
└── project/               # PROJECT layer — never touched by upgrade
    ├── project-config.md  # Project-specific configuration
    ├── docs/              # Project-specific guidelines (additive)
    ├── skills/            # Custom or overridden skills
    └── scripts/           # Project-specific scripts

Resolution Rule

When an agent looks for a skill or guideline:

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

This means you can:

  • Override a core skill by placing a file with the same path in project/skills/.
  • Extend the framework by adding new skills in project/skills/.
  • Add project guidelines in project/docs/ without touching core files.

Upgrade Steps

# 1. Check current version
cat .claude/teamdev/VERSION.md

# 2. Read MIGRATION.md for breaking changes
cat claude_teamdev/MIGRATION.md

# 3. Overwrite the core layer
rm -rf .claude/teamdev/
cp -r claude_teamdev/{README.md,TODO.md,VERSION.md,MIGRATION.md,docs,skills,scripts} .claude/teamdev/

# 4. Verify
cat .claude/teamdev/VERSION.md

Your project/ directory is untouched — all customizations preserved.

When Overrides Need Updating

If a new version changes a skill's interface (e.g., renames a section that other skills reference, changes the project-config.md schema, or alters the handoff protocol), your overrides may need updating.

Check MIGRATION.md for breaking changes. It lists:

  • Renamed or removed files
  • Changed config fields
  • Modified skill interfaces
  • Updated cross-references

Adding Project-Specific Skills

Create a skill in the project layer:

.claude/project/skills/my-custom-agent/SKILL.md

This skill is available to the manager for routing, just like core skills. It survives upgrades automatically.

Adding Project-Specific Guidelines

Create a guideline in the project layer:

.claude/project/docs/my-project-rule.md

Reference it from your custom skills. Core skills won't automatically read project-specific guidelines unless you override the core skill to include a reference.

Overriding a Core Skill

To customize how the code-reviewer works for your project:

# Copy the core skill as a starting point
cp .claude/teamdev/skills/code-reviewer/SKILL.md .claude/project/skills/code-reviewer/SKILL.md

# Edit your copy
# The project version now takes precedence

Warning

When you override a core skill, you own it. Future framework upgrades won't update your override. Check MIGRATION.md after each upgrade to see if your overrides need manual updates.

Version Compatibility

The VERSION.md file uses date-based versioning: YYYYMMDD.patch

  • YYYYMMDD — the date the release was made (tells you which upstream versions are included).
  • patch — same-day fixes (.1, .2, etc.).

Example: 20260331.0 is the first release on 2026-03-31; 20260331.1 would be a same-day fix.