xtruct 0.1.0__py3-none-any.whl

xtruct/_cli/lib/setup.js

@@ -0,0 +1,136 @@
+'use strict'
+// `xtruct setup`: wires Xtruct into Claude Code for every project on this machine.
+//   1. the `xtruct` command on PATH (a link in ~/.local/bin, plus the old `xtruct-foundry` name)
+//   2. the global `foundry` skill (~/.claude/skills/foundry)
+//   3. a marked block in ~/.claude/CLAUDE.md
+//   4. two hooks + one permission in ~/.claude/settings.json (merged, backed up first)
+// Safe to run again; `--uninstall` removes exactly what it added.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const os = require('node:os')
+const ui = require('./ui')
+
+const HOME = os.homedir()
+const CLAUDE = process.env.CLAUDE_CONFIG_DIR || path.join(HOME, '.claude')
+const SETTINGS = path.join(CLAUDE, 'settings.json')
+const CLAUDE_MD = path.join(CLAUDE, 'CLAUDE.md')
+const SKILL_DIR = path.join(CLAUDE, 'skills', 'foundry')
+const BIN_DIR = process.env.XTRUCT_FOUNDRY_BIN_DIR || path.join(HOME, '.local', 'bin')
+const ROOT = path.join(__dirname, '..')
+const CLI = path.join(ROOT, 'bin', 'xtruct.js')
+const COMMANDS = ['xtruct', 'xtruct-foundry'] // the second keeps hooks and notes from older installs working
+const MARK_START = '<!-- xtruct:start -->'
+const MARK_END = '<!-- xtruct:end -->'
+const LEGACY_MARKS = ['<!-- xtruct-foundry:start -->', '<!-- xtruct-foundry:end -->']
+const PERMISSION = 'Bash(xtruct:*)'
+const LEGACY_PERMISSIONS = ['Bash(xtruct-foundry:*)']
+const isOurs = h => typeof h.command === 'string' && /bin[\\/]xtruct(-foundry)?\.js"? hook /.test(h.command)
+
+const q = s => `"${s.replace(/(["\\$`])/g, '\\$1')}"`
+const hookCommand = event => `${q(process.execPath)} ${q(CLI)} hook ${event}`
+
+function readSettings() {
+  if (!fs.existsSync(SETTINGS)) return {}
+  try { return JSON.parse(fs.readFileSync(SETTINGS, 'utf8')) } catch (e) {
+    throw new Error(`${SETTINGS} is not valid JSON (${e.message}). Fix it first; setup will not overwrite it.`)
+  }
+}
+
+/** Remove our hook entries, keep everything else, drop now-empty groups. */
+function withoutOurHooks(hooks = {}) {
+  const out = {}
+  for (const [event, groups] of Object.entries(hooks)) {
+    const kept = groups.map(g => ({ ...g, hooks: (g.hooks || []).filter(h => !isOurs(h)) })).filter(g => g.hooks.length)
+    if (kept.length) out[event] = kept
+  }
+  return out
+}
+
+function plan({ uninstall }) {
+  const settings = readSettings()
+  const next = JSON.parse(JSON.stringify(settings))
+  next.hooks = withoutOurHooks(settings.hooks)
+  next.permissions = next.permissions || {}
+  next.permissions.allow = (next.permissions.allow || []).filter(p => p !== PERMISSION && !LEGACY_PERMISSIONS.includes(p))
+  if (!uninstall) {
+    const add = (event, cmd, extra) => (next.hooks[event] ||= []).push({ hooks: [{ type: 'command', command: cmd, timeout: 10, ...extra }] })
+    add('UserPromptSubmit', hookCommand('prompt'))
+    add('SessionStart', hookCommand('session'))
+    next.permissions.allow.push(PERMISSION)
+  }
+  if (!Object.keys(next.hooks).length) delete next.hooks
+  if (!next.permissions.allow.length) delete next.permissions.allow
+  if (!Object.keys(next.permissions).length) delete next.permissions
+
+  const md = fs.existsSync(CLAUDE_MD) ? fs.readFileSync(CLAUDE_MD, 'utf8') : ''
+  const strip = (text, [start, end]) => text.replace(new RegExp(`\\n*${start}[\\s\\S]*?${end}\\n*`), '\n')
+  const stripped = [[MARK_START, MARK_END], LEGACY_MARKS].reduce(strip, md).replace(/^\n+/, '')
+  const block = fs.readFileSync(path.join(ROOT, 'global', 'claude-md-block.md'), 'utf8').trim()
+  const nextMd = uninstall ? stripped : `${stripped.trimEnd()}${stripped.trim() ? '\n\n' : ''}${MARK_START}\n${block}\n${MARK_END}\n`
+
+  return { settings, next, md, nextMd }
+}
+
+function run({ dryRun = false, uninstall = false, version }) {
+  console.log(ui.banner(version, uninstall ? 'Removing Xtruct from Claude Code' : 'Wiring Xtruct into Claude Code'))
+  let p
+  try { p = plan({ uninstall }) } catch (e) {
+    console.error(`  ${ui.badge(ui.C.rose, 'error')} ${e.message}\n`)
+    process.exit(1)
+  }
+  const step = (label, detail) => console.log(`  ${dryRun ? ui.sym.info : ui.sym.ok} ${ui.padEnd(label, 26)}${ui.dim(detail)}`)
+  const home = s => s.replace(HOME, '~')
+
+  // 1. Command on PATH
+  const link = path.join(BIN_DIR, COMMANDS[0])
+  if (!dryRun) {
+    fs.mkdirSync(BIN_DIR, { recursive: true })
+    for (const name of COMMANDS) {
+      const l = path.join(BIN_DIR, name)
+      try { fs.unlinkSync(l) } catch {}
+      if (!uninstall) fs.symlinkSync(CLI, l)
+    }
+  }
+  const onPath = (process.env.PATH || '').split(':').includes(BIN_DIR)
+  step(uninstall ? 'Removed command' : 'Command', `${home(link)}${uninstall ? '' : ' → ' + home(CLI)}`)
+  if (!uninstall && !onPath) console.log(`    ${ui.sym.warn} ${ui.dim(`${home(BIN_DIR)} is not on your PATH; add it to ~/.zshrc: export PATH="${home(BIN_DIR)}:$PATH"`)}`)
+
+  // 2. Skill
+  if (!dryRun) {
+    fs.rmSync(SKILL_DIR, { recursive: true, force: true })
+    if (!uninstall) {
+      fs.mkdirSync(SKILL_DIR, { recursive: true })
+      fs.copyFileSync(path.join(ROOT, 'global', 'skills', 'foundry', 'SKILL.md'), path.join(SKILL_DIR, 'SKILL.md'))
+    }
+  }
+  step(uninstall ? 'Removed skill' : 'Skill', home(SKILL_DIR))
+
+  // 3. CLAUDE.md block
+  if (!dryRun && p.nextMd !== p.md) {
+    fs.mkdirSync(CLAUDE, { recursive: true })
+    if (p.nextMd.trim()) fs.writeFileSync(CLAUDE_MD, p.nextMd)
+    else fs.rmSync(CLAUDE_MD, { force: true })
+  }
+  step(uninstall ? 'Removed instructions' : 'Instructions', `${home(CLAUDE_MD)} (marked block)`)
+
+  // 4. Settings: back up, then write the merge
+  if (!dryRun && JSON.stringify(p.settings) !== JSON.stringify(p.next)) {
+    if (fs.existsSync(SETTINGS)) fs.copyFileSync(SETTINGS, `${SETTINGS}.bak-foundry`)
+    fs.writeFileSync(SETTINGS, JSON.stringify(p.next, null, 2) + '\n')
+  }
+  step(uninstall ? 'Removed hooks' : 'Hooks', uninstall ? home(SETTINGS) : `UserPromptSubmit + SessionStart in ${home(SETTINGS)}`)
+  if (!uninstall) step('Permission', `${PERMISSION} (no prompt for tracking calls)`)
+  if (!dryRun && fs.existsSync(`${SETTINGS}.bak-foundry`)) console.log(`    ${ui.dim('previous settings saved to ' + home(SETTINGS) + '.bak-foundry')}`)
+
+  console.log()
+  if (dryRun) console.log(`  ${ui.dim('Dry run: nothing changed.')}\n`)
+  else if (uninstall) console.log(`  ${ui.dim('Your journal and work items stay in ~/.config/xtruct until you delete them.')}\n`)
+  else console.log(ui.box([
+    `Restart Claude Code (or open ${ui.cmd('/hooks')} once) to load the hooks.`,
+    `Then every prompt is journaled, and each session opens`,
+    `with where you left off. See it all with ${ui.cmd('xtruct status')}.`,
+  ], { title: 'Done', color: ui.C.green }) + '\n')
+}
+
+module.exports = { run, plan, hookCommand, withoutOurHooks, MARK_START, MARK_END, PERMISSION }

xtruct/_cli/lib/tracker.js

@@ -0,0 +1,155 @@
+'use strict'
+// Personal work tracking across every project on this machine.
+//   journal.jsonl  every prompt you send (written by the UserPromptSubmit hook)
+//   tracker.json   work items Claude opens and closes with `xtruct track`
+// Both live in ~/.config/xtruct/, are readable only by you, and never leave this machine.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const os = require('node:os')
+const { spawnSync } = require('node:child_process')
+
+const { CONFIG_DIR: DIR } = require('./paths')
+const JOURNAL = path.join(DIR, 'journal.jsonl')
+const TRACKER = path.join(DIR, 'tracker.json')
+const JOURNAL_MAX_BYTES = 4 * 1024 * 1024
+const STATES = ['open', 'doing', 'blocked', 'done', 'dropped']
+const ACTIVE = new Set(['open', 'doing', 'blocked'])
+
+function ensureDir() {
+  fs.mkdirSync(DIR, { recursive: true, mode: 0o700 })
+}
+
+/** The project a directory belongs to: its git root, or the directory itself. */
+function projectOf(cwd = process.cwd()) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', timeout: 3000 })
+  if (r.status === 0) return r.stdout.trim()
+  try { return fs.realpathSync(cwd) } catch { return path.resolve(cwd) }
+}
+
+const short = p => p.replace(os.homedir(), '~')
+
+// ---------- journal ----------
+
+function appendJournal(entry) {
+  ensureDir()
+  try {
+    if (fs.statSync(JOURNAL).size > JOURNAL_MAX_BYTES) {
+      // Keep the newest half so the file stays small without losing recent history.
+      const lines = fs.readFileSync(JOURNAL, 'utf8').trim().split('\n')
+      fs.writeFileSync(JOURNAL, lines.slice(Math.floor(lines.length / 2)).join('\n') + '\n', { mode: 0o600 })
+    }
+  } catch { /* no journal yet */ }
+  fs.appendFileSync(JOURNAL, JSON.stringify(entry) + '\n', { mode: 0o600 })
+}
+
+function readJournal() {
+  try {
+    return fs.readFileSync(JOURNAL, 'utf8').trim().split('\n').filter(Boolean).map(l => {
+      try { return JSON.parse(l) } catch { return null }
+    }).filter(Boolean)
+  } catch { return [] }
+}
+
+// ---------- tracker ----------
+
+function load() {
+  try { return JSON.parse(fs.readFileSync(TRACKER, 'utf8')) } catch { return { next: 1, items: [] } }
+}
+
+function save(db) {
+  ensureDir()
+  const tmp = TRACKER + '.tmp'
+  fs.writeFileSync(tmp, JSON.stringify(db, null, 2) + '\n', { mode: 0o600 })
+  fs.renameSync(tmp, TRACKER)
+}
+
+function add({ title, project, link, note }) {
+  const db = load()
+  const now = new Date().toISOString()
+  const item = { id: db.next++, title, project, state: 'open', link: link || null, notes: note ? [{ at: now, text: note }] : [], created: now, updated: now }
+  db.items.push(item)
+  save(db)
+  return item
+}
+
+function update(id, { state, note, link }) {
+  const db = load()
+  const item = db.items.find(i => i.id === Number(id))
+  if (!item) return null
+  const now = new Date().toISOString()
+  if (state) {
+    if (!STATES.includes(state)) throw new Error(`unknown state ${state}; use ${STATES.join(', ')}`)
+    item.state = state
+  }
+  if (link) item.link = link
+  if (note) item.notes.push({ at: now, text: note })
+  item.updated = now
+  save(db)
+  return item
+}
+
+function list({ project, all } = {}) {
+  return load().items
+    .filter(i => (all || ACTIVE.has(i.state)) && (!project || i.project === project))
+    .sort((a, b) => (a.project === b.project ? a.id - b.id : a.project.localeCompare(b.project)))
+}
+
+// ---------- views ----------
+
+function gitSummary(root) {
+  const branch = spawnSync('git', ['branch', '--show-current'], { cwd: root, encoding: 'utf8', timeout: 3000 })
+  if (branch.status !== 0) return null
+  const status = spawnSync('git', ['status', '--porcelain'], { cwd: root, encoding: 'utf8', timeout: 5000 })
+  const lines = (status.stdout || '').split('\n').filter(Boolean)
+  return { branch: branch.stdout.trim() || '(detached)', changed: lines.length, untracked: lines.filter(l => l.startsWith('??')).length }
+}
+
+const ago = iso => {
+  const s = (Date.now() - new Date(iso)) / 1000
+  return s < 90 ? 'just now' : s < 5400 ? `${Math.round(s / 60)}m ago` : s < 129600 ? `${Math.round(s / 3600)}h ago` : `${Math.round(s / 86400)}d ago`
+}
+
+/** Plain-text "where you left off" for one project. Used by the SessionStart hook. */
+function resume(project) {
+  const items = list({ project })
+  const prompts = readJournal().filter(e => e.project === project).slice(-6)
+  const git = gitSummary(project)
+  const isProduct = fs.existsSync(path.join(project, 'foundry.config.json'))
+  const lines = [`Where the founder left off in ${short(project)}${isProduct ? ' (an Xtruct product)' : ''}:`]
+  if (git) lines.push(`- git: on ${git.branch}, ${git.changed ? `${git.changed} uncommitted change${git.changed > 1 ? 's' : ''}` : 'clean'}`)
+  if (items.length) {
+    lines.push('- open work items (xtruct track):')
+    for (const i of items) {
+      const note = i.notes.at(-1)
+      lines.push(`  #${i.id} [${i.state}] ${i.title}${i.link ? ` · ${i.link}` : ''} · updated ${ago(i.updated)}${note ? ` · last note: ${note.text}` : ''}`)
+    }
+  } else lines.push('- no open work items')
+  if (prompts.length) {
+    lines.push('- recent requests here:')
+    for (const p of prompts) lines.push(`  ${ago(p.at)}: ${p.prompt.replace(/\s+/g, ' ').slice(0, 160)}`)
+  }
+  const elsewhere = list().filter(i => i.project !== project)
+  if (elsewhere.length) {
+    const byProject = [...new Set(elsewhere.map(i => short(i.project)))]
+    lines.push(`- also open elsewhere: ${elsewhere.length} item${elsewhere.length > 1 ? 's' : ''} in ${byProject.slice(0, 4).join(', ')}${byProject.length > 4 ? '…' : ''}`)
+  }
+  return { text: lines.join('\n'), items, prompts, git }
+}
+
+/** Every project with open items or recent activity, newest first. */
+function portfolio({ days = 14 } = {}) {
+  const since = Date.now() - days * 864e5
+  const projects = new Map()
+  const touch = (p, at) => {
+    const cur = projects.get(p) || { project: p, items: [], prompts: 0, last: null }
+    if (at && (!cur.last || at > cur.last)) cur.last = at
+    projects.set(p, cur)
+    return cur
+  }
+  for (const e of readJournal()) if (new Date(e.at) >= since) touch(e.project, e.at).prompts++
+  for (const i of list()) touch(i.project, i.updated).items.push(i)
+  return [...projects.values()].sort((a, b) => (b.last || '').localeCompare(a.last || ''))
+}
+
+module.exports = { DIR, JOURNAL, TRACKER, STATES, projectOf, appendJournal, readJournal, add, update, list, resume, portfolio, gitSummary, ago, short }

xtruct/_cli/lib/ui.js

@@ -0,0 +1,95 @@
+'use strict'
+// Terminal styling in the Xtruct palette. No dependencies.
+// Colour turns off for pipes, NO_COLOR and TERM=dumb, and turns on with FORCE_COLOR.
+// Truecolor where the terminal says it supports it, the nearest xterm-256 colour otherwise.
+
+const env = process.env
+const out = process.stdout
+
+const enabled = env.FORCE_COLOR !== undefined
+  ? env.FORCE_COLOR !== '0'
+  : Boolean(out.isTTY) && !('NO_COLOR' in env) && env.TERM !== 'dumb'
+const truecolor = enabled && (
+  /truecolor|24bit/i.test(env.COLORTERM || '') ||
+  /^(iTerm\.app|vscode|WezTerm|ghostty|Hyper|WarpTerminal)$/.test(env.TERM_PROGRAM || '')
+)
+
+// DESIGN.md semantic palette.
+const C = {
+  cyan: '#22D3EE', // focus, primary
+  green: '#34D399', // success, verified
+  violet: '#A78BFA', // persisted state
+  amber: '#FBBF24', // attention
+  rose: '#FB7185', // failure, guarded
+  orange: '#FB923C',
+  slate: '#94A3B8', // secondary text
+  dim: '#64748B',
+}
+
+const rgb = hex => [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16))
+const to256 = ([r, g, b]) => {
+  const c = v => (v < 48 ? 0 : v < 115 ? 1 : Math.round((v - 35) / 40))
+  return 16 + 36 * c(r) + 6 * c(g) + c(b)
+}
+const fg = ([r, g, b]) => (truecolor ? `38;2;${r};${g};${b}` : `38;5;${to256([r, g, b])}`)
+const bg = ([r, g, b]) => (truecolor ? `48;2;${r};${g};${b}` : `48;5;${to256([r, g, b])}`)
+const sgr = (codes, s) => (enabled ? `\x1b[${codes}m${s}\x1b[0m` : String(s))
+
+const paint = (hex, s) => sgr(fg(rgb(hex)), s)
+const bold = s => sgr('1', s)
+const dim = s => sgr('2', s)
+// Bold midnight text on a palette colour, for status chips.
+const badge = (hex, s) => sgr(`1;${truecolor ? '38;2;2;6;23' : '38;5;16'};${bg(rgb(hex))}`, ` ${s} `)
+
+/** Per-character gradient between two hex colours. */
+function gradient(text, from, to) {
+  if (!enabled) return text
+  const a = rgb(from), b = rgb(to), chars = [...text]
+  return chars.map((ch, i) => {
+    const t = chars.length > 1 ? i / (chars.length - 1) : 0
+    return ch === ' ' ? ch : sgr(fg(a.map((v, k) => Math.round(v + (b[k] - v) * t))), ch)
+  }).join('')
+}
+
+const strip = s => String(s).replace(/\x1b\[[0-9;]*m/g, '')
+const width = s => [...strip(s)].length
+const padEnd = (s, n) => s + ' '.repeat(Math.max(0, n - width(s)))
+const columns = () => Math.max(60, Math.min(out.columns || 80, 100))
+
+const sym = {
+  ok: paint(C.green, '✓'),
+  fail: paint(C.rose, '✗'),
+  warn: paint(C.amber, '!'),
+  info: paint(C.cyan, '›'),
+  dot: paint(C.dim, '·'),
+  mark: paint(C.cyan, '◆'),
+}
+
+/** The product header: a gradient wordmark, version and tagline. */
+function banner(version, tagline) {
+  const word = gradient('xtruct', C.cyan, C.violet)
+  return `\n  ${sym.mark} ${word}  ${dim('v' + version)}\n    ${paint(C.slate, tagline)}\n`
+}
+
+/** A rounded panel. `lines` may contain ANSI; the title sits in the top border. */
+function box(lines, { title = '', color = C.dim, pad = 1 } = {}) {
+  const inner = Math.max(...lines.map(width), width(title) + 2) + pad * 2
+  const edge = s => paint(color, s)
+  const top = title
+    ? edge('╭─ ') + bold(title) + edge(' ' + '─'.repeat(Math.max(0, inner - width(title) - 3)) + '╮')
+    : edge('╭' + '─'.repeat(inner) + '╮')
+  const body = lines.map(l => edge('│') + ' '.repeat(pad) + padEnd(l, inner - pad * 2) + ' '.repeat(pad) + edge('│'))
+  return ['  ' + top, ...body.map(l => '  ' + l), '  ' + edge('╰' + '─'.repeat(inner) + '╯')].join('\n')
+}
+
+/** Rows of cells, left-aligned to the widest cell in each column. */
+function table(rows, { gap = 3, indent = 2 } = {}) {
+  const widths = rows.reduce((w, r) => r.map((c, i) => Math.max(w[i] || 0, width(c))), [])
+  return rows.map(r => ' '.repeat(indent) + r.map((c, i) => (i < r.length - 1 ? padEnd(c, widths[i] + gap) : c)).join('')).join('\n')
+}
+
+const heading = s => `\n  ${paint(C.slate, bold(s.toUpperCase().split('').join(' ')))}`
+const cmd = s => paint(C.cyan, s)
+const code = s => paint(C.violet, s)
+
+module.exports = { enabled, C, paint, bold, dim, badge, gradient, strip, width, padEnd, columns, sym, banner, box, table, heading, cmd, code }

xtruct/_cli/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@masst/xtruct",
+  "version": "0.1.0",
+  "description": "A software company made of Claude Code agents: architect, senior leads, junior devs, reviewers, integrator and QA, with ClickUp as the board and gated PR merges.",
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "multi-agent",
+    "clickup",
+    "scaffold",
+    "code-review",
+    "workflow"
+  ],
+  "license": "MIT",
+  "author": "Aditya Narayan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AdityaNarayan29/xtruct.git",
+    "directory": "foundry"
+  },
+  "homepage": "https://xtruct.masst.dev",
+  "bugs": "https://github.com/AdityaNarayan29/xtruct/issues",
+  "bin": {
+    "xtruct": "bin/xtruct.js",
+    "xtruct-foundry": "bin/xtruct-foundry.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "global/",
+    "template/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.3"
+  },
+  "scripts": {
+    "test": "bash test/run.sh"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

xtruct/_cli/template/.claude/agents/architect.md

@@ -0,0 +1,35 @@
+---
+name: architect
+description: Turns the founder's product idea into a PRD, architecture, stack choice, frozen contracts and an epic plan. Use at the start of a product or when the founder asks for a design change.
+---
+
+You are the architect of an AI-run software company. You turn the founder's idea into a plan that a team of parallel agents can build without stepping on each other.
+
+## Modes
+
+**SPEC**: from the idea in your prompt, write:
+
+1. `docs/PRD.md` from `docs/templates/PRD.md`: problem, users, MVP scope, explicit non-goals, user flows, acceptance criteria per flow.
+2. `docs/ARCHITECTURE.md` from `docs/templates/ARCHITECTURE.md`: the stack and why, alternatives rejected, components, data flow, auth, deployment, observability.
+3. `docs/CONVENTIONS.md`: stack-specific rules juniors must follow (folder layout, naming, error handling, testing patterns, how to add an endpoint/page/migration).
+4. `contracts/`: DB schema, API spec (OpenAPI, GraphQL SDL or typed RPC definitions), shared domain types, route/screen map. Parallel work depends on these, so make them complete enough that two juniors building opposite sides of an API never need to talk.
+5. An epic plan (returned to the caller): epics with goal, acceptance criteria and dependencies.
+6. If Xtruct is enabled (see CLAUDE.md → Diagrams): `docs/diagrams/architecture.html`, an Xtruct architecture diagram of the components, data stores and main request path from `docs/ARCHITECTURE.md` and `contracts/`. Link it at the top of `docs/ARCHITECTURE.md`. In REVISE mode, regenerate it if the architecture changed.
+
+**REVISE**: apply the critique in your prompt to the docs and epic plan. Accept or reject each point, and record rejected points with reasons under "Decisions" in `docs/ARCHITECTURE.md`.
+
+## Stack choice
+
+- Pick for the requirements, not for novelty. Prefer boring, well-documented tech that agents know well.
+- Prefer package managers with shared content-addressed caches (pnpm, uv, cargo). Many worktrees install in parallel, and npm/pip without a cache will choke the disk.
+- Everything must run locally with one `make setup && make dev`. Use Docker Compose for databases and queues.
+- Testing must cover unit, integration and real-browser E2E (Playwright for web).
+
+## Epic rules
+
+- Epic 1 is always **Foundation**: scaffold the stack, implement every Makefile target, add `.github/workflows/ci.yml` from `docs/templates/ci.yml` (job name `ci`), lint/format/typecheck config, unit + E2E harnesses with one passing smoke test each, commit `contracts/` as code (generated types, migrations), seed data, `.env.example`.
+- Feature epics are vertical slices (a user-visible capability end to end) and depend only on Foundation where possible, so they can run in parallel.
+- Each epic should split into roughly 5–20 tasks, with no more than ~12 runnable at the same moment. One workflow runs at most 16 agents, so a wider epic should become two sibling epics with no dependency between them; they then run side by side.
+- Last epic: **Hardening**: security review, performance, error states, accessibility, deployment.
+
+Commit docs and contracts with `docs:` commits. You may commit directly on local `main` only before the GitHub repo exists (no `origin` remote); after that, use a branch and a PR like everyone else.

xtruct/_cli/template/.claude/agents/integrator.md

@@ -0,0 +1,16 @@
+---
+name: integrator
+description: Merges an approved PR through the gated merge script, rebasing on conflicts, and updates ClickUp. The only agent that merges.
+---
+
+You are the integrator. You merge PRs only through `scripts/merge-pr.sh <n>`. Never use `gh pr merge` or the merge API directly, and never add approval labels yourself.
+
+## Procedure
+
+1. Run `scripts/merge-pr.sh <n>`. It waits for CI, checks the labels, scope, size and founder-only paths, takes a cross-agent merge lock, and squash-merges.
+2. By exit code:
+   - `0`: merged. Set the ClickUp task to `merged` and comment the merge SHA the script printed.
+   - `2`: the gate rejected it. **Do not work around it.** Return `merged: false` with the script's reason.
+   - `3`: conflicts with `main`. In your worktree: `git fetch origin && git switch -c rebase-work origin/<branch> && git rebase origin/main`. Resolve only mechanical conflicts (imports, adjacent additions, lockfiles regenerated with the package manager). Run `make lint typecheck test`, `git push --force-with-lease origin HEAD:<branch>`, then rerun the script once. If the conflict needs real judgment, abort the rebase and return `merged: false, needs_rebase: true` with what conflicts.
+   - anything else: return `merged: false` with the error output.
+3. Return `merged`, `merge_sha`, `needs_rebase`, `reason`.

xtruct/_cli/template/.claude/agents/junior-dev.md

@@ -0,0 +1,31 @@
+---
+name: junior-dev
+description: Implements exactly one scoped ClickUp task with tests on its own branch and opens a PR, or fixes an existing PR from review feedback. Use for a single task from a senior lead.
+---
+
+You are a junior developer. You own exactly one task. You work in an isolated git worktree, so other juniors are working in parallel on other files.
+
+## BUILD mode
+
+1. Set the ClickUp task to `in progress`.
+2. `git fetch origin && git switch -c t/<clickup-id>-<slug> origin/main`.
+3. Read the parts of `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/CONVENTIONS.md` and `contracts/` your task touches, and the existing code around your scope. Match its patterns.
+4. Install dependencies if needed (`make setup`).
+5. Write tests for the acceptance criteria first, then the implementation. Change only files matching your scope globs. If the task can't be done inside scope, or needs a contract change, stop and report it; don't expand scope yourself.
+6. Run `make lint typecheck test`, plus `make e2e` if you touched a user flow and the harness exists. Fix until green. Never weaken, skip or delete a test to get green.
+7. Commit, `git push -u origin HEAD`, then `gh pr create` using `.github/pull_request_template.md`: fill in the scope block with your scope globs and link the ClickUp task.
+8. Comment the PR link on the ClickUp task and set it to `in review`.
+9. Return the PR number, branch, and whether the checks passed locally. Be honest: if something doesn't work, say so in `notes`.
+
+## FIX mode
+
+You get a PR number, its branch, and numbered blocking issues.
+
+1. `git fetch origin && git switch -c fix-work origin/<branch>`.
+2. If asked to resolve conflicts: `git rebase origin/main`, resolve keeping both sides' intent, rerun the tests.
+3. Address **every** blocking issue. If you disagree with one, explain in a PR comment instead of silently skipping it.
+4. Run the checks again, then `git push --force-with-lease origin HEAD:<branch>` (only plain `git push origin HEAD:<branch>` if you didn't rebase).
+5. Remove stale approvals: `gh pr edit <n> --remove-label review:passed --remove-label lead:approved`.
+6. Comment on the PR listing what you changed per issue. Return the same fields as BUILD.
+
+Do not open a second PR for the same task.

xtruct/_cli/template/.claude/agents/qa-lead.md

@@ -0,0 +1,17 @@
+---
+name: qa-lead
+description: Verifies merged work on a fresh origin/main by running the full suite and walking the epic's acceptance criteria in the running app; files bugs in ClickUp. Use after an epic's tasks merge.
+---
+
+You are the QA lead. Your job is to find out whether the product actually works, not to confirm that it does.
+
+## VERIFY mode
+
+1. In your worktree: `git fetch origin && git switch --detach origin/main`.
+2. `make setup && make ci`. Record every failure.
+3. Start the app (`make dev` in the background), then walk each acceptance criterion of the epic (from ClickUp and `docs/PRD.md`) the way a user would: Playwright for web UIs, real HTTP calls for APIs. Try the unhappy paths too: bad input, unauthorized access, empty states, refresh mid-flow.
+4. Where an acceptance criterion has no E2E test, add one on a branch `qa/<epic-slug>` and open a PR (scope: the E2E test directory), so it is guarded from now on.
+5. File each defect as a ClickUp task in the `Epics` list, tagged `bug`, linked to the epic, with steps to reproduce, expected vs actual, and severity (`blocker`, `major`, `minor`).
+6. Stop the app. Return `passed` (no blockers or majors, and `make ci` green), a short summary, and the bugs.
+
+Never mark something as passing that you didn't actually run.

xtruct/_cli/template/.claude/agents/reviewer.md

@@ -0,0 +1,23 @@
+---
+name: reviewer
+description: Read-only code reviewer for one PR. Checks correctness, security, test quality, scope and conventions, then labels or requests changes. Use for every PR before merge.
+---
+
+You are a strict but fair code reviewer. You never edit code and never check out branches in the main working tree. Work only from `gh pr view <n>`, `gh pr diff <n>`, `gh pr checks <n>`, and reading files on `origin/main` (`git show origin/main:<path>`).
+
+## Checklist
+
+1. **Correctness**: does the diff do what the task's acceptance criteria say? Look for edge cases, error paths, off-by-one errors, races, and nulls.
+2. **Tests**: each acceptance criterion has a test that would fail without the change. No tautological tests, no over-mocking that hides the real behavior, no skipped tests.
+3. **Security**: authn/authz on every new endpoint, input validation, injection (SQL, shell, HTML), secrets in code, unsafe deserialization, data leaking across tenants or users.
+4. **Contracts**: request/response shapes, DB schema and shared types match `contracts/` exactly.
+5. **Scope**: changed files are within the PR's scope block; no drive-by refactors.
+6. **Conventions**: follows `docs/CONVENTIONS.md`; matches surrounding code.
+7. **CI**: `gh pr checks` is green, or pending with no failures.
+
+## Verdict
+
+- Approve when nothing is blocking: `gh pr edit <n> --add-label review:passed` plus a short PR comment.
+- Otherwise: a PR comment with numbered blocking issues, each with file:line and what to change. Remove `review:passed` if present.
+- Only correctness, security, missing tests, contract violations and scope breaks are blocking. Put style nits in `notes`.
+- Return `approved`, `blocking_issues`, `notes`.

xtruct/_cli/template/.claude/agents/senior-lead.md

@@ -0,0 +1,29 @@
+---
+name: senior-lead
+description: Senior engineer who owns one epic. Splits it into parallelizable tasks in ClickUp, approves junior PRs for spec fit, and reports the epic outcome. Use for epic planning, PR approval, and epic reports.
+---
+
+You are a senior engineer leading one epic. Your juniors are capable but literal: they build exactly what the task says, so your task specs carry the quality.
+
+## Modes
+
+**PLAN**: split the epic into tasks.
+
+1. Read the epic in ClickUp, `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/CONVENTIONS.md`, `contracts/`, and the current code on `origin/main` (`git fetch origin` first, and read via `git show origin/main:<path>` or a fresh look at the tree).
+2. Write tasks a junior can finish in one sitting: one PR, under ~800 changed lines.
+3. Every task has:
+   - `spec`: what to build, the files/modules involved, which contract it implements, and **acceptance criteria as testable statements**.
+   - `scope`: glob paths the task may change. **Two tasks that can run at the same time must not share a file.** If they must, add a dependency. Shared groundwork (a base component, a shared util, a DB migration) gets its own task that others depend on.
+   - `depends_on`: keys of tasks that must merge first. Keep the graph wide and shallow; parallelism is the point.
+4. Create each task as a ClickUp subtask of the epic, with spec, acceptance criteria, scope and dependencies in the description. Return the ClickUp id for each task.
+5. Set the epic to `in progress`.
+
+**APPROVE**: judge a PR for spec fit, not style (the reviewer covers code quality).
+
+- Read the task, `gh pr view <n>`, `gh pr diff <n>`, and `gh pr checks <n>`.
+- Does it do what the task and epic intend? Are all acceptance criteria actually covered by tests? Did it stay in scope? Would the next tasks in the epic build cleanly on it?
+- Approve: `gh pr edit <n> --add-label lead:approved` plus a short PR comment. Add `large-ok` only if an oversized PR genuinely can't be split.
+- Reject: PR comment with numbered blocking issues, remove `lead:approved` if present.
+- Return `approved` and `blocking_issues`. Nitpicks are not blocking.
+
+**REPORT**: if Xtruct is enabled (see CLAUDE.md → Diagrams), first create an Xtruct diagram of what this epic built: the components and flows the merged tasks added or changed, marking anything rejected or blocked. Write it outside the repo (e.g. under `/tmp`) and attach it to the ClickUp epic, so it never needs a PR. Then post the epic report as a comment on the ClickUp epic, mentioning the attached diagram: what merged (with PR links), what failed or is blocked and why, QA result, bugs filed, and what the founder should check by hand. Set the epic to `in review` if everything merged and QA passed; otherwise `blocked`. Return the report text.

xtruct/_cli/template/.claude/hooks/guard-bash.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# PreToolUse guard for Bash: blocks commands that bypass the company's git and merge rules.
+# Exit 2 = block, stderr is shown to the agent. Founder override: FOUNDRY_ALLOW_PROTECTED=1.
+set -euo pipefail
+
+[ "${FOUNDRY_ALLOW_PROTECTED:-0}" = 1 ] && exit 0
+
+cmd=$(jq -r '.tool_input.command // empty')
+[ -z "$cmd" ] && exit 0
+
+block() { echo "Blocked by company guardrail: $1" >&2; exit 2; }
+has() { grep -Eq -- "$1" <<<"$cmd"; }
+
+# Pushing to main, or force-pushing without lease.
+has 'git[[:space:]][^;&|]*push[^;&|]*([[:space:]]|:|/)(main|master)([[:space:]]|$)' \
+  && block "never push to main. Push your task branch and open a PR."
+has 'git[[:space:]][^;&|]*push[^;&|]*(--force([[:space:]]|$)|[[:space:]]-f([[:space:]]|$)|[[:space:]]\+[^[:space:]])' \
+  && block "plain force-push is not allowed. Use --force-with-lease on your own task branch."
+has '--no-verify' && block "--no-verify skips the checks. Fix what the hook complains about."
+
+# Merging outside the gate.
+has 'gh[[:space:]]+pr[[:space:]]+merge' && block "merges go through scripts/merge-pr.sh (integrator only)."
+has 'gh[[:space:]]+api.*/merge([[:space:]"'"'"']|$)' && block "merges go through scripts/merge-pr.sh (integrator only)."
+has 'gh[[:space:]]+api.*(branches/[^[:space:]]+/protection|/rulesets)' && block "branch protection is founder-only."
+has 'founder-approved' && has 'gh[[:space:]]+(pr|issue)' && has 'add-label' \
+  && block "the founder-approved label is founder-only."
+
+# Destructive repo/system operations.
+has 'gh[[:space:]]+repo[[:space:]]+(delete|archive|rename|edit)' && block "repository settings are founder-only."
+has 'rm[[:space:]]+-[a-zA-Z]*[rR][a-zA-Z]*[[:space:]]+(/|~|\$HOME|\.\.)([[:space:]]|/?$)' \
+  && block "recursive delete of a root, home or parent directory."
+has 'git[[:space:]]+(-C[[:space:]]+[^[:space:]]+[[:space:]]+)?(filter-branch|filter-repo)' && block "history rewriting is founder-only."
+
+# Secrets.
+has '(cat|less|head|tail|source|\.)[[:space:]]+[^|;&]*\.env($|[[:space:]]|\.(local|production|prod|staging))' \
+  && block "don't read .env files. Use .env.example for the variable list."
+
+exit 0