Teammates Cookbook

Concrete recipes for common workflows. Each recipe is self-contained — read the one you need, skip the rest.

Table of Contents

Add a new teammate

When: Your project has grown a new domain that doesn’t fit cleanly into any existing teammate’s ownership.

Steps:

  1. Copy the SOUL.md, GOALS.md, WISDOM.md, and RESUME.md templates from .teammates/TEMPLATE.md into a new folder: 
    .teammates/<name>/
  SOUL.md
  GOALS.md
  WISDOM.md
  RESUME.md
  memory/
    weekly/
    monthly/

  2. Fill in every section of SOUL.md with project-specific details. Use template/example/SOUL.md as a reference for tone and detail level. You can also start from one of the 16 built-in personas at packages/cli/personas/ — each provides a role-specific SOUL.md scaffold with identity, principles, and ownership pre-filled. If you’re using the CLI, run /add instead of copying by hand — it scaffolds the folder, updates the roster, and indexes the new teammate for you.

  3. Fill in GOALS.md with 2-3 initial objectives based on the teammate’s domain. Use priority tiers (P0/P1/P2). Reference template/example/GOALS.md for format.

  4. Leave WISDOM.md in its initial empty state — wisdom emerges after the first compaction.

  5. Update these shared files:
    • .teammates/README.md — add to the roster table, routing guide, and dependency flow
    • .teammates/CROSS-TEAM.md — add a row to the Ownership Scopes table
    • .teammates/PROTOCOL.md — update the conflict resolution table if the new domain introduces new conflict types

  6. Update existing teammates’ SOUL.md Boundaries sections to reference the new teammate where relevant.

  7. Verify: the new teammate’s ownership globs don’t overlap with existing teammates.

Tip: Start broad. A new teammate with wide ownership that narrows over time is better than one with gaps from day one.

Retire or archive a teammate

When: A domain has been removed, merged into another teammate, or is no longer actively maintained.

Steps:

  1. Decide: merge (transfer ownership to another teammate) or archive (remove entirely).

  2. If merging:
    • Update the receiving teammate’s SOUL.md: add the retired teammate’s file patterns to Primary Ownership, update Boundaries.
    • Move any still-relevant typed memories from the retired teammate’s memory/ into the receiving teammate’s memory/.
    • Copy any wisdom entries that still apply into the receiving teammate’s WISDOM.md.
  3. If archiving:
    • No ownership transfer needed, but verify no files are left unowned.

  4. Remove the teammate. Inside the CLI, run /remove <name> — it deletes the folder and updates the roster, recall index, and any cached state. If editing by hand, delete .teammates/<name>/.

  5. Update shared files:
    • .teammates/README.md — remove from roster, routing guide, dependency flow
    • .teammates/CROSS-TEAM.md — remove from Ownership Scopes table
    • .teammates/PROTOCOL.md — remove from conflict resolution table
    • Other teammates’ SOUL.md Boundaries sections — remove references
  6. Commit with a clear message: retire @<name>: merged into @<other> or archive @<name>: domain removed.

Hand off work between teammates

When: Your current task requires changes to files you don’t own.

Steps:

  1. Do as much work as you can within your own domain first.

  2. Write a clear handoff with full context: 
    ```handoff
@<teammate>
<What you need done, why, and any relevant context or constraints.
Include file paths, function names, or specs if applicable.>

    ```

  3. Include the handoff block anywhere in your response — it will be detected automatically.

Rules:

  • Never modify files outside your ownership, even for “small” fixes.
  • Provide enough context that the receiving teammate can act without reading your full conversation history.
  • If the task is complex, write a spec or design doc in your own folder first, then reference it in the handoff.

Hand off across repositories

When: A task spans multiple repositories that each have their own .teammates/ directory.

Steps:

  1. Complete all work in the current repository first.

  2. Write a handoff message describing:
    • Which repository needs the change
    • Which teammate in that repository should handle it
    • What needs to be done and why
    • Any interfaces or contracts that must match between repos
  3. Tell the user to switch to the other repository and relay the handoff. Cross-repo handoffs are manual — the user is the bridge.

Example:

The API contract changed: GET /users now returns { items: User[], cursor: string } instead of User[]. The frontend repo’s @pixel teammate needs to update the API client at src/api/users.ts to handle the new shape.

Run a retrospective

When: After a significant milestone, a rough week, or on a regular cadence (e.g., bi-weekly).

Steps:

  1. Ask a teammate to run /retro (or prompt them to reflect).

  2. The teammate produces four sections:
    • Working — what’s going well
    • Not Working — what’s causing friction
    • Proposed SOUL.md Changes — specific before/after edits with reasoning
    • Questions — things that need user input

  3. Review the proposed SOUL.md changes. Approve, modify, or reject each one.

  4. Approved changes are written to the teammate’s SOUL.md immediately. The retro is not complete until approved changes are applied.

See .teammates/scribe/docs/RETRO-FORMAT.md for the full format specification.

Run memory compaction

When: A teammate’s memory/ directory is getting large (20+ daily logs), or on a regular cadence.

Steps:

  1. Ask the teammate to run /compact.

  2. The command runs two pipelines:

    Episodic compaction:

    • Completed weeks’ daily logs → memory/weekly/YYYY-Wnn.md
    • Weekly summaries older than 52 weeks → memory/monthly/YYYY-MM.md
    • Raw daily logs are deleted after compaction

    Semantic compaction:

    • Reviews all typed memory files
    • Identifies patterns and recurring themes
    • Distills into WISDOM.md entries
    • Deletes fully absorbed memory files

  3. Verify: WISDOM.md entries are principled and actionable, not just summaries of events.

Tip: Run episodic compaction weekly and semantic compaction monthly for best results.

Record a decision

When: The team makes a choice that future sessions should know about — architecture, convention, tool selection, or scope decisions.

Steps:

  1. Add an entry to .teammates/DECISIONS.md:

    ## DDDD — <Title>

**Date:** YYYY-MM-DD
**Decided by:** <who was involved>
**Status:** accepted

### Context
<Why did this decision come up?>

### Decision
<What was decided?>

### Alternatives considered
- <Option A> — <why not>
- <Option B> — <why not>

  2. Number decisions sequentially (D001, D002, …).

  3. If a decision is later reversed, update its status to superseded by DDDD and add the new decision.

See the decision log template for the full format.

Add a service

When: You want to enable an optional service beyond the built-in recall search.

Note: Recall (semantic memory search) is bundled with the CLI and works automatically — no setup needed. This recipe is for adding other optional services.

Steps:

  1. Install the service: 
    cd <service-dir> && npm install && npm run build
  2. Add the service to .teammates/services.json: 
    {
  "<service-name>": {}
}
  3. The CLI automatically detects services from services.json and injects their capabilities into teammate prompts.

Update templates after a framework change

When: The upstream template/ files or bundled personas have changed (new template version, new wisdom in the persona scaffolds) and your project’s .teammates/ files need to catch up.

Steps:

  1. Check the current template version in your project files — look for <!-- template-version: N --> comments.

  2. Check the upstream template version in the template/ directory.

  3. If versions differ, compare with the upstream template/ files and apply changes manually.

  4. After updating, bump the <!-- template-version: N --> comment in each updated file.

  5. For per-teammate updates, run /update <teammate> in the CLI. It refreshes that teammate’s SOUL.md and WISDOM.md from the bundled persona while preserving the teammate’s memory folder.

Resolve an ownership conflict

When: Two teammates both believe they should handle a task, or a file falls in an ambiguous ownership zone.

Steps:

  1. Check .teammates/PROTOCOL.md — the Conflict Resolution table has explicit rules for common conflict types.

  2. If the table doesn’t cover the case:
    • The upstream owner (per the dependency flow) gets priority for shared interfaces.
    • The domain owner gets priority for implementation details.
    • When in doubt, the user decides.
  3. If this conflict type is likely to recur, add a new row to the Conflict Resolution table and record the decision in .teammates/DECISIONS.md.

Onboard a new human team member

When: A new person joins the project and needs to understand the teammates system.

Steps:

  1. Point them to README.md for the project overview and .teammates/README.md for the roster and routing guide.

  2. Have them fill in .teammates/USER.md with their role, preferences, and current focus. (This file is gitignored — it stays local.)

  3. Explain the basics:
    • @mention a teammate by name to route work directly
    • Bare text in the CLI auto-routes to the best teammate
    • Teammates hand off to each other — approve or reject handoffs as they come
  4. Optionally, point them to docs/adoption-guide.md for a deeper walkthrough of how to work with the system.