@winton979/task-cli 1.4.0 → 1.4.2

package/README.md

@@ -1,261 +1,317 @@
-# task-cli
-
-Lightweight task workflow for AI-assisted development.
-
-Designed for:
-
-* Claude Code
-* Codex CLI
-* Mature projects with frequent bug fixes and small feature iterations
-
-Task CLI provides a lightweight alternative to heavyweight spec-driven workflows by combining:
-
-* Requirement clarification (prefer Grill Me, fallback built in)
-* Brief generation
-* Implementation
-* Review
-* Decision logging
-
----
-
-## Installation
-
-```bash
-npm install -g @winton979/task-cli
-```
-
-Initialize the workflow in your project:
-
-```bash
-task init
-```
-
----
-
-## Prerequisites
-
-Task CLI can use a Grill Me compatible skill for requirement and bug exploration.
-
-Recommended:
-
-```bash
-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
-
-### Small Feature / Enhancement
-
-```text
-/task-fast
-    ↓
-clarify + brief + implement + validate
-    ↓
-/task-review
-    or
-/task-cancel
-```
-
-### Larger Requirement
-
-```text
-/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
-```
-
----
-
-## Available Skills
-
-### Task Workflow
-
-* task-fast
-* task-explore
-* task-implement
-* task-review
-* task-cancel
-
-### Bug Workflow
-
-* bug-explore
-* bug-fix
-* bug-review
-* bug-cancel
-
-### Other
-
-* decision-log
-* decision-sweep-weekly
-
----
-
-## Directory Structure
-
-```text
-.ai/
-├── tasks/
-│   ├── active/
-│   └── archive/
-│
-├── bugs/
-│   ├── active/
-│   └── archive/
-│
-├── decisions/
-│   └── decisions.md
-│
-├── .claude/skills/
-└── .codex/skills/
-```
-
----
-
-## 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):
-
-```
-/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.
-
-Use `decision-log` for in-the-moment recording and `decision-sweep-weekly` for periodic cleanup. Either alone is enough; using both is fine.
-
-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.
-
-Instead of maintaining large specifications, it focuses on:
-
-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
-
-The goal is to improve quality without slowing down iteration speed.
-
-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 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 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 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:
-
-* much lower process overhead for bugs, small features, and short iterations
-* easier to adopt in mature codebases where engineers already know the product context
-* encourages real usage because the workflow is short enough to sustain
-* keeps enough structure to improve clarity without forcing large documents
-
-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
-* 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
-
-If a project was initialized with an older version of task-cli, run:
-
-```bash
-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`
-* 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:
-
-```bash
-task doctor
-```
-
-## License
-
-MIT
-
-> Task CLI does not install Grill Me automatically.
-> Users remain free to choose any Grill Me compatible implementation, and the explore skills fall back to built-in clarification if none is installed.
+# task-cli
+
+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 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
+
+```text
+Requirement → Solution Design → Code → Review
+```
+
+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.
+
+---
+
+## Installation
+
+```bash
+npm install -g @winton979/task-cli
+```
+
+Initialize the workflow in your project:
+
+```bash
+task init
+```
+
+After initialization, Task CLI creates the `.ai/` workspace and installs workflow skills into both `.claude/skills/` and `.codex/skills/`.
+
+### Prerequisites
+
+Task CLI can use a Grill Me compatible skill for requirement and bug exploration.
+
+Recommended:
+
+```bash
+npx add-skill PJ-SBN-593844/skill-grill-me
+```
+
+If no Grill Me compatible skill is installed, `task-fast`, `task-explore`, and `bug-explore` fall back to built-in clarification prompts.
+
+---
+
+## Quick Start
+
+### Small Feature / Enhancement
+
+```text
+/task-fast
+    ↓
+clarify + brief + implement + validate
+    ↓
+/task-review   or   /task-cancel
+```
+
+### Larger Requirement
+
+```text
+/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
+```
+
+### 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
+```
+
+---
+
+## Example: Preventing Over-Engineering
+
+**Requirement:** *"Add CSV export."*
+
+### Without task-cli
+
+Common AI behavior — jumps straight into designing:
+
+* `ExportService`
+* `ExportRepository`
+* `CSVAdapter`
+* `Factory`
+* new dependency
+
+**Files changed:** 7
+**New abstractions:** 4
+
+### With task-cli
+
+Exploration runs first. Complexity Assessment determines that a new project-wide capability is not justified.
+
+Implementation:
+
+* 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.
+
+---
+
+## Available 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`
+* `decision-curate`
+
+---
+
+## 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.
+
+The default bias should be to skip writing. A decision should be logged only when leaving it undocumented would make a future task or bug exploration materially more likely to choose the wrong path.
+
+### Weekly Decision Sweep
+
+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 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.
+
+### Decision Curation
+
+When the decisions file starts collecting stale, duplicate, or low-value entries, run:
+
+```
+/decision-curate
+```
+
+The skill audits the current decisions file, classifies entries as keep, tighten, merge, or remove, and waits for explicit confirmation before changing anything. Its job is to keep the file short enough that explore can still read it cheaply.
+
+Use `decision-log` for in-the-moment recording, `decision-sweep-weekly` for harvesting new durable constraints, and `decision-curate` for pruning old ones.
+
+---
+
+## Operational Boundaries
+
+Task CLI is most effective when `active/` stays personal, local, and small. In that operating model, the main scaling risk is not total bug or task count, but whether the long-lived context remains high-signal.
+
+Recommended working limits:
+
+* Per developer, keep local `active` briefs at `1-3`. At `4-5`, the agent starts paying more context-switching cost.
+* Total `archive` size can grow into the hundreds without becoming a primary problem, because normal flows do not re-read all historical briefs.
+* Keep `.ai/decisions/decisions.md` lean. Around `15-30` durable entries is comfortable. Once it grows past `30`, run `/decision-curate` regularly.
+* Weekly completed brief volume around `10-20` is still light for `decision-sweep-weekly`. Past `20-40`, expect more review effort to separate durable constraints from one-off noise.
+
+Red flags that the workflow is becoming an agent burden:
+
+* explore spends noticeable time filtering stale or irrelevant decisions
+* many archived briefs are too small or repetitive to justify their own long-term trace
+* weekly decision sweep produces mostly skip-worthy items
+* one developer keeps more than a few local active briefs open at once
+
+When those signals appear, the right response is usually to reduce noise in decisions and brief granularity, not to add more process.
+
+---
+
+## Directory Structure
+
+```text
+.ai/
+├── tasks/
+│   ├── active/
+│   └── archive/
+├── bugs/
+│   ├── active/
+│   └── archive/
+└── decisions/
+    └── decisions.md
+
+.claude/skills/
+.codex/skills/
+```
+
+The `archive/` directories are internal storage, not user-facing steps.
+
+---
+
+## Compared with OpenSpec-Style Workflows
+
+Detailed specification workflows such as OpenSpec can improve alignment, traceability, and consistency for large initiatives, cross-team programs, and process-heavy environments.
+
+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.
+
+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.
+
+---
+
+## Strengths and Tradeoffs
+
+**Strengths**
+
+* much lower process overhead for bugs, small features, and short iterations
+* 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**
+
+* less suitable for large cross-team initiatives that need formal design traceability
+* relies more on engineer judgment and review quality than a full spec process
+* stores less long-form historical context than a dedicated spec repository
+
+---
+
+## Upgrading Existing Projects
+
+If a project was initialized with an older version of task-cli, run:
+
+```bash
+task refresh
+```
+
+This will:
+
+* keep `.ai/tasks`, `.ai/bugs`, and `.ai/decisions`
+* 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`, `decision-curate`
+* reinstall the latest versions of those skills
+
+Unrelated custom skills in the same project are left untouched. Inspect the current setup first with `task doctor`.
+
+---
+
+something else:
+> Task CLI does not install Grill Me automatically.
+> Users remain free to choose any Grill Me compatible implementation, and the explore skills fall back to built-in clarification if none is installed.
+
+## License
+
+MIT
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winton979/task-cli",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Lightweight task workflow CLI for AI-assisted development",
   "license": "MIT",
   "repository": {

package/src/init.js

@@ -519,7 +519,26 @@ Purpose
 
 Record important implementation decisions.
 
-Only record decisions that are likely to matter beyond a single task. Good candidates are durable constraints, architecture boundaries, rejected alternatives someone may retry later, externally forced choices, and intentional behavior that otherwise looks incorrect.
+Selection Standard
+
+Bias toward not writing. A decision belongs here only when leaving it undocumented would make a future task or bug exploration materially more likely to choose the wrong path.
+
+Record only durable constraints such as:
+
+* project invariants that will likely constrain future work
+* rejected alternatives someone could plausibly retry later
+* externally forced choices such as compatibility, compliance, vendor, or performance limits
+* intentional behavior that looks incorrect unless explained
+
+Do not record:
+
+* one-off implementation details
+* local cleanup notes or TODOs
+* temporary workarounds that are not yet accepted long-term behavior
+* facts already made obvious by code, tests, or tooling
+* constraints that disappeared after later simplification or optimization
+
+If unsure, skip the entry.
 
 Save Location
 
@@ -549,6 +568,8 @@ Requirements
 
 * Maximum 10 lines per decision
 * Default to append
+* Prefer fewer, harder decisions over broad coverage
+* One decision should capture one durable constraint, not a mixed summary
 * If a new entry appears to revise, merge with, or supersede an existing decision, do not edit or append yet
 * Instead, show the relevant prior entry, explain the overlap or conflict, and ask the user whether to append, revise, merge, supersede, or skip
 * Only modify an existing entry after explicit user confirmation
@@ -579,11 +600,13 @@ Workflow
 2. For cancelled briefs in either archive, treat the abandonment itself as potential decision material.
 3. Evaluate each brief against the Sediment Conditions below.
 4. For each candidate, draft a decision entry using the four-section format.
-5. Present a single review list: every scanned brief with a verdict (write / skip / insufficient info), then the proposed drafts grouped at the end.
-6. Do NOT append anything yet. Wait for the user to confirm which drafts to keep, edit, or drop.
-7. If a proposed draft appears to overlap with, conflict with, or refine an existing decision, include that prior entry in the review and present explicit options such as append as new, revise existing, merge, supersede, or skip.
-8. Only after confirmation, apply the approved action for each draft. Default to appending new entries oldest first under the matching YYYY-MM-DD section heading; revise or merge only when the user explicitly selects that action.
-9. Report what was appended, revised, merged, superseded, and skipped.
+5. Bias toward skip. Produce a draft only when the decision is clearly durable and likely to matter again.
+6. Present a single review list: every scanned brief with a verdict (write / skip / insufficient info), then the proposed drafts grouped at the end.
+7. For every skip, give a short reason such as one-off detail, already encoded in code, no future constraint, or still unsettled.
+8. Do NOT append anything yet. Wait for the user to confirm which drafts to keep, edit, or drop.
+9. If a proposed draft appears to overlap with, conflict with, or refine an existing decision, include that prior entry in the review and present explicit options such as append as new, revise existing, merge, supersede, or skip.
+10. Only after confirmation, apply the approved action for each draft. Default to appending new entries oldest first under the matching YYYY-MM-DD section heading; revise or merge only when the user explicitly selects that action.
+11. Report what was appended, revised, merged, superseded, and skipped.
 
 Sediment Conditions
 
@@ -594,12 +617,16 @@ A brief becomes a decision entry if it satisfies any of:
 * Counter-intuitive choice: code reads like an anti-pattern but is intentional.
 * Externally driven: compliance, performance, compatibility, or a third-party API limit forced the call.
 * A cancelled attempt whose failure is itself a useful conclusion.
+* Without the note, a future explore step would likely need to rediscover the same constraint.
 
 Skip Conditions
 
 * Affects only the implementation detail of one task.
 * A temporary or unsettled conclusion.
 * A bare fact with no decision behind it.
+* Already obvious from code, tests, tooling, or existing project structure.
+* A constraint that was later simplified away, optimized away, or otherwise stopped mattering.
+* Too vague to guide a future task.
 
 Entry Format
 
@@ -627,6 +654,53 @@ Requirements
 * Default to append
 * One date section per day; multiple decisions on the same day stack under the same heading
 * Never edit, merge, supersede, or delete prior entries without explicit user confirmation
+`,
+  },
+
+  'decision-curate': {
+    name: 'decision-curate',
+    description: 'Audit .ai/decisions/decisions.md and propose removing, merging, or tightening stale, duplicate, or low-value entries. Only apply changes after explicit user confirmation.',
+    content: `---
+name: decision-curate
+description: Audit .ai/decisions/decisions.md and propose removing, merging, or tightening stale, duplicate, or low-value entries. Only apply changes after explicit user confirmation.
+user-invocable: true
+---
+
+Purpose
+
+Keep .ai/decisions/decisions.md narrow enough that future explore steps can read it quickly and trust that every surviving entry still matters.
+
+Workflow
+
+1. Read .ai/decisions/decisions.md.
+2. Inspect the current codebase only as needed to judge whether each decision still represents a live constraint.
+3. Classify each entry as keep, tighten, merge, or remove.
+4. Bias toward removal when an entry is stale, duplicate, too local, too vague, or no longer changes future implementation choices.
+5. Present a review list with every entry, its classification, and a short reason.
+6. When proposing tighten, merge, or remove, quote or summarize the exact affected entry so the user can approve safely.
+7. Do NOT modify the file yet. Wait for explicit user confirmation on each proposed change set.
+8. After confirmation, apply only the approved edits and preserve unrelated entries.
+9. Summarize what was kept, tightened, merged, removed, and why.
+
+Retention Standard
+
+Keep an entry only if it still acts as a durable project constraint or explains an intentional choice a future task could otherwise get wrong.
+
+Removal Candidates
+
+* one-off implementation details
+* decisions already enforced clearly by code, tests, or tooling
+* duplicate or near-duplicate entries
+* vague notes that do not change future choices
+* constraints invalidated by later refactors, simplifications, or performance work
+* historical context that belongs in task or bug archives instead
+
+Requirements
+
+* Default to proposing, not editing
+* Never remove or rewrite an entry without explicit user confirmation
+* Prefer deleting low-value entries over rewriting them into longer prose
+* Keep the remaining file concise and high-signal
 `,
   },
 };
@@ -791,7 +865,7 @@ export function init(cwd, { fs, path, log }) {
   fast:  task-fast
   task:  task-explore -> task-implement -> task-review | task-cancel
   bug:   bug-explore -> bug-fix -> bug-review | bug-cancel
-  other: decision-log
+  other: decision-log | decision-curate
   sweep: decision-sweep-weekly`);
 }
 
@@ -826,7 +900,7 @@ export function refresh(cwd, { fs, path, log }) {
   fast:  task-fast
   task:  task-explore -> task-implement -> task-review | task-cancel
   bug:   bug-explore -> bug-fix -> bug-review | bug-cancel
-  other: decision-log
+  other: decision-log | decision-curate
   sweep: decision-sweep-weekly`);
 }