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 "…"`.
- **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`.
- **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. 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`).

## 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` |
| `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)` |
| `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`, `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; the reflog records a reconstructable removal line that explains each gap.

## Ref kinds

The vocabulary is closed — exactly nine kinds, no custom extensions in 1.0. Use `sq <type> <n> ref add <id> --kind <kind>`.

| Kind | Meaning | Direction convention | Consumer |
|---|---|---|---|
| `related` | Generic cross-reference (default) | `A related B` lives on A | Navigation |
| `blocks` | A is blocking B; B cannot proceed while A is open | `A blocks B` lives on **A** (the blocker) | `sq blocked` |
| `depends-on` | A depends on B; A cannot proceed while B is open. Equivalent to `B blocks A` — `A depends-on B` ≡ `B blocks A` | `A depends-on B` lives on **A** (the dependent) | `sq blocked` |
| `implements` | A implements the requirement or spec described by B | `A implements B` lives on A | Navigation |
| `fixes` | A (the resolving work) fixes the problem tracked by B | `A fixes B` lives on A | `sq check` ref-rule warnings |
| `addresses` | A (the resolving work) addresses or follows up on B (feedback, a review) | `A addresses B` lives on A | `sq check` ref-rule warnings |
| `supersedes` | A (a newer decision) supersedes B (an older one); B's status should be Superseded | `A supersedes B` lives on **A** (the newer decision) | `sq check` decision warnings |
| `duplicates` | A (a later filing) duplicates B (the original); A is usually closed as Cancelled | `A duplicates B` lives on **A** (the later filing) | Navigation |
| `scopes` | A (a skill) is scoped to role B; B's generated pointer preloads A | `A scopes B` lives on **A** (the skill) | Preload resolver, retirement gate |

`blocks` and `depends-on` are two spellings of the same dependency: use whichever fits your authoring context. Bare `ref add <id>` (no `--kind`) defaults to `related`.

## Common commands

```bash
sq create task "Title" --author <your-slug> [--parent FEAT-<n>] [-m "body…"]  # also: epic|feature|bug|decision|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
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

