plan-mode
npx machina-cli add skill mpuig/raw/plan-mode --openclawFiles (1)
SKILL.md
1.9 KB
Plan Mode Skill
Use this skill when creating a plan for workflow implementation.
Plan Structure
Your plan MUST follow this structure:
1. Analysis
- What needs to be done and why?
- What is the current state vs. desired state?
- What are the constraints or requirements?
2. Approach
- High-level strategy for implementation
- Key design decisions
- Which patterns or libraries to use
3. Steps
- Numbered, concrete steps (3-10 steps typically)
- Each step should be specific and actionable
- Include which files will be modified
- Mention which tools/imports are needed
- Consider dependencies between steps
4. Quality Gates
- List gates that should pass after execution
- Always include:
validate,dry - Add optional gates if needed:
pytest,ruff,typecheck
Example Plan
## Analysis
The workflow needs to fetch stock prices from Yahoo Finance API to provide
real-time data. Currently, there's no data fetching capability.
## Approach
We will create a new tool `yahoo_finance` in tools/ that wraps the yfinance
library, then integrate it into the workflow using a @step decorator.
## Steps
1. Create tools/yahoo_finance/tool.py with fetch_stock_price() function
2. Add yfinance dependency to tool's config.yaml
3. Update workflow run.py to import yahoo_finance
4. Add @step("fetch_prices") that calls yahoo_finance.fetch_stock_price()
5. Update dry_run.py with mock stock data for testing
6. Add test case in test.py for the fetch step
## Quality Gates
- validate: Structural validation must pass
- dry: Dry run with mocks must complete successfully
- pytest: All unit tests must pass
Tips
- Keep steps atomic and sequential
- Don't skip validation in your plan
- Always consider the dry run path
- Think about error cases and edge conditions
- Reference existing code patterns when possible
Source
git clone https://github.com/mpuig/raw/blob/main/builder/skills/plan-mode/SKILL.mdView on GitHub Overview
Plan Mode guides you to craft a workflow plan organized into Analysis, Approach, Steps, and Quality Gates. It emphasizes concrete, actionable steps, explicit file changes, dependencies, and checks that ensure plan integrity.
How This Skill Works
Define four sections: Analysis, Approach, Steps, and Quality Gates. Each Step is numbered, actionable, and notes which files/tools to modify; Quality Gates like validate and dry are required to pass before execution.
When to Use It
- Starting a new workflow implementation from scratch.
- Coordinating tool integrations with clear steps and dependencies.
- Preparing a milestone plan that includes quality gates.
- Documenting a repeatable automation task for future reuse.
- Auditing an existing process to improve reproducibility and checks.
Quick Start
- Step 1: Write Analysis and State the goal, current vs desired state, and constraints.
- Step 2: Define Approach and a concrete Steps list (3-10 items) with file/tool changes.
- Step 3: Specify mandatory Quality Gates (validate, dry) and optional ones as needed.
Best Practices
- Keep steps atomic and sequential.
- Always include Analysis, Approach, Steps, and Quality Gates.
- Specify affected files, tools, and imports in each step.
- Identify dependencies and edge cases before execution.
- Always run a dry run and validate the plan before implementation.
Example Use Cases
- Create a new tool under tools/, wrap it as a tool, and reference it in the plan.
- Add a dependency to a tool's config.yaml to support a new capability.
- Update run.py to import and integrate the new tool into the workflow.
- Add a concrete step that calls the tool and handles its outputs.
- Run a dry_run with mock data and verify all Quality Gates pass.
Frequently Asked Questions
Add this skill to your agents
