@winton979/task-cli 1.5.0 → 1.6.1

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
@@ -110,6 +121,10 @@ archive automatically
 /task-explore  →  TASK_READY  →  /task-implement  →  optional /task-audit
 ```
 
+`task-explore` writes the brief for a fresh-session handoff. Briefs should stay within 500 words; they may extend to 1000 only when a shorter contract would omit execution-critical information. Requirements that still do not fit should be split before implementation.
+
+When more than one active brief could match, identify the intended brief when invoking `task-implement`. The implementing agent rechecks repository facts and resolves local, reversible choices from existing conventions. It asks the user only for unresolved decisions that materially affect the contract, records confirmed narrow clarifications in the active brief, and returns material goal, scope, or acceptance changes to `task-explore`.
+
 ### Bug Fix
 
 ```text
@@ -167,9 +182,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 +324,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.1",
   "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.',
@@ -157,6 +278,15 @@ ${DECISIONS_READ_GUIDANCE}
 
 ${COMPLEXITY_ASSESSMENT_GUIDANCE}
 
+Cross-session Readiness
+
+Before finalizing the brief, assume implementation will start in a fresh session without the exploration conversation.
+
+* Record every confirmed user decision that materially constrains behavior, scope, compatibility, security, data handling, or acceptance.
+* Record material exclusions when omitting them could cause plausible scope expansion.
+* Do not copy repository facts the implementing agent can discover. Include only context needed to interpret the contract.
+* Do not output TASK_READY while a material user-owned decision remains unresolved.
+
 Task Brief Format
 
 # Goal
@@ -185,7 +315,9 @@ Clear success conditions.
 
 Requirements
 
-* Maximum 500 words
+* Aim for 500 words or fewer
+* Extend to at most 1000 words only when required to preserve execution-critical scope, constraints, risks, or acceptance criteria
+* If a coherent contract cannot fit within 1000 words, split the requirement and complete exploration for one independently executable task at a time
 * No code
 * No architecture design
 * Stay implementation-agnostic; describe constraints, not solutions
@@ -199,27 +331,39 @@ TASK_READY
 
   'task-implement': {
     name: 'task-implement',
-    description: 'Implement the latest active task brief and validate it. Archive automatically when complete.',
+    description: 'Implement a selected active task brief and validate it. Archive automatically when complete.',
     content: `---
 name: task-implement
-description: Implement the latest active task brief and validate it. Archive automatically when complete.
+description: Implement a selected active task brief and validate it. Archive automatically when complete.
 user-invocable: true
 ---
 
 Purpose
 
-Implement a task from the latest file in .ai/tasks/active/.
+Implement the intended task from .ai/tasks/active/.
 
 Rules
 
-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. Validate the result before stopping.
-8. If the work is complete, archive the brief automatically by moving it to .ai/tasks/archive/.
+1. Identify the intended brief in .ai/tasks/active/. Use a user-specified name or path when provided. Without one, proceed only when a single brief is the clear match. Ask the user when multiple briefs are plausible; do not choose by recency alone.
+2. Read the selected brief and inspect the relevant current code before planning.
+3. Follow the acceptance criteria strictly.
+4. Prefer minimal changes.
+5. Respect existing project conventions.
+6. Avoid unnecessary refactoring.
+7. State assumptions explicitly.
+8. Validate the result before stopping.
+9. If the work is complete, archive the selected brief automatically by moving it to .ai/tasks/archive/.
+
+Brief Sufficiency
+
+Before changing code, and whenever implementation reveals an ambiguity, determine whether the selected brief remains executable against the current project state.
+
+* Investigate facts available from the repository or environment instead of asking the user.
+* For a local, reversible implementation choice that does not materially affect behavior, scope, compatibility, security, data, or acceptance, follow existing conventions and choose the simplest option.
+* Do not infer an unresolved user decision that materially affects those concerns. Ask one focused question at a time, include a recommended answer, and wait.
+* After explicit confirmation of a narrow clarification, record it in the selected active brief before continuing implementation.
+* If clarification materially changes the Goal, accepted scope, or Acceptance Criteria, or the unresolved decisions collectively require material contract revision, stop and require renewed task-explore. Do not implement against an outdated brief.
+* If current project state materially contradicts the brief's context, surface the conflict and resolve it under the same rules.
 
 When making implementation decisions
 
@@ -804,8 +948,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 +997,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 +1080,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 +1117,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 +1155,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) {