Hope Coding Plan
Plan only when planning reduces real uncertainty. A plan is an implementation
map, not a ritual and not a substitute for doing the work.
When A Formal Plan Helps
Use a plan when the task has one or more of:
- Multiple ownership boundaries or dependent steps.
- Schema, migration, persistence, compatibility, or recovery risk.
- Ambiguous architecture with several credible approaches.
- Parallel work that needs explicit isolation and synthesis.
- Named completion criteria or a long-running Goal.
Skip a formal plan for a small, obvious, reversible edit with a direct check.
Evidence First
Before planning:
- Read the user request and explicit completion criteria.
- Read
AGENTS.md, relevant architecture, current diff, and critical code.
- Find a similar implementation and trace the owning path.
- Identify unknowns that materially change the design.
Do not invent files, APIs, tests, or migrations from naming alone.
Plan Contents
Each step should name:
- Outcome and behavior changed.
- Critical files or subsystem, without pretending the exact line is known when
it is not.
- Dependencies and why the order matters.
- Data, compatibility, permission, concurrency, or rollback risk.
- Direct verification and completion signal.
Keep steps sized for review and progress tracking, not artificial five-minute
chunks. Separate must-have work from optional follow-up.
Modes And Execution
- In Plan Mode, remain read-only and return the implementation plan.
- Outside Plan Mode, when the user asked for implementation and the next step is
clear, update task progress and continue. Do not ask "shall I proceed?" merely
because a plan exists.
- Create a plan document only when the user asked for one or the repository
requires a durable design artifact.
/goal defines the outcome and criteria; this skill designs the current route.- Use
ha-workflow-script only when a durable dynamic script is justified.
Parallelism Decision
Mark steps parallel only when they are independent and have non-overlapping
writes or explicit worktree isolation. Use ha-multi-agent-coding for execution
strategy. A single broad investigation is not a batch fan-out.
Quality Check
Before accepting the plan:
- Does it preserve user changes and existing contracts?
- Does every required criterion have an implementation and evidence path?
- Are risky state transitions and failure recovery covered?
- Is the plan small enough to execute but complete enough to close?
- Is the first actionable step clear?
Smoke Prompts
- "Plan this cross-crate feature, then implement it."
- "Design a read-only migration plan with rollback and verification."
- "Turn these completion criteria into an executable coding plan."
1---
2name: ha-coding-plan
3description: "Hope-native implementation planning for non-trivial code changes: ground the plan in repository evidence, order dependencies, name critical files and risks, define verification, then continue execution when allowed."
4paths: ["*.rs", "*.ts", "*.tsx", "*.js", "*.jsx", "*.py", "*.go", "*.java", "*.kt", "*.swift", "*.c", "*.cpp", "*.h", "*.rb", "*.php", "*.sh"]
5---
6
7# Hope Coding Plan
8
9Plan only when planning reduces real uncertainty. A plan is an implementation
10map, not a ritual and not a substitute for doing the work.
11
12## When A Formal Plan Helps
13
14Use a plan when the task has one or more of:
15
16- Multiple ownership boundaries or dependent steps.
17- Schema, migration, persistence, compatibility, or recovery risk.
18- Ambiguous architecture with several credible approaches.
19- Parallel work that needs explicit isolation and synthesis.
20- Named completion criteria or a long-running Goal.
21
22Skip a formal plan for a small, obvious, reversible edit with a direct check.
23
24## Evidence First
25
26Before planning:
27
281. Read the user request and explicit completion criteria.
292. Read `AGENTS.md`, relevant architecture, current diff, and critical code.
303. Find a similar implementation and trace the owning path.
314. Identify unknowns that materially change the design.
32
33Do not invent files, APIs, tests, or migrations from naming alone.
34
35## Plan Contents
36
37Each step should name:
38
39- Outcome and behavior changed.
40- Critical files or subsystem, without pretending the exact line is known when
41 it is not.
42- Dependencies and why the order matters.
43- Data, compatibility, permission, concurrency, or rollback risk.
44- Direct verification and completion signal.
45
46Keep steps sized for review and progress tracking, not artificial five-minute
47chunks. Separate must-have work from optional follow-up.
48
49## Modes And Execution
50
51- In Plan Mode, remain read-only and return the implementation plan.
52- Outside Plan Mode, when the user asked for implementation and the next step is
53 clear, update task progress and continue. Do not ask "shall I proceed?" merely
54 because a plan exists.
55- Create a plan document only when the user asked for one or the repository
56 requires a durable design artifact.
57- `/goal` defines the outcome and criteria; this skill designs the current route.
58- Use `ha-workflow-script` only when a durable dynamic script is justified.
59
60## Parallelism Decision
61
62Mark steps parallel only when they are independent and have non-overlapping
63writes or explicit worktree isolation. Use `ha-multi-agent-coding` for execution
64strategy. A single broad investigation is not a batch fan-out.
65
66## Quality Check
67
68Before accepting the plan:
69
70- Does it preserve user changes and existing contracts?
71- Does every required criterion have an implementation and evidence path?
72- Are risky state transitions and failure recovery covered?
73- Is the plan small enough to execute but complete enough to close?
74- Is the first actionable step clear?
75
76## Smoke Prompts
77
78- "Plan this cross-crate feature, then implement it."
79- "Design a read-only migration plan with rollback and verification."
80- "Turn these completion criteria into an executable coding plan."
shiwenwen