Skip to content

commands.md

Latest commit

 

History

History
331 lines (218 loc) · 11.6 KB

commands.md

File metadata and controls

331 lines (218 loc) · 11.6 KB

Commands

OMA routes slash commands through cto (or brainstorm for brainstorm sessions). Plan state and artifacts are persisted under .oma/ in the workspace directory.

System lifecycle commands stay outside the slash-command surface: oma auth, oma debug, and oma upgrade. oma upgrade follows the stable lane by default and can opt into the alpha lane with --channel alpha.

Command Surface

OMA exposes the command catalog defined in src/commands/catalog.ts.

  • Public stable surface: /plan, /implement, /validate, /roadmap, /roadmap-status, /roadmap-continue
  • Targeted but non-stable: /review, /status, /analyze
  • Advanced orchestration: /brainstorm, /prompt, /loop

The most common implementation workflow is /plan → /implement → /validate. Roadmap commands extend that flow for multi-phase work.

Launch-stable commands

Command Agent Gate Policy Description
/plan cto none Create or revise an implementation-ready plan.
/implement cto redirect_to_plan_if_not_ready Execute an implementation-ready task from the active plan.
/validate cto smallest_sufficient_validation Run the smallest validation scope that proves the requested change.
/roadmap cto none Create or revise a roadmap-scale plan.
/roadmap-status cto none Summarize current roadmap progress.
/roadmap-continue cto none Continue roadmap execution from the current phase.

Targeted commands

These commands are supported for targeted workflows, but they are not the primary launch-stable path.

Command Agent Gate Policy Description
/review cto findings_first Review a plan, diff, or current workspace with findings-first output.
/status cto none Summarize current repo, plan, validation, and execution status.
/analyze cto facts_before_inference Investigate a repository, architecture, or target area before execution.

Advanced commands

These commands stay in the catalog for advanced workflows, but they are not part of the public stable launch surface.

Command Agent Gate Policy Description
/brainstorm brainstorm none Run a structured brainstorm session and persist the artifact.
/prompt cto none Convert a brainstorm artifact into a refined downstream prompt.
/loop cto none Execute roadmap items through plan → implement → validate.

Unsupported helper names

These names are not registered in src/commands/catalog.ts and should not appear in product-facing help.

Command Status Notes
/audit Unsupported Use /validate
/quality-gate Unsupported Use /validate or /review
/instinct-status Unsupported No public replacement
/projects Unsupported No public replacement
/git-clean Unsupported No public replacement

Command Architecture

Commands are registered statically in src/commands/catalog.ts. Each definition declares:

  • agent — which embedded agent handles execution
  • executionIntent — the purpose of the command
  • outputContract — required ## heading fields in the response
  • gatePolicy — pre-execution gate enforced by CommandRouter
  • controlNotes — injected instructions the agent must follow
  • detailPolicy — always_detailed or structured_compact

Before execution, CommandRouter injects a <command_control> block that the receiving agent must treat as the authoritative contract for depth, gates, and output shape.

Common Output Headings

All commands share these required ## headings:

  • State
  • Decision
  • Why
  • Next

These headings must match exactly because downstream tooling parses markdown by heading name.

/brainstorm

/brainstorm runs a structured meta-prompt brainstorm session.

Additional required headings:

  • Questions
  • Contradictions
  • Inspirations
  • Architecture Options
  • Risk Surface
  • Recommended Direction

Rules:

  • Ask clarifying questions before synthesizing — surface hidden assumptions.
  • Identify and surface contradictions in the stated requirements or context.
  • Propose patterns, analogies, and architecture options with trade-off rationale.
  • Persist the brainstorm artifact to .oma/prompts/ before concluding.

/prompt

/prompt converts a brainstorm artifact into a refined downstream prompt artifact.

Additional required headings:

  • Prompt Source
  • Prompt Artifact
  • Downstream Target
  • Quality Assessment

Rules:

  • Read the brainstorm artifact from .oma/prompts/ before generating.
  • Assess prompt quality and flag weak or ambiguous sections.
  • Persist the refined prompt artifact to .oma/prompts/ before concluding.

/loop

/loop executes roadmap items sequentially or in parallel through plan → implement → validate.

Additional required headings:

  • Roadmap Items
  • Current Item
  • Plan Status
  • Implementation Status
  • Validation Status
  • Completed Items
  • Remaining Items
  • Blockers

Rules:

  • Read roadmap items from .oma/roadmap/ before beginning.
  • For each item: plan → implement → validate in sequence.
  • Track progress explicitly: completed, current, and remaining items.
  • Report completion or surface concrete blockers when execution cannot proceed.

/roadmap

/roadmap is roadmap-scale planning for multi-phase, multi-milestone work.

Additional required headings:

  • Roadmap Scope
  • Phases
  • Milestones
  • Dependencies
  • Risks
  • Assumptions

Rules:

  • Follow the /roadmap flow: scope definition → phase breakdown → milestone sequencing → dependency mapping → risk assessment.
  • Use writer for roadmap persistence operations.
  • Persist roadmap state to .oma/roadmap/.
  • A /roadmap run is not complete until roadmap persistence succeeds.

/roadmap-status

/roadmap-status summarizes the current roadmap state.

Additional required headings:

  • Current Phase
  • Active Milestones
  • Progress Summary
  • Blockers

Rules:

  • Read roadmap state from .oma/roadmap/ before summarizing.
  • Report the current phase, active milestones, and overall progress clearly.
  • Surface blockers and next steps explicitly.
  • Keep the answer operational and scoped to roadmap state.

/roadmap-continue

/roadmap-continue advances roadmap execution from the current phase.

Additional required headings:

  • Execution Scope
  • Completed Items
  • Remaining Items
  • Blockers

Rules:

  • Read roadmap state from .oma/roadmap/ before continuing.
  • Identify the current phase and remaining items.
  • Execute the next roadmap item through plan → implement → validate.
  • Track completed items and remaining items explicitly.
  • Report blockers when execution cannot proceed.

/plan

/plan is implementation-grade planning — not a sketch.

Canonical headings:

  • Metadata, State, Decision, Why, Goal, Non-Goals, Scope
  • Entry Criteria, Exit Criteria, Deliverables, Constraints
  • Current State, Impacted Areas, Assumptions, Evidence Contract
  • Execution Mode, Approach, Work Packages, Dependency Graph
  • Delegation Rules, Validation Layers, Failure Classification
  • Risk Register, TODO / Deferred, Ownership, Quality Gates
  • Operator Checklist, Closure Output Contract, Decision Gates
  • Phases, Unknowns, Next

Rules:

  • Treat this as an implementation-grade planning pass.
  • Flow: repo scan → gap analysis → plan-advisor → optional targeted research → clarifications/default assumptions → plan-validator → persistence.
  • ## Phases must use unchecked checklist items (- [ ]).
  • A /plan run is not complete until save_active_plan succeeds.
  • Call save_active_plan with overwrite=true when replacing an existing active plan.

Persistence:

  • Active plan: .oma/plans/active.md + .oma/plans/active.json
  • Archive: .oma/plans/archive/<plan-id>/plan.md + .oma/plans/archive/<plan-id>/plan.json

/implement

/implement continues implementation-ready work from the active plan. If no active plan exists, it redirects to /plan.

Additional required headings:

  • Preparation, Execution, Execution Scope, Preconditions
  • Planned Steps, Assignments and Task Tracking, Changes
  • Validation, Residual Risks, Blockers / TODOs
  • Completed Plan Items, Remaining Plan Items
  • Evidence Status, Gate Result, Failure Classification
  • Exit Criteria Evaluation

Rules:

  • Read .oma/plans/active.md before coding when it exists.
  • If the work is not implementation-ready, redirect to /plan with concrete gaps.
  • Progress persistence is not complete until update_plan_task succeeds (allowUpdate=true).
  • When called with no user arguments and an active plan exists, continue through remaining plan items sequentially until completion or a real blocker.

/validate

/validate coordinates the smallest sufficient validation scope for the current workspace.

Additional required headings:

  • Validation Scope, Checks, Failures, Remediation, Residual Risks

Rules:

  • Choose the smallest validation scope that still proves the requested change.
  • Prefer explicit build, test, lint, and typecheck evidence where relevant.
  • If validation cannot run, explain exactly why and what evidence is still missing.

/review

/review is findings-first and severity-ordered when problems exist.

Additional required headings:

  • Findings, Evidence, Risks

Rules:

  • Determine whether the target is a plan, a code change, or current workspace state.
  • Return findings first and severity-ordered when problems exist.
  • Prioritize correctness, regressions, missing validation, and unnecessary complexity.

/analyze

/analyze is for repository, architecture, or target-area investigation before implementation.

Additional required headings:

  • Question, Findings, Evidence, Options, Recommendation, Uncertainty

Rules:

  • Inspect relevant code paths before concluding.
  • Separate facts from inferences and call out uncertainty explicitly.
  • Prefer concrete repo findings over generic advice.
  • Do not implement changes unless the user explicitly converts this into execution.

/status

/status summarizes the current workspace state without expanding into a full plan.

Additional required headings:

  • Current Focus, Validation Status, Blockers, Next Milestone

Rules:

  • Keep the answer operational and scoped to the current workspace state.
  • Mention git/worktree, validation, blockers, and next milestone only when they materially change the answer.
  • Do not inflate status into a planning document.