clockwork-plan

name	clockwork-plan
description	Use when creating implementation plans for ralphex orchestration. Produces plans with Task headers, Validation Commands, and checkbox items suitable for automated agent execution.

Clockwork Plan Creation

Overview

Turn ideas into implementation plans through collaborative dialogue. Output follows the ralphex plan format for automated orchestration.

## MANDATORY: Follow This Process

You MUST NOT write any plan file until you have completed these steps:

Step 1: Understand (ask 2-3 questions minimum)

• Check out the current project state first (files, docs, recent commits)
• Ask questions ONE AT A TIME to refine the idea
• Prefer multiple choice questions when possible
• WAIT for user response before asking next question
• Focus on: purpose, constraints, success criteria

Step 2: Propose Approaches

• Propose 2-3 different approaches with trade-offs
• Lead with your recommended option and explain why
• WAIT for user agreement before proceeding

Step 3: Design Tasks

• Break the work into sequential tasks (one unit of work each)
• Present tasks one at a time, validating each before moving on
• Each task should be independently verifiable
• Ask: "Does this task breakdown make sense?"
• WAIT for user confirmation

Step 4: Write the Plan

• ONLY after user validates tasks, write the plan file
• Write specific, concrete, actionable checkbox items for each task
• Include test items in each task where applicable

DO NOT skip steps. DO NOT dump a complete plan without the conversation.

Plan Format

# Plan: [Meaningful Title]

[Brief description of the feature and overall goal - the overview section]

## Validation Commands

- `go test ./...`
- `golangci-lint run`

### Task 1: [First Task Title]

[2-4 sentences of context: what this task accomplishes, key components involved, what becomes possible after this task completes]

- [ ] Implement X
- [ ] Add tests for Y

### Task 2: [Second Task Title]

[Context for task 2...]

- [ ] Implement Z
- [ ] Update documentation

Format rules:

• Plan title uses # Plan: [Name] format (H1)
• Validation Commands section is required (## Validation Commands) with test/lint commands as a list
• Tasks use ### Task N: headers (H3) — alternative: ### Iteration N:
• Each task starts with context paragraph before checkbox items
• Checkbox items use - [ ] format (ralphex marks them - [x] when complete)
• Tasks are processed sequentially by the orchestrator

After the Plan

Documentation:

• Write the plan to docs/plans/YYYY-MM-DD-<topic>.md
• Commit the plan to git

Next steps:

• Ask: "Ready to run this with ralphex?"
• If yes, remind them: ralphex run --plan docs/plans/YYYY-MM-DD-<topic>.md

Key Principles

• One question at a time - Don't overwhelm
• Multiple choice preferred - Easier to answer
• YAGNI ruthlessly - Remove unnecessary work from plans
• Verifiable tasks - Each task must be mechanically verifiable via Validation Commands
• Incremental validation - Validate tasks, then write plan immediately