work-kit-cli 0.2.4 → 0.2.6

package/README.md

@@ -104,7 +104,7 @@ Any stage can route back to a previous stage. Each route is enforced with a max
 ### Output
 
 ```
-.claude/work-kit/
+.work-kit-tracker/
   2026-04-03-avatar-upload.md        # distilled summary
   archive/
     2026-04-03-avatar-upload.md      # full state.md copy

package/cli/src/commands/cancel.ts

@@ -0,0 +1,103 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readState, findWorktreeRoot, stateDir } from "../state/store.js";
+
+export interface CancelResult {
+  action: "cancelled" | "error";
+  slug?: string;
+  branch?: string;
+  worktreeRemoved: boolean;
+  branchDeleted: boolean;
+  message: string;
+}
+
+function resolveMainRepoRoot(worktreeRoot: string): string {
+  try {
+    const output = execFileSync("git", ["worktree", "list", "--porcelain"], {
+      cwd: worktreeRoot,
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    const firstLine = output.split("\n").find(l => l.startsWith("worktree "));
+    if (firstLine) return firstLine.slice("worktree ".length).trim();
+  } catch {
+    // fallback
+  }
+  return worktreeRoot;
+}
+
+export function cancelCommand(worktreeRoot?: string): CancelResult {
+  const root = worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    return {
+      action: "error",
+      worktreeRemoved: false,
+      branchDeleted: false,
+      message: "No work-kit state found. Nothing to cancel.",
+    };
+  }
+
+  const state = readState(root);
+
+  if (state.status === "completed") {
+    return {
+      action: "error",
+      slug: state.slug,
+      worktreeRemoved: false,
+      branchDeleted: false,
+      message: `${state.slug} is already completed. Nothing to cancel.`,
+    };
+  }
+
+  const slug = state.slug;
+  const branch = state.branch;
+  const mainRoot = resolveMainRepoRoot(root);
+  const isWorktree = path.resolve(root) !== path.resolve(mainRoot);
+
+  let worktreeRemoved = false;
+  let branchDeleted = false;
+
+  // Remove .work-kit/ state directory
+  const stDir = stateDir(root);
+  if (fs.existsSync(stDir)) {
+    fs.rmSync(stDir, { recursive: true, force: true });
+  }
+
+  // Remove the worktree (if we're in one)
+  if (isWorktree) {
+    try {
+      execFileSync("git", ["worktree", "remove", root, "--force"], {
+        cwd: mainRoot,
+        encoding: "utf-8",
+        timeout: 10000,
+      });
+      worktreeRemoved = true;
+    } catch {
+      // Worktree removal failed — may need manual cleanup
+    }
+  }
+
+  // Delete the feature branch
+  if (branch) {
+    try {
+      execFileSync("git", ["branch", "-D", branch], {
+        cwd: mainRoot,
+        encoding: "utf-8",
+        timeout: 5000,
+      });
+      branchDeleted = true;
+    } catch {
+      // Branch may not exist or may be checked out elsewhere
+    }
+  }
+
+  return {
+    action: "cancelled",
+    slug,
+    branch,
+    worktreeRemoved,
+    branchDeleted,
+    message: `Cancelled ${slug}.${worktreeRemoved ? " Worktree removed." : ""}${branchDeleted ? " Branch deleted." : ""}`,
+  };
+}

package/cli/src/commands/complete.ts

@@ -108,8 +108,16 @@ export function completeCommand(target: string, outcome?: string, worktreeRoot?:
       return { action: "complete", message: "All phases complete. Work-kit finished." };
     }
 
-    state.currentPhase = null;
-    state.currentSubStage = null;
+    // Mark the first pending sub-stage of the next phase as "waiting"
+    // so the observer can distinguish "running" from "waiting for human"
+    const nextSubs = Object.entries(state.phases[nextPhase].subStages);
+    const firstPending = nextSubs.find(([_, ss]) => ss.status === "pending");
+    if (firstPending) {
+      firstPending[1].status = "waiting";
+    }
+
+    state.currentPhase = nextPhase;
+    state.currentSubStage = firstPending ? firstPending[0] : null;
     writeState(root, state);
 
     return {
@@ -156,7 +164,7 @@ function archiveCompleted(worktreeRoot: string, state: WorkKitState): void {
   const mainRoot = resolveMainRepoRoot(worktreeRoot);
   const date = new Date().toISOString().split("T")[0];
   const slug = state.slug;
-  const wkDir = path.join(mainRoot, ".claude", "work-kit");
+  const wkDir = path.join(mainRoot, ".work-kit-tracker");
   const archiveDir = path.join(wkDir, "archive");
 
   // Ensure directories exist

package/cli/src/commands/init.ts

@@ -91,6 +91,19 @@ ${description}
   return md;
 }
 
+function ensureGitignored(worktreeRoot: string): void {
+  const gitignorePath = path.join(worktreeRoot, ".gitignore");
+  const entry = ".work-kit/";
+
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, "utf-8");
+    if (content.split("\n").some((line) => line.trim() === entry)) return;
+    fs.appendFileSync(gitignorePath, `\n${entry}\n`);
+  } else {
+    fs.writeFileSync(gitignorePath, `${entry}\n`);
+  }
+}
+
 export function initCommand(options: {
   mode: "full" | "auto";
   description: string;
@@ -171,6 +184,9 @@ export function initCommand(options: {
     },
   };
 
+  // Ensure .work-kit/ is gitignored (temp working state, not for commits)
+  ensureGitignored(worktreeRoot);
+
   // Write state files
   writeState(worktreeRoot, state);
   writeStateMd(worktreeRoot, generateStateMd(slug, branch, modeLabel, description, classification, workflow));

package/cli/src/commands/next.ts

@@ -48,7 +48,7 @@ export function nextCommand(worktreeRoot?: string): Action {
       state.phases[phase].startedAt = new Date().toISOString();
 
       const subStages = Object.entries(state.phases[phase].subStages);
-      const firstActive = subStages.find(([_, ss]) => ss.status === "pending");
+      const firstActive = subStages.find(([_, ss]) => ss.status === "pending" || ss.status === "waiting");
 
       if (!firstActive) {
         return { action: "error", message: `No pending sub-stages in ${phase}` };

package/cli/src/commands/observe.ts

@@ -30,12 +30,17 @@ export async function observeCommand(opts: { mainRepo?: string }): Promise<void>
     : findMainRepoRoot(process.cwd());
 
   let scrollOffset = 0;
+  let tick = 0;
+  let tickInterval: ReturnType<typeof setInterval> | null = null;
   let cleanedUp = false;
 
   function cleanup(): void {
     if (cleanedUp) return;
     cleanedUp = true;
 
+    // Stop tick interval
+    if (tickInterval) { clearInterval(tickInterval); tickInterval = null; }
+
     // Restore terminal
     exitAlternateScreen();
     if (process.stdin.isTTY && process.stdin.setRawMode) {
@@ -54,7 +59,7 @@ export async function observeCommand(opts: { mainRepo?: string }): Promise<void>
     }
 
     const data = collectDashboardData(mainRepoRoot, watcher.getWorktrees());
-    const frame = moveCursorHome() + renderDashboard(data, width, height, scrollOffset);
+    const frame = moveCursorHome() + renderDashboard(data, width, height, scrollOffset, tick);
     process.stdout.write(frame);
   }
 
@@ -80,6 +85,12 @@ export async function observeCommand(opts: { mainRepo?: string }): Promise<void>
     // Initial render
     render();
 
+    // Tick interval for flashing active stage indicator
+    tickInterval = setInterval(() => {
+      tick++;
+      render();
+    }, 500);
+
     // Handle terminal resize
     process.stdout.on("resize", () => {
       render();

package/cli/src/commands/status.ts

@@ -30,7 +30,7 @@ export function statusCommand(worktreeRoot?: string): StatusOutput {
       if (ss.status === "skipped") continue;
       total++;
       if (ss.status === "completed") completed++;
-      else if (ss.status === "in-progress") active++;
+      else if (ss.status === "in-progress" || ss.status === "waiting") active++;
     }
     phases[phase] = { status: ps.status, completed, total, active };
   }

package/cli/src/engine/transitions.ts

@@ -17,7 +17,7 @@ export function nextSubStageInPhase(state: WorkKitState, phase: PhaseName): stri
 
   for (const ss of subStages) {
     const ssState = phaseState.subStages[ss];
-    if (ssState && (ssState.status === "pending" || ssState.status === "in-progress")) {
+    if (ssState && (ssState.status === "pending" || ssState.status === "in-progress" || ssState.status === "waiting")) {
       return ss;
     }
   }

package/cli/src/index.ts

@@ -16,6 +16,7 @@ import { completionsCommand } from "./commands/completions.js";
 import { observeCommand } from "./commands/observe.js";
 import { uninstallCommand } from "./commands/uninstall.js";
 import { bootstrapCommand } from "./commands/bootstrap.js";
+import { cancelCommand } from "./commands/cancel.js";
 import { bold, green, yellow, red } from "./utils/colors.js";
 import type { Classification, PhaseName } from "./state/schema.js";
 
@@ -269,4 +270,21 @@ program
     }
   });
 
+// ── cancel ──────────────────────────────────────────────────────────
+
+program
+  .command("cancel")
+  .description("Cancel the active work-kit, remove worktree and branch")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = cancelCommand(opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.action === "error" ? 1 : 0);
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/cli/src/observer/data.ts

@@ -16,6 +16,7 @@ export interface WorkItemView {
   currentPhase: string | null;
   currentSubStage: string | null;
   currentPhaseStartedAt?: string;
+  currentSubStageStatus?: string;
   currentSubStageIndex?: number;
   currentPhaseTotal?: number;
   startedAt: string;
@@ -92,6 +93,7 @@ export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
 
   // Track current phase substage position
   let currentPhaseStartedAt: string | undefined;
+  let currentSubStageStatus: string | undefined;
   let currentSubStageIndex: number | undefined;
   let currentPhaseTotal: number | undefined;
 
@@ -105,9 +107,11 @@ export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
       continue;
     }
 
+    // If any sub-stage is "waiting", show the phase as waiting in the view
+    const hasWaiting = Object.values(phase.subStages).some(ss => ss.status === "waiting");
     phaseViews.push({
       name: phaseName,
-      status: phase.status,
+      status: hasWaiting ? "waiting" : phase.status,
       startedAt: phase.startedAt,
       completedAt: phase.completedAt,
     });
@@ -134,10 +138,12 @@ export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
       if (phaseName === state.currentPhase) {
         currentPhaseStartedAt = phase.startedAt;
         currentPhaseTotal = activeKeys.length;
-        const idx = state.currentSubStage
-          ? activeKeys.indexOf(state.currentSubStage)
-          : -1;
-        currentSubStageIndex = idx >= 0 ? idx + 1 : undefined;
+        if (state.currentSubStage) {
+          const idx = activeKeys.indexOf(state.currentSubStage);
+          currentSubStageIndex = idx >= 0 ? idx + 1 : undefined;
+          const ss = phase.subStages[state.currentSubStage];
+          currentSubStageStatus = ss?.status;
+        }
       }
     }
   }
@@ -166,6 +172,7 @@ export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
     currentPhase: state.currentPhase,
     currentSubStage: state.currentSubStage,
     currentPhaseStartedAt,
+    currentSubStageStatus,
     currentSubStageIndex,
     currentPhaseTotal,
     startedAt: state.started,
@@ -188,7 +195,7 @@ function getAutoKitPhases(state: WorkKitState): PhaseName[] {
 // ── Collect Completed Items ─────────────────────────────────────────
 
 export function collectCompletedItems(mainRepoRoot: string): CompletedItemView[] {
-  const indexPath = path.join(mainRepoRoot, ".claude", "work-kit", "index.md");
+  const indexPath = path.join(mainRepoRoot, ".work-kit-tracker", "index.md");
   if (!fs.existsSync(indexPath)) return [];
 
   let content: string;
@@ -252,11 +259,13 @@ export function collectDashboardData(mainRepoRoot: string, cachedWorktrees?: str
   });
 
   // Merge completed items from worktrees and index file, dedup by slug
+  // Also exclude any slug that is currently active (re-initialized features)
+  const activeSlugs = new Set(activeItems.map(i => i.slug));
   const indexItems = collectCompletedItems(mainRepoRoot);
   const seen = new Set(completedFromWorktrees.map(i => i.slug));
   const completedItems = [
-    ...completedFromWorktrees,
-    ...indexItems.filter(i => !seen.has(i.slug)),
+    ...completedFromWorktrees.filter(i => !activeSlugs.has(i.slug)),
+    ...indexItems.filter(i => !seen.has(i.slug) && !activeSlugs.has(i.slug)),
   ];
 
   return {

package/cli/src/observer/renderer.ts

@@ -90,10 +90,11 @@ function renderProgressBar(
 
 // ── Phase Status Indicators ─────────────────────────────────────────
 
-function phaseIndicator(status: string): string {
+function phaseIndicator(status: string, tick: number = 0): string {
   switch (status) {
     case "completed": return green("✓");
-    case "in-progress": return cyan("▶");
+    case "in-progress": return tick % 2 === 0 ? cyan("▶") : dim("▶");
+    case "waiting": return tick % 2 === 0 ? yellow("◉") : dim("◉");
     case "pending": return dim("·");
     case "skipped": return dim("⊘");
     case "failed": return red("✗");
@@ -118,7 +119,7 @@ function formatMode(mode: string, classification?: string): string {
   return classification ? `${label} · ${classification}` : label;
 }
 
-function renderWorkItem(item: WorkItemView, innerWidth: number): string[] {
+function renderWorkItem(item: WorkItemView, innerWidth: number, tick: number = 0): string[] {
   const lines: string[] = [];
 
   // Line 1: slug + branch (right-aligned)
@@ -156,16 +157,22 @@ function renderWorkItem(item: WorkItemView, innerWidth: number): string[] {
   ));
 
   // Line 4: phase indicators with sub-stage shown under current phase
-  const phaseStrs = item.phases.map(p => `${p.name} ${phaseIndicator(p.status)}`);
+  const phaseStrs = item.phases.map(p => `${p.name} ${phaseIndicator(p.status, tick)}`);
   lines.push("  " + phaseStrs.join("  "));
 
   // Line 5 (optional): current sub-stage detail under the phase line
   if (item.currentSubStage && item.currentPhase) {
+    const isWaiting = item.currentSubStageStatus === "waiting";
     let subLabel = `↳ ${item.currentSubStage}`;
     if (item.currentSubStageIndex != null && item.currentPhaseTotal != null) {
       subLabel += ` (${item.currentSubStageIndex}/${item.currentPhaseTotal})`;
     }
-    lines.push("    " + dim(subLabel));
+    if (isWaiting) {
+      const badge = tick % 2 === 0 ? bgYellow(" WAITING ") : dim(" WAITING ");
+      lines.push("    " + yellow(subLabel) + "  " + badge);
+    } else {
+      lines.push("    " + (tick % 2 === 0 ? cyan(subLabel) : dim(subLabel)));
+    }
   }
 
   // Line 5 (optional): loopbacks
@@ -217,7 +224,8 @@ export function renderDashboard(
   data: DashboardData,
   width: number,
   height: number,
-  scrollOffset: number = 0
+  scrollOffset: number = 0,
+  tick: number = 0
 ): string {
   const maxWidth = Math.min(width, 120);
   const innerWidth = maxWidth - 4; // account for "║ " and " ║"
@@ -261,7 +269,7 @@ export function renderDashboard(
 
       for (let i = 0; i < data.activeItems.length; i++) {
         const item = data.activeItems[i];
-        const itemLines = renderWorkItem(item, innerWidth);
+        const itemLines = renderWorkItem(item, innerWidth, tick);
         for (const line of itemLines) {
           allLines.push(boxLine(line, innerWidth));
         }

package/cli/src/state/helpers.ts

@@ -38,7 +38,7 @@ export function resetToLocation(state: WorkKitState, location: Location): void {
   let reset = false;
   for (const [ss, ssState] of Object.entries(targetPhaseState.subStages)) {
     if (ss === location.subStage) reset = true;
-    if (reset && ssState.status === "completed") {
+    if (reset && (ssState.status === "completed" || ssState.status === "waiting")) {
       ssState.status = "pending";
       delete ssState.completedAt;
       delete ssState.outcome;

package/cli/src/state/schema.ts

@@ -35,7 +35,7 @@ export type Classification = "bug-fix" | "small-change" | "refactor" | "feature"
 // ── Phase & Sub-stage State ──────────────────────────────────────────
 
 export type PhaseStatus = "pending" | "in-progress" | "completed" | "skipped";
-export type SubStageStatus = "pending" | "in-progress" | "completed" | "skipped";
+export type SubStageStatus = "pending" | "in-progress" | "completed" | "skipped" | "waiting";
 
 export interface SubStageState {
   status: SubStageStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "work-kit-cli",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Structured development workflow for Claude Code. Two modes, 6 phases, 27 sub-stages.",
   "type": "module",
   "bin": {

package/skills/auto-kit/SKILL.md

@@ -2,7 +2,7 @@
 name: auto-kit
 description: "Smart pipeline that analyzes the request and builds a dynamic workflow. Usage: /auto-kit <description> to start, /auto-kit to continue."
 user-invocable: true
-argument-hint: "[description]"
+argument-hint: "[--gated] [description]"
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep
 ---
 
@@ -97,7 +97,7 @@ The table is a guide, not a rigid rule. Adjust based on the actual request:
    cd worktrees/<slug>
    npx work-kit-cli init --mode auto --description "<description>" --classification <classification>
    ```
-   If the user requested gated mode (manual approval between phases), add `--gated`.
+   If the user passed `--gated` (e.g., `/auto-kit --gated fix login bug`), add `--gated` to the init command. Strip `--gated` from the description text.
 2. Show the workflow to the user: `npx work-kit-cli workflow`
 3. User can adjust: `npx work-kit-cli workflow --add review/security` or `npx work-kit-cli workflow --remove test/e2e`
 4. **Wait for approval** — user can add/remove steps before proceeding

package/skills/cancel-kit/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: cancel-kit
+description: "Cancel the active work-kit session. Removes state, worktree, and feature branch."
+user-invocable: true
+allowed-tools: Bash, Read
+---
+
+# Cancel Kit
+
+Cancels the active work-kit session and cleans up all artifacts.
+
+## What it does
+
+1. Finds the active work-kit session (via `bootstrap`)
+2. Confirms with the user before proceeding
+3. Runs `npx work-kit-cli cancel` to:
+   - Remove `.work-kit/` state directory
+   - Remove the git worktree
+   - Delete the feature branch
+4. Reports what was cleaned up
+
+## Instructions
+
+1. Run `npx work-kit-cli bootstrap` to detect the active session
+2. If no active session: tell the user there's nothing to cancel
+3. If active: show the user what will be cancelled:
+   - Slug and branch name
+   - Current phase and sub-stage
+   - Any uncommitted work in the worktree will be lost
+4. **Ask the user to confirm** — do not proceed without explicit confirmation
+5. `cd` into the worktree directory
+6. Run `npx work-kit-cli cancel`
+7. `cd` back to the main repo root
+8. Report the result to the user

package/skills/full-kit/SKILL.md

@@ -2,7 +2,7 @@
 name: full-kit
 description: "Full pipeline for feature development. Runs all phases and sub-stages in order. Usage: /full-kit <description> to start, /full-kit to continue."
 user-invocable: true
-argument-hint: "[description]"
+argument-hint: "[--gated] [description]"
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep
 ---
 
@@ -39,7 +39,7 @@ Do not proceed until `doctor` reports all checks passed.
    cd worktrees/<slug>
    npx work-kit-cli init --mode full --description "<description>"
    ```
-   If the user requested gated mode (manual approval between phases), add `--gated`.
+   If the user passed `--gated` (e.g., `/full-kit --gated add user avatar`), add `--gated` to the init command. Strip `--gated` from the description text.
 2. Parse the JSON response and follow the action
 3. Continue with the execution loop below
 

package/skills/wk-deploy/stages/merge.md

@@ -13,14 +13,18 @@ description: "Deploy sub-stage: Get the PR merged safely."
    ```bash
    git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"
    ```
-2. Sync the feature branch with the default branch:
+2. Remove `.work-kit/` from git tracking before merging (state is transient — the archive in `.work-kit-tracker/` is the permanent record):
+   ```bash
+   git rm -r --cached .work-kit/ 2>/dev/null && git commit -m "work-kit: remove transient state before merge" || true
+   ```
+3. Sync the feature branch with the default branch:
    ```bash
    git fetch origin
    git rebase origin/<default-branch>
    ```
    If rebase conflicts occur, resolve them. If they're non-trivial, report to the user and abort.
-3. If a PR exists, check CI status — all checks must pass. If CI fails, diagnose and fix (loop back to Build if needed).
-4. Merge automatically using the project's preferred method (check CONTRIBUTING.md or README; default to squash):
+4. If a PR exists, check CI status — all checks must pass. If CI fails, diagnose and fix (loop back to Build if needed).
+5. Merge automatically using the project's preferred method (check CONTRIBUTING.md or README; default to squash):
    - If a PR exists: merge via `gh pr merge --squash --delete-branch`
    - If no PR: merge locally:
      ```bash

package/skills/wk-wrap-up/SKILL.md

@@ -12,16 +12,16 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 
 ## Instructions
 
-> **Note:** Archiving state.md and appending to `.claude/work-kit/index.md` are handled automatically by the CLI when you run `work-kit complete` on the last sub-stage. You do NOT need to do these manually.
+> **Note:** Archiving state.md and appending to `.work-kit-tracker/index.md` are handled automatically by the CLI when you run `work-kit complete` on the last sub-stage. You do NOT need to do these manually.
 
 1. **Read the full `.work-kit/state.md`** — every phase output from Plan through the last completed phase
 2. **Synthesize the work-kit log entry** — not a copy-paste of state, but a distilled record that a future developer (or agent) would find useful
-3. **Write the summary file** to `.claude/work-kit/<date>-<slug>.md` on the **main branch** (not the worktree)
+3. **Write the summary file** to `.work-kit-tracker/<date>-<slug>.md` on the **main branch** (not the worktree)
 4. **Ask the user** if they want the worktree and branch removed
 
 ## Work-Kit Log Entry Format
 
-Write to `.claude/work-kit/<YYYY-MM-DD>-<slug>.md`:
+Write to `.work-kit-tracker/<YYYY-MM-DD>-<slug>.md`:
 
 ```markdown
 ---
@@ -88,7 +88,7 @@ After writing the summary:
 1. Switch to main branch: `cd` back to the main repo root
 2. Stage and commit all work-kit log files:
    ```bash
-   git add .claude/work-kit/
+   git add .work-kit-tracker/
    git commit -m "work-kit: <slug>"
    ```
 3. Remove the worktree and delete the feature branch (merge already happened, cleanup is safe):