@aopslabs/aops 0.3.31 → 0.3.32

package/aops-assets-release/skills/aops-cli-collab/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: aops-cli-collab
+version: 31
+description: "DEPRECATED — the repo-first collab command surface is retired. Routes agents to aops-cli-discuss (decision/consensus), aops-cli-chat (coordination/wake via hosted rooms), and aops-cli-projectman (review + issues). `aops-cli start` multi-agent mode is now chat-room, not full-collab. Kept one release for compatibility."
+metadata:
+  supersedes: "v30"
+  short-description: "Deprecation pointer: collab split into discuss + chat + PM"
+  tags:
+    - cli
+    - agentspace
+    - deprecated
+    - pointer
+    - discuss
+    - chat
+    - projectman-review-request
+---
+
+# AOPS CLI Collab (deprecated)
+
+The repo-first `collab` command surface (`aops-cli collab ...`, the collab session ledger, and collab chat) is **retired**. Coordination, decision, and review now live in three separate surfaces — pick the one that matches the need:
+
+- **`aops-cli-discuss`** — decision / consensus: standalone discussion topics, the design-decision ritual, the two-agent turn protocol, and deterministic `conclude` outputs.
+- **`aops-cli-chat`** — coordination / wake: hosted Agentspace rooms and DMs, members, bindings, and `inbox`/`listen`/`catchup` read loops.
+- **`aops-cli-projectman`** — review + execution truth: `pm review-request` create/result, re-review (`--parent`), `pm issue`, and `pm feedback`.
+
+`aops-cli start`'s multi-agent mode is now **`chat-room`** (the `full-collab` mode was removed). There is **no automatic decision bridge**: `discuss conclude` writes only its own outputs; surfacing a decision to PM or chat is explicit (a PM feedback/issue carrying the discussion-topic ref, or a chat `agentspace.discussion-topic` binding).
+
+This pointer is kept for **one release** for compatibility; new instructions should reference the three skills above directly. The full v30 collab playbook lives on in this skill's version history.
+
+## Old → new mapping
+
+| Old (retired collab) | New |
+|----------------------|-----|
+| `collab start` / session ledger / `collab event` / `collab status` / `collab close` | Hosted **`aops-cli chat`** room for coordination + **`aops-cli pm`** for review/issue/closeout truth (`aops-cli-chat`, `aops-cli-projectman`) |
+| `collab chat` (repo-first session chat) | **`aops-cli chat`** hosted rooms/DMs (`aops-cli-chat`) |
+| `collab review request` / `collab review result` (session review composite) | **`aops-cli pm review-request create` / `... result`** + `pm review-request create --parent <rr-id>` for re-review (`aops-cli-projectman`) |
+| Session-bound discuss (`discuss start --session ...`) | **Standalone `aops-cli discuss`** (no `--session`) (`aops-cli-discuss`) |
+| `collab listen` / `collab chat daemon` listener patterns | **`aops-cli chat listen` / `chat catchup`** read loop (`aops-cli-chat`) |
+| `collab close` + post-collab memory | Operator-approved **`pm board closeout`** + `aops-cli mem` closeout note (`aops-cli-projectman`, `aops-cli-agentspace`) |
+| `start --mode full-collab` | `start --mode chat-room` |
+
+If `--help` and this pointer disagree, `--help` wins.

package/aops-assets-release/skills/aops-cli-core/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: aops-cli-core
+version: 17
+description: "Use when an AI agent needs AOPS CLI core operator playbook: help-first discovery, guard flags, project registry/project selection, partitioned sync, archive lifecycle, server-canonical vs local cache rules, hosted invoke fallback, doc-reading ladder, and schema fallback. Thin guide; .aops/docman/aops-guides/aops-cli-user-guide.md and command --help are authoritative."
+metadata:
+  supersedes: "v16"
+  short-description: "AOPS CLI core operator thin discipline guide"
+  tags:
+    - cli
+    - tooling
+    - operators
+    - discovery
+    - guard-pattern
+    - sync
+    - hosted-mirror
+    - help-first
+    - schema-first
+    - project-registry
+    - archive
+---
+
+# AOPS CLI Core
+
+`aops-cli` is the operator plane. It routes agents to domain owners; it is not the semantic owner of planning, memory, documents, files, or execution.
+
+This is a thin discipline guide. Deep mechanics live in `.aops/docman/aops-guides/aops-cli-user-guide.md`; exact command shape lives in live `--help`. If this skill conflicts with either, `--help` and the user guide win.
+
+## Use This Skill For
+
+1. Help-first command discovery.
+2. Guard flags: `--preview`, `--apply`, `--confirm`, `--idempotency-key`, `--json`, `--yes`.
+3. Server-canonical truth vs local cache routing.
+4. Raw hosted invoke fallback when sugar is absent.
+5. Doc/guide reading ladder and schema fallback discipline.
+6. Repo project registry routing: `aops-cli project link`, `aops-cli project links list`, `aops-cli project migrate-local-root`, and `pm --project-slug` project selection.
+7. Partitioned sync (read/mirror): `sync --project-slug` and `sync --all-projects`.
+8. Hosted PM archive lifecycle: `archive create`, `archive verify`, `archive delete`, and `archive decommission-check`.
+
+Use the family skills for domain work: projectman for PM (including review-request/result and re-review), agentspace for memory/assets, discuss for decision/consensus, chat for hosted-room coordination/wake, docman for docs, fileman for snapshots, tasker for runner/tasker, view for read-only cockpit surfaces.
+
+## Canonical Sources
+
+1. `.aops/docman/aops-guides/aops-cli-user-guide.md`, read by section name/keyword, not by fragile section number.
+2. `aops-cli --help`, `aops-cli <family> --help`, and nested `--help`.
+3. Domain user guides: `domains/<domain>/USER_GUIDE.md` for semantic rules.
+4. Hosted prompt/skill truth through `aops-cli prompt|skill ...`; `.aops/hosted/**` is only a mirror.
+5. Hosted Docman guide truth through `aops-cli doc ...`; `.aops/docman/**` is only a mirror.
+6. Repo project registry truth: `.aops/aops.config.json`, inspected with `aops-cli project links list --json`.
+
+## Help-First Workflow
+
+```bash
+aops-cli --help
+aops-cli <family> --help
+aops-cli <family> <subcommand> --help
+```
+
+Decision chain:
+
+1. Use sugar if help exposes it.
+2. Inspect a compact hosted catalog: `aops-cli agent tools --domain <domain> --summary --json`.
+3. Narrow noisy domains with `--q` and `--limit`: `aops-cli agent tools --domain <domain> --q <keyword> --limit 20 --summary --json`.
+4. Inspect compact schema first: `aops-cli agent schema --tool <domain>.<operation> --summary --json`.
+5. Invoke exact payload: `aops-cli agent invoke --tool <toolId> --input '@payload.json' --apply --json`.
+6. Use `aops-cli api call` only as an explicit escape hatch.
+
+## Agent Tool Catalog Ladder
+
+Use compact discovery before dumping whole catalogs:
+
+```bash
+aops-cli agent tools --domain agentspace --summary --json
+aops-cli agent tools --domain agentspace --q memory --limit 20 --summary --json
+aops-cli agent schema --tool agentspace.memory-item.search-memory-items --summary --json
+```
+
+`agent tools --json` without `--summary` returns the full gateway payload and can be very large. `--summary` returns compact resource/tool rows plus next-step hints. `--examples` adds the first invoke example only when you explicitly need it; otherwise prefer `agent schema` for payload authoring.
+
+## Guard Flags
+
+| Flag | Meaning |
+|---|---|
+| `--preview` | validate/planning output without write effects when the command supports preview |
+| `--apply` | execute a guarded write |
+| `--confirm` | confirm destructive overwrite/delete/restore/cleanup |
+| `--idempotency-key <id>` | make retries deterministic |
+| `--json` | scriptable output |
+| `--yes` | non-interactive/fail-fast; not a substitute for `--apply` or `--confirm` |
+
+Common default: reads need no guard, writes need `--apply`, destructive writes need `--apply --confirm`.
+
+## Server-Canonical Truth And Local Caches
+
+The hosted AOPS server is the source of truth for planning and Agentspace state. Create, write, and read all go through the hosted gateway:
+
+1. Projectman (`aops-cli pm ...`) — server-canonical.
+2. Agentspace memory (`aops-cli mem ...`) — server-canonical.
+3. Discussion topics (`aops-cli discuss ...`) — server-canonical (hosted discuss authoring).
+4. Experience (`aops-cli exp ...`) — server-canonical.
+
+Read-only local caches (refreshed by `sync pull`, never an authoring source):
+
+1. `.aops/projectman/**`, `.aops/agentspace/memory/items/**`, `.aops/agentspace/discussions/**`, `.aops/agentspace/collabs/**`: a local cache of server state for offline/read inspection.
+2. `.aops/hosted/prompts/**` and `.aops/hosted/skills/**`: hosted prompt/skill mirrors; refresh after a hosted prompt/skill publish with `aops-cli sync pull --apply --hosted-project-slug aops --json`.
+3. `.aops/docman/**`: Docman guide mirrors; refresh with `aops-cli doc mirror pull ... --apply --json`. `sync pull` does not refresh Docman guide mirrors.
+
+Do not hand-edit a read-only cache or mirror as canonical truth; change hosted truth through the hosted CLI and refresh the cache.
+
+## Project Registry And Project Selection
+
+The repo project registry lets one repo bind more than one hosted project so `pm --project-slug <slug>` (and the other family commands) can target the intended hosted project. Authoring is always hosted; the registry only controls selection and where the read-only local cache lives.
+
+```bash
+aops-cli project link --slug aops --mode local --local-root .aops/projects/aops --apply --json
+aops-cli project link --slug cockpit --mode hosted-only --apply --json
+aops-cli project links list --json
+aops-cli project migrate-local-root --project-slug aops --local-root .aops/projects/aops --dry-run --json
+aops-cli project migrate-local-root --project-slug aops --local-root .aops/projects/aops --apply --confirm --json
+```
+
+Operational facts:
+
+1. `project link` mutates only `.aops/aops.config.json` after verifying the hosted project exists and is not archived/deleted.
+2. `local-root` names the repo-relative path where that project's read-only cache (PM/memory/discuss mirrors) is materialized by `sync pull`.
+3. `project link --mode` records the link mode metadata; PM/memory/discuss authoring routes to the hosted server regardless, so inspect a project through hosted/project views or read its local cache.
+4. `migrate-local-root` is repo-local and only moves the local cache root. Run `--dry-run` first; the real move requires `--apply --confirm` because the prior root is moved to an archive.
+5. `ownerRepo` and `parentProjectSlug` are metadata on the registry link; they do not change domain ownership.
+
+## Partitioned Sync
+
+Sync is a read/mirror operation that refreshes the local cache from the hosted server; it is not a PM authoring path. Use project selection when a repo has more than one linked project:
+
+```bash
+aops-cli sync status --project-slug aops --json
+aops-cli sync diff --project-slug aops --json
+aops-cli sync pull --project-slug aops --apply --json
+aops-cli sync status --all-projects --json
+aops-cli sync pull --all-projects --apply --json
+```
+
+Shipped behavior:
+
+1. `sync --project-slug <slug>` resolves the project link from `.aops/aops.config.json` and scopes the cache refresh to that project's `localRoot`.
+2. `sync --all-projects` runs `status`, `diff`, `pull`, or `bootstrap` once per runnable local project, skips ambiguous local projects without `localRoot` when multiple local projects exist, and reports project-level errors without fail-fast.
+3. `sync pull` and `sync bootstrap` are project-level mirror commands. Use `--hosted-project-id|--hosted-project-name|--hosted-project-slug` to refresh hosted prompt/skill mirrors for additional hosted projects.
+4. To author PM records, use the hosted `pm --project-slug` CRUD path described in `aops-cli-projectman`; sync does not write server records.
+
+## Archive Lifecycle
+
+Archive is currently documented in `aops-cli-core` rather than a separate skill because the shipped surface is a core CLI cleanup lifecycle over existing Projectman/Agentspace tools. Split it into `aops-cli-archive` only if it grows into a broader domain with its own guide and workflows.
+
+```bash
+aops-cli archive create --project-slug aops --apply --json
+aops-cli archive verify --manifest .aops/archive/aops/<ts>/manifest.json --apply --json
+aops-cli archive delete --manifest .aops/archive/aops/<ts>/manifest.json --json
+aops-cli archive delete --manifest .aops/archive/aops/<ts>/manifest.json --apply --confirm --json
+aops-cli archive decommission-check --manifest .aops/archive/aops/<ts>/manifest.json --json
+```
+
+Shipped behavior:
+
+1. `archive create` downloads the hosted Projectman graph to `.aops/archive/<slug>/<timestamp>` and writes a local bundle. It does not delete hosted records.
+2. New manifests are intentionally partial: `partial: true`, `decommissionSafe: false`, and non-empty `pendingDomains` for `agentspace.memory`, `agentspace.discussions`, `agentspace.chat`, and hosted reusable assets. This blocks full project/scope decommission until other domains are handled.
+3. `archive verify` re-fetches the hosted PM graph and compares local files to remote counts/checksums. With `--apply`, it persists `verification.status: passed` into the manifest.
+4. `archive delete` requires a verified manifest. Without `--apply`, it is a preview. Destructive hosted deletion requires `--apply --confirm`.
+5. Delete order is children-before-parents: review requests, feedback, issues, microtasks, sprints, tasks, board-column links, columns, boards. The manifest records per-action deletion state so reruns skip already `deleted` or `missing` actions.
+6. `archive decommission-check` allows full project/scope decommission only when `decommissionSafe === true` and `pendingDomains` is empty. The current create flow leaves this blocked by design.
+7. Archive uses existing hosted tools (`agentspace.project.get-by-id`, Projectman list/get/delete tools). There is no new hosted archive tool in the agent catalog.
+
+## Doc Reading Ladder
+
+Use this ladder when a skill points to docs:
+
+```bash
+# broad project guide search, local mirror when available
+aops-cli doc scope search --project-slug aops --q "<keyword>" --local --json
+
+# search within a known saved document version
+aops-cli doc search --document-version-id <docver-id> --q "<keyword>" --local --json
+
+# hosted structure/id probe; can still be large on big docs
+aops-cli doc outline get --document-version-id <docver-id> --titles-only --depth 0 --json
+
+# actual mirrored section body
+aops-cli view doc-page <document-slug>#<section-slug> --max-bytes 6000
+```
+
+`doc scope search` is broad and can rank source docs above guide docs. `doc search --local` is retrieval/search, not guaranteed full section body. `doc outline get --titles-only` drops page bodies but still returns link/section/page metadata, so use it for ids rather than as a compact table of contents. `view doc-page` selectors use `<document-slug-or-uid>#<exact-heading-or-heading-slug>`; partial keywords and group paths do not resolve. There is no `aops-cli docman ... --slug` command.
+
+## Schema Fallback Ladder
+
+Before direct hosted payloads:
+
+```bash
+aops-cli agent schema --tool <domain>.<operation> --summary --json
+```
+
+`--summary` flattens nested fields into compact `path`, `type`, `required`, and enum rows, plus next-step hints. Use full `--json` only when you need the complete JSON Schema.
+
+If the compact summary marks `opaque: true`, or if full schema only exposes a flexible envelope such as `{ "data": { "additionalProperties": true } }`, use this order:
+
+1. Matching sugar `--help`, if sugar exists.
+2. Existing read shape from list/get/detail commands.
+3. Domain `USER_GUIDE.md` and architecture docs.
+4. `aops-cli agent openapi --domain <domain> --json` or the HTTP detail endpoint `GET /api/agent/tools/{toolId}`.
+5. Source Zod/schema only when authoring direct invoke or debugging a wrapper bug.
+
+If sugar returns 400/validation errors, stop retrying random flag variants. Compare sugar payload with `agent schema --summary` and then full schema/OpenAPI as needed; use raw `agent invoke` as a temporary bypass only after the contract is known, or file a wrapper bug.
+
+## Anti-Patterns
+
+1. Guessing flags or payload fields from memory.
+2. Treating `aops-cli` as the domain owner.
+3. Hand-editing `.aops/hosted/**` or `.aops/docman/**` mirrors, or the `.aops/projectman/**` / `.aops/agentspace/**` local cache, as canonical truth.
+4. Assuming `sync pull` refreshes Docman guide mirrors.
+5. Treating `--yes` as the missing write guard.
+6. Reading whole guides when a targeted search plus `view doc-page` is enough.
+7. Treating `sync` as a way to write server records; sync only refreshes the read-only local cache, while PM/memory/discuss authoring is hosted (`pm|mem|discuss --project-slug`).
+8. Using `archive delete` before `archive verify --apply`, or treating `decommission-check` as passed while `pendingDomains` is non-empty.

package/aops-assets-release/skills/aops-cli-discuss/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: aops-cli-discuss
+version: 3
+description: "Use when an AI agent runs a standalone server-canonical AI discussion topic with aops-cli: the design-decision ritual (independent research, two-agent turn protocol, kind=final-stance, deterministic conclude outputs), slug-first selectors, and JSON-driven stop-state reads. discuss = the decision/consensus surface only; coordinate/wake via aops-cli-chat, track review + execution truth via aops-cli-projectman. Thin discipline guide; canonical mechanics live in .aops/docman/domain-guides/agentspace-user-guide.md and command --help."
+metadata:
+  supersedes: "v2"
+  short-description: "AOPS CLI standalone discuss / decision-ritual guide"
+  tags:
+    - cli
+    - agentspace
+    - discussion
+    - discuss
+    - decision-ritual
+    - consensus-gate
+    - two-agent-protocol
+    - conclude-outputs
+    - standalone
+---
+
+# AOPS CLI Discuss
+
+`aops-cli discuss` manages **standalone AI discussion topics** that are server-canonical (hosted discuss authoring): create, append turns, and read through the hosted gateway. `.aops/agentspace/discussions/**` is a read-only local cache of that server state, refreshed by `sync pull`. discuss is the decision/consensus surface in the AOPS coordination triad:
+
+- **`aops-cli chat`** (hosted rooms/channels) = coordination, wake, catch-up → `aops-cli-chat`.
+- **`aops-cli pm`** (review-request/result, issue, feedback) = review + execution truth → `aops-cli-projectman`.
+- **`aops-cli discuss`** (standalone) = consensus / decision protocol → this skill.
+
+There is **no automatic decision bridge**: `discuss conclude` only writes its own conclude outputs. Surfacing a concluded decision to PM or a chat room is an **explicit** step (see "Explicit linking" below). `discuss` is standalone-only — there is no `--session` flag and no session ledger.
+
+This skill is a **thin discipline guide**: discovery, the design-decision ritual, the two-agent automation protocol, slug-first selectors, anti-patterns, and pointers. Deep mechanics, full exit-code matrices, and troubleshooting live in the canonical Agentspace User Guide. When this skill conflicts with `aops-cli discuss --help` or the user guide, **those win**.
+
+## Roles are operator-only (read first)
+
+Participant roles for any discussion — initiator/driver, peer, primary, reviewer — are **operator-driven**. Do not auto-default by agent name (`codex`, `claude`), runtime brand (Codex CLI, Claude Code), or prior-session convention; the literal `codex`/`claude` ids in the examples below are illustrative pairs, **not defaults**. If the operator did not specify who plays which role, **ASK** before starting the topic or writing the first turn.
+
+## Use another skill for
+
+| Need | Skill |
+|------|-------|
+| Coordination / wake / catch-up (hosted rooms, DMs) | `aops-cli-chat` |
+| Review-request/result, re-review, issues, feedback | `aops-cli-projectman` |
+| CLI guard flags, sync, hosted mirror mechanics | `aops-cli-core` |
+| Document graph authoring/search | `aops-cli-docman` |
+| Memory / project / prompt / resource / skill assets | `aops-cli-agentspace` |
+| File snapshots / diff / restore | `aops-cli-fileman` |
+
+## Canonical sources (authoritative)
+
+When this skill is silent, ambiguous, or out of date, **defer to these**:
+
+1. `.aops/docman/domain-guides/agentspace-user-guide.md` — semantics for discuss topics, turns, the decision ritual, and loop discipline. Reference sections by name (numbers drift), e.g.:
+   - "Coordination semantics (loop discipline and exit codes)" (search: exit code, loop discipline, wait, self-wakeup)
+   - "Coordination semantics (review-request reply pairing)" (search: review-result, projectman.review-request, discussion-topic ref)
+   - "Anti-patterns appendix" (search: anti-patterns, lifecycle, decision ledger)
+   - "Troubleshooting" (search: troubleshooting, ready-to-conclude, open question block)
+2. `aops-cli discuss --help` and nested subcommand help — flag-level detail and the current argument schema.
+3. Section-focused reading via the doc discovery ladder (see **Pointers** below).
+4. Read-only local cache: `.aops/agentspace/discussions/topics/<slug>-<topic-slug>/` (`topic.md`, `turns/*.md`, `outputs/*.md`) mirrors server state for offline reads; author through the hosted CLI, not by hand-editing the cache.
+
+## Discovery: which command for what
+
+| Need | Command |
+|------|---------|
+| Start a standalone decision topic | `aops-cli discuss start --title <t> --slug <topic-slug> --agent <a> --agent <b> --question <q> --apply --json` |
+| Child topic referencing a prior one (parent unchanged) | `aops-cli discuss follow-up --from <topic-slug> ... --apply --json` |
+| Branch/alternative from an existing topic (parent unchanged) | `aops-cli discuss fork --from <topic-slug> ... --apply --json` |
+| Child-topic lineage tree for one root | `aops-cli discuss lineage --id <topic-slug> --json` |
+| List topics (filter by status/scope/agent/subject) | `aops-cli discuss list --status active --scope standalone --json` |
+| Full topic with turns + outputs | `aops-cli discuss get --id <topic-slug> --json` |
+| Append one turn | `aops-cli discuss turn --topic <topic-slug> --agent <a> --kind <kind> --from-file <path> --apply --json` |
+| Deterministic state (next speaker, open questions, guards) | `aops-cli discuss status --id <topic-slug> --json` |
+| Poll until your turn / block / ready | `aops-cli discuss wait --id <topic-slug> --for <a> --timeout-sec <s> --interval-sec <s> --json` |
+| Persistent automation loop prompt | `aops-cli discuss loop-prompt --id <topic-slug> --for <a> --json` |
+| Non-interpretive context pack | `aops-cli discuss digest --id <topic-slug> --json` |
+| Write conclude scaffolds, move to `concluding` | `aops-cli discuss conclude --topic <topic-slug> --apply --json` |
+| Mark an invalid/unwanted topic abandoned | `aops-cli discuss abandon --topic <topic-slug> --apply --json` |
+
+Turn kinds: `statement | question | answer | objection | concession | proposal | final-stance`. Discuss topics are server-canonical (hosted authoring); `.aops/agentspace/discussions/**` is a read-only cache refreshed by `sync pull`. There is no auto-promote into memory/experience — promotion stays explicit.
+
+## Mandatory design-decision ritual (standalone)
+
+Use this whenever the operator asks for a collaborative architecture/design discussion before implementation, a peer consensus, or implementation only after another agent has independently argued/reviewed the design.
+
+1. **Start the topic** with at least two unique operator-assigned participants; give the operator the topic slug and a paste-ready peer join prompt (`discuss status --id <slug> --prompt-for-next --json`) before waiting.
+2. **Independent research before the first substantive turn.** Tell the peer to research and form its own position, not merely validate the opener's plan. Each participant grounds its opening turn in its own reading.
+3. **At least four substantive non-final turns** (analysis / proposal / objection / question / answer / concession). `final-stance` turns, bare acknowledgements, and operator-addressed questions do **not** count toward that floor. A `--require-question-answer` topic blocks other turn kinds while an operator/peer question is open — answer it first.
+4. **Each participant files a `kind=final-stance` turn.** This append-only turn under `turns/*.md` is the canonical final stance — not the `outputs/<agent>-final-stance.md` scaffold that `conclude` later writes.
+5. **Confirm completeness from JSON, never prose.** Read `discuss status --id <slug> --json`: check `lifecycleState` and `missingTurnFinalStances` (and `outputs.missingFinalStances` when present). Do not infer "everyone is done" from turn text or shell wrapper wording.
+6. **Only after all final stances exist, run `discuss conclude`.** It scaffolds `outputs/<agent>-final-stance.md`, `consensus.md`, `disagreement.md`, `open-questions.md` and moves the topic to `concluding`. `conclude` is **blocked while an open question remains**. It does **not** finalize the discussion — the **initiator/driver** (the recorded output owner) then reviews and finalizes `consensus.md` / `disagreement.md` / `open-questions.md` with **no `_TBD_` placeholders**. Either agent may run `conclude`; running it does not lock ownership.
+7. **Implementation stays blocked** until the operator explicitly approves the consensus or grants a recorded override. If the operator changes the ritual mid-discussion, treat the stricter rule as binding even if the topic opened with a weaker `--min-turns-before-conclude`.
+
+## Workflow: standalone discuss → conclude
+
+```bash
+aops-cli discuss start --title "<decision>" --slug <topic-slug> \
+  --agent codex --agent claude --question "<architecture question>" \
+  --min-turns-before-conclude 4 --apply --json
+aops-cli discuss turn --topic <topic-slug> --agent claude --kind statement --from-file ./context.md --apply --json
+aops-cli discuss wait --id <topic-slug> --for codex --timeout-sec 540 --interval-sec 5 --json
+# iterate substantive turns (statement/proposal/objection/question/answer/concession),
+# reading `discuss status --json` between waits, until >=4 non-final turns exist
+aops-cli discuss turn --topic <topic-slug> --agent claude --kind final-stance --from-file ./final-claude.md --apply --json
+aops-cli discuss turn --topic <topic-slug> --agent codex  --kind final-stance --from-file ./final-codex.md  --apply --json
+aops-cli discuss status --id <topic-slug> --json        # confirm missingTurnFinalStances is empty
+aops-cli discuss conclude --topic <topic-slug> --apply --json
+# then the initiator/driver finalizes outputs/consensus.md|disagreement.md|open-questions.md (no _TBD_)
+```
+
+Read `lifecycleState`, `nextTurn`, `missingTurnFinalStances`, and `outputs.missingFinalStances` from JSON; never infer stop state from prose. Output ownership defaults to the discussion **driver** (often, but not always, the topic initiator — the driver may differ from a participant who merely ran `conclude`).
+
+## Two-agent automation protocol
+
+When two agents drive a topic on their own, each loops on `discuss wait` keyed to its own id. Read the structured `exitCode` (same value as the process exit code and as `result.wait.exitCode`):
+
+| Exit | Meaning | Do |
+|------|---------|----|
+| `0` | Requested agent may write the next turn | Write `discuss turn ... --agent <you> --expect-next <you> ...`, then re-`wait`. |
+| `20` | Blocked by an operator-addressed open question/block | **Stop and return to the operator** — an agent cannot clear an operator block. |
+| `21` | Ready to conclude / concluding / concluded / abandoned | Do **not** write more turns; proceed to `conclude` (or stop if already concluded/abandoned). |
+| `22` | Timeout, no change | Re-poll (`wait` again) if still waiting; otherwise do other non-overlapping work. |
+
+`--expect-next` is a race guard and **must equal `--agent`**: it requires that the deterministic next turn already allows that agent, so two automated writers never collide. On a sequence collision, re-read `discuss status` and retry. `discuss loop-prompt --id <slug> --for <agent>` prints a ready-made persistent loop for operator-started automation.
+
+## Explicit linking (no auto bridge)
+
+A concluded decision does **not** propagate anywhere by itself. Surface it explicitly:
+
+- **To Projectman** — carry the discussion-topic ref into a PM record so review/execution truth references the decision:
+
+  ```bash
+  aops-cli pm feedback create --title "<decision applied>" \
+    --description "Consensus from discussion-topic <topic-slug>: <decision summary>" --apply --json
+  aops-cli pm issue create --title "<follow-up from decision>" --severity <sev> \
+    --description "Per discussion-topic <topic-slug> consensus" --apply --json
+  ```
+
+- **To a chat room** — bind the topic so the room shows where the decision lives (rooms are FLOW, not the decision ledger):
+
+  ```bash
+  aops-cli chat binding add --room-id <id> --binding-type agentspace.discussion-topic \
+    --ref-id <topic-uid> --title "<decision>" --created-by <agent> --apply --json
+  ```
+
+This replaces the retired `collab start --from-discuss` / conclude-writeback path. There is no implicit promotion into memory either — write a memory item with a `agentspace.discussion-topic` source-ref if the decision is durable (see `aops-cli-agentspace`).
+
+## Slug-first selector contract
+
+1. Operator text, handoffs, and links use the **topic slug** (`--id` / `--topic`), not raw UUIDs; raw UUIDs stay in JSON/debug.
+2. A legacy folder-name or implicit short-id match emits `cliDeprecationWarnings` in JSON — treat that as a signal to rewrite future instructions to the slug.
+3. If a slug is ambiguous, run `aops-cli discuss list --status active --agent <agent> --limit <n> --json` and retry with `--short-id <8char>` from the matching row. Use `--prefer-active` only when an ambiguous selector has exactly one active match.
+
+## Pointers
+
+- **Agentspace User Guide** by document title + **section name** + keywords (not bare numbers): "Coordination semantics (loop discipline and exit codes)" (search: exit code, wait, loop discipline), "Coordination semantics (review-request reply pairing)" (search: discussion-topic ref, review-result), "Anti-patterns appendix" (search: decision ledger, lifecycle), "Troubleshooting" (search: ready-to-conclude, open question block).
+- **Help is canonical:** `aops-cli discuss --help`, then `aops-cli discuss start|turn|wait|status|conclude|list|follow-up|fork|lineage|loop-prompt|digest|abandon --help`.
+- **Doc discovery ladder** (section-focused reading, no id needed): `aops-cli doc scope search --project-slug aops --q "<keyword>" --local --json`, then targeted `aops-cli doc search --document-version-id <docver-id> --q "<keyword>" --local --json` and `aops-cli doc outline get --document-version-id <docver-id> --json`. There is no `aops-cli docman … --slug` command — use the ladder; reference sections by title + section name + keywords, not bare numbers.
+- **Tool Input Schema:** before authoring `--data`/`--input`/`--patch` payloads for any hosted write, fetch the live JSON Schema first (`aops-cli agent schema --tool <domain>.<operation>`). Full explanation in `aops-cli-core` (Tool Input Schema section).
+
+## Top anti-patterns
+
+1. **Implementing before the operator approves the consensus** (or before a recorded override).
+2. **Inferring stop-state from prose** instead of reading JSON `lifecycleState` / `missingTurnFinalStances` / `wait` `exitCode`.
+3. **Leaving `_TBD_` placeholders** in `consensus.md` / `disagreement.md` / `open-questions.md` after `conclude`; the output owner must finalize them.
+4. **Concluding before all `kind=final-stance` turns exist**, or treating the `outputs/<agent>-final-stance.md` scaffold as the canonical stance instead of the `turns/*.md` final-stance record.
+5. **Treating a chat room (or chat in general) as the decision ledger** — the durable decision is the discuss topic + its conclude outputs; bind it into chat, do not decide only in chat.
+6. **Auto-defaulting participant roles** by agent name / runtime brand / convention instead of taking them from the operator.
+7. **Setting `--expect-next` to a different agent than `--agent`**, or ignoring a `20` (operator block) by trying to write through it.
+8. **Hand-editing the `.aops/agentspace/discussions/**` cache** as if it were authoring truth; it is a read-only mirror of server state — author through the hosted CLI and refresh with `sync pull`.
+
+---
+
+If `--help` and this skill disagree, **`--help` wins** (canonical command surface). If the user guide and this skill disagree, **the user guide wins**.

package/aops-assets-release/skills/aops-cli-docman/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: aops-cli-docman
+version: 14
+description: "Use when an AI agent needs the AOPS CLI Docman playbook: composable document authoring, CRUD-first edits, guarded import, safe delete, publish and mirror refresh, and index/summary/search/answer retrieval gates."
+metadata:
+  supersedes: "v13"
+  short-description: "AOPS CLI Docman thin discipline guide"
+  tags:
+    - cli
+    - docman
+    - documents
+    - composable
+    - retrieval
+    - crud-first
+    - safe-delete
+    - publish
+    - mirror
+    - help-first
+---
+
+# AOPS CLI Docman
+
+Docman owns canonical written knowledge as a composable graph:
+document -> document version -> section -> page -> page version -> links.
+
+This is a thin agent guide. Deep mechanics live in the current `Docman User Guide`; exact flags live in `aops doc ... --help`. Help wins for flags, the guide wins for normative workflow, and the running server schema wins for raw payloads.
+
+## Start Here
+
+1. Read `aops doc --help`, then the smallest nested `--help` surface.
+2. Refresh the repo mirror when freshness matters:
+   `aops doc mirror pull --project-slug <slug> --apply --json`.
+3. Find the smallest relevant guide section with local search or `view doc-page`.
+4. Inspect the current document/version/outline before any write.
+5. Prefer section/page CRUD for a targeted change; do not rebuild a whole document unnecessarily.
+6. After a published content change, rebuild index and summary, test search and answer, then refresh the mirror.
+
+The installed launcher may be `aops`; the package launcher is `aops-cli`.
+
+## Use This Skill For
+
+- creating and reading document groups, documents, and versions;
+- composable section/page authoring and targeted page-version edits;
+- guarded Markdown import when the whole structure changes;
+- publishing a current version and refreshing mirrors;
+- index, summary, search, answer, source, and materialization reads;
+- guarded deletion of a disposable document.
+
+Use `aops-cli-core` for repo context and guard flags, `aops-cli-projectman` for execution/review truth, `aops-cli-discuss` for design decisions, and `aops-cli-agentspace` for durable memory and reusable assets.
+
+## Canonical Sources
+
+1. Hosted `Docman User Guide` in `slug:aops` for deep mechanics.
+2. `domains/docman/USER_GUIDE.md` for domain-development source parity.
+3. `domains/docman/architecture.md` for ownership boundaries.
+4. Live help: `aops doc <group> <command> --help`.
+5. Live discovery: `aops agent tools --domain docman --summary --json`.
+6. Raw schema: `aops agent schema --tool docman.<operation> --summary --json`.
+
+`.aops/docman/**` is a read-only cache. Never hand-edit it as canonical truth.
+
+## Command Map
+
+| Need | Primary surface |
+|---|---|
+| Find ids and structure | `doc list`, `doc version list`, `doc outline get`, `doc source` |
+| Edit one page body | `doc version create --init-mode clone_all`, `doc page draft-save`, `doc page-version update` |
+| Edit metadata | `doc section update`, `doc page update` |
+| Add or reorder graph nodes | `doc section create`, `doc page create`, `doc link`, `doc order` |
+| Import a complete Markdown structure | `doc import --baseline --guard-target --dry-run` |
+| Publish current truth | `doc set-current-version --publish-now` |
+| Retrieval gates | `doc index build`, `doc summary build`, `doc search`, `doc answer` |
+| Refresh local cache | `doc mirror pull` |
+| Delete a disposable document | `doc delete --id --confirm-name --preview`, then reviewed `--apply --confirm` |
+| Raw fallback | `agent schema`, then `agent invoke` only when sugar is insufficient |
+
+## Composable Authoring Rule
+
+All durable guides, ADR logs, specs, and comparable knowledge documents should be structured as meaningful sections and pages. Avoid one giant page when independent sections can preserve meaning and be retrieved separately.
+
+Every new published version should support this read path:
+
+```bash
+aops doc index build --document-version-id <docver-id> --json
+aops doc summary build --document-version-id <docver-id> --json
+aops doc search --document-version-id <docver-id> --q "<known fact>" --remote --json
+aops doc answer --document-version-id <docver-id> --q "<question>" --remote --json
+aops doc mirror pull --project-slug <slug> --document-slug <slug> --apply --json
+```
+
+Review citations as well as the generated answer. Retrieval is deterministic assistance, not authority to ignore the cited source.
+
+## Safe Targeted Page Edit
+
+```bash
+aops doc version create --document-id <doc-id> --version <next-n> \
+  --status draft --init-mode clone_all --source-version-id <current-docver-id> \
+  --apply --json
+
+aops doc outline get --document-version-id <new-docver-id> \
+  --titles-only --depth 3 --json
+
+aops doc page draft-save --page-version-id <pagever-id> \
+  --document-link-id <section-page-link-id> --content '@./target-page.md' \
+  --apply --json
+
+aops doc page-version update --id <new-pagever-id> --status published --apply --json
+aops doc set-current-version --document-id <doc-id> --version-id <new-docver-id> \
+  --expected-previous-version-id <old-docver-id> --publish-now --apply --json
+```
+
+Use a real file or JSON encoder for multiline content. Do not pass literal `\\n` text and assume it became a newline.
+
+## Full Import Guard
+
+Use full import only when the complete document structure truly changes:
+
+```bash
+aops doc import --from-markdown --document-version-id <docver-id> \
+  --source ./candidate.md \
+  --baseline ./.aops/docman/<group>/<document>.md \
+  --guard-target "<intended heading path or title>" \
+  --dry-run --json
+```
+
+Apply only after reviewing the baseline guard and unrelated deltas. If the plan reports `section-direct-body-ignored`, stop; use the documented overview-page synthesis only when direct section prose must become leaf pages.
+
+## Safe Disposable Delete
+
+Read back the exact document id and title. Preview first:
+
+```bash
+aops doc delete --project-slug <slug> --id <document-id> \
+  --confirm-name '<exact current title>' --preview --json
+```
+
+Apply only to the verified disposable record:
+
+```bash
+aops doc delete --project-slug <slug> --id <document-id> \
+  --confirm-name '<exact current title>' --apply --confirm --json
+```
+
+An exact-title mismatch is a `confirmName` validation error and must not delete the record. After a successful delete, a hosted get should return not found. A repo mirror may remain stale until the next mirror pull; stale mirror bytes do not mean the canonical record still exists.
+
+## Reading Ladder
+
+```bash
+# broad local discovery
+aops doc scope search --project-slug aops --q "<topic>" --local --json
+
+# known-version retrieval
+aops doc search --document-version-id <docver-id> --q "<topic>" --local --json
+
+# structure and ids
+aops doc outline get --document-version-id <docver-id> --titles-only --depth 2 --json
+
+# exact mirrored section body
+aops view doc-page <document-slug>#<exact-heading-or-slug> --max-bytes 6000
+```
+
+Use `doc search --remote` or `doc answer --remote` after canonical changes and before mirror refresh. Use `--local` only when the mirror is known to be current or hosted access is unavailable.
+
+## Schema Fallback
+
+Before raw writes:
+
+```bash
+aops agent schema --tool docman.<operation> --summary --json
+```
+
+Sugar option names may differ from raw schema fields. Sugar help wins for `aops doc`; schema wins for `agent invoke`. Do not guess payload fields or retry with invented flags.
+
+## Anti-Patterns
+
+1. Hand-editing `.aops/docman/**` as canonical truth.
+2. Full import for a one-page edit.
+3. Publishing without current-version and expected-previous guards.
+4. Skipping index/summary/search/answer after a guide or ADR change.
+5. Reviewing a stale mirror after a hosted write.
+6. Treating `--confirm` as routine instead of a reviewed destructive gate.
+7. Deleting by broad selector, guessed title, or an unverified id.
+8. Copying the entire user guide into this skill.
+
+## Done When
+
+- the intended current version is published;
+- index and summary builds succeed;
+- a known-fact search and citation-first answer reach the new section;
+- the targeted mirror reports the current version id;
+- any public asset is regenerated from canonical output;
+- temporary records and files are removed without touching unrelated state.