compound-workflow 1.1.1 → 1.3.0

package/README.md

@@ -29,7 +29,7 @@ npx compound-workflow install
 
 **What Install does:** Merges `AGENTS.md` (preserves your Repo Config Block), creates standard dirs (`docs/`, `todos/`), writes `opencode.json` (for OpenCode), and—if the project has a `.cursor` directory—creates `.cursor/skills/<skill>`, `.cursor/agents`, `.cursor/commands`, and `.cursor/references` (symlinks into the package). All paths reference `node_modules/compound-workflow`; no file copying.
 
-**CLI options:** `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder).
+**CLI options:** `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder), `--cursor` (create `.cursor` and wire Cursor symlinks even if `.cursor` does not already exist).
 
 **Legacy (clone inside repo):** If you cloned this repo inside a host repo and need to copy files without npm, use `./scripts/sync-into-repo.sh` (copy only; does not update opencode.json). Prefer the npm + Install flow above.
 
@@ -131,7 +131,7 @@ Full detail: [src/AGENTS.md](src/AGENTS.md), [src/.agents/commands/](src/.agents
 
 Commands are the public API. Skills and agents are invoked by commands; you don’t call them directly.
 
-- **Workflow skills:** `brainstorming`, `file-todos`, `compound-docs`, `document-review`, `technical-review`, `git-worktree`, `agent-browser`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`.
+- **Workflow skills:** `brainstorming`, `file-todos`, `compound-docs`, `document-review`, `technical-review`, `git-worktree`, `agent-browser`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`, `standards`.
 - **State orchestration:** Use a state-orchestration skill when complexity exceeds simple local state (e.g. `xstate-actor-orchestration` per Skill Index)—UI container-as-orchestrator flows, backend/internal actor orchestration, receptionist/child-actor patterns, retries/timeouts/cancellation, or boolean-flag sprawl.
 - **Skill-local metadata:** Some skills may include tool-specific metadata under `src/.agents/skills/<skill>/agents/` (for example `openai.yaml`) when required by skill validation/runtime.
 - **Guardrail standards:** `data-foundations`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability` — applied when work touches multi-tenant data, PII, money, or audit.
@@ -159,6 +159,8 @@ Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.
 
 **Skills not showing in Cursor?** Cursor discovers skills from (1) the plugin’s `skills/` directory when you load the plugin from this repo, or (2) the project’s `.cursor/skills/` when you use npm: ensure the project has a `.cursor` directory and run `npx compound-workflow install`—Install creates the full structure (`.cursor/skills/<skill>`, `.cursor/agents`, `.cursor/commands`, `.cursor/references`). If skills still don’t appear, check Cursor Settings → Rules and any `permission.skill` settings.
 
+If your project does not already have `.cursor/`, run `npx compound-workflow install --cursor` to create it and wire links. Install now fails fast when existing non-symlink files/directories block `.cursor` link creation, to prevent partial installs and command drift.
+
 **Skills not showing in OpenCode?** OpenCode uses the `.agents/compound-workflow-skills` symlink and `opencode.json` `skills.paths`. Run Install from the project root (`npx compound-workflow install`). The learnings-capture skill is named **compound-docs** (hyphen, plural); **compound_doc** (underscore) is an alias that resolves to the same skill.
 
 ---

package/package.json

@@ -1 +1 @@
-{"name":"compound-workflow","version":"1.1.1","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"scripts":{"check:pack-readme":"node scripts/check-pack-readme.mjs"},"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}
+{"name":"compound-workflow","version":"1.3.0","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"scripts":{"check:pack-readme":"node scripts/check-pack-readme.mjs"},"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}

package/scripts/install-cli.mjs

@@ -14,7 +14,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function usage(exitCode = 0) {
   const msg = `
 Usage:
-  npx compound-workflow install [--root <projectDir>] [--dry-run] [--no-config]
+  npx compound-workflow install [--root <projectDir>] [--dry-run] [--no-config] [--cursor]
 
 One action: writes opencode.json (loads from package), merges AGENTS.md, creates dirs,
 and prompts for Repo Config Block (unless --no-config).
@@ -22,17 +22,19 @@ and prompts for Repo Config Block (unless --no-config).
   --root <dir>   Project directory (default: cwd)
   --dry-run      Print planned changes only
   --no-config   Skip Repo Config Block prompt (only write opencode.json + AGENTS.md + dirs)
+  --cursor      Force Cursor integration (create .cursor if missing, then wire links)
 `;
   (exitCode === 0 ? console.log : console.error)(msg.trimStart());
   process.exit(exitCode);
 }
 
 function parseArgs(argv) {
-  const out = { root: process.cwd(), dryRun: false, noConfig: false };
+  const out = { root: process.cwd(), dryRun: false, noConfig: false, cursor: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--dry-run") out.dryRun = true;
     else if (a === "--no-config") out.noConfig = true;
+    else if (a === "--cursor") out.cursor = true;
     else if (a === "--root") {
       const v = argv[i + 1];
       if (!v) usage(1);
@@ -233,11 +235,11 @@ function ensureSkillsSymlink(targetRoot, dryRun) {
   }
 }
 
-function ensureCursorDirSymlink(targetRoot, cursorSubdir, pkgSubdir, dryRun, label) {
+function ensureCursorDirSymlink(targetRoot, cursorSubdir, pkgSubdir, dryRun, label, cursorReady) {
   const cursorDir = path.join(targetRoot, ".cursor");
-  if (!fs.existsSync(cursorDir)) return;
+  if (!cursorReady) return { status: "skipped-missing-cursor" };
   const pkgPath = path.join(packageRoot, "src", ".agents", pkgSubdir);
-  if (!fs.existsSync(pkgPath)) return;
+  if (!fs.existsSync(pkgPath)) return { status: "skipped-missing-package-path" };
 
   const linkPath = path.join(cursorDir, cursorSubdir);
   const targetRel = path.join("..", "node_modules", "compound-workflow", "src", ".agents", pkgSubdir);
@@ -245,7 +247,7 @@ function ensureCursorDirSymlink(targetRoot, cursorSubdir, pkgSubdir, dryRun, lab
 
   if (dryRun) {
     console.log("[dry-run] Would create .cursor/" + cursorSubdir, "symlink (Cursor)");
-    return;
+    return { status: "dry-run" };
   }
 
   let needCreate = true;
@@ -254,7 +256,7 @@ function ensureCursorDirSymlink(targetRoot, cursorSubdir, pkgSubdir, dryRun, lab
     if (stat.isSymbolicLink() && symlinkPointsTo(linkPath, targetAbs)) needCreate = false;
     else if (!stat.isSymbolicLink()) {
       console.warn("Skipped", ".cursor/" + cursorSubdir, "because it exists and is not a symlink");
-      return;
+      return { status: "blocked-nonsymlink", path: linkPath };
     }
   } catch (_) {}
 
@@ -263,15 +265,17 @@ function ensureCursorDirSymlink(targetRoot, cursorSubdir, pkgSubdir, dryRun, lab
     const type = process.platform === "win32" ? "dir" : "dir";
     fs.symlinkSync(targetRel, linkPath, type);
     console.log("Created", ".cursor/" + cursorSubdir, "->", label || pkgSubdir, "(Cursor)");
+    return { status: "created" };
   }
+  return { status: "ok" };
 }
 
-function ensureCursorSkills(targetRoot, dryRun) {
+function ensureCursorSkills(targetRoot, dryRun, cursorReady) {
   const cursorDir = path.join(targetRoot, ".cursor");
-  if (!fs.existsSync(cursorDir)) return;
+  if (!cursorReady) return { blocked: [] };
 
   const packageSkillsDir = path.join(packageRoot, "src", ".agents", "skills");
-  if (!fs.existsSync(packageSkillsDir)) return;
+  if (!fs.existsSync(packageSkillsDir)) return { blocked: [] };
 
   const skillNames = [];
   try {
@@ -290,11 +294,19 @@ function ensureCursorSkills(targetRoot, dryRun) {
 
   if (dryRun) {
     console.log("[dry-run] Would create .cursor/skills/<skill> symlinks for:", skillNames.join(", "));
-    return;
+    return { blocked: [] };
   }
 
   if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
+  else {
+    const stat = fs.lstatSync(skillsDir);
+    if (!stat.isDirectory()) {
+      console.warn("Skipped .cursor/skills because it exists and is not a directory");
+      return { blocked: [skillsDir] };
+    }
+  }
 
+  const blocked = [];
   for (const name of skillNames) {
     const linkPath = path.join(skillsDir, name);
     const targetRel = path.join("..", "..", "..", "node_modules", "compound-workflow", "src", ".agents", "skills", name);
@@ -305,6 +317,7 @@ function ensureCursorSkills(targetRoot, dryRun) {
       if (stat.isSymbolicLink() && symlinkPointsTo(linkPath, targetAbs)) needCreate = false;
       else if (!stat.isSymbolicLink()) {
         console.warn("Skipped", ".cursor/skills/" + name, "because it exists and is not a symlink");
+        blocked.push(linkPath);
         continue;
       }
     } catch (_) {}
@@ -315,13 +328,67 @@ function ensureCursorSkills(targetRoot, dryRun) {
       console.log("Created", ".cursor/skills/" + name, "-> package skill (Cursor)");
     }
   }
+  return { blocked };
+}
+
+function verifyCursorIntegration(targetRoot) {
+  const cursorDir = path.join(targetRoot, ".cursor");
+  if (!fs.existsSync(cursorDir)) return [];
+
+  const checks = [
+    { name: ".cursor/agents", rel: path.join("agents") },
+    { name: ".cursor/commands", rel: path.join("commands") },
+    { name: ".cursor/references", rel: path.join("references") },
+  ];
+  const issues = [];
+
+  for (const check of checks) {
+    const linkPath = path.join(cursorDir, check.rel);
+    const expectedAbs = path.join(targetRoot, "node_modules", "compound-workflow", "src", ".agents", check.rel);
+    if (!symlinkPointsTo(linkPath, expectedAbs)) issues.push(`${check.name} is missing or not linked to package`);
+  }
+
+  const workCommand = path.join(cursorDir, "commands", "workflow", "work.md");
+  if (!fs.existsSync(workCommand)) {
+    issues.push(".cursor/commands/workflow/work.md is not reachable after integration");
+  }
+  return issues;
 }
 
-function ensureCursorIntegration(targetRoot, dryRun) {
-  ensureCursorSkills(targetRoot, dryRun);
-  ensureCursorDirSymlink(targetRoot, "agents", "agents", dryRun, "package agents");
-  ensureCursorDirSymlink(targetRoot, "commands", "commands", dryRun, "package commands");
-  ensureCursorDirSymlink(targetRoot, "references", "references", dryRun, "package references");
+function ensureCursorIntegration(targetRoot, dryRun, forceCursor) {
+  const cursorDir = path.join(targetRoot, ".cursor");
+  let cursorReady = fs.existsSync(cursorDir);
+  if (!fs.existsSync(cursorDir)) {
+    if (!forceCursor) return { issues: [] };
+    if (dryRun) console.log("[dry-run] Would create .cursor directory (Cursor)");
+    else {
+      fs.mkdirSync(cursorDir, { recursive: true });
+      cursorReady = true;
+    }
+    if (dryRun) cursorReady = true;
+  }
+
+  const skillReport = ensureCursorSkills(targetRoot, dryRun, cursorReady);
+  const dirReports = [
+    ensureCursorDirSymlink(targetRoot, "agents", "agents", dryRun, "package agents", cursorReady),
+    ensureCursorDirSymlink(targetRoot, "commands", "commands", dryRun, "package commands", cursorReady),
+    ensureCursorDirSymlink(targetRoot, "references", "references", dryRun, "package references", cursorReady),
+  ];
+
+  const issues = [];
+  if (skillReport?.blocked?.length) {
+    for (const p of skillReport.blocked) issues.push(`${path.relative(targetRoot, p)} blocks symlink creation (not a symlink)`);
+  }
+  for (const report of dirReports) {
+    if (report?.status === "blocked-nonsymlink") {
+      issues.push(`${path.relative(targetRoot, report.path)} blocks symlink creation (not a symlink)`);
+    }
+  }
+
+  if (!dryRun) {
+    for (const issue of verifyCursorIntegration(targetRoot)) issues.push(issue);
+  }
+  return { issues };
 }
 
 function writeOpenCodeJson(targetRoot, dryRun) {
@@ -472,10 +539,19 @@ function main() {
   writeOpenCodeJson(targetRoot, args.dryRun);
   ensureSkillsSymlink(targetRoot, args.dryRun);
   reportOpenCodeIntegration(targetRoot, args.dryRun);
-  ensureCursorIntegration(targetRoot, args.dryRun);
+  const cursorReport = ensureCursorIntegration(targetRoot, args.dryRun, args.cursor);
   writeAgentsMd(targetRoot, args.dryRun);
   ensureDirs(targetRoot, args.dryRun);
 
+  if (cursorReport.issues.length) {
+    console.error("\nCursor integration drift detected:");
+    for (const issue of cursorReport.issues) console.error("-", issue);
+    if (!args.dryRun) {
+      console.error("Fix blockers (or remove conflicting paths) and rerun install.");
+      process.exit(2);
+    }
+  }
+
   if (!args.noConfig && !args.dryRun && process.stdin.isTTY) {
     console.log("\nRepo Config: edit AGENTS.md to set default_branch, test_command, lint_command, dev_server_url.");
   }

package/src/.agents/commands/workflow/triage.md

@@ -1,19 +1,19 @@
 ---
 name: triage
 invocation: workflow:triage
-description: Triage pending todo files into an executable ready queue (priority, dependencies, recommended action)
-argument-hint: "[optional: todo path, issue id, or 'pending' (default)]"
+description: Triage and prioritize todo files into an executable ready queue (priority, dependencies, recommended action)
+argument-hint: "[optional: todo path, issue id, status filter ('pending'|'ready'|'active')]"
 ---
 
 # /workflow:triage
 
-Turn `todos/*-pending-*.md` items into an executable queue.
+Turn todo items into a prioritized executable queue.
 
 This command does not implement fixes. It approves and organizes work so `/workflow:work` can execute without ambiguity.
 
 ## Inputs
 
-- Default: triage all pending todos under `todos/`
+- Default: triage all active todos under `todos/` (`pending` + `ready`)
 - Optional: a specific todo file path or issue id
 
 ## Preconditions
@@ -24,9 +24,9 @@ This command does not implement fixes. It approves and organizes work so `/workf
 ## Workflow
 
 1. Identify the target set:
-   - all `todos/*-pending-*.md`, or
+   - all active todos (`todos/*-pending-*.md` + `todos/*-ready-*.md`), or
    - the requested todo
-2. For each pending todo:
+2. For each target todo:
    - read Problem Statement + Findings + Proposed Solutions
    - fill **Recommended Action** (make it executable)
    - set `priority` (`p1|p2|p3`)
@@ -45,8 +45,9 @@ This command does not implement fixes. It approves and organizes work so `/workf
    - **Blocking spikes first:** If a spike unblocks downstream build todos, prioritize approving that spike before its dependents. Do not approve dependent build todos as executable ahead of unresolved blocking spikes.
    - **Parallel spike readiness:** If multiple spike todos are independent (no dependency edges between them), they may be approved together for parallel execution.
 3. Decision:
-   - **approve now** -> rename `*-pending-*` -> `*-ready-*` and set frontmatter `status: ready` (only when Acceptance Criteria and Agentic Execution Contract are executable)
-   - **defer** -> rename `*-pending-*` -> `*-deferred-*` and set frontmatter `status: deferred` (keep priority, typically `p3`). Ensure Recommended Action, Findings, and Work Log have enough context for future reference. Deferred items are not executed until re-triaged to `ready`.
+   - **approve now** -> if pending, rename `*-pending-*` -> `*-ready-*` and set frontmatter `status: ready`; if already ready, keep `status: ready` and update priority/dependencies as needed
+   - **defer** -> rename `*-pending-*` or `*-ready-*` -> `*-deferred-*` and set frontmatter `status: deferred` (keep priority, typically `p3`). Ensure Recommended Action, Findings, and Work Log have enough context for future reference. Deferred items are not executed until re-triaged to `ready`.
+   - **needs rework** -> when a `ready` todo is not executable, rename `*-ready-*` -> `*-pending-*`, set `status: pending`, and record what is missing before re-approval.
    - **blocked follow-up** -> when work returns a blocked todo, keep it as `pending` (rename from `*-ready-*` when needed), add `tags: [blocker]`, and require blocker options + recommendation in Work Log before re-approval.
 4. Output:
    - list approved `ready` todos (blocking spikes first, then other unblocked items)

package/src/.agents/commands/workflow/work.md

@@ -221,8 +221,9 @@ The input must be a plan file path.
 
    After creating todos:
 
-   - If any todos are `pending`, stop and offer `/workflow:triage` to approve and prioritize before execution.
-   - If all todos are `ready`, proceed to Phase 2.
+   - Run `/workflow:triage` before any implementation work to approve/prioritize the queue for this plan.
+   - Do not proceed to Phase 2 until triage completes and execution order is explicit.
+   - If triage leaves no unblocked `ready` todos, stop and report pending/deferred/blocked items.
 
 ### Phase 2: Execute
 
@@ -249,7 +250,7 @@ The input must be a plan file path.
 
    - If no unblocked `ready` todos remain:
      - summarize remaining `pending`, `deferred` (parked for reference), and blocked items
-     - recommend running `/workflow:triage` for pending items
+     - require re-running `/workflow:triage` for pending/blocked prioritization
      - stop (do not invent work)
 
    For each task in priority order:

package/src/.agents/skills/capture-skill/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: capture-skill
+description: Capture learnings, patterns, or workflows from the current conversation into a new or existing skill. Use when the user wants to save what was learned, discovered, or built during a conversation as a reusable skill for future sessions.
+---
+
+# Capture Skill from Conversation
+
+This skill extracts reusable knowledge from the current conversation and stores it as a skill.
+
+## Default Policy
+
+`capture-skill` uses an overlay model by default:
+
+- Treat existing repo-provided skills as immutable unless the user explicitly asks to edit a specific one.
+- Store project-specific refinements in a project overlay skill (for example, `.agents/skills/project-standards/`).
+- Only modify an existing skill when the user clearly says to do so (for example, "update skill X").
+- Promote overlay content into base skills only as an explicit, deliberate follow-up action.
+
+## When to Use
+
+- The user says "capture this as a skill" or "save this for next time"
+- A reusable workflow, pattern, or piece of domain knowledge emerged
+- The user wants to refine project standards based on this conversation
+- The conversation revealed non-obvious steps, gotchas, or best practices worth preserving
+
+## Capture Process
+
+### Phase 1: Identify What to Capture
+
+Prioritize broad, reusable patterns over one-off implementation details.
+
+Look for:
+
+1. High-level principles and standards
+2. Multi-step workflows discovered through trial and error
+3. Domain constraints that are not obvious
+4. Gotchas and reliable fixes
+5. Decision rationale that establishes a repeatable rule
+
+Summarize the planned capture and confirm with the user before writing.
+
+### Phase 2: Check Related Skills and Consolidate
+
+Before creating a new skill:
+
+1. List existing skills in personal and project locations.
+2. Find related skill scopes.
+3. Decide: consolidate into existing skill, extend an existing skill section, or create a new skill.
+
+Consolidate when content overlaps domain, trigger conditions, or workflow usage.
+
+### Phase 3: Choose Destination
+
+If not already specified:
+
+1. Decide whether this is a new skill or an update.
+2. For new captures, decide storage:
+   - Personal skill directory for cross-project behavior
+   - Project skill directory for project-specific behavior
+3. Apply the default policy:
+   - Prefer project overlay skills for refinements
+   - Do not mutate repo-provided skills by default
+
+### Phase 4: Draft Skill Content
+
+For new skills:
+
+1. Use a descriptive kebab-case name (max 64 chars)
+2. Write a precise description with WHAT + WHEN
+3. Distill into actionable instructions
+4. Add compact examples
+5. Include scripts/assets only when needed
+
+For updates:
+
+1. Read existing `SKILL.md`
+2. Integrate into the best section
+3. Avoid duplication
+4. Keep structure and voice consistent
+
+### Phase 5: Distill for Reuse
+
+Guidelines:
+
+1. Lead with general principles
+2. Generalize from specific files/functions
+3. Explain why the pattern exists
+4. Include only context the agent would not infer
+5. Keep content concise and maintainable (`SKILL.md` under 500 lines)
+
+Do not:
+
+- Store conversation artifacts
+- Overfit to single-file fixes
+- Repeat obvious model knowledge
+- Include excessive implementation trivia
+
+### Phase 6: Write and Verify
+
+If consolidating:
+
+1. Merge into the chosen home skill
+2. Keep sections clear and non-overlapping
+3. Remove obsolete duplicate skills
+4. Update name/description if scope broadened
+
+If creating/updating:
+
+1. Write `SKILL.md`
+2. Verify trigger description accuracy
+3. Verify no duplicate scope across skills
+4. Confirm captured content with the user
+
+## Consolidation Rules
+
+- Prefer fewer, broader, discoverable skills over many narrow duplicates.
+- Group frequently co-used patterns into one skill with clear sections.
+- If overlap is discovered after creation, consolidate immediately.
+
+## Edge Cases
+
+- Multiple unrelated learnings: split into separate skills.
+- Tiny single-rule capture: recommend a rule file instead of a skill.
+- Major rewrite needed: ask whether to restructure or supersede.
+- User asks to evolve standards safely: keep changes in project overlay unless explicit promotion is requested.

package/src/.agents/skills/standards/SKILL.md

@@ -0,0 +1,705 @@
+---
+name: standards
+description: General coding practices, implementation styles, and patterns for the Altai application. Covers domain entities, XState patterns, type usage, and code organization. Use when implementing features, writing new code, or refactoring existing code in the Altai codebase.
+---
+
+# Altai Code Standards
+
+## Core Principles
+
+1. **Simplicity over cleverness** - Prefer straightforward solutions
+2. **Maintainability over flexibility** - Avoid premature abstraction
+3. **YAGNI** - Add complexity when needed, not before
+4. **Domain entities for logic** - Use pure functions in entities for transforms and predicates
+5. **Keep controllers simple** - Delegate complexity to domain entities
+6. **Early exits over else/else-if** - Return early for special cases, avoid nested conditionals
+
+---
+
+## Domain Entities
+
+Location: `src/features/{feature}/domain/entities/`
+
+Domain entities contain **types** and **pure functions** that encapsulate business logic. Use them for transforms, predicates, and any complex logic - keeping controllers/machines simple.
+
+### Structure
+
+- Pure functions, no classes
+- One file per concern (e.g., `PlaylistSelectionEntity.ts` vs `PlaylistReorderEntity.ts`)
+- Private helpers stay internal (no `export`)
+
+### Function Signatures
+
+**Use named params for 2+ arguments:**
+
+```typescript
+// Good - clear at call site
+export const hasAddedPlaylists = ({
+  current,
+  incoming,
+}: PlaylistCompareParams): boolean => {
+  // ...
+};
+
+// Usage
+hasAddedPlaylists({ current: ctx.playlists, incoming: evt.payload.playlists });
+```
+
+**Benefits**: Self-documenting, easier to refactor, better IDE support.
+
+### Naming Conventions
+
+| Prefix | Purpose               | Example                                    |
+| ------ | --------------------- | ------------------------------------------ |
+| `hasX` | Boolean predicate     | `hasAddedPlaylists`, `hasRemovedPlaylists` |
+| `getX` | Retrieve/extract data | `getAddedPlaylists`, `getRemovedPlaylists` |
+| `toX`  | Transform data        | `toPlaylistIds`, `toSortedPlaylistIds`     |
+
+### Early Exit Pattern
+
+**Always prefer early exits over else/else-if** - this is a code standard, not a suggestion.
+
+```typescript
+// ❌ Bad - nested conditionals with else-if
+export const createAction = (params) => {
+  if (params.pendingFolder) {
+    return {
+      metadata: {
+        createFolder: params.pendingFolder,
+        mode: "create",
+      },
+    };
+  } else if (params.existingFolder) {
+    return {
+      metadata: {
+        targetFolder: params.existingFolder,
+        mode: "existing",
+      },
+    };
+  } else {
+    throw new Error("Invalid params");
+  }
+};
+
+// ✅ Good - early exits, flat structure
+export const createAction = (params) => {
+  // Handle special case first
+  if (params.pendingFolder) {
+    return {
+      metadata: {
+        createFolder: params.pendingFolder,
+        mode: "create",
+      },
+    };
+  }
+
+  // Handle next case
+  if (params.existingFolder) {
+    return {
+      metadata: {
+        targetFolder: params.existingFolder,
+        mode: "existing",
+      },
+    };
+  }
+
+  // Invalid state
+  throw new Error("Invalid params");
+};
+```
+
+**Benefits**:
+
+- **Flat code structure** - No nesting, easier to read
+- **Clear intent** - Each case is independent and complete
+- **Easier to modify** - Add/remove cases without touching others
+- **No else-if** - Else-if is a code smell indicating missed early exit opportunities
+
+**When extracting action creation to entities**:
+
+```typescript
+// ✅ Good - early exits for different contexts
+export const createSelectFolderRootAction = ({
+  folder,
+  activeTabId,
+  activeFolderId,
+  pendingFolderName,
+}: Params): PanelActionEntity => {
+  // Early exit - pending folder
+  if (pendingFolderName && activeTabId) {
+    return panelActionEntity.toActionItem(ActionTypes.SHARE, {
+      label: pendingFolderName,
+      metadata: {
+        targetTabId: activeTabId,
+        createFolderName: pendingFolderName,
+        mode: "folderRoot",
+      },
+    });
+  }
+
+  // Early exit - existing folder in share context
+  if (activeTabId && activeFolderId) {
+    return panelActionEntity.toActionItem(ActionTypes.SHARE, {
+      label: folder?.label ?? "Folder",
+      metadata: {
+        targetTabId: activeTabId,
+        targetFolderId: activeFolderId,
+        mode: "folderRoot",
+      },
+    });
+  }
+
+  // Early exit - move to folder context
+  if (activeFolderId) {
+    return panelActionEntity.toActionItem(ActionTypes.MOVE, {
+      label: folder?.label ?? "Folder",
+      metadata: {
+        targetFolderId: activeFolderId,
+        mode: "folderRoot",
+      },
+    });
+  }
+
+  throw new Error("Invalid parameters");
+};
+```
+
+**Anti-patterns to avoid**:
+
+- `else` and `else-if` blocks
+- Conditional spreading: `...(condition && { prop: value })`
+- Let variables modified in conditionals
+- Nested ternaries for complex logic
+
+### When to Use
+
+- **Predicates**: `hasAddedPlaylists`, `isValidState`
+- **Transforms**: `toPlaylistIds`, `toSortedItems`
+- **Comparisons**: Diffing arrays, checking membership
+- **Complex conditionals**: Extract to helper functions
+
+```typescript
+// Extract complex logic to helpers
+const getFolderLabel = (
+  folder: InputOption | ClipsPanelFolderEntity
+): string => {
+  return "label" in folder ? folder.label : (folder.folderName ?? "Folder");
+};
+```
+
+This keeps controllers/machines simple - they delegate logic to entities.
+
+---
+
+## XState Patterns
+
+### Guards (Conditions)
+
+Extract complex guards to domain entity predicates. Inline the entity call in `cond`:
+
+```typescript
+import * as playlistSelectionEntity from "src/features/tapesv3/domain/entities/PlaylistSelectionEntity";
+
+[EventType.PLAYLIST_CHANGED]: [
+  {
+    cond: (ctx, evt) =>
+      playlistSelectionEntity.hasAddedPlaylists({
+        current: ctx.playlists,
+        incoming: evt.payload.playlists,
+      }),
+    actions: [/* ... */],
+  },
+],
+```
+
+Avoid unnecessary wrapper functions - inline entity calls directly.
+
+### State vs Context: Model UI Modes as State
+
+**Use state machines to model UI modes** - don't store mode flags in context:
+
+```typescript
+// Bad - storing mode in context
+type Context = {
+  viewMode: "folder" | "search"; // Don't store what state can represent
+};
+
+// Good - model modes as parallel states
+viewModeManagement: {
+  initial: "folderView",
+  states: {
+    folderView: {
+      on: {
+        [EventType.SYNC_VIEW_MODE]: {
+          cond: (_, evt) => evt.payload.viewMode === "search",
+          target: "searchView",
+        },
+      },
+    },
+    searchView: { /* ... */ },
+  },
+},
+```
+
+**Rationale**: State machines semantically represent modes. Context holds data, not state.
+
+**Exception**: Storing previous values in context for business logic comparison is acceptable:
+
+```typescript
+// Acceptable - storing previous value for change detection
+type Context = {
+  oldHierarchy: Hierarchy | null; // For comparing with newHierarchy
+  viewMode: "folder" | "search"; // For comparing previous vs current in change detection
+};
+```
+
+The distinction: Don't store current UI state in context when it can be modeled as machine state. Do store previous values when needed for comparison logic (change detection, diffing, etc.).
+
+### Event & Type Patterns
+
+**Consolidate similar events with properties:**
+
+```typescript
+// Bad - event proliferation
+BROADCAST_FOLDER_VIEW_MODE;
+BROADCAST_SEARCH_VIEW_MODE;
+
+// Good - single event with property
+BROADCAST_VIEW_MODE: {
+  payload: {
+    viewMode: "folder" | "search";
+  }
+}
+```
+
+**Move reusable types to domain entities:**
+
+```typescript
+// Domain entity: FolderSelectorEntity.ts
+export type FolderSelectorViewMode = "folder" | "search";
+```
+
+Single source of truth, consistent types across controllers/containers.
+
+### assertEvent Usage
+
+**Only use `assertEvent` when TypeScript can't narrow the event type:**
+
+```typescript
+// Bad - redundant, TypeScript already knows the type from transition
+[EventType.SYNC_VIEW_MODE]: {
+  actions: assign({
+    viewMode: (_, evt) => {
+      assertEvent(evt, EventType.SYNC_VIEW_MODE); // Unnecessary
+      return evt.payload.viewMode;
+    },
+  }),
+}
+
+// Good - no assertEvent needed in assign actions
+[EventType.SYNC_VIEW_MODE]: {
+  actions: assign({
+    viewMode: (_, evt) => evt.payload.viewMode,
+  }),
+}
+
+// Good - assertEvent needed in broadcast payload functions
+broadcast({
+  type: PublicEventType.BROADCAST_VIEW_MODE,
+  payload: (ctx, evt) => {
+    assertEvent(evt, EventType.SYNC_VIEW_MODE); // Needed - type not narrowed
+    return { viewMode: evt.payload.viewMode };
+  },
+})
+```
+
+**Rationale**: In `assign` actions, the event type is already narrowed by the transition. In `broadcast` payload functions, the event type isn't narrowed, so `assertEvent` provides runtime type safety.
+
+### Handler Placement
+
+**Event handlers live in the state that manages that concern** - not in parallel states or background sync:
+
+```typescript
+// Good - handler in the state managing search view
+viewModeManagement: {
+  states: {
+    searchView: {
+      on: {
+        [EventType.SYNC_BATCH_SEARCH_RESULTS]: {
+          actions: [/* Handle search results here */],
+        },
+      },
+    },
+  },
+},
+```
+
+Keeps concerns separated, avoids "half jobs" split across states.
+
+### Container State Management
+
+**When moving state to parent, remove all fallback logic** - make props required:
+
+```typescript
+// Good - fully controlled by parent
+type ContainerProps = {
+  viewMode: ViewMode; // Required
+  onViewModeChange: (viewMode: ViewMode) => void; // Required
+};
+
+// Parent manages state
+const [viewMode, setViewMode] = useState<ViewMode>("folder");
+<Container viewMode={viewMode} onViewModeChange={setViewMode} />
+```
+
+Eliminates dual sources of truth, makes data flow explicit.
+
+### Entity Imports
+
+Import as namespace for clarity:
+
+```typescript
+import * as playlistSelectionEntity from "...";
+playlistSelectionEntity.hasAddedPlaylists({ ... });
+```
+
+---
+
+## Import Paths
+
+Use absolute paths from `src/`:
+
+```typescript
+import { InputOption } from "src/features/common/domain/entities/SelectionInputEntity";
+import * as playlistSelectionEntity from "src/features/tapesv3/domain/entities/PlaylistSelectionEntity";
+```
+
+Relative paths acceptable within same feature for deeply nested files.
+
+---
+
+## File Organization
+
+### Feature Structure
+
+```
+src/features/{feature}/
+├── application/
+│   ├── containers/     # React containers (connect to XState)
+│   └── controllers/    # XState machines
+├── domain/
+│   └── entities/       # Pure functions, types, business logic
+├── presentation/       # React components (UI only)
+└── types.ts           # Shared types, event enums
+```
+
+### When to Create New Files
+
+- **New entity file**: When the concern is distinct (e.g., selection vs reordering)
+- **Same file**: When functions are tightly related and small
+
+---
+
+## Container / Controller Separation
+
+### Containers
+
+Location: `src/features/{feature}/application/containers/`
+
+Containers wire controllers to presentation components. They do NOT contain business logic.
+
+**Responsibilities:**
+
+- Get actor ref via `useActorRefById`
+- Select UI-relevant data via `useSelector`
+- Create callbacks that send events to controller
+- Compose presentation components
+- Apply `useMemo` for derived UI values if needed
+
+**Do NOT:**
+
+- Transform data (controller's job)
+- Contain business logic
+- Make decisions about state
+
+```typescript
+export const TapesClipsViewHeaderContainer = () => {
+  const actor = useActorRefById<TapesClipsViewerHeaderRef>({
+    actorId: TapesActorIds.CLIPS_VIEWER_HEADER,
+  });
+
+  // Select UI data from controller
+  const { playlists, availablePlaylists } = useSelector(
+    actor,
+    (s) => ({
+      playlists: s.context.playlists,
+      availablePlaylists: s.context.availablePlaylists,
+    }),
+    shallowEquals,
+  );
+
+  // Callback sends event - no logic
+  const onPlaylistChange = useCallback(
+    (playlists: InputOption[]) => {
+      actor.send({
+        type: TapesClipsViewerHeaderEventType.PLAYLIST_CHANGED,
+        payload: { playlists },
+      });
+    },
+    [actor],
+  );
+
+  return (
+    <PanelClips.TapesViewerHeader>
+      <MultiSelectorV2Container
+        selectedOptions={playlists}
+        options={availablePlaylists}
+        onChange={onPlaylistChange}
+      />
+    </PanelClips.TapesViewerHeader>
+  );
+};
+```
+
+### Controllers
+
+Location: `src/features/{feature}/application/controllers/`
+
+Controllers handle all business rules and data transforms.
+
+**Responsibilities:**
+
+- Transform incoming data to UI-ready format
+- Handle business logic (predicates, conditions)
+- Broadcast events to other actors
+- Manage state transitions
+
+```typescript
+[PublicTapesEventType.BROADCAST_CLIPS_DATA_SYNC]: {
+  actions: [
+    assign({
+      playlists: (ctx, evt) => {
+        // Transform here, not in container
+        return evt.payload.clipsData?.playlists.map((playlist) => ({
+          id: playlist.playlistId,
+          label: playlist.playlistTitle ?? "",
+          value: playlist.playlistId,
+        })) ?? [];
+      },
+    }),
+  ],
+},
+```
+
+### Data Flow
+
+```
+Server Data → Controller (transform) → Context → Container (useSelector) → Presentation
+                  ↑
+User Action → Container (send event) → Controller (business logic)
+```
+
+### Containers, Handlers, and React Query
+
+When events trigger handlers that fetch/update data, data flows through React Query and derived state—**never through useState in the container**.
+
+**Rules:**
+
+1. **No useState for handler-driven data** — Handler results live in React Query cache, not container state
+2. **Queries only in dedicated hooks** — All queries in feature hook (e.g. `useTapesQueries`)
+3. **Handler writes to cache** — Use `queryClient.setQueryData(key, result)`, query hook subscribes
+4. **Trigger only in container** — Callback invokes handler prop, data returns via props from derived state
+5. **Sync in useEffect** — Watch props, sync to actor in `useEffect`
+
+**Pipeline:**
+
+```
+Event → Container (invoke handler)
+     → Handler (fetch + setQueryData)
+     → Query hook (subscribed to cache)
+     → Derived state (transform)
+     → Container props
+     → useEffect syncs to actor
+```
+
+---
+
+## Persisting State to localStorage
+
+When user preferences persist across sessions, use a localStorage service invoked by the state machine.
+
+### Service Pattern
+
+Create service in `src/features/{feature}/infrastructure/services/`:
+
+```typescript
+export type ViewType = "Batch" | "Profile";
+const STORAGE_KEY = "feature:preferenceKey";
+
+export const getPreference = (): Promise<ViewType> => {
+  return new Promise((resolve) => {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) {
+        resolve("Batch");
+        return;
+      }
+      const stored = window.localStorage.getItem(STORAGE_KEY);
+      resolve(stored === "Profile" ? "Profile" : "Batch");
+    } catch {
+      resolve("Batch");
+    }
+  });
+};
+
+export const setPreference = (viewType: ViewType): void => {
+  try {
+    window.localStorage?.setItem(STORAGE_KEY, viewType);
+  } catch {
+    // Silently fail
+  }
+};
+```
+
+### Machine Hydration Pattern
+
+```typescript
+viewManagement: {
+  initial: "hydrate",
+  states: {
+    hydrate: {
+      invoke: {
+        src: getPreference,
+        onDone: [
+          {
+            target: "profile",
+            cond: (_, evt) => evt.data === "Profile", // XState v4 uses evt.data
+          },
+          { target: "batch" },
+        ],
+        onError: { target: "batch" },
+      },
+    },
+    batch: {
+      tags: [Tags.VIEW_TYPE_BATCH],
+      entry: [broadcast({ type: EventType.BROADCAST_VIEW_TYPE_CHANGED, payload: () => ({ viewType: "Batch" }) })],
+      on: {
+        [EventType.TOGGLE_VIEW_TYPE]: {
+          target: "profile",
+          actions: [() => setPreference("Profile")],
+        },
+      },
+    },
+    profile: {
+      tags: [Tags.VIEW_TYPE_PROFILE],
+      entry: [broadcast({ type: EventType.BROADCAST_VIEW_TYPE_CHANGED, payload: () => ({ viewType: "Profile" }) })],
+      on: {
+        [EventType.TOGGLE_VIEW_TYPE]: {
+          target: "batch",
+          actions: [() => setPreference("Batch")],
+        },
+      },
+    },
+  },
+},
+```
+
+**Key points**: Broadcast on entry for dependent controllers, use `evt.data` for invoke results, guard `window`/`localStorage` for SSR.
+
+---
+
+## Error Handling and Validation
+
+### Never Suppress Unexpected Outcomes
+
+**Always throw errors for unexpected states** - never silent returns:
+
+```typescript
+// Bad - silently fails, hides bugs
+if (!playlist) return;
+
+// Good - throws error, makes failures visible
+if (!playlist) throw new Error("Playlist not found");
+```
+
+Silent failures hide bugs and data inconsistencies.
+
+### Validation at Call Sites
+
+**Validate at call sites** (controllers) for context-specific checks, then pass validated data to pure functions:
+
+```typescript
+// Controller validates
+if (!ctx.activeTabId || !ctx.activeFolderId) {
+  throw new Error("Active tab ID and folder ID are required");
+}
+const playlist = ctx.availablePlaylists.find(
+  (p) => p.id === evt.payload.playlistId
+);
+if (!playlist) throw new Error("Playlist not found");
+
+// Entity receives validated data
+const action = tapesActionEntity.createApplyPlaylistActionForFolder({
+  playlist,
+  activeTabId: ctx.activeTabId,
+  activeFolderId: ctx.activeFolderId,
+});
+```
+
+**Entity functions validate**: Input format/type issues, required parameters that can't be validated at call site.
+
+**Entity functions do NOT validate**: Objects already validated at call sites, context-specific requirements.
+
+### Type Safety: Required vs Optional
+
+**Make parameters required when always validated at call sites:**
+
+```typescript
+// Good - required, TypeScript enforces
+export const createAction = ({
+  playlist,
+  activeFolderId, // Required - validated at call site
+}: {
+  playlist: InputOption;
+  activeFolderId: string;
+}) => {
+  // No runtime check needed
+};
+```
+
+TypeScript catches missing parameters at compile time, removes redundant runtime validation.
+
+### Extracting Action Creation
+
+When action creation logic appears in multiple controllers, extract to entity file.
+
+**Location**: `src/features/{feature}/actions/{Feature}ActionEntity.ts`
+
+```typescript
+// Entity file
+export const createApplyPlaylistAction = ({
+  playlist,
+}: {
+  playlist: ClipsBatchPlayListTag;
+}): PanelActionEntity => {
+  return panelActionEntity.toActionItem(TapesActionTypes.APPLY_PLAYLIST, {
+    label: playlist.label,
+    referenceId: playlist.id,
+    buttonType: "button",
+    metadata: { playlistId: playlist.id },
+  });
+};
+
+// Controller uses entity
+const action = tapesActionEntity.createApplyPlaylistAction({ playlist });
+```
+
+Reusable, testable, single source of truth.
+
+---
+
+## Future Sections
+
+_Add patterns as they emerge:_
+
+- Testing patterns
+- API/data fetching patterns

package/src/AGENTS.md

@@ -26,13 +26,10 @@ This `.agents` workspace is portable and command-first.
 
 1. `/workflow:brainstorm` -> clarify what to build
 2. `/workflow:plan` -> define how to build it
-3. `/workflow:work` -> implement
-4. `/workflow:review` -> validate quality
-5. `/workflow:compound` -> capture durable learnings
-
-Supporting command:
-
-- `/workflow:triage` -> approve and prioritize pending todos
+3. `/workflow:triage` -> approve and prioritize the todo queue before execution
+4. `/workflow:work` -> implement
+5. `/workflow:review` -> validate quality
+6. `/workflow:compound` -> capture durable learnings
 
 Continuous improvement:
 
@@ -56,6 +53,7 @@ Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:
 - **Solution scope contract is mandatory in every plan.** Plans must declare `solution_scope` (`partial_fix|full_remediation|migration`) plus explicit completion expectation and non-goals so `/workflow:work` can enforce intent.
 - **SpecFlow is a validation gate, not a rewrite engine.** High fidelity required; Medium recommended; Low optional. Output must translate into acceptance criteria/edge cases, not new scope.
 - **Isolation preflight is a hard gate.** `/workflow:work` must complete and record worktree/isolation preflight before any implementation commands. `/workflow:review` must do the same for non-current PR/branch targets before analysis.
+- **Triage before execution is mandatory.** `/workflow:work` must not execute todos until a `/workflow:triage` pass has prioritized the queue and validated dependencies/ready state for the current plan.
 - **Spike governance is explicit and ordered.** Risky plans must evaluate spike need, spike candidates must declare initial priority/dependencies/unblocks/timebox/deliverable, triage confirms those assumptions, and `/workflow:work` executes blocking spikes before dependent build todos.
 - **Agentic access/testability is mandatory in planning.** Every plan must include an executable access + validation contract so work/review can run deterministically.
 - **Todo completion requires evidence.** A todo may move to `complete` only after success criteria evidence and quality gate evidence are recorded in Work Log.
@@ -157,7 +155,7 @@ worktree_bootstrap_notes:
 ## Implemented Components (Current Scope)
 
 - Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:work`, `workflow:triage`, `workflow:review`, `workflow:compound` (under `.agents/commands/workflow/`), plus `test-browser`, `metrics`, `assess`, `setup`, `sync` (root commands)
-- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs` (alias: `compound_doc`), `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`
+- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs` (alias: `compound_doc`), `capture-skill`, `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`, `standards`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`
 - Agents:
   - `repo-research-analyst`
   - `learnings-researcher`
@@ -213,12 +211,14 @@ Maintenance:
 | `document-review` | You need to review a document/spec and extract issues, gaps, and concrete next actions. |
 | `technical-review` | A plan or feature approach has passed document review and must be checked for technical correctness before build. |
 | `compound-docs` (alias: `compound_doc`) | A durable learning (solved problem or implementation insight) should be captured as institutional knowledge. |
+| `capture-skill` | You want to capture conversation learnings as a reusable skill, while defaulting to project-overlay refinement and avoiding implicit edits to repo-provided base skills. |
 | `file-todos` | You need a file-backed todo workflow for iterative multi-step changes. |
 | `agent-browser` | You need to inspect available agents/skills and route deterministically. |
 | `git-worktree` | You need isolated parallel work (review/feature) using git worktrees. |
 | `process-metrics` | You want to log and assess session performance and process improvements. |
 | `react-ddd-mvc-frontend` | You need React frontend architecture guidance (DDD + MVC hybrid) during planning or review to enforce feature structure, layer boundaries, composable pure components, container/controller responsibilities, and maintainable patterns. |
 | `xstate-actor-orchestration` | You are evaluating complexity and need explicit state orchestration: React container-as-orchestrator for UI flows, or actor/state-machine orchestration for backend/internal workflows (especially multi-step async branching, retries/timeouts/cancellation, receptionist/child-actor coordination, or boolean-flag sprawl). |
+| `standards` | You need Altai coding standards for implementation and refactoring, including domain entity patterns, XState conventions, type usage, and feature code organization. |
 
 ### Reference standards (guardrails)