@nidvue/teamwork 0.0.0-stage → 1.1.1

package/skills/teamwork/references/Adapters.md

@@ -0,0 +1,112 @@
+# Adapters - running the team on any agent host
+
+The team is a **protocol**, not a product feature. Everything normative in this
+skill - the workspace format, acceptance-criteria records, the two-stage gate,
+the hash-chained ledger, the test-layer matrix, `AGENTS.md` - is host-independent
+and lives in files the team owns. Only six operations need a host to provide a
+mechanism, and this file maps each one to the concrete tool of a given host.
+
+Never hard-code a host tool in a normative step. Name the operation, then use the
+adapter. If a host cannot provide an operation, use its documented degraded mode -
+the gates still hold, only the concurrency drops.
+
+This file is the only **adoption surface** that names a concrete host. Every other surface
+(`SKILL.md`, README, install guide, quickstart) describes one generic protocol and
+points here, so a new host is a new column, never a rewrite of the instructions.
+
+## The six operations
+
+| # | Operation | What the team needs |
+|---|---|---|
+| 1 | **Spawn a teammate** | start a long-lived agent with a persona and its own context |
+| 2 | **Delegate one-shot work** | run a bounded, isolated task and take its result |
+| 3 | **Message an agent** | send a direct or broadcast instruction |
+| 4 | **Inspect teammate state** | see who is idle, busy, stuck; read their last output |
+| 5 | **Re-wake on a schedule** (pulse) | periodic trigger to feed idle lanes |
+| 6 | **Close the team** | stop the teammates and release the lanes |
+
+## Host mapping
+
+| Operation | Pi | Claude Code | opencode | Codex / Cursor / Windsurf / Gemini CLI | Generic (no agent runtime) |
+|---|---|---|---|---|---|
+| 1 spawn | `subagent({agent, task})` - one call per lane, `async: true` keeps the CEO free while it runs; a *persistent* teammate needs a teams-style extension, the default host gives bounded runs | `Agent`/`Task` tool with a `.claude/agents/<name>.md` persona | `.opencode/agent/<name>.md` + the Task tool | run the CLI as a subprocess (`codex exec`, `cursor-agent`) | `bash` background process + a prompt file |
+| 2 one-shot | `subagent({agent,task})` | `Task` tool, single agent | Task tool / a separate `opencode run` | `codex exec "<task>"` | one `bash` invocation, result to a file |
+| 3 message | child to parent: `contact_supervisor` / `subagent_supervisor({action:"reply"})`; parent to child: `subagent({action:"steer"/"resume", id, message})` | `SendMessage` / prompt injection | agent-to-agent message | write to the agent's inbox file | append to `Agents/<Name>/Inbox.md` |
+| 4 inspect | `subagent({action:"status", id})` and `subagent_supervisor({action:"list"/"pending"})` for the runs | agent status / task list | session list | process list + worklog | `teamwork.py board` + `pulse` + `WorkLog.md` |
+| 5 pulse | `subagent({action:"schedule.create", options:{every:"5m"}})` | no built-in scheduler: `Bash` background loop, `/loop`, or host `cron` running `claude -p` | no scheduler: `cron`/systemd running `opencode run` | host `cron` / `watch` / CI schedule | `cron`, `systemd` timer, or a `while` loop running `teamwork.py pulse --commit` |
+| 6 close | a bounded run ends with its own task; stop a live one with `subagent({action:"stop", id})` and list what still runs with `subagent_supervisor({action:"list"})` | stop the subagents / end the session | stop sessions | kill the processes | `pkill` the lanes, `teamwork.py clean` |
+| skill install | `~/.pi/agent/skills/<name>/SKILL.md` | `.claude/skills/<name>/SKILL.md` (Agent Skills format - this file already matches: `name` + `description` frontmatter) | `AGENTS.md` + `.opencode/command/<name>.md` | `AGENTS.md` (every one of these reads it) | `AGENTS.md` + this directory |
+
+The Pi column was verified against the installed `pi-subagents` package on
+2026-10-19 (pi 1.3.0): it exposes `subagent`, `subagents_enable`,
+`subagent_supervisor`, `contact_supervisor` and `structured_output`, and **no
+`teams(...)` tool**. A host that does provide a teams-style tool maps the same
+four operations to
+`teams({action:"delegate"/"message_dm"/"member_status"/"team_done"})`.
+
+`AGENTS.md` at the project root is the universal contract: Claude Code, opencode,
+Codex, Cursor, Windsurf, Gemini CLI, Aider and Pi all read it. Write the team
+constitution there once (`teamwork.py agents-md`) and every host inherits it.
+
+## Degraded modes (still complete, just slower)
+
+- **No scheduler** (operation 5): run `teamwork.py pulse --commit` on a host `cron`
+  entry, or have the CEO re-issue the pulse prompt at milestones, or simply have
+  each lane self-serve with `teamwork.py task next <name>` between turns. The rule
+  "never let an idle lane sit while runnable work exists" is unchanged; only the
+  automation of the wake-up differs.
+- **No teammate tool** (operation 1/2): the same role charters are executed
+  sequentially by one agent that switches hats, claiming tasks from the same
+  shared queues. The evidence gates, the Reviewer separation and the ledger are
+  unaffected - which is the point: the protocol does not depend on parallelism.
+- **No message tool** (operation 3): the mailbox is already a file
+  (`Agents/<Name>/Inbox.md`); writing to it is a valid message on every host.
+- **No `teams` tool**: spawn with the host's own CLI in a `bash` job and point it
+  at `Agents/<Name>/StartHere.md` - the startup routine is identical.
+- **Only bounded runs** (Pi's `subagent`, a CLI job): fan the lanes out as
+  concurrent calls instead of persistent teammates - one Reviewer instance per
+  call, each starting from its own `StartHere.md`. Bounded runs cannot see each
+  other, so the **board is what keeps them apart**: the CEO fans deliverables out
+  with `pulse --commit` and every lane takes work with
+  `review ... --claim --by <lane>` / `task next`, which is exactly why a claim is
+  a record and not a handshake. Two Reviewer lanes that skip the claim will
+  review the same deliverable twice.
+
+## Host detection also drives model routing
+
+The same detection that picks the adapter picks the model: `teamwork.py model auto`
+reads the host (pi, claude, opencode, codex, cursor, gemini) and the model that host
+exposes, then routes the strongest available model to the decision lanes and the
+economy model to the mechanical lanes; `TEAMWORK_AGENT_HOST` pins the detection when
+the markers are ambiguous. Policy: [Concurrency](Concurrency.md).
+
+## The skill copy is the thing that runs
+
+Every host reads a *copy* of this skill from its skills directory, so the copy has
+to follow the remote. One command owns that on every host:
+
+```sh
+teamwork refresh            # fetch origin/main, then mirror into the host's skills dir
+teamwork refresh --check    # drift only, writes nothing, exit 1 when stale
+teamwork refresh --dest ~/.agents/skills/teamwork   # another host's directory
+teamwork refresh --mirror --repo <url>             # no checkout yet: create the mirror once
+```
+
+Measured failure this prevents: a host copy with an old `SKILL.md` and eight
+engine modules missing - the engine imported `config`/`gitutil`/`records` fine
+from the checkout and failed from the installed copy. A dirty checkout is
+mirrored, never reset; files the source dropped are deleted; a host reload is
+required after a write and the command says so.
+
+## Rules
+
+1. **The engine is the constant.** `teamwork.py` (stdlib only, Python 3.9-3.13) is
+   the only thing a host must be able to run. It never calls a host API.
+2. **State lives in git and in `.pi/`.** Nothing important lives in a host's
+   private memory: a teammate that dies and is respawned on another host resumes
+   from `StartHere.md`, the task queue and the ledger.
+3. **One voice to the user** stays true on every host: only the CEO reports.
+4. **A missing capability is not a red line.** Record the adapter used and the
+   degradation in the task evidence; never fake a tool call that the host lacks.
+5. **Adding a host** means adding a column here plus a smoke test that the six
+   operations exist in some form - not changing the protocol.

package/skills/teamwork/references/Audit.md

@@ -0,0 +1,120 @@
+# Recording, traceability and audit
+
+Reference for the /teamwork skill. Loaded on demand.
+
+Related: [Evidence](Evidence.md) | [Roles](Roles.md) | [Engineering](Engineering.md) | [State](State.md) | [Docs](Docs.md) | [Testing](Testing.md) | [Concurrency](Concurrency.md)
+
+## What is recorded
+
+Every piece of state is a record with provenance, not a note in a chat:
+
+| Record | Where | Provenance |
+|---|---|---|
+| Memory entry | `Roles/<Role>/ShortTermMemory.md`, `LongTermMemory.md` | `by`, `src`, `rev` on every entry |
+| Task | `Roles/<Role>/TaskQueue.md` | `claimed_by`, `branch`, `pr`, `area`, `evidence`, `reviewer`, `merge_commit`, `forced` |
+| Acceptance criterion | `Criteria.md` | owner + the verifying instance and its evidence |
+| Test layer | `Tests.md`, `TestPlan.md` | owner role, runner, command, evidence, revision |
+| Review / PR | `Reviews.md` | author, branch, reviewer, verdict, merge revision |
+| Dispute | `Disputes.md` | raiser, opponent, every round, signatures, ruling |
+| Decision | `docs/Team/Decisions.md` | decider, evidence, falsifier, consequences |
+| Accepted result | `docs/Team/Archive.md` | what shipped, by which instance, verified how, at which revision |
+| **Every mutation** | `Ledger.jsonl` | timestamp, actor, role, action, target, detail, revision |
+
+Nothing is written without naming who wrote it and what it came from.
+
+## The ledger
+
+`Ledger.jsonl` is append-only. Each line is one record:
+
+```json
+{"ts":"2026-10-17T20:08:43","n":7,"actor":"developer-1","role":"developer",
+ "action":"commit","target":"T-0001","detail":"feat(auth): src/auth.py | 2 file(s) e257f69",
+ "rev":"e257f69","prev":"<hash of record 6>","hash":"<sha256(prev + canonical record)>"}
+```
+
+`hash = sha256(prev_hash + canonical_json(record))`, so records are chained: editing
+or deleting any line breaks every hash after it.
+
+Actions cover the whole lifecycle: `memory.add|update|promote|drop|merge|evict`,
+`task.add|claim|status|evidence|reclaim`, `selfcheck`, `review.pass|fail`,
+`pr.open|merge`, `branch.start|retire`, `criteria.add|verify`, `tests.add|run`,
+`dispute.open|round|escalate|sign|resolve`, `decision.add`, `commit`, `ledger.export`.
+
+Memory maintenance is logged too, so a fact never disappears silently: promotion,
+dropping, key-merging and archive eviction each write a record with the entry key.
+
+## Internal audit
+
+```sh
+teamwork.py trace <T-id|AC-id|TS-id|P-id>   # one claim, end to end
+teamwork.py ledger show --tail 40 [--action review.pass] [--actor reviewer-1]
+teamwork.py ledger verify                    # recompute the chain
+teamwork.py audit                            # trail health + provenance + coverage
+teamwork.py loop                             # a broken trail blocks STOP
+```
+
+`trace` joins the task, its commits, the PR, the review, the tests, the criteria and
+the ledger events into one chronological view: claim -> evidence -> commit -> review
+-> merge -> archive.
+
+`audit` reports: chain problems, memory entries without `by` provenance, decisions
+without evidence, a ledger that shrank since the last export, plus the usual gates,
+coverage and branch checks.
+
+## External audit
+
+`teamwork.py ledger export` writes two committed artifacts that a third party can
+check **without trusting the team**:
+
+- `docs/Team/AuditManifest.json` - team, project, git revision and branch, ledger
+  record count and head hash, a sha256 digest for every committed state artifact
+  except `docs/Team/Archive.md` (append-only: it gains an entry when a review
+  passes, so a digest committed beside it would be stale by construction; its
+  entries are followed through the ledger), and the exact verification steps.
+- `docs/Team/AuditReport.md` - the human summary of the same facts.
+
+Verification procedure (reproducible by anyone with the repository):
+
+```sh
+teamwork.py ledger verify --reconcile   # recompute the chain; a head cache left
+                                        # behind by a crash is repaired, a removal
+                                        # of records is reported
+teamwork.py ledger repair --by <instance> --reason "<why>"   # drop a torn tail
+sha256sum -c <(jq -r '.artifacts[] | "\(.sha256)  \(.path)"' docs/Team/AuditManifest.json)
+git cat-file -t <git.head>   # the reviewed revision still exists
+teamwork.py trace <T-id>     # follow any individual claim
+```
+
+What each check proves:
+
+| Check | Proves |
+|---|---|
+| hash chain + head hash | the trail was not edited, reordered or truncated after export |
+| `verify --reconcile` | a crash artefact is distinguishable from tampering: a stale cache is repaired, a *shrinking* ledger is reported |
+| `ledger repair` | a torn tail is recoverable, and the repair itself is a logged record |
+| artifact digests | the records themselves are byte-identical to the reviewed state |
+| git revision | the work that was accepted is the work that exists |
+| per-record provenance | every claim can be attributed to an instance, a role and a revision |
+
+The manifest separates **externally verifiable** artifacts (committed project
+output under `docs/Team/`) from **local_state** (hidden working state under
+`.pi/`, only checkable on the machine that produced it). The export records its own
+`ledger.export` event *before* capturing the checkpoint, so `ledger verify` after
+an export matches the manifest exactly.
+
+`AuditManifest.json` should be committed with the milestone it covers (the Reviewer
+can include it in the `chore(records)` commit), so the head hash becomes a
+checkpoint in git history - and a later truncation of the ledger is then detected
+by comparing against it.
+
+## Honest limits
+
+- The ledger is tamper-**evident**, not tamper-**proof**: anyone with write access
+  can rebuild it, but they cannot reproduce the exported head hash without also
+  rewriting the committed manifest, and the manifest's git history is append-only.
+- Identity is accountability, not cryptography: `--by` names an existing instance,
+  and every action it performs is recorded against it. It does not prove which OS
+  process typed the command.
+- A record proves that something was declared, with the evidence that was given.
+  Whether the evidence proves the claim is what the Reviewer and `criteria verify`
+  are for: both require an independent role.

package/skills/teamwork/references/Concurrency.md

@@ -0,0 +1,160 @@
+# Concurrency and reuse
+
+Reference for the /teamwork skill. Loaded on demand; `SKILL.md` keeps the
+operating procedure.
+
+Related: [Engineering](Engineering.md) | [Evidence](Evidence.md) | [Docs](Docs.md) | [State](State.md) | [Concurrency](Concurrency.md) | [Roles](Roles.md) | [Testing](Testing.md) | [Audit](Audit.md)
+
+## Concurrency budget and resource reuse
+
+Run everything as parallel as the providers allow, never past their caps.
+
+| Provider | Concurrent agents | Use it for |
+|---|---|---|
+| Ollama Cloud | 64 | focused reasoning lanes: architecture, review, disputes, analysis |
+| DeepSeek official API | ~2500 | wide independent fanout: many developer/tester/designer sub-tasks, bulk docs and research |
+
+Caps live in `.pi/Teamwork/Teams/<Team>/Settings.json` and are overridable with
+`TEAMWORK_PROVIDER_LIMITS="ollama-cloud=64,deepseek=2500"`.
+
+### Slots are leases
+
+Every model-heavy task holds a lease in `.pi/Teamwork/Teams/<Team>/Runtime/Slots/<provider>/`.
+Leases expire after `TEAMWORK_SLOT_TTL_MINUTES` (90) so a crashed lane cannot
+leak capacity.
+
+```sh
+teamwork.py slot acquire --agent developer-3 --provider deepseek --task T-0012
+teamwork.py slot renew   --agent developer-3          # every ~60 min on long work
+teamwork.py slot release --agent developer-3
+teamwork.py slot list                                  # used / cap / free per provider
+teamwork.py slot reap                                  # expire dead leases
+```
+
+At the cap, `slot acquire` fails with exit 3 instead of blocking. The lane then
+does work that needs no slot (read, plan, review a peer's output), fans out on
+another provider, or waits for a lane to release - it never stalls the team.
+
+### Plan the parallelism
+
+```sh
+teamwork.py parallel
+# - focused reasoning lanes (ollama-cloud): 7 free
+# - bulk fanout lanes (deepseek): 2496 free
+# - start up to 7 new lane(s) now (ready tasks: 12)
+# - 3 lane(s) already hold a slot: hand the next task to a running lane first
+# - independent sub-tasks only: one writer per file
+```
+
+The CEO uses this before every dispatch round: fill every free slot with
+independent ready work, and scale `developer-N` / `tester-N` / `designer-N`
+instances to the available capacity rather than to a fixed number.
+
+### Work-in-progress, not lane count, is the throughput
+
+A lane that holds one task and waits for its review is idle capacity. The engine
+therefore schedules on **capacity**, not on idleness:
+
+| Concept | Default | Where |
+|---|---|---|
+| `LANE_WIP` - units one lane may hold (`doing` + `selfcheck`) | 2 | `engine.LANE_WIP` |
+| Reviewer claims per lane | 1 | `review --claim` lease |
+| Provider capacity | `Settings.json` (`ollama-cloud` 64, `deepseek` 2500) | `parallel`, `pulse` |
+
+`task next <lane> --capacity N` claims N executable tasks at once; `pulse
+--commit` tops every lane back up to its limit and refuses to plan more work than
+there are free provider slots, printing the shortfall. A claim that is still live
+blocks its lane; an expired claim is open for take-over, which is exactly what the
+next pulse hands out.
+
+### Stream the dependencies
+
+`deps: role:T-id` waits for `done` and is the slowest possible edge. Two earlier
+release points exist and should be used for every contract-shaped dependency:
+
+| Dep form | Releases when | Use it for |
+|---|---|---|
+| `role:T-id@started` | the owner has picked the task up | shadow work, fixtures, environment setup |
+| `role:T-id@review` | the work is submitted for review | testing and docs against a frozen interface |
+| `role:T-id` (default) | the task is `done` and merged | anything that needs the merged artifact |
+
+Using `@review` on every interface dependency is what lets the tester, the writer
+and the next developer start in the same hour rather than after a full review
+cycle.
+
+### Reuse before you recompute
+
+- Reuse a **running lane** before spawning a new one - the teammate already holds
+  its memory, role and context.
+- Reuse **evidence**: if a verification already passed on the same revision, cite
+  it (`BUILD ECONOMY`) instead of re-running.
+- Reuse **research and artifacts**: read global memory, long-term memory and
+  `docs/Team/` before producing anything new; update in place, never duplicate.
+- Reuse **build/test caches**; never rebuild from scratch for a clean slate.
+- Reuse **the same artifact across lanes**: a frozen interface, fixture or script
+  is shared, not re-created per task.
+- Deduplicate before dispatch: `teamwork.py audit` flags near-identical tasks.
+
+### Parallelism rules (non-negotiable)
+
+- One writer per file/worktree. Concurrency never means two agents editing the
+  same file.
+- Only independent tasks run together; dependent tasks queue on their `deps`.
+- The Reviewer, the Project Manager and the CEO are lanes too - keep them fed.
+- **Review concurrency is the number of lanes, not the depth of the queue.**
+  `pulse --commit` fans unclaimed deliverables out one per idle Reviewer lane and
+  records a `review.claim` lease (`SlotTtlMinutes`, default 90 min) on each: the
+  holder counts as busy, another lane is refused while the lease is live, a verdict
+  or `--release` clears it, and an expired lease is open for take-over. So staff at
+  least `reviewer-1` and `reviewer-2`, and never stack the backlog on one lane.
+- Never exceed a provider cap to "go faster": the extra lanes fail, and the
+  failure costs more than the parallelism gains.
+
+
+## Per-agent model configuration
+
+The skill does **not** ship a model and does not call an LLM API itself. Each
+agent runs through the host's own API, so the model is a property of the *agent*,
+not of the project, and every lane can pick one independently:
+
+```sh
+teamwork.py model set reviewer   --provider anthropic --model <strong>   # role default
+teamwork.py model set developer-1 --provider deepseek --model <cheap>   # instance override
+teamwork.py model get developer-1
+teamwork.py model list
+```
+
+- An **instance** setting wins over the **role** default; an unset agent uses the
+  host's own default and records `unset`.
+- Give the reasoning-heavy lanes the stronger model (Reviewer, Architect,
+  Security Auditor) and the mechanical ones a cheaper or faster one (bulk edits,
+  formatting, link checks). Cost and latency are a per-lane choice, not a global one.
+- A model change is a recorded act (`Settings.json` + the ledger); the CEO sets the
+  lanes at intake, and an agent never changes another agent's model.
+- Model choice never changes the protocol: the evidence gates, the two-stage
+  review and the ledger hold whatever model produced the work.
+
+### Automatic cost-aware routing
+
+```sh
+teamwork.py model auto            # dry run: the plan, per lane
+teamwork.py model auto --apply    # write it into Settings.json
+teamwork.py model auto --json
+```
+
+`model auto` reads the *runtime environment* - which agent host is running (Pi,
+Claude Code, opencode, Codex, Cursor, Gemini CLI) and which model that host already
+exposes - and routes **the strongest available model to the lanes where a mistake
+is expensive** (Reviewer, Architect, Security Auditor, CEO, CTO) and **the economy
+model to the mechanical lanes** (developers, testers, writers, formatting, link
+checks). Quality where it compounds, cheapness where it does not.
+
+- It never invents a model id: `TEAMWORK_MODEL_STRONG` (or the host's own
+  `ANTHROPIC_MODEL` / `PI_MODEL` / `OPENCODE_MODEL` / ...) supplies the strong tier,
+  `TEAMWORK_MODEL_ECONOMY` the cheap one, and a lane with neither is reported as
+  `unset` together with the variable to set.
+- `--apply` is explicit: the plan is a dry run by default, and applying it is
+  recorded in the ledger.
+- Re-run it when the host or the budget changes; it is idempotent.
+- `TEAMWORK_AGENT_HOST=claude|pi|opencode|codex|cursor|gemini` overrides
+  detection when the markers are ambiguous (CI, wrapper scripts).

package/skills/teamwork/references/Dissent.md

@@ -0,0 +1,85 @@
+# Decisions, dissent and the tribunal
+
+Reference for the /teamwork skill. Loaded on demand; `SKILL.md` keeps the
+operating procedure.
+
+Related: [Engineering](Engineering.md) | [Evidence](Evidence.md) | [Docs](Docs.md) | [State](State.md) | [Concurrency](Concurrency.md) | [Roles](Roles.md) | [Testing](Testing.md) | [Audit](Audit.md)
+
+## Decision and dissent protocol
+
+The team's decisions are independent and evidence-based, not consensus by
+deference.
+
+**Every agent decides independently.** A decision is only valid with an evidence
+chain: claim, data/measurement (command, file, benchmark, revision, source+date),
+reasoning from evidence to conclusion, rejected alternatives, the bet you are
+making, and the test that would falsify it. "I think", "should be fine" and
+"best practice" are not evidence. Prefer measuring over debating; when a
+measurement is impossible, label the decision provisional.
+
+**Dissent is mandatory, not optional.** An agent that finds a design or decision
+unreasonable must challenge the owner with counter-evidence instead of silently
+complying or working around it:
+
+```sh
+python3 "$SKILL/scripts/teamwork.py" dispute open \
+    --by developer-1 --against architect --topic "sync DB calls in request path" \
+    --position "will not meet the p99 target" \
+    --evidence "bench: 12ms/query x8 = 96ms @abc123 > 50ms budget" --task T-0007
+python3 "$SKILL/scripts/teamwork.py" dispute round D-0001 --by architect \
+    --message "pooling measured at 14ms total @def456"
+```
+
+**3-round cap, then the tribunal.** The two agents get at most three rounds. If
+they still disagree, the dispute escalates to the **CEO + CTO + CFO tribunal**,
+which discusses it and issues a final, binding ruling:
+
+```sh
+python3 "$SKILL/scripts/teamwork.py" dispute escalate D-0001 --by developer-1
+python3 "$SKILL/scripts/teamwork.py" dispute sign D-0001 --by ceo   # and cto, cfo
+python3 "$SKILL/scripts/teamwork.py" dispute resolve D-0001 --by ceo \
+    --decision "pool + 20ms timeout + load-test gate"
+```
+
+The tool enforces this: a 4th round is refused, an escalated dispute cannot be
+resolved until all three tribunal members have signed, and `audit` flags any open
+dispute at the round cap. The ruling is recorded in `docs/Team/Decisions.md` and
+is final - the losing side implements it and says so in its report. A dispute
+never blocks unrelated work; keep going on everything not contested.
+
+## Parallel lanes
+
+The team is a set of lanes, not a queue:
+
+- **Lane 0 (blocking, short):** requirements -> acceptance criteria -> frozen
+  interfaces -> task graph. Everyone else starts the moment this lands.
+- **Lane A (code):** developers implement against the contract; unit tests are
+  part of each change.
+- **Lane B (verification):** testers build integration/E2E suites from the same
+  contract in parallel with implementation, then run and monitor them.
+- **Lane C (design):** designers produce specs and copy from the contract, then
+  review the merged UI.
+- **Lane D (research/ops/cost):** PM research, COO risk and process, CFO cost,
+  running continuously and feeding lanes A-C.
+- **Lane E (docs):** produced from merged code, scheduled last, never a gate.
+
+Rules: one writer per file/worktree; interfaces frozen before parallel writers
+start; interface changes require a `Decisions.md` entry plus notification to
+every dependent lane; a lane that finishes takes the next unblocked task instead
+of waiting.
+
+## Failure handling
+
+- **Infrastructure failure** (spawn, tool, provider): stop the lane, record the
+  exact error, worktree state and partial diff, retry once cleanly, then report
+  to the CEO. Never silently switch execution mode.
+- **Blocked on a dependency**: mark the task `blocked` with the exact unblock
+  action and owner, tell the Project Manager, and take other executable work.
+- **Blocked on the user**: CEO asks one consolidated question; the lane keeps
+  working elsewhere meanwhile.
+- **Contradictory evidence**: escalate to the CEO; record the resolution in
+  `Decisions.md` and global memory.
+- **Repeated failure of the same task**: the CEO re-scopes, splits, or reassigns;
+  it is never marked done to make the board look green.
+- **Red-line refusal**: expected and correct behaviour. Record it, escalate, and
+  continue with the rest of the plan.

package/skills/teamwork/references/Docs.md

@@ -0,0 +1,74 @@
+# Documentation standard
+
+Reference for the /teamwork skill. Loaded on demand; `SKILL.md` keeps the
+operating procedure.
+
+Related: [Engineering](Engineering.md) | [Evidence](Evidence.md) | [Docs](Docs.md) | [State](State.md) | [Concurrency](Concurrency.md) | [Roles](Roles.md) | [Testing](Testing.md) | [Audit](Audit.md)
+
+## Documentation standard (markdown, structured, linked)
+
+Everything the team writes - memory, plans, designs, research, decisions, docs -
+is **markdown**, structured for a human reader, and cross-linked both ways.
+This is enforced: `teamwork.py links` fails on broken links, malformed URLs, bare
+URLs and missing back-links, and `audit` includes link health.
+
+### Structure
+
+- One `# H1` per file; the title states what the document is.
+- A one-line `Owner:` line naming the role that maintains it.
+- A `Related:` line directly under the header with relative links to every
+  document it interacts with (see the link graph below).
+- Numbered `##` sections in reading order; `###` only when it earns its depth.
+- Prefer tables and short bullets over paragraphs. One idea per bullet.
+- Mark placeholders as `<like this>` so unfinished sections are obvious.
+
+### Be concise (hard)
+
+Saved content is read by humans under time pressure. Every file must be short
+enough to scan.
+
+- Lead with the conclusion; put the detail under it, never before it.
+- One fact per line. Prefer a table row or a bullet over a paragraph.
+- Write the smallest text that is still unambiguous. Delete anything the reader
+  already knows, any restatement of the brief, and any sentence that only
+  announces what the next sentence does.
+- No filler: no "as mentioned above", "it is important to note", "in order to",
+  "various", "several", "etc." Lists are exhaustive or they are not lists.
+- Numbers over adjectives: "12ms p99", not "quite fast". `<command> -> <result>`,
+  not "we verified it".
+- A memory entry is **one line**: the fact, plus a key. If it needs three
+  paragraphs, it belongs in a document, not in memory.
+- Cap each section at roughly one screen. If it grows past that, split the
+  document or move detail to a linked file.
+- Rewrite, do not append. Documents and memory entries are kept current, not
+  accumulated; stale text is deleted rather than left below new text.
+
+### Links
+
+- **External references always carry a direct, working link plus an access date**:
+  `- [title](https://full-url) - accessed YYYY-MM-DD`. Never cite a search page,
+  a bare domain, or "the docs" without a URL. A claim without a link is
+  `UNVERIFIED` and cannot justify a decision.
+- **Internal references are relative markdown links** to the file
+  (`[PLAN](Plan.md)`), never absolute paths and never bare file names in prose.
+- **Bidirectional**: if A links to B, B links back to A. Put the back-link in the
+  `Related:` line, which is why every shared document has one.
+- Every decision cites the evidence and the documents it affects; every research
+  claim cites its source; every task result cites the artifact and the command.
+
+### Link graph (committed docs, every edge bidirectional)
+
+```text
+PROJECT ─ PLAN ─ BOARD ─ ARCHIVE
+   │       │      │        │
+   │       ├──────┴────────┴── RISKS ─ COSTS
+   │       │                     │
+   ├── ARCHITECTURE ─ DESIGN     │
+   │        │                    │
+   ├── RESEARCH ─────────────────┘
+   └── DECISIONS  (links to ARCHITECTURE, RESEARCH, RISKS, COSTS, ARCHIVE, PLAN)
+```
+
+`teamwork.py links` verifies it. `.pi/` memory files link to `TaskQueue.md`,
+`Role.md`, `ShortTermMemory.md`, `LongTermMemory.md`, global memory and the committed docs
+they inform.