@rashidee/co2 1.2.6 → 1.3.1

package/plugin/skills/conductor-feature-develop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-feature-develop
-model: claude-sonnet-4-6
+model: claude-sonnet-5
 effort: high
 description: >
   Application development orchestrator — orchestrates full-stack code implementation

package/plugin/skills/conductor-feature-prepare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-feature-prepare
-model: claude-sonnet-4-6
+model: claude-sonnet-5
 effort: high
 description: >
   Context artifacts preparation orchestrator — generates all context artifacts (module models,

package/plugin/skills/depgen-k8s/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: depgen-k8s
-model: claude-sonnet-4-6
+model: claude-sonnet-5
 effort: high
 description: >
   Generate a Dockerfile and Kubernetes manifests for an application targeting a single

package/plugin/skills/tracegen-matrix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tracegen-matrix
-model: claude-sonnet-4-6
+model: claude-sonnet-5
 effort: medium
 description: >
   Requirement-to-code traceability generator — links every PRD requirement ID (User Stories,

package/plugin/skills/util-gencicdscript/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: util-gencicdscript
+model: claude-sonnet-5
+effort: high
+description: >
+  Generate the self-contained CI/CD build/run/deploy app for a CO2 project from an APPROVED
+  cicd/CICD_PLAN.md. Refuses to run unless the plan has `**Status**: COMPLETED` AND an
+  `**Approved**:` line (stamped by Compound Context Studio's Approve button). Produces
+  cicd/app/ — a zero-npm-dependency node:http app (server.js + cicd.config.json) rendering a
+  bare light-themed page (no header/sidebar/footer, iframe-embeddable) with one nav tab per
+  application: a controls bar (status badge, clickable app URL opening a new tab, Build /
+  Start / Stop / Deploy buttons) above that application's log streamed live over a built-in
+  zero-dependency WebSocket (bounded tail + backpressure drop server-side, trimmed DOM buffer
+  client-side — no leaks/OOM). Build and Deploy commands come from the approved plan (inferred
+  from ENVIRONMENT.md/DEVTOOL.md — e.g. Spring Boot jar vs Docker image; deploy via web-server
+  copy, docker run or kubectl apply, or none). Controls are disabled for any application that
+  has never completed a conductor-develop workflow run (checked against the studio's
+  /api/cicd-guard endpoint using the spawn-env token). Health/port probing marks apps already
+  running — even ones started outside this app. No version selector: only the latest built
+  applications are operated. Writes cicd/CICD_GENERATION.md with `**Status**:` IN PROGRESS →
+  COMPLETED so the studio watcher detects completion. Idempotent — re-running regenerates
+  cicd/app in place. Trigger on keywords: "generate cicd", "gen cicd script", "generate ci/cd
+  app", "cicd app", "generate deployment app". Accepts one MANDATORY argument: the
+  project-relative plan path (e.g., /util-gencicdscript cicd/CICD_PLAN.md).
+---
+
+# Util Generate CI/CD Script
+
+## Inputs
+
+```
+/util-gencicdscript cicd/CICD_PLAN.md
+```
+
+## Phase 0 — Gate (hard requirements, check in order)
+
+1. The argument file exists — else STOP: "run /util-plancicd first".
+2. It contains a top-level `**Status**: COMPLETED` — else STOP: "the plan is not complete".
+3. It contains an `**Approved**:` line — else STOP: "approve the plan in the studio's CI/CD
+   screen first". NEVER proceed without approval.
+
+## Phase 1 — Write the generation tracking file
+
+Write `cicd/CICD_GENERATION.md`:
+
+```markdown
+# CI/CD App Generation
+
+**Started**: <ISO date>
+**Status**: IN PROGRESS
+```
+
+## Phase 2 — Generate cicd/app/
+
+Read `references/cicd-app-template.md` for the complete file templates. Produce:
+
+1. `cicd/app/cicd.config.json` — from the plan's tables:
+   `{ "port": <CI/CD app port>, "apps": [{ "name", "folder", "method", "port", "build",
+   "start", "stop", "deployMethod", "deploy", "health" }] }` — `deployMethod` is the plan's
+   Deploy Method column (`none|web-server|docker|kubernetes`) and `deploy` its command
+   (`null` when the method is `none`).
+2. `cicd/app/server.js` — the template verbatim (it is generic; all project specifics live in
+   cicd.config.json). Zero npm dependencies.
+3. Ensure `cicd/logs/` and `cicd/state.json` are ignored: append `cicd/logs/` and
+   `cicd/state.json` to the project `.gitignore` if absent.
+
+## Phase 3 — Complete
+
+Flip `cicd/CICD_GENERATION.md` `**Status**:` to `COMPLETED`. Print a summary (app folder,
+port, application count) and STOP — the studio starts/embeds the app.
+
+## Important Rules
+
+- Zero npm dependencies — plain node:http only (the WebSocket log stream is hand-rolled in the
+  template); no install step may be required.
+- The page is bare: no header, sidebar or footer (it is iframed by the studio). Light theme,
+  one nav tab per application; the tab body is that application's live log.
+- Build/Start/Stop/Deploy run the plan's commands verbatim, each with the APPLICATION FOLDER
+  (`<project>/<folder>`) as working directory — command paths are relative to the application
+  folder (e.g. `java -jar target\app.jar`), never to the project root. Deploy renders only
+  when the plan assigned a deploy method other than `none`. No version selector — only the
+  latest built applications are operated.
+- Develop gate: controls stay disabled for an application that never completed a
+  conductor-develop run — checked via `${CO2_STUDIO_URL}/api/cicd-guard/${CO2_PROJECT_ID}`
+  with the CO2_GUARD_TOKEN from the spawn env (refreshed every 30 s, last answer cached).
+- Log streaming must stay bounded: per-app log file on disk, bounded tail on connect, live
+  append broadcast only, slow subscribers dropped on backpressure, client DOM buffer trimmed.
+- Already-running detection: `/api/state` probes each application's health URL (falling back
+  to its port) so an app started outside this page still shows as running; a Stop on an
+  externally started process is refused with a hint instead of killed.
+- Never touch PRD.md/CLAUDE.md; never run builds or deploys yourself during generation.

package/plugin/skills/util-gencicdscript/references/cicd-app-template.md

@@ -0,0 +1,414 @@
+# CI/CD App Template
+
+`cicd/app/server.js` — generic; reads `cicd.config.json`. Copy verbatim.
+
+```js
+// Generated by util-gencicdscript — zero-dependency CI/CD build/run/deploy app.
+// Env (set by Compound Context Studio at spawn): PORT, CO2_STUDIO_URL, CO2_PROJECT_ID,
+// CO2_GUARD_TOKEN. Bare page — designed to be embedded in the studio as an iframe.
+// One nav tab per application; the tab body streams that application's log live over a
+// hand-rolled WebSocket (server→client push only). Memory safety: logs live on disk, the
+// server retains nothing per subscriber beyond the socket itself (bounded initial tail,
+// slow clients are dropped on backpressure), and the client trims its DOM log buffer.
+const http = require('node:http')
+const { spawn, execFileSync } = require('node:child_process')
+const { createHash } = require('node:crypto')
+const { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, openSync, readSync, closeSync, createWriteStream } = require('node:fs')
+const { join, resolve } = require('node:path')
+
+const APP_DIR = __dirname
+const PROJECT_DIR = resolve(APP_DIR, '..', '..')
+const LOG_DIR = join(PROJECT_DIR, 'cicd', 'logs')
+const STATE_FILE = join(PROJECT_DIR, 'cicd', 'state.json')
+const CONFIG = JSON.parse(readFileSync(join(APP_DIR, 'cicd.config.json'), 'utf8'))
+const PORT = Number(process.env.PORT || CONFIG.port || 4100)
+const STUDIO = process.env.CO2_STUDIO_URL || 'http://127.0.0.1:3001'
+const PROJECT_ID = process.env.CO2_PROJECT_ID || ''
+const TOKEN = process.env.CO2_GUARD_TOKEN || ''
+
+mkdirSync(LOG_DIR, { recursive: true })
+const running = new Map() // app name -> ChildProcess (only processes THIS app spawned)
+const activity = new Map() // app name -> 'building' | 'deploying' (transient, exclusive)
+const failed = new Map() // app name -> true after a nonzero run exit
+const stopping = new Set() // app names whose exit was requested — not a failure
+const lastError = new Map() // app name -> string
+
+function saveState() {
+  const s = {}
+  for (const a of CONFIG.apps) s[a.name] = running.has(a.name) ? 'running' : 'stopped'
+  try { writeFileSync(STATE_FILE, JSON.stringify(s)) } catch {}
+}
+
+function currentBranch() {
+  try {
+    return execFileSync('git', ['branch', '--show-current'], { cwd: PROJECT_DIR }).toString().trim()
+  } catch { return null }
+}
+
+// ---- Develop gate (Compound Context Studio) --------------------------------------------
+// An application that never completed a conductor-develop run has nothing to build or run —
+// its tab controls are disabled. Refreshed every 30 s; the last known answer is kept when the
+// studio is briefly unreachable, and `null` (never fetched) disables controls with a hint.
+let guardApps = null // Map lower(name|folder) -> developedOnce
+async function refreshGuard() {
+  if (!PROJECT_ID) return
+  try {
+    const r = await fetch(`${STUDIO}/api/cicd-guard/${PROJECT_ID}?token=${TOKEN}`, { signal: AbortSignal.timeout(3000) })
+    if (!r.ok) return
+    const g = await r.json()
+    if (Array.isArray(g.applications)) {
+      guardApps = new Map()
+      for (const a of g.applications) guardApps.set(String(a.name).toLowerCase(), !!a.developedOnce)
+    }
+  } catch {}
+}
+function developedOnce(app) {
+  if (!guardApps) return null // unknown — controls stay disabled until the studio answers
+  const byName = guardApps.get(app.name.toLowerCase())
+  if (byName !== undefined) return byName
+  const byFolder = guardApps.get(String(app.folder || '').toLowerCase())
+  return byFolder === undefined ? null : byFolder
+}
+refreshGuard()
+setInterval(refreshGuard, 30_000).unref?.()
+
+// ---- Log streaming ---------------------------------------------------------------------
+// One log file per application (build + run + deploy share it — the tab is one stream).
+// Subscribers get a bounded tail on connect, then live appends; nothing is buffered
+// server-side, and a subscriber that cannot keep up is dropped instead of queuing forever.
+const subscribers = new Map() // app name -> Set<net.Socket>
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+
+function wsFrame(data) {
+  const payload = Buffer.from(data)
+  const len = payload.length
+  let header
+  if (len < 126) header = Buffer.from([0x81, len])
+  else if (len < 65_536) { header = Buffer.alloc(4); header[0] = 0x81; header[1] = 126; header.writeUInt16BE(len, 2) }
+  else { header = Buffer.alloc(10); header[0] = 0x81; header[1] = 127; header.writeBigUInt64BE(BigInt(len), 2) }
+  return Buffer.concat([header, payload])
+}
+
+function broadcast(name, chunk) {
+  const subs = subscribers.get(name)
+  if (!subs || subs.size === 0) return
+  const frame = wsFrame(chunk)
+  for (const s of subs) {
+    if (s.writableLength > 1_000_000) { subs.delete(s); try { s.destroy() } catch {} ; continue }
+    s.write(frame)
+  }
+}
+
+function logPath(name) { return join(LOG_DIR, `${name}.log`) }
+
+function logTail(name, bytes = 16_384) {
+  try {
+    const p = logPath(name)
+    const size = statSync(p).size
+    const start = Math.max(0, size - bytes)
+    const buf = Buffer.alloc(size - start)
+    const fd = openSync(p, 'r')
+    readSync(fd, buf, 0, buf.length, start)
+    closeSync(fd)
+    return buf.toString('utf8')
+  } catch { return '' }
+}
+
+function logLine(app, text) {
+  const line = `\n--- ${new Date().toISOString()} ${text}\n`
+  try { createWriteStream(logPath(app.name), { flags: 'a' }).end(line) } catch {}
+  broadcast(app.name, line)
+}
+
+function runLogged(app, command, onExit) {
+  const log = createWriteStream(logPath(app.name), { flags: 'a' })
+  log.write(`\n--- ${new Date().toISOString()} $ ${command}\n`)
+  broadcast(app.name, `\n--- ${new Date().toISOString()} $ ${command}\n`)
+  const child = spawn(command, { cwd: join(PROJECT_DIR, app.folder), shell: true, env: process.env })
+  const tap = (d) => { log.write(d); broadcast(app.name, d) }
+  child.stdout.on('data', tap)
+  child.stderr.on('data', tap)
+  child.on('exit', (code) => { log.end(); onExit(code) })
+  return child
+}
+
+// ---- App lifecycle ---------------------------------------------------------------------
+async function probe(app) {
+  const url = app.health || `http://127.0.0.1:${app.port}/`
+  try {
+    await fetch(url, { signal: AbortSignal.timeout(800) })
+    return true
+  } catch { return false }
+}
+
+function buildApp(app) {
+  if (activity.has(app.name)) return
+  activity.set(app.name, 'building'); lastError.delete(app.name)
+  runLogged(app, app.build, (code) => {
+    activity.delete(app.name)
+    if (code !== 0) lastError.set(app.name, `build exited ${code} — see log`)
+    else logLine(app, 'build OK')
+  })
+}
+
+function deployApp(app) {
+  if (activity.has(app.name) || !app.deploy) return
+  activity.set(app.name, 'deploying'); lastError.delete(app.name)
+  runLogged(app, app.deploy, (code) => {
+    activity.delete(app.name)
+    if (code !== 0) lastError.set(app.name, `deploy exited ${code} — see log`)
+    else logLine(app, `deploy OK (${app.deployMethod})`)
+  })
+}
+
+function startApp(app) {
+  if (running.get(app.name) || activity.has(app.name)) return
+  failed.delete(app.name); lastError.delete(app.name)
+  if (app.method === 'container') {
+    runLogged(app, app.start, () => {})
+    saveState(); return
+  }
+  const child = runLogged(app, app.start, (code) => {
+    running.delete(app.name)
+    // A user-requested Stop exits nonzero (killed) — that is not a failure.
+    if (code !== 0 && !stopping.delete(app.name)) {
+      failed.set(app.name, true)
+      lastError.set(app.name, `process exited ${code} — see log`)
+    } else stopping.delete(app.name)
+    saveState()
+  })
+  running.set(app.name, child)
+  saveState()
+}
+
+// shell:true spawns a shell whose grandchildren survive child.kill() on Windows — kill the
+// whole tree there (taskkill /T); plain kill elsewhere.
+function killTree(child) {
+  if (process.platform === 'win32' && child.pid) {
+    try { execFileSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' }) } catch {}
+  } else {
+    try { child.kill() } catch {}
+  }
+}
+
+function stopApp(app) {
+  if (app.method === 'container' && app.stop && app.stop !== 'process-kill') {
+    try { execFileSync(app.stop.split(' ')[0], app.stop.split(' ').slice(1), { cwd: PROJECT_DIR }) } catch {}
+  } else {
+    const child = running.get(app.name)
+    if (!child) {
+      lastError.set(app.name, 'running outside this CI/CD app — stop it from where it was started')
+      return
+    }
+    stopping.add(app.name)
+    killTree(child)
+  }
+  running.delete(app.name)
+  saveState()
+}
+
+function json(res, code, body) {
+  res.writeHead(code, { 'content-type': 'application/json' })
+  res.end(JSON.stringify(body))
+}
+
+// ---- Page ------------------------------------------------------------------------------
+const PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>CI/CD</title><style>
+body{font-family:system-ui,sans-serif;margin:0;background:#f6f7f9;color:#1c2128;display:flex;flex-direction:column;height:100vh}
+.top{display:flex;gap:8px;align-items:center;padding:10px 12px 6px;font-size:13px}
+.meta{font-size:11px;color:#5b6572}
+.tabs{display:flex;gap:2px;padding:0 12px;border-bottom:1px solid #d9dee5;flex-wrap:wrap}
+.tab{border:1px solid #d9dee5;border-bottom:none;border-radius:8px 8px 0 0;background:#eef1f5;padding:6px 14px;font-size:13px;cursor:pointer;display:flex;gap:6px;align-items:center}
+.tab.active{background:#fff;font-weight:600}
+.tab .dot{width:8px;height:8px;border-radius:99px;background:#8a94a0}
+.dot.running{background:#1c8a4a}.dot.failed{background:#c23b3b}.dot.building,.dot.deploying{background:#c9922a}
+.bar{display:flex;gap:8px;align-items:center;padding:10px 12px;background:#fff;border-bottom:1px solid #e1e5ea;flex-wrap:wrap}
+.badge{font-size:10px;text-transform:uppercase;border-radius:99px;padding:2px 8px;color:#fff;background:#8a94a0}
+.badge.running{background:#1c8a4a}.badge.failed{background:#c23b3b}.badge.building,.badge.deploying{background:#c9922a}
+.url{font-size:12px;color:#1a66d0;text-decoration:underline;word-break:break-all}
+button{background:#fff;color:#1c2128;border:1px solid #c6cdd6;border-radius:6px;padding:4px 12px;font-size:12px;cursor:pointer}
+button:hover:enabled{background:#eef1f5}
+button:disabled{opacity:.4;cursor:default}
+.notice{padding:4px 12px;font-size:11px;color:#8a5a00;background:#fff7e6;display:none}
+.err{padding:4px 12px;font-size:11px;color:#c23b3b;display:none;white-space:pre-wrap}
+#log{flex:1;margin:0;padding:10px 12px;background:#0f1216;color:#d7dde4;font-size:11px;line-height:1.5;overflow:auto;white-space:pre-wrap}
+</style></head><body>
+<div class="top"><strong>CI/CD</strong><span id="branch" class="meta"></span></div>
+<div class="tabs" id="tabs"></div>
+<div class="bar" id="bar"></div>
+<div class="notice" id="notice"></div>
+<div class="err" id="err"></div>
+<pre id="log"></pre>
+<script>
+let state = { apps: [] }
+let active = null
+let ws = null, wsTimer = null
+
+function appOf(name){ return state.apps.find(a => a.name === name) }
+
+function renderTabs(){
+  document.getElementById('tabs').innerHTML = state.apps.map(a => \`
+    <div class="tab \${a.name===active?'active':''}" onclick="setActive('\${a.name}')">
+      <span class="dot \${a.phase}"></span>\${a.name}\${a.developedOnce===false?' 🔒':''}</div>\`).join('')
+}
+
+function renderBar(){
+  const a = appOf(active)
+  if (!a) return
+  const url = 'http://'+location.hostname+':'+a.port+'/'
+  const gate = a.developedOnce === true
+  const busy = a.phase==='building'||a.phase==='deploying'
+  document.getElementById('bar').innerHTML = \`
+    <span class="badge \${a.phase}">\${a.phase}\${a.external?' (external)':''}</span>
+    <span class="meta">\${a.method} · port \${a.port}</span>
+    <a class="url" href="\${url}" target="_blank" rel="noreferrer">\${url}</a>
+    <span style="flex:1"></span>
+    <button onclick="act('build')" \${!gate||busy||a.phase==='running'?'disabled':''}>Build</button>
+    <button onclick="act('start')" \${!gate||busy||a.phase==='running'?'disabled':''}>Start</button>
+    <button onclick="act('stop')" \${a.phase!=='running'||(a.external&&a.method!=='container')?'disabled':''}>Stop</button>
+    \${a.deploy?\`<button onclick="act('deploy')" \${!gate||busy?'disabled':''}>Deploy (\${a.deployMethod})</button>\`:''}\`
+  const notice = document.getElementById('notice')
+  if (a.developedOnce === false) {
+    notice.textContent = 'This application has not been developed through the workflow yet — run conductor-feature-develop first.'
+    notice.style.display = 'block'
+  } else if (a.developedOnce === null) {
+    notice.textContent = 'Develop status not verified yet (studio unreachable) — controls stay disabled.'
+    notice.style.display = 'block'
+  } else notice.style.display = 'none'
+  const err = document.getElementById('err')
+  if (a.error) { err.textContent = a.error; err.style.display = 'block' } else err.style.display = 'none'
+}
+
+function setActive(name){
+  if (active === name) return
+  active = name
+  closeWs()
+  document.getElementById('log').textContent = ''
+  openWs(name)
+  renderTabs(); renderBar()
+}
+
+// Live log stream. One socket at a time (closed on tab switch); auto-reconnect while the tab
+// stays active; the DOM buffer is trimmed so long sessions never grow the page unbounded.
+function openWs(name){
+  ws = new WebSocket('ws://'+location.host+'/ws?app='+encodeURIComponent(name))
+  ws.onmessage = e => appendLog(e.data)
+  ws.onclose = () => { ws = null; if (active === name) wsTimer = setTimeout(() => openWs(name), 2000) }
+}
+function closeWs(){
+  if (wsTimer) { clearTimeout(wsTimer); wsTimer = null }
+  if (ws) { ws.onclose = null; try { ws.close() } catch {} ws = null }
+}
+function appendLog(text){
+  const el = document.getElementById('log')
+  const atBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 40
+  el.textContent += text
+  if (el.textContent.length > 400000) el.textContent = el.textContent.slice(-250000)
+  if (atBottom) el.scrollTop = el.scrollHeight
+}
+
+async function refresh(){
+  const s = await fetch('/api/state').then(r => r.json()).catch(() => null)
+  if (!s) return
+  state = s
+  document.getElementById('branch').textContent = s.currentBranch ? 'branch: '+s.currentBranch : ''
+  if (!active && s.apps.length) setActive(s.apps[0].name)
+  renderTabs(); renderBar()
+}
+async function act(op){
+  await fetch('/api/apps/'+encodeURIComponent(active)+'/'+op, { method: 'POST' })
+  refresh()
+}
+refresh(); setInterval(refresh, 3000)
+</script></body></html>`
+
+// ---- HTTP ------------------------------------------------------------------------------
+const server = http.createServer(async (req, res) => {
+  if (req.method === 'GET' && req.url === '/') {
+    res.writeHead(200, { 'content-type': 'text/html' })
+    return res.end(PAGE)
+  }
+  if (req.method === 'GET' && req.url === '/api/state') {
+    const apps = await Promise.all(CONFIG.apps.map(async (a) => {
+      const healthy = await probe(a)
+      const phase = activity.get(a.name) || (healthy ? 'running' : failed.has(a.name) ? 'failed' : 'stopped')
+      return {
+        name: a.name, method: a.method, port: a.port, phase,
+        deploy: !!a.deploy, deployMethod: a.deployMethod || 'none',
+        external: healthy && !running.has(a.name),
+        developedOnce: developedOnce(a),
+        error: lastError.get(a.name) || null,
+      }
+    }))
+    return json(res, 200, { currentBranch: currentBranch(), apps })
+  }
+  const m = req.url && req.url.match(/^\/api\/apps\/([^/]+)\/(build|start|stop|deploy)$/)
+  if (m && req.method === 'POST') {
+    const app = CONFIG.apps.find((a) => a.name === decodeURIComponent(m[1]))
+    if (!app) return json(res, 404, { error: 'unknown app' })
+    if (m[2] !== 'stop' && developedOnce(app) === false) {
+      return json(res, 409, { error: 'application has not completed a develop workflow run' })
+    }
+    if (m[2] === 'build') buildApp(app)
+    else if (m[2] === 'start') startApp(app)
+    else if (m[2] === 'deploy') deployApp(app)
+    else stopApp(app)
+    return json(res, 200, { ok: true })
+  }
+  json(res, 404, { error: 'not found' })
+})
+
+// WebSocket endpoint /ws?app=<name> — push-only log stream (see "Log streaming" above).
+server.on('upgrade', (req, socket) => {
+  let name = ''
+  let isWsPath = false
+  try {
+    const url = new URL(req.url, 'http://x')
+    isWsPath = url.pathname === '/ws'
+    name = url.searchParams.get('app') || ''
+  } catch {}
+  const key = req.headers['sec-websocket-key']
+  const app = CONFIG.apps.find((a) => a.name === name)
+  if (!app || !key || !isWsPath) { socket.destroy(); return }
+  const accept = createHash('sha1').update(key + WS_GUID).digest('base64')
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
+    `Sec-WebSocket-Accept: ${accept}\r\n\r\n`,
+  )
+  let subs = subscribers.get(name)
+  if (!subs) { subs = new Set(); subscribers.set(name, subs) }
+  subs.add(socket)
+  const cleanup = () => { subs.delete(socket); try { socket.destroy() } catch {} }
+  socket.on('close', cleanup)
+  socket.on('error', cleanup)
+  // Client frames are only ever close (0x8) — anything else is ignored, never buffered.
+  socket.on('data', (buf) => { if ((buf[0] & 0x0f) === 0x8) cleanup() })
+  socket.write(wsFrame(logTail(name)))
+})
+
+server.listen(PORT, () => console.log(`cicd app on :${PORT}`))
+```
+
+`cicd/app/cicd.config.json` shape — one entry per application from the plan's Deployment
+Decisions table. `deployMethod`/`deploy` come from the plan's Deploy columns (`deploy` is
+`null` when the method is `none`):
+
+```json
+{
+  "port": 4100,
+  "apps": [
+    {
+      "name": "my-app",
+      "folder": "my-app",
+      "method": "process",
+      "port": 3000,
+      "build": "pnpm install && pnpm build",
+      "start": "node dist/index.js",
+      "stop": "process-kill",
+      "deployMethod": "kubernetes",
+      "deploy": "kubectl apply -f my-app/k8s/",
+      "health": "http://127.0.0.1:3000/"
+    }
+  ]
+}
+```

package/plugin/skills/util-plancicd/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: util-plancicd
+model: claude-sonnet-5
+effort: high
+description: >
+  Infer a local-deployment plan for every custom application of a CO2 project and write it to
+  cicd/CICD_PLAN.md for human review in Compound Context Studio. Reads the project's
+  ENVIRONMENT.md and DEVTOOL.md, CLAUDE.md (# Custom Applications, # Port Allocation) and each
+  application's context/specification/SPECIFICATION.md, then decides per application: deployment
+  method (container vs bare process), build command (e.g. Spring Boot jar vs Docker image),
+  start command, stop mechanism, deploy method + command (none / web-server copy / docker run /
+  kubectl apply — only when the environment calls for one), port and health-check URL, plus a
+  port for the generated CI/CD app itself. The plan carries a top-level
+  `**Status**: IN PROGRESS` header flipped to `COMPLETED` when done — the studio's watcher reads
+  it. This skill NEVER generates the CI/CD app (that is util-gencicdscript, which runs only
+  after the studio stamps an **Approved**: line into the plan). Trigger on keywords: "plan
+  cicd", "plan deployment", "cicd plan", "infer deployment", "deployment plan", "plan ci/cd".
+  Accepts one MANDATORY argument: the project-relative path of the plan-request markdown the
+  studio generated (e.g., /util-plancicd execution/cicd-plan-3-1753000000000.md).
+---
+
+# Util Plan CI/CD
+
+## Inputs
+
+```
+/util-plancicd <path-to-plan-request-md>
+```
+
+| Argument | Required | Description |
+|---|---|---|
+| path | yes | Project-relative path of the studio-generated plan-request markdown under `execution/` |
+
+If the argument is missing or the file does not exist, STOP and tell the user to click
+**Plan deployment** in the studio's CI/CD screen first.
+
+### Auto-Resolved Paths
+
+| Logical file | Path |
+|---|---|
+| Plan request | `<argument>` |
+| Environment | `ENVIRONMENT.md` (project root) |
+| Dev tools | `DEVTOOL.md` (project root) |
+| Project context | `CLAUDE.md` (project root; `source/CLAUDE.md` fallback) |
+| App specification | `<app_folder>/context/specification/SPECIFICATION.md` |
+| Output plan | `cicd/CICD_PLAN.md` |
+
+## Phase 1 — Gather
+
+1. Read the plan-request markdown; its `## Applications` list is the authoritative application set.
+2. Read `ENVIRONMENT.md` (registries, credentials, external services) and `DEVTOOL.md`
+   (installed tools + paths: node/pnpm/docker/kubectl/python versions).
+3. Read `CLAUDE.md`: `# Custom Applications` (folder names, Depends on) and `# Port Allocation`
+   (per-application ports).
+4. For each application, read its SPECIFICATION.md tech-stack section if present; otherwise
+   infer the stack from build files (`package.json` → node, `pom.xml` → spring-boot,
+   `composer.json` → laravel).
+
+## Phase 2 — Decide (per application)
+
+- **Working directory (CRITICAL)**: the generated CI/CD app executes every command with the
+  **application folder** (`<project>/<folder>`) as its working directory — NEVER the project
+  root. All paths inside build/start/stop/deploy commands must therefore be relative to the
+  application folder (`mvn -q package`, `java -jar target\app.jar`) — never prefixed with the
+  application folder itself (`skolafund_middleware\target\...` is WRONG).
+- **Method**: `container` only when Docker appears in DEVTOOL.md AND the stack has a sensible
+  container path; otherwise `process` (bare local process — the default for a dev VM).
+- **Build command**: from the stack (e.g. `pnpm install && pnpm build`, `mvn -q package`,
+  `composer install`). Use tool paths from DEVTOOL.md when the tool is not on PATH.
+- **Start command**: the stack's production-ish local start (e.g. `node dist/index.js`,
+  `java -jar target/<artifact>.jar`, `php artisan serve --port <port>`); `docker build`/
+  `docker run` pair when method=container. For jar-based stacks, resolve the EXACT artifact
+  filename — read the pom/gradle build config: a Maven `<finalName>` means
+  `target/<finalName>.jar` with NO version suffix (Spring Boot repackage keeps that name and
+  leaves a `.jar.original` beside it — never reference the `.original`). Never guess
+  `<app>-<version>.jar` and never use a `target/*.jar` glob (shell-dependent, breaks on
+  Windows cmd).
+- **Stop**: `process-kill` for bare processes; `docker stop <name>` for containers.
+- **Deploy** (method + command): only when ENVIRONMENT.md/DEVTOOL.md show a deployment target —
+  `kubernetes` (`kubectl apply -f <app>/k8s/` when kubectl + a cluster/kubeconfig appear),
+  `docker` (`docker run`/`docker compose up -d` when the image is the deliverable),
+  `web-server` (copy the built artifact into the configured web/app server, e.g. nginx html
+  root or Tomcat webapps, when one is configured). Default **`none`** — a bare local process
+  needs no deploy step beyond Start; never invent a target the config does not name.
+- **Port**: from `# Port Allocation`; if absent, assign sequentially from 3000 avoiding
+  collisions with the studio (3001) and the CI/CD app port.
+- **Health**: `http://127.0.0.1:<port>/` or a documented health endpoint from the spec.
+- **CI/CD app port**: 4100 unless taken in `# Port Allocation`; record it in the plan.
+
+## Phase 3 — Write the plan
+
+Create `cicd/` if missing and write `cicd/CICD_PLAN.md`:
+
+```markdown
+# CI/CD Deployment Plan — <Project Name>
+
+**Generated**: <ISO date>
+**Status**: IN PROGRESS
+
+## CI/CD App
+
+- **Port**: <port>
+- **Folder**: cicd/app
+
+## Deployment Decisions
+
+| Application | Folder | Method | Port | Build | Start | Stop | Deploy Method | Deploy | Health |
+|---|---|---|---|---|---|---|---|---|---|
+| <name> | <folder> | process|container | <port> | `<cmd>` | `<cmd>` | process-kill|docker stop | none|web-server|docker|kubernetes | `<cmd or ->` | <url> |
+
+## Rationale
+
+- <per-application: why this method/commands, citing ENVIRONMENT.md/DEVTOOL.md evidence>
+```
+
+Then flip `**Status**: IN PROGRESS` to `**Status**: COMPLETED`. The studio watcher advances
+only on COMPLETED.
+
+## STOP — Hand Back to the Human
+
+Print a one-paragraph summary and STOP. Never invoke util-gencicdscript or any other skill —
+the human reviews and approves the plan in the studio's CI/CD screen first.
+
+## Important Rules
+
+- Never write the CI/CD app; never modify PRD.md/CLAUDE.md/BUG.md.
+- Never delete an existing `**Approved**:` line if re-planning over a previous plan — overwrite
+  the whole file WITHOUT any Approved line (a re-plan always requires fresh approval).
+- Credentials from ENVIRONMENT.md may be referenced in commands verbatim (dev-environment
+  plaintext rule) but never echoed into the Rationale narrative.