@winton979/task-cli 1.0.2 → 1.1.0

package/README.md

@@ -1,38 +1,203 @@
 # task-cli
 
-Lightweight task workflow CLI for AI-assisted development.
+Lightweight task workflow for AI-assisted development.
 
-## Install
+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 (via Grill Me)
+* 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 relies on a Grill Me compatible skill for requirement exploration.
+
+Recommended:
+
+```bash
+npx add-skill PJ-SBN-593844/skill-grill-me
+```
+
+Compatible Grill Me implementations may also work.
+
+---
+
 ## Usage
 
 ```bash
-task init     # Initialize .ai/ workflow structure in current directory
-task --help   # Show help
+task init
+task refresh
+task doctor
+task --help
 ```
 
-After `task init`, the following skills become available in Claude Code:
+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, archives, or decision log.
+
+Use `task doctor` to check whether the required directories exist, whether managed skills are missing or outdated, and whether the `.gitignore` rules are present.
 
-**Task workflow:** `task-fast` → `task-explore` → `task-brief` → `task-implement` → `task-review`
+---
 
-**Bug workflow:** `bug-explore` → `bug-brief` → `bug-fix` → `bug-review`
+## Recommended Workflow
 
-**Other:** `decision-log`
+### Small Feature / Enhancement
 
-## Directory structure
+```text
+/task-fast
+    ↓
+clarify + brief + implement + validate + archive
+    ↓
+/task-review
+```
+
+### Larger Requirement
 
+```text
+/task-explore
+    ↓
+TASK_READY
+    ↓
+/task-implement
+    ↓
+/task archived
+    ↓
+/task-review
 ```
+
+### Bug Fix
+
+```text
+/bug-explore
+    ↓
+BUG_READY
+    ↓
+/bug-fix
+    ↓
+/bug archived
+    ↓
+/bug-review
+```
+
+---
+
+## Available Skills
+
+### Task Workflow
+
+* task-fast
+* task-explore
+* task-implement
+* task-review
+
+### Bug Workflow
+
+* bug-explore
+* bug-fix
+* bug-review
+
+### Other
+
+* decision-log
+
+---
+
+## Directory Structure
+
+```text
 .ai/
 ├── tasks/
 │   ├── active/
 │   └── archive/
+│
 ├── bugs/
 │   ├── active/
 │   └── archive/
-└── decisions/
-    └── decisions.md
-```
+│
+├── decisions/
+│   └── decisions.md
+│
+├── .claude/skills/
+└── .codex/skills/
+```
+
+---
+
+## 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 and lightweight archiving
+4. Reviewing work against acceptance criteria
+5. Keeping a lightweight decision history
+
+The goal is to improve quality without slowing down iteration speed.
+
+
+## Can This Be Simpler?
+
+Yes. The main simplification is to collapse the old 4-step paths:
+
+* `task-explore` now includes brief generation.
+* `bug-explore` now includes bug brief generation.
+* `task-implement` and `bug-fix` now validate and archive the brief when the work is complete.
+
+That leaves these practical flows:
+
+* Explore only: `/task-explore` or `/bug-explore`
+* Execute and archive: `/task-implement` or `/bug-fix`
+* Review: `/task-review` or `/bug-review`
+* One-shot small work: `/task-fast`
+
+## 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`, `bug-explore`, `bug-fix`, `bug-review`, `decision-log`
+* 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
+```
+
+> Task CLI does not install Grill Me automatically.
+> Users remain free to choose any Grill Me compatible implementation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winton979/task-cli",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Lightweight task workflow CLI for AI-assisted development",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
-import { init } from './init.js';
+import { init, refresh, doctor } from './init.js';
 
 const cwd = process.cwd();
 const cmd = process.argv[2];
@@ -20,17 +20,30 @@ task - Lightweight AI-assisted task workflow
 
 Usage:
   task init     Initialize task workflow in current directory
-  task --help   Show this help`);
+  task refresh  Reinstall task-cli managed workflow skills
+  task doctor   Check workflow setup and skill freshness
+  task --help   Show this help
+
+Recommended flows after init:
+  fast: task-fast
+  task: task-explore -> task-implement -> task-review
+  bug:  bug-explore -> bug-fix -> bug-review`);
 }
 
 switch (cmd) {
   case 'init':
     init(cwd, { fs, path, log });
     break;
+  case 'refresh':
+    refresh(cwd, { fs, path, log });
+    break;
+  case 'doctor':
+    doctor(cwd, { fs, path, log });
+    break;
   case undefined:
   case '--help':
   case '-h':
   default:
     showHelp();
     break;
-}
+}

package/src/init.js

@@ -1,90 +1,107 @@
-import { readFileSync } from 'node:fs';
+const TASK_ACTIVE_DIR = '.ai/tasks/active';
+const TASK_ARCHIVE_DIR = '.ai/tasks/archive';
+const BUG_ACTIVE_DIR = '.ai/bugs/active';
+const BUG_ARCHIVE_DIR = '.ai/bugs/archive';
+const DECISIONS_FILE = '.ai/decisions/decisions.md';
+const CLAUDE_SKILLS_DIR = '.claude/skills';
+const CODEX_SKILLS_DIR = '.codex/skills';
+const GITIGNORE_BLOCK = [
+  '# task workflow',
+  '.ai/tasks/active/*.md',
+  '.ai/bugs/active/*.md',
+].join('\n');
 
 const SKILLS = {
   'task-fast': {
     name: 'task-fast',
-    description: 'Fast path for small requirements. Invoke Grill Me, generate task brief, save to .ai/tasks/active/.',
+    description: 'Fast path for small requirements. Clarify quickly, create the brief, implement, verify, and archive.',
     content: `---
 name: task-fast
-description: Fast path for small requirements. Invoke Grill Me, generate task brief, save to .ai/tasks/active/.
+description: Fast path for small requirements. Clarify quickly, create the brief, implement, verify, and archive.
 user-invocable: true
 ---
 
 Purpose
 
-Fast path for small requirements and optimizations.
+Handle a small requirement in one continuous workflow with minimal ceremony.
 
 Workflow
 
-1. Invoke the installed Grill Me skill.
-2. Continue requirement clarification until Grill Me completes.
-3. Generate a task brief automatically.
-4. Save the brief to:
+1. Clarify the requirement just enough to remove ambiguity.
+2. Create a concise task brief and save it to:
 
 .ai/tasks/active/YYYY-MM-DD-task-name.md
 
-5. Present the brief.
-6. Wait for approval before implementation.
+3. Show the brief before coding.
+4. If the user does not object, implement immediately.
+5. Verify the result against the acceptance criteria.
+6. Move the brief to:
 
-Output
+.ai/tasks/archive/YYYY-MM-DD-task-name.md
 
-TASK_BRIEF_READY
-`,
-  },
+7. Summarize the outcome and any follow-up risks.
 
-  'task-explore': {
-    name: 'task-explore',
-    description: 'Clarify requirements before implementation. Invoke Grill Me until the task is understood.',
-    content: `---
-name: task-explore
-description: Clarify requirements before implementation. Invoke Grill Me until the task is understood.
-user-invocable: true
----
+Task Brief Format
 
-Purpose
+# Goal
 
-Clarify requirements before implementation.
+What should be achieved.
 
-Workflow
+# Context
 
-1. Invoke the installed Grill Me skill.
-2. Continue until Grill Me determines the task is sufficiently understood.
-3. Do not write code.
-4. Do not create implementation plans.
-5. Focus only on requirement clarification.
+Relevant project background.
 
-When complete output:
+# Constraints
 
-TASK_READY
+Business or technical limitations.
+
+# Risks
+
+Potential pitfalls.
+
+# Acceptance Criteria
+
+Clear success conditions.
+
+Requirements
+
+* Maximum 500 words
+* No code
+* No architecture digression
+* Only information required for execution
+
+Output
+
+TASK_DONE
 `,
   },
 
-  'task-brief': {
-    name: 'task-brief',
-    description: 'Convert a completed Grill Me discussion into a concise task brief saved to .ai/tasks/active/.',
+  'task-explore': {
+    name: 'task-explore',
+    description: 'Clarify a requirement and generate the execution brief in one step, without implementing.',
     content: `---
-name: task-brief
-description: Convert a completed Grill Me discussion into a concise task brief saved to .ai/tasks/active/.
+name: task-explore
+description: Clarify a requirement and generate the execution brief in one step, without implementing.
 user-invocable: true
 ---
 
 Purpose
 
-Convert the completed Grill Me discussion into a concise execution brief.
+Clarify requirements and leave behind a ready-to-execute brief.
 
-Save Location
-
-.ai/tasks/active/YYYY-MM-DD-task-name.md
-
-Naming Convention
+Workflow
 
-YYYY-MM-DD-short-task-name.md
+1. Explore the requirement through focused questions.
+2. Continue until the task is sufficiently understood.
+3. Do not write code.
+4. Do not create implementation details.
+5. Once the requirement is clear, generate a concise task brief and save it to:
 
-Example
+.ai/tasks/active/YYYY-MM-DD-task-name.md
 
-2026-06-10-resize-handle.md
+6. Show the saved brief and stop.
 
-Output Format
+Task Brief Format
 
 # Goal
 
@@ -110,40 +127,38 @@ Requirements
 
 * Maximum 500 words
 * No code
-* No implementation details
 * No architecture design
 * Only information required for execution
 
-After generation:
+When complete output:
 
-1. Save the file.
-2. Show the content.
-3. Wait for approval.
+TASK_READY
 `,
   },
 
   'task-implement': {
     name: 'task-implement',
-    description: 'Implement the task using task.md. Follow acceptance criteria strictly.',
+    description: 'Implement the latest active task brief, validate it, and archive it when complete.',
     content: `---
 name: task-implement
-description: Implement the task using task.md. Follow acceptance criteria strictly.
+description: Implement the latest active task brief, validate it, and archive it when complete.
 user-invocable: true
 ---
 
 Purpose
 
-Implement the task using task.md.
+Implement a task from the latest file in .ai/tasks/active/.
 
 Rules
 
-1. Follow task.md strictly.
-2. Follow acceptance criteria strictly.
+1. Read the latest relevant brief from .ai/tasks/active/.
+2. Follow the acceptance criteria strictly.
 3. Prefer minimal changes.
 4. Respect existing project conventions.
 5. Avoid unnecessary refactoring.
 6. State assumptions explicitly.
-7. Keep implementation focused.
+7. Validate the result before stopping.
+8. If the work is complete, move the brief to .ai/tasks/archive/.
 
 Output
 
@@ -158,21 +173,30 @@ Files modified.
 ## Validation
 
 How acceptance criteria were satisfied.
+
+## Archive
+
+Whether the brief was archived.
 `,
   },
 
   'task-review': {
     name: 'task-review',
-    description: 'Review implementation against task.md. Evaluate completion, edge cases, maintainability, and risks.',
+    description: 'Review the latest task implementation against the active or archived task brief.',
     content: `---
 name: task-review
-description: Review implementation against task.md. Evaluate completion, edge cases, maintainability, and risks.
+description: Review the latest task implementation against the active or archived task brief.
 user-invocable: true
 ---
 
 Purpose
 
-Review implementation against task.md.
+Review implementation against the corresponding task brief.
+
+Rules
+
+1. Use the latest matching brief from .ai/tasks/active/ or .ai/tasks/archive/.
+2. Review the actual changes, not just the intent.
 
 Evaluate
 
@@ -206,23 +230,23 @@ Anything not fully implemented.
 
   'bug-explore': {
     name: 'bug-explore',
-    description: 'Investigate a bug before fixing it. Identify root cause candidates, separate observed vs expected behavior.',
+    description: 'Investigate a bug and generate a fix brief in one step, without writing code.',
     content: `---
 name: bug-explore
-description: Investigate a bug before fixing it. Identify root cause candidates, separate observed vs expected behavior.
+description: Investigate a bug and generate a fix brief in one step, without writing code.
 user-invocable: true
 ---
 
 Purpose
 
-Investigate a bug before fixing it.
+Investigate a bug and leave behind a ready-to-fix brief.
 
 Rules
 
 1. Do not write code.
-2. Do not suggest fixes immediately.
+2. Do not suggest fixes before enough evidence exists.
 3. Identify root cause candidates.
-4. Ask one question at a time.
+4. Ask focused questions.
 5. Request evidence whenever possible.
 6. Separate:
 
@@ -230,38 +254,13 @@ Rules
    * expected behavior
    * assumptions
 
-When sufficient evidence exists output:
-
-BUG_READY
-`,
-  },
-
-  'bug-brief': {
-    name: 'bug-brief',
-    description: 'Summarize bug investigation into a brief saved to .ai/bugs/active/.',
-    content: `---
-name: bug-brief
-description: Summarize bug investigation into a brief saved to .ai/bugs/active/.
-user-invocable: true
----
-
-Purpose
-
-Summarize bug investigation.
-
-Save Location
+7. Once the bug is sufficiently understood, generate a brief and save it to:
 
 .ai/bugs/active/YYYY-MM-DD-bug-name.md
 
-Naming Convention
-
-YYYY-MM-DD-short-bug-name.md
-
-Example
-
-2026-06-10-iframe-resize.md
+8. Show the saved brief and stop.
 
-Output Format
+Bug Brief Format
 
 # Problem
 
@@ -287,34 +286,35 @@ Technical limitations.
 
 Conditions proving the bug is fixed.
 
-After generation
+When sufficient evidence exists output:
 
-1. Save the file.
-2. Show the content.
-3. Wait for approval.
+BUG_READY
 `,
   },
 
   'bug-fix': {
     name: 'bug-fix',
-    description: 'Fix the bug using bug.md. Minimize changes, fix root cause not symptoms.',
+    description: 'Fix the latest active bug brief, validate the result, and archive the brief when complete.',
     content: `---
 name: bug-fix
-description: Fix the bug using bug.md. Minimize changes, fix root cause not symptoms.
+description: Fix the latest active bug brief, validate the result, and archive the brief when complete.
 user-invocable: true
 ---
 
 Purpose
 
-Fix the bug using bug.md.
+Fix a bug from the latest file in .ai/bugs/active/.
 
 Rules
 
-1. Minimize changes.
-2. Avoid unrelated refactoring.
-3. Fix root cause, not symptoms.
-4. Preserve existing behavior.
-5. Explain reasoning.
+1. Read the latest relevant brief from .ai/bugs/active/.
+2. Minimize changes.
+3. Avoid unrelated refactoring.
+4. Fix root cause, not symptoms.
+5. Preserve existing behavior.
+6. Explain reasoning.
+7. Validate the fix before stopping.
+8. If the bug is fixed, move the brief to .ai/bugs/archive/.
 
 Output
 
@@ -329,21 +329,30 @@ Changes made.
 ## Validation
 
 Verification performed.
+
+## Archive
+
+Whether the brief was archived.
 `,
   },
 
   'bug-review': {
     name: 'bug-review',
-    description: 'Review bug fix against bug.md. Check root cause, regression risks, side effects.',
+    description: 'Review the latest bug fix against the active or archived bug brief.',
     content: `---
 name: bug-review
-description: Review bug fix against bug.md. Check root cause, regression risks, side effects.
+description: Review the latest bug fix against the active or archived bug brief.
 user-invocable: true
 ---
 
 Purpose
 
-Review implementation against bug.md.
+Review implementation against the corresponding bug brief.
+
+Rules
+
+1. Use the latest matching brief from .ai/bugs/active/ or .ai/bugs/archive/.
+2. Check whether the reported root cause was truly addressed.
 
 Check
 
@@ -415,43 +424,44 @@ Requirements
   },
 };
 
-export function init(cwd, { fs, path, log }) {
-  // Directory structure
-  const dirs = [
-    '.ai',
-    '.ai/tasks/active',
-    '.ai/tasks/archive',
-    '.ai/bugs/active',
-    '.ai/bugs/archive',
-    '.ai/decisions',
-    '.claude/skills',
-  ];
+const MANAGED_SKILL_NAMES = Object.values(SKILLS).map((skill) => skill.name);
 
-  log.info('Creating directory structure...');
-  for (const dir of dirs) {
-    const full = path.join(cwd, dir);
-    if (!fs.existsSync(full)) {
-      fs.mkdirSync(full, { recursive: true });
-      log.chalk.green(`  ✓ ${dir}`);
-    } else {
-      log.chalk.dim(`  - ${dir} (exists)`);
-    }
-  }
+function skillFilePath(path, cwd, skillRoot, skillName) {
+  return path.join(cwd, skillRoot, skillName, 'SKILL.md');
+}
 
-  // Create decisions.md placeholder
-  const decisionsPath = path.join(cwd, '.ai/decisions/decisions.md');
-  if (!fs.existsSync(decisionsPath)) {
-    fs.writeFileSync(decisionsPath, '# Decisions Log\n\n');
-    log.chalk.green('  ✓ .ai/decisions/decisions.md');
-  } else {
-    log.chalk.dim('  - .ai/decisions/decisions.md (exists)');
+function logCheck(log, ok, label, detail) {
+  if (ok) {
+    log.chalk.green(`  OK   ${label}${detail ? ` - ${detail}` : ''}`);
+    return;
   }
+  console.log(chalk.yellow(`  WARN ${label}${detail ? ` - ${detail}` : ''}`));
+}
+
+function ensureDir(fs, path, baseDir, relativeDir, log) {
+  const full = path.join(baseDir, relativeDir);
+  if (!fs.existsSync(full)) {
+    fs.mkdirSync(full, { recursive: true });
+    log.chalk.green(`  ✓ ${relativeDir}`);
+    return;
+  }
+  log.chalk.dim(`  - ${relativeDir} (exists)`);
+}
+
+function ensureFile(fs, path, filePath, content, log) {
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, content);
+    log.chalk.green(`  ✓ ${path.relative(process.cwd(), filePath)}`);
+    return;
+  }
+  log.chalk.dim(`  - ${path.relative(process.cwd(), filePath)} (exists)`);
+}
 
-  // Create skill files
-  log.info('\nInstalling workflow skills...');
-  for (const [key, skill] of Object.entries(SKILLS)) {
-    const skillDir = path.join(cwd, '.claude/skills', skill.name);
-    const skillFile = path.join(skillDir, 'SKILL.md');
+function installSkills(fs, path, cwd, skillRoot, log) {
+  ensureDir(fs, path, cwd, skillRoot, log);
+  for (const skill of Object.values(SKILLS)) {
+    const skillDir = path.join(cwd, skillRoot, skill.name);
+    const skillFile = skillFilePath(path, cwd, skillRoot, skill.name);
 
     if (!fs.existsSync(skillDir)) {
       fs.mkdirSync(skillDir, { recursive: true });
@@ -459,26 +469,185 @@ export function init(cwd, { fs, path, log }) {
 
     if (!fs.existsSync(skillFile)) {
       fs.writeFileSync(skillFile, skill.content);
-      log.chalk.green(`  ✓ ${skill.name}`);
+      log.chalk.green(`  ✓ ${skillRoot}/${skill.name}`);
     } else {
-      log.chalk.dim(`  - ${skill.name} (exists)`);
+      log.chalk.dim(`  - ${skillRoot}/${skill.name} (exists)`);
+    }
+  }
+}
+
+function removeManagedSkills(fs, path, cwd, skillRoot, log) {
+  const rootPath = path.join(cwd, skillRoot);
+  if (!fs.existsSync(rootPath)) {
+    log.chalk.dim(`  - ${skillRoot} (missing)`);
+    return;
+  }
+
+  for (const skillName of MANAGED_SKILL_NAMES) {
+    const skillDir = path.join(rootPath, skillName);
+    if (!fs.existsSync(skillDir)) {
+      log.chalk.dim(`  - ${skillRoot}/${skillName} (missing)`);
+      continue;
     }
+
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    log.chalk.green(`  ✓ removed ${skillRoot}/${skillName}`);
   }
+}
 
-  // Create or append .gitignore
+function updateGitignore(fs, path, cwd, log) {
   const gitignorePath = path.join(cwd, '.gitignore');
-  const gitignoreEntry = '\n# task workflow\n.ai/tasks/active/*.md\n.ai/bugs/active/*.md\n';
-  let existing = '';
-  if (fs.existsSync(gitignorePath)) {
-    existing = fs.readFileSync(gitignorePath, 'utf-8');
+  const existing = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, 'utf-8')
+    : '';
+
+  if (existing.includes('# task workflow')) {
+    log.chalk.dim('  - .gitignore (task workflow block exists)');
+    return;
   }
-  if (!existing.includes('# task workflow')) {
-    fs.writeFileSync(gitignorePath, existing.trimEnd() + gitignoreEntry);
-    log.chalk.green('  ✓ .gitignore updated');
+
+  const prefix = existing.trimEnd();
+  const next = prefix ? `${prefix}\n\n${GITIGNORE_BLOCK}\n` : `${GITIGNORE_BLOCK}\n`;
+  fs.writeFileSync(gitignorePath, next);
+  log.chalk.green('  ✓ .gitignore updated');
+}
+
+export function init(cwd, { fs, path, log }) {
+  const dirs = [
+    '.ai',
+    TASK_ACTIVE_DIR,
+    TASK_ARCHIVE_DIR,
+    BUG_ACTIVE_DIR,
+    BUG_ARCHIVE_DIR,
+    '.ai/decisions',
+  ];
+
+  log.info('Creating directory structure...');
+  for (const dir of dirs) {
+    ensureDir(fs, path, cwd, dir, log);
   }
 
-  log.info(`\nTask workflow initialized. Skills available:
-  task:  fast, explore, brief, implement, review
-  bug:   explore, brief, fix, review
+  const decisionsPath = path.join(cwd, DECISIONS_FILE);
+  ensureFile(fs, path, decisionsPath, '# Decisions Log\n\n', log);
+
+  log.info('\nInstalling workflow skills...');
+  installSkills(fs, path, cwd, CLAUDE_SKILLS_DIR, log);
+  installSkills(fs, path, cwd, CODEX_SKILLS_DIR, log);
+
+  log.info('\nUpdating ignore rules...');
+  updateGitignore(fs, path, cwd, log);
+
+  log.info(`\nTask workflow initialized. Recommended flows:
+  fast:  task-fast
+  task:  task-explore -> task-implement -> task-review
+  bug:   bug-explore -> bug-fix -> bug-review
   other: decision-log`);
-}
+}
+
+export function refresh(cwd, { fs, path, log }) {
+  const dirs = [
+    '.ai',
+    TASK_ACTIVE_DIR,
+    TASK_ARCHIVE_DIR,
+    BUG_ACTIVE_DIR,
+    BUG_ARCHIVE_DIR,
+    '.ai/decisions',
+  ];
+
+  log.info('Ensuring directory structure...');
+  for (const dir of dirs) {
+    ensureDir(fs, path, cwd, dir, log);
+  }
+
+  const decisionsPath = path.join(cwd, DECISIONS_FILE);
+  ensureFile(fs, path, decisionsPath, '# Decisions Log\n\n', log);
+
+  log.info('\nRefreshing managed workflow skills...');
+  removeManagedSkills(fs, path, cwd, CLAUDE_SKILLS_DIR, log);
+  removeManagedSkills(fs, path, cwd, CODEX_SKILLS_DIR, log);
+  installSkills(fs, path, cwd, CLAUDE_SKILLS_DIR, log);
+  installSkills(fs, path, cwd, CODEX_SKILLS_DIR, log);
+
+  log.info('\nUpdating ignore rules...');
+  updateGitignore(fs, path, cwd, log);
+
+  log.info(`\nTask workflow refreshed. Managed skills reinstalled:
+  fast:  task-fast
+  task:  task-explore -> task-implement -> task-review
+  bug:   bug-explore -> bug-fix -> bug-review
+  other: decision-log`);
+}
+
+export function doctor(cwd, { fs, path, log }) {
+  const checks = [];
+  const requiredDirs = [
+    '.ai',
+    TASK_ACTIVE_DIR,
+    TASK_ARCHIVE_DIR,
+    BUG_ACTIVE_DIR,
+    BUG_ARCHIVE_DIR,
+    '.ai/decisions',
+    CLAUDE_SKILLS_DIR,
+    CODEX_SKILLS_DIR,
+  ];
+
+  log.info('Checking task workflow setup...');
+
+  for (const dir of requiredDirs) {
+    const full = path.join(cwd, dir);
+    const exists = fs.existsSync(full);
+    checks.push(exists);
+    logCheck(log, exists, dir, exists ? 'present' : 'missing');
+  }
+
+  const decisionsPath = path.join(cwd, DECISIONS_FILE);
+  const decisionsExists = fs.existsSync(decisionsPath);
+  checks.push(decisionsExists);
+  logCheck(log, decisionsExists, DECISIONS_FILE, decisionsExists ? 'present' : 'missing');
+
+  for (const skillRoot of [CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR]) {
+    for (const skill of Object.values(SKILLS)) {
+      const skillPath = skillFilePath(path, cwd, skillRoot, skill.name);
+      if (!fs.existsSync(skillPath)) {
+        checks.push(false);
+        logCheck(log, false, `${skillRoot}/${skill.name}`, 'missing');
+        continue;
+      }
+
+      const content = fs.readFileSync(skillPath, 'utf-8');
+      const matches = content === skill.content;
+      checks.push(matches);
+      logCheck(
+        log,
+        matches,
+        `${skillRoot}/${skill.name}`,
+        matches ? 'current' : 'outdated, run `task refresh`'
+      );
+    }
+  }
+
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const gitignore = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, 'utf-8')
+    : '';
+  const hasGitignoreBlock = gitignore.includes(GITIGNORE_BLOCK);
+  checks.push(hasGitignoreBlock);
+  logCheck(
+    log,
+    hasGitignoreBlock,
+    '.gitignore',
+    hasGitignoreBlock ? 'task workflow rules present' : 'missing task workflow rules'
+  );
+
+  const okCount = checks.filter(Boolean).length;
+  const totalCount = checks.length;
+  const allGood = okCount === totalCount;
+
+  log.info(`\nSummary: ${okCount}/${totalCount} checks passed.`);
+  if (allGood) {
+    log.chalk.green('Task workflow is healthy.');
+    return;
+  }
+
+  console.log(chalk.yellow('Recommended next step: run `task refresh` to reinstall managed skills and repair setup.'));
+}