plan-flow-skill 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/.claude/commands/create-contract.md +468 -0
  2. package/.claude/commands/create-plan.md +512 -0
  3. package/.claude/commands/discovery-plan.md +561 -0
  4. package/.claude/commands/execute-plan.md +682 -0
  5. package/.claude/commands/review-code.md +459 -0
  6. package/.claude/commands/review-pr.md +651 -0
  7. package/.claude/commands/setup.md +1609 -0
  8. package/.claude/commands/write-tests.md +543 -0
  9. package/.claude/rules/core/allowed-patterns.md +175 -0
  10. package/.claude/rules/core/complexity-scoring.md +225 -0
  11. package/.claude/rules/core/forbidden-patterns.md +253 -0
  12. package/.claude/rules/languages/python-patterns.md +6 -0
  13. package/.claude/rules/languages/typescript-patterns.md +7 -0
  14. package/.claude/rules/patterns/contract-patterns.md +332 -0
  15. package/.claude/rules/patterns/discovery-patterns.md +342 -0
  16. package/.claude/rules/patterns/discovery-templates.md +319 -0
  17. package/.claude/rules/patterns/jest-patterns.md +482 -0
  18. package/.claude/rules/patterns/plans-patterns.md +225 -0
  19. package/.claude/rules/patterns/plans-templates.md +227 -0
  20. package/.claude/rules/patterns/pytest-patterns.md +457 -0
  21. package/.claude/rules/patterns/review-code-templates.md +305 -0
  22. package/.claude/rules/patterns/review-pr-patterns.md +360 -0
  23. package/.claude/rules/tools/auth-pr-tool.md +30 -0
  24. package/.claude/rules/tools/interactive-questions-tool.md +235 -0
  25. package/.claude/rules/tools/jest-testing-tool.md +73 -0
  26. package/.claude/rules/tools/plan-mode-tool.md +164 -0
  27. package/.claude/rules/tools/pytest-testing-tool.md +121 -0
  28. package/.claude/rules/tools/reference-expansion-tool.md +326 -0
  29. package/LICENSE +21 -0
  30. package/README.md +167 -0
  31. package/dist/cli/commands/init.d.ts +6 -0
  32. package/dist/cli/commands/init.d.ts.map +1 -0
  33. package/dist/cli/commands/init.js +139 -0
  34. package/dist/cli/commands/init.js.map +1 -0
  35. package/dist/cli/handlers/claude.d.ts +9 -0
  36. package/dist/cli/handlers/claude.d.ts.map +1 -0
  37. package/dist/cli/handlers/claude.js +119 -0
  38. package/dist/cli/handlers/claude.js.map +1 -0
  39. package/dist/cli/handlers/codex.d.ts +9 -0
  40. package/dist/cli/handlers/codex.d.ts.map +1 -0
  41. package/dist/cli/handlers/codex.js +100 -0
  42. package/dist/cli/handlers/codex.js.map +1 -0
  43. package/dist/cli/handlers/cursor.d.ts +8 -0
  44. package/dist/cli/handlers/cursor.d.ts.map +1 -0
  45. package/dist/cli/handlers/cursor.js +34 -0
  46. package/dist/cli/handlers/cursor.js.map +1 -0
  47. package/dist/cli/handlers/openclaw.d.ts +8 -0
  48. package/dist/cli/handlers/openclaw.d.ts.map +1 -0
  49. package/dist/cli/handlers/openclaw.js +34 -0
  50. package/dist/cli/handlers/openclaw.js.map +1 -0
  51. package/dist/cli/handlers/shared.d.ts +9 -0
  52. package/dist/cli/handlers/shared.d.ts.map +1 -0
  53. package/dist/cli/handlers/shared.js +44 -0
  54. package/dist/cli/handlers/shared.js.map +1 -0
  55. package/dist/cli/index.d.ts +8 -0
  56. package/dist/cli/index.d.ts.map +1 -0
  57. package/dist/cli/index.js +43 -0
  58. package/dist/cli/index.js.map +1 -0
  59. package/dist/cli/types.d.ts +26 -0
  60. package/dist/cli/types.d.ts.map +1 -0
  61. package/dist/cli/types.js +5 -0
  62. package/dist/cli/types.js.map +1 -0
  63. package/dist/cli/utils/files.d.ts +37 -0
  64. package/dist/cli/utils/files.d.ts.map +1 -0
  65. package/dist/cli/utils/files.js +122 -0
  66. package/dist/cli/utils/files.js.map +1 -0
  67. package/dist/cli/utils/logger.d.ts +11 -0
  68. package/dist/cli/utils/logger.d.ts.map +1 -0
  69. package/dist/cli/utils/logger.js +34 -0
  70. package/dist/cli/utils/logger.js.map +1 -0
  71. package/dist/cli/utils/prompts.d.ts +10 -0
  72. package/dist/cli/utils/prompts.d.ts.map +1 -0
  73. package/dist/cli/utils/prompts.js +65 -0
  74. package/dist/cli/utils/prompts.js.map +1 -0
  75. package/dist/test/setup.d.ts +5 -0
  76. package/dist/test/setup.d.ts.map +1 -0
  77. package/dist/test/setup.js +7 -0
  78. package/dist/test/setup.js.map +1 -0
  79. package/package.json +63 -0
  80. package/rules/core/_index.mdc +89 -0
  81. package/rules/core/allowed-patterns.mdc +185 -0
  82. package/rules/core/complexity-scoring.mdc +235 -0
  83. package/rules/core/forbidden-patterns.mdc +263 -0
  84. package/rules/languages/_index.mdc +80 -0
  85. package/rules/languages/python-patterns.mdc +188 -0
  86. package/rules/languages/typescript-patterns.mdc +128 -0
  87. package/rules/patterns/_index.mdc +185 -0
  88. package/rules/patterns/contract-patterns.mdc +344 -0
  89. package/rules/patterns/discovery-patterns.mdc +354 -0
  90. package/rules/patterns/discovery-templates.mdc +329 -0
  91. package/rules/patterns/jest-patterns.mdc +492 -0
  92. package/rules/patterns/plans-patterns.mdc +237 -0
  93. package/rules/patterns/plans-templates.mdc +237 -0
  94. package/rules/patterns/pytest-patterns.mdc +467 -0
  95. package/rules/patterns/review-code-templates.mdc +315 -0
  96. package/rules/patterns/review-pr-patterns.mdc +370 -0
  97. package/rules/skills/_index.mdc +174 -0
  98. package/rules/skills/create-contract-skill.mdc +239 -0
  99. package/rules/skills/create-plan-skill.mdc +271 -0
  100. package/rules/skills/discovery-skill.mdc +295 -0
  101. package/rules/skills/execute-plan-skill.mdc +388 -0
  102. package/rules/skills/review-code-skill.mdc +308 -0
  103. package/rules/skills/review-pr-skill.mdc +496 -0
  104. package/rules/skills/setup-skill.mdc +923 -0
  105. package/rules/skills/write-tests-skill.mdc +294 -0
  106. package/rules/templates/index-template.mdc +126 -0
  107. package/rules/tools/_index.mdc +114 -0
  108. package/rules/tools/auth-pr-tool.mdc +362 -0
  109. package/rules/tools/interactive-questions-tool.mdc +337 -0
  110. package/rules/tools/jest-testing-tool.mdc +96 -0
  111. package/rules/tools/plan-mode-tool.mdc +229 -0
  112. package/rules/tools/pytest-testing-tool.mdc +144 -0
  113. package/rules/tools/reference-expansion-tool.mdc +338 -0
  114. package/skills/plan-flow/SKILL.md +109 -0
  115. package/skills/plan-flow/create-contract/SKILL.md +139 -0
  116. package/skills/plan-flow/create-plan/SKILL.md +93 -0
  117. package/skills/plan-flow/discovery/SKILL.md +85 -0
  118. package/skills/plan-flow/execute-plan/SKILL.md +89 -0
  119. package/skills/plan-flow/review-code/SKILL.md +100 -0
  120. package/skills/plan-flow/review-pr/SKILL.md +122 -0
  121. package/skills/plan-flow/setup/SKILL.md +73 -0
  122. package/skills/plan-flow/write-tests/SKILL.md +115 -0
  123. package/templates/shared/AGENTS.md.template +60 -0
  124. package/templates/shared/CLAUDE.md.template +62 -0
@@ -0,0 +1,326 @@
1
+
2
+ ## Reference Code System
3
+
4
+ ### Code Prefixes
5
+
6
+ | Prefix | Folder | Description |
7
+ |--------|--------|-------------|
8
+ | COR- | `rules/core/` | Core rules (allowed/forbidden patterns, complexity) |
9
+ | LNG- | `rules/languages/` | Language-specific patterns |
10
+ | PTN- | `rules/patterns/` | Pattern files (discovery, plans, tests, etc.) |
11
+ | SKL- | `rules/skills/` | Skill files for commands |
12
+ | TLS- | `rules/tools/` | Tool documentation |
13
+
14
+ ### Code Format
15
+
16
+ ```
17
+ [PREFIX]-[SUBCATEGORY]-[NUMBER]
18
+ ```
19
+
20
+ **Examples**:
21
+ - `COR-1` - Core rule section 1
22
+ - `LNG-TS-1` - TypeScript pattern section 1
23
+ - `PTN-DIS-1` - Discovery pattern section 1
24
+ - `SKL-EXEC-1` - Execute plan skill section 1
25
+ - `TLS-AUTH-1` - Auth tool section 1
26
+
27
+ ---
28
+
29
+ ## Expansion Workflow
30
+
31
+ ### Step 1: Load the Index
32
+
33
+ When a command or skill is invoked, load the relevant `_index.md` file:
34
+
35
+ ```
36
+ rules/[folder]/_index.md
37
+ ```
38
+
39
+ The index contains a table of all reference codes with descriptions.
40
+
41
+ ### Step 2: Identify Needed References
42
+
43
+ Based on the current task, identify which reference codes are needed:
44
+
45
+ - Read the "When to Expand" section in the index
46
+ - Match the task to specific codes
47
+ - Only expand what's needed for the current task
48
+
49
+ ### Step 3: Expand Reference Codes
50
+
51
+ Use the Read tool to load the specific line range:
52
+
53
+ ```
54
+ Read file: rules/[folder]/[filename].md
55
+ Lines: [start]-[end]
56
+ ```
57
+
58
+ ### Step 4: Use the Content
59
+
60
+ The expanded content is now in context. Use it for the current task.
61
+
62
+ ---
63
+
64
+ ## When to Expand vs. When to Skip
65
+
66
+ ### Expand When
67
+
68
+ | Situation | Action |
69
+ |-----------|--------|
70
+ | Creating a discovery document | Expand PTN-DIS-* (discovery templates/patterns) |
71
+ | Writing tests | Expand PTN-JEST-* or PTN-PYTEST-* |
72
+ | Reviewing a PR | Expand PTN-PR-* and SKL-PR-* |
73
+ | Need specific example code | Expand the example section code |
74
+ | Following a specific pattern | Expand that pattern's section |
75
+
76
+ ### Skip When
77
+
78
+ | Situation | Action |
79
+ |-----------|--------|
80
+ | Task is simple and familiar | Use index summary only |
81
+ | Pattern is well-known | Don't expand, just reference |
82
+ | Multiple sections might apply | Start with index, narrow down |
83
+ | Already have similar context | Don't duplicate |
84
+
85
+ ---
86
+
87
+ ## Example: Discovery Command
88
+
89
+ **Task**: Create a discovery document
90
+
91
+ **Step 1**: Load index
92
+ ```
93
+ Read: rules/patterns/_index.md
94
+ ```
95
+
96
+ **Step 2**: Identify needed codes from index
97
+ - PTN-DIS-1: Discovery document template
98
+ - PTN-DIS-2: Requirements gathering example
99
+
100
+ **Step 3**: Expand specific sections
101
+ ```
102
+ Read: rules/patterns/discovery-templates.md
103
+ Lines: 15-80 (for PTN-DIS-1)
104
+ Lines: 244-279 (for PTN-DIS-2)
105
+ ```
106
+
107
+ **Step 4**: Use templates to create the document
108
+
109
+ ---
110
+
111
+ ## Example: Execute Plan Command
112
+
113
+ **Task**: Execute an implementation plan
114
+
115
+ **Step 1**: Load indexes
116
+ ```
117
+ Read: rules/skills/_index.md
118
+ Read: rules/core/_index.md
119
+ ```
120
+
121
+ **Step 2**: Identify needed codes
122
+ - SKL-EXEC-1: Execution workflow
123
+ - SKL-EXEC-2: Complexity-based grouping
124
+ - COR-3: Complexity scoring table
125
+
126
+ **Step 3**: Expand as needed during execution
127
+
128
+ ---
129
+
130
+ ## Maintenance Guidelines
131
+
132
+ ### When to Update Indexes
133
+
134
+ Update the relevant `_index.md` when:
135
+
136
+ 1. **Adding a new section** to a source file
137
+ 2. **Removing a section** from a source file
138
+ 3. **Renaming a section** in a source file
139
+ 4. **Line numbers change** significantly (after major edits)
140
+
141
+ ### How to Update
142
+
143
+ 1. Open the source file and identify the new/changed section
144
+ 2. Note the line range (start line to end line)
145
+ 3. Update the `_index.md` reference table:
146
+ - Add new code for new sections
147
+ - Update line ranges for moved sections
148
+ - Remove codes for deleted sections
149
+
150
+ ### Best Practices
151
+
152
+ | Practice | Reason |
153
+ |----------|--------|
154
+ | Update index immediately after editing source | Prevents stale references |
155
+ | Use descriptive section descriptions | Helps identify correct code |
156
+ | Keep line ranges accurate | Ensures correct content is loaded |
157
+ | Review indexes periodically | Catch any drift |
158
+
159
+ ---
160
+
161
+ ## Index File Locations
162
+
163
+ | Folder | Index Path |
164
+ |--------|------------|
165
+ | Core | `rules/core/_index.md` |
166
+ | Languages | `rules/languages/_index.md` |
167
+ | Patterns | `rules/patterns/_index.md` |
168
+ | Skills | `rules/skills/_index.md` |
169
+ | Tools | `rules/tools/_index.md` |
170
+
171
+ ---
172
+
173
+ ## Troubleshooting
174
+
175
+ ### Reference Code Not Found
176
+
177
+ If a reference code isn't in the index:
178
+ 1. Check the prefix matches the correct folder
179
+ 2. Verify the index file exists
180
+ 3. The section may have been added recently - check source file
181
+
182
+ ### Line Range Invalid
183
+
184
+ If the line range doesn't match expected content:
185
+ 1. The source file was edited after index creation
186
+ 2. Re-analyze the source file
187
+ 3. Update the line range in the index
188
+
189
+ ### Content Seems Incomplete
190
+
191
+ If expanded content is missing context:
192
+ 1. Expand a larger line range
193
+ 2. Include surrounding sections
194
+ 3. Check if section references other sections
195
+
196
+ ---
197
+
198
+ ## Adding New Reference Codes
199
+
200
+ When adding content to the project that should be indexed:
201
+
202
+ ### Step 1: Create or Edit the Source File
203
+
204
+ Add your new section to the appropriate file in `rules/`:
205
+ - Core rules → `rules/core/`
206
+ - Language patterns → `rules/languages/`
207
+ - Patterns → `rules/patterns/`
208
+ - Skills → `rules/skills/`
209
+ - Tools → `rules/tools/`
210
+
211
+ ### Step 2: Determine the Reference Code
212
+
213
+ Use the naming convention:
214
+ ```
215
+ [PREFIX]-[SUBCATEGORY]-[NUMBER]
216
+ ```
217
+
218
+ | Prefix | For Files In |
219
+ |--------|--------------|
220
+ | COR- | rules/core/ |
221
+ | LNG- | rules/languages/ |
222
+ | PTN- | rules/patterns/ |
223
+ | SKL- | rules/skills/ |
224
+ | TLS- | rules/tools/ |
225
+
226
+ ### Step 3: Update the Index
227
+
228
+ Open `rules/[folder]/_index.md` and add a new row to the reference table:
229
+
230
+ ```markdown
231
+ | NEW-CODE-1 | 150-180 | Description of the new section |
232
+ ```
233
+
234
+ ### Step 4: Verify
235
+
236
+ 1. Check the line numbers match the actual content
237
+ 2. Ensure the description is clear and actionable
238
+ 3. Update "When to Expand" section if needed
239
+
240
+ ---
241
+
242
+ ## Context Savings Estimate
243
+
244
+ The hierarchical loading system reduces context consumption significantly:
245
+
246
+ ### Before (Full Loading)
247
+
248
+ | Folder | Total Lines | Always Loaded |
249
+ |--------|-------------|---------------|
250
+ | rules/core/ | ~1,200 | Yes (partial) |
251
+ | rules/languages/ | ~800 | No |
252
+ | rules/patterns/ | ~2,500 | No |
253
+ | rules/skills/ | ~2,800 | No |
254
+ | rules/tools/ | ~1,400 | No |
255
+ | **Total** | **~8,700** | |
256
+
257
+ ### After (Index + On-Demand)
258
+
259
+ | Component | Lines | When Loaded |
260
+ |-----------|-------|-------------|
261
+ | Index files (6 total) | ~600 | Per command |
262
+ | Average expansion | ~100-200 | Per task |
263
+ | **Typical session** | **~800-1,000** | |
264
+
265
+ ### Estimated Savings
266
+
267
+ | Scenario | Before | After | Savings |
268
+ |----------|--------|-------|---------|
269
+ | Discovery command | ~3,500 lines | ~800 lines | ~77% |
270
+ | Execute plan | ~4,000 lines | ~1,000 lines | ~75% |
271
+ | Write tests | ~2,500 lines | ~600 lines | ~76% |
272
+ | **Average** | **~3,300 lines** | **~800 lines** | **~76%** |
273
+
274
+ ---
275
+
276
+ ## System Overview
277
+
278
+ The context optimization system consists of:
279
+
280
+ ### Components
281
+
282
+ | Component | Location | Purpose |
283
+ |-----------|----------|---------|
284
+ | Index Template | `rules/templates/index-template.md` | Template for creating new indexes |
285
+ | Core Index | `rules/core/_index.md` | Core rules reference codes |
286
+ | Languages Index | `rules/languages/_index.md` | Language patterns reference codes |
287
+ | Patterns Index | `rules/patterns/_index.md` | Pattern files reference codes |
288
+ | Skills Index | `rules/skills/_index.md` | Skill files reference codes |
289
+ | Tools Index | `rules/tools/_index.md` | Tool files reference codes |
290
+ | Expansion Tool | `rules/tools/reference-expansion-tool.md` | This documentation |
291
+
292
+ ### Workflow Summary
293
+
294
+ ```
295
+ Command Invoked
296
+ |
297
+ v
298
+ Load Command File
299
+ |
300
+ v
301
+ Load Relevant Indexes (_index.md)
302
+ |
303
+ v
304
+ Identify Needed Reference Codes
305
+ |
306
+ v
307
+ Expand Specific Sections (Read tool)
308
+ |
309
+ v
310
+ Execute Task with Loaded Context
311
+ |
312
+ v
313
+ (Optional) Update Indexes if Files Changed
314
+ ```
315
+
316
+ ---
317
+
318
+ ## Summary
319
+
320
+ | Step | Action |
321
+ |------|--------|
322
+ | 1 | Load `_index.md` for relevant folder |
323
+ | 2 | Identify reference codes needed for task |
324
+ | 3 | Use Read tool with specific line ranges |
325
+ | 4 | Use content for current task |
326
+ | 5 | Update index if source files change |
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Plan-Flow Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,167 @@
1
+ # Plan-Flow
2
+
3
+ Structured AI-assisted development workflows for discovery, planning, execution, code reviews, and testing.
4
+
5
+ Works with **Claude Code**, **Cursor**, **OpenClaw**, and **Codex CLI**.
6
+
7
+ ## Quick Start
8
+
9
+ ```bash
10
+ npx plan-flow init
11
+ ```
12
+
13
+ This interactive command installs plan-flow into your project for your chosen platform(s).
14
+
15
+ ## Installation by Platform
16
+
17
+ ### Claude Code
18
+
19
+ ```bash
20
+ npx plan-flow init --claude
21
+ ```
22
+
23
+ Installs slash commands (`.claude/commands/`) and pattern rules (`.claude/rules/`) into your project. Creates or updates your `CLAUDE.md` with plan-flow instructions.
24
+
25
+ ### Cursor
26
+
27
+ ```bash
28
+ npx plan-flow init --cursor
29
+ ```
30
+
31
+ Copies Cursor-compatible rules (`rules/*.mdc`) into your project.
32
+
33
+ ### OpenClaw
34
+
35
+ ```bash
36
+ npx plan-flow init --openclaw
37
+ ```
38
+
39
+ Copies skill manifests to `skills/plan-flow/` in your project.
40
+
41
+ ### Codex CLI
42
+
43
+ ```bash
44
+ npx plan-flow init --codex
45
+ ```
46
+
47
+ Copies skills to `.agents/skills/plan-flow/` and creates or updates your `AGENTS.md` with plan-flow instructions.
48
+
49
+ ### All Platforms
50
+
51
+ ```bash
52
+ npx plan-flow init --all
53
+ ```
54
+
55
+ Installs for Claude Code, Cursor, OpenClaw, and Codex CLI simultaneously.
56
+
57
+ ### Options
58
+
59
+ | Flag | Description |
60
+ |------|-------------|
61
+ | `--claude` | Install for Claude Code |
62
+ | `--cursor` | Install for Cursor |
63
+ | `--openclaw` | Install for OpenClaw |
64
+ | `--codex` | Install for Codex CLI |
65
+ | `--all` | Install for all platforms |
66
+ | `--force` | Overwrite existing files |
67
+ | `--target <dir>` | Target directory (defaults to current) |
68
+
69
+ ## Manual Installation
70
+
71
+ ### Claude Code (Manual)
72
+
73
+ 1. Copy `.claude/commands/*.md` to your project's `.claude/commands/`
74
+ 2. Copy `.claude/rules/` to your project's `.claude/rules/`
75
+ 3. Add the plan-flow section from `templates/shared/CLAUDE.md.template` to your `CLAUDE.md`
76
+
77
+ ### Cursor (Manual)
78
+
79
+ Copy `rules/` to your project's `rules/`
80
+
81
+ ### OpenClaw (Manual)
82
+
83
+ Copy `skills/plan-flow/` to your project's `skills/plan-flow/`
84
+
85
+ ### Codex CLI (Manual)
86
+
87
+ 1. Copy `skills/plan-flow/` to your project's `.agents/skills/plan-flow/`
88
+ 2. Add the plan-flow section from `templates/shared/AGENTS.md.template` to your `AGENTS.md`
89
+
90
+ ## Commands
91
+
92
+ | Command | Description |
93
+ |---------|-------------|
94
+ | `/setup` | Analyze project and generate pattern files |
95
+ | `/discovery-plan` | Create discovery document for requirements |
96
+ | `/create-plan` | Create implementation plan with phases |
97
+ | `/execute-plan` | Execute plan phases with verification |
98
+ | `/create-contract` | Create integration contract from API docs |
99
+ | `/review-code` | Review local uncommitted changes |
100
+ | `/review-pr` | Review a Pull Request |
101
+ | `/write-tests` | Generate tests for coverage target |
102
+
103
+ ## Workflow
104
+
105
+ ```
106
+ 1. /setup -> Index project patterns (run once)
107
+ 2. /discovery-plan -> Gather requirements for a feature
108
+ 3. /create-plan -> Create structured implementation plan
109
+ 4. /execute-plan -> Execute the plan phase by phase
110
+ 5. /review-code -> Review changes before committing
111
+ ```
112
+
113
+ ## Complexity Scoring
114
+
115
+ Every plan phase has a complexity score (0-10):
116
+
117
+ | Score | Level | Description |
118
+ |-------|-------|-------------|
119
+ | 0-2 | Trivial | Simple, mechanical changes |
120
+ | 3-4 | Low | Straightforward implementation |
121
+ | 5-6 | Medium | Moderate complexity |
122
+ | 7-8 | High | Complex, multiple considerations |
123
+ | 9-10 | Very High | Significant complexity/risk |
124
+
125
+ ## Directory Structure
126
+
127
+ All artifacts are stored in `flow/`:
128
+
129
+ ```
130
+ flow/
131
+ ├── archive/ # Completed/abandoned plans
132
+ ├── contracts/ # Integration contracts
133
+ ├── discovery/ # Discovery documents
134
+ ├── plans/ # Active implementation plans
135
+ ├── references/ # Reference materials
136
+ ├── reviewed-code/ # Code review documents
137
+ └── reviewed-pr/ # PR review documents
138
+ ```
139
+
140
+ ## Requirements
141
+
142
+ - Node.js 18+
143
+ - `git` - For version control
144
+ - `gh` - GitHub CLI (for PR reviews)
145
+
146
+ ## Development
147
+
148
+ ```bash
149
+ # Install dependencies
150
+ npm install
151
+
152
+ # Build
153
+ npm run build
154
+
155
+ # Run init CLI
156
+ node dist/cli/index.js init --all
157
+
158
+ # Development mode
159
+ npm run dev
160
+
161
+ # Run tests
162
+ npm run test
163
+ ```
164
+
165
+ ## License
166
+
167
+ MIT
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Init Command - Installs plan-flow for selected platforms
3
+ */
4
+ import type { InitOptions } from '../types.js';
5
+ export declare function runInit(options: InitOptions): Promise<void>;
6
+ //# sourceMappingURL=init.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC;AAqHrE,wBAAsB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDjE"}
@@ -0,0 +1,139 @@
1
+ /**
2
+ * Init Command - Installs plan-flow for selected platforms
3
+ */
4
+ import { resolve } from 'node:path';
5
+ import * as log from '../utils/logger.js';
6
+ import { fileExists } from '../utils/files.js';
7
+ import { selectPlatforms } from '../utils/prompts.js';
8
+ import { initClaude } from '../handlers/claude.js';
9
+ import { initCursor } from '../handlers/cursor.js';
10
+ import { initOpenClaw } from '../handlers/openclaw.js';
11
+ import { initCodex } from '../handlers/codex.js';
12
+ import { initShared } from '../handlers/shared.js';
13
+ function printBanner() {
14
+ log.header('Plan-Flow Setup');
15
+ log.info('Structured AI-assisted development workflows for discovery, planning, execution, code reviews, and testing.');
16
+ }
17
+ function detectPlatforms(options) {
18
+ if (options.all) {
19
+ return ['claude', 'cursor', 'openclaw', 'codex'];
20
+ }
21
+ const platforms = [];
22
+ if (options.claude)
23
+ platforms.push('claude');
24
+ if (options.cursor)
25
+ platforms.push('cursor');
26
+ if (options.openclaw)
27
+ platforms.push('openclaw');
28
+ if (options.codex)
29
+ platforms.push('codex');
30
+ return platforms.length > 0 ? platforms : null;
31
+ }
32
+ function validateTarget(target) {
33
+ // Check for common project indicators
34
+ const indicators = [
35
+ 'package.json',
36
+ 'pyproject.toml',
37
+ 'Cargo.toml',
38
+ 'go.mod',
39
+ 'Gemfile',
40
+ '.git',
41
+ ];
42
+ const found = indicators.some((f) => fileExists(resolve(target, f)));
43
+ if (!found) {
44
+ log.warn('No project files detected in target directory. Are you in a project root?');
45
+ }
46
+ return true; // Allow proceeding regardless
47
+ }
48
+ function printSummary(results, target) {
49
+ log.header('Summary');
50
+ let totalCreated = 0;
51
+ let totalSkipped = 0;
52
+ let totalUpdated = 0;
53
+ for (const { platform, result } of results) {
54
+ const created = result.created.length;
55
+ const skipped = result.skipped.length;
56
+ const updated = result.updated.length;
57
+ totalCreated += created;
58
+ totalSkipped += skipped;
59
+ totalUpdated += updated;
60
+ if (created > 0) {
61
+ log.success(`${platform}: ${created} file(s) created`);
62
+ }
63
+ if (updated > 0) {
64
+ log.warn(`${platform}: ${updated} file(s) updated`);
65
+ }
66
+ if (skipped > 0) {
67
+ log.skip(`${platform}: ${skipped} file(s) skipped (already exist)`);
68
+ }
69
+ }
70
+ log.blank();
71
+ if (totalCreated + totalUpdated > 0) {
72
+ log.success(`Done! ${totalCreated} created, ${totalUpdated} updated, ${totalSkipped} skipped.`);
73
+ }
74
+ else if (totalSkipped > 0) {
75
+ log.info('All files already exist. Use --force to overwrite.');
76
+ }
77
+ }
78
+ function printNextSteps(platforms) {
79
+ log.header('Next Steps');
80
+ if (platforms.includes('claude')) {
81
+ log.info('Claude Code: Use /setup in Claude Code to index your project patterns');
82
+ }
83
+ if (platforms.includes('cursor')) {
84
+ log.info('Cursor: Rules are installed. Restart Cursor to activate.');
85
+ }
86
+ if (platforms.includes('openclaw')) {
87
+ log.info('OpenClaw: Skills are installed. Run clawhub to verify.');
88
+ }
89
+ if (platforms.includes('codex')) {
90
+ log.info('Codex CLI: Skills and AGENTS.md are installed. Use /setup in Codex to get started.');
91
+ }
92
+ log.blank();
93
+ }
94
+ export async function runInit(options) {
95
+ printBanner();
96
+ const target = resolve(options.target);
97
+ const force = options.force ?? false;
98
+ validateTarget(target);
99
+ // Detect platforms from flags or prompt interactively
100
+ let platforms = detectPlatforms(options);
101
+ if (!platforms) {
102
+ platforms = await selectPlatforms();
103
+ }
104
+ log.blank();
105
+ log.info(`Installing for: ${platforms.join(', ')}`);
106
+ log.info(`Target: ${target}`);
107
+ if (force) {
108
+ log.warn('Force mode: existing files will be overwritten');
109
+ }
110
+ const results = [];
111
+ // Run platform-specific handlers
112
+ for (const platform of platforms) {
113
+ log.header(`Setting up ${platform}...`);
114
+ let result;
115
+ switch (platform) {
116
+ case 'claude':
117
+ result = await initClaude(target, { force });
118
+ break;
119
+ case 'cursor':
120
+ result = await initCursor(target, { force });
121
+ break;
122
+ case 'openclaw':
123
+ result = await initOpenClaw(target, { force });
124
+ break;
125
+ case 'codex':
126
+ result = await initCodex(target, { force });
127
+ break;
128
+ }
129
+ results.push({ platform, result });
130
+ }
131
+ // Run shared handler (flow directories, config template)
132
+ log.header('Setting up shared resources...');
133
+ const sharedResult = await initShared(target, { force });
134
+ results.push({ platform: 'shared', result: sharedResult });
135
+ // Print summary and next steps
136
+ printSummary(results, target);
137
+ printNextSteps(platforms);
138
+ }
139
+ //# sourceMappingURL=init.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Claude Code handler
3
+ *
4
+ * Copies .claude/commands/ and .claude/rules/ to the user's project,
5
+ * and creates/updates CLAUDE.md with plan-flow instructions.
6
+ */
7
+ import type { CopyOptions, CopyResult } from '../types.js';
8
+ export declare function initClaude(target: string, options: CopyOptions): Promise<CopyResult>;
9
+ //# sourceMappingURL=claude.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/claude.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAoF3D,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAuDrB"}