Fireteam — Persistent Memory for AI Coding Sessions

Fireteam gives AI coding agents a memory that survives session restarts, context limits, and crashes. It uses a

.fireteam/

Primary use case: One agent working across multiple sessions on the same project.

.fireteam/

Secondary use case: 2-6 agents coordinating on the same codebase through shared

.fireteam/

Core mechanic: Every AI agent can read and write files. Fireteam uses the file system as the persistent memory layer.

CRITICAL: Scope Boundaries

Fireteam operates ONLY within the current working directory. These rules are non-negotiable:

1. NEVER navigate to, read, scan, or reference files outside the current working directory. Not parent directories, not sibling directories, not the user's home folder, not other projects. The project boundary is the current working directory — period.

2. NEVER search the filesystem for other projects. If the current directory is empty and the user asked to set up a fireteam, set it up HERE. Do not go looking for code elsewhere.

3. All

   .fireteam/

   files are created in the current working directory. Not in a discovered project, not in a parent directory.

4. Recon scans ONLY the current working directory. If the directory is empty, recon finds nothing — that's correct. Proceed as greenfield.

5. If the current directory seems wrong (empty when user said "existing project"), ASK the user: "This directory appears empty. Would you like to set up a greenfield fireteam here, or should you navigate to your project first?" Do NOT go exploring.

When to Use This Skill

Session continuity (primary):

• User wants their agent to remember context across sessions
• User says "continue my fireteam" or "pick up where I left off"
• User says "set up a fireteam" for a new or existing project
• User wants to save progress: "write a checkpoint"
• User is resuming after a crash or context limit

Multi-agent coordination (secondary):

• User wants multiple AI agents working on the same project
• User needs to create a handoff between agents
• User says "coordinate my agents" or "onboard agents"

Adaptive Entry Point

Fireteam uses ONE entry sequence that adapts to context. Never ask the user "are you bootstrapping or initializing?" — detect the state and act.

Phase 1: Context Assessment

Before doing anything, assess the project state:

Does .fireteam/ exist and have a populated MISSION.md?
├─ YES → REJOIN: run heartbeat, read board, pick up work (skip to Phase 5)
├─ .fireteam/ exists but empty/stale → treat as new setup
└─ NO → new setup, continue to Phase 2

Phase 2: Gather Inputs

Use everything available within the current working directory. Do NOT ask the user which flow to use.

Phase 3: Recon (when code exists in CWD)

Only runs when there's existing code in the current working directory. Read the codebase structure to understand what's already built. See

references/recon.md

SCOPE: Scan ONLY the current working directory. Never traverse up or into sibling directories. If CWD is empty, skip recon entirely — proceed as greenfield.

Quick version — scan these files:

• README / docs → what the project claims to be
• Package files (package.json, requirements.txt, Cargo.toml, go.mod) → stack
• Directory listing (2 levels deep) → code organization
• Config files (.env.example ONLY — never .env, config/, CI files) → deployment, services
• Entry points (main files, route definitions) → API surface
• Recent git log (if git, last 20 commits) → recent work

SECURITY: Never read

.env

.env.example

.env.sample

references/recon.md

Present findings to the user for confirmation before creating tasks. Output goes into INTEL.md.

Phase 4: Setup .fireteam/

Run

scripts/setup.sh

Step 1 — MISSION.md: Translate PRD goals (or recon findings + user goals) into mission statement, goals, scope, constraints. Use template from

assets/templates/mission.md

Step 2 — ROSTER.md: Propose operators based on work ahead. Reference

references/presets.md

assets/templates/roster.md

Step 3 — SOUL files: For EACH operator, create

checkpoints/[callsign]-soul.md

assets/templates/soul.md

Step 4 — HEARTBEAT files: For EACH operator, create

checkpoints/[callsign]-heartbeat.md

assets/templates/heartbeat.md

Step 5 — Objectives: Create task files in

tasks/OBJ-XXX.md

assets/templates/task.md

• Every objective MUST have a goal chain (Mission → Goal → Task → Why)
• Each objective is atomic: one deliverable, completable in one session
• Map dependencies between objectives
• For existing projects: tasks MUST reference real file paths and existing patterns from recon
• Assign to operator callsigns

Step 6 — BOARD.md: Populate with all objectives. Use template from

assets/templates/board.md

Step 7 — INTEL.md: Seed with key facts. For greenfield: stack, constraints, design direction from PRD. For existing projects: everything discovered in recon — file paths, API routes, database schema, conventions. NEVER write actual credential values — only variable names and service descriptions. Use template from

assets/templates/intel.md

Step 8 — Field log: Create today's

memory/YYYY-MM-DD.md

Step 9 — Checkpoint: Write

checkpoints/team-lead.md

Step 10 — Debrief: Tell the user:

1. Operators proposed and why
2. Objective breakdown with dependencies
3. Which operator to deploy next
4. The onboarding prompt for that operator

Phase 5: Execute & Continue

Single agent (default): After completing setup, begin working on the highest-priority task from the board. Work through tasks sequentially — when one finishes, write a handoff note (what was built, API contracts, file paths), update the board, and start the next ready task. Checkpoint every 15 minutes.

When the session ends (context limit, crash, user stops), everything is saved in

.fireteam/

Multiple agents (when the user wants parallelism): Generate onboarding prompts for each additional agent. The user pastes these into separate terminals. Each agent reads

.fireteam/

Onboarding prompt for additional agents:

You are the [ROLE] operator. Callsign: [callsign].
Read these files in order:
1. .fireteam/MISSION.md
2. .fireteam/CONVENTIONS.md
3. .fireteam/ROSTER.md
4. .fireteam/checkpoints/[callsign]-soul.md
5. .fireteam/INTEL.md
6. .fireteam/memory/[today].md
7. .fireteam/checkpoints/[callsign].md (if resuming)
8. .fireteam/BOARD.md
9. .fireteam/handoffs/ (check for files addressed to you)
Run your heartbeat, then pick up your highest-priority objective.

For recovery after crashes: See

references/recovery.md

Core Protocol Rules

These rules govern all agent behavior within Fireteam. Full details in

references/conventions.md

Goal Chains (mandatory)

Every task traces: Mission → Goal → Task → Why It Matters. No goal chain = don't start the task.

Atomic Checkout

Before starting a task, check

checked_out_by

Progressive Checkpointing

Don't wait for session end. Update

checkpoints/[you].md

Heartbeat (every session start)

Read: MISSION → CONVENTIONS → ROSTER → SOUL → INTEL → field log → checkpoint → BOARD → handoffs → comms. Then assess: what is the highest-priority action?

Handoffs (when your work feeds another agent)

Create

handoffs/HO-XXX.md

Session End Protocol

1. Update field log
2. Write checkpoint
3. Update BOARD.md
4. Create handoffs if needed

File Permissions

• You MAY modify: your task files, BOARD.md (your rows), today's field log (append), your checkpoint, project code your task requires
• You MUST NOT modify: MISSION.md (Team Lead only), CONVENTIONS.md (Human only), ROSTER.md (Team Lead only), INTEL.md (Team Lead only), other agents' files

Task Lifecycle

backlog → in-progress → review → done
              ↓
           blocked (create comms thread)

Conflict Resolution

If you find conflicting work: STOP. Create high-priority comms thread. Wait for Team Lead or Human.

.fireteam/ Directory Structure

.fireteam/
├── MISSION.md              ← why we're here (Team Lead owns)
├── CONVENTIONS.md          ← rules of engagement (Human owns)
├── ROSTER.md               ← who's on the team (Team Lead owns)
├── BOARD.md                ← objectives kanban (Team Lead owns rows, agents update theirs)
├── INTEL.md                ← curated knowledge (Team Lead owns)
├── tasks/OBJ-XXX.md        ← individual objectives with goal chains
├── handoffs/HO-XXX.md      ← context transfers between agents
├── comms/THREAD-XXX.md     ← async discussions
├── decisions/DEC-XXX.md    ← architecture/tech decision records
├── memory/YYYY-MM-DD.md    ← daily field logs (append-only)
└── checkpoints/
    ├── [callsign].md        ← progressive session state
    ├── [callsign]-soul.md   ← operator identity (mandatory)
    └── [callsign]-heartbeat.md ← session start checklist

File References

Templates for all file types are in

assets/templates/

assets/templates/task.md

assets/templates/handoff.md

assets/templates/checkpoint.md

assets/templates/soul.md

assets/templates/heartbeat.md

assets/templates/thread.md

assets/templates/decision.md

assets/templates/fieldlog.md

assets/templates/mission.md

assets/templates/roster.md

assets/templates/board.md

assets/templates/intel.md

references/conventions.md

For full protocol rules:

references/conventions.md

references/recovery.md

references/recon.md

references/presets.md

Fireteam Dashboard

The skill includes

assets/dashboard.html

.fireteam/

"Open

dashboard.html

.fireteam/

The dashboard reads

.fireteam/

When setting up a fireteam, copy

assets/dashboard.html

cp assets/dashboard.html [project-root]/fireteam-dashboard.html