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:

## 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:

## 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:

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:

## 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:

## 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)