These are proposed commands, not yet shipped. Greenlight a subset, then implementation happens via canonical agent-commands.md plus per-project profiles. Every entry below is a specification, not a capability.
Scope: 20 candidates across capture, GitHub, Jira, memory, research, Confluence, deploy, observability, and comms. Selection bias favours commands that already exist as recurring ad-hoc flows and deserve a stable grammar.
| command | access | budget | purpose | priority |
|---|---|---|---|---|
| capture & handoff | ||||
| /brief | RW-project | 3–5 | Snapshot current convo as a handoff doc (not a new convo). Use before long breaks, before sharing with a colleague, or as input to /spawn. | ★★★ |
| /diary | RW-project | 2–4 | Append today's activity summary to a rolling diary-YYYY-MM.md project file. Weekly/monthly aggregation on request. | ★ |
| /digest | RW-project | N×2+3 | Summarize last N project conversations into one digest doc. Useful before retros. | ★★ |
| github | ||||
| /pr | RW-repo | 4–8 | Create or update a PR from current branch; auto-generate body from commits plus slice guidance. Defaults to kyriba-eng/platform-capabilities. | ★★★ |
| /chain | RW-mem | 2–5 | View and manipulate the =POC PR CHAIN. Subcommands: add #N, status, reorder. | ★★★ |
| /gh | RO | 3–6 | Ad-hoc GitHub API query via HTML pipeline with the right PAT auto-selected. /gh issue #241, /gh search "NotificationRequest" --repo=.... | ★★ |
| /slice | RW-repo | 3–5 | Create a slice branch per Kyriba convention (poc/PSE-989-<n>-<name>) off the current chain head; prepare first commit. | ★★ |
| /gate | RO | 5–8 | Run pr-review-gates-v2 checklist against current diff. Reports violations per architecture-review rules. | ★★★ |
| jira | ||||
| /jira | RO | 2–3 | View any Jira issue by key: summary, status, assignee, latest comments, attachments. Short form of the read flow. | ★★ |
| /standup | RO | 5–8 | Generate standup notes (yesterday / today / blockers) from yesterday's GH activity plus Jira transitions. Outputs Markdown ready to paste. | ★ |
| memory & context | ||||
| /recall | RO | 1–2 | Print memory entry by tag. /recall =POC for current POC state. Avoids the full retrieve for a single lookup. | ★★★ |
| /pin | RW-mem | 2–3 | Quick-pin an observation to a tag without full RLA ceremony. Staging-style entry with a soft TTL flag that /compact honors. | ★★ |
| /tag | RO | 2–3 | List all memory tags with last-updated dates. Index view; complements /audit. | ★★ |
| research & synthesis | ||||
| /dig | RO | 8–20 | Recursive primary-source research per the source-verification rule (max 10 hops). Useful for architecture decisions, vendor claims, standards. | ★★ |
| /opine | RO | 3–5 | Single-question dual-cave (anthro + open) with synthesis. Lighter than /fanout for a one-shot question. | ★★★ |
| confluence | ||||
| /wiki | RO | 2–4 | Search Confluence; return top snippets with links. /wiki "notification contract". | ★★ |
| deploy & sync | ||||
| /deploy | RW-repo | 2–4 | Trigger a GH Pages / repo sync deploy. deploy cheatsheet pushes current cheatsheet; deploy agents pushes canonical. Idempotent. | ★ |
| observability | ||||
| /status | RO | 2–3 | Current convo snapshot: files touched, commands run, pending items. Lighter than /rite (no classification). | ★★ |
| /where | RO | 1–2 | Contextual orientation: current project, active PR (from memory/context), Jira issue in scope, branch if inferable. Micro-command for disorientation. | ★ |
| comms | ||||
| /reply | RW-repo | 3–6 | Draft a reply to ONE item (PR comment, Jira comment, email snippet). Dual-cave optional (--cave). Does not publish. Single-target version of /review. | ★★ |
1. capture decision tree: /brief vs /spawn vs /digest
want to preserve conversation state?
│
┌─────────────────────────┼─────────────────────────┐
▼ ▼ ▼
doc only, no new new convo with multi-convo
conversation work to continue summary wanted
│ │ │
▼ ▼ ▼
/brief /spawn /digest
(handoff.md in (fresh context, (rolls up last N
project files) same task queue) conversations)
2. PR pipeline: /slice → edits → /pr → /chain → review → merge
/slice edits commit /pr
┌───────┐ ──▶ ┌───────┐ ──▶ ┌────────┐ ──▶ ┌───────┐
│branch │ │diff │ │local │ │draft │
│off │ │scoped │ │commit │ │PR on │
│chain │ │to │ │signed │ │GH │
│head │ │slice │ │ │ │ │
└───────┘ └───────┘ └────────┘ └───┬───┘
│
┌───────────────────────────────────────────────┘
▼
/chain add #N ──▶ review cycle ──▶ /review ──▶ merge
(tracks slice (reviewer (harvested (chain
order in memory) comments) responses) advances)
3. /gate in the PR lifecycle
commit ──▶ /gate (local diff) ──▶ /pr ──▶ /review ──▶ merge
│
▼
violations? ──yes──▶ fix ──▶ re-run /gate
│
no
│
▼
proceed to /pr
/gate checks: PSE-slice size, test parity, no-cross-module imports,
migration reversibility, naming per review-gates-v2.
4. /opine vs /fanout vs /meteorite
need parallel cognition?
│
┌───────────┼────────────────┐
▼ ▼ ▼
1 question N independent project-wide
need depth subtasks /rite scan
│ │ │
▼ ▼ ▼
/opine /fanout /meteorite
(dual-cave, (N workers, (fanout rite
synthesized) harvester) --since=90)
rule of thumb: if you would otherwise copy the same prompt to
two caves and diff the answers, use /opine.
5. memory lifecycle ring
observe something worth keeping
│
▼
/pin <tag> (staging, soft TTL)
│
▼
( time passes, /compact runs )
│
▼
consolidated
┌───────┴───────┐
▼ ▼
/recall <tag> /tag
(lookup one) (index all tags)
│
▼
full /audit (monthly)
6. /reply vs /review
inbound comment(s)?
│
┌────────────┴────────────┐
▼ ▼
one specific item all unreplied on PR
│ │
▼ ▼
/reply /review
┌──────────────────┐ ┌──────────────────┐
│ manual target │ │ auto-discover │
│ optional --cave │ │ dual-cave workers│
│ no harvester │ │ harvester convo │
│ no publish │ │ no publish │
└──────────────────┘ └──────────────────┘
7. /standup source pipeline
yesterday 00:00 ──────────── now
│ │
├── GH events ────────┤ merges, reviews, new PRs
├── Jira transitions ─┤ status changes assigned to me
├── project files ────┤ diary entries if present
│ │
▼ ▼
aggregate ──▶ classify ──▶ format (Y / T / blockers) ──▶ clipboard-ready MD
8. /status vs /rite
/status (RO, 2-3 calls) /rite (RO, 2-3 light / 6-8 full)
───────────────────── ─────────────────────────────
files touched classification (PERSIST / DISCARD / UNPERSISTED)
commands run confidence scoring
pending TODOs memory drift detection
active branch triggers /reap when called via /kill
rule: /status answers "where am I"; /rite answers "what should survive".
9. /deploy targets
/deploy cheatsheet ──▶ push cheatsheet/*.html ──▶ GHA sync ──▶ Pages
/deploy agents ──▶ push agents/*.md ──▶ consumers /inhale
/deploy <custom> ──▶ resolve from agent-project-profile.md
idempotent: if tree is clean, no-op with message.
Produces a handoff document describing the current conversation: goal, decisions taken, artifacts produced, open questions. Writes to briefs/YYYY-MM-DD-<slug>.md in the project. Does not create a new conversation; does not alter memory.
Rationale: today this is done ad-hoc before long breaks or when sharing state with a colleague. The output is reliably the same shape; worth making a command so it is cheap to invoke and consistent to read.
/spawn --from-brief <path> (future) to seed a fresh convo/brief /brief --slug=poc-notification-refactor /brief --stdout # print, do not write
Creates or updates a pull request from the current branch. Body is generated from commits since fork-point plus slice guidance (links back to chain parent, Jira key, test notes). Defaults to the project's default repo; overridable with --repo=.
Rationale: PR creation is the single most repeated RW-repo action. Current flow is "copy commit log, remember the slice template, paste into gh pr create". Command encapsulates the template and the PAT choice.
/gate has not passed on current HEAD (override with --force)agent-project-profile.md=POC PR CHAIN when invoked inside a chain context/pr /pr --draft /pr --title "PSE-989-3 split notification router" --repo=kyriba-eng/platform-capabilities
Read/write the POC PR chain tracked in memory under =POC PR CHAIN. Subcommands: add #N, remove #N, status, reorder 3,1,2, clear. Status fetches live PR states (merged, open, conflicts) and prints a table.
Rationale: chain state lives in memory but is manipulated by natural-language prompts that waste a round-trip per change. A command collapses it.
/chain status is the canonical answer to "where is the chain"/slice which reads head to branch from/chain status /chain add #241 /chain reorder 2,1,3
Runs the pr-review-gates-v2 checklist against the local diff. Reports violations grouped by rule with file:line anchors. RO: does not fix, does not commit, does not open PR.
Rationale: gates are currently re-applied mentally after every commit, which is the worst time to remember them. Making it a command lets it run automatically before /pr (with override).
.review-gates-v2.yml if present, else uses canonical default/pr to parse/gate /gate --since=origin/main /gate --rule=no-cross-module-imports
Prints a single memory entry (or small group) by tag. No full retrieve, no summary. /recall =POC, /recall @pat-github. Complements /tag.
Rationale: the full retrieve is the wrong tool when you want one fact. It bloats context and muddles attention. A targeted lookup is ~100x cheaper.
--fuzzy/recall =POC /recall @pat-github /recall --fuzzy notification
Sends one question to both caves (anthro + open) in parallel, then synthesizes their answers with deltas called out. No harvester, no fanout ceremony. For single architectural or judgement calls.
Rationale: dual-cave for one question is a proven pattern but heavy when wrapped in /fanout. /opine is the right-sized tool for "help me decide X".
/pin--one-cave=anthro|open to force single source if budget matters--fresh/opine "should notification contract be push or pull?" /opine --fresh "estimate migration risk for 3-slice plan"
Changes required to ship any subset of the above, organised by canonical file.
| file | change | commands affected |
|---|---|---|
| agent-commands.md | new rows in command table; full spec blocks per command; update state machine if /brief or /digest interact with PERSIST/UNPERSISTED classification | all 20 |
| agent-project-profile.md | defaults for /pr (repo, reviewers, PAT key), /slice (naming), /deploy (targets), /jira (project key) | /pr, /slice, /deploy, /jira, /standup |
| agent-tooling.md | document HTML-pipeline wrapper for /gh; document cave invocation for /opine; memory access patterns for /recall//pin//tag//chain | /gh, /opine, /recall, /pin, /tag, /chain |
| agent-memory-framework.md | formalise staging TTL flag used by /pin; define =POC PR CHAIN schema referenced by /chain | /pin, /chain, /compact |
| cheatsheet/index.html | add new category sections (capture, memory-lookup, research, comms) for any shipped commands; grid layout stays 3-col | any shipped subset |
Design constraint reminder: new access scopes are not introduced. Everything maps onto existing RO / RW-conv / RW-project / RW-mem / RW-repo / RW-project+mem levels.
Reply with any of:
1, 4, 5, 8, 11, 15: ship exactly these numbers (from the table above).top 6: ship all priority-3 commands (/brief, /pr, /chain, /gate, /recall, /opine).all but 2, 10, 17, 19: ship everything except the listed numbers.all: ship the full 20 (not recommended in one pass).After greenlight: implementation PR updates agent-commands.md + referenced files in one commit per command, chained in the canonical order (spec first, cheatsheet last).
Dual-cave (anthro + open) reviewed the full list independently. Strong convergence: keep ~7, fold/kill the rest, and ship a reversibility triad before any new RW command lands. This section supersedes the per-row priorities above where it contradicts them.
| command | verdict | rationale |
|---|---|---|
| /brief | keep ★★★ | Durable artifact. Unambiguous. Ship. |
| /pr | keep ★★★ | Split into subcommands: /pr plan, /pr create, /pr refresh-body, /pr publish. Single-verb create/update clobbers hand edits. |
| /gate | keep ★★★ | Daily guardrail. Spec the gates doc location and version it alongside agent-commands.md. |
| /recall | keep ★★★ | Cheap daily win. Requires explicit tag taxonomy, else degrades to fuzzy search. |
| /pin | keep ★★★ (up from ★★) | Shapes memory quality more than /recall. Drop soft TTL; make TTL explicit and surfaced in /audit. |
| /reply | keep ★★★ (up from ★★) | Narrow fast lane. Common enough to deserve the slot. |
| /dig | keep ★★★ (reframed) | Not a recursive browse; a knowledge-graph builder. See detail card below. |
| /where | keep ★★ (up from ★) | Cheap context-switch reset. Pays every day. |
| /chain | defer | Concept correct, backend wrong. Canonical chain must live in repo/project artifact, not memory compaction zone. Fix storage first. |
| /standup | defer | Composite of /digest + /jira + /gh. Revisit after primitives stable. |
| /digest | fold | Mode of /brief --scope=project --since=N, not a new verb. |
| /diary | fold | /brief --append=diary. Standalone adds append-only sediment. |
| /slice | fold | Setup step of /pr create, not a peer. Two git commands do not earn a command. |
| /opine | fold | /fanout N=2 --dual-cave --synthesize. Preset, not primitive. |
| /tag | fold | /recall --tags. Subcommand. |
| /status | fold | /rite --brief. Redundant with existing classifier output mode. |
| /gh | kill | Generic escape hatch. Opaque PAT auto-selection breaks trust. Browser/prompt is better. |
| /jira | kill | Fetcher, not workflow. Prompt suffices. |
| /wiki | kill | Same pattern as /jira. |
| /deploy | kill | No rollback story. Idempotence is not reversibility. Revisit after /rewind lands. |
Net shape: 7 new top-level commands (/brief, /pr, /gate, /recall, /pin, /reply, /dig), 1 optional (/where), 2 deferred (/chain, /standup), 6 folded as flags, 4 killed.
Both caves independently proposed a reversibility primitive as the #1 missing command. That is the strongest signal in the entire review. These three land first; everything else waits.
Undo the last mutating command. Restores previous file content, memory entries, PR body revisions, any declared write target. Requires every RW command to append a reversal hint to a ring buffer (per-conversation, bounded).
--n=N, or specific run-id--preview: show what would be reverted without acting/reap boundary without --force (that is the lifecycle seam)/rewind /rewind --n=3 --preview /rewind --run=RUN-4421
Prints current convo's tool-call spend plus per-command actuals vs declared ranges. Turns declared budgets into enforceable contracts. Feeds /audit with drift data.
--since= for windowed view/cost /cost --since=RUN-4400 /cost --audit # feeds /audit with current-window spend
Dry-run any command. Prints exact tool plan, write targets, estimated budget, rollback path. No side effects. Pairs with /rewind to make reversibility auditable at invocation time.
/rehearse <cmd> <args>/pr publish, /reap, /land/rehearse /pr publish /rehearse /reap /rehearse /land #241
Safe merge of PR (or stack head): run /gate, merge, retarget child PRs, update chain manifest. One reversible step replacing the current manual dance. Refuses if /gate fails; --force bypasses with audit trail.
land-RUN-XXXX.md rollback note (for /rewind)--ignore-comments/land #241 /land chain head /land #241 --force
Ranked executable next-actions pulled from current convo, active PR, Jira issues in scope, and known blockers. Not a summary; an action queue. Each item includes an inferred command invocation where possible.
=POC PR CHAIN, Jira assigned-to-me, unreplied PR comments/cmd args" hint/next /next --top=5 /next --scope=pr
Binary-search across convo history, PR chain, and memory snapshots to find when a property changed. Temporal diagnostic; complements /audit. /audit detects drift, /bisect finds the pivot.
/bisect "PSE-989-2 missing from chain" /bisect --window=30d "notification contract field X removed"
Memory delta since last /compact. Which entries are new, mutated, stale. Makes /compact decisions auditable. Fills the memory-side gap that /audit does not cover.
/compact run--since=30d for fixed window/compact as preview input/diff-mem /diff-mem --since=30d /diff-mem --staged # only /pin-created entries
Follow-the-white-rabbit primary-source research that builds a durable knowledge graph in project files. Not a recursive browse; an artifact. Each node is (claim, source URL, confidence, retrieved-at). Edges are explicit citations between nodes. Output is a navigable markdown tree at dig/YYYY-MM-DD-<slug>/ with an index and per-node files.
dig/.../index.md shows the graph as an outline/recall: /recall dig:<slug> pulls the index/dig "ISO 20022 pain.001 vs pain.008 mandate requirements" /dig --slug=notification-contract "does push-or-pull affect at-least-once semantics?" /dig --extend=notification-contract "follow the GS1 branch"
reversibility triad: /cost → /rehearse → /rewind
before any RW command:
/cost (am I within budget?)
│
▼
/rehearse <cmd> (what will it do, what's the rollback?)
│
▼
<cmd> executes (ring buffer entry written)
│
▼
/rewind (if regret; bounded by ring buffer depth)
Without this triad, "recoverable" and "cost-transparent" are marketing.
/dig knowledge graph layout
dig/
└── 2026-04-18-notification-contract/
├── index.md (outline, edges, confidence heatmap)
├── n001-seed.md (original question)
├── n002-iso20022-spec.md (primary: iso.org PDF)
├── n003-ebics-mandate.md (primary: EBICS consortium spec)
├── n004-gs1-semantics.md (branch from n002)
└── n005-rejection.md (contradicts n003, confidence=low)
each node: quote + URL + parent + children + confidence + retrieved-at
/recall dig:notification-contract prints index.md
/cost, /rehearse, /rewind. Ring-buffer infra in project files. Every existing RW command retrofitted to emit reversal hints./brief, /pr (split modes), /gate, /recall, /pin (explicit TTL)./reply, /dig, /land./next, /bisect, /diff-mem, /where./chain (after storage redesign), /standup (after primitives stable), /deploy (after /rewind).Folded as flags of existing or Phase-1 commands: /digest, /diary, /slice, /opine, /tag, /status. Killed: /gh, /jira, /wiki.