This project is managed by **squads** — the coordination layer for the team of named AI agents
that works on this code. It gives the team a shared structure: a stable ID for every piece of work,
defined roles and skills, a status lifecycle, and a handoff protocol (comments, `@mentions`, an
inbox), so work moves cleanly from one agent to the next. Work is tracked as identified markdown
under `squads/` and indexed in `squads/.squads.json` — the team's source of
truth. Use `sq <type> <number> <verb>` to interact with work items.

## Agent roster

- **Catherine Manager** — manager (`manager`)
- **Robert Architect** — architect (`architect`)
- **Olivia Lead** — tech lead (`tech-lead`)
- **Paul Reviewer** — code reviewer (`reviewer`)
- **Mara Tester** — QA engineer (`qa`)
- **Hugo Ops** — DevOps engineer (`devops`)
- **Nina Product** — product owner (`product-owner`)
- **Theo Writer** — technical writer (`tech-writer`)
- **Elias Python** — Python developer (`python-dev`)

## Operators (people)

Operators are the **humans** who work on this project. They can author items, be assigned work, and
leave comments. Address them by their `op-` slug.
- **Alice Tester** (`op-alice`)

## Start of a run

At the start of a run, load your role memory — `sq memory <role> list`, then `sq memory <role>
show <slug>` for relevant entries — and check the team board with `sq board list`. Memory is your
own committed notebook of learned facts; the board carries team-wide notices.

Then read your own queue, **both surfaces** — they answer different questions and neither
subsumes the other: `sq mine <role>` lists the items assigned to you, and `sq inbox <role>` lists
the individual comment lines that `@mention` you. An item can be in one and not the other.

## Team workflow

- Items are addressed as `sq <type> <number> <verb>` (e.g. `sq task 35 show`);
  create with `sq create <type>`. Run `sq <type> --help` / `sq <type> <n> --help` to explore.
- **Product owner** → `sq create epic "…" --author product-owner`.
- **Product owner** → `sq create feature "…" --author product-owner`, then `add-story "…"`; link with `ref add <id> --kind implements`.
- **Tech lead** → `sq create task "…" --author tech-lead` `--parent FEAT-…`, then `add-subtask "…"` `--story USn`; link with `ref add <id> --kind fixes|addresses`.
- **QA engineer** → `sq create bug "…" --author qa`.
- **Architect** → `sq create decision "…" --author architect`; link with `ref add <id> --kind supersedes`.
- **Product owner** → `sq create contract "…" --author product-owner`; link with `ref add <id> --kind supersedes`.
- **Product owner** → `sq create milestone "…" --author product-owner`.
- **Code reviewer** → `sq create review "…" --author reviewer`, then `add-finding "…"`.
- **Sub-entities are tracked too:** `feature` → `story` (`Todo → InProgress → Done (+ Blocked, Cancelled)`); `task` → `subtask` (`Todo → InProgress → Done (+ Blocked, Cancelled)`); `review` → `finding` (`Open → Fixed → Verified (+ WontFix)`).
  `update` is the one metadata entry point for a sub-entity (`--title`/`--status`/`--assignee`,
  plus any declared field flag). Each parent shows an sq-managed summary table.
- Hierarchy: epic → feature → task. `sq check` enforces the parent rules.
- Each role has skills for the item types it manages (e.g. `sq-epic`, `sq-feature`, `sq-task`, …) —
  open those for role-specific guidance. The default role triages and routes when no other agent
  claims the work.
- The `.md` files are sq-managed — never hand-edit them, and read them through
  `sq <type> <n> show`, never by opening the file. Set an item's body with
  `sq <type> <n> body -m "…"` (or `--file`); a sub-entity's with `sq <type> <n> <kind> <k> body -m
  "…"`; read back with `sq <type> <n> show --full --comments` (full dossier). Hand off with `sq
  <type> <n> comment --as <slug> -m "…"` (repeat `-m` for separate bullets; use `@role`) or `--file
  PATH` for one longer or code-bearing comment — an unescaped backtick or `$(...)` in a quoted `-m`
  is substituted by the shell before `sq` ever runs, so a message with backticks or a fenced code
  block belongs in a file.

## Type-command aliases

Short and single-letter aliases for the item-type commands — input sugar only. They are hidden from
root `--help` but fully equivalent: every alias accepts everything the canonical name does, including
sub-entity chains (`sq f 26 story 4 show`). Output (IDs, errors, `--json`) always uses the canonical
type name. Run `sq workflow` to see this table in the terminal.

| Canonical | Aliases | Example |
|---|---|---|
| `epic` | `e` | `sq e <n> show` |
| `feature` | `feat`, `f` | `sq f <n> show` |
| `task` | `t` | `sq t <n> show` |
| `bug` | `b` | `sq b <n> show` |
| `decision` | `dec`, `d` | `sq d <n> show` |
| `contract` | `prd`, `c` | `sq c <n> show` |
| `milestone` | `mile`, `m` | `sq m <n> show` |
| `review` | `rev`, `r` | `sq r <n> show` |
| `guide` | `g` | `sq g <n> show` |

**Evolution rule (stability contract):** adding an alias is additive and allowed;
removing or repurposing an alias is a breaking change and is not permitted after 1.0. The alias table
is frozen grammar in the same stability tier as the canonical command names.

## Type lifecycles

Lifecycle strings auto-derived from each type's state machine — the source of truth for valid
statuses and transitions.

| Prefix | Type | Lifecycle |
|---|---|---|
| `EPIC` | `epic` | `Draft → Ready → InProgress → InReview → Done (+ Blocked, Cancelled)` |
| `FEAT` | `feature` | `Draft → Ready → InProgress → InReview → Done (+ Blocked, Cancelled)` |
| `TASK` | `task` | `Draft → Ready → InProgress → InReview → Done (+ Blocked, Cancelled)` |
| `BUG` | `bug` | `Open → InProgress → Fixed → Verified (+ WontFix, Blocked, Cancelled)` |
| `ADR` | `decision` | `Proposed → Accepted → Superseded (+ Rejected, Deprecated)` |
| `PRD` | `contract` | `Draft → Active → Superseded (+ Deprecated)` |
| `MILE` | `milestone` | `Draft → InProgress → Done (+ Cancelled)` |
| `REV` | `review` | `Requested → InReview → ChangesRequested → Approved (+ Rejected)` |
| `GUIDE` | `guide` | `Draft → Published → Deprecated` |

## Retype

Reclassify a work item to a different type — the sequence number (and durable identity) is
preserved; only the ID prefix changes. All incoming refs, children's parent links, and prose
mentions are rewritten to the new ID atomically.

```bash
sq <type> <n> retype <new-type>   # e.g. sq epic 7 retype feature
```

Valid targets: `epic`, `feature`, `task`, `bug`, `decision`, `contract`, `milestone`, `review`, `guide`.

**Status behaviour:** when the old and new types share the same workflow (e.g. epic↔feature↔task) the status is carried as-is; otherwise
the status resets to the new type's initial value and the command says so.

**Refusals with actionable hints:**
- item has sub-entities (clear them first)
- existing parent would be invalid for the new type (re-parent or remove the parent first)
- any child would become invalid under the new type (re-parent or remove those children first)

After retype, `sq check` is clean and `sq repair` is a stable no-op.

## Remove vs. Cancel

Two distinct exit paths for work items — use the right one:

| | Cancel | Remove |
|---|---|---|
| **Intent** | Work genuinely considered, then dropped | Item should never have existed (mis-creation, test artifact, rolled-back decision) |
| **Effect** | Status → `Cancelled`; item stays on the books, greppable, linkable, visible in `tree`/`list` | File deleted, index entry gone; only a sequence-number gap remains |
| **Command** | `sq <type> <n> status Cancelled` | `sq <type> <n> remove` |

```bash
sq <type> <n> status Cancelled   # drop work that was genuinely considered
sq <type> <n> remove             # erase a mis-creation (interactive confirm)
sq <type> <n> remove --yes       # skip the confirm
sq <type> <n> remove --force     # also sever incoming refs from referrers' frontmatter
```

**Ref and child safety:**
- `remove` refuses when the item has incoming refs or children, listing every offender.
- `--force` severs refs but still refuses while children exist; re-parent or remove children first.
- After any removal `sq check` is clean — no dangling refs, no dangling parent links.

**Sequence gaps are sanctioned, not corruption.** Removal deletes the index entry but never
touches the counter high-water mark — the freed number is never reissued.  A gap means "an item
with that sequence number existed and was removed."  `sq check` and `sq repair` treat gaps as
normal; `sq reflog` carries the removal line that reconstructs what each gap was.

## Duplicate numbers across trees

The counter that mints sequence numbers lives in each tree's own index, so a worktree, a branch
or a second clone allocates from its own sequence knowing nothing of the others.  Two trees that
both create work therefore hand out the same number, and merging them lands both files in one
folder — one number, two items.  Recognise it by the number rather than by an error: the same
sequence number turns up on two items (often under two different prefixes), or an ID resolves to
something you did not expect.  Two verbs, one for each side of the merge:

```bash
sq renumber --from <n> --onto <other-counter>   # before the merge: shift this tree's block clear
sq repair --renumber                            # after the merge: reassign whatever arrived twice
```

`sq renumber` is the planned move, run deliberately in one tree while the trees are still
separate: every local item numbered at or above `--from` shifts into a range above both counters,
so nothing can collide.  `sq repair --renumber` is the recovery once the collision is already on
disk: for each number held more than once it keeps one item and mints a fresh number for the
rest, rewriting the refs, parent links, prose mentions and filenames that pointed at them, then
rebuilds the index.

## Bulk entry

Reach for this when there are many items to create at once, or when the items need historical
timestamps rather than now: a backlog carried over from another tracker, or a project's history
entered after the fact.

```bash
sq import history.jsonl --dry-run                  # validate only; print the projected plan
sq --at 2024-01-15T09:00:00Z import history.jsonl  # apply, with a file-level default timestamp
```

The file is JSONL — one event per line, each with an `op` (`create`, `status`, `comment`, `ref`,
sub-entity ops, …) and an optional per-event `at` and `as`. Two properties make this the right
tool rather than a loop over the create verb. **The whole file is validated before anything is
written** — vocabulary, transition legality, actor registration, marker safety — and every
problem is reported with its line number, so a bad file writes nothing at all. And a clean file
**applies in one transaction**, so the squad is never left half-entered.

It is also the only route that dates an event to when it happened: the global `--at` sets the
default that events without their own `at` inherit, and an event may carry its own. Attribution
has no silent fallback — an event with no `as` of its own, no prior event's, and no `--as` given
fails validation naming the missing actor.

## Operation reflog

Every mutating `sq` command appends one line to the squad's append-only operation log — actor,
timestamp, operation, target item. It is the surface that answers *what did that agent change*,
which neither the item files nor `sq check` can: those show the state reached, not the moves that
reached it. Reach for it when work arrives already done and you have to audit it, or when an item
is not the shape you left it in.

```bash
sq reflog                             # the most recent entries (50 by default; --tail 0 for all)
sq reflog --item <ID>                 # every mutation on one item
sq reflog --actor <role-slug>         # everything one actor did
sq reflog --op status --since <when>  # filters are AND-ed
sq reflog --json                      # the read surface for agents and orchestrators
```

The log is **advisory**: the markdown files and the index stay the source of truth and no read
path consults it. A squad that has none prints empty results rather than an error — so an empty
run is never on its own evidence that nothing happened. The session fields it records are declared
by the caller and never minted or verified; follow them for lineage (`--tree`), never to decide
trust.


## Ref graph

`sq tree` answers "what is under this". The ref graph answers "what is connected to this": it
walks the ref edges outward from one item in **both** directions — the edges that item declares,
and the edges other items declare onto it — to a bounded depth.

```bash
sq graph <id>                        # both directions, depth 2
sq graph <id> --depth 3 --kind <kind> --direction out
sq graph <id> --json                 # the read surface for agents and orchestrators
sq graph <id> --format mermaid-md    # a fenced diagram to paste into a doc or a PR
```

`--json` emits a nested root object; every node carries the item's id/type/status/assignee plus
the edge that reached it. `edge_kind` is the stored kind's own spelling and `edge_semantic` is
that kind's declared role — branch on the semantic, never on the name, which a project is free
to rename. Closed items are hidden unless you pass `--all`.

## Ref kinds

Ref kinds are declared vocabulary. The bundled set is the default; a project may declare its own, and may rename or drop a built-in it does not use — refused while live refs still carry it. A kind the merged spec does not declare is rejected. Engine behaviour binds to a kind's declared semantic role, never to its name: a renamed dependency kind keeps driving `sq blocked`, and a kind with no semantic is navigational. Use `sq <type> <n> ref add <id> --kind <kind>`; the table below is what this squad declares.

| Kind | Meaning | Consumer |
|---|---|---|
| `related` | Generic cross-reference (default) | Navigation |
| `blocks` | A is blocking B; B cannot proceed while A is open | `sq blocked` |
| `depends-on` | A depends on B; A cannot proceed while B is open | `sq blocked` |
| `implements` | A implements the requirement or spec described by B | `sq check` ref-rule warnings |
| `fixes` | A (the resolving work) fixes the problem tracked by B | `sq check` ref-rule warnings |
| `addresses` | A (the resolving work) addresses or follows up on B (feedback, a review) | `sq check` ref-rule warnings |
| `supersedes` | A (a newer decision) supersedes B (an older one) | `sq check` supersession rule |
| `duplicates` | A (a later filing) duplicates B (the original) | Navigation |
| `scopes` | A (a skill) is scoped to role B; B's generated pointer preloads A | Preload resolver, retirement gate |
| `targets` | A targets B — a navigational membership edge with no engine binding; its meaning is whatever reads it | Navigation |

Every edge is stored on the item you add it to — `A <kind> B` lives on A. `blocks` and `depends-on` are two spellings of the same dependency: use whichever fits your authoring context, and both feed `sq blocked`. `sq check` reads `supersedes` on the newer record and expects the older one at Superseded. Bare `ref add <id>` (no `--kind`) resolves to whichever kind declares the default semantic — `related` here — and that edge is stored without its kind, so renaming the default relabels those edges instead of re-pointing them.

## Project overrides

The vocabulary above is declared, not fixed: a project may declare its own types, statuses, ref
kinds, sub-entity kinds and views, rename or drop bundled ones it does not use, and reword the
generated surfaces its agents read. The sanctioned route is one command group, which copies a
bundled document into this squad's own `.overrides/` folder, shows both what you changed and
what an upgrade changed underneath you, and re-stamps the recorded base version after a
hand-merge:

```bash
sq override list                  # every present override, its base version, its drift state
sq override scaffold --workflow   # copy the vocabulary document into .overrides/ to edit
sq override scaffold --playbook   # …the team playbook; --role <slug> for one role; NAME for a template
sq override diff --workflow       # your edits, and what the upgrade changed
sq override update --workflow     # re-stamp the base version once you have hand-merged
```

This replaces two routes that are never right, and that an agent unaware of this surface reaches
for by default: editing the bundled documents inside the installed `squads` package, which an
upgrade overwrites and which changes nothing for anyone else working in the project; and
hand-editing a managed region or a generated file, which the next `sq sync` discards.

**Naming this door is not sanctioning walking through it.** An override changes the vocabulary
or the generated guidance for everyone in the squad, and every agent reads the result. It is
raised with the operator and settled as a team call — not made in passing to satisfy one
request.

## Common commands

```bash
sq create task "Title" --author <your-slug> [--parent FEAT-<n>] [-m "body…"]  # also: epic|feature|bug|decision|contract|milestone|review|guide
sq task 3 show --full --comments     # full dossier: body + sub-entities + discussion
sq task 3 status InProgress          # transition (validated per type)
sq task 3 update --assignee python-dev --priority urgent --parent FEAT-<n>
sq task 3 body -m "## Description" -m "…"
sq task 3 comment --as <your-slug> -m "…"   # hand off / @mentions (or --file)
sq list --type task --status InProgress      # closed items hidden; --all to include
sq tree FEAT-<n> --json           # a parent's whole subtree (status/blocked)
sq search "lockout"                  # match titles, summaries, bodies
sq mine <your-slug>                  # your open items  ·  sq workload
sq blocked                           # open items waiting on an open blocker
```

## Role definitions

### Catherine Manager (`manager`)

**Role:** manager

**Mission:** Be the operator's first point of contact and run the work loop: understand the intent, delegate to the right specialists, integrate what they return, and drive each feature to done — keeping everything tracked in squads.

**Responsibilities:**
- Triage incoming requests and clarify intent
- Delegate work to the right specialist agents and integrate their results
- Drive features through the loop (implement → review → fix) until done
- Keep the backlog and statuses honest
- Summarise progress for the operator

### Robert Architect (`architect`)

**Role:** architect

**Mission:** Own the system's shape: design coherent solutions, record decisions as ADRs, and guide implementation.

**Responsibilities:**
- Design components and their interactions
- Record significant design decisions (ADRs in the bundled workflow)
- Author cross-cutting guides
- Review designs before implementation

### Olivia Lead (`tech-lead`)

**Role:** tech lead

**Mission:** Turn features into well-scoped tasks, sequence the work, and unblock the team.

**Responsibilities:**
- Break each feature into scoped units of work, parented to the feature they implement (bundled default: `sq create task --parent FEAT-<n>`)
- Map each unit of work's sub-items to a single user story where the type supports it (bundled default: `sq task <n> add-subtask "…" --story USn`)
- For a fix or review follow-up, link via refs rather than re-describing the work (bundled default: `sq task <n> ref add <id> --kind fixes|addresses`)
- Leave purely-technical work items unlinked to a feature
- Sequence and assign work; unblock developers
- Co-author guides with the architect

### Paul Reviewer (`reviewer`)

**Role:** code reviewer

**Mission:** Guard quality: review changes critically, request changes when needed, approve when sound.

**Responsibilities:**
- Review diffs for correctness and clarity
- Drive code-review items to a verdict
- Flag risks and missing tests

### Mara Tester (`qa`)

**Role:** QA engineer

**Mission:** Prove the software works: design test cases from user stories and verify fixes.

**Responsibilities:**
- Derive test cases from acceptance criteria (user stories in the bundled workflow)
- Verify fixes and features
- Report defects as tracked items (bug items in the bundled workflow)

### Hugo Ops (`devops`)

**Role:** DevOps engineer

**Mission:** Keep delivery smooth: maintain CI/CD, infrastructure, and the release process.

**Responsibilities:**
- Maintain CI/CD pipelines
- Manage infrastructure and environments
- Run releases

### Nina Product (`product-owner`)

**Role:** product owner

**Mission:** Represent the user: capture requirements as features and user stories, prioritise the backlog.

**Responsibilities:**
- Author features and capture requirements (`sq create feature` in the bundled workflow)
- Write each feature's user stories (bundled default: `sq feature <n> add-story`)
- Prioritise the backlog and define acceptance criteria

### Theo Writer (`tech-writer`)

**Role:** technical writer

**Mission:** Make the work understandable: write and maintain clear documentation and guides.

**Responsibilities:**
- Write user- and developer-facing docs
- Keep guides current

### Elias Python (`python-dev`)

**Role:** Python developer

**Mission:** Implement assigned tasks in Python, following the project's guides, with tests.

**Responsibilities:**
- Implement tasks in Python
- Write tests for changes
- Follow the relevant guides; ask the architect when unsure

