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