@aopslabs/aops 0.3.31 → 0.3.33

package/aops-assets-release/docs/user-guides/tasker-user-guide.md

@@ -0,0 +1,244 @@
+# Tasker + Runner User Guide
+
+_Release Notes:_ Initial canonical guide aligned to the integrated Tasker profile and M2 CLI sugar.
+
+## 1 Choose the owner first
+
+### 1.1 Overview
+
+Use one owner for each kind of truth:
+
+| Need | Owner |
+| --- | --- |
+| Boards, sprints, microtasks, issues, feedback, and review results | Projectman: `aops pm ...` |
+| Human-first execution boards, tasks, and WorkGroups | Tasker: `aops tasker ...` |
+| Run status, events, artifacts, and guarded operator controls | Runner: `aops runner ...` |
+| Durable resume, decisions, blockers, and closeout memory | Agentspace: `aops mem ...` |
+
+A Tasker WorkGroup is an execution batch, not a Projectman sprint. Tasker may
+retain a weak Projectman origin reference, but it does not own a second planning
+lifecycle.
+
+## 2 Discover before acting
+
+### 2.1 Overview
+
+Start with the installed command surface:
+
+```bash
+aops tasker --help
+aops tasker board --help
+aops tasker task --help
+aops tasker work-group --help
+aops runner --help
+```
+
+The sugar commands intentionally cover only common operator workflows. Discover
+the complete hosted Tasker catalog and the exact input schema when you need a
+capability or field that is not exposed as a human flag:
+
+```bash
+aops agent tools --domain tasker --summary --json
+aops agent schema --tool <tasker-tool-id> --summary --json
+```
+
+Use `--input '@request.json'` on a sugar command when you already have the full
+hosted-tool input. `aops agent invoke` remains the explicit generic escape hatch.
+
+## 3 Tasker boards and tasks
+
+### 3.1 Overview
+
+Read a project's execution boards and one board:
+
+```bash
+aops tasker board list --project-slug <slug> --json
+aops tasker board get --scope-id <scope-id> --id <board-id> --json
+```
+
+Preview every write before applying it:
+
+```bash
+aops tasker board create \
+  --scope-id <scope-id> \
+  --data '{"name":"Delivery"}' \
+  --preview --json
+
+aops tasker board create \
+  --scope-id <scope-id> \
+  --data '{"name":"Delivery"}' \
+  --apply --json
+```
+
+Create and update a human-first execution task:
+
+```bash
+aops tasker task create \
+  --scope-id <scope-id> \
+  --column <column-id> \
+  --title "Implement the approved slice" \
+  --type task \
+  --preview --json
+
+aops tasker task update \
+  --scope-id <scope-id> \
+  --id <task-id> \
+  --patch '{"title":"Implement and verify the approved slice"}' \
+  --apply --json
+```
+
+List or read Tasker tasks with the smallest useful response:
+
+```bash
+aops tasker task list --scope-id <scope-id> --summary --json
+aops tasker task get --scope-id <scope-id> --id <task-id> --summary --json
+```
+
+Tasker sugar does not expose delete or broad compatibility CRUD. Use live tool
+discovery and schema inspection when a hosted-only operation is genuinely
+needed.
+
+## 4 WorkGroups
+
+### 4.1 Overview
+
+The CLI keeps WorkGroups read-only because creation and scheduling policy are
+not part of the minimal operator sugar:
+
+```bash
+aops tasker work-group list --scope-id <scope-id> --summary --json
+aops tasker work-group get --scope-id <scope-id> --id <work-group-id> --summary --json
+```
+
+Do not model a Projectman sprint as a WorkGroup. Link execution to planning with
+the canonical weak origin reference when the hosted schema supports it.
+
+## 5 Runner reads
+
+### 5.1 Overview
+
+Runner sugar is a status-and-control surface over Tasker Loop Runner v2. It is
+not a second executor and it does not acquire worker leases.
+
+```bash
+aops runner status --run-id <run-id> --include-events --summary --json
+aops runner event list --run-id <run-id> --limit 20 --summary --json
+aops runner artifact list --run-id <run-id> --summary --json
+```
+
+Event recording stays executor-owned. It is deliberately not an operator sugar
+command.
+
+## 6 Guarded Runner controls
+
+### 6.1 Overview
+
+Stop, resume, and reconcile are writes. They require `--preview` or `--apply`;
+provide an idempotency key so an operator retry is safe.
+
+```bash
+aops runner stop \
+  --run-id <run-id> \
+  --idempotency-key <key> \
+  --preview --json
+
+aops runner resume \
+  --run-id <run-id> \
+  --idempotency-key <key> \
+  --apply --json
+
+aops runner reconcile \
+  --run-id <run-id> \
+  --kind status \
+  --idempotency-key <key> \
+  --apply --json
+```
+
+After a control write, read `aops runner status` again. A successful request
+means the hosted control operation was accepted; it does not by itself prove the
+run completed useful work.
+
+## 7 Guard and automation rules
+
+### 7.1 Overview
+
+1. Reads do not need an effect flag.
+2. Tasker and Runner writes fail closed unless exactly one of `--preview` or
+   `--apply` is supplied.
+3. Automation should call the same app-owned `pnpm` scripts and CLI commands;
+   do not hand-edit hosted rows or `.aops` mirrors.
+4. Prefer `--summary --json` for agent reads, then request the full payload only
+   when necessary.
+5. If guide prose disagrees with installed `--help`, the installed help wins for
+   command shape. If either is stale, refresh the generated appendix and the
+   canonical Docman document together.
+
+## 8 Troubleshooting
+
+### 8.1 Overview
+
+| Symptom | Action |
+| --- | --- |
+| `guarded_write_requires_preview_or_apply` | Add `--preview` first, inspect JSON, then use `--apply`. |
+| Unknown field or missing capability | Run `aops agent tools --domain tasker --summary --json`, then inspect the selected tool schema. |
+| Tasker catalog is absent | Verify the intended AOPS Server candidate is running and Tasker is in its integrated hosted profile. |
+| Runner control was accepted but state did not change | Read status and events; do not infer executor progress from the control response. |
+| Planning data is being duplicated | Move the planning record to Projectman and keep only an origin reference in Tasker. |
+
+## 9 Appendices
+
+### 9.1 Overview
+
+<!-- aops-generated:tasker-command-catalog:start -->
+
+### 9.2 Generated Tasker and Runner command catalog
+
+#### 9.2.1 Overview
+
+> This compact appendix is generated from the public `aops tasker` and `aops runner` Commander registrations. Do not edit it by hand; regenerate it with `aops docs user-guide --guide tasker`.
+
+| Command | Purpose |
+| --- | --- |
+| `aops runner artifact list` | List artifact refs for a Tasker runner run |
+| `aops runner event list` | List events for a Tasker runner run |
+| `aops runner reconcile` | Request a guarded Tasker runner reconciliation |
+| `aops runner resume` | Resume a Tasker runner run through the guarded control surface |
+| `aops runner status` | Get a Tasker runner status snapshot |
+| `aops runner stop` | Stop a Tasker runner run through the guarded control surface |
+| `aops tasker board create` | Create a Tasker kanban board |
+| `aops tasker board get` | Get a Tasker kanban board by id |
+| `aops tasker board list` | List Tasker kanban boards |
+| `aops tasker board update` | Update a Tasker kanban board |
+| `aops tasker task create` | Create a Tasker task |
+| `aops tasker task get` | Get a Tasker task by id |
+| `aops tasker task list` | Search Tasker tasks |
+| `aops tasker task update` | Update a Tasker task |
+| `aops tasker work-group get` | Get a Tasker WorkGroup by id |
+| `aops tasker work-group list` | List Tasker WorkGroups |
+
+<!-- aops-generated:tasker-command-catalog:end -->
+
+<!-- aops-generated:tasker-discovery:start -->
+
+### 9.3 Generated Tasker capability discovery guide
+
+#### 9.3.1 Overview
+
+> Tasker and Runner sugar cover common operator workflows. The running server catalog remains authoritative for the complete hosted capability set, so this guide does not freeze a second tool inventory.
+
+| Command | Purpose |
+| --- | --- |
+| `aops agent tools` | List federated tools from the canonical operator plane (/api/agent/tools) |
+| `aops agent schema` | Print the live JSON Schema for one tool's input contract — use this before authoring --input payloads |
+| `aops agent invoke` | Invoke a tool via the canonical operator plane (/api/agent/tools/{toolId}/invoke) |
+
+Use the smallest useful read:
+
+```bash
+aops tasker --help
+aops runner --help
+aops agent tools --domain tasker --summary --json
+aops agent schema --tool <tasker-tool-id> --summary --json
+```
+
+<!-- aops-generated:tasker-discovery:end -->

package/aops-assets-release/release.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 2,
+  "version": "0.2.0",
+  "archive": "aops-assets.json.gz",
+  "sha256": "14ea15a5b193d560a633968c4800921949fbc4c190768918023911b64bd98fb3"
+}

package/aops-assets-release/roles/coordinator/ROLE.md

@@ -0,0 +1,28 @@
+# Coordinator role
+
+## Purpose
+
+Act as the operator's single interface for a delegated session and keep assignments, reviews, issues, and handoffs coherent.
+
+## Responsibilities
+
+- Independently research requests before planning or assignment.
+- Bind each assignment to canonical mission, task, sprint, or issue references.
+- Select implementers and reviewers, track bounded slices, and keep PM state truthful.
+- Escalate only decisions or effects owned by the operator.
+- Use idle windows to measure improvements and file them as issues or feedback, not hidden side work.
+
+## Required disciplines and skills
+
+- Discipline: `coordinator-loop`.
+- Skills: `aops-collaborative-work`, `aops-cli-projectman`, `aops-cli-chat`, and `aops-cli-agentspace`.
+
+## Prohibited actions
+
+- Do not replace Projectman or Discuss truth with chat coordination.
+- Do not impersonate an independent reviewer or write a result under another agent identity.
+- Do not perform commits, publication, deletion, or other operator effects without authority.
+
+## Output and handoff
+
+Provide truthful assignment status, accepted/rejected review state, issues, checkpoints, operator decisions needed, and the next action.

package/aops-assets-release/roles/implementer/ROLE.md

@@ -0,0 +1,27 @@
+# Implementer role
+
+## Purpose
+
+Deliver the assigned bounded change and produce evidence that another agent can reproduce.
+
+## Responsibilities
+
+- Read the canonical Projectman scope and referenced policies before editing.
+- Preserve unrelated user work and stay within the assigned paths and effects.
+- Implement the smallest complete slice, run proportional validation, and report exact evidence.
+- Open or update the Projectman review request and resolve findings before handoff.
+
+## Required disciplines and skills
+
+- Discipline: `solo-pm-loop` or `build-review-chat`, as selected by mission/session policy.
+- Skills: `aops-collaborative-work`, `aops-cli-projectman`, and the domain skill for the changed surface.
+
+## Prohibited actions
+
+- Do not approve your own implementation.
+- Do not treat ChatV3 prose as plan or review truth.
+- Do not commit, publish, delete, or perform another operator effect without explicit authority.
+
+## Output and handoff
+
+Provide changed scope, validation results, known gaps, PM/RR references, and the next action.

package/aops-assets-release/roles/reviewer/ROLE.md

@@ -0,0 +1,27 @@
+# Reviewer role
+
+## Purpose
+
+Independently decide whether a bounded plan or implementation is correct, complete, and supported by reproducible evidence.
+
+## Responsibilities
+
+- Read the exact Projectman review request and every file or record in scope.
+- Reproduce the important checks independently and inspect failure behavior.
+- Record findings with severity and actionable evidence; link material findings to issues.
+- Write the review result only under your own reviewer identity.
+
+## Required disciplines and skills
+
+- Discipline: `build-review-chat`; use `design-first-consensus` for material design review.
+- Skills: `aops-cli-projectman`, `aops-collaborative-work`, and the relevant domain skill.
+
+## Prohibited actions
+
+- Do not approve work you implemented or evidence you did not inspect.
+- Do not broaden a validated bounded slice into an unrelated hardening program.
+- Do not treat review acceptance as authorization for commit, publish, deletion, or another operator effect.
+
+## Output and handoff
+
+Provide outcome, reproduced evidence, findings or zero-findings statement, residual risk, and exact RR references.

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

@@ -0,0 +1,112 @@
+---
+name: aops
+version: 11
+description: "Use when an operator or AI agent needs to discover which AOPS CLI family skill applies — project planning, hosted missions, working disciplines, durable memory, document graph, file snapshots, multi-agent coordination, read-only cockpit views, hosted skill/prompt authoring, agent profiles, or board lifecycle. This skill is a thin router/index over the aops-cli-* skill family and AOPS working-discipline skill; load the matching family skill afterwards. Triggers: 'aops', 'aops-cli', 'AOPS overview', 'which aops skill', 'aops cli surface', 'plan in aops', 'aops mission', 'aops discipline', 'aops memory', 'aops discuss', 'aops chat', 'aops docman', 'aops fileman'."
+metadata:
+  supersedes: "v10"
+---
+
+# AOPS skill index
+
+AOPS (Agentic Operations System) is the operator plane that coordinates planning, hosted missions, working disciplines, durable memory, documents, files, multi-agent coordination, cockpit views, and skill/prompt authoring through the `aops-cli` command surface. Domain ownership lives in the underlying domains (`projectman`, `agentspace`, `docman`, `fileman`, etc); `aops-cli` exposes the operator sugar.
+
+This skill is a **thin router/index**. It does not carry workflow detail — it points to the family-specific skill that does. Load the matching `aops-cli-*` skill once you identify the right family; that family skill points to the relevant hosted Docman mirror or domain guide plus the live `aops-cli <command> --help`.
+
+> Override priority across the AOPS skill family: `--help` wins over skill text (canonical command surface); domain user guide wins over skill text (canonical normative content). Searchable principles: AOPS Docman document `aops-doc-skill-system-principles` (slug:aops, search by title + section name + keywords).
+
+> Closeout policy: board closeout is operator-controlled. Agents should not auto-run `pm board closeout` or closeout memory just because a turn is ending; use resume/handoff/checkpoint context until the operator explicitly requests or approves closeout.
+
+## Discovery: which family for what
+
+### aops-cli-core
+
+The CLI core operator playbook: help-first command discovery, the guard flag conventions (`--preview`, `--apply`, `--confirm`, `--idempotency-key`, `--json`), the canonical operator family map (`init`/`setup`/`auth`/`host`/`agent`/`api`/`sync`/`view`), local cache vs. hosted server routing, and the raw hosted-invoke fallback when sugar is missing. **Load this skill first** when you are unsure about CLI guard semantics, sync mechanics, or how to escape from missing sugar to `agent invoke`. It also carries the canonical Tool-Input-Schema discovery block the other family skills point to. Canonical: `.aops/docman/aops-guides/aops-cli-user-guide.md`.
+
+### aops-cli-discuss
+
+Standalone decision / consensus: `discuss` durable decision topics, the design-decision ritual (independent research → ≥4 substantive turns → `kind=final-stance` per agent), the two-agent turn protocol, and deterministic `conclude` outputs. There is **no automatic decision bridge** — surfacing a decision to PM or chat is explicit. **Load this skill** when running a server-canonical design decision or peer consensus before implementation. Canonical: `.aops/docman/domain-guides/agentspace-user-guide.md` (Coordination semantics + Anti-patterns appendix + Troubleshooting sections).
+
+### aops-cli-chat
+
+Coordination / wake: hosted Agentspace rooms and DMs, members and roleKey vocabulary, reference bindings, messages, and `inbox`/`listen`/`catchup` read cursors. Rooms are FLOW (coordination + wake), not the decision ledger. **Load this skill** when coordinating peers, posting a review-request wake, or running a catch-up loop. Canonical: `.aops/docman/domain-guides/agentspace-user-guide.md` (Coordination semantics). For review-request/result, re-review, and operator-approved closeout truth, use `aops-cli-projectman`.
+
+### aops-cli-projectman
+
+Planning truth (server-canonical): `pm board/ktask/sprint/utask/issue/feedback/handoff` CRUD, atomic board lifecycle (`kickoff`/`resume`/operator-approved `closeout`), sprint phase + microtask plan patching, status derivation, subject-aware handoff, and the PM-vs-Agentspace ownership boundary. **Load this skill** when creating or moving kanban tasks, building or completing sprints, opening issues/feedback, or running board windows from kickoff/resume through operator-approved closeout. Canonical: `domains/projectman/USER_GUIDE.md`.
+
+### aops-cli-mission
+
+Hosted Agentspace mission command discipline: mission create/list/get/update/resume, mission policy seed through `--policy-json`, active Projectman implementation-plan references, `aops-cli start --resume` integration, and the ownership boundary between Mission, Projectman, and Agentspace memory. **Load this skill** when creating or resuming a hosted mission, carrying mission policy into startup, binding implementation-plan refs, or diagnosing mission/session resume behavior. Mission closeout checks and handoff helpers are explicit future automation unless the matching command exists in live `--help`.
+
+### aops-working-disciplines
+
+AOPS execution discipline routing: solo-pm-loop, build-review-chat, and design-first-consensus; how each maps to mission policy, Projectman review requests/issues, Agentspace memory, standalone discuss consensus, ChatV3 coordination, and closeout guardrails. **Load this skill** when selecting or interpreting a working discipline, reviewing `aops-cli start` discipline policy output, planning build-review-chat slices, or applying the closeout checklist without running operator-only board/room closeout.
+
+### aops-cli-agentspace
+
+Agentspace context and reusable assets: durable memory (`mem write/list/update/synopsis/resume/compact/prune/search`), sticky guidance, generated synopsis, experience capture (`exp`), the hosted asset families (`project`/`prompt`/`resource`/`artifact`/`skill`), agent profile metadata, and the activity log read surface. **Load this skill** when writing kickoff/resume/checkpoint memory, operator-approved closeout memory, authoring sticky bootstrap rules, publishing prompt or skill versions, or composing agent profiles for collab `--profile-mount`. Canonical: `.aops/docman/domain-guides/agentspace-user-guide.md` (Entity model + Memory model + Useful commands sections).
+
+### aops-cli-docman
+
+Document graph CRUD-first authoring + retrieval: section/page/page-version/link CRUD sugar, draft-save body edits, status workflow (`draft`/`review`/`published`/`archived`), retrieval helpers (`outline`/`index`/`summary`/`search`/`scope search`/`answer`/`source`), publish flow, and local mirror read fallback. **Load this skill** when targeting a known document node for an edit (prefer CRUD sugar over full mirror push), running search-driven retrieval over saved document versions, or publishing a document version's current pointer. Canonical: `domains/docman/USER_GUIDE.md`.
+
+### aops-cli-fileman
+
+File snapshot, diff, restore, copy, zip, and clean over hosted Fileman targets: target inventory CRUD, immutable snapshot lifecycle, snapshot-vs-snapshot or snapshot-vs-live diff, destructive restore (with explicit guards), non-destructive copy, archive hand-off, and retention pruning. **Load this skill** for snapshotting a file or directory, inspecting drift, restoring a snapshot, or applying retention policy — Fileman is hosted-canonical with no `.aops/fileman/**` mirror. Canonical: `domains/fileman/USER_GUIDE.md`.
+
+### aops-cli-tasker
+
+Insan-first task manager + scenario-first runner: `tasker` (task list/get/create/update/delete + label/checklist/relation/comment + system views like my-work/today/upcoming) and `runner` (tracked execution backed by Projectman subjects, ad-hoc runs, workflow instances, queue workers, ingress). **Load this skill** when pushing a task into the runner queue (`tasker create --enqueue`), inspecting runner run state, or composing a workflow instance — Projectman remains the planning owner; Tasker is human-first execution. Canonical: `domains/tasker/USER_GUIDE.md`.
+
+### aops-cli-view
+
+Read-only local-cache cockpit and hosted-inventory presentation: `view dashboard`, focused subject views (`view sprint/task/board`), Agentspace context views (`view memory/resume/discussions`), Docman/skill/prompt mirror views, hosted project inventory (`view hosted-projects/hosted-inventory`), and `view digest --depth shallow|deep` for handoff context packs. **Load this skill** when you need to inspect repo or hosted state without mutating it; view never syncs, refreshes, or mutates. Canonical: `.aops/docman/aops-guides/aops-cli-user-guide.md` (AOPS markdown view sugar section).
+
+### aops-cli-board-lifecycle (deprecated pointer)
+
+Folded into `aops-cli-projectman` from PR2 onward. Routes agents to the projectman skill for board kickoff/resume/operator-approved closeout, kanban-task and sprint policy, and atomic board windows. Kept as a stable pointer for one release cycle so older prompts and AGENTS references keep working. New task prompts should prefer `aops-cli-projectman` directly.
+
+### aops-cli-sugar-authoring
+
+Thin authoring playbook for **adding or extending sugar CLI commands** on `aops-cli` or `eops-cli` over a hosted domain operation. Identifies the right command surface (commander-based aops-cli vs. argv+registry eops-cli), points to canonical authoring sources, and keeps every new sugar wired to `agent schema --tool <id>` discovery. Use this when the target operation already exists in the kit/host-plugin manifest and you just need to expose or compose it as a sugar.
+
+### aops-cli-tooling-agent (modular index)
+
+Compatibility index for the modular AOPS CLI skill family after the v33 split. Routes agents to the right family skill (`aops-cli-core`, `aops-cli-discuss`, `aops-cli-chat`, `aops-cli-projectman`, etc.) and preserves help-first + hosted-mirror reminders for old prompts. Use when a runtime is missing a family-specific skill and an agent needs the fallback help-first sequence; otherwise prefer the smallest matching family skill.
+
+## How to use this index
+
+1. Identify the family from the table above (e.g. "I need to plan a sprint" → `aops-cli-projectman`).
+2. Load that specific skill with the Skill tool (Claude) or by referencing it in the catalog (Codex).
+3. The family skill points you to its canonical user guide section (by name), its `--help` surface, and the doc discovery ladder for section-focused reading.
+4. When `--help` and skill text disagree, `--help` wins. When user guide and skill text disagree, user guide wins.
+
+## Server-canonical and local cache
+
+- Server-canonical truth: the hosted AOPS server is the source of truth for planning (`projectman`), durable memory (`agentspace.memory-item`), discussion topics (`agentspace.discussion-topic`), and experience. Create, write, and read these through the hosted `aops-cli` surface (`pm`, `mem`, `discuss`, `exp`).
+- Local cache: `.aops/projectman/**`, `.aops/agentspace/memory/items/**`, `.aops/agentspace/discussions/**`, and `.aops/agentspace/collabs/**` are a read-only local cache of server state, refreshed by `sync pull`. Do not treat them as an authoring source or planning truth.
+- Hosted prompt/skill mirrors: `.aops/hosted/prompts/**` and `.aops/hosted/skills/**`; refresh with `aops-cli sync pull --apply --hosted-project-slug aops --json`.
+- Hosted Docman guide mirrors: `.aops/docman/**`; refresh separately with `aops-cli doc mirror pull --project-slug aops --document-slug <slug> --out-dir ./.aops/docman --apply --json`. `sync pull` does not refresh `.aops/docman/**`.
+- Never hand-edit a mirror or cache as canonical truth. Change hosted truth via the hosted CLI (`aops-cli pm|mem|discuss|prompt|skill|doc ...`) and refresh the matching mirror.
+- `--yes` is non-interactive/fail-fast mode for supported commands; do not treat it as a proven fix for an abort unless logs prove that.
+
+## Tool Input Schema discovery
+
+For any hosted write, fetch the live JSON Schema first instead of guessing payload fields: `aops-cli agent schema --tool <domain>.<operation>`. The full explanation lives in `aops-cli-core` (Tool Input Schema section); architecture: slug:aops `tooling-cli-host-plugin-system` (Agent Gateway section, "Tool Input JSON Schema Discovery").
+
+## Deep reading (doc discovery ladder)
+
+Search the guides by content instead of linear reads — pick the rung by what you know:
+
+```bash
+# broad search across the project's guides (local mirror, no id needed):
+aops-cli doc scope search --project-slug aops --q "<keyword>" --local --json
+# exact search within a known guide version:
+aops-cli doc search --document-version-id <docver-id> --q "<keyword>" --local --json
+# section tree of a known guide version (hosted-only — no local fallback):
+aops-cli doc outline get --document-version-id <docver-id> --json
+# project/sprint memory:
+aops-cli mem search --subject project --id <project-uuid> --json
+```
+
+There is no `aops-cli docman … --slug` command — that path does not exist; use the ladder above. Reference guide sections by document title + section name + keywords, never a bare section number.