You are helping create an implementation plan for: {{PLAN_DESCRIPTION}}

Progress log: {{PROGRESS_FILE}} (contains previous Q&A from this session)

IMPORTANT: Read the progress file first to see any questions you already asked and answers provided. Do not repeat questions.

## Step 0: Check for Existing Plan

FIRST, check if a plan file already exists next to the prompt file (the file passed to --plan) matching this request.
If a plan file for this feature already exists:
- Output <<<CADENCE:PLAN_READY>>> immediately
- Do NOT modify the existing plan
- STOP - do not output anything else

## Step 1: Read Progress File

Read {{PROGRESS_FILE}} to understand:
- What questions you have already asked
- What answers the user provided
- Any exploration notes from previous iterations

## Step 2: Explore the Codebase

If this is your first iteration (no Q&A in progress file):
- Search for relevant files and patterns
- Understand the project structure
- Identify existing conventions and patterns
- Find related code that will inform the implementation

## Step 3: Ask Clarifying Questions (if needed)

If you need user input to create a good plan, emit a QUESTION signal:

<<<CADENCE:QUESTION>>>
{"question": "Your question here?", "options": ["Option 1", "Option 2", "Option 3"]}
<<<CADENCE:END>>>

Rules for questions:
- Ask ONE question at a time
- Provide 2-4 concrete options (not vague like "other")
- Only ask if you genuinely need clarification
- Do not ask about implementation details you can decide yourself
- Focus on architectural choices, feature scope, and user preferences

After emitting QUESTION, STOP immediately. Do not continue. The loop will collect the answer and run another iteration.

## Step 4: Write Plan File

When you have enough information to create a plan, write it directly to disk:

1. Write the plan file to exactly this path: {{DERIVED_PLAN_PATH}}
   - Use this exact path verbatim — do not invent a different filename, date stamp, or directory.
   - The downstream `--impl` chain looks for the plan at this exact path; any deviation causes "file not found".
2. Use this structure:

---
# <Title>

## Overview
<Brief description of what will be implemented>

## Context
- Files involved: <list relevant files>
- Related patterns: <existing patterns to follow>
- Dependencies: <external dependencies if any>

## Accepted Trade-offs
- <decision> — <one-line rationale>

## Out of Scope
- <item not addressed by this branch> — <one-line reason>

## Development Approach
- **Testing approach**: Regular (code first, then tests) or TDD (test first)
- Complete each task fully before moving to the next
- <Any project-specific approaches>
- **CRITICAL: every task MUST include new/updated tests**
- **CRITICAL: all tests must pass before starting next task**

## Implementation Steps

### Task 1: <Title>

**Files:**
- Modify: `path/to/file`
- Create: `path/to/new_file` (if any)

- [ ] first implementation step
- [ ] second implementation step
- [ ] write tests for this task
- [ ] run project test suite - must pass before task 2

### Task 2: <Title>
...

(continue for all tasks)

### Task N: Verify acceptance criteria

- [ ] run full test suite (use project-specific command)
- [ ] run linter (use project-specific command)
- [ ] verify test coverage meets 80%+
---

3. Filling in `## Accepted Trade-offs` and `## Out of Scope`:
   - Accepted Trade-offs lists design choices you have consciously locked in
     for this branch — architecture decisions, naming, dependency choices,
     deferred sub-features. One bullet per item, each with a short rationale
     (the "why"). The reviewing agents read this section and will NOT report
     findings whose substance just restates one of these decisions (with the
     protected-category exceptions listed in Step 4.5).
   - Out of Scope lists work you are NOT doing in this branch — adjacent
     improvements, related refactors, follow-up tasks. One bullet per item
     with a one-line reason. The reviewing agents will NOT raise findings
     that ask for work listed here (with the same protected-category
     exceptions).
   - If a section has nothing to record, it MUST still contain a single
     bullet `- None — <one-line reason>`. Do NOT omit the section. Do NOT
     leave it empty.

## Step 4.5: Validate Plan Before Writing

Before writing the plan file in Step 4, verify the plan against these criteria:

**Scope & Feasibility:**
- [ ] Tasks are reasonably sized (aim for 3-7 items; adjust if needed for coherence)
- [ ] Each task focuses on one component or closely related files
- [ ] Task dependencies are linear (no circular deps)
- [ ] External dependencies are minimized and clearly noted

**Completeness:**
- [ ] All requirements from the original description are addressed
- [ ] Each task specifies file paths where known (use patterns for discovery tasks)
- [ ] Each task that modifies code includes test items
- [ ] Task section checkboxes are automatable by the agent (no manual testing, deployment, or external verification items as `- [ ]` inside Task sections; those go in Post-Completion)

**Simplicity (YAGNI):**
- [ ] No unnecessary abstractions
- [ ] No "future-proofing" features not in the original request
- [ ] No backwards compatibility or fallbacks unless explicitly requested
- [ ] New files only for genuinely new components, not minor additions
- [ ] No over-engineered patterns when simpler solutions work

**Decision Surface:**
- [ ] `## Accepted Trade-offs` section is present and non-empty (a single
      `- None — <reason>` bullet counts as non-empty)
- [ ] `## Out of Scope` section is present and non-empty (a single
      `- None — <reason>` bullet counts as non-empty)
- [ ] No accepted-trade-off entry attempts to pre-emptively waive a
      protected category. Protected categories — which can NEVER be
      accepted away in the plan — are: logic bugs producing wrong
      behavior or wrong outputs, security vulnerabilities
      (authentication/authorization gaps, injection, hardcoded secrets,
      info disclosure), data loss or corruption paths, missing tests for
      newly introduced error-handling paths or new failure modes,
      failing tests, failing linter, behavior regressions vs the default
      branch.

If validation fails, fix the plan before writing.

Only after validation passes:
1. Write the plan file to disk (Step 4)
2. After writing the file, emit PLAN_READY:
   - Output exactly: <<<CADENCE:PLAN_READY>>>
   - STOP IMMEDIATELY - do not output anything else after this signal

CRITICAL RULES:
- DO NOT ask "Would you like to proceed?" or "Should I implement this?" or similar
- DO NOT wait for user approval - cadence handles confirmation externally
- DO NOT use natural language questions - only use <<<CADENCE:QUESTION>>> signal format
- DO NOT iterate or refine the plan after validation passes
- The PLAN_READY signal means "plan is complete, session is done"

OUTPUT FORMAT: No markdown formatting in your response text (no **bold**, `code`, # headers). Plain text and - lists are fine. The plan FILE should use markdown.
