squads 0.1.0__tar.gz

squads-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v6.0.3
+      - uses: actions/setup-python@v6.2.0
+        with:
+          python-version-file: pyproject.toml
+      - uses: astral-sh/setup-uv@v8.2.0
+      - run: uv build
+      - run: uv publish

squads-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.3
+      - uses: actions/setup-python@v6.2.0
+        with:
+          python-version-file: pyproject.toml
+      - uses: astral-sh/setup-uv@v8.2.0
+      - run: uv sync --frozen
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format
+        run: uv run ruff format --check .
+      - name: pyright
+        run: uv run pyright
+      - name: pytest
+        run: uv run pytest

squads-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+.pytest_cache
+.ruff_cache
+.venv
+dist

squads-0.1.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.analysis.autoImportCompletions": true
+}

squads-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-08
+
+Initial release.
+
+### Added
+
+- **CLI** (`squads` / `sq`) for managing a team of AI agents as identified markdown with a
+  JIRA-like, globally-unique ID system. Item types: epic, feature, task, bug, decision (ADR),
+  review, guide, role, skill.
+- **Index** — a single `<squad>/.squads.json` with one global monotonic counter and all item
+  metadata; filelock'd, atomic writes. The `.md` frontmatter is the durable source of truth; the
+  index is rebuildable (`sq repair`, `sq repair --renumber`).
+- **Commands** — `init`, `adopt`, `create`, `list`, `show`, `tree`, `link`/`unlink`, `update`,
+  `status`, `comment`, `story`, `subtask`, `ref`/`refs`, `inbox`, `role`, `dev`, `skill`, `guide`,
+  `check`, `repair`, `sync`, `workflow`. Global `--dir` (target a squad) and `--at` (forge
+  timestamps for history-preserving migration).
+- **Workflow** — per-type status machines with validated transitions; parent rules
+  (task → feature, feature → epic); typed forward refs with computed backrefs; user stories &
+  subtasks with their own discussion; `@mention` inbox.
+- **Claude Code backend** — thin `.claude/` pointers to real definitions under the squad folder,
+  bundled `squads` skill + per-item-type skills, a managed `CLAUDE.md` section with
+  greeting-based impersonation, and a non-clobbering `settings.json` merge.
+- **8 bundled roles** + on-demand stack developers (`sq dev add`); the role↔item-type playbook.
+- **Docs** — README, plus `docs/` (workflow, internals, adoption, agents, tutorial, roles,
+  backends, recipes, faq); `py.typed`; MIT licensed.
+
+[Unreleased]: https://github.com/TheCaptainCat/squads/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/TheCaptainCat/squads/releases/tag/v0.1.0

squads-0.1.0/CLAUDE.md

@@ -0,0 +1,102 @@
+# CLAUDE.md — working on the squads codebase
+
+`squads` (`sq`) is a Python/uv Typer CLI that manages a team of AI agents on a code project:
+it bootstraps roles/skills and tracks work as identified markdown with a JIRA-like ID system.
+Claude Code is the first pluggable backend. This file guides work **on squads itself**.
+
+## Commands
+
+```bash
+uv sync                 # install deps + the sq entry point
+uv run pytest           # full suite (fast, all in tmp dirs)
+uv run sq <cmd>         # exercise the CLI
+uv build                # wheel/sdist (templates ship as package data)
+```
+
+## Architecture & layering
+
+```
+_cli → _service → (index store, backends, rendering)
+_models  shared, no internal deps
+```
+
+**Module privacy convention.** Every implementation module and subpackage is **private** —
+leading-underscore names (`_service.py`, `_models/`, `_backends/_claude_code/`, …). Package
+`__init__.py` files do **not** re-export (this is a CLI, not yet a library API), so internal code
+imports straight from the underscore modules (`from squads._models._item import Item`). The only
+non-empty inits are `squads/__init__` (`__version__`), `_cli/__init__` (the Typer `app`, the entry
+point `squads._cli:app`), and `_backends/_claude_code/__init__` (backend registration side-effect).
+Namespace-style imports use an alias to keep call sites readable: `from squads import _clock as clock`.
+
+- `_models/` — pydantic v2. `_item` (`Item`), `_index` (`SquadsDB`), `_enums` (`ItemType`/`Status`
+  + prefix→folder maps), `_markers` (sq anchor tags), `_config` (`.squads.toml`), `_extras`
+  (`ExtraKey`).
+- `_paths.py` — resolve the active squad folder (`--dir` > `.squads.toml` walk-up > default), map an
+  ID/type to its location, and guard `abspath` against path traversal.
+- `_index/_store.py` — the integrity core: filelock'd, atomic (`os.replace`) read-modify-write of
+  `<squad-dir>/.squads.json`; `allocate_id` bumps the **single global counter**; `load` wraps a
+  corrupt index in `SquadsError`.
+- `_sections.py` / `_itemfile.py` — marker-safe edits and frontmatter↔Item mapping.
+- `_workflow.py` — per-type status machines + `can_transition` + `TERMINAL`/`is_open` +
+  `ALLOWED_PARENTS`/`parent_allowed`/`parent_hint`.
+- `_rendering/` — Jinja2 (`StrictUndefined`); templates are package data under `_rendering/templates/`.
+- `_backends/` — `AgentBackend` ABC + registry; `_claude_code/` writes pointer files, managed skills
+  (real body under `<squad>/agents/skills/`, thin pointer in `.claude/`), and the CLAUDE.md section.
+- `_roles/_catalog.py` — the 8 bundled roles + dev name pool + `dev_role()`.
+- `_interactions.py` — the team **playbook**: which roles interact with each item type (`*dev`
+  sentinel = any `<tech>-dev` role). Drives the per-item-type managed skills (`sq-<type>`) and
+  `skills_for_role()`. Workflow cheatsheet partial: `_rendering/templates/workflow.md.j2` (shared by
+  the `squads` skill and `sq workflow`).
+- `_service.py` — orchestration; the logic behind each command. `_discussion.py` — comment/story/
+  subtask formatting + `@mention` extraction.
+- `_cli/` — Typer app (`__init__` wires sub-typers + the `--dir` callback + version notice);
+  one `_module` per command group; `_common.py` has the shared console/error decorator/parsers.
+
+## Invariants — keep these true
+
+1. **Frontmatter is the source of truth.** `.squads.json` is a rebuildable index; never store
+   anything in it that can't be reconstructed from the `.md` files (`sq repair` proves this).
+2. **Global counter.** One monotonic counter for all types; an ID's number is globally unique.
+   Allocate only inside `IndexStore.transaction()`.
+3. **Marker-safe edits only.** Touch file content solely via `_sections.py`; never rewrite an
+   agent-authored body. Markers are `<!-- sq:<tag> -->` / `<!-- sq:<tag>:end -->`.
+4. **Forward edges only.** `item.refs` holds outgoing refs; backrefs are computed by inversion
+   (`SquadsDB.backrefs`), never persisted.
+5. **`.claude/` files are pointers**, not content. Real definitions live under `squads/`.
+6. **Backends are pluggable.** Don't reach into `.claude/` outside a backend; go through the ABC.
+
+## Conventions / gotchas
+
+- **Escape dynamic output.** Rich treats `[...]` (e.g. a `[x]` checkbox) as markup — always wrap
+  user/content strings with `_cli._common.e()` when printing to the console or a table.
+- **Time is injectable.** Use `clock.now()` / `clock.iso()` so tests can freeze it
+  (`frozen_time` fixture); never call `datetime.now()` directly.
+- **Marker regex is strict.** `_sections.find_markers` only matches well-formed tags so prose like
+  `` `<!-- sq:* -->` `` in role files isn't linted as a real marker.
+- **User-facing errors** subclass `SquadsError`; the CLI's `@handle_errors` turns them into a clean
+  message + exit 1. Raise those, not bare exceptions.
+- **Templates are package data** — adding one means dropping a `.j2` under `_rendering/templates/`;
+  the wheel includes them automatically (verified in build).
+- **No `from __future__ import annotations`** — we target Python 3.14 (PEP 649 lazy annotations),
+  so forward refs work unquoted. Keep the import graph **acyclic** (verified); if a future edge
+  would create a cycle, use `if TYPE_CHECKING:` + a string annotation rather than a runtime import.
+- **`Item.extra` keys** come from `_models/_extras.py::ExtraKey` (imported as `X`) — never hand-write
+  the string keys; that's where role/dev/skill/ref metadata field names live.
+- **Strict typing** — `pyright` runs in strict mode and `ruff` (E/F/I/UP/B/W + C901/SIM/PERF/PTH/RUF/TRY/PLR0911-15,
+  max-complexity 12, max-args 8, TRY003 ignored) must stay clean:
+  `uv run pyright && uv run ruff check . && uv run ruff format --check .`. Annotate bare `dict`/
+  `list` (e.g. `dict[str, Any]`); Typer's `Option/Argument` call-defaults are why `B008` is
+  ignored under `_cli/`.
+
+## Testing
+
+`pytest` with `typer.testing.CliRunner`; the `project`/`svc` fixtures (`tests/conftest.py`) init a
+squad in a `tmp_path` and `chdir` into it — **all file generation stays in temp**. Cover behaviour
+through the service/CLI, and assert generated files (valid YAML frontmatter, intact markers,
+preserved body). When adding a feature, add a service-level test and a CLI smoke test.
+
+## Status
+
+All three planned phases are built and green. The only explicitly-deferred feature is
+project-level template/role overrides (e.g. `squads/.templates/`). The full design lives in the
+approved plan referenced from the project memory.

squads-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to squads
+
+Thanks for hacking on squads! This is a Python 3.14 / `uv` project. `CLAUDE.md` is the terse
+working-reference; this file is the friendly version. Deeper design lives in
+[docs/internals.md](docs/internals.md).
+
+## Setup
+
+```bash
+uv sync                 # install deps + the `sq` entry point into the project venv
+uv run sq --help        # exercise the CLI
+uv run pytest           # the test suite (fast; everything runs in tmp dirs)
+```
+
+## The gate (must stay green)
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright            # strict mode
+uv run pytest
+```
+
+Ruff runs an expanded ruleset (`E F I UP B W` + `C901 SIM PERF PTH RUF TRY PLR0911/12/13/15`,
+`max-complexity 12`, `max-args 8`, `TRY003` ignored). Pyright is **strict**. CI (`.github/workflows`)
+runs all four on pushes/PRs to `main`.
+
+## Conventions
+
+- **Private layout.** Every module and subpackage is underscore-prefixed
+  (`squads._service`, `squads._models._item`, …) and package `__init__`s don't re-export — import
+  straight from the underscore modules. (`squads/__init__` keeps `__version__`; `_cli/__init__` the
+  Typer `app`; `_backends/_claude_code/__init__` the registration side-effect.)
+- **Frontmatter is the source of truth.** `.squads.json` is a rebuildable index — never store
+  anything in it that can't be reconstructed from the `.md` files (`sq repair` proves it).
+- **Marker-safe edits only** — touch file content via `squads._sections`; never rewrite an agent's
+  body. Markers are `<!-- sq:<tag> -->` / `<!-- sq:<tag>:end -->`.
+- **Forward edges only** — `item.refs`; backrefs are computed by inversion, never persisted.
+- **`.claude/` is pointers + tool config**; real content lives under the squad folder.
+- **Time is injectable** — use `_clock.now()` / `_clock.iso()`, never `datetime.now()`.
+- **`Item.extra` keys** come from `squads._models._extras.ExtraKey` — don't hand-write the literals.
+- **Escape dynamic console output** with `_cli._common.e()` (Rich treats `[...]` as markup).
+- **No `from __future__ import annotations`** (Python 3.14 / PEP 649); keep the import graph
+  **acyclic** — if a future edge would create a cycle, use `if TYPE_CHECKING:` + a string annotation.
+
+## How to add things
+
+- **A template** → drop a `.j2` under `squads/_rendering/templates/`; it ships in the wheel as
+  package data automatically. Render with `squads._rendering._engine.render` (StrictUndefined).
+- **A command** → add it to the right `squads/_cli/_*` module (or a new one), wire it onto `app`
+  in `_cli/__init__`, and route logic through `Service`.
+- **An item type** → add to `ItemType` (`_models/_enums`) with its prefix + folder, give it a
+  workflow in `_workflow`, an item template, and (if agents author it) a `PLAYBOOK` entry in
+  `_interactions`.
+- **A backend** → see [docs/backends.md](docs/backends.md).
+
+## Tests
+
+`pytest` with `typer.testing.CliRunner`. The `project`/`svc` fixtures (`tests/conftest.py`) init a
+squad in a `tmp_path` and `chdir` into it — **all file generation stays in temp**. Cover behaviour
+through the service/CLI and assert on the generated files (valid frontmatter, intact markers,
+preserved body). When you add a feature, add a service-level test and a CLI smoke test. Time is
+frozen via the `frozen_time` fixture; the `_reset_clock_override` autouse fixture stops a forged
+`--at` from leaking between tests.
+
+## Commits / PRs
+
+Keep the gate green. PRs target `main` and run the `test` workflow. Releases are tagged `v*`, which
+triggers `publish.yml` (PyPI trusted publishing). Bump `__version__` (in `squads/__init__.py` and
+`pyproject.toml`) and add a [CHANGELOG.md](CHANGELOG.md) entry when behaviour or the managed
+templates change — a version bump is also what nudges existing squads to `sq sync`.

squads-0.1.0/CONTRIBUTORS.md

@@ -0,0 +1,8 @@
+# Contributors
+
+Thanks to everyone who has helped build squads.
+
+- **Pierre Chat** ([@TheCaptainCat](https://github.com/TheCaptainCat)) — author & maintainer
+- **Claude** (Anthropic) — design & implementation, paired via Claude Code
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to get involved.

squads-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Chat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

squads-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: squads
+Version: 0.1.0
+Summary: Manage a team of AI agents working on a code project: bootstrap roles & skills, track work with JIRA-like IDs in predictable markdown.
+Project-URL: Homepage, https://github.com/TheCaptainCat/squads
+Project-URL: Repository, https://github.com/TheCaptainCat/squads
+Project-URL: Issues, https://github.com/TheCaptainCat/squads/issues
+Author-email: Pierre Chat <pierrechat@outlook.com>, Claude <noreply@anthropic.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,cli,markdown,project-management
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: filelock>=3.13
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# squads
+
+A CLI (`squads` / `sq`) that manages a **team of AI agents** working on a code project.
+
+squads bootstraps agent **roles** and **skills**, produces markdown in a predictable structure,
+and gives every tracked artifact a stable JIRA-like ID (`TASK-000003`). Claude Code is the first
+supported backend; the design is pluggable.
+
+The real content lives under a relocatable `squads/` folder. The files written into `.claude/`
+are **thin pointers** to those definitions, plus a managed `squads` skill and a managed section in
+`CLAUDE.md` that teaches the agents how to work.
+
+---
+
+## Install
+
+Requires Python ≥ 3.14. Install as a **tool** so `squads` / `sq` land on your `PATH`:
+
+```bash
+# with uv (recommended)
+uv tool install squads          # from PyPI, once published
+uv tool install .               # from a local checkout
+
+# or with pipx
+pipx install squads             # from PyPI
+pipx install .                  # from a local checkout
+```
+
+Then `sq` is available everywhere:
+
+```bash
+sq --help
+sq --version
+```
+
+Try it once without installing, via `uvx` (or `pipx run`):
+
+```bash
+uvx --from squads sq --help     # or: uvx --from . sq --help  in a checkout
+```
+
+> **From source / development:** `uv sync` creates the project venv and exposes the CLI as
+> `uv run sq …`. The examples below use bare `sq` (tool install); prefix with `uv run` if you're
+> working from a source checkout.
+
+## Quickstart
+
+```bash
+cd your-project
+sq init --roles all                 # scaffold squads/, .claude/, CLAUDE.md
+sq create feature "User authentication" --desc "Login & sessions"
+sq create task "Validate token expiry" --parent FEAT-000010
+sq status TASK-000011 InProgress
+sq comment TASK-000011 --as architect -m "Reuse the clock abstraction" -m "@qa verify edges"
+sq tree
+```
+
+---
+
+## Concepts
+
+- **Items** — every tracked thing is an item with a type and a stable ID. Types: `epic`,
+  `feature`, `task`, `bug`, `decision` (ADR), `review`, `guide`, `role`, `skill`.
+- **Global IDs** — `PREFIX-NNNNNN` with a single global counter, so the number is unique across
+  all types (you never have both `TASK-000002` and `BUG-000002`). The prefix marks the type:
+  `EPIC FEAT TASK BUG ADR REV GUIDE ROLE SKILL`.
+- **Source of truth** — the markdown **frontmatter** is durable truth; `squads/.squads.json` is a
+  fast index that is fully rebuildable from the files (`sq repair`).
+- **sq-owned sections** — files carry invisible markers (`<!-- sq:body -->`, `<!-- sq:discussion -->`,
+  …). `sq` owns the frontmatter and marked sections (status, discussion); **agents write all other
+  prose directly** and must never touch the marker lines.
+- **Agents** — named roles (real name + slug, e.g. *Robert Architect* / `architect`). The `.claude/`
+  files are pointers to the real definitions under `squads/agents/`.
+
+### On-disk layout
+
+```
+your-project/
+├── .squads.toml                 # config (squad dir, backend, version, default role)
+├── CLAUDE.md                    # managed section: process + greeting impersonation
+├── .claude/
+│   ├── agents/<slug>.md         # POINTER → squads/agents/roles/ROLE-*.md
+│   └── skills/{squads,<slug>}/SKILL.md
+└── squads/                      # self-contained & relocatable (override with --dir)
+    ├── .squads.json             # the index: counter + all items + refs
+    ├── epics/ features/ tasks/ bugs/ adrs/ reviews/ guides/
+    └── agents/{roles,skills}/
+```
+
+### Status workflows
+
+| Type | Lifecycle |
+|------|-----------|
+| epic / feature / task / bug | `Draft → Ready → InProgress → InReview → Done` (+ `Blocked`, `Cancelled`) |
+| decision (ADR) | `Proposed → Accepted → Superseded` (+ `Rejected`, `Deprecated`) |
+| review | `Requested → InReview → ChangesRequested → Approved` (+ `Rejected`) |
+| guide | `Draft → Published → Deprecated` |
+| role / skill | `Draft → Active → Archived` |
+
+`sq status` validates transitions; use `--force` to override.
+
+---
+
+## Documentation
+
+Full docs (with diagrams) live in **[docs/](docs/README.md)**:
+
+- **[tutorial](docs/tutorial.md)** — a 15-minute, end-to-end first squad.
+- **[workflow](docs/workflow.md)** — who creates & links what, and the per-type status lifecycles.
+- **[agents](docs/agents.md)** — operating *as* an agent inside a squad.
+- **[roles](docs/roles.md)** — the bundled roster, bundles, and stack developers.
+- **[recipes](docs/recipes.md)** — copy-paste sequences · **[faq](docs/faq.md)** — common errors.
+- **[adoption](docs/adoption.md)** — migrating an existing project (`sq adopt`, `--at`).
+- **[internals](docs/internals.md)** / **[backends](docs/backends.md)** — under the hood & writing a backend.
+
+Contributing: **[CONTRIBUTING.md](CONTRIBUTING.md)** · contributors: **[CONTRIBUTORS.md](CONTRIBUTORS.md)** · changes: **[CHANGELOG.md](CHANGELOG.md)**.
+
+---
+
+## Command reference
+
+**Setup**
+- `sq init [--squad-dir squads] [--backend claude_code] [--roles all|core|minimal|<slugs>] [--no-claude] [--force]`
+- `sq adopt [--squad-dir squads] [--backend] [--roles] [--no-claude]` — bring an *existing* project under sq management (non-destructive; imports existing items). See [docs/adoption.md](docs/adoption.md).
+- `sq workflow` — print the team-workflow cheatsheet
+- `sq sync` — regenerate tool-owned managed files to the current version
+- `--dir PATH` (global) — operate on the squad folder at PATH instead of walking up to `.squads.toml`
+- `--at WHEN` (global) — forge timestamps (ISO 8601, UTC) for this command, to preserve history when migrating
+
+**Items**
+- `sq create epic|feature|task|bug|decision|review|guide TITLE [--parent ID] [--desc] [--label] [--ref ID] [--assignee] [--json]`
+- `sq list [--type|--status|--parent|--label|--assignee] [--json]` · `sq show ID [--json]` · `sq tree [ROOT_ID]`
+- `sq update ID [--title|--desc|--assignee|--add-label|--rm-label]` (`--title` renames the file)
+- `sq status ID STATUS [--force]` · `sq link CHILD --parent P` · `sq unlink CHILD`
+
+**Collaboration**
+- `sq comment ID -m "…" [-m "…"] [--as <slug|operator>] [--story USn|--subtask STn]` (use `@role` to notify)
+- `sq story add FEAT-ID [LABEL] [--json]` · `sq story list FEAT-ID`
+- `sq subtask add TASK-ID [LABEL] [--story USn] [--json]` · `sq subtask list TASK-ID` · `sq subtask done TASK-ID STn [--undo]`
+- `sq inbox <role>` — open items mentioning `@role`
+
+`story add` / `subtask add` **scaffold an empty block with a writable body region** and print
+(or return, with `--json`) the file and the marker/line range to write between — the agent then
+fills it with free-form paragraphs or bullet lists. The optional `LABEL` is just a short heading;
+the substance lives in the body. `sq` still owns the discussion and the subtask checkbox.
+
+**Cross-linking**
+- `sq ref add FROM TO [--kind related|blocks|implements|fixes|addresses]` · `sq ref rm FROM TO`
+- `sq refs ID [--out|--in|--all] [--json]` (forward edges stored; backrefs computed)
+
+**Agents**
+- `sq role list [--available] | show <slug> | activate <slug> | regen ID | rm ID [--purge]`
+- `sq dev add --tech <t> [--name] [--model] | list` — stack-specific developers
+- `sq skill add NAME [--desc|--when-to-use|--allowed-tools] | list | show | regen | rm [--purge]`
+- `sq guide add TITLE [--tech] [--tag] | list`
+
+**Maintenance**
+- `sq check` — lint markers, dangling parent/ref IDs, invalid status, index drift
+- `sq repair [--renumber]` — rebuild the index from frontmatter; `--renumber` resolves merged ID collisions
+
+---
+
+## Working with agents
+
+After `sq init`, open Claude Code in the project. `CLAUDE.md` tells the agents how the process
+works and how to **impersonate a role on greeting**: say *"Hi Robert"* and Claude becomes Robert
+Architect; with no name it defaults to **Catherine Manager**, who triages and routes the request.
+
+The bundled roster: Catherine Manager (`manager`, default), Robert Architect (`architect`),
+Olivia Lead (`tech-lead`), Paul Reviewer (`reviewer`), Mara Tester (`qa`), Hugo Ops (`devops`),
+Nina Product (`product-owner`), Theo Writer (`tech-writer`). Add stack developers with `sq dev add`.
+
+Agents create items with `sq`, get back the file path, write the body directly, and hand off via
+`sq comment … @role`. Status and discussion stay owned by the CLI.
+
+`sq init`/`sq sync` also generate a **skill per item type** (`sq-feature`, `sq-task`, `sq-bug`, …)
+with role-directed guidance, plus the general `squads` skill. Each role's `.claude/agents/<slug>.md`
+pointer preloads (via `skills:`) only the skills for the item types that role manages — so the
+product owner gets `sq-feature`/`sq-epic`, a developer gets `sq-task`/`sq-bug`/`sq-review`, and the
+manager (who triages rather than owning a type) gets just `squads`. Run `sq workflow` for the
+cheatsheet.
+
+### Team workflow
+
+squads encodes a light division of labour (enforced by validation + `sq check`):
+
+- The **product owner** writes **features** and their **user stories**
+  (`sq create feature`, `sq story add`).
+- The **tech lead** writes **tasks**. A task's **parent is the feature** it implements, and each
+  **subtask maps to one user story**:
+  ```bash
+  sq create task "Token validation" --parent FEAT-000002
+  sq subtask add TASK-000003 "Validate expiry" --story US1   # US1 must exist in FEAT-000002
+  ```
+- A task may instead/also link a **bug** or **review** via typed refs — or nothing if it's purely
+  technical:
+  ```bash
+  sq ref add TASK-000003 BUG-000009 --kind fixes
+  sq ref add TASK-000003 REV-000010 --kind addresses
+  ```
+
+A task's parent must be a feature (link a bug/review with a ref, not as parent); a feature's parent
+must be an epic. Invalid links are rejected at create/link time and flagged by `sq check`.
+
+---
+
+## Git notes
+
+Commit `.squads.toml`, the `squads/` folder, `CLAUDE.md`, and `.claude/` (the pointers + squads
+skill). `squads/.gitignore` already excludes the lock/temp files. On a merge conflict in
+`.squads.json`, take either side and run `sq repair` (the frontmatter is the truth);
+if two branches reused an ID number, run `sq repair --renumber`.