xtruct 0.1.0__py3-none-any.whl

xtruct/__init__.py

@@ -0,0 +1,3 @@
+"""Xtruct: a software company made of Claude Code agents."""
+
+__version__ = "0.1.0"

xtruct/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .launcher import main
+
+sys.exit(main())

xtruct/_cli/bin/xtruct-foundry.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Old name, kept so installs from before the rename (hooks, ~/.local/bin/xtruct-foundry) keep working.
+require('./xtruct.js')

xtruct/_cli/bin/xtruct.js

@@ -0,0 +1,541 @@
+#!/usr/bin/env node
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const os = require('node:os')
+const { parseArgs } = require('node:util')
+const { spawnSync } = require('node:child_process')
+
+const PKG = require('../package.json')
+const ui = require('../lib/ui')
+const { sym, paint, bold, dim, C } = ui
+const TEMPLATE = path.join(__dirname, '..', 'template')
+const USER_CONFIG = path.join(require('../lib/paths').CONFIG_DIR, 'config.json')
+
+// npm strips .gitignore from published packages, so the template ships it under another name.
+const RENAMES = { _gitignore: '.gitignore' }
+
+// Company files that `update` refreshes. Everything else in a product (docs, contracts, code,
+// Makefile, foundry.config.json) belongs to the product and is never touched.
+const MANAGED = [
+  'CLAUDE.md',
+  '.claude/agents',
+  '.claude/hooks',
+  '.claude/workflows',
+  '.claude/skills',
+  '.claude/settings.json',
+  'scripts/capacity.mjs',
+  'scripts/merge-pr.sh',
+  'scripts/bootstrap-github.sh',
+  'docs/templates',
+  '.github/pull_request_template.md',
+]
+const EXECUTABLE_DIRS = ['scripts', '.claude/hooks']
+const USER_KEYS = ['clickup.workspace_id', 'clickup.space_id', 'clickup.space_name', 'defaults.dir']
+
+function help() {
+  const rows = [
+    [ui.cmd('new') + ' ' + dim('<name>'), 'Create a product repo from the company template'],
+    [ui.cmd('init'), 'Add the company to the current repo (never overwrites)'],
+    [ui.cmd('update'), 'Refresh agents, hooks, workflows and scripts in this repo'],
+    [ui.cmd('dashboard'), 'Watch the company work, live in your browser'],
+    [ui.cmd('doctor'), 'Check prerequisites'],
+    [ui.cmd('capacity'), 'How many agents this machine can run at once'],
+    [ui.cmd('config') + ' ' + dim('[key [value]]'), 'Show or set your defaults'],
+    [ui.cmd('status'), 'Every project: open work, recent requests, uncommitted changes'],
+    [ui.cmd('track') + ' ' + dim('add|start|done|block|drop|list'), 'Your work items across all projects'],
+    [ui.cmd('setup'), 'Install the tracking hooks and the work-tracking skill into Claude Code'],
+  ]
+  const opts = [
+    [paint(C.violet, '--dir') + ' ' + dim('<parent>'), 'new: where to create the product'],
+    [paint(C.violet, '--no-git'), 'new: skip git init and the first commit'],
+    [paint(C.violet, '--dry-run'), 'update: show what would change'],
+    [paint(C.violet, '--json'), 'capacity: machine-readable output'],
+    [paint(C.violet, '--port') + ' ' + dim('<n>'), 'dashboard: port (default 4141)'],
+    [paint(C.violet, '--demo'), 'dashboard: show sample data'],
+    [paint(C.violet, '--clickup-space') + ' ' + dim('<id>'), 'new/init: ClickUp space (also --clickup-workspace, --clickup-space-name)'],
+  ]
+  const keys = USER_KEYS.map(k => [paint(C.violet, k), ''])
+  keys[0][1] = 'ClickUp workspace new products use'
+  keys[1][1] = 'ClickUp space new products use'
+  keys[2][1] = 'or a space name to look up instead'
+  keys[3][1] = 'parent folder for new (default: current directory)'
+  return [
+    ui.banner(PKG.version, 'A software company made of Claude Code agents').replace(/\n$/, ''),
+    ui.heading('Usage'),
+    '    xtruct ' + ui.cmd('<command>') + ' ' + dim('[options]'),
+    ui.heading('Commands'),
+    ui.table(rows, { indent: 4 }),
+    ui.heading('Options'),
+    ui.table(opts, { indent: 4 }),
+    ui.heading('Config'),
+    ui.table(keys, { indent: 4 }),
+    '    ' + dim('saved in ' + USER_CONFIG.replace(os.homedir(), '~')),
+    '',
+    '  ' + dim('Docs') + '  ' + paint(C.cyan, 'https://github.com/AdityaNarayan29/xtruct/tree/main/foundry'),
+    '',
+  ].join('\n')
+}
+
+// ---------- helpers ----------
+
+const ok = s => console.log(`  ${sym.ok} ${s}`)
+const warn = s => console.log(`  ${sym.warn} ${s}`)
+const step = (symbol, label, detail = '') => console.log(`  ${symbol} ${ui.padEnd(label, 22)}${dim(detail)}`)
+
+function die(msg) {
+  console.error(`\n  ${ui.badge(C.rose, 'error')} ${msg}\n`)
+  process.exit(1)
+}
+
+/** "32 files · 6 agents · 2 workflows · 1 skill · 2 guards" for a list of template paths. */
+function describeTemplate(files) {
+  const direct = dir => files.filter(f => new RegExp(`^${dir.replace('.', '\\.')}/[^/]+$`).test(f)).length
+  const skills = new Set(files.filter(f => f.startsWith('.claude/skills/')).map(f => f.split('/')[2])).size
+  const plural = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`
+  return [plural(files.length, 'file'), plural(direct('.claude/agents'), 'agent'), plural(direct('.claude/workflows'), 'workflow'), plural(skills, 'skill'), plural(direct('.claude/hooks'), 'guard')].join(' · ')
+}
+
+const home = p => p.replace(os.homedir(), '~')
+
+function readJSON(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (e) {
+    if (e.code === 'ENOENT' && fallback !== undefined) return fallback
+    die(`could not read ${file}: ${e.message}`)
+  }
+}
+
+function writeJSON(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+}
+
+function getKey(obj, key) {
+  return key.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj)
+}
+
+function setKey(obj, key, value) {
+  const parts = key.split('.')
+  let o = obj
+  for (const k of parts.slice(0, -1)) o = o[k] ??= {}
+  o[parts.at(-1)] = value
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts })
+  return { ok: r.status === 0, out: (r.stdout || '') + (r.stderr || ''), missing: r.error?.code === 'ENOENT' }
+}
+
+/** Every file in the template as [templateRelPath, productRelPath]. */
+function templateFiles(dir = TEMPLATE, rel = '') {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap(e => {
+    const from = path.join(rel, e.name)
+    if (e.isDirectory()) return templateFiles(path.join(dir, e.name), from)
+    const base = RENAMES[e.name] || e.name
+    return [[from, path.join(rel, base)]]
+  })
+}
+
+const isManaged = rel => MANAGED.some(m => rel === m || rel.startsWith(m + '/'))
+
+/** Copy template files into dest. Returns {written, created, skipped, unchanged}. */
+function copyTemplate(dest, { overwrite, filter = () => true, dryRun = false }) {
+  const result = { written: [], created: [], skipped: [], unchanged: [] }
+  for (const [from, to] of templateFiles()) {
+    if (!filter(to)) continue
+    const src = path.join(TEMPLATE, from)
+    const dst = path.join(dest, to)
+    const exists = fs.existsSync(dst)
+    if (exists && fs.readFileSync(dst).equals(fs.readFileSync(src))) {
+      result.unchanged.push(to)
+      continue
+    }
+    if (exists && !overwrite) {
+      result.skipped.push(to)
+      continue
+    }
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(dst), { recursive: true })
+      fs.copyFileSync(src, dst)
+      if (EXECUTABLE_DIRS.some(d => to.startsWith(d + '/')) && to.endsWith('.sh')) fs.chmodSync(dst, 0o755)
+    }
+    result.written.push(to)
+    if (!exists) result.created.push(to)
+  }
+  return result
+}
+
+function clickupDefaults(flags) {
+  const user = readJSON(USER_CONFIG, {})
+  return {
+    workspace_id: flags['clickup-workspace'] ?? getKey(user, 'clickup.workspace_id') ?? '',
+    space_id: flags['clickup-space'] ?? getKey(user, 'clickup.space_id') ?? '',
+    space_name: flags['clickup-space-name'] ?? getKey(user, 'clickup.space_name') ?? '',
+  }
+}
+
+function writeProductConfig(dest, name, flags) {
+  const file = path.join(dest, 'foundry.config.json')
+  const cfg = readJSON(file)
+  cfg.product = name
+  cfg.foundry_version = PKG.version
+  Object.assign(cfg.clickup, clickupDefaults(flags))
+  writeJSON(file, cfg)
+}
+
+function findProductRoot(start = process.cwd()) {
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'foundry.config.json'))) return dir
+    if (path.dirname(dir) === dir) return null
+  }
+}
+
+function nextSteps(dir) {
+  const n = i => paint(C.cyan, String(i))
+  const lines = [
+    `${n(1)}  ${dir === '.' ? dim('you are already in the product') : ui.cmd('cd ' + dir)}`,
+    `${n(2)}  ${ui.cmd('xtruct doctor')}`,
+    `${n(3)}  open Claude Code here and say:`,
+    `   ${paint(C.violet, '"run plan-product with idea: <what to build>"')}`,
+  ]
+  console.log('\n' + ui.box(lines, { title: 'Next', color: C.cyan }) + '\n')
+}
+
+// ---------- commands ----------
+
+function cmdNew(positionals, flags) {
+  const name = positionals[0]
+  if (!name) die('usage: xtruct new <name>')
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) die(`use lowercase letters, digits and dashes: ${name}`)
+  const parent = path.resolve(flags.dir || getKey(readJSON(USER_CONFIG, {}), 'defaults.dir')?.replace(/^~/, os.homedir()) || '.')
+  const dest = path.join(parent, name)
+  if (fs.existsSync(dest)) die(`already exists: ${dest}`)
+
+  console.log(ui.banner(PKG.version, 'A software company made of Claude Code agents'))
+  console.log(`  ${sym.info} Creating ${bold(name)} ${dim('in ' + home(parent))}\n`)
+  const r = copyTemplate(dest, { overwrite: false })
+  step(sym.ok, 'Company template', describeTemplate(r.written))
+  writeProductConfig(dest, name, flags)
+  const space = clickupDefaults(flags)
+  step(sym.ok, 'foundry.config.json', space.space_id ? `ClickUp space ${space.space_id}` : 'defaults')
+
+  if (!flags['no-git']) {
+    const steps = [['init', '-q', '-b', 'main'], ['add', '-A'], ['commit', '-qm', 'chore: company scaffold from xtruct']]
+    const failed = steps.map(s => run('git', s, { cwd: dest })).find(r => !r.ok)
+    if (failed) step(sym.warn, 'Git repository', 'not committed: ' + failed.out.trim().split('\n')[0])
+    else step(sym.ok, 'Git repository', 'main · ' + run('git', ['rev-parse', '--short', 'HEAD'], { cwd: dest }).out.trim())
+  }
+  if (!space.space_id && !space.space_name) {
+    step(sym.warn, 'ClickUp space', 'not set; the planner will look it up (xtruct config clickup.space_id <id>)')
+  }
+  const rel = path.relative(process.cwd(), dest)
+  nextSteps([rel, home(dest)].sort((a, b) => a.length - b.length)[0] || '.')
+}
+
+function cmdInit(flags) {
+  const dest = process.cwd()
+  const fresh = !fs.existsSync(path.join(dest, 'foundry.config.json'))
+  console.log(ui.banner(PKG.version, 'Adding the company to ' + path.basename(dest)))
+  const r = copyTemplate(dest, { overwrite: false })
+  if (fresh) writeProductConfig(dest, path.basename(dest).toLowerCase().replace(/[^a-z0-9-]/g, '-'), flags)
+  step(sym.ok, 'Company template', r.written.length ? describeTemplate(r.written) : 'already present')
+  if (r.skipped.length) {
+    step(sym.warn, 'Kept your files', `${r.skipped.length} existing; merge the company versions by hand:`)
+    r.skipped.forEach(f => console.log(`      ${dim('·')} ${f}`))
+    if (r.skipped.includes('Makefile')) warn('your Makefile must provide: setup dev lint typecheck test e2e build ci')
+    if (r.skipped.includes('CLAUDE.md')) warn('add the company handbook to your CLAUDE.md (see the xtruct template)')
+  }
+  nextSteps('.')
+}
+
+function cmdUpdate(flags) {
+  const root = findProductRoot()
+  if (!root) die('not inside an xtruct product (no foundry.config.json found)')
+  const cfgFile = path.join(root, 'foundry.config.json')
+  const cfg = readJSON(cfgFile)
+  const dryRun = Boolean(flags['dry-run'])
+  const r = copyTemplate(root, { overwrite: true, filter: isManaged, dryRun })
+  const from = cfg.foundry_version || 'unknown'
+
+  console.log(ui.banner(PKG.version, `${dryRun ? 'Checking' : 'Updating'} ${cfg.product || path.basename(root)}`))
+  if (!r.written.length) {
+    ok(`company files already match ${bold(PKG.version)}`)
+  } else {
+    console.log(`  ${sym.info} ${dryRun ? 'Would update' : 'Updated'} ${bold(r.written.length)} file${r.written.length === 1 ? '' : 's'}  ${dim(from + ' → ' + PKG.version)}\n`)
+    for (const f of r.written) {
+      const created = r.created.includes(f)
+      console.log(`    ${created ? paint(C.green, '+') : paint(C.amber, '~')} ${f}${created ? dim('  new') : ''}`)
+    }
+  }
+  if (!dryRun && cfg.foundry_version !== PKG.version) {
+    cfg.foundry_version = PKG.version
+    writeJSON(cfgFile, cfg)
+  }
+  if (!dryRun && r.written.length) {
+    console.log(`\n  ${dim('Review with')} ${ui.cmd('git diff')}${dim(', then commit. In a protected repo, open a PR with the founder-approved label.')}`)
+  }
+  console.log()
+}
+
+function cmdDoctor() {
+  const rows = []
+  let failures = 0, warnings = 0
+  const add = (state, label, detail = '') => {
+    if (state === 'fail') failures++
+    if (state === 'warn') warnings++
+    rows.push([{ ok: sym.ok, fail: sym.fail, warn: sym.warn }[state], state === 'ok' ? label : bold(label), dim(detail)])
+  }
+  const version = (bin, args = ['--version']) => run(bin, args).out.split('\n')[0].replace(/^[^0-9]*/, '').split(' ')[0]
+
+  const [major] = process.versions.node.split('.').map(Number)
+  add(major >= 18 ? 'ok' : 'fail', 'node', major >= 18 ? process.versions.node : 'install Node 18 or newer')
+  for (const [bin, hint] of [
+    ['git', 'install git'],
+    ['gh', 'install the GitHub CLI: https://cli.github.com'],
+    ['jq', 'brew install jq · apt install jq'],
+    ['make', 'xcode-select --install on macOS'],
+  ]) {
+    const missing = run(bin, ['--version']).missing
+    add(missing ? 'fail' : 'ok', bin, missing ? hint : version(bin))
+  }
+  const auth = run('gh', ['auth', 'status'])
+  if (!auth.missing) add(auth.ok ? 'ok' : 'fail', 'gh login', auth.ok ? (auth.out.match(/account (\S+)/) || [])[1] || 'logged in' : 'run: gh auth login')
+  if (run('claude', ['--version']).missing) add('warn', 'claude CLI', 'not on PATH; fine in VS Code, JetBrains or the desktop app')
+  else add('ok', 'claude', version('claude'))
+  const xtruct = [
+    path.join(os.homedir(), '.claude', 'skills', 'xtruct'),
+    path.join(os.homedir(), '.agents', 'skills', 'xtruct'),
+    path.join(process.cwd(), '.claude', 'skills', 'xtruct'),
+  ].find(dir => fs.existsSync(path.join(dir, 'SKILL.md')))
+  add(xtruct ? 'ok' : 'warn', 'xtruct skill', xtruct ? home(xtruct) : 'optional diagrams: npx skills add AdityaNarayan29/xtruct -g')
+
+  console.log(ui.banner(PKG.version, 'Checking this machine'))
+  console.log(ui.table(rows, { gap: 2 }))
+
+  const root = findProductRoot()
+  if (root) {
+    const cfg = readJSON(path.join(root, 'foundry.config.json'))
+    const prows = [[sym.ok, cfg.product || path.basename(root), dim(home(root))]]
+    if (cfg.foundry_version && cfg.foundry_version !== PKG.version) prows.push([sym.warn, bold('version'), dim(`product on ${cfg.foundry_version}, you have ${PKG.version}: xtruct update`)])
+    prows.push(cfg.clickup?.space_id || cfg.clickup?.space_name
+      ? [sym.ok, 'ClickUp', dim(cfg.clickup.space_id || cfg.clickup.space_name)]
+      : [sym.warn, bold('ClickUp'), dim('no space set; the planner will try to find one')])
+    prows.push(cfg.github?.repo
+      ? [sym.ok, 'GitHub', dim(cfg.github.repo)]
+      : [sym.warn, bold('GitHub'), dim('no repo yet; run scripts/bootstrap-github.sh after approving the spec')])
+    warnings += prows.filter(r => r[0] === sym.warn).length
+    console.log(ui.heading('Product'))
+    console.log(ui.table(prows, { gap: 2 }))
+  }
+
+  console.log()
+  if (failures) console.log(`  ${ui.badge(C.rose, `${failures} to fix`)} ${dim('before agents can run')}`)
+  else console.log(`  ${ui.badge(C.green, 'ready')} ${dim(warnings ? `${warnings} optional item${warnings > 1 ? 's' : ''} above` : 'everything checks out')}`)
+  console.log(`  ${dim('Also needed: the ClickUp connector in Claude (claude.ai → Settings → Connectors)')}\n`)
+  process.exit(failures ? 1 : 0)
+}
+
+function readCapacity() {
+  const root = findProductRoot()
+  const script = root && fs.existsSync(path.join(root, 'scripts', 'capacity.mjs'))
+    ? path.join(root, 'scripts', 'capacity.mjs')
+    : path.join(TEMPLATE, 'scripts', 'capacity.mjs')
+  const r = run(process.execPath, [script], { cwd: root || process.cwd() })
+  if (!r.ok) die(`capacity check failed: ${r.out.trim()}`)
+  return { raw: r.out, cap: JSON.parse(r.out) }
+}
+
+function cmdCapacity(flags) {
+  const { raw, cap: c } = readCapacity()
+  if (flags.json) return process.stdout.write(raw)
+  const colors = [C.cyan, C.green, C.violet, C.amber, C.orange]
+  console.log(ui.banner(PKG.version, 'How many agents this machine can run at once'))
+  console.log(ui.table([
+    [dim('machine'), `${c.cpus} cores · ${c.ram_gb} GB · load ${c.load_1m}`],
+    [dim('budget'), `${paint(C.cyan, bold(c.total_agents))} agents at once  ${dim('limited by ' + c.limited_by.replace('_', ' '))}`],
+    [dim('ceiling'), `${c.per_workflow_ceiling} per workflow ${dim('(Claude Code runtime)')}`],
+  ]))
+  console.log()
+  for (let i = 0; i < c.epics_at_once; i++) {
+    console.log(`  ${paint(colors[i % colors.length], '■'.repeat(c.agents_per_epic))} ${dim(`epic ${i + 1} · ${c.agents_per_epic}`)}`)
+  }
+  const spare = c.total_agents - c.epics_at_once * c.agents_per_epic
+  if (spare > 0) console.log(`  ${dim('□'.repeat(spare))} ${dim(`${spare} spare`)}`)
+  console.log(`\n  ${dim('Tune in foundry.config.json → limits: agents_per_core, ram_per_agent_gb, reserve_ram_gb, max_agents')}\n`)
+}
+
+function cmdConfig(positionals) {
+  const [key, value] = positionals
+  const cfg = readJSON(USER_CONFIG, {})
+  if (!key) {
+    console.log()
+    console.log(ui.table(USER_KEYS.map(k => [paint(C.violet, k), getKey(cfg, k) ?? dim('not set')])))
+    console.log(`\n  ${dim(home(USER_CONFIG))}\n`)
+    return
+  }
+  if (!USER_KEYS.includes(key)) die(`unknown key ${key}. Known: ${USER_KEYS.join(', ')}`)
+  if (value === undefined) {
+    console.log(getKey(cfg, key) ?? '')
+    return
+  }
+  setKey(cfg, key, value)
+  writeJSON(USER_CONFIG, cfg)
+  ok(`${paint(C.violet, key)} = ${value}`)
+}
+
+// ---------- tracking ----------
+
+const tracker = () => require('../lib/tracker')
+const STATE_COLOR = { open: C.cyan, doing: C.green, blocked: C.rose, done: C.dim, dropped: C.dim }
+
+function itemRow(t, i) {
+  const state = paint(STATE_COLOR[i.state] || C.slate, i.state.padEnd(7))
+  const note = i.notes.at(-1)
+  return [paint(C.violet, '#' + i.id), state, i.title, dim(t.ago(i.updated) + (i.link ? ' · ' + i.link : '') + (note ? ' · ' + note.text : ''))]
+}
+
+function cmdTrack(positionals, flags) {
+  const t = tracker()
+  const [action = 'list', ...rest] = positionals
+  const project = flags.project ? path.resolve(flags.project) : t.projectOf()
+  const verbs = { start: 'doing', done: 'done', block: 'blocked', drop: 'dropped', reopen: 'open' }
+
+  if (action === 'add') {
+    const title = rest.join(' ').trim()
+    if (!title) die('usage: xtruct track add "<what you are working on>" [--link <url>] [--note <text>]')
+    const item = t.add({ title, project, link: flags.link, note: flags.note })
+    if (flags.json) return console.log(JSON.stringify(item))
+    return ok(`${paint(C.violet, '#' + item.id)} ${item.title} ${dim('· ' + t.short(project))}`)
+  }
+  if (verbs[action] || action === 'note') {
+    const id = rest[0]
+    if (!id) die(`usage: xtruct track ${action} <id> [--note <text>]`)
+    const note = flags.note || (action === 'note' ? rest.slice(1).join(' ') : undefined)
+    const item = t.update(id, { state: verbs[action], note, link: flags.link })
+    if (!item) die(`no work item #${id}`)
+    if (flags.json) return console.log(JSON.stringify(item))
+    return ok(`${paint(C.violet, '#' + item.id)} ${paint(STATE_COLOR[item.state], item.state)} ${item.title}`)
+  }
+  if (action === 'list') {
+    const items = t.list({ project: flags.all ? undefined : project, all: Boolean(flags.done) })
+    if (flags.json) return console.log(JSON.stringify(items))
+    if (!items.length) return console.log(`\n  ${dim(flags.all ? 'No open work items anywhere.' : 'No open work items in ' + t.short(project) + '. Use --all for every project.')}\n`)
+    let last = null
+    console.log()
+    for (const i of items) {
+      if (i.project !== last) { console.log(`  ${bold(t.short(i.project))}`); last = i.project }
+      console.log(ui.table([itemRow(t, i)], { indent: 4, gap: 2 }))
+    }
+    return console.log()
+  }
+  die(`unknown track action "${action}". Use add, start, done, block, drop, reopen, note or list`)
+}
+
+function cmdStatus(flags) {
+  const t = tracker()
+  const projects = t.portfolio({ days: Number(flags.days) || 14 })
+  if (flags.json) return console.log(JSON.stringify(projects))
+  console.log(ui.banner(PKG.version, 'Everything you have in flight'))
+  if (!projects.length) return console.log(`  ${dim('Nothing tracked yet. Prompts and work items will show up here.')}\n`)
+  for (const p of projects) {
+    const git = t.gitSummary(p.project)
+    const product = fs.existsSync(path.join(p.project, 'foundry.config.json'))
+    const head = [
+      bold(t.short(p.project)),
+      product ? paint(C.cyan, '◆ product') : '',
+      git ? dim(`${git.branch}${git.changed ? ` · ${git.changed} uncommitted` : ''}`) : '',
+      dim(`· ${p.prompts} request${p.prompts === 1 ? '' : 's'}${p.last ? ' · last ' + t.ago(p.last) : ''}`),
+    ].filter(Boolean).join('  ')
+    console.log(`  ${p.items.length ? sym.info : dim('·')} ${head}`)
+    if (p.items.length) console.log(ui.table(p.items.map(i => itemRow(t, i)), { indent: 6, gap: 2 }))
+  }
+  console.log(`\n  ${dim('Details:')} ${ui.cmd('xtruct track list --all')}\n`)
+}
+
+/** Hooks must never block or break a session: read stdin, do the work, swallow every error. */
+function cmdHook(positionals) {
+  const event = positionals[0]
+  let input = {}
+  try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}') } catch {}
+  try {
+    const t = tracker()
+    const project = t.projectOf(input.cwd || process.cwd())
+    if (event === 'prompt') {
+      const prompt = String(input.prompt || '').trim()
+      if (prompt) t.appendJournal({ at: new Date().toISOString(), project, session: input.session_id || null, prompt: prompt.slice(0, 600) })
+    } else if (event === 'session') {
+      const r = t.resume(project)
+      const open = r.items.length
+      process.stdout.write(JSON.stringify({
+        systemMessage: open
+          ? `◆ xtruct: ${open} open item${open > 1 ? 's' : ''} in ${path.basename(project)}${r.git?.changed ? ` · ${r.git.changed} uncommitted` : ''}`
+          : undefined,
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: r.text },
+      }))
+    }
+  } catch { /* never fail the user's session */ }
+  process.exit(0)
+}
+
+function cmdSetup(flags) {
+  require('../lib/setup').run({ dryRun: Boolean(flags['dry-run']), uninstall: Boolean(flags.uninstall), version: PKG.version })
+}
+
+// ---------- main ----------
+
+function main() {
+  let parsed
+  try {
+    parsed = parseArgs({
+      allowPositionals: true,
+      options: {
+        dir: { type: 'string' },
+        'no-git': { type: 'boolean' },
+        'dry-run': { type: 'boolean' },
+        json: { type: 'boolean' },
+        port: { type: 'string' },
+        'no-open': { type: 'boolean' },
+        demo: { type: 'boolean' },
+        project: { type: 'string' },
+        link: { type: 'string' },
+        note: { type: 'string' },
+        all: { type: 'boolean' },
+        done: { type: 'boolean' },
+        days: { type: 'string' },
+        uninstall: { type: 'boolean' },
+        'clickup-workspace': { type: 'string' },
+        'clickup-space': { type: 'string' },
+        'clickup-space-name': { type: 'string' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+      },
+    })
+  } catch (e) {
+    die(e.message)
+  }
+  const { values: flags, positionals } = parsed
+  const [cmd, ...rest] = positionals
+
+  if (flags.version) return console.log(PKG.version)
+  if (flags.help || !cmd || cmd === 'help') return console.log(help())
+
+  switch (cmd) {
+    case 'new': return cmdNew(rest, flags)
+    case 'init': return cmdInit(flags)
+    case 'update': return cmdUpdate(flags)
+    case 'doctor': return cmdDoctor()
+    case 'capacity': return cmdCapacity(flags)
+    case 'track': return cmdTrack(rest, flags)
+    case 'status': return cmdStatus(flags)
+    case 'hook': return cmdHook(rest)
+    case 'setup': return cmdSetup(flags)
+    case 'dashboard': return require('../lib/dashboard').start({ root: findProductRoot(), port: Number(flags.port) || 4141, open: !flags['no-open'], demo: Boolean(flags.demo), capacity: () => readCapacity().cap, version: PKG.version })
+    case 'config': return cmdConfig(rest)
+    default: die(`unknown command "${cmd}". Run xtruct --help`)
+  }
+}
+
+main()

xtruct/_cli/global/claude-md-block.md

@@ -0,0 +1,5 @@
+## Work tracking (xtruct)
+
+- Every task that changes files or takes several steps gets a work item: `xtruct track add "<title>"` at the start, `xtruct track done <id> --note "<what changed>"` at the end, `xtruct track block <id> --note "<what's needed>"` when waiting on me. Questions don't need one. Follow the `foundry` skill.
+- Each session starts with a "Where the founder left off" note. Use it to continue open work instead of starting over, and mention open items when they relate to what I ask.
+- New products or multi-part features go through Xtruct as the `foundry` skill describes. Never launch an agent team without my explicit OK in the conversation.

xtruct/_cli/global/skills/foundry/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: foundry
+description: Track and route the founder's work across every project. Use at the start of any task that changes files or takes several steps (open a work item), when finishing or pausing it (close or block it), when the founder asks what's in flight, where they left off or for status, and when they ask for a new product or a multi-part feature (route it into Xtruct).
+---
+
+# Xtruct: keep track, route big work
+
+The founder works across many projects and must never lose track. Every session starts with a "Where the founder left off" note (from a hook) listing open work items, recent requests and uncommitted changes for this project. Use it to pick up where things stopped instead of starting over.
+
+## Keep the ledger (every non-trivial task)
+
+| When | Run |
+|---|---|
+| A task that changes files or takes several steps begins | `xtruct track add "<short title>"`, unless an open item already covers it (check the session note or `xtruct track list`) |
+| You start working on it | `xtruct track start <id>` |
+| It's finished | `xtruct track done <id> --note "<what changed and where>"` |
+| You're waiting on the founder, access or a decision | `xtruct track block <id> --note "<what's needed>"` |
+| The founder drops it | `xtruct track drop <id>` |
+| You stop mid-task | Leave it open with `xtruct track note <id> "<next step>"` |
+
+- Pure questions and explanations don't get items.
+- Titles say the outcome ("Add refund webhook to payments API"), not the activity.
+- Add `--link <url>` for a PR, ClickUp task or artifact.
+- When the founder asks "what's pending?", "where was I?" or "status": run `xtruct status` (all projects) or `xtruct track list` (this one), and summarize.
+
+## Route the work
+
+| Request | What to do |
+|---|---|
+| A question, an explanation, or a small change (a few files, under about an hour of human work) | Do it yourself, tracked as above. |
+| A multi-part feature in a **Xtruct product** (`foundry.config.json` exists) | Propose it as an epic: goal, rough task list, what runs in parallel. **Ask the founder to confirm**, then create the epic in ClickUp and use the `run-epics` skill. |
+| A multi-part feature in **any other repo** | Do it yourself in tracked steps. If it's large, offer `xtruct init` to bring in the agent company. That changes the repo, so ask first. |
+| A brand-new product | Confirm the name and idea, then `xtruct new <name>`, then the `plan-product` workflow in the new folder. |
+
+**Never start a multi-agent workflow without the founder's explicit OK in this conversation.** Agent teams cost real money. Say how many agents and roughly what they'll do before asking.
+
+## Commands
+
+```
+xtruct status                     everything in flight, all projects
+xtruct track list [--all] [--done]
+xtruct track add "<title>" [--link <url>] [--note <text>]
+xtruct track start|done|block|drop|reopen <id> [--note <text>]
+xtruct dashboard                  live view inside an Xtruct product
+xtruct capacity                   agents this machine can run
+```