evanflow-writing-plans

Name: evanflow-writing-plans
Author: evanklem

419stars18forks

How to install evanflow-writing-plans?

evanklem/evanflow/evanflow-writing-plans

$npx -y skills add evanklem/evanflow --skill evanflow-writing-plans

Installs into the current project.

Summary

Turn a spec or requirements into a bite-sized implementation plan. File-structure-first (deep modules), embedded grill to stress-test, no forced sub-skill chains. Use when you have a spec or clear requirements and are ready to plan execution.

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Writing Plans
2
3
4
5	## Vocabulary
6
7	See `evanflow` meta-skill. Key terms: deep modules, interface, vertical slice, deletion test.
8
9	## When to Use
10
11	- A spec or clear requirements exist
12	- Multi-step task that benefits from upfront decomposition
13	- About to touch ≥3 files
14
15	SKIP when: single-file change, typo fix, one-line config tweak. Just do it.
16
17	## The Flow
18
19	### 1. Scope Check
20
21	If the spec covers multiple independent subsystems, suggest splitting into separate plans. Each plan should produce working, testable software on its own.
22
23	### 2. File Structure First
24
25	Before any tasks, name the files that will be created or modified, with a one-line responsibility for each. This locks in decomposition decisions.
26
27	Example (adapt the paths to your project's structure):
28
29	```
30	<backend>/routers/foo.ts — API router; thin, delegates to service
31	<backend>/services/foo.ts — business logic; pure where possible
32	<backend>/services/foo.test.ts — vertical-slice tests
33	<frontend>/pages/foo.tsx — UI; consumes the API
34	```
35
36	Apply the deletion test: if a file would just shuffle complexity to its callers, fold it into the caller.
37
38	### 2.5. Parallelization Check (offer coder-overseer if applicable)
39
40	After the file structure is sketched, ask: does this plan have 3+ truly independent units that share a common interface contract?
41
42	If YES — offer `evanflow-coder-overseer` to the user as the execution path:
43
44	> "This plan has [N] independent units sharing [contract]. We could execute it sequentially via `evanflow-executing-plans`, or in parallel via `evanflow-coder-overseer` (one coder per unit + per-coder overseer + integration overseer + executable contract via integration tests). Parallel is faster for big plans and adds independent QA, but only works if the units are truly independent. Which?"
45
46	Signals that favor coder-overseer:
47	- 3+ files/modules that don't import each other
48	- A clear shared interface contract (types, naming, invariants)
49	- Integration touchpoints that can be expressed as named integration tests
50	- Plan would otherwise be tedious to execute serially
51
52	Signals that favor sequential `executing-plans`:
53	- Tasks have hidden dependencies (one's output feeds the next)
54	- Fewer than 3 units
55	- No shared contract surface — units don't need to interoperate
56	- Risk-averse work (auth, payments, migrations) where a single careful pass beats parallelism
57
58	If the user picks coder-overseer, structure the plan with a per-coder section and the cohesion contract upfront. If sequential, continue to step 3 normally.
59
60	### 3. Embedded Grill
61
62	Stress-test the structure before writing tasks:
63
64	- "Where does this go wrong if the user does X?"
65	- "What happens if this fails halfway? What's the recovery?"
66	- "Is there an existing service in the project that already does part of this?"
67	- "Does the file structure follow project conventions documented in CLAUDE.md or visible in similar existing files?"
68	- "Are we introducing or changing domain terms? Update `CONTEXT.md` first?"
69
70	### 4. Bite-Sized Tasks
71
72	Each task is one focused unit (~15-30 min of work). Within each task, list bite-sized steps (~2-5 min each):
73
74	```markdown
75	### Task 1: [Component Name]
76
77	Files: Create `path/to/foo.ts`, modify `path/to/bar.ts:123-145`, test `path/to/foo.test.ts`
78
79	- [ ] Write the failing test (one behavior — see evanflow-tdd)
80	- [ ] Run test, confirm it fails for the right reason
81	- [ ] Write minimal implementation
82	- [ ] Run test, confirm it passes
83	- [ ] Run the project's quality checks (typecheck / lint / test) — exact commands are project-specific; see CLAUDE.md or the project's README
84	```
85
86	After all tasks complete, the executor hands off to `evanflow-iterate` for self-review, then stops and reports. The plan does NOT include staging or committing — the user controls those.
87
88	### 5. Plan Header (lighter than upstream)
89
90	```markdown
91	# [Feature Name] Plan
92
93	Goal: [one sentence]
94	Architecture: [2-3 sentences]
95	Files: [list from step 2]
96
97	---
98	```
99
100	No "REQUIRED SUB-SKILL" header. Sub-skills are suggestions documented inline at hand-off points, not mandates baked into the plan format.
101
102	### 6. Save the Plan
103
104	Default location: `docs/plans/YYYY-MM-DD-<topic>.md`. If the user has a different preference, honor it. Don't write to any vendor-specific path unless explicitly asked.
105
106	## Hard Rules
107
108	- Never include staging or commit steps in the plan. Plans end at "verified, await user direction." The user decides when to stage, commit, push, merge.
109	- No forced sub-skill chain. No "must use using-git-worktrees" or "must use subagent-driven-development" header.
110	- Plans live where the user wants. Default `docs/plans/` only

People who liked this also viewed

6 picks

Type

evanflow-writing-plans

419stars18forks

View on GitHub

How to install evanflow-writing-plans?

evanklem/evanflow/evanflow-writing-plans

$npx -y skills add evanklem/evanflow --skill evanflow-writing-plans

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Writing Plans
2
3
4
5	## Vocabulary
6
7	See `evanflow` meta-skill. Key terms: deep modules, interface, vertical slice, deletion test.
8
9	## When to Use
10
11	- A spec or clear requirements exist
12	- Multi-step task that benefits from upfront decomposition
13	- About to touch ≥3 files
14
15	SKIP when: single-file change, typo fix, one-line config tweak. Just do it.
16
17	## The Flow
18
19	### 1. Scope Check
20
21	If the spec covers multiple independent subsystems, suggest splitting into separate plans. Each plan should produce working, testable software on its own.
22
23	### 2. File Structure First
24
25	Before any tasks, name the files that will be created or modified, with a one-line responsibility for each. This locks in decomposition decisions.
26
27	Example (adapt the paths to your project's structure):
28
29	```
30	<backend>/routers/foo.ts — API router; thin, delegates to service
31	<backend>/services/foo.ts — business logic; pure where possible
32	<backend>/services/foo.test.ts — vertical-slice tests
33	<frontend>/pages/foo.tsx — UI; consumes the API
34	```
35
36	Apply the deletion test: if a file would just shuffle complexity to its callers, fold it into the caller.
37
38	### 2.5. Parallelization Check (offer coder-overseer if applicable)
39
40	After the file structure is sketched, ask: does this plan have 3+ truly independent units that share a common interface contract?
41
42	If YES — offer `evanflow-coder-overseer` to the user as the execution path:
43
44	> "This plan has [N] independent units sharing [contract]. We could execute it sequentially via `evanflow-executing-plans`, or in parallel via `evanflow-coder-overseer` (one coder per unit + per-coder overseer + integration overseer + executable contract via integration tests). Parallel is faster for big plans and adds independent QA, but only works if the units are truly independent. Which?"
45
46	Signals that favor coder-overseer:
47	- 3+ files/modules that don't import each other
48	- A clear shared interface contract (types, naming, invariants)
49	- Integration touchpoints that can be expressed as named integration tests
50	- Plan would otherwise be tedious to execute serially
51
52	Signals that favor sequential `executing-plans`:
53	- Tasks have hidden dependencies (one's output feeds the next)
54	- Fewer than 3 units
55	- No shared contract surface — units don't need to interoperate
56	- Risk-averse work (auth, payments, migrations) where a single careful pass beats parallelism
57
58	If the user picks coder-overseer, structure the plan with a per-coder section and the cohesion contract upfront. If sequential, continue to step 3 normally.
59
60	### 3. Embedded Grill
61
62	Stress-test the structure before writing tasks:
63
64	- "Where does this go wrong if the user does X?"
65	- "What happens if this fails halfway? What's the recovery?"
66	- "Is there an existing service in the project that already does part of this?"
67	- "Does the file structure follow project conventions documented in CLAUDE.md or visible in similar existing files?"
68	- "Are we introducing or changing domain terms? Update `CONTEXT.md` first?"
69
70	### 4. Bite-Sized Tasks
71
72	Each task is one focused unit (~15-30 min of work). Within each task, list bite-sized steps (~2-5 min each):
73
74	```markdown
75	### Task 1: [Component Name]
76
77	Files: Create `path/to/foo.ts`, modify `path/to/bar.ts:123-145`, test `path/to/foo.test.ts`
78
79	- [ ] Write the failing test (one behavior — see evanflow-tdd)
80	- [ ] Run test, confirm it fails for the right reason
81	- [ ] Write minimal implementation
82	- [ ] Run test, confirm it passes
83	- [ ] Run the project's quality checks (typecheck / lint / test) — exact commands are project-specific; see CLAUDE.md or the project's README
84	```
85
86	After all tasks complete, the executor hands off to `evanflow-iterate` for self-review, then stops and reports. The plan does NOT include staging or committing — the user controls those.
87
88	### 5. Plan Header (lighter than upstream)
89
90	```markdown
91	# [Feature Name] Plan
92
93	Goal: [one sentence]
94	Architecture: [2-3 sentences]
95	Files: [list from step 2]
96
97	---
98	```
99
100	No "REQUIRED SUB-SKILL" header. Sub-skills are suggestions documented inline at hand-off points, not mandates baked into the plan format.
101
102	### 6. Save the Plan
103
104	Default location: `docs/plans/YYYY-MM-DD-<topic>.md`. If the user has a different preference, honor it. Don't write to any vendor-specific path unless explicitly asked.
105
106	## Hard Rules
107
108	- Never include staging or commit steps in the plan. Plans end at "verified, await user direction." The user decides when to stage, commit, push, merge.
109	- No forced sub-skill chain. No "must use using-git-worktrees" or "must use subagent-driven-development" header.
110	- Plans live where the user wants. Default `docs/plans/` only

People who liked this also viewed

6 picks

Type