@winton979/task-cli 1.3.3 → 1.4.1

package/README.md

@@ -1,20 +1,67 @@
 # task-cli
 
-Lightweight task workflow for AI-assisted development.
+A workflow methodology for AI coding agents.
+
+Task CLI separates requirement exploration from implementation, so AI agents decide whether complexity is justified **before** they start coding.
+
+**Explore** — Understand the problem. Assess whether additional complexity is warranted.
+**Implement** — Solve the accepted problem with the least necessary complexity.
+**Review** — Validate against the brief, not against new ideas introduced during coding.
 
 Designed for:
 
 * Claude Code
 * Codex CLI
-* Mature projects with frequent bug fixes and small feature iterations
+* Mature codebases with frequent bug fixes and small feature iterations
+
+> **Core principle**
+> Explore decides whether complexity is justified.
+> Implement decides how to satisfy the requirement with the least necessary complexity.
+
+---
+
+## Why task-cli?
+
+### Traditional AI Workflow
 
-Task CLI provides a lightweight alternative to heavyweight spec-driven workflows by combining:
+```text
+Requirement → Solution Design → Code → Review
+```
 
-* Requirement clarification (prefer Grill Me, fallback built in)
-* Brief generation
-* Implementation
-* Review
-* Decision logging
+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.
+
+### task-cli Workflow
+
+```text
+Requirement
+    ↓
+Explore  ──►  Understand + Challenge
+    ↓
+Complexity Assessment  ──►  Is added complexity justified?
+    ↓
+Brief
+    ↓
+Implement  ──►  Simplest acceptable solution
+    ↓
+Review  ──►  Validate against the brief
+```
+
+Exploration and implementation are intentionally separated.
+
+---
+
+## Core Philosophy
+
+Most AI coding agents fail because they mix exploration and implementation in the same conversation. Task CLI intentionally separates them.
+
+| Stage                     | Question                                   |
+| ------------------------- | ------------------------------------------ |
+| Explore                   | What problem are we solving?               |
+| Complexity Assessment     | Is additional complexity justified?        |
+| Implement                 | What is the simplest acceptable solution?  |
+| Review                    | Did we satisfy the brief?                  |
+
+This keeps AI agents from over-designing solutions during requirement discovery, and keeps implementation focused on the accepted scope.
 
 ---
 
@@ -30,9 +77,9 @@ Initialize the workflow in your project:
 task init
 ```
 
----
+After initialization, Task CLI creates the `.ai/` workspace and installs workflow skills into both `.claude/skills/` and `.codex/skills/`.
 
-## Prerequisites
+### Prerequisites
 
 Task CLI can use a Grill Me compatible skill for requirement and bug exploration.
 
@@ -42,32 +89,11 @@ Recommended:
 npx add-skill PJ-SBN-593844/skill-grill-me
 ```
 
-Compatible Grill Me implementations may also work.
-
 If no Grill Me compatible skill is installed, `task-fast`, `task-explore`, and `bug-explore` fall back to built-in clarification prompts.
 
-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.
-
----
-
-## Usage
-
-```bash
-task init
-task refresh
-task doctor
-task --help
-```
-
-After initialization, Task CLI creates the `.ai/` workspace and installs workflow skills into both `.claude/skills/` and `.codex/skills/`.
-
-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.
-
-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.
-
 ---
 
-## Recommended Workflow
+## Quick Start
 
 ### Small Feature / Enhancement
 
@@ -76,160 +102,157 @@ Use `task doctor` to check whether the required directories exist, whether manag
     ↓
 clarify + brief + implement + validate
     ↓
-/task-review
-    or
-/task-cancel
+/task-review   or   /task-cancel
 ```
 
 ### Larger Requirement
 
 ```text
-/task-explore
-    ↓
-TASK_READY
-    ↓
-/task-implement
-    ↓
-/task-review
-    or
-/task-cancel
+/task-explore  →  TASK_READY  →  /task-implement  →  /task-review  or  /task-cancel
 ```
 
 ### Bug Fix
 
 ```text
-/bug-explore
-    ↓
-BUG_READY
-    ↓
-/bug-fix
-    ↓
-/bug-review
-    or
-/bug-cancel
+/bug-explore  →  BUG_READY  →  /bug-fix  →  /bug-review  or  /bug-cancel
+```
+
+### CLI Commands
+
+```bash
+task init       # initialize workspace and install skills
+task refresh    # reinstall managed skills without touching .ai content
+task doctor     # check workspace state, skill versions, gitignore rules
+task --help
 ```
 
 ---
 
-## Available Skills
+## Example: Preventing Over-Engineering
+
+**Requirement:** *"Add CSV export."*
+
+### Without task-cli
+
+Common AI behavior — jumps straight into designing:
 
-### Task Workflow
+* `ExportService`
+* `ExportRepository`
+* `CSVAdapter`
+* `Factory`
+* new dependency
 
-* task-fast
-* task-explore
-* task-implement
-* task-review
-* task-cancel
+**Files changed:** 7
+**New abstractions:** 4
 
-### Bug Workflow
+### With task-cli
 
-* bug-explore
-* bug-fix
-* bug-review
-* bug-cancel
+Exploration runs first. Complexity Assessment determines that a new project-wide capability is not justified.
 
-### Other
+Implementation:
 
-* decision-log
-* decision-sweep-weekly
+* reuse existing export path
+* modify two files
+* no new dependency
+
+**Files changed:** 2
+**New abstractions:** 0
+
+The workflow encourages the simplest acceptable implementation instead of the most elaborate one.
 
 ---
 
-## Directory Structure
+## Available Skills
 
-```text
-.ai/
-├── tasks/
-│   ├── active/
-│   └── archive/
-│
-├── bugs/
-│   ├── active/
-│   └── archive/
-│
-├── decisions/
-│   └── decisions.md
-│
-├── .claude/skills/
-└── .codex/skills/
-```
+**Task Workflow**
+
+* `task-fast`
+* `task-explore`
+* `task-implement`
+* `task-review`
+* `task-cancel`
+
+**Bug Workflow**
+
+* `bug-explore`
+* `bug-fix`
+* `bug-review`
+* `bug-cancel`
+
+**Decision Logging**
+
+* `decision-log`
+* `decision-sweep-weekly`
 
 ---
 
-## Weekly Decision Sweep
+## Decision Logging
+
+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.
+
+The decisions file is intentionally narrow. It holds durable project invariants and reusable constraints, not a running transcript of every local implementation choice.
+
+### Weekly Decision Sweep
 
-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):
+Calling `/decision-log` after every task is easy to forget. As a lower-friction alternative, run once per week (Friday is a natural fit):
 
 ```
 /decision-sweep-weekly
 ```
 
-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.
+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.
 
-Use `decision-log` for in-the-moment recording and `decision-sweep-weekly` for periodic cleanup. Either alone is enough; using both is fine.
+Use `decision-log` for in-the-moment recording and `decision-sweep-weekly` for periodic cleanup. Either alone is enough.
 
-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.
-
-## Philosophy
+---
 
-Task CLI is intentionally lightweight.
+## Directory Structure
 
-Instead of maintaining large specifications, it focuses on:
+```text
+.ai/
+├── tasks/
+│   ├── active/
+│   └── archive/
+├── bugs/
+│   ├── active/
+│   └── archive/
+└── decisions/
+    └── decisions.md
 
-1. Clarifying requirements before coding
-2. Capturing execution context in concise briefs
-3. Executing with validation while archiving automatically in the background
-4. Reviewing work against acceptance criteria
-5. Keeping a lightweight decision history
+.claude/skills/
+.codex/skills/
+```
 
-The goal is to improve quality without slowing down iteration speed.
+The `archive/` directories are internal storage, not user-facing steps.
 
-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.
+---
 
 ## Compared with OpenSpec-Style Workflows
 
-Task CLI is designed as a lightweight alternative to heavier spec-driven systems such as OpenSpec.
+Detailed specification workflows such as OpenSpec can improve alignment, traceability, and consistency for large initiatives, cross-team programs, and process-heavy environments.
 
-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.
+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.
 
-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.
+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.
 
-Task CLI takes a narrower and more pragmatic approach:
-
-* clarify the requirement
-* capture only the minimum useful brief
-* execute against acceptance criteria
-* review the result
-* keep a lightweight decision trail
-
-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.
+---
 
 ## Strengths and Tradeoffs
 
-Task CLI is optimized for execution speed and sustained adoption rather than full process coverage.
-
-Strengths:
+**Strengths**
 
 * much lower process overhead for bugs, small features, and short iterations
-* easier to adopt in mature codebases where engineers already know the product context
+* easier to adopt in mature codebases where engineers already know the product
 * encourages real usage because the workflow is short enough to sustain
 * keeps enough structure to improve clarity without forcing large documents
 
-Tradeoffs:
+**Tradeoffs**
 
 * less suitable for large cross-team initiatives that need formal design traceability
-* relies more on engineer judgment and review quality than a full specification process
+* relies more on engineer judgment and review quality than a full spec process
 * stores less long-form historical context than a dedicated spec repository
 
-## Recommended Workflow Model
-
-Task CLI keeps the user-facing flow short:
-
-* `task-fast`
-* `task-explore -> task-implement -> task-review` or `task-cancel`
-* `bug-explore -> bug-fix -> bug-review` or `bug-cancel`
-
-The `archive/` directories remain as internal storage. They are not separate user steps in the recommended workflow.
+---
 
 ## Upgrading Existing Projects
 
@@ -242,16 +265,12 @@ task refresh
 This will:
 
 * keep `.ai/tasks`, `.ai/bugs`, and `.ai/decisions`
-* 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`
+* 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`
 * reinstall the latest versions of those skills
 
-This avoids touching unrelated custom skills in the same project.
-
-Before refreshing, you can inspect the current setup with:
+Unrelated custom skills in the same project are left untouched. Inspect the current setup first with `task doctor`.
 
-```bash
-task doctor
-```
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winton979/task-cli",
-  "version": "1.3.3",
+  "version": "1.4.1",
   "description": "Lightweight task workflow CLI for AI-assisted development",
   "license": "MIT",
   "repository": {
@@ -13,7 +13,7 @@
   },
   "type": "module",
   "bin": {
-    "task": "./bin/task.js"
+    "task": "bin/task.js"
   },
   "files": [
     "bin",

package/src/init.js

@@ -30,6 +30,20 @@ Use it narrowly:
 * treat the file as a source of durable project invariants, not as a second specification
 * if relevant decisions exist, summarize them briefly in Context or Constraints instead of copying them verbatim`;
 
+const COMPLEXITY_ASSESSMENT_GUIDANCE = `Complexity Assessment
+
+Before finalizing the brief, assess whether the requirement justifies added complexity.
+
+* Treat added complexity as a cost that must be justified by the requirement.
+* Flag any indication that the requirement may require:
+
+  - new project-wide capability
+  - new dependency
+  - cross-cutting architectural change
+
+  as a Risk, not a plan.
+* When complexity appears justified, do not design the solution here. Simply record that additional implementation effort is likely required.`;
+
 const SKILLS = {
   'task-fast': {
     name: 'task-fast',
@@ -50,21 +64,24 @@ Workflow
 2. If no Grill Me compatible skill is available, clarify the requirement yourself with focused questions just far enough to remove ambiguity.
 3. Read the project code and conventions needed to avoid obvious conflicts.
 4. Read .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain this task.
-5. Create a concise task brief and save it to:
+5. Before finalizing the brief, perform a Complexity Assessment.
+6. Create a concise task brief and save it to:
 
 .ai/tasks/active/YYYY-MM-DD-task-name.md
 
-6. Show the brief before coding.
-7. If the user does not object, implement immediately.
-8. Verify the result against the acceptance criteria.
-9. Archive the brief automatically by moving it to:
+7. Show the brief before coding.
+8. If the user does not object, implement immediately.
+9. Verify the result against the acceptance criteria.
+10. Archive the brief automatically by moving it to:
 
 .ai/tasks/archive/YYYY-MM-DD-task-name.md
 
-10. Summarize the outcome and any follow-up risks.
+11. Summarize the outcome and any follow-up risks.
 
 ${DECISIONS_READ_GUIDANCE}
 
+${COMPLEXITY_ASSESSMENT_GUIDANCE}
+
 Task Brief Format
 
 # Goal
@@ -77,7 +94,11 @@ Relevant project background.
 
 # Constraints
 
-Business or technical limitations.
+Business or technical limitations. When materially supported by the exploration, record complexity expectations such as:
+
+- A new dependency does not currently appear necessary.
+- Existing project boundaries likely remain sufficient.
+- Cross-cutting changes do not currently appear justified.
 
 # Risks
 
@@ -129,6 +150,8 @@ Workflow
 
 ${DECISIONS_READ_GUIDANCE}
 
+${COMPLEXITY_ASSESSMENT_GUIDANCE}
+
 Task Brief Format
 
 # Goal
@@ -141,7 +164,11 @@ Relevant project background.
 
 # Constraints
 
-Business or technical limitations.
+Business or technical limitations. When materially supported by the exploration, record complexity expectations such as:
+
+- A new dependency does not currently appear necessary.
+- Existing project boundaries likely remain sufficient.
+- Cross-cutting changes do not currently appear justified.
 
 # Risks
 
@@ -156,6 +183,7 @@ Requirements
 * Maximum 500 words
 * No code
 * No architecture design
+* Stay implementation-agnostic; describe constraints, not solutions
 * Only information required for execution
 
 When complete output:
@@ -188,6 +216,14 @@ Rules
 7. Validate the result before stopping.
 8. If the work is complete, archive the brief automatically by moving it to .ai/tasks/archive/.
 
+When making implementation decisions
+
+* Reuse existing helpers, patterns, and APIs before introducing new ones.
+* Before introducing a new abstraction, confirm that extending existing code would not satisfy the requirement.
+* Choose the simplest implementation that satisfies the acceptance criteria.
+* Introduce a new dependency or abstraction only when no in-project option exists, and state why.
+* Do not optimize for hypothetical future reuse.
+
 Output
 
 ## Plan
@@ -375,6 +411,12 @@ Rules
 7. Validate the fix before stopping.
 8. If the bug is fixed, archive the brief automatically by moving it to .ai/bugs/archive/.
 
+When making implementation decisions
+
+* Extend existing behavior before introducing new abstractions.
+* Prefer the smallest behavioral correction that resolves the confirmed root cause.
+* Introduce new dependencies only when existing project capabilities cannot reasonably solve the problem.
+
 Output
 
 ## Root Cause