# Pipeline Command Authoring Standard

<purpose>
Authoring standard for pipeline commands (.claude/commands/*.md). Complements skill-authoring.md (FSM style) — Pipeline suits linear staged pipelines; FSM suits orchestrators and decision engines.

Selection criteria: control flow complexity. Use FSM when ≥3 conditions are met (non-linear branching, runtime chain reshaping, precise re-entry, multi-component handoff, 20+ persisted fields); otherwise use Pipeline. See knowhow DCS-20260531-1048.
</purpose>

---

## 1. Architecture: Staged Pipeline

Pipeline commands are **staged linear pipelines**: entry routing → sequential phases → produce artifact → report completion.

Core characteristics:
- Mode is fixed at entry (create/revise/check), no runtime reshaping
- Each phase has explicit input/output contracts
- Implementation details delegated to workflow files (`Follow 'workflow/X.md' completely`)
- Self-contained — unaware of orchestrators (ralph, etc.)

### File Structure

```
---
frontmatter (name, description, argument-hint, allowed-tools)
---

<purpose>              <!-- Required -->
<required_reading>     <!-- Conditionally required: when command delegates to a workflow file -->
<deferred_reading>     <!-- Conditionally required: when command has lazily loaded templates -->
<context>              <!-- Required -->
  ### Pre-load          <!-- Standard subsection -->
  ### Role Knowledge    <!-- Standard subsection -->
<interview_protocol>   <!-- Conditionally required: when command has multi-round interactive decisions -->
<execution>            <!-- Required -->
<completion>           <!-- Required -->
<error_codes>          <!-- Required -->
<success_criteria>     <!-- Required -->
</output>              <!-- Closing tag -->
```

### Section Requirement Classification

| Level | Sections | Rule |
|-------|----------|------|
| **Required** | purpose, context, execution, completion, error_codes, success_criteria | Every pipeline command must have these |
| **Conditionally Required** | required_reading, deferred_reading, interview_protocol | Include when the trigger condition is met; omit when not applicable |

**Trigger conditions for conditionally required sections:**

| Section | Include when | Omit when |
|---------|-------------|-----------|
| `<required_reading>` | Command delegates to a workflow file (`Follow 'workflow/X.md'`) | Command is self-contained with all logic inline |
| `<deferred_reading>` | Command loads templates or references on-demand during execution | No lazy-loaded dependencies exist |
| `<interview_protocol>` | Command has **multi-round interactive decision trees** (scope → depth → dimensions, etc.) | Command only uses AskUserQuestion for simple one-shot confirmations (proceed/cancel, yes/no) |

**Interview protocol classification guide:**

| Usage pattern | Needs interview_protocol? | Example |
|---------------|--------------------------|---------|
| Multi-round decision tree with traversal order | **Yes** — full protocol with 6 strategy elements | analyze, brainstorm, grill, roadmap, blueprint, init |
| Version/option selection (1-2 questions, no tree) | **Lightweight** — declare decision points only, no traversal rules | milestone-release |
| Simple confirmation (proceed/cancel) | **No** — handled inline in `<execution>` | plan, execute, verify, milestone-audit, milestone-complete |

Section authoring rules are defined in § 2 below.

---

## 2. Section Specifications

### `<purpose>` — Goal and Positioning

State three things: **what it does**, **what it produces**, **where it sits in the pipeline**.

```markdown
<purpose>
Create, revise, or verify an execution plan through a 5-stage pipeline:
Exploration, Clarification, Planning, Plan Checking, and Confirmation.
Produces plan.json with waves, task definitions, and user-confirmed execution strategy.

Supports three modes:
- **Create** (default): Build plan from analysis context
- **Revise** (`--revise`): Incrementally modify existing plan
- **Check** (`--check`): Standalone plan verification

All output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`.
</purpose>
```

**Rules**:
- First paragraph: one-sentence summary + pipeline phase names
- Mode list: one line per mode, include trigger flag
- Output path: describe directory pattern
- Pipeline position: what is upstream, what is downstream (ASCII diagram or one sentence)
- No more than 15 lines

### `<required_reading>` — Startup Dependencies (Conditionally Required)

Include when the command delegates execution to a workflow file. Omit when the command is self-contained with all logic inline in `<execution>`.

Workflow files loaded immediately when the command starts. Use `@` prefix for absolute paths.

```markdown
<required_reading>
@~/.maestro/workflows/plan.md
</required_reading>
```

**Rules**:
- Only list files that must be read before command execution begins
- Keep to 1-3 files
- Use `@~/.maestro/workflows/` prefix for paths
- Omit this section entirely if the command has no external workflow dependency

### `<deferred_reading>` — Lazy Loading (Conditionally Required)

Include when the command loads templates or references on-demand during execution. Omit when no lazy-loaded dependencies exist.

```markdown
<deferred_reading>
- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
- [task.json](~/.maestro/templates/task.json) — read when generating task files
- [state.json](~/.maestro/templates/state.json) — read when registering artifact
</deferred_reading>
```

**Rules**:
- Each entry annotates when it is triggered (`read when ...`)
- Link format: `[display name](path) — trigger condition`
- Omit this section entirely when there is nothing to defer

### `<context>` — Arguments and Environment

Input arguments, flags, and scope routing logic.

```markdown
<context>
$ARGUMENTS — phase number, or no args for milestone-wide, with optional flags.

**Flags:**
| Flag | Effect | Default |
|------|--------|---------|
| `-y` / `--yes` | Auto mode — skip interactive questions | false |
| `--from <source>` | Load upstream context (analyze:ANL-xxx, blueprint:BLP-xxx) | — |
| `--gaps` | Plan from verification gaps | — |

**Scope routing:**
| Input | Scope | Resolution |
|-------|-------|------------|
| numeric arg | phase | Resolve from roadmap |
| `--from analyze:ANL-xxx` | standalone | Direct artifact path |
| no args + roadmap | milestone | Current milestone |

### Pre-load

1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md, FEATURES.md
2. **Specs**: `maestro spec load --category {category}` — load coding/arch/review constraints
3. **Wiki search**: `maestro wiki search "{phase keywords}" --json` → top 5-10 entries as context
4. All optional — proceed without if unavailable (log warning)

### Role Knowledge

1. Browse: `maestro wiki list --category {category}`
2. Select task-relevant entries from index
3. Load: `maestro wiki load <id1> [id2...]`
</context>
```

**Rules**:
- `$ARGUMENTS` on the first line describes positional arguments
- Flags use tables, not prose
- Scope routing uses tables or pseudocode with explicit priority order
- `### Pre-load` subsection: numbered steps, each with condition check + command + degradation handling
- `### Role Knowledge` subsection: standard three steps (browse → select → load)
- Pre-load category selection by command domain:
  | Command domain | spec category | wiki category |
  |----------------|---------------|---------------|
  | Analysis | arch | debug |
  | Planning | arch, coding | arch |
  | Execution | coding, ui (conditional) | coding |
  | Verification | review | review |
  | Brainstorming | arch | arch |

### `<interview_protocol>` — Interactive Decisions (Conditionally Required)

**When required**: Include when the command has **multi-round interactive decision trees** (e.g., scope → depth → dimensions). Omit when the command only uses AskUserQuestion for simple one-shot confirmations (proceed/cancel).

| Usage pattern | Section needed? | Format |
|---------------|-----------------|--------|
| Multi-round decision tree | **Full protocol** — 6 strategy elements | Reference standard + all elements |
| 1-2 option selections, no traversal | **Lightweight** — decision points only | Decision points + scope guard |
| Simple confirmation (yes/no) | **Not needed** — handle inline in `<execution>` | — |

Interview protocol has two layers: **interaction mechanics** (shared across commands) and **decision strategy** (unique per command).

#### Interaction Mechanics (Shared Standard)

The following rules apply to all commands with an interview_protocol. Commands reference this standard directly — no need to rewrite each rule inline:

**Format**: One decision per turn via AskUserQuestion, 2-4 options, first option marked `(Recommended)`. User can terminate or redirect at any time via `Other`.

**Search-first**: Before asking, attempt self-resolution (priority high to low):
1. Project state files: state.json, roadmap.md, project.md
2. Current session artifacts already produced
3. Knowledge base: `maestro spec load` / `maestro wiki search`
4. Codebase: Glob / Grep / Read
5. Open-ended exploration: `Agent(subagent_type: Explore)` / `maestro delegate --role explore`

Principle: **never ask what code or memory can answer**; never bounce your own ambiguity back to the user.

**Writeback cadence**: After each decision settles, **write to disk immediately** (target file specified by the command). Do not batch. Partial decisions must be on disk before the next question.

**Skip conditions**: Skip the entire interview in auto mode (`-y`/`--yes`), resume mode (`-c`/`--continue`), or when input is already unambiguous. Commands may append additional skip conditions.

**Decision table schema**: `| # | Decision | Choice | Source (user / code / default) |`

#### Decision Strategy (Command-Specific)

Each command only needs to declare the following elements in its `<interview_protocol>`:

| Element | Description | Example |
|---------|-------------|---------|
| **Interaction mode** | Convergent menu / adversarial Socratic / hybrid | `convergent menu-driven` |
| **Decision tree** | Decision points and traversal order | `scope → depth → dimensions → threshold` |
| **Traversal rules** | Strict order / allow jumps | `strict: do not open next branch until current settles` |
| **Scope guard** | What to decide, what NOT to prejudge | `only analyze; do not prejudge plan/execute` |
| **Writeback target** | Which file and section to write decisions to | `discussion.md top table + context.md` |
| **Additional search sources** | Data sources beyond the shared list | `issues.jsonl (for --gaps mode)` |
| **Additional skip conditions** | Skip conditions beyond the shared list | `--revise, --review` |
| **Exit condition** | When to end the interview | `all decision points settled` |

**Example usage in a command (convergent menu)**:

```markdown
<interview_protocol>
Follows @~/.maestro/workflows/interview-mechanics.md standard.

**Interaction mode**: convergent menu-driven
**Decision tree** (strict order): scope → depth → dimensions → Go/No-Go threshold
**Scope guard**: only analyze decisions; do not prejudge plan/execute concerns
**Writeback target**: discussion.md (top table) + context.md "Interview Decisions"
**Additional search sources**: issues.jsonl (--gaps mode), roadmap.md
**Additional skip conditions**: input is already specific (explicit phase number or unambiguous topic)
**Exit condition**: all decision points settled → finalize session metadata
</interview_protocol>
```

**Example usage in a command (adversarial mode, grill-specific)**:

```markdown
<interview_protocol>
Follows @~/.maestro/workflows/interview-mechanics.md standard,
but **overrides interaction mode to adversarial Socratic**.

**Interaction mode**: adversarial Socratic — NOT menu-driven
**Question style**:
  - Reference specific code: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
  - Concrete scenarios: "What happens when {action} while {condition}?"
  - Challenge contradictions: immediately surface conflicts with code evidence or prior answers
  - Escalating depth: per branch basic → specific → adversarial
**Branch traversal** (depth-gated): Scope → Data Model → Edge Cases → Integration → Scale → Security → Observability → Migration
**Writeback target**: grill-report.md (Q&A append) + terminology.md (term crystallization)
**Exit condition**: all depth-selected branches fully walked → finalize report + context-package.json
</interview_protocol>
```

### `<execution>` — Execution Logic

Core structure: workflow reference + command-specific extensions.

```markdown
<execution>
### Pre-flight
{Checks before entering the pipeline}

Follow '~/.maestro/workflows/{name}.md' completely.

### {Command-specific extension 1}
{Only write logic not covered by the workflow file}

### {Command-specific extension 2}
{Same}
</execution>
```

**Rules**:
- `Follow 'workflow/X.md' completely` is the core delegation — the workflow file contains phase details
- Only write command-layer logic that the workflow file does not cover
- Extensions use `###` subsections with clear titles
- Do not repeat content already in the workflow file
- Pre-flight checks (e.g., `maestro collab preflight`) go before the workflow reference

**Typical extension types**:

| Type | Description | Example |
|------|-------------|---------|
| Agent constraint | Specific phases must/must not use Agent | P3 planning MUST spawn planner agent |
| Post-task inquiry | Knowledge capture after task completion | "Record as arch constraint?" |
| Issue sync | Bidirectional sync with issues.jsonl | task completion → issue status update |
| Mode routing | Entry points for special modes | `--gaps` → follow alternative workflow |

### `<completion>` — Completion Report

Separate from `<execution>`. Defines the command's output protocol after completion.

```markdown
<completion>
### Standalone report

```
=== {COMMAND_NAME} READY ===
{Key}: {value}
{Key}: {value}

Output:
  {artifact paths}

Next steps:
  /{next-command}     -- {description}
  /{alt-command}      -- {description}
```

### Ralph-invoked completion

Report completion via CLI (do not output text blocks):
```
maestro ralph complete <idx> --status {STATUS} [--evidence {path}] [--concerns "..."]
```

Status verdicts:
- **DONE** — Normal completion
- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
- **BLOCKED** — External hard blocker; pass `--reason`

### Next-step routing

| Condition | Suggestion |
|-----------|-----------|
| {condition_1} | `/{command_1}` |
| {condition_2} | `/{command_2}` |
</completion>
```

**Rules**:
- Standalone reports are wrapped with `=== X READY ===` or `=== X COMPLETE ===`
- Report template must include: artifact paths + next-step suggestions
- Ralph-invoked completion uses CLI calls only, no `--- COMPLETION STATUS ---` text blocks
- Next-step routing uses condition tables, covering all terminal states (success/partial/failure)
- Do not mix completion logic into `<execution>`

### `<error_codes>` — Error Code Table

Enumerate all foreseeable errors and warnings.

```markdown
<error_codes>
| Code | Severity | Condition | Recovery |
|------|----------|-----------|----------|
| E001 | error | No args and no roadmap | Provide phase number or create roadmap |
| E002 | error | Upstream artifact not found | Check artifact ID, verify state.json |
| W001 | warning | Wiki search unavailable | Continue without prior knowledge |
| W002 | warning | Collision detected with existing plan | Review and confirm scope |
</error_codes>
```

**Rules**:
- At least 2 errors + 1 warning
- Every error must have a Recovery (resolution advice)
- Error codes use `E0xx`, warning codes use `W0xx`
- Severity has only two levels: `error` and `warning`
- Cover the following scenarios:
  | Scenario | Example |
  |----------|---------|
  | Missing prerequisite | No roadmap, no plan, no artifacts |
  | Invalid input | Invalid phase number, unknown flag |
  | External dependency failure | CLI tool unavailable, delegate failed |
  | Quality gate failure | Checker found issues, coverage below threshold |
  | Degraded operation | Wiki/spec unavailable, partial context |

### `<success_criteria>` — Acceptance Checklist

Line-by-line verifiable completion standards.

```markdown
<success_criteria>
- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves
- [ ] .task/TASK-*.json files created for each task
- [ ] Every task has `read_first[]` with at least the file being modified
- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions
- [ ] Plan-checker passed (or minor issues acknowledged)
- [ ] User confirmation captured (execute/modify/cancel)
- [ ] Artifact registered in state.json with correct scope/milestone/phase
</success_criteria>
```

**Rules**:
- At least 5 items
- Each item must be **objectively verifiable** — determinable via file existence check, field non-empty check, or command exit code
- No subjective descriptions ("good code quality", "user is satisfied")
- Cover three categories:
  | Category | Verification method | Example |
  |----------|-------------------|---------|
  | Artifact existence | Glob / Read | plan.json, TASK-*.json exist |
  | Artifact quality | Field check | Every task has convergence.criteria[] |
  | State update | state.json check | Artifact registered |

---

## 3. Pre-load Context Pattern

Plan, Execute, and Verify share a similar pre-load pattern. Unified standard below:

### Standard Pre-load Steps

```
1. Codebase docs (structural context):
   IF .workflow/codebase/doc-index.json exists:
     Read ARCHITECTURE.md → module boundaries, integration points
     Read FEATURES.md → component mapping (if relevant)
   ELSE: log "W0xx: Codebase docs unavailable, continuing with code exploration only"

2. Knowledge specs (conventions + constraints):
   Bash("maestro spec load --category {category}")
   Category mapping: analyze→arch, plan→arch, execute→coding, verify→review
   Pass as constraints context to downstream agents

3. Wiki search (prior knowledge):
   keywords = extract 2-5 key terms from phase goal/title
   Bash("maestro wiki search '{keywords}' --json 2>/dev/null")
   IF exit code != 0 OR empty: log "W0xx: Wiki search unavailable"
   ELSE: extract top 5-10 entries as prior knowledge context

4. UI specs (conditional — only when task involves frontend):
   IF task scope contains UI keywords (component, page, style, layout, CSS, frontend):
     Bash("maestro spec load --category ui")
   ELSE: skip
```

### Per-command Tailoring

| Command | Step 1 | Step 2 | Step 3 | Step 4 |
|---------|--------|--------|--------|--------|
| analyze | ARCHITECTURE.md | arch | debug keywords | — |
| plan | ARCHITECTURE.md + FEATURES.md | arch, coding | phase goal | UI conditional |
| execute | ARCHITECTURE.md | coding | phase keywords | UI conditional |
| verify | ARCHITECTURE.md + FEATURES.md | review | "architecture constraint" | — |
| brainstorm | — | arch | topic keywords | — |
| roadmap | — | arch | requirement keywords | — |

Commands reference this standard in `<context> ### Pre-load` and annotate their tailoring — no need to rewrite the full procedure.

---

## 4. Depth Standard

Using `maestro-plan.md` (188 lines) as the depth benchmark. Every pipeline command should meet the following minimum depth:

### Minimum Requirements

**Required sections** (every pipeline command):

| Section | Min lines | Min entries | Must cover |
|---------|-----------|-------------|------------|
| `<purpose>` | 5 | — | Goal + modes + output path |
| `<context>` | 15 | Flags table + scope routing | Arguments, flags, Pre-load, Role Knowledge |
| `<execution>` | 5 | Workflow ref or inline logic + ≥1 extension | Core logic + command-specific extensions |
| `<completion>` | 10 | 2 modes | Standalone report + ralph CLI + next-step routing |
| `<error_codes>` | 4 | ≥2 error + ≥1 warning | Prerequisite + degradation |
| `<success_criteria>` | 5 | ≥5 items | Artifact existence + quality + state update |

**Conditionally required sections** (when trigger condition is met):

| Section | Min lines | Min entries | Must cover |
|---------|-----------|-------------|------------|
| `<required_reading>` | 1 | 1 file | Primary workflow file |
| `<deferred_reading>` | 2 | 1 entry with trigger | Template/reference + "read when ..." |
| `<interview_protocol>` (full) | 8 | 6 strategy elements | Interaction mode + decision tree + scope guard + writeback target + exit condition |
| `<interview_protocol>` (lightweight) | 4 | Decision points list | Decision points + scope guard |

### Signs of Insufficient Depth

| Signal | Problem | Fix |
|--------|---------|-----|
| `<execution>` only has "Follow workflow X" | Missing command-specific constraints | Add Pre-flight / Agent constraints / Post-task |
| No `<error_codes>` | Error scenarios not enumerated | Cover at least missing prerequisites + dependency failures |
| No `<success_criteria>` | Ralph cannot judge completion quality | List grep/file-check verifiable acceptance items |
| No `<completion>` | Completion protocol unclear | Add standalone report + ralph CLI |
| `<context>` has no Pre-load | Missing knowledge context | Follow § 3 standard |

---

## 5. Anti-Patterns

| Anti-Pattern | Correct |
|---|---|
| `<execution>` only says "Follow workflow X" with nothing else | Add at least Pre-flight + command-specific extensions + separate completion |
| interview_protocol copies 50-line boilerplate | Reference this standard, write only 6 strategy elements (or lightweight variant) |
| Adding interview_protocol for simple yes/no confirmations | Only add for multi-round decision trees; simple confirmations go inline in `<execution>` |
| Adding required_reading when command has no external workflow | Only add when command delegates to a workflow file; self-contained commands omit it |
| Pre-load rewritten step-by-step in every command | Reference § 3 standard, annotate tailoring |
| Completion logic mixed into `<execution>` | Separate into `<completion>` section |
| error_codes / success_criteria missing | Every command must have them, even at minimum |
| `<purpose>` is a single sentence | Cover at least goal + modes + output path |
| Command repeats workflow file phase details | Command only writes extensions not in the workflow |
| Scope routing described in prose with implicit priority | Use tables or pseudocode with explicit priority order |
| Interview decision tree buried in prose | List decision points independently, state traversal order |
| success_criteria contains subjective descriptions | Every item must be objectively verifiable |

---

## 6. Pipeline vs FSM Decision Guide

| Choose Pipeline | Choose FSM |
|-----------------|------------|
| Linear phases (N phases executed sequentially) | 10+ states with multi-path branching |
| 1-3 modes, routed at entry then each runs independently | Runtime decisions reshape subsequent path |
| Self-contained, no cross-command handoff | Bidirectional handoff (A ↔ B loop) |
| Artifact written once | Per-step precise PERSIST, 20+ fields with cross-references |
| Simple re-entry (`-c` resume session) | Arbitrary step resumption, steps[] grow/shrink at runtime |

The two styles are complementary: FSM orchestrators invoke pipeline commands; pipeline commands are unaware of orchestrators.

### Current Command Classification

| Style | Commands |
|-------|----------|
| **Pipeline** | init, analyze, plan, execute, verify, brainstorm, grill, blueprint, roadmap, milestone-audit, milestone-complete, milestone-release |
| **FSM** | ralph, ralph-execute, ralph-beta |
| **Needs evaluation** | coordinate (multi-role handoff may need FSM) |

---

## 7. Workflow File Authoring

Workflow files (`workflows/*.md`) are the **implementation** behind pipeline commands. A command file says `Follow 'workflow/X.md' completely` — the workflow file contains the actual phase-by-phase procedure, pseudocode, agent prompts, and internal logic.

### Content Boundary: Command vs Workflow

| Content | Owned by | Rationale |
|---------|----------|-----------|
| Error code registry (`<error_codes>`) | **Command** | Command is the contract surface |
| Success criteria checklist | **Command** | Completion validation owned by caller |
| Completion report format | **Command** | `<completion>` section owns output protocol |
| Interview decision strategy | **Command** | `<interview_protocol>` owns the decision tree |
| Pre-load context pattern | **Command** | `<context> ### Pre-load` references § 3 |
| Phase-by-phase procedures | **Workflow** | Detailed execution steps with pseudocode |
| Agent spawn prompts | **Workflow** | Full prompt templates for sub-agents |
| Scope resolution logic | **Workflow** | Pseudocode priority cascade |
| Behavioral guards (Iron Law, Red Flags) | **Workflow** | Runtime constraints for agents |
| Output schemas (JSON) | **Workflow** | jsonc blocks for artifact formats |
| Internal quality gates | **Workflow** | Execution-time checks beyond success_criteria |
| State field writes | **Workflow** | Detailed index.json/state.json updates |
| Flag definitions | **Both** | Command = table; Workflow = implementation |
| Next-step routing | **Both** | Command = condition table; Workflow = implementation |
| Pipeline position diagram | **Both** | Command = brief in `<purpose>`; Workflow = full ASCII diagram |

**Principle**: The command file is the **contract** (what, when, error codes, success criteria); the workflow file is the **implementation** (how, step-by-step, pseudocode, agent prompts).

### File Structure

```
# Workflow: {Name}
{1-3 line summary: purpose + output + key constraint}

---

## Behavioral Guards              ← Iron Law, Red Flags, Forbidden Wording (if applicable)
## Prerequisites                  ← Required upstream artifacts (if applicable)
## Architecture                   ← ASCII pipeline diagram (if multi-mode)
## Parameters                     ← Flags/arguments table
## Scope Resolution               ← Input routing pseudocode
## Output Artifacts               ← Directory tree / file list (if 3+ output files)

---

## {Phase 1}: {Title}             ← Core pipeline phases (sequential)
## {Phase 2}: {Title}
## ...
## {Phase N}: {Title}

---

## Mode: {Name} ({--flag})        ← Alternate modes as trailing sections (if applicable)
## ...

---

## Quality Gates                  ← Internal quality checks (if applicable)
## Error Handling                 ← Error table OR reference to command file
## State Updates                  ← State field writes (if applicable)
```

### Section Rules

#### H1 Title + Opening Summary

```markdown
# Workflow: {Name}

5-phase pipeline: Context Collection → Clarification → Planning → Plan Checking → Confirmation.
Produces plan.json + .task/TASK-{NNN}.json in .workflow/scratch/{YYYYMMDD}-plan-{slug}/.
```

- H1 format: `# Workflow: {Name}` (standardized across all workflow files)
- Opening summary: exactly 1-3 lines — purpose, output, key constraint
- `---` horizontal rule after summary, and between every H2 section

#### Behavioral Guards (conditionally required)

For high-stakes workflows (execute, verify) that need anti-hallucination or anti-shortcut enforcement:

```markdown
## Iron Law
Never mark a task as complete unless the convergence criteria are met.

## Red Flags
- Empty catch blocks, @ts-ignore, `as any` → stop, fix the root cause
- Test file has 0 assertions → invalid, rewrite
- "Aligned X with Y" without concrete change → reject
```

Required when: workflow agents can hallucinate success, skip verification, or hide errors.

#### Prerequisites

```markdown
## Prerequisites
- None for standalone operation (state.json auto-bootstraps)
- For milestone/phase scope: init + roadmap required
```

Required when: workflow depends on upstream artifacts or commands.

#### Parameters

Always use table format. Title: `## Parameters` (not "Flag Processing", "Arguments", or "Input").

```markdown
## Parameters

| Flag | Effect | Default |
|------|--------|---------|
| `--collab` | Use collaborative multi-planner mode in P3 | false |
| `--gaps` | Plan from verification gaps, skip P1 exploration | false |
| `--tdd` | Generate RED-GREEN-REFACTOR triplet tasks | false |
```

#### Scope Resolution

Always use pseudocode in fenced code blocks with explicit priority numbering:

```markdown
## Scope Resolution

```
Resolution priority (highest to lowest):
  1. --from analyze:ANL-xxx → CONTEXT_DIR = artifact path, scope = "standalone"
  2. --dir <path> → CONTEXT_DIR = path, scope from state.json
  3. numeric arg → scope = "phase", resolve from roadmap
  4. no args + roadmap → scope = "milestone"
  5. no args + no roadmap → ERROR E001
```
```

Never use prose paragraphs for scope resolution — pseudocode makes priority order unambiguous.

#### Output Artifacts (conditionally required)

When the workflow produces 3+ output files, document the directory structure:

```markdown
## Output Artifacts

```
.workflow/scratch/{YYYYMMDD}-plan-P{N}-{slug}/
  plan.json                    ← Plan overview with task_ids[], waves[]
  .task/
    TASK-001.json              ← Individual task definition
    TASK-002.json
  .process/
    exploration-arch.json      ← Agent exploration results
    context-package.json       ← Aggregated context
```
```

#### Phase Sections (core content)

**Phase naming convention**:

| Pattern | When to use | Example |
|---------|-------------|---------|
| `{Letter}{N}: {Title}` | Core pipeline trio (plan/execute/verify) — they cross-reference each other | `P1: Context Collection`, `E2: Wave Parallel Execution`, `V1: Goal-Backward Verification` |
| `Step {N}: {Title}` | All other workflows | `Step 1: Parse & Route`, `Step 4: Branch Walking` |
| Fractional numbering | Interstitial phases in any workflow | `P4.5: Collision Detection`, `Step 2.5: Terminology Alignment` |

**Phase internal structure**:
- Use numbered steps within each phase
- Sub-steps use decimal notation: `4.1`, `4.2`, `5b`
- Pseudocode in fenced code blocks for conditional logic and loops
- Agent spawn blocks use `Agent()` pseudocode with full prompt templates
- Data mappings use tables, not prose

#### Alternate Modes (conditionally required)

When a workflow supports `--revise`, `--review`, `--check`, or similar alternate modes:

```markdown
## Mode: Revise (--revise)

### Plan Discovery
Resolve which existing plan to revise via --dir or latest artifact lookup.

### Execution Flow
1. Load existing plan.json
2. Obtain revision instructions (user or --revise arg)
3. Spawn planner agent with existing plan + instructions
4. Re-run P4 checker
5. Update artifact in state.json
```

- Place alternate modes as trailing H2 sections **after** the main pipeline phases
- Heading format: `## Mode: {Name} ({--flag})`
- Do not embed alternate mode logic inline within main pipeline phases

#### Error Handling

```markdown
## Error Handling

| Error | Condition | Recovery |
|-------|-----------|----------|
| E001 | No roadmap and no --dir | Provide phase number or create roadmap |
| E004 | Planner agent returned empty plan | Retry with expanded context |
| Runtime | Agent timeout | Retry once, then mark task failed |
```

- Use table format matching the command file's `<error_codes>` schema
- At minimum, reference the command file's error codes
- Add workflow-specific runtime errors not covered by the command

#### Quality Gates (conditionally required)

Workflow-internal quality checks that run during execution (distinct from command's `<success_criteria>` which validates after completion):

```markdown
## Quality Gates

- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions
- [ ] No task `action` contains vague language ("align", "ensure", "improve")
- [ ] Plan confidence score ≥ 70 before proceeding to confirmation
```

Use "Quality Gates" naming to avoid confusion with command's "success_criteria".

#### State Updates (conditionally required)

When the workflow writes to index.json or state.json:

```markdown
## State Updates

| When | Field | Value |
|------|-------|-------|
| P5 completion | state.json.artifacts[] | New PLN artifact entry |
| P5 completion | index.json.status | "confirmed" |
| Collision detected | index.json.collisions[] | Colliding file paths |
```

### Formatting Rules

| Element | Format | Example |
|---------|--------|---------|
| Section separators | `---` between every H2 section | Universal |
| Flags/parameters | Table with Flag / Effect / Default columns | `## Parameters` |
| Scope resolution | Pseudocode in fenced code block | Numbered priority cascade |
| Agent spawn prompts | `Agent()` pseudocode with structured prompt | Full template inline |
| Output schemas | `jsonc` code blocks with annotation comments | verification.json, context-package.json |
| Report templates | Plain code blocks with `{placeholder}` variables | Completion report format |
| Anti-patterns / traps | Bullet list | Red Flags section |
| Next-step routing | Condition → suggestion table | Post-pipeline routing |

### Depth Calibration

Workflow depth correlates with interactivity, multi-agent orchestration, and mode count:

| Workflow type | Expected lines | Characteristics |
|---------------|---------------|-----------------|
| Interactive (discussion loops, feedback rounds) | 400-800 | analyze, brainstorm, grill |
| Multi-agent (parallel spawning, cross-agent synthesis) | 400-700 | execute, brainstorm |
| Multi-mode (3+ execution paths) | 400-600 | plan (create/revise/check/tdd) |
| Standard (single linear pipeline) | 200-400 | blueprint, roadmap |
| Procedural/operational (archive, audit, release) | 100-200 | milestone-audit, milestone-complete |

A workflow under 100 lines likely belongs inline in the command file rather than as a separate file.

### Shared Logic Extraction

When 2+ workflow files share procedural logic, extract to a `{name}-common.md` companion:

```
roadmap.md         → imports shared logic from roadmap-common.md
roadmap-common.md  → shared scope routing, milestone resolution, state updates
```

- Primary workflow delegates with `Follow '{name}-common.md' § {Section}` pattern
- Common file uses the same H2 section structure as regular workflows
- Only extract when duplication is ≥30 lines across 2+ files

### Workflow Anti-Patterns

| Anti-Pattern | Correct |
|---|---|
| Duplicating command's error_codes or success_criteria | Workflow adds runtime errors only; command owns the registry |
| Embedding completion report format | Completion format belongs in command's `<completion>` |
| Defining interview decision strategy | Decision tree belongs in command's `<interview_protocol>` |
| Omitting Parameters / Scope Resolution sections | Always include — readers should not need the command file for basic routing |
| Prose paragraphs for scope resolution | Use pseudocode with numbered priority levels |
| Inline alternate modes within main pipeline phases | Place as trailing `## Mode: {Name}` sections |
| "Quality Criteria" naming | Use "Quality Gates" to avoid collision with command's success_criteria |
| No `---` separators between H2 sections | Always separate for visual parsing |
| H1 title inconsistency ("X Workflow" vs "Workflow: X") | Standardize on `# Workflow: {Name}` |
| Workflow under 100 lines as separate file | Inline into the command file instead |
