xtruct 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# PreToolUse guard for Edit/Write: keeps agents out of founder-only paths and secret files.
+# 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
+
+path=$(jq -r '.tool_input.file_path // .tool_input.notebook_path // empty')
+[ -z "$path" ] && exit 0
+
+block() { echo "Blocked by company guardrail: $1 ($path)" >&2; exit 2; }
+
+case "$path" in
+  *.env.example) ;;
+  *.env|*.env.*|*/.env|*/.env.*) block "secret files are off limits; document variables in .env.example" ;;
+  *.pem|*.key|*/id_rsa*|*/id_ed25519*) block "private keys are off limits" ;;
+esac
+
+grep -Eq '/\.claude/(settings[^/]*\.json|hooks/|agents/|workflows/|skills/)' <<<"$path" \
+  && block "the company's agent setup is founder-only"
+grep -Eq '(^|/)(CLAUDE\.md|scripts/merge-pr\.sh|scripts/bootstrap-github\.sh|scripts/capacity\.mjs)$' <<<"$path" \
+  && block "this file is founder-only"
+
+exit 0

xtruct/_cli/template/.claude/settings.json

@@ -0,0 +1,39 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(gh:*)",
+      "Bash(make:*)",
+      "Bash(scripts/merge-pr.sh:*)",
+      "Bash(jq:*)",
+      "Bash(pnpm:*)",
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(node:*)",
+      "Bash(uv:*)",
+      "Bash(python3:*)",
+      "Bash(pytest:*)",
+      "Bash(docker compose:*)",
+      "mcp__claude_ai_ClickUp"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.local)",
+      "Read(./.env.production)",
+      "Bash(gh repo delete:*)",
+      "Bash(gh pr merge:*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-bash.sh" }]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-files.sh" }]
+      }
+    ]
+  }
+}

xtruct/_cli/template/.claude/skills/run-epics/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: run-epics
+description: Run one or more epics with the agent team, sized to this machine's capacity. Use when the founder says to run, build or start an epic or epics, names epic ids (E2, E3…), or says "build everything that's ready".
+---
+
+# Run epics at machine capacity
+
+Each epic runs as its own `run-epic` workflow. Claude Code caps a single workflow at min(16, cores − 2) agents, so to use the whole machine, run several epics side by side, each capped at its share.
+
+## 1. Measure the machine
+
+Run `node scripts/capacity.mjs`. Use `total_agents` (the machine's budget) and `per_workflow_ceiling`.
+
+## 2. Pick the epics
+
+Read `foundry.config.json` for `clickup.epics_list_id`, then list the epics in ClickUp with their status and the dependencies in their descriptions.
+
+- An epic is **ready** when every epic it depends on is `in review` or `done`.
+- If the founder named epics, use those. If one isn't ready, say which dependency is missing and leave it out.
+- If the founder said "everything that's ready", take all ready epics in key order.
+- **Foundation (E1) always runs alone.** If it isn't done yet, run only E1.
+
+## 3. Split the budget and launch
+
+- `n` = number of epics to start now = min(ready epics, max(1, floor(total_agents / 8))). With one ready epic, n = 1.
+- Each epic's `maxAgents` = min(per_workflow_ceiling, floor(total_agents / n)).
+- Start all `n` workflows **in the same message**, one Workflow call each: `name: "run-epic"`, `args: {"epic": "<ClickUp id>", "maxAgents": <share>}`.
+- Tell the founder in two or three lines: which epics started, agents per epic, total versus the machine's budget, and which ready epics are queued.
+
+## 4. Refill as epics finish
+
+When a run-epic workflow completes:
+
+1. Report its result to the founder in a few lines: merged / rejected / failed / blocked counts, whether QA passed, and the ClickUp epic link.
+2. Rerun `node scripts/capacity.mjs`, since load may have changed.
+3. Recheck readiness: an epic that just reached `in review` may unblock others.
+4. Start queued or newly ready epics, keeping the sum of `maxAgents` across running workflows at or below `total_agents`.
+
+Stop when nothing is ready or queued. Never start an epic whose dependency finished with failed or rejected tasks; report it as blocked and let the founder decide.
+
+## Rules
+
+- Never exceed `total_agents` in total, even if the founder names more epics than fit. Queue the rest.
+- If `capacity.mjs` shows `limited_by: "ram"` and the machine feels slow, lower the shares rather than raising them.
+- The founder can tune capacity in `foundry.config.json` → `limits` (`agents_per_core`, `ram_per_agent_gb`, `reserve_ram_gb`, `max_agents`).

xtruct/_cli/template/.claude/workflows/plan-product.js

@@ -0,0 +1,136 @@
+export const meta = {
+  name: 'plan-product',
+  description: 'Architect turns the founder idea into PRD, architecture, contracts and epics; two critics challenge it; epics land in ClickUp',
+  whenToUse: 'Start of a new product. args: {idea: "<what to build, for whom, any constraints>"}',
+  phases: [
+    { title: 'Spec', detail: 'architect drafts PRD, architecture, stack, contracts, epics' },
+    { title: 'Critique', detail: 'product and engineering critics challenge the draft' },
+    { title: 'Revise', detail: 'architect applies or rejects each critique point' },
+    { title: 'Board', detail: 'ClickUp folder + Epics list with one task per epic' },
+  ],
+}
+
+const IDEA = typeof args === 'string' ? args : args && args.idea
+if (!IDEA) throw new Error('plan-product needs args: {idea: "<what to build>"}')
+
+const EPICS_SCHEMA = {
+  type: 'object',
+  properties: {
+    product_name: { type: 'string' },
+    stack_summary: { type: 'string', description: 'one line, e.g. "Next.js + tRPC + Postgres (Drizzle), Playwright"' },
+    epics: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', description: 'E1, E2, ...; E1 is Foundation' },
+          name: { type: 'string' },
+          goal: { type: 'string' },
+          acceptance: { type: 'array', items: { type: 'string' } },
+          depends_on: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['key', 'name', 'goal', 'acceptance', 'depends_on'],
+      },
+    },
+    open_questions: { type: 'array', items: { type: 'string' }, description: 'decisions only the founder can make' },
+  },
+  required: ['product_name', 'stack_summary', 'epics', 'open_questions'],
+}
+
+const CRITIQUE_SCHEMA = {
+  type: 'object',
+  properties: {
+    issues: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          severity: { type: 'string', enum: ['must-fix', 'should-fix', 'consider'] },
+          where: { type: 'string' },
+          issue: { type: 'string' },
+          suggestion: { type: 'string' },
+        },
+        required: ['severity', 'where', 'issue', 'suggestion'],
+      },
+    },
+  },
+  required: ['issues'],
+}
+
+const BOARD_SCHEMA = {
+  type: 'object',
+  properties: {
+    folder_id: { type: 'string' },
+    epics_list_id: { type: 'string' },
+    note: { type: 'string', description: 'anything the founder must act on, e.g. which ClickUp space to use' },
+    epics: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { key: { type: 'string' }, name: { type: 'string' }, clickup_id: { type: 'string' }, url: { type: 'string' } },
+        required: ['key', 'name', 'clickup_id'],
+      },
+    },
+  },
+  required: ['folder_id', 'epics_list_id', 'epics'],
+}
+
+phase('Spec')
+const draft = await agent(
+  `Mode: SPEC. The founder's idea:\n\n${IDEA}\n\nWrite docs/PRD.md, docs/ARCHITECTURE.md, docs/CONVENTIONS.md and contracts/, commit them, and return the epic plan. Where the idea is ambiguous, choose the simplest reasonable option, note it in the PRD, and list it in open_questions.`,
+  { agentType: 'architect', phase: 'Spec', label: 'architect:spec', schema: EPICS_SCHEMA },
+)
+if (!draft) throw new Error('architect did not return a spec')
+
+phase('Critique')
+const LENSES = [
+  {
+    key: 'product',
+    prompt: 'You are a skeptical product manager. Does the PRD actually solve the founder\'s idea? Is the MVP the smallest thing worth shipping? Missing user flows, missing unhappy paths, acceptance criteria that are not testable, scope creep.',
+  },
+  {
+    key: 'engineering',
+    prompt: 'You are a principal engineer. Is the stack a good fit and boring enough? Are contracts complete enough that juniors building opposite sides never need to talk? Security gaps (auth, tenancy, input validation)? Can the feature epics really run in parallel after Foundation, or are there hidden dependencies?',
+  },
+]
+const critiques = await parallel(LENSES.map(l => () => agent(
+  `${l.prompt}\n\nThe founder's idea:\n${IDEA}\n\nReview docs/PRD.md, docs/ARCHITECTURE.md, docs/CONVENTIONS.md and contracts/ as committed, and this epic plan:\n${JSON.stringify(draft.epics, null, 2)}\n\nDo not edit files. Return concrete issues only; no praise.`,
+  { phase: 'Critique', label: `critic:${l.key}`, schema: CRITIQUE_SCHEMA },
+)))
+const issues = critiques.filter(Boolean).flatMap((c, i) => c.issues.map(x => ({ lens: LENSES[i].key, ...x })))
+log(`${issues.length} critique points (${issues.filter(x => x.severity === 'must-fix').length} must-fix)`)
+
+phase('Revise')
+const final = issues.length
+  ? await agent(
+    `Mode: REVISE. Apply this critique to the docs, contracts and epic plan. Fix every must-fix point unless it is wrong, in which case record why under Decisions. Commit, then return the revised epic plan.\n\n${JSON.stringify(issues, null, 2)}`,
+    { agentType: 'architect', phase: 'Revise', label: 'architect:revise', schema: EPICS_SCHEMA },
+  )
+  : draft
+if (!final) throw new Error('architect did not return a revised plan')
+
+phase('Board')
+const board = await agent(
+  `Set up the ClickUp board for product "${final.product_name}". Read the clickup section of foundry.config.json.
+0. If space_id is empty, look up the workspace hierarchy with the ClickUp tools and pick the space named space_name, or the only space if there is exactly one. If that's still ambiguous, create nothing; return empty ids, no epics, and a note listing the available spaces so the founder can set clickup.space_id.
+1. Create a folder named "${final.product_name}" in that space, and inside it a list named "Epics".
+2. Create one task per epic below, in order, status "to do". Description: goal, acceptance criteria as a checklist, dependencies (by epic name), and a link to docs/PRD.md. Prefix names with the key, e.g. "E1 · Foundation".
+3. Write workspace_id, space_id, folder_id and epics_list_id into foundry.config.json and commit ("chore: link ClickUp board"). Use jq or a small script; do not hand-edit other keys.
+Return the ids.
+
+Epics:\n${JSON.stringify(final.epics, null, 2)}`,
+  { phase: 'Board', label: 'lead:board', schema: BOARD_SCHEMA },
+)
+
+return {
+  product: final.product_name,
+  stack: final.stack_summary,
+  epics: final.epics.map(e => {
+    const b = board && board.epics.find(x => x.key === e.key)
+    return { key: e.key, name: e.name, depends_on: e.depends_on, clickup_id: b ? b.clickup_id : null, url: b ? b.url : null }
+  }),
+  open_questions: final.open_questions,
+  critique_points: issues.length,
+  board_ready: Boolean(board && board.epics_list_id),
+  board_note: board ? board.note || '' : 'board agent did not complete',
+}

xtruct/_cli/template/.claude/workflows/run-epic.js

@@ -0,0 +1,248 @@
+export const meta = {
+  name: 'run-epic',
+  description: 'Senior lead splits a ClickUp epic into tasks; juniors build them in parallel worktrees; reviewer + lead gate each PR; integrator merges through the gate; QA verifies main',
+  whenToUse: 'After the spec is approved and scripts/bootstrap-github.sh has run. Usually started by the run-epics skill. args: {epic: "<ClickUp epic task id>", maxAgents?: <share from scripts/capacity.mjs>, fixRounds?: 2}',
+  phases: [
+    { title: 'Plan', detail: 'senior lead splits the epic into tasks in ClickUp' },
+    { title: 'Build', detail: 'one junior per task in its own worktree, opens a PR' },
+    { title: 'Review', detail: 'reviewer and lead check each PR in parallel; fix rounds on rejection' },
+    { title: 'Merge', detail: 'integrator merges through scripts/merge-pr.sh' },
+    { title: 'Verify', detail: 'QA runs the full suite and acceptance walk-through on main' },
+  ],
+}
+
+const EPIC = typeof args === 'string' ? args : args && args.epic
+if (!EPIC) throw new Error('run-epic needs args: {epic: "<ClickUp epic task id>"}')
+const FIX_ROUNDS = args && Number.isInteger(args.fixRounds) ? args.fixRounds : 2
+// This epic's share of the machine (from scripts/capacity.mjs). Several epics run side by side,
+// each capped at its share, so together they never exceed what the machine can take.
+const MAX_AGENTS = args && Number.isInteger(args.maxAgents) && args.maxAgents > 0 ? args.maxAgents : 16
+
+// Counting semaphore around agent(). A finishing agent hands its slot straight to the next waiter,
+// so a new caller can never slip in between and push the count over MAX_AGENTS.
+let active = 0
+const waiting = []
+async function run(prompt, opts) {
+  if (active >= MAX_AGENTS) await new Promise(resolve => waiting.push(resolve))
+  else active++
+  try {
+    return await agent(prompt, opts)
+  } finally {
+    const next = waiting.shift()
+    if (next) next()
+    else active--
+  }
+}
+
+const TASKS_SCHEMA = {
+  type: 'object',
+  properties: {
+    epic_title: { type: 'string' },
+    tasks: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', description: 'T1, T2, ...' },
+          clickup_id: { type: 'string' },
+          title: { type: 'string' },
+          spec: { type: 'string', description: 'what to build plus acceptance criteria as testable statements' },
+          scope: { type: 'array', items: { type: 'string' }, description: 'globs this task may change' },
+          depends_on: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['key', 'clickup_id', 'title', 'spec', 'scope', 'depends_on'],
+      },
+    },
+  },
+  required: ['epic_title', 'tasks'],
+}
+const PR_SCHEMA = {
+  type: 'object',
+  properties: {
+    pr_number: { type: 'integer', description: '0 if no PR could be opened' },
+    branch: { type: 'string' },
+    checks_passed: { type: 'boolean', description: 'make lint typecheck test passed locally' },
+    notes: { type: 'string' },
+  },
+  required: ['pr_number', 'branch', 'checks_passed', 'notes'],
+}
+const VERDICT_SCHEMA = {
+  type: 'object',
+  properties: {
+    approved: { type: 'boolean' },
+    blocking_issues: { type: 'array', items: { type: 'string' } },
+    notes: { type: 'string' },
+  },
+  required: ['approved', 'blocking_issues'],
+}
+const MERGE_SCHEMA = {
+  type: 'object',
+  properties: {
+    merged: { type: 'boolean' },
+    merge_sha: { type: 'string' },
+    needs_rebase: { type: 'boolean' },
+    reason: { type: 'string' },
+  },
+  required: ['merged'],
+}
+const QA_SCHEMA = {
+  type: 'object',
+  properties: {
+    passed: { type: 'boolean' },
+    summary: { type: 'string' },
+    bugs: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          severity: { type: 'string', enum: ['blocker', 'major', 'minor'] },
+          clickup_id: { type: 'string' },
+        },
+        required: ['title', 'severity'],
+      },
+    },
+  },
+  required: ['passed', 'summary', 'bugs'],
+}
+
+// ---- Plan ----
+phase('Plan')
+const plan = await run(
+  `Mode: PLAN. Epic: ${EPIC}. Split it into tasks, create each as a ClickUp subtask of the epic, set the epic to in progress, and return the tasks.`,
+  { agentType: 'senior-lead', phase: 'Plan', label: 'lead:plan', schema: TASKS_SCHEMA },
+)
+if (!plan || !plan.tasks.length) return { epic: EPIC, status: 'no tasks planned' }
+
+const byKey = new Map(plan.tasks.map(t => [t.key, t]))
+for (const t of plan.tasks) {
+  const unknown = t.depends_on.filter(k => !byKey.has(k))
+  if (unknown.length) {
+    log(`${t.key}: ignoring unknown dependencies ${unknown.join(', ')}`)
+    t.depends_on = t.depends_on.filter(k => byKey.has(k))
+  }
+}
+const visiting = new Set(), visited = new Set()
+const visit = (k, path) => {
+  if (visited.has(k)) return
+  if (visiting.has(k)) throw new Error(`dependency cycle in plan: ${[...path, k].join(' -> ')}`)
+  visiting.add(k)
+  byKey.get(k).depends_on.forEach(d => visit(d, [...path, k]))
+  visiting.delete(k)
+  visited.add(k)
+}
+plan.tasks.forEach(t => visit(t.key, []))
+const roots = plan.tasks.filter(t => !t.depends_on.length).length
+log(`"${plan.epic_title}": ${plan.tasks.length} tasks, ${roots} can start immediately, up to ${MAX_AGENTS} agents at once`)
+
+// ---- Build → Review → Merge, per task, started as soon as its dependencies merge ----
+const settled = new Map(plan.tasks.map(t => {
+  let resolve
+  const promise = new Promise(r => { resolve = r })
+  return [t.key, { promise, resolve }]
+}))
+
+const brief = t => `Task ${t.key}: ${t.title}
+ClickUp task: ${t.clickup_id}
+Epic: ${EPIC}
+Scope (globs you may change): ${t.scope.join(', ')}
+
+${t.spec}`
+
+async function build(t, pr, issues, label) {
+  const prompt = pr
+    ? `Mode: FIX. PR #${pr.pr_number} on branch ${pr.branch}.\n${brief(t)}\n\nBlocking issues:\n${issues.map((s, i) => `${i + 1}. ${s}`).join('\n')}`
+    : `Mode: BUILD.\n${brief(t)}`
+  return run(prompt, { agentType: 'junior-dev', isolation: 'worktree', phase: 'Build', label, schema: PR_SCHEMA })
+}
+
+async function review(t, pr, round) {
+  const suffix = round ? `#${round}` : ''
+  const [rev, lead] = await parallel([
+    () => run(`Mode: REVIEW. PR #${pr.pr_number}.\n${brief(t)}`,
+      { agentType: 'reviewer', phase: 'Review', label: `review:${t.key}${suffix}`, schema: VERDICT_SCHEMA }),
+    () => run(`Mode: APPROVE. PR #${pr.pr_number}.\n${brief(t)}`,
+      { agentType: 'senior-lead', phase: 'Review', label: `lead:${t.key}${suffix}`, schema: VERDICT_SCHEMA }),
+  ])
+  const issues = [
+    ...(rev ? rev.blocking_issues.map(s => `[reviewer] ${s}`) : ['[reviewer] review did not complete; re-request it']),
+    ...(lead ? lead.blocking_issues.map(s => `[lead] ${s}`) : ['[lead] approval did not complete; re-request it']),
+  ]
+  return { approved: Boolean(rev && rev.approved && lead && lead.approved), issues }
+}
+
+const merge = (t, pr, attempt) => run(
+  `Merge PR #${pr.pr_number} (branch ${pr.branch}) for task ${t.key}, ClickUp ${t.clickup_id}.`,
+  { agentType: 'integrator', isolation: 'worktree', phase: 'Merge', label: `merge:${t.key}${attempt ? '#2' : ''}`, schema: MERGE_SCHEMA },
+)
+
+async function runTask(t) {
+  const base = { key: t.key, title: t.title, clickup_id: t.clickup_id }
+  const deps = await Promise.all(t.depends_on.map(k => settled.get(k).promise))
+  const failedDeps = t.depends_on.filter((k, i) => deps[i].status !== 'merged')
+  if (failedDeps.length) return { ...base, status: 'blocked', reason: `dependencies not merged: ${failedDeps.join(', ')}` }
+
+  let pr = await build(t, null, null, `junior:${t.key}`)
+  if (!pr || !pr.pr_number) return { ...base, status: 'failed', reason: pr ? pr.notes : 'junior agent died' }
+
+  let verdict
+  for (let round = 0; ; round++) {
+    verdict = await review(t, pr, round)
+    if (verdict.approved || round >= FIX_ROUNDS) break
+    const fixed = await build(t, pr, verdict.issues, `fix:${t.key}#${round + 1}`)
+    if (fixed && fixed.pr_number) pr = fixed
+  }
+  if (!verdict.approved) {
+    return { ...base, status: 'rejected', pr: pr.pr_number, reason: `still blocked after ${FIX_ROUNDS} fix rounds: ${verdict.issues.join(' | ')}` }
+  }
+
+  let m = await merge(t, pr, 0)
+  if (m && !m.merged && m.needs_rebase) {
+    const fixed = await build(t, pr, [`Rebase onto origin/main and resolve conflicts: ${m.reason || 'see integrator output'}`], `rebase:${t.key}`)
+    if (fixed && fixed.pr_number) {
+      const recheck = await review(t, fixed, FIX_ROUNDS + 1)
+      if (recheck.approved) m = await merge(t, fixed, 1)
+      else m = { merged: false, reason: `re-review after rebase failed: ${recheck.issues.join(' | ')}` }
+    }
+  }
+  if (!m || !m.merged) return { ...base, status: 'failed', pr: pr.pr_number, reason: m ? m.reason : 'integrator died' }
+  return { ...base, status: 'merged', pr: pr.pr_number, sha: m.merge_sha }
+}
+
+const results = await parallel(plan.tasks.map(t => async () => {
+  let r
+  try {
+    r = await runTask(t)
+  } catch (e) {
+    r = { key: t.key, title: t.title, clickup_id: t.clickup_id, status: 'failed', reason: String(e) }
+  }
+  settled.get(t.key).resolve(r)
+  log(`${t.key} ${r.status}${r.pr ? ` (PR #${r.pr})` : ''}`)
+  return r
+}))
+
+// ---- Verify ----
+phase('Verify')
+const count = s => results.filter(r => r && r.status === s).length
+log(`merged ${count('merged')}, rejected ${count('rejected')}, failed ${count('failed')}, blocked ${count('blocked')}`)
+
+const qa = count('merged')
+  ? await run(
+    `Mode: VERIFY. Epic ${EPIC} ("${plan.epic_title}"). Merged tasks:\n${results.filter(r => r.status === 'merged').map(r => `- ${r.key} ${r.title} (PR #${r.pr})`).join('\n')}`,
+    { agentType: 'qa-lead', isolation: 'worktree', phase: 'Verify', label: 'qa:verify', schema: QA_SCHEMA },
+  )
+  : null
+
+const report = await run(
+  `Mode: REPORT. Epic ${EPIC} ("${plan.epic_title}").\n${JSON.stringify({ tasks: results, qa }, null, 2)}`,
+  { agentType: 'senior-lead', phase: 'Verify', label: 'lead:report' },
+)
+
+return {
+  epic: EPIC,
+  title: plan.epic_title,
+  done: count('merged') === plan.tasks.length && Boolean(qa && qa.passed),
+  tasks: results,
+  qa,
+  report,
+}

xtruct/_cli/template/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Task
+ClickUp: <link>  ·  Epic: <link>
+
+## What changed
+-
+
+## Acceptance criteria → tests
+| Criterion | Test |
+|---|---|
+|  |  |
+
+## Scope
+<!-- scope
+src/example/**
+tests/example/**
+-->
+
+## Checks run locally
+- [ ] make lint
+- [ ] make typecheck
+- [ ] make test
+- [ ] make e2e (if a user flow changed)
+
+## Notes for reviewers

xtruct/_cli/template/CLAUDE.md

@@ -0,0 +1,65 @@
+# Company handbook
+
+This product is built by a team of AI agents. The founder (the human) sets direction and has final say. Every agent follows this handbook.
+
+@docs/CONVENTIONS.md
+
+## Roles
+
+| Role | Agent | Owns |
+|---|---|---|
+| Founder | human | Approving the spec and epics, final sign-off, founder-only paths |
+| Architect | `architect` | PRD, architecture, stack choice, `contracts/` |
+| Senior lead | `senior-lead` | One epic: splits it into tasks, assigns each task's scope, approves PRs for spec fit |
+| Junior dev | `junior-dev` | One task: code + tests on its own branch, opens the PR |
+| Reviewer | `reviewer` | Code review: correctness, security, test quality |
+| Integrator | `integrator` | Merging, only through `scripts/merge-pr.sh` |
+| QA lead | `qa-lead` | E2E tests from the spec, verifying `main` after each epic |
+
+## Sources of truth
+
+- Product: `docs/PRD.md`. Architecture and stack: `docs/ARCHITECTURE.md`. Stack-specific coding rules: `docs/CONVENTIONS.md`.
+- Contracts (DB schema, API spec, shared types, route map): `contracts/`. They are frozen once the Foundation epic merges. If a task needs a contract change, stop and report it; do not change it.
+- Work tracking: ClickUp. Workspace, space, folder and list IDs are in `foundry.config.json`.
+
+## Make targets (stack-agnostic contract)
+
+Every product implements `make setup`, `lint`, `typecheck`, `test`, `e2e`, `build`, `dev` and `ci`. CI runs `make ci`. Run at least `make lint typecheck test` before opening a PR.
+
+## Git
+
+- Branch from fresh `origin/main`: `git fetch origin && git switch -c t/<clickup-id>-<slug> origin/main`.
+- Conventional commits ending with the ClickUp id, e.g. `feat: login form (CU-86abc12)`.
+- Never push to `main`. Never force-push (`--force-with-lease` on your own task branch only). Never `--no-verify`.
+- Never merge yourself. Only the integrator merges, and only through `scripts/merge-pr.sh`.
+- One task = one PR, under ~800 changed lines excluding lockfiles.
+
+## Pull requests
+
+- Use `.github/pull_request_template.md`. The `<!-- scope ... -->` block lists the task's scope globs exactly as the lead assigned them; the merge gate rejects files outside it.
+- Labels: `review:passed` (reviewer), `lead:approved` (lead), `large-ok` (lead, oversized PR), `founder-approved` (founder only, never add it yourself).
+- All agents share one GitHub account, so `gh pr review --approve` does not work. Approval is a PR comment plus the label.
+
+## ClickUp
+
+- Hierarchy: product folder → list `Epics` → task = epic → subtask = task → checklist items = subtasks.
+- Status flow: `to do` → `in progress` → `in review` → `changes requested` → `merged` → `done`; `blocked` at any point. If the list lacks a status, use the closest one and add a tag with the intended status.
+- Comment on the ClickUp task at each step: PR link when opened, review verdict, merge SHA.
+
+## Diagrams (Xtruct)
+
+When the `xtruct` skill is available and `foundry.config.json` → `integrations.xtruct` is not `"off"`, the architect and senior leads produce interactive Xtruct diagrams as their roles describe. Diagrams are optional output: if the skill is missing or its validation fails twice, carry on without one and say so in one line. Never block a task on a diagram.
+
+## Definition of done (task)
+
+- Every acceptance criterion is met and covered by at least one test that would fail without the change.
+- `make lint typecheck test` pass locally and CI is green.
+- No skipped or disabled tests, no TODOs without a ClickUp task, no secrets, no debug output.
+- Reviewer and lead approved, integrator merged, ClickUp updated.
+
+## Guardrails
+
+- Founder-only paths: `.claude/`, `CLAUDE.md`, `scripts/merge-pr.sh`, `scripts/bootstrap-github.sh`, `scripts/capacity.mjs`. Hooks block agent edits there.
+- Never read or write `.env` files other than `.env.example`. Document every config variable in `.env.example`.
+- If a guardrail blocks you, do not work around it. Report what you needed and why.
+- After two honest attempts at something that still fails, stop and report `blocked` with what you tried. An honest "blocked" beats a fake "done".

xtruct/_cli/template/Makefile

@@ -0,0 +1,8 @@
+# Stack-agnostic contract. CI and every agent call these targets, never the stack's tools directly.
+# The Foundation epic replaces each recipe with the real command for the chosen stack.
+.PHONY: setup dev lint typecheck test e2e build ci
+
+setup dev lint typecheck test e2e build:
+	@echo "make $@: not configured yet (the Foundation epic sets this up)"; exit 1
+
+ci: lint typecheck test build e2e

xtruct/_cli/template/_gitignore

@@ -0,0 +1,13 @@
+.env
+.env.*
+!.env.example
+node_modules/
+.venv/
+__pycache__/
+dist/
+build/
+coverage/
+playwright-report/
+test-results/
+.DS_Store
+.claude/settings.local.json

xtruct/_cli/template/contracts/README.md

@@ -0,0 +1,4 @@
+# Contracts
+
+DB schema, API spec, shared types and route map. Written by the architect, frozen after Foundation.
+Tasks build against these; changes need the architect and the founder.

xtruct/_cli/template/docs/CONVENTIONS.md

@@ -0,0 +1,3 @@
+# Conventions
+
+Written by the architect once the stack is chosen. Until then, follow the surrounding code.

xtruct/_cli/template/docs/templates/ARCHITECTURE.md

@@ -0,0 +1,30 @@
+# <Product> — Architecture
+
+## Stack
+| Layer | Choice | Why |
+|---|---|---|
+
+### Alternatives considered
+What was rejected and why.
+
+## Components
+Each service/app/package: responsibility, owner epic, main dependencies.
+
+## Data model
+Summary; source of truth is `contracts/`.
+
+## API
+Style (REST/GraphQL/RPC) and conventions; source of truth is `contracts/`.
+
+## Auth and permissions
+
+## Deployment and environments
+Local (`make dev`), preview, production.
+
+## Observability
+Logging, errors, metrics.
+
+## Security considerations
+
+## Decisions
+Dated log of significant decisions and rejected critique.