devloom 1.0.0 → 1.2.0

package/patterns/pr-babysitter.md

@@ -0,0 +1,37 @@
+---
+id: pr-babysitter
+cadence: "*/15 * * * *"
+level: L2
+agents: [planner, developer, qa]
+cost: 200000
+description: "Watch long-running PRs and push them forward"
+---
+# PR Babysitter Pattern
+
+## Purpose
+Watch open PRs that have been idle for >2 hours and push them forward with fixes, rebases, or reviews.
+
+## State Schema
+```json
+{
+  "prs": [
+    {
+      "number": number,
+      "status": "idle" | "in_progress" | "blocked" | "merged",
+      "lastActivity": "ISO string",
+      "agentAssigned": string,
+      "attempts": number
+    }
+  ]
+}
+```
+
+## Agent Chain
+1. planner — analyze PR diff and comments, plan next action
+2. developer — implement the planned change in a worktree
+3. qa — verify the change, run tests
+
+## Safety
+- L2: all changes go through verifier review before commit
+- Max 3 attempts per PR per tick
+- Never force-push

package/patterns/registry.yaml

@@ -0,0 +1,52 @@
+# Loop Pattern Registry
+# Each pattern defines: cadence, safety level, agent chain, token cost estimate
+v: 1
+patterns:
+  - id: daily-triage
+    cadence: "0 6 * * *"
+    level: L1
+    agents: [verifier, documenter]
+    cost_estimate: 50000
+    description: "Report repo health every morning"
+  - id: pr-babysitter
+    cadence: "*/15 * * * *"
+    level: L2
+    agents: [planner, developer, qa]
+    cost_estimate: 200000
+    description: "Watch long-running PRs and push them forward"
+  - id: ci-sweeper
+    cadence: "*/10 * * * *"
+    level: L2
+    agents: [developer, qa]
+    cost_estimate: 300000
+    description: "Detect and fix CI failures"
+  - id: dependency-sweeper
+    cadence: "0 */6 * * *"
+    level: L2
+    agents: [verifier, developer]
+    cost_estimate: 100000
+    description: "Patch-only dependency updates"
+  - id: changelog-drafter
+    cadence: "0 8 * * *"
+    level: L1
+    agents: [documenter]
+    cost_estimate: 30000
+    description: "Draft release notes from recent commits"
+  - id: post-merge-cleanup
+    cadence: "0 3 * * *"
+    level: L1
+    agents: [developer, qa]
+    cost_estimate: 40000
+    description: "Clean up stale branches and worktrees"
+  - id: issue-triage
+    cadence: "0 */2 * * *"
+    level: L1
+    agents: [planner]
+    cost_estimate: 60000
+    description: "Propose labels and priorities for new issues"
+  - id: design-audit
+    cadence: "on-demand"
+    level: L1
+    agents: [verifier]
+    cost_estimate: 150000
+    description: "Comprehensive UI/UX design audit with automated fix loop"

package/postinstall.mjs

@@ -1,62 +1,96 @@
 #!/usr/bin/env node
-// postinstall.mjs — Installs DevLoom agents, commands, and skills into OpenCode's global config dirs.
-
-import { copyFileSync, mkdirSync, existsSync, readdirSync, statSync } from "fs"
+import { copyFileSync, mkdirSync, existsSync, readdirSync, statSync, accessSync, constants, readFileSync, writeFileSync } from "fs"
 import { resolve, dirname, join, relative } from "path"
 import { fileURLToPath } from "url"
 import { homedir, platform } from "os"
+import { getOpenCodeCacheDir, refreshOpenCodePluginCache, syncOpenCodePluginDependencies } from "./scripts/plugin-cache.mjs"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
-// ── Config dir resolution (cross-platform) ────────────────────────────────────
-function getConfigDir() {
-  const os = platform()
-  if (os === "win32") {
-    return resolve(process.env.APPDATA ?? homedir(), "opencode")
-  }
-  if (os === "darwin") {
-    return resolve(homedir(), "Library", "Application Support", "opencode")
+export function getConfigDir(_platform = platform(), _homedir = homedir()) {
+  if (_platform === "win32") {
+    return resolve(process.env.APPDATA ?? _homedir, "opencode")
   }
+  // OpenCode resolves its global config from the XDG path on macOS too
+  // (~/.config/opencode), not ~/Library/Application Support.
   return resolve(
-    process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
+    process.env.XDG_CONFIG_HOME ?? join(_homedir, ".config"),
     "opencode"
   )
 }
 
-const CONFIG_DIR = getConfigDir()
-const AGENTS_DIR  = resolve(CONFIG_DIR, "agents")
-const COMMANDS_DIR = resolve(CONFIG_DIR, "commands")
-const SKILLS_DIR = resolve(CONFIG_DIR, "skills")
-
-const AGENTS = [
-  "devloom-orchestrator",
-  "devloom-analyst",
-  "devloom-architect",
-  "devloom-developer",
-  "devloom-qa",
-  "devloom-documenter",
-]
+export function isPathSafe(basePath, resolvedPath) {
+  const rel = relative(basePath, resolvedPath)
+  return !rel.startsWith("..") && !rel.startsWith("/")
+}
 
-const COMMANDS = ["devloom", "devloom-status", "devloom-resume", "devloom-init"]
+export function isDebug() {
+  return process.env.DEVLOOM_DEBUG === "1" || process.env.DEVLOOM_DEBUG === "true"
+}
 
-// ── Helpers ───────────────────────────────────────────────────────────────────
-function ensureDir(dir) {
+export function ensureDir(dir) {
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true })
+    if (isDebug()) console.log(`[debug] Created directory: ${dir}`)
     console.log(`  Created: ${dir}`)
   }
 }
 
+// Register the DevLoom TUI plugin in tui.json's `plugin` array so OpenCode's
+// TUI loads the rightbar sidebar slot (no directory auto-discovery for TUI
+// plugins). Preserves every existing key (theme, keybinds, ...); dedupes the
+// plugin entry; returns the merged object, or null when the file is corrupt
+// (caller decides whether to warn).
+export function ensureTuiPlugin(tuiPath, pluginName = "devloom") {
+  let tui = {}
+  if (existsSync(tuiPath)) {
+    try {
+      tui = JSON.parse(readFileSync(tuiPath, "utf8"))
+    } catch {
+      return null
+    }
+  }
+  if (typeof tui !== "object" || tui === null || Array.isArray(tui)) return null
+  if (!tui.$schema) tui.$schema = "https://opencode.ai/tui.json"
+  const plugins = Array.isArray(tui.plugin) ? tui.plugin.filter((spec) => spec !== pluginName) : []
+  plugins.push(pluginName)
+  tui.plugin = plugins
+  writeFileSync(tuiPath, JSON.stringify(tui, null, 2) + "\n")
+  return tui
+}
+
 let installFailed = false
 
-function installFile(src, dest, label) {
+export function installFile(src, dest, label, configDir, optional = false) {
+  const baseDir = configDir || getConfigDir()
   if (!existsSync(src)) {
+    if (optional) {
+      console.log(`  Skipped (not shipped) -- ${label}`)
+      return
+    }
     console.error(`  Source file not found: ${src}`)
     installFailed = true
     return
   }
+  const destDir = dirname(dest)
+  if (!isPathSafe(baseDir, resolve(destDir))) {
+    console.error(`  Path traversal blocked -- ${label}: ${dest}`)
+    installFailed = true
+    return
+  }
+  try {
+    accessSync(destDir, constants.W_OK)
+  } catch {
+    console.error(`  No write permission -- ${label}: ${destDir}`)
+    installFailed = true
+    return
+  }
   try {
     copyFileSync(src, dest)
+    if (isDebug()) {
+      const srcStat = statSync(src)
+      console.log(`[debug] Copied ${src} -> ${dest} (${srcStat.size} bytes)`)
+    }
     console.log(`  ${label}`)
   } catch (err) {
     console.error(`  Failed -- ${label}: ${err.message}`)
@@ -64,7 +98,8 @@ function installFile(src, dest, label) {
   }
 }
 
-function installDirRecursive(srcDir, destDir, labelPrefix) {
+export function installDirRecursive(srcDir, destDir, labelPrefix, configDir) {
+  const baseDir = configDir || getConfigDir()
   if (!existsSync(srcDir)) {
     console.error(`  Source dir not found: ${srcDir}`)
     installFailed = true
@@ -77,61 +112,226 @@ function installDirRecursive(srcDir, destDir, labelPrefix) {
     const destPath = join(destDir, entry)
     const stat = statSync(srcPath)
     if (stat.isDirectory()) {
-      installDirRecursive(srcPath, destPath, `${labelPrefix}/${entry}`)
+      installDirRecursive(srcPath, destPath, `${labelPrefix}/${entry}`, baseDir)
     } else {
-      installFile(srcPath, destPath, `${labelPrefix}/${entry}`)
+      installFile(srcPath, destPath, `${labelPrefix}/${entry}`, baseDir)
     }
   }
 }
 
-// ── Main ──────────────────────────────────────────────────────────────────────
-console.log("\nDevLoom -- post-install\n")
-console.log(`  Config dir  : ${CONFIG_DIR}`)
-console.log(`  Agents dir  : ${AGENTS_DIR}`)
-console.log(`  Commands dir: ${COMMANDS_DIR}`)
-console.log(`  Skills dir  : ${SKILLS_DIR}\n`)
+const CONFIG_DIR = getConfigDir()
+const AGENTS_DIR  = resolve(CONFIG_DIR, "agents")
+const COMMANDS_DIR = resolve(CONFIG_DIR, "commands")
+const SKILLS_DIR = resolve(CONFIG_DIR, "skills")
+const PROTOCOL_DIR = resolve(CONFIG_DIR, "protocol")
+const AI_DIR = resolve(CONFIG_DIR, "devloom-ai")
+const THEMES_DIR = resolve(CONFIG_DIR, "themes")
+
+const AGENTS = [
+  "devloom-orchestrator",
+  "devloom-planner",
+  "devloom-developer",
+  "devloom-qa",
+  "devloom-verifier",
+  "devloom-security",
+  "devloom-documenter",
+  "devloom-vision",
+  "devloom-visual-director",
+  "devloom-visual-critic",
+  "devloom-planner-senior",
+  "devloom-developer-senior",
+  "devloom-security-senior",
+  "devloom-planner-flash",
+  "devloom-developer-flash",
+  "devloom-qa-flash",
+  "devloom-documenter-flash",
+]
+
+const COMMANDS = ["devloom", "devloom-status", "devloom-resume", "devloom-init", "devloom-save", "devloom-auto", "devloom-go", "devloom-go-economy", "devloom-go-flash", "devloom-deepseek", "devloom-free", "devloom-mimo", "devloom-deepseek-mimo", "devloom-plan", "devloom-context", "devloom-agents", "devloom-refresh"]
+
+const SCRIPTS_DIR = resolve(CONFIG_DIR, "devloom-scripts")
 
-ensureDir(AGENTS_DIR)
-ensureDir(COMMANDS_DIR)
+const PROTOCOLS = [
+  "orchestrator-core",
+  "agent-contracts",
+  "artifact-system",
+  "verification-policy",
+  "project-system",
+]
+
+function main() {
+  console.log("\nDevLoom -- post-install\n")
+  console.log(`  Config dir  : ${CONFIG_DIR}`)
+  console.log(`  Agents dir  : ${AGENTS_DIR}`)
+  console.log(`  Commands dir: ${COMMANDS_DIR}`)
+  console.log(`  Skills dir  : ${SKILLS_DIR}\n`)
+  console.log(`  AI dir      : ${AI_DIR}\n`)
+
+  if (isDebug()) console.log("[debug] Starting DevLoom post-install")
 
+  ensureDir(AGENTS_DIR)
+  ensureDir(COMMANDS_DIR)
 
-console.log("Installing agents:")
-for (const name of AGENTS) {
+  console.log("Installing agents:")
+  for (const name of AGENTS) {
+    installFile(
+      resolve(__dirname, "agents", `${name}.md`),
+      resolve(AGENTS_DIR, `${name}.md`),
+      `Agent: ${name}`
+    )
+  }
+
+  console.log("\nInstalling commands:")
+  for (const name of COMMANDS) {
+    installFile(
+      resolve(__dirname, "commands", `${name}.md`),
+      resolve(COMMANDS_DIR, `${name}.md`),
+      `Command: /${name}`
+    )
+  }
   installFile(
-    resolve(__dirname, "agents", `${name}.md`),
-    resolve(AGENTS_DIR, `${name}.md`),
-    `Agent: ${name}`
+    resolve(__dirname, "scripts", "profile.mjs"),
+    resolve(COMMANDS_DIR, "profile.mjs"),
+    "Profile manager"
   )
-}
-
-console.log("\nInstalling commands:")
-for (const name of COMMANDS) {
   installFile(
-    resolve(__dirname, "commands", `${name}.md`),
-    resolve(COMMANDS_DIR, `${name}.md`),
-    `Command: /${name}`
+    resolve(__dirname, "scripts", "model-capabilities.mjs"),
+    resolve(COMMANDS_DIR, "model-capabilities.mjs"),
+    "Model capabilities helper"
   )
-}
+  installFile(
+    resolve(__dirname, "scripts", "briefing.mjs"),
+    resolve(COMMANDS_DIR, "briefing.mjs"),
+    "Briefing change tracker"
+  )
+  installFile(
+    resolve(__dirname, "scripts", "plugin-cache.mjs"),
+    resolve(COMMANDS_DIR, "plugin-cache.mjs"),
+    "Plugin cache helper"
+  )
+
+  console.log("\nInstalling skills:")
+  installDirRecursive(
+    resolve(__dirname, "skills"),
+    SKILLS_DIR,
+    "Skill"
+  )
+
+  console.log("\nInstalling AI DSL:")
+  installDirRecursive(
+    resolve(__dirname, ".ai"),
+    AI_DIR,
+    "AI"
+  )
+
+  console.log("\nInstalling profile manager scripts:")
+  installDirRecursive(
+    resolve(__dirname, "scripts"),
+    SCRIPTS_DIR,
+    "Script"
+  )
+
+  console.log("\nInstalling protocol modules:")
+  ensureDir(PROTOCOL_DIR)
+  for (const name of PROTOCOLS) {
+    installFile(
+      resolve(__dirname, "protocol", `${name}.md`),
+      resolve(PROTOCOL_DIR, `${name}.md`),
+      `Protocol: ${name}`
+    )
+  }
 
-console.log("\nInstalling skills:")
-installDirRecursive(
-  resolve(__dirname, "skills"),
-  SKILLS_DIR,
-  "Skill"
-)
+  // Install theme
+  console.log("\nInstalling DevLoom Night Owl theme:")
+  ensureDir(THEMES_DIR)
+  const themeSrc = resolve(__dirname, ".opencode", "themes", "devloom-night-owl.json")
+  const themeDest = resolve(THEMES_DIR, "devloom-night-owl.json")
+  // ponytail: cosmetic asset — a missing theme must never fail the install
+  installFile(themeSrc, themeDest, "Theme: DevLoom Night Owl", CONFIG_DIR, true)
 
-if (!installFailed) {
-  console.log(`
+  // Register the TUI plugin in tui.json (the right sidebar renders only plugin
+  // slots, so this is what makes the DevLoom agents visible in the rightbar)
+  // and activate the theme when no theme is set.
+  const tuiPath = resolve(CONFIG_DIR, "tui.json")
+  const tui = ensureTuiPlugin(tuiPath)
+  if (tui === null) {
+    console.log("  Skipping tui.json update (parse error)")
+  } else {
+    if (!tui.theme) {
+      tui.theme = "devloom-night-owl"
+      writeFileSync(tuiPath, JSON.stringify(tui, null, 2) + "\n")
+      console.log("  Theme activated in tui.json (change via /theme)")
+    } else {
+      console.log(`  Theme already set: ${tui.theme} (change via /theme)`)
+    }
+    console.log("  DevLoom TUI plugin registered in tui.json (agents render in the right sidebar)")
+  }
+
+  // Refresh the OpenCode plugin cache so the plugin code loaded by the TUI
+  // actually contains the config hook that injects DevLoom agents + profile
+  // into the sidebar. Best-effort only: OpenCode installs plugins with
+  // ignoreScripts, so this copy is the only way the cache picks up new code.
+  // Cosmetic failures here must never fail the npm install.
+  console.log("\nRefreshing OpenCode plugin cache:")
+  const cacheDir = getOpenCodeCacheDir()
+  const refresh = refreshOpenCodePluginCache(__dirname, cacheDir)
+  if (refresh.build && refresh.build.built) {
+    console.log("  Rebuilt dist/ before refreshing the plugin cache.")
+  }
+  if (refresh.build && refresh.build.errors.length > 0) {
+    console.log(`  Warning (not fatal): dist rebuild failed — ${refresh.build.errors[0]}`)
+  }
+  for (const entry of refresh.refreshed) {
+    console.log(`  Refreshed plugin cache: ${entry} -> fresh DevLoom code with the sidebar config hook`)
+  }
+  for (const entry of refresh.skipped) {
+    console.log(`  Skipped: no OpenCode plugin cache entry found at ${entry}`)
+  }
+  for (const error of refresh.errors) {
+    console.log(`  Warning (not fatal): plugin cache refresh failed for ${error}`)
+  }
+  if (refresh.skipped.length > 0 && refresh.refreshed.length === 0) {
+    console.log("")
+    console.log("  DevLoom is not yet registered as an OpenCode plugin.")
+    console.log("  Install it once with: opencode plugin devloom --global")
+    console.log("  then re-run this installer (or /devloom-refresh) to sync the plugin code.")
+  } else if (refresh.errors.length > 0) {
+    console.log("  The plugin cache could not be fully refreshed — run /devloom-refresh to retry.")
+  }
+
+  console.log("\nSyncing plugin cache dependencies (TUI sidebar plugin):")
+  const deps = syncOpenCodePluginDependencies(__dirname, cacheDir)
+  for (const entry of deps.synced) {
+    console.log(`  Synced runtime deps: ${entry} (right-sidebar TUI plugin ready)`)
+  }
+  for (const entry of deps.skipped) {
+    console.log(`  Skipped: no OpenCode plugin cache entry found at ${entry}`)
+  }
+  for (const error of deps.errors) {
+    console.log(`  Warning (not fatal): dependency sync failed for ${error}`)
+  }
+
+  if (!installFailed) {
+    console.log(`
 DevLoom installed successfully!
 
 Start weaving:
   /devloom Build a REST API for user management with JWT auth
   /devloom-status
 
+Protocol modules available at ~/.config/opencode/protocol/
+
+Theme: DevLoom Night Owl active (change via /theme or edit tui.json)
+
 Debug mode:
   DEVLOOM_DEBUG=1 opencode @devloom-orchestrator
 `)
-} else {
-  console.error("\nSome files could not be installed. See errors above.")
-  process.exit(1)
+  } else {
+    console.error("\nSome files could not be installed. See errors above.")
+    process.exit(1)
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  main()
 }

package/project/README.md

@@ -0,0 +1,29 @@
+# DevLoom Project Standard
+
+ROOT: `.opencode/devloom/project/`
+
+GOALS:
+- EN artifacts
+- JSONM for AI-only state
+- SingleActive queue
+- Persist pending work
+- Load memory every prompt
+- Use relevant skills every prompt
+- Append each prompt as the last task/todo
+- Keep tickets/todos/plan in sync
+- Tests+Regr required
+- Local tracker default
+- GitHub Project mirror only with explicit authorization
+
+TREE:
+- README.md
+- config.json
+- board.json
+- state.json
+- stories/
+- tasks/
+- bugs/
+- decisions/
+- reports/
+
+JSON_KEYS: v|id|type|title|status|ac|deps|files|tests|cols|ts

package/protocol/agent-contracts.md

@@ -0,0 +1,27 @@
+# Agent Contracts
+
+LOAD: ~/.config/opencode/devloom-ai/core.dsl|~/.config/opencode/devloom-ai/workflow.dsl|~/.config/opencode/devloom-ai/verify.dsl
+
+FMT:
+`Agent|Purpose|In|Out|Rules|Signal`
+
+AGENTS (7):
+- Orchestrator|triage+route+queue+inline recovery|prompt|state+handoffs|EN|SingleActive|PersistAll|LoadMemory|UseSkills|AppendPromptTask|MaintainPlan|NoSelfDelegate|DEVLOOM_DONE
+- Planner|prompt->REQ and/or PLAN+tickets|prompt/REQ|REQ|PLAN+tasks/*|NoImpl|CleanArch|LatestStableCheck|OfficialDocsFirst|TestsInPlan|ANALYST_COMPLETE/ARCHITECT_COMPLETE/PLANNER_COMPLETE
+- Developer|implement one ticket OR fix one defect|ticket/defect+PLAN|code+tests|TDDReq|RootCauseFix|NoWorkaround|SOLID|NoScopeCreep|MinChange|DEVELOPER_COMPLETE/REPAIR_COMPLETE
+- QA|verify+review+regression|ticket+diff|results|Lint|Tests|CodeReview|Regr|QA_PASS/QA_FAIL/REGRESSION_PASS/REGRESSION_FAIL
+- Verifier|runtime app verification by scope|scope+app url/cmd|defects/report|UX_BAR|NoGuess|Forensic|VERIFIER_COMPLETE
+- Security|review CRUD/exposure surfaces|endpoint+dto+component api|security report|SEC checks|Forensic|SECURITY_REVIEW_COMPLETE
+- Documenter|update docs+state|done tasks|docs+state|OnlyImplemented|EN|DOCUMENTER_COMPLETE
+
+SHARED:
+- EN
+- DeltaCommOnly
+- FinalResponse<=40lines: status signal + deltas + artifact paths; full detail goes to .opencode/devloom/ artifacts, never chat
+- JSONM for AI-only state
+- Update BOARD+PSTATE on ticket state change
+- Append each prompt to project/tasks/TODO.md before execution routing
+- Keep tasks/todos/plan aligned with the active ticket
+- DevLoom subagents are callable by the orchestrator and may also be invoked manually by the user
+- OfficialDocsFirst for stack-specific decisions
+- LatestStableCheck before stack-specific planning/coding

package/protocol/artifact-system.md

@@ -0,0 +1,53 @@
+# Artifact System
+
+LOAD: ~/.config/opencode/devloom-ai/core.dsl
+
+REG:
+- REG=.opencode/devloom/registry.json
+- BOARD=.opencode/devloom/project/board.json
+- PSTATE=.opencode/devloom/project/state.json
+
+TYPES: feature|defect|requirement|plan|exploration|verification|journey|decision
+
+RULES:
+- use ids, not raw dumps
+- send title|files|ac|signal only
+- summaries <=100 tokens when possible
+- use relative paths
+- persist active work in BOARD
+- append each prompt to project/tasks/TODO.md as the last todo item
+- keep task, todo, and plan artifacts aligned on every state change
+- JSONM for AI-only files
+
+JSONM_EX:
+```json
+{"v":1,"id":"TASK-003","type":"task","status":"doing","ac":["auth ok"],"files":["src/auth.ts"],"tests":["npm test -- auth"],"ts":"2026-05-24T19:00:00Z"}
+```
+
+LAYERS:
+- L1 project summary
+- L2 arch summary
+- L3 module summaries
+- L4 source files on demand only
+
+SIG:
+- ANALYST_COMPLETE
+- ARCHITECT_COMPLETE
+- DEVELOPER_COMPLETE
+- QA_PASS
+- QA_FAIL
+- EXPLORER_COMPLETE
+- ROUTE_VERIFIER_COMPLETE
+- FORM_VERIFIER_COMPLETE
+- A11Y_VERIFIER_COMPLETE
+- API_VERIFIER_COMPLETE
+- JOURNEY_AGENT_COMPLETE
+- RCA_COMPLETE
+- REPAIR_COMPLETE
+- REGRESSION_PASS
+- REGRESSION_FAIL
+- RECOVERY_DONE
+- DOCUMENTER_COMPLETE
+- DEVLOOM_RESUME
+- DEVLOOM_HANG_DETECTED
+- DEVLOOM_DONE