chapterhouse 0.3.0 → 0.3.2

package/dist/squad/init.js

@@ -0,0 +1,395 @@
+/**
+ * src/squad/init.ts
+ *
+ * Core scaffolding logic for `chapterhouse squad init`.
+ * Creates a complete `.squad/` directory structure with casting state,
+ * agent charters, and team coordination files.
+ *
+ * This is the mechanical implementation of the Squad coordinator's
+ * Init Mode Phase 2 flow (see `.squad/squad.agent.md`).
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Universe character pools
+// ---------------------------------------------------------------------------
+/**
+ * Dune character pool — function/pressure/consequence-flavored names.
+ * Coordinator = "Squad", Scribe = "Scribe", Ralph = "Ralph" are exempted.
+ * Source: Issue #23 + `.squad/skills/dune-release-names/SKILL.md`
+ */
+export const DUNE_CHARACTERS = [
+    'Leto',
+    'Jessica',
+    'Stilgar',
+    'Chani',
+    'Gurney',
+    'Duncan',
+    'Thufir',
+    'Piter',
+    'Feyd',
+    'Hawat',
+    'Mapes',
+    'Liet',
+    'Halleck',
+    'Idaho',
+    'Shaddam',
+    'Irulan',
+];
+/** All available universe pools.  Add new universes here. */
+export const UNIVERSE_CHARACTERS = {
+    Dune: DUNE_CHARACTERS,
+    Firefly: ['Mal', 'Zoe', 'Wash', 'Inara', 'Jayne', 'Kaylee', 'Simon', 'River', 'Book', 'Shepherd'],
+    'Star Wars': ['Luke', 'Leia', 'Han', 'Chewie', 'Obi-Wan', 'Yoda', 'Vader', 'Wedge', 'Lando', 'R2-D2', 'C-3PO', 'Poe'],
+    'The Matrix': ['Neo', 'Trinity', 'Morpheus', 'Oracle', 'Tank', 'Apoc', 'Switch', 'Dozer', 'Cypher', 'Agent-Smith'],
+    'Breaking Bad': ['Walt', 'Jesse', 'Skyler', 'Hank', 'Saul', 'Mike', 'Gus', 'Jane', 'Lydia', 'Todd', 'Andrea', 'Huell'],
+};
+export const DEFAULT_UNIVERSE = 'Dune';
+/** Roles cast when teamSize ≤ 4 (Lead + 3 specialists + Scribe). */
+const ROLE_PRESETS = {
+    3: [
+        { slug: 'lead', role: 'Lead', description: 'Scope, decisions, code review', icon: '🏗️' },
+        { slug: 'dev', role: 'Developer', description: 'Implementation, features', icon: '⚙️' },
+        { slug: 'tester', role: 'Tester', description: 'Tests, quality, edge cases', icon: '🧪' },
+    ],
+    4: [
+        { slug: 'lead', role: 'Lead', description: 'Scope, decisions, code review', icon: '🏗️' },
+        { slug: 'frontend', role: 'Frontend Dev', description: 'UI, components, styling', icon: '⚛️' },
+        { slug: 'backend', role: 'Backend Dev', description: 'APIs, database, services', icon: '🔧' },
+        { slug: 'tester', role: 'Tester', description: 'Tests, quality, edge cases', icon: '🧪' },
+    ],
+    5: [
+        { slug: 'lead', role: 'Lead', description: 'Scope, decisions, architecture', icon: '🏗️' },
+        { slug: 'frontend', role: 'Frontend Dev', description: 'UI, components, styling', icon: '⚛️' },
+        { slug: 'backend', role: 'Backend Dev', description: 'APIs, database, services', icon: '🔧' },
+        { slug: 'tester', role: 'Tester', description: 'Tests, quality, edge cases', icon: '🧪' },
+        { slug: 'devops', role: 'DevOps', description: 'CI/CD, infra, deployment', icon: '🚀' },
+    ],
+};
+/** Always-present fixed-name agents (exempt from casting). */
+const FIXED_AGENTS = [
+    { slug: 'scribe', role: 'Scribe', description: 'Memory, decisions, session logs', icon: '📋', castName: 'Scribe' },
+    { slug: 'ralph', role: 'Monitor', description: 'Work queue, backlog, keep-alive', icon: '🔄', castName: 'Ralph' },
+];
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Returns true if `.squad/team.md` with a populated `## Members` section exists. */
+export function isSquadInitialized(projectRoot) {
+    const teamMd = join(projectRoot, '.squad', 'team.md');
+    if (!existsSync(teamMd))
+        return false;
+    const content = readFileSync(teamMd, 'utf-8');
+    return /^## Members/m.test(content) && content.includes('|');
+}
+/**
+ * Allocate cast names from the chosen universe for the given role slots.
+ * Returns a map of role slug → cast name.
+ */
+export function allocateCast(roles, universe) {
+    const pool = UNIVERSE_CHARACTERS[universe] ?? DUNE_CHARACTERS;
+    const result = {};
+    pool.slice(0, roles.length).forEach((name, i) => {
+        result[roles[i].slug] = name;
+    });
+    return result;
+}
+/**
+ * Resolve the AgentRole[] for a given team size.
+ * Clamps to valid presets (3–5). Extras default to the 5-slot preset.
+ */
+export function resolveRoles(teamSize) {
+    const clamped = Math.min(Math.max(teamSize, 3), 5);
+    return ROLE_PRESETS[clamped] ?? ROLE_PRESETS[4];
+}
+/**
+ * Scaffold a complete `.squad/` directory for `projectRoot`.
+ *
+ * Safe to call on an already-initialized project — if `.squad/team.md`
+ * already has roster entries, the call returns `null` without touching disk.
+ * Pass `{ force: true }` to override.
+ */
+export function scaffoldSquad(projectRoot, config, opts = {}) {
+    if (!opts.force && isSquadInitialized(projectRoot)) {
+        return null; // idempotent guard
+    }
+    const { projectName, stack, goal, teamSize = 4, universe = DEFAULT_UNIVERSE, humanName = 'the team', } = config;
+    const squadDir = join(projectRoot, '.squad');
+    const roles = resolveRoles(teamSize);
+    const castMap = allocateCast(roles, universe);
+    const now = new Date().toISOString();
+    const assignmentId = randomUUID();
+    // Build flat agent list (cast agents + fixed agents)
+    const castAgents = roles.map(r => ({
+        slug: castMap[r.slug].toLowerCase(),
+        castName: castMap[r.slug],
+        role: r.role,
+        description: r.description,
+        icon: r.icon,
+        originalSlug: r.slug,
+    }));
+    // Directories to create
+    const dirs = [
+        squadDir,
+        join(squadDir, 'agents'),
+        join(squadDir, 'casting'),
+        join(squadDir, 'decisions'),
+        join(squadDir, 'decisions', 'inbox'),
+        join(squadDir, 'orchestration-log'),
+        join(squadDir, 'log'),
+        join(squadDir, 'skills'),
+        join(squadDir, 'identity'),
+        ...castAgents.map(a => join(squadDir, 'agents', a.slug)),
+        ...FIXED_AGENTS.map(a => join(squadDir, 'agents', a.slug)),
+    ];
+    dirs.forEach(d => mkdirSync(d, { recursive: true }));
+    // ── team.md ──────────────────────────────────────────────────────────────
+    const rosterRows = [
+        ...castAgents.map(a => `| ${a.icon} ${a.castName} | @${a.slug} | ${a.role} | ${a.description} |`),
+        `| 📋 Scribe     | @scribe | Scribe  | Memory, decisions, session logs |`,
+        `| 🔄 Ralph      | @ralph  | Monitor | Work queue, backlog, keep-alive |`,
+    ].join('\n');
+    writeFile(join(squadDir, 'team.md'), `# ${projectName} — Squad Team
+
+## Project Context
+
+- **Project:** ${projectName}
+- **Stack:** ${stack}
+- **Goal:** ${goal}
+- **Human:** ${humanName}
+- **Universe:** ${universe}
+- **Initialized:** ${now}
+
+## Members
+
+| Icon | Name | Role | Description |
+|------|------|------|-------------|
+${rosterRows}
+`);
+    // ── routing.md ───────────────────────────────────────────────────────────
+    const routingRules = castAgents.map(a => `- **${a.role}** → @${a.slug}`).join('\n');
+    writeFile(join(squadDir, 'routing.md'), `# Routing Rules
+
+Route tasks to the right agent based on their role.
+
+${routingRules}
+- **Memory / Decisions** → @scribe
+- **Backlog / Queue** → @ralph
+
+## Default
+
+When unclear, route to the Lead.
+`);
+    // ── ceremonies.md ────────────────────────────────────────────────────────
+    writeFile(join(squadDir, 'ceremonies.md'), `# Ceremonies
+
+## Sprint Rhythm
+
+- **Sprint Planning** — Start of each sprint: define goals, assign issues
+- **Daily Standup** — Each session: what's in progress, blockers
+- **Sprint Review** — End of sprint: demo, retro, decisions
+
+## PR Review Gate
+
+All PRs require approval from the Lead before merging.
+
+## Decision Log
+
+Architectural decisions land in \`.squad/decisions/inbox/\` via each agent's decision-drop.
+Scribe merges inbox items into \`.squad/decisions.md\`.
+`);
+    // ── decisions.md ─────────────────────────────────────────────────────────
+    writeFile(join(squadDir, 'decisions.md'), `# Decisions
+
+This file is maintained by Scribe. Append-only — do not edit existing entries.
+
+<!-- git attribute: .squad/decisions.md merge=union -->
+`);
+    // ── agent charters ───────────────────────────────────────────────────────
+    for (const agent of castAgents) {
+        writeFile(join(squadDir, 'agents', agent.slug, 'charter.md'), buildCharter({
+            castName: agent.castName,
+            role: agent.role,
+            description: agent.description,
+            projectName,
+            stack,
+            goal,
+            humanName,
+            universe,
+        }));
+        writeFile(join(squadDir, 'agents', agent.slug, 'history.md'), buildHistory({
+            castName: agent.castName,
+            role: agent.role,
+            projectName,
+            stack,
+            goal,
+            humanName,
+            now,
+        }));
+    }
+    // Scribe charter
+    writeFile(join(squadDir, 'agents', 'scribe', 'charter.md'), `# Scribe — Memory Keeper
+
+> Keeps the record. Remembers everything so everyone else can focus.
+
+## Identity
+
+- **Name:** Scribe
+- **Role:** Scribe / Memory Keeper
+- **Project:** ${projectName}
+
+## What I Own
+
+- \`.squad/decisions.md\` — merge inbox items, maintain canonical list
+- \`.squad/orchestration-log/\` — session summaries
+- Cross-agent context sharing
+
+## Constraints
+
+- Read-only on all non-\`.squad/\` files
+- Never authors code or domain artifacts
+`);
+    writeFile(join(squadDir, 'agents', 'scribe', 'history.md'), `# Scribe History\n\n## Init — ${now}\n\nInitialized for **${projectName}** by ${humanName}.\nStack: ${stack}\nGoal: ${goal}\n`);
+    // Ralph charter
+    writeFile(join(squadDir, 'agents', 'ralph', 'charter.md'), `# Ralph — Monitor
+
+> Keeps the queue moving. Never lets work pile up unnoticed.
+
+## Identity
+
+- **Name:** Ralph
+- **Role:** Monitor / Work Queue
+- **Project:** ${projectName}
+
+## What I Own
+
+- GitHub issue triage and backlog health
+- Keep-alive heartbeat checks
+- Sprint queue management
+`);
+    writeFile(join(squadDir, 'agents', 'ralph', 'history.md'), `# Ralph History\n\n## Init — ${now}\n\nInitialized for **${projectName}** by ${humanName}.\n`);
+    // ── casting state ─────────────────────────────────────────────────────────
+    const policyJson = {
+        casting_policy_version: '1.1',
+        allowlist_universes: [universe],
+        universe_capacity: {
+            [universe]: (UNIVERSE_CHARACTERS[universe] ?? DUNE_CHARACTERS).length,
+        },
+    };
+    const registryAgents = {};
+    for (const a of castAgents) {
+        registryAgents[a.originalSlug] = {
+            persistent_name: a.castName,
+            universe,
+            created_at: now,
+            legacy_named: false,
+            status: 'active',
+        };
+    }
+    for (const a of FIXED_AGENTS) {
+        registryAgents[a.slug] = {
+            persistent_name: a.castName,
+            universe: 'exempt',
+            created_at: now,
+            legacy_named: false,
+            status: 'active',
+        };
+    }
+    const registryJson = { agents: registryAgents };
+    const agentSnapshot = {};
+    for (const a of castAgents)
+        agentSnapshot[a.originalSlug] = a.castName;
+    agentSnapshot['scribe'] = 'Scribe';
+    agentSnapshot['ralph'] = 'Ralph';
+    const historyJson = {
+        universe_usage_history: [{ universe, assignment_id: assignmentId, used_at: now }],
+        assignment_cast_snapshots: {
+            [assignmentId]: { universe, agents: agentSnapshot, created_at: now },
+        },
+    };
+    writeFile(join(squadDir, 'casting', 'policy.json'), JSON.stringify(policyJson, null, 2));
+    writeFile(join(squadDir, 'casting', 'registry.json'), JSON.stringify(registryJson, null, 2));
+    writeFile(join(squadDir, 'casting', 'history.json'), JSON.stringify(historyJson, null, 2));
+    // ── .gitattributes merge driver ───────────────────────────────────────────
+    ensureGitattributes(projectRoot);
+    return {
+        squadDir,
+        agents: castAgents.map(a => ({ slug: a.slug, castName: a.castName, role: a.role })),
+        universe,
+        assignmentId,
+    };
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+function writeFile(path, content) {
+    writeFileSync(path, content, 'utf-8');
+}
+function buildCharter(opts) {
+    return `# ${opts.castName} — ${opts.role}
+
+> ${opts.description}
+
+## Identity
+
+- **Name:** ${opts.castName}
+- **Role:** ${opts.role}
+- **Universe:** ${opts.universe}
+- **Project:** ${opts.projectName}
+
+## Project Context
+
+- **Stack:** ${opts.stack}
+- **Goal:** ${opts.goal}
+- **Human:** ${opts.humanName}
+
+## What I Own
+
+_Defined by role: ${opts.role}. Update this section with project-specific scope._
+
+## Constraints
+
+- Follow the team's conventions in \`.squad/decisions.md\`
+- All commits must follow Conventional Commits
+- All PRs must reference the issue they close
+
+## Voice
+
+Direct. Focused on delivering quality work for ${opts.projectName}.
+`;
+}
+function buildHistory(opts) {
+    return `# ${opts.castName} History
+
+<!-- git attribute: .squad/agents/${opts.castName.toLowerCase()}/history.md merge=union -->
+
+## Init — ${opts.now}
+
+Joined **${opts.projectName}** as ${opts.role}, working with ${opts.humanName}.
+
+**Stack:** ${opts.stack}
+**Goal:** ${opts.goal}
+`;
+}
+const GITATTRIBUTES_BLOCK = `
+# Squad — append-only conflict-free merge
+.squad/decisions.md merge=union
+.squad/agents/*/history.md merge=union
+.squad/log/** merge=union
+.squad/orchestration-log/** merge=union
+`;
+function ensureGitattributes(projectRoot) {
+    const gaPath = join(projectRoot, '.gitattributes');
+    const marker = '.squad/decisions.md merge=union';
+    if (existsSync(gaPath)) {
+        const existing = readFileSync(gaPath, 'utf-8');
+        if (!existing.includes(marker)) {
+            appendFileSync(gaPath, GITATTRIBUTES_BLOCK);
+        }
+    }
+    else {
+        writeFileSync(gaPath, GITATTRIBUTES_BLOCK.trimStart());
+    }
+}
+//# sourceMappingURL=init.js.map