feature: defer plan generation from add to work-implement

Author: cowwoc

.cat/issues/v2/v2.1/defer-plan-generation-to-work-phase/index.json

@@ -1,3 +1,5 @@
 {
-  "status": "open"
+  "status": "closed",
+  "resolution": "implemented with final inline fixes (config reads, temp cleanup, hardcoded paths)",
+  "targetBranch": "v2.1"
 }

.cat/issues/v2/v2.1/defer-plan-generation-to-work-phase/plan.md

@@ -15,6 +15,159 @@ Deferring full plan generation ensures the implementation plan reflects the curr
   (including implementation steps) at issue creation time
 - `cat:work-implement-agent` currently assumes a complete PLAN.md exists when it runs
 
+## Approaches
+
+### A: Inline lightweight plan in add + plan-builder invocation in work-implement
+
+- **Risk:** LOW
+- **Scope:** 3 files (plugin/skills/add/first-use.md, plugin/skills/work-implement-agent/first-use.md,
+  plugin/skills/plan-builder-agent/first-use.md and SKILL.md)
+- **Description:** Replace plan-builder invocation in add/first-use.md with inline lightweight plan generation.
+  Add plan-builder invocation in work-implement-agent/first-use.md before spawning the implementation subagent
+  (only when plan.md lacks implementation steps).
+
+> Selected: Approach A — minimal, targeted changes; backward compatible with existing full plan.mds.
+
+## Risk Assessment
+
+- **Risk Level:** LOW
+- **Concerns:** Existing open issues have full PLAN.md files (with implementation steps). They must continue to work.
+- **Mitigation:** `cat:work-implement-agent` checks whether plan.md already contains `## Sub-Agent Waves` or
+  `## Execution Steps` before invoking plan-builder-agent. If the section exists, skip the invocation. This
+  preserves existing full plans unchanged.
+
+## Files to Modify
+
+- `plugin/skills/add/first-use.md` — Replace plan-builder invocation in `issue_create` step with inline
+  lightweight plan.md generation (lines ~948–988)
+- `plugin/skills/work-implement-agent/first-use.md` — Add new "Generate implementation steps" section after
+  displaying the implementing banner (after Step 3) and before "Read plan.md and Invoke Main Agent Waves"
+- `plugin/skills/plan-builder-agent/SKILL.md` — Update description field to remove `/cat:add` reference
+- `plugin/skills/plan-builder-agent/first-use.md` — Update "When to Use" section and Mode: `initial` description
+
+## Pre-conditions
+
+- [ ] All dependent issues are closed
+
+## Sub-Agent Waves
+
+### Wave 1
+
+- **Modify `plugin/skills/add/first-use.md`**: Replace the plan-builder invocation in the `issue_create` step
+  with lightweight inline plan generation.
+
+  Locate the block starting with `**Generate plan.md via plan-builder-agent:**` (around line 948) through
+  the end of the plan-builder invocation (around line 989, just before `**Apply auto-detected skill dependency
+  updates...`).
+
+  Replace with `**Generate lightweight plan.md:**` block that:
+  1. Creates a unique temporary plan.md file using `planTempFile=$(mktemp --suffix=.md)` (multi-instance
+     safe — avoids name collisions when multiple `/cat:add` invocations run concurrently). Writes content:
+     - `# Plan` header
+     - `## Goal` section containing `${ISSUE_DESCRIPTION}` verbatim
+     - `## Post-conditions` section with POSTCONDITIONS items as a checklist
+
+     Use this bash approach (the agent writes the file using the Write tool, not a heredoc, to avoid
+     quoting issues with variable content):
+
+     ```
+     First: planTempFile=$(mktemp --suffix=.md)
+     Then the agent writes the lightweight plan.md to ${planTempFile} using the Write tool
+     (or Bash with printf/echo) with the following structure:
+
+     # Plan
+
+     ## Goal
+
+     ${ISSUE_DESCRIPTION}
+
+     ## Post-conditions
+
+     - [ ] ${postcondition_1}
+     - [ ] ${postcondition_2}
+     ...
+     ```
+
+  2. Passes `${planTempFile}` to `create-issue` via `planFile` parameter — same as before, but
+     pointing to the new lightweight file instead of the plan-builder output.
+  3. Removes the PLAN_CONTEXT JSON file creation step.
+  4. Removes the `cat:plan-builder-agent` Skill tool invocation.
+  5. Keeps the `create-issue` bash call structure identical (only the `planFile` value changes).
+
+  Files: `plugin/skills/add/first-use.md`
+
+- **Modify `plugin/skills/work-implement-agent/first-use.md`**: Insert a new "### Generate Implementation Steps"
+  section between the "Step 3 (Implementing Banner)" content and the "### Read plan.md and Invoke Main Agent
+  Waves" section (around line 153).
+
+  The new section:
+
+  ```markdown
+  ### Generate Implementation Steps
+
+  Before reading Main Agent Waves, check whether plan.md already contains implementation steps:
+
+  ```bash
+  PLAN_MD="${ISSUE_PATH}/plan.md" && \
+  grep -qE '^## (Sub-Agent Waves|Execution Steps)' "${PLAN_MD}" && \
+  echo "hasSteps=true" || echo "hasSteps=false"
+  ```
+
+  **If `hasSteps=false`** (lightweight plan created by `/cat:add`): invoke `cat:plan-builder-agent` in
+  revise mode to generate full implementation steps before spawning the implementation subagent:
+
+  1. Read EFFORT from config:
+     ```bash
+     CONFIG=$("${CLAUDE_PLUGIN_ROOT}/client/bin/get-config-output" effective)
+     EFFORT=$(echo "$CONFIG" | grep -o '"effort"[[:space:]]*:[[:space:]]*"[^"]*"' \
+       | sed 's/.*"effort"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+     ```
+
+  2. Invoke plan-builder-agent to add implementation steps:
+     ```
+     Skill tool:
+       skill: "cat:plan-builder-agent"
+       args: "${CAT_AGENT_ID} ${EFFORT} revise ${ISSUE_PATH} Generate full implementation steps for
+     this lightweight plan. Add Sub-Agent Waves or Execution Steps section with detailed step-by-step
+     implementation guidance."
+     ```
+
+  3. After plan-builder-agent returns, re-read the updated plan.md in subsequent steps.
+
+  **If `hasSteps=true`** (full plan with implementation steps): skip plan-builder-agent invocation.
+  Proceed directly to "Read plan.md and Invoke Main Agent Waves".
+  ```
+
+  Files: `plugin/skills/work-implement-agent/first-use.md`
+
+- **Modify `plugin/skills/plan-builder-agent/SKILL.md`**: Update the `description` field:
+  - Old: `Invoked by /cat:add for initial plans and by /cat:work for mid-work revisions.`
+  - New: `Invoked by /cat:work to generate full implementation steps before spawning the implementation
+    subagent, and for mid-work revisions when requirements change during implementation.`
+
+  Files: `plugin/skills/plan-builder-agent/SKILL.md`
+
+- **Modify `plugin/skills/plan-builder-agent/first-use.md`**: Update two sections:
+
+  Section 1 — "When to Use" (around line 61-64):
+  - Old line 63: `- **Initial planning** (\`/cat:add\`): Generate plan.md from issue description and context`
+  - New line 63: `- **Initial implementation** (\`/cat:work\`): Generate full implementation steps from a
+    lightweight plan.md created by \`/cat:add\` (which contains only goal and post-conditions)`
+
+  Section 2 — "### Mode: `initial`" (around line 33-48):
+  - Old line 35: `Used by \`/cat:add\`. The \`contextPath\` points to a temporary JSON file containing:`
+  - New line 35: `**Deprecated.** This mode was previously used by \`/cat:add\`. The \`revise\` mode is now
+    used by \`/cat:work-implement-agent\` to generate full implementation steps from lightweight plan.mds.
+    The \`contextPath\` points to a temporary JSON file containing:`
+
+  Files: `plugin/skills/plan-builder-agent/first-use.md`
+
+- **Commit all three file changes in one commit** with message:
+  `feature: defer plan generation from add to work-implement`
+
+  Also include index.json closure in this same commit:
+  - Set status to `closed` and progress to `100%` in the issue's index.json
+
 ## Post-conditions
 
 1. `/cat:add-agent` creates a lightweight PLAN.md containing only: goal description, pre-conditions, and

client/build-jlink.sh

@@ -87,6 +87,7 @@ readonly -a HANDLERS=(
   "statusline-install:util.StatuslineInstall"
   "record-learning:util.RecordLearning"
   "benchmark-runner:skills.BenchmarkRunner"
+  "verify-defer-plan-generation:util.VerifyDeferPlanGeneration"
 )
 
 # --- Logging ---

client/src/main/java/io/github/cowwoc/cat/hooks/util/VerifyDeferPlanGeneration.java

@@ -0,0 +1,197 @@
+/*
+ * Copyright (c) 2026 Gili Tzabari. All rights reserved.
+ *
+ * Licensed under the CAT Commercial License.
+ * See LICENSE.md in the project root for license terms.
+ */
+package io.github.cowwoc.cat.hooks.util;
+
+import io.github.cowwoc.cat.hooks.HookOutput;
+import io.github.cowwoc.cat.hooks.JvmScope;
+import io.github.cowwoc.cat.hooks.MainJvmScope;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.io.PrintStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Objects;
+
+/**
+ * Manual E2E verification tool for the defer-plan-generation-to-work-phase feature.
+ * <p>
+ * Asserts that:
+ * <ol>
+ *   <li>{@code plugin/skills/add/first-use.md} does NOT contain a {@code cat:plan-builder-agent} invocation</li>
+ *   <li>{@code plugin/skills/add/first-use.md} contains the lightweight plan generation block
+ *       ({@code planTempFile=$(mktemp})</li>
+ *   <li>{@code plugin/skills/work-implement-agent/first-use.md} contains the {@code hasSteps} check</li>
+ *   <li>{@code plugin/skills/work-implement-agent/first-use.md} invokes {@code cat:plan-builder-agent}</li>
+ * </ol>
+ * <p>
+ * Usage: {@code verify-defer-plan-generation [PROJECT_ROOT]}
+ * <p>
+ * {@code PROJECT_ROOT} defaults to the {@code CLAUDE_PROJECT_DIR} environment variable.
+ */
+public final class VerifyDeferPlanGeneration
+{
+  /**
+   * Instances are not supported.
+   */
+  private VerifyDeferPlanGeneration()
+  {
+  }
+
+  /**
+   * Entry point for the verify-defer-plan-generation CLI tool.
+   *
+   * @param args optional first argument is the project root path; defaults to {@code CLAUDE_PROJECT_DIR}
+   */
+  public static void main(String[] args)
+  {
+    try (MainJvmScope scope = new MainJvmScope())
+    {
+      try
+      {
+        run(args, scope, System.out);
+      }
+      catch (IOException e)
+      {
+        System.err.println("ERROR: " + e.getMessage());
+        System.exit(1);
+      }
+      catch (RuntimeException | AssertionError e)
+      {
+        Logger log = LoggerFactory.getLogger(VerifyDeferPlanGeneration.class);
+        log.error("Unexpected error", e);
+        System.out.println(new HookOutput(scope).block(
+          Objects.toString(e.getMessage(), e.getClass().getSimpleName())));
+      }
+    }
+  }
+
+  /**
+   * Runs the verification checks, writing results to {@code out}.
+   *
+   * @param args  command-line arguments; optional first arg is PROJECT_ROOT
+   * @param scope the JVM scope providing the project path when no argument is supplied
+   * @param out   the output stream for results
+   * @throws IOException          if a skill file cannot be read
+   * @throws NullPointerException if {@code args}, {@code scope}, or {@code out} are null
+   */
+  @SuppressWarnings("PMD.DoNotTerminateVM")
+  public static void run(String[] args, JvmScope scope, PrintStream out) throws IOException
+  {
+    Path projectRoot;
+    if (args.length >= 1)
+      projectRoot = Path.of(args[0]);
+    else
+      projectRoot = scope.getProjectPath();
+
+    Path addSkill = projectRoot.resolve("plugin/skills/add/first-use.md");
+    Path workImplementSkill = projectRoot.resolve("plugin/skills/work-implement-agent/first-use.md");
+
+    out.println("=== E2E Verification: defer-plan-generation-to-work-phase ===");
+
+    int passed = 0;
+    int failed = 0;
+
+    // Check 1: add/first-use.md must NOT contain cat:plan-builder-agent invocation
+    if (Files.notExists(addSkill))
+    {
+      out.println("FAIL: add/first-use.md has no cat:plan-builder-agent invocation");
+      out.println("      File not found: " + addSkill);
+      ++failed;
+    }
+    else
+    {
+      String addContent = Files.readString(addSkill);
+      if (addContent.contains("cat:plan-builder-agent"))
+      {
+        out.println("FAIL: add/first-use.md has no cat:plan-builder-agent invocation");
+        out.println("      Found 'cat:plan-builder-agent' in " + addSkill);
+        ++failed;
+      }
+      else
+      {
+        out.println("PASS: add/first-use.md has no cat:plan-builder-agent invocation");
+        ++passed;
+      }
+    }
+
+    // Check 2: add/first-use.md must contain the lightweight plan generation block
+    if (Files.notExists(addSkill))
+    {
+      out.println("FAIL: add/first-use.md contains lightweight plan block (planTempFile mktemp)");
+      out.println("      File not found: " + addSkill);
+      ++failed;
+    }
+    else
+    {
+      String addContent = Files.readString(addSkill);
+      if (addContent.contains("planTempFile=$(mktemp"))
+      {
+        out.println("PASS: add/first-use.md contains planTempFile=$(mktemp ...)");
+        ++passed;
+      }
+      else
+      {
+        out.println("FAIL: add/first-use.md contains lightweight plan block (planTempFile mktemp)");
+        out.println("      Pattern 'planTempFile=$(mktemp' not found in " + addSkill);
+        ++failed;
+      }
+    }
+
+    // Check 3: work-implement-agent/first-use.md must contain hasSteps check
+    if (Files.notExists(workImplementSkill))
+    {
+      out.println("FAIL: work-implement-agent/first-use.md contains hasSteps check");
+      out.println("      File not found: " + workImplementSkill);
+      ++failed;
+    }
+    else
+    {
+      String workContent = Files.readString(workImplementSkill);
+      if (workContent.contains("hasSteps"))
+      {
+        out.println("PASS: work-implement-agent/first-use.md contains hasSteps check");
+        ++passed;
+      }
+      else
+      {
+        out.println("FAIL: work-implement-agent/first-use.md contains hasSteps check");
+        out.println("      Pattern 'hasSteps' not found in " + workImplementSkill);
+        ++failed;
+      }
+    }
+
+    // Check 4: work-implement-agent/first-use.md must invoke cat:plan-builder-agent
+    if (Files.notExists(workImplementSkill))
+    {
+      out.println("FAIL: work-implement-agent/first-use.md invokes cat:plan-builder-agent");
+      out.println("      File not found: " + workImplementSkill);
+      ++failed;
+    }
+    else
+    {
+      String workContent = Files.readString(workImplementSkill);
+      if (workContent.contains("cat:plan-builder-agent"))
+      {
+        out.println("PASS: work-implement-agent/first-use.md invokes cat:plan-builder-agent");
+        ++passed;
+      }
+      else
+      {
+        out.println("FAIL: work-implement-agent/first-use.md invokes cat:plan-builder-agent");
+        out.println("      Pattern 'cat:plan-builder-agent' not found in " + workImplementSkill);
+        ++failed;
+      }
+    }
+
+    out.println("=== Results: " + passed + " passed, " + failed + " failed ===");
+
+    if (failed > 0)
+      System.exit(1);
+  }
+}