@mindfoldhq/trellis 0.3.10 → 0.4.0-beta.10

package/dist/templates/opencode/lib/trellis-context.js

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, readFileSync, appendFileSync, readdirSync } from "fs"
-import { join } from "path"
+import { isAbsolute, join } from "path"
 import { homedir, platform } from "os"
 import { execSync } from "child_process"
 
@@ -191,12 +191,52 @@ export class TrellisContext {
       if (!existsSync(currentTaskPath)) {
         return null
       }
-      return readFileSync(currentTaskPath, "utf-8").trim()
+      const taskRef = readFileSync(currentTaskPath, "utf-8").trim()
+      const normalized = this.normalizeTaskRef(taskRef)
+      return normalized || null
     } catch {
       return null
     }
   }
 
+  normalizeTaskRef(taskRef) {
+    if (!taskRef) {
+      return ""
+    }
+
+    if (isAbsolute(taskRef)) {
+      return taskRef.trim()
+    }
+
+    let normalized = taskRef.trim().replace(/\\/g, "/")
+    while (normalized.startsWith("./")) {
+      normalized = normalized.slice(2)
+    }
+
+    if (normalized.startsWith("tasks/")) {
+      return `.trellis/${normalized}`
+    }
+
+    return normalized
+  }
+
+  resolveTaskDir(taskRef) {
+    const normalized = this.normalizeTaskRef(taskRef)
+    if (!normalized) {
+      return null
+    }
+
+    if (isAbsolute(normalized)) {
+      return normalized
+    }
+
+    if (normalized.startsWith(".trellis/")) {
+      return join(this.directory, normalized)
+    }
+
+    return join(this.directory, ".trellis", "tasks", normalized)
+  }
+
   // ============================================================
   // Hook Decision Logic
   // ============================================================

package/dist/templates/opencode/{plugin → plugins}/inject-subagent-context.js

@@ -9,7 +9,7 @@
  * - Otherwise, this plugin handles injection
  */
 
-import { existsSync, writeFileSync } from "fs"
+import { existsSync, writeFileSync, readdirSync } from "fs"
 import { join } from "path"
 import { TrellisContext, debugLog } from "../lib/trellis-context.js"
 
@@ -119,8 +119,7 @@ function getCheckContext(ctx, taskDir) {
     const checkFiles = [
       [".opencode/commands/trellis/finish-work.md", "Finish work checklist"],
       [".opencode/commands/trellis/check-cross-layer.md", "Cross-layer check spec"],
-      [".opencode/commands/trellis/check-backend.md", "Backend check spec"],
-      [".opencode/commands/trellis/check-frontend.md", "Frontend check spec"],
+      [".opencode/commands/trellis/check.md", "Check spec"],
     ]
     for (const [f, description] of checkFiles) {
       const content = ctx.readProjectFile(f)
@@ -202,8 +201,7 @@ function getDebugContext(ctx, taskDir) {
     }
 
     const checkFiles = [
-      [".opencode/commands/trellis/check-backend.md", "Backend check spec"],
-      [".opencode/commands/trellis/check-frontend.md", "Frontend check spec"],
+      [".opencode/commands/trellis/check.md", "Check spec"],
       [".opencode/commands/trellis/check-cross-layer.md", "Cross-layer check spec"],
     ]
     for (const [f, description] of checkFiles) {
@@ -229,17 +227,46 @@ function getDebugContext(ctx, taskDir) {
 function getResearchContext(ctx, taskDir) {
   const parts = []
 
-  parts.push(`## Project Spec Directory Structure
-
-\`\`\`
-.trellis/spec/
-├── shared/      # Cross-project common specs
-├── frontend/    # Frontend standards
-├── backend/     # Backend standards
-└── guides/      # Thinking guides
+  // Dynamic project structure (scan actual spec directory)
+  const specPath = ".trellis/spec"
+  const specFull = join(ctx.directory, specPath)
+
+  const structureLines = [`## Project Spec Directory Structure\n\n\`\`\`\n${specPath}/`]
+  if (existsSync(specFull)) {
+    try {
+      const entries = readdirSync(specFull, { withFileTypes: true })
+        .filter(d => d.isDirectory() && !d.name.startsWith("."))
+        .sort((a, b) => a.name.localeCompare(b.name))
+
+      for (const entry of entries) {
+        const entryPath = join(specFull, entry.name)
+        // Check if this is a direct spec layer (has index.md)
+        if (existsSync(join(entryPath, "index.md"))) {
+          structureLines.push(`├── ${entry.name}/`)
+        } else {
+          // Check for nested package dirs (monorepo)
+          try {
+            const nested = readdirSync(entryPath, { withFileTypes: true })
+              .filter(d => d.isDirectory() && existsSync(join(entryPath, d.name, "index.md")))
+              .sort((a, b) => a.name.localeCompare(b.name))
+            if (nested.length > 0) {
+              structureLines.push(`├── ${entry.name}/`)
+              for (const n of nested) {
+                structureLines.push(`│   ├── ${n.name}/`)
+              }
+            }
+          } catch {
+            // Ignore nested read errors
+          }
+        }
+      }
+    } catch {
+      // Ignore read errors
+    }
+  }
+  structureLines.push("```")
 
-.trellis/big-question/  # Known issues and pitfalls
-\`\`\`
+  parts.push(structureLines.join("\n") + `
 
 ## Search Tips
 
@@ -250,10 +277,10 @@ function getResearchContext(ctx, taskDir) {
 
   if (taskDir) {
     const jsonlPath = join(ctx.directory, taskDir, "research.jsonl")
-    const entries = ctx.readJsonlWithFiles(jsonlPath)
-    if (entries.length > 0) {
+    const researchEntries = ctx.readJsonlWithFiles(jsonlPath)
+    if (researchEntries.length > 0) {
       parts.push("\n## Additional Search Context\n")
-      parts.push(ctx.buildContextFromEntries(entries))
+      parts.push(ctx.buildContextFromEntries(researchEntries))
     }
   }
 

package/dist/templates/opencode/{plugin → plugins}/session-start.js

@@ -11,44 +11,28 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from "fs"
-import { join } from "path"
+import { basename, join } from "path"
+import { execFileSync } from "child_process"
+import { platform } from "os"
 import { TrellisContext, contextCollector, debugLog } from "../lib/trellis-context.js"
 
+const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
+
 
 /**
  * Check current task status and return structured status string.
  * JavaScript equivalent of _get_task_status in Claude's session-start.py.
  */
-function getTaskStatus(directory) {
-  const trellisDir = join(directory, ".trellis")
-  const currentTaskFile = join(trellisDir, ".current-task")
-
-  if (!existsSync(currentTaskFile)) {
-    return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
-  }
-
-  let taskRef
-  try {
-    taskRef = readFileSync(currentTaskFile, "utf-8").trim()
-  } catch {
-    return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
-  }
-
+function getTaskStatus(ctx) {
+  const taskRef = ctx.getCurrentTask()
   if (!taskRef) {
     return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
   }
 
   // Resolve task directory
-  let taskDir
-  if (taskRef.startsWith("/")) {
-    taskDir = taskRef
-  } else if (taskRef.startsWith(".trellis/")) {
-    taskDir = join(directory, taskRef)
-  } else {
-    taskDir = join(trellisDir, "tasks", taskRef)
-  }
+  const taskDir = ctx.resolveTaskDir(taskRef)
 
-  if (!existsSync(taskDir)) {
+  if (!taskDir || !existsSync(taskDir)) {
     return `Status: STALE POINTER\nTask: ${taskRef}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish`
   }
 
@@ -67,7 +51,7 @@ function getTaskStatus(directory) {
   const taskStatus = taskData.status || "unknown"
 
   if (taskStatus === "completed") {
-    const dirName = taskDir.split("/").pop()
+    const dirName = basename(taskDir)
     return `Status: COMPLETED\nTask: ${taskTitle}\nNext: Archive with \`python3 ./.trellis/scripts/task.py archive ${dirName}\` or start a new task`
   }
 
@@ -101,6 +85,124 @@ function getTaskStatus(directory) {
   return `Status: READY\nTask: ${taskTitle}\nNext: Continue with implement or check`
 }
 
+/**
+ * Load Trellis config for session-start decisions.
+ * Calls get_context.py --mode packages --json for reliable config data.
+ */
+function loadTrellisConfig(directory) {
+  const scriptPath = join(directory, ".trellis", "scripts", "get_context.py")
+  if (!existsSync(scriptPath)) {
+    return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
+  }
+  try {
+    const output = execFileSync(PYTHON_CMD, [scriptPath, "--mode", "packages", "--json"], {
+      cwd: directory,
+      timeout: 5000,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+    const data = JSON.parse(output)
+    if (data.mode !== "monorepo") {
+      return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
+    }
+    // Convert packages array to dict keyed by name
+    const pkgDict = {}
+    for (const pkg of (data.packages || [])) {
+      pkgDict[pkg.name] = pkg
+    }
+    return {
+      isMonorepo: true,
+      packages: pkgDict,
+      specScope: data.specScope || null,
+      activeTaskPackage: data.activeTaskPackage || null,
+      defaultPackage: data.defaultPackage || null,
+    }
+  } catch (e) {
+    debugLog("session", "loadTrellisConfig error:", e.message)
+    return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
+  }
+}
+
+
+/**
+ * Check for legacy spec directory structure in monorepo.
+ */
+function checkLegacySpec(directory, config) {
+  if (!config.isMonorepo || Object.keys(config.packages).length === 0) {
+    return null
+  }
+
+  const specDir = join(directory, ".trellis", "spec")
+  if (!existsSync(specDir)) return null
+
+  // Check for legacy flat spec dirs
+  let hasLegacy = false
+  for (const name of ["backend", "frontend"]) {
+    if (existsSync(join(specDir, name, "index.md"))) {
+      hasLegacy = true
+      break
+    }
+  }
+  if (!hasLegacy) return null
+
+  // Check which packages are missing spec/<pkg>/ directory
+  const pkgNames = Object.keys(config.packages).sort()
+  const missing = pkgNames.filter(name => !existsSync(join(specDir, name)))
+
+  if (missing.length === 0) return null
+
+  if (missing.length === pkgNames.length) {
+    return (
+      `[!] Legacy spec structure detected: found \`spec/backend/\` or \`spec/frontend/\` ` +
+      `but no package-scoped \`spec/<package>/\` directories.\n` +
+      `Monorepo packages: ${pkgNames.join(", ")}\n` +
+      `Please reorganize: \`spec/backend/\` -> \`spec/<package>/backend/\``
+    )
+  }
+  return (
+    `[!] Partial spec migration detected: packages ${missing.join(", ")} ` +
+    `still missing \`spec/<pkg>/\` directory.\n` +
+    `Please complete migration for all packages.`
+  )
+}
+
+
+/**
+ * Resolve which packages should have their specs injected.
+ * Returns a Set of allowed package names, or null for full scan.
+ */
+function resolveSpecScope(config) {
+  if (!config.isMonorepo || Object.keys(config.packages).length === 0) {
+    return null
+  }
+
+  const { specScope, activeTaskPackage, defaultPackage, packages } = config
+  if (specScope == null) return null
+
+  if (specScope === "active_task") {
+    if (activeTaskPackage && activeTaskPackage in packages) return new Set([activeTaskPackage])
+    if (defaultPackage && defaultPackage in packages) return new Set([defaultPackage])
+    return null
+  }
+
+  if (Array.isArray(specScope)) {
+    const valid = new Set()
+    for (const entry of specScope) {
+      if (entry in packages) {
+        valid.add(entry)
+      }
+    }
+    if (valid.size > 0) return valid
+    // All invalid: fallback
+    if (activeTaskPackage && activeTaskPackage in packages) return new Set([activeTaskPackage])
+    if (defaultPackage && defaultPackage in packages) return new Set([defaultPackage])
+    return null
+  }
+
+  return null
+}
+
+
 /**
  * Build session context for injection
  */
@@ -110,6 +212,10 @@ function buildSessionContext(ctx) {
   const claudeDir = join(directory, ".claude")
   const opencodeDir = join(directory, ".opencode")
 
+  // Load config for scope filtering and legacy detection
+  const config = loadTrellisConfig(directory)
+  const allowedPkgs = resolveSpecScope(config)
+
   const parts = []
 
   // 1. Header
@@ -118,6 +224,12 @@ You are starting a new session in a Trellis-managed project.
 Read and follow all instructions below carefully.
 </trellis-context>`)
 
+  // Legacy migration warning
+  const legacyWarning = checkLegacySpec(directory, config)
+  if (legacyWarning) {
+    parts.push(`<migration-warning>\n${legacyWarning}\n</migration-warning>`)
+  }
+
   // 2. Current Context (dynamic)
   const contextScript = join(trellisDir, "scripts", "get_context.py")
   if (existsSync(contextScript)) {
@@ -155,15 +267,31 @@ Read and follow all instructions below carefully.
       }).sort()
 
       for (const sub of subs) {
+        // Always include guides/ regardless of scope
+        if (sub === "guides") {
+          const indexFile = join(specDir, sub, "index.md")
+          if (existsSync(indexFile)) {
+            const content = ctx.readFile(indexFile)
+            if (content) {
+              parts.push(`## ${sub}\n${content}\n`)
+            }
+          }
+          continue
+        }
+
         const indexFile = join(specDir, sub, "index.md")
         if (existsSync(indexFile)) {
-          // Flat spec dir: spec/<layer>/index.md
+          // Flat spec dir: spec/<layer>/index.md (single-repo)
           const content = ctx.readFile(indexFile)
           if (content) {
             parts.push(`## ${sub}\n${content}\n`)
           }
         } else {
           // Nested package dirs (monorepo): spec/<pkg>/<layer>/index.md
+          // Apply scope filter
+          if (allowedPkgs !== null && !allowedPkgs.has(sub)) {
+            continue
+          }
           try {
             const nested = readdirSync(join(specDir, sub)).filter(name => {
               try {
@@ -206,7 +334,7 @@ Read and follow all instructions below carefully.
   }
 
   // 6. Task status (R2: check task state for session resume)
-  const taskStatus = getTaskStatus(directory)
+  const taskStatus = getTaskStatus(ctx)
   parts.push(`<task-status>\n${taskStatus}\n</task-status>`)
 
   // 7. Final directive (R3: active, not passive)

package/dist/templates/qoder/skills/before-dev/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: before-dev
+description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
+---
+
+Read the relevant development guidelines before starting your task.
+
+Execute these steps:
+
+1. **Discover packages and their spec layers**:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+2. **Identify which specs apply** to your task based on:
+   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
+   - What type of work (backend, frontend, unit-test, docs, etc.)
+
+3. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Pre-Development Checklist"** section in the index.
+
+4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+5. **Always read shared guides**:
+   ```bash
+   cat .trellis/spec/guides/index.md
+   ```
+
+6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+
+This step is **mandatory** before writing any code.

package/dist/templates/qoder/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: "Brainstorm - Requirements Discovery (AI Coding Enhanced)"
+description: "Collaborative requirements discovery session optimized for AI coding workflows. Creates task directories, seeds PRDs, runs codebase research, proposes concrete implementation approaches with trade-offs, and converges on MVP scope through structured Q&A. Use when requirements are unclear, multiple implementation paths exist, trade-offs need evaluation, or a complex feature needs scoping before development."
 ---
 
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)

package/dist/templates/qoder/skills/break-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: break-loop
-description: "Break the Loop - Deep Bug Analysis"
+description: "Deep post-fix bug analysis across five dimensions: root cause categorization, fix failure analysis, prevention mechanisms, systematic expansion, and knowledge capture. Updates .trellis/spec/ guides with lessons learned to prevent recurring bugs. Use when a debugging session completes, after fixing a tricky bug, when the same class of bug keeps recurring, or when you want to capture debugging insights into project documentation."
 ---
 
 # Break the Loop - Deep Bug Analysis

package/dist/templates/qoder/skills/check/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: check
+description: "Validates recently written code against project-specific development guidelines from .trellis/spec/. Identifies changed files via git diff, discovers applicable spec modules, runs lint and typecheck, and reports guideline violations. Use when code is written and needs quality verification, to catch context drift during long sessions, or before committing changes."
+---
+
+Check if the code you just wrote follows the development guidelines.
+
+Execute these steps:
+
+1. **Identify changed files**:
+   ```bash
+   git diff --name-only HEAD
+   ```
+
+2. **Determine which spec modules apply** based on the changed file paths:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+3. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Quality Check"** section in the index.
+
+4. **Read the specific guideline files** referenced in the Quality Check section (e.g., `quality-guidelines.md`, `conventions.md`). The index is NOT the goal — it points you to the actual guideline files. Read those files and review your code against them.
+
+5. **Run lint and typecheck** for the affected package.
+
+6. **Report any violations** and fix them if found.

package/dist/templates/qoder/skills/check-cross-layer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-cross-layer
-description: "Cross-Layer Check"
+description: "Post-implementation verification across multiple code dimensions: cross-layer data flow, code reuse analysis, import path validation, and same-layer consistency checks. Identifies missed update sites, type mismatches, and duplicated constants. Use when changes span 3+ architectural layers, after modifying shared constants or configs, after batch file modifications, or when creating new utility functions."
 ---
 
 # Cross-Layer Check

package/dist/templates/qoder/skills/create-command/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-command
-description: "Create New Skill"
+description: "Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set."
 ---
 
 # Create New Skill
@@ -93,8 +93,8 @@ Description:
 | Skill Type | Prefix | Example |
 |------------|--------|---------|
 | Session Start | `start` | `start` |
-| Pre-development | `before-` | `before-frontend-dev` |
-| Check | `check-` | `check-frontend` |
+| Pre-development | `before-` | `before-dev` |
+| Check | `check-` | `check` |
 | Record | `record-` | `record-session` |
 | Generate | `generate-` | `generate-api-doc` |
 | Update | `update-` | `update-changelog` |

package/dist/templates/qoder/skills/finish-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finish-work
-description: "Finish Work - Pre-Commit Checklist"
+description: "Pre-commit quality checklist covering lint, typecheck, tests, code-spec sync, API changes, database migrations, cross-layer verification, and manual testing. Blocks commit if infra or cross-layer specs lack executable depth. Use when code is written and tested but not yet committed, before submitting changes, or as a final review before git commit."
 ---
 
 # Finish Work - Pre-Commit Checklist

package/dist/templates/qoder/skills/integrate-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integrate-skill
-description: "Integrate Skill into Project Guidelines"
+description: "Adapts an external skill into project-specific development guidelines in .trellis/spec/. Creates guideline sections, code example templates with .template suffix, and updates spec indexes. Use when integrating an external skill, adding a new skill's patterns to project conventions, or incorporating third-party skill best practices into .trellis/spec/ documentation."
 ---
 
 # Integrate Skill into Project Guidelines

package/dist/templates/qoder/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard
-description: "PART 3: Customize Your Development Guidelines"
+description: "Interactive three-part onboarding for new team members to the Trellis AI-assisted workflow system. Covers core philosophy (AI memory, project-specific knowledge, context drift), system structure and command deep-dives, real-world workflow examples, and guideline customization. Use when a new developer joins the project, someone needs to understand the Trellis workflow, or project guidelines need initial setup."
 ---
 
 You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
@@ -131,13 +131,13 @@ AI needs the same onboarding - but compressed into seconds at session start.
 
 ---
 
-### $before-frontend-dev and $before-backend-dev - Inject Specialized Knowledge
+### $before-dev - Inject Specialized Knowledge
 
 **WHY IT EXISTS**:
 AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
 
 **WHAT IT ACTUALLY DOES**:
-1. Reads `.trellis/spec/frontend/` or `.trellis/spec/backend/`
+1. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
 2. Loads project-specific patterns into AI's working context:
    - Component naming conventions
    - State management patterns
@@ -145,12 +145,12 @@ AI models have "pre-trained knowledge" - general patterns from millions of codeb
    - Error handling standards
 
 **WHY THIS MATTERS**:
-- Without before-*-dev: AI writes generic code that doesn't match project style.
-- With before-*-dev: AI writes code that looks like the rest of the codebase.
+- Without before-dev: AI writes generic code that doesn't match project style.
+- With before-dev: AI writes code that looks like the rest of the codebase.
 
 ---
 
-### $check-frontend and $check-backend - Combat Context Drift
+### $check - Combat Context Drift
 
 **WHY IT EXISTS**:
 AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift."
@@ -216,9 +216,9 @@ All the context AI built during this session will be lost when session ends. The
 
 **[1/8] $start** - AI needs project context before touching code
 **[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference
-**[3/8] $before-frontend-dev** - Inject project-specific frontend knowledge
+**[3/8] $before-dev** - Inject project-specific development guidelines
 **[4/8] Investigate and fix the bug** - Actual development work
-**[5/8] $check-frontend** - Re-verify code against guidelines
+**[5/8] $check** - Re-verify code against guidelines
 **[6/8] $finish-work** - Holistic cross-layer review
 **[7/8] Human tests and commits** - Human validates before code enters repo
 **[8/8] $record-session** - Persist memory for future sessions
@@ -233,9 +233,9 @@ All the context AI built during this session will be lost when session ends. The
 ### Example 3: Code Review Fixes
 
 **[1/6] $start** - Resume context from previous session
-**[2/6] $before-backend-dev** - Re-inject guidelines before fixes
+**[2/6] $before-dev** - Re-inject guidelines before fixes
 **[3/6] Fix each CR issue** - Address feedback with guidelines in context
-**[4/6] $check-backend** - Verify fixes didn't introduce new issues
+**[4/6] $check** - Verify fixes did not introduce new issues
 **[5/6] $finish-work** - Document lessons from CR
 **[6/6] Human commits, then $record-session** - Preserve CR lessons
 
@@ -243,16 +243,16 @@ All the context AI built during this session will be lost when session ends. The
 
 **[1/5] $start** - Clear baseline before major changes
 **[2/5] Plan phases** - Break into verifiable chunks
-**[3/5] Execute phase by phase with /check-* after each** - Incremental verification
+**[3/5] Execute phase by phase with $check after each** - Incremental verification
 **[4/5] $finish-work** - Check if new patterns should be documented
 **[5/5] Record with multiple commit hashes** - Link all commits to one feature
 
 ### Example 5: Debug Session
 
 **[1/6] $start** - See if this bug was investigated before
-**[2/6] $before-backend-dev** - Guidelines might document known gotchas
+**[2/6] $before-dev** - Guidelines might document known gotchas
 **[3/6] Investigation** - Actual debugging work
-**[4/6] $check-backend** - Verify debug changes don't break other things
+**[4/6] $check** - Verify debug changes do not break other things
 **[5/6] $finish-work** - Debug findings might need documentation
 **[6/6] Human commits, then $record-session** - Debug knowledge is valuable
 
@@ -261,7 +261,7 @@ All the context AI built during this session will be lost when session ends. The
 ## KEY RULES TO EMPHASIZE
 
 1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
-2. **Guidelines before code** - /before-*-dev commands inject project knowledge.
+2. **Guidelines before code** - $before-dev command injects project knowledge.
 3. **Check after code** - /check-* commands catch context drift.
 4. **Record everything** - $record-session persists memory.