compound-workflow 1.1.1 → 1.2.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.2.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/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

@@ -157,7 +157,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`), `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`
@@ -219,6 +219,7 @@ Maintenance:
 | `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)