@winton979/task-cli 1.4.3 → 1.6.0

package/README.md

@@ -82,22 +82,29 @@ 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.
+### Exploration Protocol
+
+Task CLI embeds the `grilling` primitive from [Matt Pocock's skills collection](https://github.com/mattpocock/skills.git). Its wording is the methodological foundation for decision-driven exploration, not a runtime dependency.
+
+`task-explore` and `bug-explore` preserve the primitive's body verbatim. Their only workflow-specific interpretation of it is that "act on it" means creating the brief. `task-fast` uses a narrower clarification loop so the fast path remains fast.
+
+`project-explore` is explicitly invoked, read-only, and evidence-driven. It answers when the available evidence supports a bounded conclusion and asks a question only when ambiguity would materially change the answer.
+
+Task CLI neither requires nor installs a companion interviewing skill.
 
 ---
 
-## Quick Start
-
+## Quick Start
+
+### Project Understanding
+
+```text
+Claude Code: /project-explore
+Codex CLI:   $project-explore
+             ↓
+evidence-based explanation  →  no artifacts or changes
+```
+
 ### Small Feature / Enhancement
 
 ```text
@@ -171,9 +178,13 @@ The workflow encourages the simplest acceptable implementation instead of the mo
 
 ---
 
-## Available Skills
-
-**Task Workflow**
+## Available Skills
+
+**Project Understanding**
+
+* `project-explore`
+
+**Task Workflow**
 
 * `task-fast`
 * `task-explore`
@@ -309,18 +320,12 @@ task refresh
 This will:
 
 * keep `.ai/tasks`, `.ai/bugs`, and `.ai/decisions`
-* remove only managed skills from `.claude/skills/` and `.codex/skills/`, including legacy `task-review` and `bug-review`, then reinstall the current set: `task-fast`, `task-explore`, `task-implement`, `task-audit`, `task-cancel`, `bug-explore`, `bug-fix`, `bug-audit`, `bug-cancel`, `decision-log`, `decision-sweep-weekly`, `decision-curate`
+* remove only managed skills from `.claude/skills/` and `.codex/skills/`, including legacy `task-review` and `bug-review`, then reinstall the current set: `project-explore`, `task-fast`, `task-explore`, `task-implement`, `task-audit`, `task-cancel`, `bug-explore`, `bug-fix`, `bug-audit`, `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
+## License
 
 MIT
 

package/package.json

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

package/src/cli.js

@@ -25,6 +25,7 @@ Usage:
   task --help   Show this help
 
 Recommended flows after init:
+  explore: project-explore
   fast: task-fast
   task: task-explore -> task-implement -> task-audit (optional, risk-triggered)
   bug:  bug-explore -> bug-fix -> bug-audit (optional, risk-triggered)

package/src/init.js

@@ -13,11 +13,15 @@ const GITIGNORE_BLOCK = [
   '.ai/bugs/active/*.md',
 ].join('\n');
 
-const GRILL_ME_HINTS = [
-  'grill-me',
-  'skill-grill-me',
-  'grill me',
-];
+const GRILLING_GUIDANCE = `Grilling
+
+Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
+
+If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+
+Do not act on it until I confirm we have reached a shared understanding.`;
 
 const DECISIONS_READ_GUIDANCE = `Decision Intake
 
@@ -44,7 +48,128 @@ Before finalizing the brief, assess whether the requirement justifies added comp
   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 PROJECT_EXPLORE_DESCRIPTION = 'Build an evidence-based understanding of the existing project without changing it. Use only when the user explicitly invokes project-explore; do not use for implementation, bug investigation, or formal review.';
+const PROJECT_EXPLORE_BODY = `Purpose
+
+Establish a shared, evidence-based understanding of the existing project within the current conversation.
+
+Explain behavior, structure, design intent, constraints, and trade-offs. Do not create change work.
+
+Workflow
+
+1. Classify the user's primary intent. If it matches a case under Transitions, state the boundary and stop.
+2. Identify the question or project area to understand.
+3. Inspect the relevant code, tests, configuration, documentation, decisions, and repository history. Look up repository facts instead of asking the user for them.
+4. Build the answer from evidence. Separate:
+
+   * observed facts
+   * recorded intent
+   * inferred rationale
+   * assumptions and unknowns
+   * trade-offs
+
+5. Answer when the evidence supports a bounded conclusion. Do not prolong exploration to remove immaterial uncertainty.
+6. Ask one focused question at a time only when ambiguity would materially change the answer. Recommend an answer only for a user-owned choice.
+7. Stop when the question is answered or the remaining uncertainty is stated precisely.
+
+Evidence Discipline
+
+* Treat current code, tests, configuration, and direct observations as evidence of behavior.
+* Treat documentation, decisions, archives, and repository history as evidence of context or intent. Do not let them override contradictory current behavior.
+* Cite file paths and line numbers when practical.
+* Treat missing rationale as unknown. Do not infer that no rationale existed.
+* When sources conflict, report the conflict and identify which claim each source supports.
+* Do not treat unfamiliar design as defective. If evidence indicates incorrect behavior, label it as a possible issue rather than diagnosing it here.
+
+Decision Discussion
+
+When discussing a design choice:
+
+* identify the decision and its constraints
+* compare only relevant alternatives
+* state the benefits, costs, and assumptions of each alternative
+* recommend a direction only when the user explicitly requests a recommendation and the available evidence is sufficient
+
+Keep recommendations conceptual. Do not provide code, file-by-file changes, implementation steps, acceptance criteria, or estimates. Do not present exploration as architecture approval.
+
+Project Memory
+
+Before explaining a project decision, inspect .ai/decisions/decisions.md if it exists and contains entries beyond the title.
+
+Use it narrowly:
+
+* extract only decisions relevant to the question
+* treat them as durable constraints, not complete documentation
+* verify that current project evidence does not contradict them
+* omit unrelated history
+
+Transitions
+
+If the user's primary intent becomes:
+
+* new or changed behavior: recommend task-fast or task-explore
+* suspected incorrect behavior: recommend bug-explore
+* recording an approved durable decision: recommend decision-log
+* review of a completed task or bug with a brief: recommend task-audit or bug-audit
+* standalone architecture or quality review: state that no managed workflow covers it; do not issue findings, ratings, approval, or a release verdict
+
+After routing, stop. Do not inspect the project to fulfill the out-of-scope request. Do not invoke another workflow or create its artifacts unless the user explicitly requests it.
+
+Boundaries
+
+Do not:
+
+* modify code, documentation, or project state
+* create task, bug, or decision artifacts
+* design an implementation
+* perform a formal architecture review or audit
+* treat exploration findings as approved decisions
+
+Output
+
+Answer directly. Use only the sections that improve clarity:
+
+## Understanding
+
+## Evidence
+
+## Intent and Uncertainty
+
+## Trade-offs
+
+## Open Questions
+
+Omit empty sections. For a simple question, prefer concise prose without headings.
+`;
+
 const SKILLS = {
+  'project-explore': {
+    name: 'project-explore',
+    description: PROJECT_EXPLORE_DESCRIPTION,
+    content: `---
+name: project-explore
+description: ${PROJECT_EXPLORE_DESCRIPTION}
+user-invocable: true
+disable-model-invocation: true
+---
+
+${PROJECT_EXPLORE_BODY}`,
+    codexContent: `---
+name: project-explore
+description: ${PROJECT_EXPLORE_DESCRIPTION}
+---
+
+${PROJECT_EXPLORE_BODY}`,
+    codexAgentContent: `interface:
+  display_name: "Project Explore"
+  short_description: "Explore existing projects from repository evidence"
+  default_prompt: "Use $project-explore to explain the current project from repository evidence."
+
+policy:
+  allow_implicit_invocation: false
+`,
+  },
+
   'task-fast': {
     name: 'task-fast',
     description: 'Fast path for small requirements. Clarify quickly, create the brief, implement, and verify. Archive automatically on completion.',
@@ -60,23 +185,24 @@ Handle a small requirement in one continuous workflow with minimal ceremony.
 
 Workflow
 
-1. If a Grill Me compatible skill is available in the current environment, use it for requirement clarification.
-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. Before finalizing the brief, perform a Complexity Assessment.
-6. Create a concise task brief and save it to:
+1. Read the project code and conventions needed to avoid obvious conflicts.
+2. If a fact can be found by exploring the environment, look it up rather than asking the user.
+3. Ask only questions whose answers can change the implementation or acceptance criteria. Ask them one at a time, waiting for feedback on each before continuing. For each question, provide your recommended answer.
+4. Put unresolved decisions to the user; do not make them on the user's behalf.
+5. Read .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain this task.
+6. Before finalizing the brief, perform a Complexity Assessment.
+7. Create a concise task brief and save it to:
 
 .ai/tasks/active/YYYY-MM-DD-task-name.md
 
-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:
+8. Show the brief as the fast-path summary of shared understanding, ask the user to confirm it, and stop. Do not code until the user confirms.
+9. Once the user confirms the brief, implement immediately.
+10. Verify the result against the acceptance criteria.
+11. Archive the brief automatically by moving it to:
 
 .ai/tasks/archive/YYYY-MM-DD-task-name.md
 
-11. Summarize the outcome and any follow-up risks.
+12. Summarize the outcome and any follow-up risks.
 
 ${DECISIONS_READ_GUIDANCE}
 
@@ -123,10 +249,10 @@ TASK_DONE
 
   'task-explore': {
     name: 'task-explore',
-    description: 'Clarify a requirement and generate the execution brief in one step, without implementing.',
+    description: 'Grill the user relentlessly about a requirement; generate an execution brief only after shared understanding, without implementing.',
     content: `---
 name: task-explore
-description: Clarify a requirement and generate the execution brief in one step, without implementing.
+description: Grill the user relentlessly about a requirement; generate an execution brief only after shared understanding, without implementing.
 user-invocable: true
 ---
 
@@ -136,17 +262,17 @@ Clarify requirements and leave behind a ready-to-execute brief.
 
 Workflow
 
-1. If a Grill Me compatible skill is available in the current environment, use it for requirement exploration.
-2. If no Grill Me compatible skill is available, explore the requirement yourself through focused questions.
-3. Continue until the task is sufficiently understood.
-4. Do not write code.
-5. Do not create implementation details.
-6. Before writing the brief, inspect .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain this task.
-7. Once the requirement is clear, generate a concise task brief and save it to:
+1. Grill the requirement using the Grilling section below.
+2. Do not write code or create implementation details.
+3. Before writing the brief, inspect .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain this task.
+4. For this workflow, "act on it" means creating the brief.
+5. Generate a concise task brief and save it to:
 
 .ai/tasks/active/YYYY-MM-DD-task-name.md
 
-8. Show the saved brief and stop.
+6. Show the saved brief and stop.
+
+${GRILLING_GUIDANCE}
 
 ${DECISIONS_READ_GUIDANCE}
 
@@ -358,10 +484,10 @@ TASK_CANCELLED
 
   'bug-explore': {
     name: 'bug-explore',
-    description: 'Investigate a bug and generate a fix brief in one step, without writing code.',
+    description: 'Grill the user relentlessly about a bug while investigating its evidence; generate a fix brief only after shared understanding, without writing code.',
     content: `---
 name: bug-explore
-description: Investigate a bug and generate a fix brief in one step, without writing code.
+description: Grill the user relentlessly about a bug while investigating its evidence; generate a fix brief only after shared understanding, without writing code.
 user-invocable: true
 ---
 
@@ -371,24 +497,24 @@ Investigate a bug and leave behind a ready-to-fix brief.
 
 Rules
 
-1. If a Grill Me compatible skill is available in the current environment, use it for bug exploration.
-2. If no Grill Me compatible skill is available, ask focused questions and drive the investigation yourself.
-3. Do not write code.
-4. Do not suggest fixes before enough evidence exists.
-5. Identify root cause candidates.
-6. Request evidence whenever possible.
-7. Separate:
+1. Grill the bug using the Grilling section below.
+2. Investigate the bug and gather reproducible evidence. Do not write code or suggest fixes before enough evidence exists.
+3. Identify root cause candidates.
+4. Separate:
 
    * observed behavior
    * expected behavior
    * assumptions
 
-8. Before writing the brief, inspect .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain the observed behavior, expected behavior, or likely root cause.
-9. Once the bug is sufficiently understood, generate a brief and save it to:
+5. Before writing the brief, inspect .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain the observed behavior, expected behavior, or likely root cause.
+6. For this workflow, "act on it" means creating the brief.
+7. Generate a brief and save it to:
 
 .ai/bugs/active/YYYY-MM-DD-bug-name.md
 
-10. Show the saved brief and stop.
+8. Show the saved brief and stop.
+
+${GRILLING_GUIDANCE}
 
 ${DECISIONS_READ_GUIDANCE}
 
@@ -799,51 +925,22 @@ const MANAGED_SKILL_NAMES = [
   ...LEGACY_MANAGED_SKILL_NAMES,
 ];
 
-function skillFilePath(path, cwd, skillRoot, skillName) {
-  return path.join(cwd, skillRoot, skillName, 'SKILL.md');
-}
-
-function hasGrillMeHint(value) {
-  const normalized = value.toLowerCase();
-  return GRILL_ME_HINTS.some((hint) => normalized.includes(hint));
-}
-
-function detectLocalGrillMeSkill(fs, path, cwd, skillRoot) {
-  const root = path.join(cwd, skillRoot);
-  if (!fs.existsSync(root)) {
-    return null;
+function skillArtifacts(skillRoot, skill) {
+  const artifacts = [{
+    relativePath: 'SKILL.md',
+    content: skillRoot === CODEX_SKILLS_DIR && skill.codexContent
+      ? skill.codexContent
+      : skill.content,
+  }];
+
+  if (skillRoot === CODEX_SKILLS_DIR && skill.codexAgentContent) {
+    artifacts.push({
+      relativePath: 'agents/openai.yaml',
+      content: skill.codexAgentContent,
+    });
   }
 
-  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-
-    if (MANAGED_SKILL_NAMES.includes(entry.name)) {
-      continue;
-    }
-
-    if (hasGrillMeHint(entry.name)) {
-      return entry.name;
-    }
-
-    const skillPath = path.join(root, entry.name, 'SKILL.md');
-    if (!fs.existsSync(skillPath)) {
-      continue;
-    }
-
-    const content = fs.readFileSync(skillPath, 'utf-8');
-    const metadata = content
-      .split('---')
-      .slice(1, 2)
-      .join('\n');
-
-    if (hasGrillMeHint(metadata)) {
-      return entry.name;
-    }
-  }
-
-  return null;
+  return artifacts;
 }
 
 function logCheck(log, ok, label, detail) {
@@ -877,18 +974,24 @@ 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 });
     }
 
-    if (!fs.existsSync(skillFile)) {
-      fs.writeFileSync(skillFile, skill.content);
-      log.chalk.green(`  ✓ ${skillRoot}/${skill.name}`);
-    } else {
-      log.chalk.dim(`  - ${skillRoot}/${skill.name} (exists)`);
+    let created = false;
+    for (const artifact of skillArtifacts(skillRoot, skill)) {
+      const artifactPath = path.join(skillDir, artifact.relativePath);
+      if (fs.existsSync(artifactPath)) {
+        continue;
+      }
+
+      fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+      fs.writeFileSync(artifactPath, artifact.content);
+      created = true;
     }
+
+    const label = `${skillRoot}/${skill.name}`;
+    created ? log.chalk.green(`  ✓ ${label}`) : log.chalk.dim(`  - ${label} (exists)`);
   }
 }
 
@@ -954,6 +1057,7 @@ export function init(cwd, { fs, path, log }) {
   updateGitignore(fs, path, cwd, log);
 
   log.info(`\nTask workflow initialized. Recommended flows:
+  explore: project-explore
   fast:  task-fast
   task:  task-explore -> task-implement -> task-audit (optional, risk-triggered)
   bug:   bug-explore -> bug-fix -> bug-audit (optional, risk-triggered)
@@ -990,6 +1094,7 @@ export function refresh(cwd, { fs, path, log }) {
   updateGitignore(fs, path, cwd, log);
 
   log.info(`\nTask workflow refreshed. Managed skills reinstalled:
+  explore: project-explore
   fast:  task-fast
   task:  task-explore -> task-implement -> task-audit (optional, risk-triggered)
   bug:   bug-explore -> bug-fix -> bug-audit (optional, risk-triggered)
@@ -1027,22 +1132,27 @@ export function doctor(cwd, { fs, path, log }) {
 
   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;
+      for (const artifact of skillArtifacts(skillRoot, skill)) {
+        const artifactPath = path.join(cwd, skillRoot, skill.name, artifact.relativePath);
+        const label = artifact.relativePath === 'SKILL.md'
+          ? `${skillRoot}/${skill.name}`
+          : `${skillRoot}/${skill.name}/${artifact.relativePath}`;
+        if (!fs.existsSync(artifactPath)) {
+          checks.push(false);
+          logCheck(log, false, label, 'missing');
+          continue;
+        }
+
+        const content = fs.readFileSync(artifactPath, 'utf-8');
+        const matches = content === artifact.content;
+        checks.push(matches);
+        logCheck(
+          log,
+          matches,
+          label,
+          matches ? 'current' : 'outdated, run `task refresh`'
+        );
       }
-
-      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`'
-      );
     }
 
     for (const skillName of LEGACY_MANAGED_SKILL_NAMES) {
@@ -1056,22 +1166,6 @@ export function doctor(cwd, { fs, path, log }) {
     }
   }
 
-  const grillMeFindings = [
-    [CLAUDE_SKILLS_DIR, detectLocalGrillMeSkill(fs, path, cwd, CLAUDE_SKILLS_DIR)],
-    [CODEX_SKILLS_DIR, detectLocalGrillMeSkill(fs, path, cwd, CODEX_SKILLS_DIR)],
-  ];
-
-  for (const [skillRoot, skillName] of grillMeFindings) {
-    if (skillName) {
-      logCheck(log, true, `${skillRoot} Grill Me companion`, `detected ${skillName}`);
-      continue;
-    }
-
-    console.log(chalk.yellow(
-      `  WARN ${skillRoot} Grill Me companion - not detected locally; task-fast, task-explore, and bug-explore will use built-in clarification fallback`
-    ));
-  }
-
   const gitignorePath = path.join(cwd, '.gitignore');
   const gitignore = fs.existsSync(gitignorePath)
     ? fs.readFileSync(gitignorePath, 'utf-8')