Primitive 03 / Command

One entrance. One clear route.

A command turns a human invocation into a known workflow entry. It parses intent, validates the minimum inputs, selects a mode, and transfers control to the role that owns the conversation.

Command

a user-facing routing contract—not a miniature agent

Try the three real /feature modes to see how the same entrance reaches different stages.

Command routercommands/feature.md

first token: “Add”Full pipeline

ParseNo reserved mode word

PreparePass description as context

AdoptOrchestrator in this conversation

Enter Stage 1 · DiscoveryThe command stops routing. The orchestrator now owns workflow state and user interaction.

01 / Real anatomy

The command should become boring once routing is correct.

The reference /feature command contains five surfaces. Select each one to see which responsibility it owns—and where ownership must stop.

02 / Honest boundary

Markdown describes determinism. Code enforces it.

The reference commands are executable instructions for an AI environment. Their routing rules are explicit, but still interpreted by a model unless a wrapper validates them.

Reference implementation

Markdown command contract

First word: resume
Extract: feature number
Route: first missing artifact

Portable and easy to inspect. Correctness depends on the model following the contract.

Hardened implementation

Parser and validator

mode = parse(argv)
require_feature!(number)
stage = first_missing(files)

Use code when an input, path, enum, or transition has one correct answer.

Portability rule

Port the workflow grammar first. Then move every mechanically verifiable rule from command prose into the host language’s CLI, task runner, or orchestration code.

03 / Command families

Commands differ by what they route into.

The repository exposes several entrances. Their surfaces differ, but each gives the user a stable verb and transfers control to a named owner.

/feature

Pipeline router

Choose a stage

Starts a full feature, skips discovery with a brief, or resumes at the first missing artifact.

→ orchestrator

/request · /bug

Intake adapter

Choose an intake type

Seeds the first report, then keeps the interview in the main conversation.

→ intake agent

/roadmap

Strategy entrance

Adopt a decision lens

Reads open GitHub issues, ICP files, and dependencies to propose—not silently impose—a build order.

→ roadmap analyst

/init-project

Bootstrap procedure

Create the operating substrate

Audits actual project patterns before establishing AGENTS.md, TODO structure, and conventions.

→ guided setup

/define-icp

Persona entrance

Name who it's for

Interviews the user to write or refresh one persona's Ideal Customer Profile. Supports more than one file—a marketplace's buyer and seller, say—so /roadmap judges backlog items against a specific persona, not an average.

→ guided interview

/update-readme

Documentation entrance

Keep the docs honest

Audits the codebase and regenerates the README and domain docs to reflect current state, rather than trusting a hand-written pass to stay accurate as the code moves on.

→ guided audit

One agent, two doors

/bug and /request route to the same intake agent—same identity, same interview flow, only the label and destination differ. It is the cleanest proof on this page that a command is a doorway, not a role: two entrances, one bounded judgment behind both.

04 / Conversation topology

Adopt interactive roles. Spawn bounded specialists.

A command decides where the work begins. Whether a role runs here or as a subagent depends on continuity—not status or complexity.

User/feature resume 001

Main conversationCommand adopts orchestratorMaintains approvals, questions, and pipeline state across turns

Bounded subagents

Architectartifact → artifact

Engineerspecs → code

4 reviewersevidence → verdicts

Keep here

The role must ask follow-ups, secure approval, preserve user context, or coordinate multiple turns.

Spawn

The role has bounded inputs, one output, independent judgment, and a clean stopping point.

Common mistake

Spawning the orchestrator would isolate the very conversation state it exists to coordinate. The command adopts it in place; the orchestrator spawns the specialists beneath it.

05 / Responsibility split

The command routes. The coordinator remembers. The specialist judges.

CommandParse + validate + route

No design or implementation decisions.

CoordinatorTrack + sequence + gate

No specialist work hidden inside orchestration.

SpecialistInspect + judge + write

No workflow control beyond its own handoff.

Make deterministic

Entry mechanics

Recognized mode words
Argument count and shape
Path readability
Feature-number format
Entry-point prerequisites
Stage-to-owner mapping

Leave interpretive

Work after routing

Interview follow-up questions
Whether a brief resolves ambiguity
Architecture tradeoffs
Implementation judgment
Review findings
Recommendations requiring approval

06 / Failure modes

A command fails when it becomes an invisible workflow.

Command does the work/feature designs, builds, and reviews.

Command transfers ownership/feature parses mode, prepares input, adopts orchestrator.

An entrance should not contain the organization behind it.

Ambiguous grammar/feature maybe continue that thing

Named modes/feature resume 001

Stable syntax makes workflows teachable and automatable.

Silent fallbackInvalid path? Guess what the user meant.

Explicit validationUnreadable path → report error and stop.

Do not spend probabilistic judgment on a mechanical failure.

07 / Portable template

Define the grammar before the prose.

Start with supported invocations, mode selection, validation, and the ownership transfer. If the command still makes domain decisions after handoff, its boundary is too broad.

Inspect the source commands

commands/<verb>.mdPortable skeleton

---
name: <Command name>
description: <When to use it + exact usage>
---

# <Command> entry

Arguments: [ARGUMENT]

## Supported invocations
- /<verb> <description>
- /<verb> <mode> <identifier>

## 1. Parse mode
Match only: <allowed mode words>.
Reject: <invalid combinations>.

## 2. Validate inputs
- Require <identifier format>.
- Verify <path or prerequisite>.
- Stop with <actionable error> if invalid.

## 3. Prepare context
Normalize <raw input> into <known shape>.

## 4. Transfer ownership
Adopt or launch <coordinator> at <entry stage>.
Preserve the main conversation when user interaction
or multi-turn state is required.

## Cannot
- Make domain decisions
- Perform the specialist's work
- Continue after ownership transfer