# Command Pattern Documentation

**Purpose:** Guide for developers creating task-constrained commands

**Status:** Pattern Reference (November 22, 2025)

---

## Pattern: Task-Bounded Command Structure

All commands must enforce task constraints. Use this pattern:

### Pattern 1: Implementation Command

(For commands that create/modify code)

```markdown
---
description: Brief description of what this does
agent: build # or oracle/code-auditor depending on complexity
---

# Command Name: $ARGUMENTS

## MANDATORY GATE: Task Must Exist

Check that `@backlog/tasks/$ARGUMENTS/` contains:

- [ ] prd.md with Goal, Scope, and Success Criteria sections
- [ ] spec.md with Architecture, Constraints, and Edge Cases sections

**If ANY missing:** STOP. Create task with `/task-with-spec "$ARGUMENTS"` first.

## Step 1: Load Task Context

Read both files and extract:

- **From PRD:** Goal, In-Scope, Out-of-Scope, Success Criteria
- **From Spec:** Architecture, Constraints, Edge Cases, Testing approach

**Purpose:** Every decision must align with task boundaries.

## Step 2: [Your action 1]

Describe what the agent should do. Include:

- What constraints apply? (from spec)
- What success criteria must be met? (from PRD)
- What edge cases must be handled? (from spec)
- What boundaries NOT to cross? (from PRD Out-of-Scope)

## Step 3: [Your action 2]

Continue with specific steps...

## Step N: Complete Review.md

After work done, fill `@backlog/tasks/$ARGUMENTS/review.md`:

- **What Changed:** Specific files/functions modified
- **What Skipped:** Intentional limitations
- **Inconsistencies:** Any spec deviations and why
- **Validation:** Which success criteria complete

**ABORT:** If review.md incomplete, task cannot be marked done.

---

**ANTI-HALLUCINATION: Work must stay within task boundaries at every step**
```

**Key Principles:**

1. **Gates first** - Check task exists before ANY work
2. **Load constraints** - Extract PRD+spec requirements upfront
3. **Step-by-step** - Each action validates against constraints
4. **Review enforcement** - Task cannot complete without review.md
5. **Clear boundaries** - State what NOT to do explicitly

---

### Pattern 2: Planning/Analysis Command

(For commands that create plans or analyze scope)

```markdown
---
description: Brief description
agent: plan # or oracle for complex analysis
---

# Command Name: $ARGUMENTS

## MANDATORY GATE: Task Must Exist

Check for `@backlog/tasks/$ARGUMENTS/` with prd.md and spec.md.

**If missing:** STOP. Create task first with `/task-with-spec`.

## Step 1: Extract Task Requirements

Read PRD:

- Goal (1-2 sentences, measurable)
- Scope (In-Scope/Out-of-Scope lists)
- Success Criteria (checkboxes)

Read Spec:

- Architecture (proposed approach)
- Constraints (rules to follow)
- Edge Cases (corner cases)
- Testing (how to verify)

## Step 2: Create Plan/Analysis

[Your planning logic here]

## Step 3: Validate Against Constraints

Before presenting results, verify:

- [ ] Stays within PRD scope
- [ ] Follows ALL spec constraints
- [ ] Handles ALL spec edge cases
- [ ] Achieves all success criteria

**If ANY check fails:** Revise.

## Step 4: Present Results

Show analysis/plan with:

- What it achieves (PRD goal)
- How it respects constraints (spec rules)
- What edge cases it handles
- What's still unknown/unsolved

---

**ANTI-HALLUCINATION: Plans must serve task constraints - no exploring alternatives**
```

**Key Principles:**

1. **Scope-first** - Extract task boundaries before analyzing
2. **Constraint validation** - Every recommendation must respect constraints
3. **Edge case handling** - Show how each edge case is addressed
4. **Presentation** - Link every decision back to task requirements
5. **No alternatives** - Don't explore solutions outside scope

---

### Pattern 3: Validation/Completion Command

(For commands that verify work is done)

```markdown
---
description: Validate something is complete
agent: build
---

# Command Name: $ARGUMENTS

## MANDATORY VALIDATION GATES

### Gate 1: [Check thing 1]

- [ ] Condition A exists
- [ ] Condition B is true

**If ANY fails:** STOP with clear error.

### Gate 2: [Check thing 2]

- [ ] Condition C exists
- [ ] Condition D is true

**If ANY fails:** STOP with clear error.

### Gate N: [Final validation]

- [ ] Everything documented
- [ ] All success criteria met

**If ANY fails:** STOP and list what's missing.

## Validation Passed

**ONLY if ALL gates pass:**

1. Take action A
2. Take action B
3. Display success summary

---

**ANTI-HALLUCINATION: Validation must pass ALL gates before proceeding - no shortcuts**
```

**Key Principles:**

1. **All-or-nothing** - Every gate must pass, no partial credit
2. **Early exit** - Stop at first failure and explain why
3. **Clear checklists** - What to check is explicit
4. **Helpful errors** - Tell user exactly what's missing

---

## Anti-Hallucination Rules for Commands

### Rule 1: Gates Before Work

Every command modifying code MUST have gates checking:

- [ ] Task directory exists (`@backlog/tasks/$TASK_ID/`)
- [ ] prd.md exists and has Goal, Scope, Success Criteria
- [ ] spec.md exists and has Architecture, Constraints, Edge Cases

**Violate this:** Agent aborts before any modification.

### Rule 2: Scope Enforcement

During work, validate each action:

- **Is this within PRD In-Scope?** (if no → STOP)
- **Does this follow spec Constraints?** (if no → STOP)
- **Does this handle a spec Edge Case?** (if applicable)
- **Does this help achieve PRD Success Criteria?** (if no → reconsider)

**Violate this:** Incomplete or off-scope work.

### Rule 3: Review.md Requirement

After work, MUST complete:

- **What Changed** (specific files/functions)
- **What Skipped** (intentional limitations)
- **Inconsistencies** (spec deviations and why)
- **Validation** (which success criteria complete)

**Violate this:** Task cannot be marked done.

### Rule 4: No Shell Script Validation

❌ **WRONG:**

```markdown
!`if [ ! -f "$TASK_DIR/prd.md" ]; then echo "ERROR"; exit 1; fi`
```

✅ **RIGHT:**

```markdown
Check that `@backlog/tasks/$TASK_ID/` contains:

- [ ] prd.md (file to verify)
- [ ] spec.md (file to verify)

**If ANY missing:** STOP. Create task with `/task-with-spec` first.
```

**Why:** Agents read and execute decision logic, not shell scripts.

### Rule 5: Clear Boundaries

Always state what NOT to do:

```markdown
## What NOT to Do

❌ Modify files outside PRD scope
❌ Use libraries forbidden by spec
❌ Skip edge cases listed in spec
❌ Work beyond Out-of-Scope boundaries
```

### Rule 6: Link to Task Context

Every step should reference task files:

```markdown
**From PRD:** [What part of PRD this follows]
**From Spec:** [What constraint/architecture this implements]
**Edge Cases:** [Which spec edge cases this handles]
```

---

## Command Categories

### Category A: Implementation Commands

(Modify code within task constraints)

- `/research-and-implement` → Research + implement
- `/quick-build` → Single-file changes only
- `/plan-and-build` → Plan approval + implement

**Pattern to use:** Implementation Command (Pattern 1)

**Key requirement:** Complete review.md after work

### Category B: Research/Analysis Commands

(Gather information within task scope)

- `/research` → Research within boundaries
- `/plan` → Create execution plan
- `/task-with-spec` → Create task structure

**Pattern to use:** Planning/Analysis Command (Pattern 2)

**Key requirement:** Validate all findings against scope

### Category C: Validation/Completion Commands

(Verify work meets standards)

- `/complete-task` → Mark task done
- `/commit` → Create commits with validation
- `/status` → Show task compliance

**Pattern to use:** Validation/Completion Command (Pattern 3)

**Key requirement:** All gates must pass

### Category D: Support Commands

(Enable work without implementing)

- `/handoff` → Create task context for next agent
- `/context` → Show relevant codebase context

**Pattern to use:** Planning/Analysis Command (Pattern 2)

**Key requirement:** Keep output focused on task

---

## Testing Your Command

Before merging a new command:

1. **Read Pattern** - Does it follow one of the 3 patterns?
2. **Check Gates** - Does it validate task existence first?
3. **Verify Boundaries** - Does it extract and enforce constraints?
4. **Test Failure** - What happens if task is missing files?
5. **Check Docs** - Does it clearly state what NOT to do?

---

## Common Mistakes to Avoid

### ❌ Mistake 1: Template syntax as enforcement

Wrong: `!`if [ ! -f file ]; then exit 1; fi``
Right: Checkboxes + "STOP" instruction

### ❌ Mistake 2: Working without reading task files

Wrong: "Implement X based on $ARGUMENTS"
Right: "Read task PRD+spec first, then implement within boundaries"

### ❌ Mistake 3: No review.md requirement

Wrong: "Complete implementation"
Right: "Complete review.md with what changed, skipped, inconsistencies"

### ❌ Mistake 4: No scope validation

Wrong: "Search codebase for relevant patterns"
Right: "Search for patterns matching task goal WITHIN spec constraints"

### ❌ Mistake 5: Vague error conditions

Wrong: "Task validation failed"
Right: "Task validation failed: prd.md exists but spec.md missing"

---

## Examples of Properly Structured Commands

### Example 1: Implementation Command

See: `.opencode/command/research-and-implement.md`

- Has task validation gates ✅
- Extracts constraints upfront ✅
- References PRD+spec in each step ✅
- Requires review.md completion ✅

### Example 2: Planning Command

See: `.opencode/command/plan.md`

- Has task validation gates ✅
- Validates plan against constraints ✅
- Explicit approval gate before proceeding ✅
- Shows constraint compliance ✅

### Example 3: Completion Command

See: `.opencode/command/complete-task.md`

- 6 sequential validation gates ✅
- All-or-nothing enforcement ✅
- Clear error messages ✅
- Shows what's missing ✅

---

## Updating This Documentation

When adding new commands:

1. Add command file to `.opencode/command/`
2. Follow one of the 3 patterns above
3. Include anti-hallucination gates
4. Link to task constraints (PRD+spec)
5. Require review.md for implementation commands
6. Update `COMMAND_PATTERNS.md` with category

**Last reviewed:** November 22, 2025
