@winton979/task-cli 1.5.0 → 1.6.0

package/README.md

@@ -84,16 +84,27 @@ After initialization, Task CLI creates the `.ai/` workspace and installs workflo
 
 ### 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 exploration, not a runtime dependency.
+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
@@ -167,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`
@@ -305,7 +320,7 @@ 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winton979/task-cli",
-  "version": "1.5.0",
+  "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

@@ -48,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.',
@@ -804,8 +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 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,
+    });
+  }
+
+  return artifacts;
 }
 
 function logCheck(log, ok, label, detail) {
@@ -839,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)`);
   }
 }
 
@@ -916,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)
@@ -952,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)
@@ -989,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) {