@winton979/task-cli 1.4.0 → 1.4.1

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 (2) hide show
  1. package/README.md +154 -135
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,20 +1,67 @@
1
1
  # task-cli
2
2
 
3
- Lightweight task workflow for AI-assisted development.
3
+ A workflow methodology for AI coding agents.
4
+
5
+ Task CLI separates requirement exploration from implementation, so AI agents decide whether complexity is justified **before** they start coding.
6
+
7
+ **Explore** — Understand the problem. Assess whether additional complexity is warranted.
8
+ **Implement** — Solve the accepted problem with the least necessary complexity.
9
+ **Review** — Validate against the brief, not against new ideas introduced during coding.
4
10
 
5
11
  Designed for:
6
12
 
7
13
  * Claude Code
8
14
  * Codex CLI
9
- * Mature projects with frequent bug fixes and small feature iterations
15
+ * Mature codebases with frequent bug fixes and small feature iterations
16
+
17
+ > **Core principle**
18
+ > Explore decides whether complexity is justified.
19
+ > Implement decides how to satisfy the requirement with the least necessary complexity.
20
+
21
+ ---
22
+
23
+ ## Why task-cli?
24
+
25
+ ### Traditional AI Workflow
10
26
 
11
- Task CLI provides a lightweight alternative to heavyweight spec-driven workflows by combining:
27
+ ```text
28
+ Requirement → Solution Design → Code → Review
29
+ ```
12
30
 
13
- * Requirement clarification (prefer Grill Me, fallback built in)
14
- * Brief generation
15
- * Implementation
16
- * Review
17
- * Decision logging
31
+ The AI often starts designing before the requirement is fully clarified. Complexity gets introduced during coding, and review happens against whatever the AI produced rather than against the original intent.
32
+
33
+ ### task-cli Workflow
34
+
35
+ ```text
36
+ Requirement
37
+ ↓
38
+ Explore ──► Understand + Challenge
39
+ ↓
40
+ Complexity Assessment ──► Is added complexity justified?
41
+ ↓
42
+ Brief
43
+ ↓
44
+ Implement ──► Simplest acceptable solution
45
+ ↓
46
+ Review ──► Validate against the brief
47
+ ```
48
+
49
+ Exploration and implementation are intentionally separated.
50
+
51
+ ---
52
+
53
+ ## Core Philosophy
54
+
55
+ Most AI coding agents fail because they mix exploration and implementation in the same conversation. Task CLI intentionally separates them.
56
+
57
+ | Stage | Question |
58
+ | ------------------------- | ------------------------------------------ |
59
+ | Explore | What problem are we solving? |
60
+ | Complexity Assessment | Is additional complexity justified? |
61
+ | Implement | What is the simplest acceptable solution? |
62
+ | Review | Did we satisfy the brief? |
63
+
64
+ This keeps AI agents from over-designing solutions during requirement discovery, and keeps implementation focused on the accepted scope.
18
65
 
19
66
  ---
20
67
 
@@ -30,9 +77,9 @@ Initialize the workflow in your project:
30
77
  task init
31
78
  ```
32
79
 
33
- ---
80
+ After initialization, Task CLI creates the `.ai/` workspace and installs workflow skills into both `.claude/skills/` and `.codex/skills/`.
34
81
 
35
- ## Prerequisites
82
+ ### Prerequisites
36
83
 
37
84
  Task CLI can use a Grill Me compatible skill for requirement and bug exploration.
38
85
 
@@ -42,32 +89,11 @@ Recommended:
42
89
  npx add-skill PJ-SBN-593844/skill-grill-me
43
90
  ```
44
91
 
45
- Compatible Grill Me implementations may also work.
46
-
47
92
  If no Grill Me compatible skill is installed, `task-fast`, `task-explore`, and `bug-explore` fall back to built-in clarification prompts.
48
93
 
49
- When `.ai/decisions/decisions.md` contains real entries, those skills should inspect it before finalizing a brief and pull in only the decisions that materially constrain the current task or bug.
50
-
51
- ---
52
-
53
- ## Usage
54
-
55
- ```bash
56
- task init
57
- task refresh
58
- task doctor
59
- task --help
60
- ```
61
-
62
- After initialization, Task CLI creates the `.ai/` workspace and installs workflow skills into both `.claude/skills/` and `.codex/skills/`.
63
-
64
- Use `task refresh` in existing projects to remove and reinstall only the workflow skills managed by task-cli. It does not delete your `.ai` briefs, internal archives, or decision log.
65
-
66
- Use `task doctor` to check whether the required directories exist, whether managed skills are missing or outdated, whether a local Grill Me companion was detected, and whether the `.gitignore` rules are present.
67
-
68
94
  ---
69
95
 
70
- ## Recommended Workflow
96
+ ## Quick Start
71
97
 
72
98
  ### Small Feature / Enhancement
73
99
 
@@ -76,160 +102,157 @@ Use `task doctor` to check whether the required directories exist, whether manag
76
102
  ↓
77
103
  clarify + brief + implement + validate
78
104
  ↓
79
- /task-review
80
- or
81
- /task-cancel
105
+ /task-review or /task-cancel
82
106
  ```
83
107
 
84
108
  ### Larger Requirement
85
109
 
86
110
  ```text
87
- /task-explore
88
- ↓
89
- TASK_READY
90
- ↓
91
- /task-implement
92
- ↓
93
- /task-review
94
- or
95
- /task-cancel
111
+ /task-explore → TASK_READY → /task-implement → /task-review or /task-cancel
96
112
  ```
97
113
 
98
114
  ### Bug Fix
99
115
 
100
116
  ```text
101
- /bug-explore
102
- ↓
103
- BUG_READY
104
- ↓
105
- /bug-fix
106
- ↓
107
- /bug-review
108
- or
109
- /bug-cancel
117
+ /bug-explore → BUG_READY → /bug-fix → /bug-review or /bug-cancel
118
+ ```
119
+
120
+ ### CLI Commands
121
+
122
+ ```bash
123
+ task init # initialize workspace and install skills
124
+ task refresh # reinstall managed skills without touching .ai content
125
+ task doctor # check workspace state, skill versions, gitignore rules
126
+ task --help
110
127
  ```
111
128
 
112
129
  ---
113
130
 
114
- ## Available Skills
131
+ ## Example: Preventing Over-Engineering
132
+
133
+ **Requirement:** *"Add CSV export."*
134
+
135
+ ### Without task-cli
136
+
137
+ Common AI behavior — jumps straight into designing:
115
138
 
116
- ### Task Workflow
139
+ * `ExportService`
140
+ * `ExportRepository`
141
+ * `CSVAdapter`
142
+ * `Factory`
143
+ * new dependency
117
144
 
118
- * task-fast
119
- * task-explore
120
- * task-implement
121
- * task-review
122
- * task-cancel
145
+ **Files changed:** 7
146
+ **New abstractions:** 4
123
147
 
124
- ### Bug Workflow
148
+ ### With task-cli
125
149
 
126
- * bug-explore
127
- * bug-fix
128
- * bug-review
129
- * bug-cancel
150
+ Exploration runs first. Complexity Assessment determines that a new project-wide capability is not justified.
130
151
 
131
- ### Other
152
+ Implementation:
132
153
 
133
- * decision-log
134
- * decision-sweep-weekly
154
+ * reuse existing export path
155
+ * modify two files
156
+ * no new dependency
157
+
158
+ **Files changed:** 2
159
+ **New abstractions:** 0
160
+
161
+ The workflow encourages the simplest acceptable implementation instead of the most elaborate one.
135
162
 
136
163
  ---
137
164
 
138
- ## Directory Structure
165
+ ## Available Skills
139
166
 
140
- ```text
141
- .ai/
142
- ├── tasks/
143
- │ ├── active/
144
- │ └── archive/
145
- │
146
- ├── bugs/
147
- │ ├── active/
148
- │ └── archive/
149
- │
150
- ├── decisions/
151
- │ └── decisions.md
152
- │
153
- ├── .claude/skills/
154
- └── .codex/skills/
155
- ```
167
+ **Task Workflow**
168
+
169
+ * `task-fast`
170
+ * `task-explore`
171
+ * `task-implement`
172
+ * `task-review`
173
+ * `task-cancel`
174
+
175
+ **Bug Workflow**
176
+
177
+ * `bug-explore`
178
+ * `bug-fix`
179
+ * `bug-review`
180
+ * `bug-cancel`
181
+
182
+ **Decision Logging**
183
+
184
+ * `decision-log`
185
+ * `decision-sweep-weekly`
156
186
 
157
187
  ---
158
188
 
159
- ## Weekly Decision Sweep
189
+ ## Decision Logging
190
+
191
+ Task CLI keeps a lightweight decision trail in `.ai/decisions/decisions.md`. Explore and fast-path skills should consult it before finalizing a brief, and pull in only the decisions that materially constrain the current task or bug.
192
+
193
+ The decisions file is intentionally narrow. It holds durable project invariants and reusable constraints, not a running transcript of every local implementation choice.
194
+
195
+ ### Weekly Decision Sweep
160
196
 
161
- Calling `/decision-log` after every task is easy to forget. As a lower-friction alternative, run `decision-sweep-weekly` once per week (Friday is a natural fit):
197
+ Calling `/decision-log` after every task is easy to forget. As a lower-friction alternative, run once per week (Friday is a natural fit):
162
198
 
163
199
  ```
164
200
  /decision-sweep-weekly
165
201
  ```
166
202
 
167
- The skill scans archived task and bug briefs from the past 7 days, judges which ones contain a decision worth keeping (cross-task impact, rejected alternatives, counter-intuitive choices, externally driven calls, or instructive cancellations), drafts the entries, and waits for confirmation before writing anything to `.ai/decisions/decisions.md`. When a draft overlaps with or updates an existing decision, it should present the old and new versions together and ask whether to append, revise, merge, supersede, or skip.
203
+ The skill scans archived task and bug briefs from the past 7 days, judges which ones contain a decision worth keeping (cross-task impact, rejected alternatives, counter-intuitive choices, externally driven calls, or instructive cancellations), drafts the entries, and waits for confirmation before writing to `.ai/decisions/decisions.md`. When a draft overlaps with an existing decision, it presents both versions and asks whether to append, revise, merge, supersede, or skip.
168
204
 
169
- Use `decision-log` for in-the-moment recording and `decision-sweep-weekly` for periodic cleanup. Either alone is enough; using both is fine.
205
+ Use `decision-log` for in-the-moment recording and `decision-sweep-weekly` for periodic cleanup. Either alone is enough.
170
206
 
171
- The decisions file is intentionally narrow. It is meant to hold durable project invariants and reusable constraints, not a running transcript of every local implementation choice. The default write mode should still be append, but revisions to existing entries are reasonable when explicitly reviewed and confirmed by the user.
172
-
173
- ## Philosophy
207
+ ---
174
208
 
175
- Task CLI is intentionally lightweight.
209
+ ## Directory Structure
176
210
 
177
- Instead of maintaining large specifications, it focuses on:
211
+ ```text
212
+ .ai/
213
+ ├── tasks/
214
+ │ ├── active/
215
+ │ └── archive/
216
+ ├── bugs/
217
+ │ ├── active/
218
+ │ └── archive/
219
+ └── decisions/
220
+ └── decisions.md
178
221
 
179
- 1. Clarifying requirements before coding
180
- 2. Capturing execution context in concise briefs
181
- 3. Executing with validation while archiving automatically in the background
182
- 4. Reviewing work against acceptance criteria
183
- 5. Keeping a lightweight decision history
222
+ .claude/skills/
223
+ .codex/skills/
224
+ ```
184
225
 
185
- The goal is to improve quality without slowing down iteration speed.
226
+ The `archive/` directories are internal storage, not user-facing steps.
186
227
 
187
- That decision history is meant to be selectively reusable. Explore and fast-path skills should consult it to avoid violating existing project decisions, but only the parts that materially constrain the current work belong in the new brief.
228
+ ---
188
229
 
189
230
  ## Compared with OpenSpec-Style Workflows
190
231
 
191
- Task CLI is designed as a lightweight alternative to heavier spec-driven systems such as OpenSpec.
232
+ Detailed specification workflows such as OpenSpec can improve alignment, traceability, and consistency for large initiatives, cross-team programs, and process-heavy environments.
192
233
 
193
- Detailed specification workflows can improve alignment, traceability, and consistency. They are often the right choice for large initiatives, cross-team programs, and environments with strong process requirements.
234
+ The difficulty is that the same level of ceremony does not fit day-to-day engineering. For frequent bug fixes, small features, and fast iteration, the process becomes heavier than the change itself — maintenance overhead grows, documentation quality drifts, and teams gradually stop using the workflow as intended.
194
235
 
195
- The difficulty is that the same level of ceremony does not always fit day-to-day engineering work. For frequent bug fixes, small features, and fast iteration, the process can become heavier than the change itself. When that happens, maintenance overhead increases, documentation quality starts to drift, and teams gradually stop using the workflow as originally intended.
236
+ Task CLI takes a narrower approach: clarify the requirement, capture only the minimum useful brief, execute against acceptance criteria, review the result, and keep a lightweight decision trail. The goal is a workflow people will actually keep using.
196
237
 
197
- Task CLI takes a narrower and more pragmatic approach:
198
-
199
- * clarify the requirement
200
- * capture only the minimum useful brief
201
- * execute against acceptance criteria
202
- * review the result
203
- * keep a lightweight decision trail
204
-
205
- The goal is not to replace specification systems in every context. It is to provide a workflow that people will actually keep using during day-to-day engineering work.
238
+ ---
206
239
 
207
240
  ## Strengths and Tradeoffs
208
241
 
209
- Task CLI is optimized for execution speed and sustained adoption rather than full process coverage.
210
-
211
- Strengths:
242
+ **Strengths**
212
243
 
213
244
  * much lower process overhead for bugs, small features, and short iterations
214
- * easier to adopt in mature codebases where engineers already know the product context
245
+ * easier to adopt in mature codebases where engineers already know the product
215
246
  * encourages real usage because the workflow is short enough to sustain
216
247
  * keeps enough structure to improve clarity without forcing large documents
217
248
 
218
- Tradeoffs:
249
+ **Tradeoffs**
219
250
 
220
251
  * less suitable for large cross-team initiatives that need formal design traceability
221
- * relies more on engineer judgment and review quality than a full specification process
252
+ * relies more on engineer judgment and review quality than a full spec process
222
253
  * stores less long-form historical context than a dedicated spec repository
223
254
 
224
- ## Recommended Workflow Model
225
-
226
- Task CLI keeps the user-facing flow short:
227
-
228
- * `task-fast`
229
- * `task-explore -> task-implement -> task-review` or `task-cancel`
230
- * `bug-explore -> bug-fix -> bug-review` or `bug-cancel`
231
-
232
- The `archive/` directories remain as internal storage. They are not separate user steps in the recommended workflow.
255
+ ---
233
256
 
234
257
  ## Upgrading Existing Projects
235
258
 
@@ -242,16 +265,12 @@ task refresh
242
265
  This will:
243
266
 
244
267
  * keep `.ai/tasks`, `.ai/bugs`, and `.ai/decisions`
245
- * remove only these managed skills from `.claude/skills/` and `.codex/skills/`: `task-fast`, `task-explore`, `task-implement`, `task-review`, `task-cancel`, `bug-explore`, `bug-fix`, `bug-review`, `bug-cancel`, `decision-log`, `decision-sweep-weekly`
268
+ * remove only managed skills from `.claude/skills/` and `.codex/skills/`: `task-fast`, `task-explore`, `task-implement`, `task-review`, `task-cancel`, `bug-explore`, `bug-fix`, `bug-review`, `bug-cancel`, `decision-log`, `decision-sweep-weekly`
246
269
  * reinstall the latest versions of those skills
247
270
 
248
- This avoids touching unrelated custom skills in the same project.
249
-
250
- Before refreshing, you can inspect the current setup with:
271
+ Unrelated custom skills in the same project are left untouched. Inspect the current setup first with `task doctor`.
251
272
 
252
- ```bash
253
- task doctor
254
- ```
273
+ ---
255
274
 
256
275
  ## License
257
276
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@winton979/task-cli",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "Lightweight task workflow CLI for AI-assisted development",
5
5
  "license": "MIT",
6
6
  "repository": {