@mindfoldhq/trellis 0.3.9 → 0.3.10-beta.0

package/dist/templates/opencode/agents/dispatch.md

@@ -106,8 +106,7 @@ Hook will auto-inject:
 
 - finish-work.md
 - check-cross-layer.md
-- check-backend.md
-- check-frontend.md
+- check.md
 - All spec files from check.jsonl
 
 ### action: "debug"

package/dist/templates/opencode/agents/implement.md

@@ -65,8 +65,8 @@ Before implementing, read:
 
 Read relevant specs based on task type:
 
-- Backend: `.trellis/spec/backend/`
-- Frontend: `.trellis/spec/frontend/`
+- Spec layers: `.trellis/spec/<package>/<layer>/`
+- Shared guides: `.trellis/spec/guides/`
 - Guides: `.trellis/spec/guides/`
 
 ### 2. Understand Requirements

package/dist/templates/opencode/agents/research.md

@@ -29,8 +29,7 @@ Otherwise, if task-specific research is needed:
    - If `path` is a directory → Read all `.md` files in it
 
 Project spec locations for reference:
-- `.trellis/spec/backend/` - Backend standards
-- `.trellis/spec/frontend/` - Frontend standards
+- `.trellis/spec/<package>/<layer>/` - Package-specific standards
 - `.trellis/spec/guides/` - Thinking guides
 - `.trellis/big-question/` - Known issues and pitfalls
 

package/dist/templates/opencode/commands/trellis/before-dev.md

@@ -0,0 +1,29 @@
+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/opencode/commands/trellis/check.md

@@ -0,0 +1,25 @@
+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/opencode/commands/trellis/create-command.md

@@ -101,8 +101,8 @@ Description:
 | Command 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/opencode/commands/trellis/onboard.md

@@ -126,13 +126,13 @@ AI needs the same onboarding - but compressed into seconds at session start.
 
 ---
 
-### /trellis:before-frontend-dev and /trellis:before-backend-dev - Inject Specialized Knowledge
+### /trellis: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
@@ -140,12 +140,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.
 
 ---
 
-### /trellis:check-frontend and /trellis:check-backend - Combat Context Drift
+### /trellis: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."
@@ -211,9 +211,9 @@ All the context AI built during this session will be lost when session ends. The
 
 **[1/8] /trellis: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] /trellis:before-frontend-dev** - Inject project-specific frontend knowledge
+**[3/8] /trellis:before-dev** - Inject project-specific development guidelines
 **[4/8] Investigate and fix the bug** - Actual development work
-**[5/8] /trellis:check-frontend** - Re-verify code against guidelines
+**[5/8] /trellis:check** - Re-verify code against guidelines
 **[6/8] /trellis:finish-work** - Holistic cross-layer review
 **[7/8] Human tests and commits** - Human validates before code enters repo
 **[8/8] /trellis:record-session** - Persist memory for future sessions
@@ -228,9 +228,9 @@ All the context AI built during this session will be lost when session ends. The
 ### Example 3: Code Review Fixes
 
 **[1/6] /trellis:start** - Resume context from previous session
-**[2/6] /trellis:before-backend-dev** - Re-inject guidelines before fixes
+**[2/6] /trellis:before-dev** - Re-inject guidelines before fixes
 **[3/6] Fix each CR issue** - Address feedback with guidelines in context
-**[4/6] /trellis:check-backend** - Verify fixes didn't introduce new issues
+**[4/6] /trellis:check** - Verify fixes did not introduce new issues
 **[5/6] /trellis:finish-work** - Document lessons from CR
 **[6/6] Human commits, then /trellis:record-session** - Preserve CR lessons
 
@@ -238,16 +238,16 @@ All the context AI built during this session will be lost when session ends. The
 
 **[1/5] /trellis: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 /trellis:check after each** - Incremental verification
 **[4/5] /trellis: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] /trellis:start** - See if this bug was investigated before
-**[2/6] /trellis:before-backend-dev** - Guidelines might document known gotchas
+**[2/6] /trellis:before-dev** - Guidelines might document known gotchas
 **[3/6] Investigation** - Actual debugging work
-**[4/6] /trellis:check-backend** - Verify debug changes don't break other things
+**[4/6] /trellis:check** - Verify debug changes do not break other things
 **[5/6] /trellis:finish-work** - Debug findings might need documentation
 **[6/6] Human commits, then /trellis:record-session** - Debug knowledge is valuable
 
@@ -256,7 +256,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** - /trellis:record-session persists memory.
 

package/dist/templates/opencode/commands/trellis/parallel.md

@@ -41,8 +41,7 @@ python3 ./.trellis/scripts/get_context.py
 ### Step 3: Read Project Guidelines `[AI]`
 
 ```bash
-cat .trellis/spec/frontend/index.md  # Frontend guidelines index
-cat .trellis/spec/backend/index.md   # Backend guidelines index
+python3 ./.trellis/scripts/get_context.py --mode packages  # Discover available spec layers
 cat .trellis/spec/guides/index.md    # Thinking guides
 ```
 

package/dist/templates/opencode/commands/trellis/record-session.md

@@ -31,7 +31,7 @@ python3 ./.trellis/scripts/add_session.py \
   --summary "Brief summary of what was done"
 
 # Method 2: Pass detailed content via stdin
-cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
+cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash"
 | Feature | Description |
 |---------|-------------|
 | New API | Added user authentication endpoint |

package/dist/templates/opencode/commands/trellis/start.md

@@ -40,9 +40,14 @@ This shows: developer identity, git status, current task (if any), active tasks.
 ### Step 3: Read Guidelines Index
 
 ```bash
-cat .trellis/spec/frontend/index.md  # Frontend guidelines
-cat .trellis/spec/backend/index.md   # Backend guidelines
-cat .trellis/spec/guides/index.md    # Thinking guides
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+This shows available packages and their spec layers. Read the relevant spec indexes:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md   # Package-specific guidelines
+cat .trellis/spec/guides/index.md              # Thinking guides (always read)
 ```
 
 > **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).

package/dist/templates/opencode/plugin/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/session-start.js

@@ -12,8 +12,12 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from "fs"
 import { 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.
@@ -101,6 +105,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 +232,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 +244,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 +287,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 {

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

@@ -0,0 +1,34 @@
+---
+name: before-dev
+description: "Read the relevant development guidelines before starting your task."
+---
+
+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/check/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: check
+description: "Check if the code you just wrote follows the development guidelines."
+---
+
+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/create-command/SKILL.md

@@ -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` |