automaton/tasks/phase-scoped-prompts/SPEC.md

# SPEC: Phase-Scoped Prompts with Forbidden Actions

## Goal
Restructure all phase prompts to include explicit ALLOWED and FORBIDDEN action sections, ensuring agents cannot skip phases or perform actions outside their current phase scope.

## Background
Currently, phase prompts describe what to produce (SPEC.md, DESIGN.md, etc.) but never state what's NOT allowed. When a user says "fix this bug," the agent has no instruction refusing to skip phases. The prompts are also monolithic — the orchestrator prompt is 493 lines, diluting compliance. Each phase prompt needs hard boundaries.

## Requirements

### 1. ALLOWED/FORBIDDEN sections in every phase prompt
Every phase prompt must include two explicit sections:

```markdown
## ALLOWED ACTIONS
- {action 1}
- {action 2}

## FORBIDDEN ACTIONS
- Do NOT {forbidden action 1}
- Do NOT {forbidden action 2}
- If the user requests {forbidden action}, respond: "That requires going through the {phase} phase first. The current phase is {current phase}."
```

### 2. Per-phase ALLOWED and FORBIDDEN definitions

#### research.md
- ALLOWED: Read project files, ask clarifying questions, write SPEC.md
- FORBIDDEN: Edit code, create IMPLEMENTATION.md, create DESIGN.md, create any artifact other than SPEC.md, skip to implementation regardless of user request
- APPROVAL REQUIRED: SPEC.md must be approved before transitioning to the next phase. The research phase has sub-states:
  - `research`: Active — agent is working on SPEC.md
  - `research:awaiting_approval`: SPEC.md draft is produced, waiting for user sign-off
  - `research:approved`: User has approved SPEC.md, ready to transition to next phase

#### decompose.md
- ALLOWED: Read SPEC.md, ask decomposition questions, write DECOMPOSITION.md, run VRAM detection
- FORBIDDEN: Edit code, create IMPLEMENTATION.md, modify SPEC.md, create sub-task folders (the Orchestrator does this)
- APPROVAL REQUIRED: DECOMPOSITION.md must be approved before sub-tasks are created. Sub-states:
  - `decomposition`: Active — agent is working on DECOMPOSITION.md
  - `decomposition:awaiting_approval`: DECOMPOSITION.md draft is produced, waiting for user sign-off
  - `decomposition:approved`: User has approved DECOMPOSITION.md, ready to create sub-tasks

#### design.md
- ALLOWED: Read SPEC.md, ask design questions, write DESIGN.md
- FORBIDDEN: Edit code, create IMPLEMENTATION.md, modify SPEC.md, skip to implementation regardless of user request
- APPROVAL REQUIRED: DESIGN.md must be approved before transitioning. Sub-states:
  - `design`: Active — agent is working on DESIGN.md
  - `design:awaiting_approval`: DESIGN.md draft is produced, waiting for user sign-off
  - `design:approved`: User has approved DESIGN.md, ready to transition

#### test_design.md
- ALLOWED: Read SPEC.md and DESIGN.md, ask test questions, write TEST_PLAN.md
- FORBIDDEN: Edit code, write test implementations, create IMPLEMENTATION.md, modify SPEC.md or DESIGN.md
- APPROVAL REQUIRED: TEST_PLAN.md must be approved before transitioning. Sub-states:
  - `test_design`: Active — agent is working on TEST_PLAN.md
  - `test_design:awaiting_approval`: TEST_PLAN.md draft is produced, waiting for user sign-off
  - `test_design:approved`: User has approved TEST_PLAN.md, ready to transition

#### implement.md (already exists, needs FORBIDDEN additions)
- ALLOWED: Edit code, write tests, create IMPLEMENTATION.md, run test suite
- FORBIDDEN: Create new tasks, modify SPEC.md or DESIGN.md, transition to bug-find phase (the Orchestrator does this)
- NO APPROVAL: implement phase has no approval sub-states — it transitions directly to bug_find when IMPLEMENTATION.md is complete and CONTRACT_MET is output

#### bug_finder.md
- ALLOWED: Read code, read SPEC.md, read IMPLEMENTATION.md, write BUG_REPORT.md
- FORBIDDEN: Edit code, fix bugs (that's a separate implementation task), modify SPEC.md

#### adversarial_bug_find.md
- ALLOWED: Read code, read SPEC.md, read BUG_REPORT.md, write ADVERSARIAL_BUG_REPORT.md
- FORBIDDEN: Edit code, fix bugs, modify SPEC.md or BUG_REPORT.md

#### doc_review.md
- ALLOWED: Read DESIGN.md, read code, read docs, write DOC_REVIEW.md, update documentation
- FORBIDDEN: Edit non-documentation code, modify SPEC.md, modify DESIGN.md

#### referee.md
- ALLOWED: Read all artifacts, write VERDICT.md
- FORBIDDEN: Edit code, modify any artifact other than VERDICT.md

#### orchestrate.md
- ALLOWED: Read `.state`, transition `.state`, create task folders (via `status.py --create-task`), delegate to phase prompts, call `status.py --approve` on behalf of the user in manual mode
- FORBIDDEN: Edit code directly, produce phase artifacts (SPEC.md, DESIGN.md, etc.), skip phases, create task folders manually (must use `status.py --create-task`)

### 3. User override resistance
Each FORBIDDEN section must include a standard response template for when the user tries to bypass the workflow:

```markdown
## Handling User Overrides
If the user requests an action that is FORBIDDEN in the current phase:
1. Do NOT perform the forbidden action
2. Respond with: "That action requires the {required_phase} phase. The current phase is {current_phase}. To proceed, say 'orchestrate' and I will advance to the next phase."
3. If the user insists, you may note their request but still do not perform the forbidden action
```

### 4. `.state` precondition check
Each phase prompt must include in its "Read These Files" section:
```markdown
1. {project}/.automaton/tasks/{task-name}/.state — Confirm the task is in the correct phase. If the phase does not match this prompt, STOP and report the mismatch.
```

### 5. Approval gate check
For phases that require approval (research, decomposition, design, test_design), the prompt must include:

```markdown
## Approval Gate (MANDATORY)
This phase requires user approval before proceeding to the next phase.

1. After producing the draft artifact ({artifact_name}), transition to awaiting_approval:
   python ~/.automaton/scripts/status.py --task {task-name} --transition {phase}:awaiting_approval

2. Present the draft to the user for review and sign-off.

3. After the user says "APPROVED" or equivalent:
   python ~/.automaton/scripts/status.py --task {task-name} --approve

4. Then transition to the next phase:
   python ~/.automaton/scripts/status.py --task {task-name} --transition {next-phase}

You MUST NOT transition past {phase}:awaiting_approval without explicit user approval.
status.py --transition will REFUSE the transition if approval has not been granted.
```

### 5. Folder validation check
Each phase prompt must include a mandatory validation step before beginning work:
```markdown
## Pre-Work Validation (MANDATORY)
Before starting any work, you MUST run:
  python ~/.automaton/scripts/status.py --validate-folder --task {task-name}

If this reports FORBIDDEN artifacts, STOP. Do not proceed. Report the violation and ask the user to resolve it.
```

This catches phase-skipping violations before the agent begins work in a phase, preventing the agent from building on top of artifacts that shouldn't exist.

### 5. Prompt length discipline
- Each phase prompt should be **under 150 lines** (except orchestrate.md which may be longer due to the state machine definition)
- Remove redundant content — if the state machine is defined in `workflow.md`, don't repeat it in `orchestrate.md`
- The orchestrator prompt should reference `workflow.md` for state transitions rather than duplicating them

### 6. Orchestrate.md restructuring
- Remove the detailed state determination logic from orchestrate.md (it lives in workflow.md, which is already separate)
- Remove the sub-task management details (move to a new `prompts/subtask_management.md` reference document)
- Keep orchestrate.md focused on: reading `.state`, determining next action, writing `.state` transitions, and delegating to phase prompts
- Target: reduce orchestrate.md from 493 lines to under 200 lines

## Acceptance Criteria
- [ ] Every phase prompt has explicit ALLOWED ACTIONS section
- [ ] Every phase prompt has explicit FORBIDDEN ACTIONS section
- [ ] Every phase prompt includes user override resistance instructions
- [ ] Every phase prompt includes `.state` precondition check
- [ ] Every phase prompt includes mandatory `--validate-folder` check before work
- [ ] Research, decomposition, design, and test_design prompts include approval gate check
- [ ] Approval gate check references `--transition {phase}:awaiting_approval`, `--approve`, and `--transition {next-phase}`
- [ ] Implementation, bug finder, adversarial bug finder, doc review, and referee prompts do NOT include approval gates
- [ ] orchestrate.md FORBIDDEN section includes "create task folders manually (must use status.py --create-task)"
- [ ] orchestrate.md is under 200 lines
- [ ] State transition logic is not duplicated between orchestrate.md and workflow.md
- [ ] Sub-task management is extracted to its own reference document
- [ ] No prompt exceeds 150 lines (except orchestrate.md which may be up to 200)

## Non-Goals
- This spec does not cover the `.state` file implementation (separate task)
- This spec does not cover the `status.py` script (separate task)
- This spec does not cover autopilot integration (separate task)