View on GitHub

campaign-mode

Work with a party of AI advisors with genuinely different perspectives.

SPEC-CM-006-B: Campaign State Directory

Field Value
Specification ID SPEC-CM-006-B
Parent ADR ADR-CM-006
Version 1.3
Status Draft
Last Updated 2026-02-18

Overview

This specification defines the .campaign/ directory structure used to store campaign state. The directory stores character profile files, the quest definition file (quest.md) which tracks campaign mode, success criteria, current phase, and progress log, the council report file (council-report.md) which captures multi-perspective project analysis, and conversation transcript files in conversations/ which preserve full verbatim records of every agent consultation. This specification establishes the directory convention, file formats, and export protocol.

Directory Structure

.campaign/
├── quest.md                    # Quest definition (mode, criteria, narrative, progress log)
├── council-report.md           # Council analysis report (multi-perspective diagnostic)
├── conversations/              # Conversation transcripts (one file per session)
│   ├── 2026-02-18-14-32-cat.md
│   ├── 2026-02-18-15-10-owl.md
│   └── 2026-02-18-16-00-guardian.md
└── profiles/                   # Character profiles
    ├── bear.md                 # Animal profile (if profiled)
    ├── cat.md                  # Animal profile (if profiled)
    ├── owl.md                  # Animal profile (if profiled)
    ├── puppy.md                # Animal profile (if profiled)
    ├── rabbit.md               # Animal profile (if profiled)
    ├── wolf.md                 # Animal profile (if profiled)
    ├── gandalf.md              # NPC skin (if themed)
    ├── dragon.md               # NPC skin (if themed)
    └── guardian.md             # NPC skin (if themed)

Directory Location

The .campaign/ directory lives at the project root – the same level as .claude/, skills/, and docs/. It is created by Gandalf during Phase 2 when the user opts into character profiles.

File Naming

Partial Profiles

Not all files need to exist. If the user profiles only Bear and Cat, only bear.md and cat.md appear in profiles/. Animals without profiles use their default archetypes. NPCs without skins use their default presentation.

Profile File Format

Profile files follow the format defined in SPEC-CM-006-A:

Quest Definition File

quest.md

The quest definition file stores durable campaign state. It is the canonical source of truth for campaign mode, success criteria, quest narrative, and campaign progress. NPC agents read this file rather than relying on conversation context.

Format

The file uses YAML frontmatter (matching the profile file pattern from SPEC-CM-006-A) with a markdown body:

---
campaign-mode: Grow & Ship
phase: 3
created: 2026-02-14
---

## Quest Narrative
[Gandalf's framing of the quest — stakes, challenge, invitation]

## Success Criteria
1. [Criterion text as agreed with the user]
2. [Criterion text as agreed with the user]
3. [Criterion text as agreed with the user]

## Anticipated Dragon
[The internal obstacle or resistance the user identified]

## Progress Log
- **Phase 1 complete** — Quest defined (2026-02-14)
- **Phase 2 skipped** — Ship mode (2026-02-14)
- **Guardian checkpoint** — Conditional Approval: "API design is solid but error handling needs work" (2026-02-14)
- **Guardian checkpoint** — Approved (2026-02-14)
- **Dragon confrontation** — Dragon Slain: "All criteria met" (2026-02-14)

Frontmatter Fields

Field Type Description
campaign-mode String One of Grow, Ship, or Grow & Ship
phase Integer (1–6) Current campaign phase
created Date (ISO 8601) Date the quest was defined

Body Sections

Section Description Written by
Quest Narrative Gandalf’s framing of the quest Gandalf (Phase 1)
Success Criteria Numbered list of testable criteria Gandalf (Phase 1)
Anticipated Dragon The internal obstacle the user identified Gandalf (Phase 1)
Progress Log Append-only log of phase transitions and NPC verdicts All NPCs

Who Writes What

Agent Action When
Gandalf Creates quest.md with all sections End of Phase 1
Gandalf Updates phase, appends Phase 2 log entry End of Phase 2 (or skip)
Guardian Appends checkpoint result to Progress Log After delivering verdict
Dragon Appends confrontation result to Progress Log, updates phase After delivering verdict

Progress Log Entry Formats

Lifecycle

  1. File does not exist before Phase 1
  2. Gandalf creates the file at the end of Phase 1 (quest definition complete)
  3. File is read by /continue-quest to reconstruct campaign context
  4. Guardian and Dragon read the file for success criteria and campaign mode
  5. Guardian and Dragon append to the Progress Log after delivering verdicts
  6. File persists after campaign completion as a record of the quest

Council Report File

council-report.md

The council report file captures the output of a /council invocation — a multi-perspective project analysis from all six animal agents, synthesised by Simon.

Format

---
created: 2026-02-14
council-type: standalone
---

# Council Report

## Animal Perspectives

### Bear — Vision & Direction
[Summary of Bear's observations]

### Cat — Risk & Scope
[Summary of Cat's observations]

### Owl — Process & Structure
[Summary of Owl's observations]

### Puppy — Opportunities & Momentum
[Summary of Puppy's observations]

### Rabbit — Resources & Stakeholders
[Summary of Rabbit's observations]

### Wolf — Cohesion & Balance
[Summary of Wolf's observations]

## Consensus
[Common themes, key tensions, overall assessment from Simon]

## Recommended Next Steps
1. [Prioritised action]
2. [Prioritised action]
3. [Prioritised action]

Frontmatter Fields

Field Type Description
created Date (ISO 8601) Date the council was convened
council-type String One of standalone (no active quest) or quest-informed (active quest provided context)

Profile Name Overrides

When character profiles exist in .campaign/profiles/, section headers use the profile name with the archetype in parentheses (e.g., ### Paladin (Bear) — Vision & Direction).

Lifecycle

  1. File does not exist before the first /council invocation
  2. The /council command creates the file after all animal analyses and Simon’s synthesis
  3. The file is overwritten on each subsequent /council invocation (no history)
  4. Gandalf reads the file during quest definition (Phase 1) if it exists, to inform quest framing
  5. The /continue-quest command detects the file and offers it as context when no active quest exists
  6. File persists indefinitely as a project diagnostic artefact

Who Writes What

Agent Action When
Council command Creates council-report.md with all sections End of /council invocation
Gandalf Reads report to inform quest framing Phase 1 (if report exists)

Conversation Transcript Files

conversations/

The conversations directory stores full verbatim transcripts of every agent consultation during a campaign. Each file captures one conversation session — the complete exchange between the user and a single agent (or the Council as a whole).

Files are named with a date-first format ({YYYY-MM-DD}-{HH-MM}-{agent}.md) for chronological sorting. The agent identifier uses the archetype name (lowercase). When a profile exists, the profile’s skin-name is appended in round brackets (lowercase, hyphens for spaces) — e.g., 2026-02-18-14-32-cat(eeyore).md. The profile name also appears in frontmatter.

Transcript format, write protocol, isolation rules, and timing are defined in SPEC-CM-012-A.

Who Writes What

Agent Action When
Animals Write own transcript End of Phase 3 consultation, before Next Perspective
Gandalf Writes own transcript End of Phase 1, mid-campaign counsel, Phase 5 readiness review
Guardian Writes own transcript After checkpoint verdict + quest.md update
Dragon Writes own transcript After confrontation verdict + quest.md update
Council Writes session transcript After council report write

Isolation Rules

Guardian and Dragon may write their own transcripts but must NOT read transcripts from .campaign/conversations/. See SPEC-CM-003-A for full isolation rules.

Export Protocol

User-Managed Export

Users can copy .campaign/profiles/ to reuse profiles in future campaigns. The system does not manage a roster – this is the user’s responsibility.

# Save profiles for reuse
cp -r .campaign/profiles/ ~/my-saved-profiles/quest-name/

# Reuse profiles in a new campaign
cp -r ~/my-saved-profiles/quest-name/ .campaign/profiles/

Export Scope

Import Behaviour

When a user copies profiles into a new campaign’s .campaign/profiles/ directory:

Gitignore Considerations

The .campaign/ directory contains user-generated campaign state. Projects should consider whether to track it in version control:

This is a user decision – Gandalf does not manage .gitignore entries.

Scope Boundary

In Scope

Out of Scope (Deferred)

This specification resolves Open Question #5 (State Management) from the north-star. Campaign state is persisted in .campaign/quest.md and profiles in .campaign/profiles/.

Spec ID Title Relationship
SPEC-CM-006-A Character Profile Format Format of files stored in this directory
SPEC-CM-001-A Skill Architecture Parallel directory convention (.claude/ for skills, .campaign/ for state)
SPEC-CM-001-B Campaign Lifecycle Phase 2 where profiles are created and stored
SPEC-CM-012-A Conversation Transcript Protocol Format and protocol for files stored in conversations/

Changelog

Version Date Author Changes
1.3 2026-02-18 Chris Barlow Added conversations/ directory for conversation transcript storage, file naming convention, write protocol, and isolation rules (ADR-CM-019).
1.2 2026-02-14 Chris Barlow Added council-report.md format specification, lifecycle, and read/write protocol (ADR-CM-011).
1.1 2026-02-14 Chris Barlow Added quest.md format specification, progress log, NPC read/write protocol. Moved quest.md from reserved to fully specified. Resolved Open Question #5.
1.0 2026-02-14 Chris Barlow Initial specification