QuoxPlan

What QuoxPlan is #

QuoxPlan has been the canonical Quox roadmap store since the 2026-07-25 cutover (owner order). Its quox-strategic roadmap is the live Quox strategic roadmap, reads and writes. Every capability is API-first, so a Claude session can brief on a stream or mutate it with no local install, the same way the dashboard, the standalone CLI, the quox plan CLI and the TUI all do.

roadmap-cli, the tool that used to read and write ~/STRATEGIC_ROADMAP.json directly, is retired: every invocation, including --help and no arguments, prints a retirement banner mapping each old verb to its quoxplan equivalent and exits 1.

~/STRATEGIC_ROADMAP.json is now a generated read-only mirror kept in sync a few seconds after every mutation, never a source of truth. Never hand-edit it or any exported roadmap JSON, edits are silently overwritten on the next mutation.

A fictitious "Meridian Robotics" demo corpus (3 roadmaps, 63+ streams) lives in the same database as quox-strategic, used for onboarding and screenshots. It is a separate roadmap set, not a staging copy of the real one.

Getting around Beta #

QuoxPlan lives under Developers inside QuoxCORE (/quoxplan, lazy-loaded route). No separate app, no inner shell, no second sign-in. Four views, plus a per-stream page:

Org-scoped roadmaps support division/department scope filters: a scope=query param on the streams and timeline endpoints narrows to a scope plus its ancestor context and full subtree. Only the roadmap-list endpoint enforces org scoping today, see the known gaps below.

A stream entering BLOCKED or DECISION_NEEDED auto-creates an open action item (deduped, never double-created); leaving either status auto-resolves it. The Focus view's roadmap-level strip and the stream page both surface open items.

Editing and governance #

Edit mode is a global toggle: inline editors, drag reprioritise, a plan editor with markdown preview, and a dependency combobox. Every mutation, from any surface, is surfaced in the stream's event feed.

Agents reach COMPLETE only through the HITL escape hatch: quoxplan_request_complete files an owner-approval card in the Inbox instead of writing directly. The actual COMPLETE PATCH, and its quoxplan.stream.completed AEE envelope, are issued only once the owner approves; denying the card does nothing.

Notes are append-only. There is no "edit history" for a note, only new notes; the standalone CLI's update <id> notes <value> appends (with a stderr warning) rather than overwriting, matching the server's model.

The collector's own /api/v1/quoxplan/* proxy emits a quoxplan.*AEE envelope for every successful mutating request that passes through it, mapped by method and path to an intent (quoxplan.stream.updated, .status_changed, .note.added, .phase.updated, .plan.updated, .reprioritised, and so on). Emission is fire-and-forget: a failure to emit never fails the underlying request.

The CLIs #

Two CLIs, built in verb-for-verb parity, wrapping the same server API:

Shared verb set: roadmaps, list [roadmap] [--lens focus|tier|all], focus [roadmap], show <id>, timeline [roadmap] [--weeks N], status <id> <STATUS> [--confirm-owner], note <id> <text...>, phase <id> tick|untick <seq> | add <title>, plan <id> [--edit] [--history], move <roadmap> <id> <position>. Every command supports --json (standalone: a flag; parity: --output json).

Five roadmap-cli-retirement verbs exist only in the standalone quoxplan CLI today: add <json>, update <id> <field> <value>, rename <oldId> <newId>, stats [roadmap], completed [roadmap]. quox plan has no equivalents for these five yet, use the standalone CLI or the raw API.

# brief on a stream, then log progress and tick a phase
quoxplan show PC-NAV-CORE
quoxplan note PC-NAV-CORE Slipped a day on tuning, still on track for Friday
quoxplan phase PC-NAV-CORE tick 2
# mark done, owner-confirmed
quoxplan status PC-NAV-CORE complete --confirm-owner

quoxplan tui is an interactive terminal UI (main, detail and timeline screens), standalone-only, needs a TTY. quox plan exit codes map an API error's HTTP status to a process exit code (401→3, 403→4, 404→5, 409→6, 5xx→8), so the 403 COMPLETE gate exits 4 specifically, scripts can branch on it without parsing stderr.

Agents Beta #

Since the 2026-07-25 cutover, quoxplan_* is the only live tool family for roadmap work. The older roadmap_list/roadmap_show/roadmap_statstools still exist in the collector's tool registry but now read the frozen, stale STRATEGIC_ROADMAP.json archive, treat any answer from those as out of date.

The four write tools route through the collector's own /api/v1/quoxplan/*proxy, the boundary where AEE emission and WARD witnessing happen, so agent writes are witnessed today, the same as a quox plan CLI write or a dashboard edit. The standalone quoxplan CLI (bare :3107) remains the one path that is not witnessed.

ROADY, the roadmap agent, is the live consumer of this tool family inside the dashboard: a collapsible chat rail in the QuoxPlan header, addressed to agent: "roady", with a per-surface context prefix (current roadmap id, current stream id if you're on a stream page). Ask it things like "what's blocking PC-NAV-CORE" or "brief me on this stream".

Quoxpert #

Quoxpert is Quox as a Claude skill: install it once and any Claude becomes fluent at operating Quox. The quoxpert-quoxplan sub-skill covers this whole page for an agent: the quoxplan/quox planCLIs, the seven quoxplan_* tools and their witnessing boundary, the dashboard views, and the gotchas above (the JSON mirror, the append-only notes, the owner-gated COMPLETE, the importer's disaster-recovery-only guard).

# Claude Code marketplace
/plugin marketplace add quoxai/quoxpert
/plugin install quoxpert

# or the curl fallback (copies sub-skills into ~/.claude/skills/)
curl -sSL https://raw.githubusercontent.com/quoxai/quoxpert/main/install.sh | bash

Once installed, ask Claude to load the quoxpert-quoxplan sub-skill (or ask "what is Quoxpert", the root skill routes to it for any roadmap task). It never asks you to paste a credential into chat, the CLIs and API tokens are wired the same way this page describes.

Suggested Rules #

A tool only gets used if it ships with the rules that make an agent reach for it at the right moment. Paste this into the consuming team's own CLAUDE.md or agent onboarding file:

### QuoxPlan
- Roadmap reads and visuals go through QuoxPlan (dashboard `/quoxplan`,
  `quoxplan` or `quox plan` CLI, or the `quoxplan_*` agent tools). Never
  hand-edit `~/STRATEGIC_ROADMAP.json` or any exported roadmap JSON, it is
  a generated mirror and gets overwritten.
- Never bypass the COMPLETE confirmation gate; it is owner-gated at the
  API. Use `--confirm-owner` (CLI) or `quoxplan_request_complete` (agent),
  never automate around it.
- Notes are append-only. Don't try to "correct" a note, add a new one.
- Agents orient on a stream via `quoxplan_stream_brief` (or `quoxplan show
  <id>`) before working on it, not from memory of an earlier state.
- After bulk edits, refresh derived views (`quoxplan stats`, the Focus
  lens) before quoting numbers, the export/bulk report tells you what
  actually changed.

Stable, beta and planned #

Compiled from the quoxplan repository's own docs/STATUS_AND_LIMITS_QUOXPLAN.md and verified against services/collector/lib/quoxplanTools.js in quox-dashboard, which fixed the agent-write-tools witnessing gap the same day as this page was compiled.

Stable Verified and pinned by tests

• The owner-confirmation gate on COMPLETE, enforced at the API with a dedicated test, exercised from the Stream page, the Board's drag-to-COMPLETE path, and the HITL approval flow
• Dependency-cycle detection, returning the exact cycle chain in a 422 response
• The dashboard embed's Developers nav entry and lazy-loaded route
• The standalone quoxplan CLI (28 tests) and quox plan for its covered verb set (25 tests)

Beta Working, short usage history against the real roadmap

• Org-scoped roadmaps and division/department scope filters; only the roadmap-list endpoint enforces org scoping today, a caller who already knows a roadmap id can still read or write it directly
• Action items, including auto-emission on BLOCKED/DECISION_NEEDED
• Agent write tools plus HITL-gated completion, now routed through the governed collector proxy so writes are AEE-witnessed
• The Focus, Board, Timeline and Streams views, and the stream page, against both the demo corpus and the live quox-strategic roadmap
• Edit mode: full round trip verified, every mutation surfaced in the event feed
• The containerised backend with 6-hourly backups (local disk only, no off-host copy yet)
• Export/bulk with the server-side JSON mirror, optimistic concurrency via expected_updated
• The five roadmap-cli-parity CLI verbs, standalone quoxplan only

Experimental Runs, not yet adversarially audited

• The command palette (Cmd/Ctrl+K) exists in the standalone dev harness but was not carried into the dashboard-embedded view

Stub Reserved, nothing shipped

• Marketplace, licensing and signing for QuoxPlan as a distributable plugin: flat price fields only, no config schema, safety block or Ed25519 signing yet

Known gap Documented limitations, not softened

• The standalone quoxplan CLI's writes are not AEE/WARD-witnessed, it talks to the bare :3107 server directly. Use quox plan, the dashboard, or an agent tool if a write needs evidence
• Org scoping is a list-endpoint filter, not per-roadmap-id authorisation; there is no per-org license gate on the collector proxy yet, deferred to the multi-tenant phase
• The disaster-recovery importer (npm run import:roadmap) wipes-and-reinserts quox-strategic from the frozen archive file; it refuses to run (exit 2) unless QUOXPLAN_ARCHIVE_RESTORE=1 is set, because running it unguarded once destroyed roughly 20 minutes of live edits