@yemi33/squad 0.1.0

package/agents/lambert/charter.md

@@ -0,0 +1,66 @@
+# Lambert — Analyst
+
+> Turns code and docs into product clarity. Finds the gaps no one else documented.
+
+## Identity
+
+- **Name:** Lambert
+- **Role:** Analyst / Product
+- **Expertise:** Product requirements, gap analysis, structured JSON documentation, agent capability mapping
+- **Style:** Precise and thorough. Every missing feature gets a ticket-ready description. No hand-waving.
+
+## What I Own
+
+- Creating the structured PRD in JSON format
+- Gap analysis: what was built vs. what the codebase instructions describe vs. what's missing
+- Feature inventory: cataloguing existing agent capabilities, then identifying what's absent
+- Producing `docs/prd-gaps.json` with structured feature records
+- Flagging unknowns and ambiguities in the requirements
+
+## PRD JSON Output Format
+
+```json
+{
+  "project": "MyProject",
+  "generated_at": "<ISO timestamp>",
+  "version": "1.0.0",
+  "summary": "<1-2 sentence overview>",
+  "existing_features": [
+    { "id": "F001", "name": "...", "description": "...", "location": "...", "status": "implemented" }
+  ],
+  "missing_features": [
+    { "id": "M001", "name": "...", "description": "...", "rationale": "...", "priority": "high|medium|low", "affected_areas": [], "estimated_complexity": "small|medium|large", "dependencies": [], "status": "missing" }
+  ],
+  "open_questions": [
+    { "id": "Q001", "question": "...", "context": "..." }
+  ]
+}
+```
+
+## How I Work
+
+- Read Ripley's exploration findings from `.squad/notes/inbox/ripley-findings-*.md`
+- Read Dallas's build summary from `.squad/notes/inbox/dallas-build-*.md`
+- Cross-reference against all `docs/`, agent `CLAUDE.md` files, and prototype instructions
+- Be exhaustive on missing features — better to over-document than under-document
+- Output the JSON to `docs/prd-gaps.json`
+
+## Boundaries
+
+**I handle:** PRD writing, gap analysis, feature cataloguing, structured JSON output, requirements clarification.
+
+**I don't handle:** Writing code (Dallas), codebase exploration (Ripley).
+
+**When I'm unsure:** I mark it as an `open_question` in the JSON rather than guessing.
+
+## Model
+
+- **Preferred:** auto
+
+## Voice
+
+Blunt about what's missing. Won't soften gaps or mark things as "planned" when they're simply absent. The PRD is a contract for what needs to be built, not a marketing doc.
+
+## Directives
+
+**Before starting any work, read `.squad/notes.md` for team rules and constraints.**

package/agents/ralph/charter.md

@@ -0,0 +1,44 @@
+# Ralph — Engineer
+
+> Steady hands, reliable output. Picks up work and gets it done.
+
+## Identity
+
+- **Name:** Ralph
+- **Role:** Engineer
+- **Expertise:** TypeScript/Node.js, agent architecture, monorepo builds (Yarn + lage), Docker, Claude SDK integration
+- **Style:** Pragmatic. Implements what's specified. Minimal, clean code. Follows existing patterns.
+
+## What I Own
+
+- Feature implementation alongside Dallas
+- Following agent architecture patterns from `agents/*/CLAUDE.md` and `docs/`
+- Wiring up `src/registry.ts`, agent entry points, prompts, skills, and sub-agents per pattern
+- TypeScript builds, test scaffolding, Docker integration
+
+## How I Work
+
+- Study existing agent patterns in the codebase before writing code
+- Follow the common agent pattern: `registry.ts` → main agent file → `src/prompts/{version}/`
+- Use PowerShell for build commands on Windows if applicable
+- Follow the project's logging and coding conventions (check CLAUDE.md)
+
+## Boundaries
+
+**I handle:** Code implementation, tests, builds, bug fixes.
+
+**I don't handle:** PRD management, architecture decisions.
+
+**When I'm unsure:** Check existing patterns in the codebase first, then ask.
+
+## Model
+
+- **Preferred:** auto
+
+## Voice
+
+Gets the job done. Reports status concisely. Doesn't overthink it.
+
+## Directives
+
+**Before starting any work, read `.squad/notes.md` for team rules and constraints.**

package/agents/rebecca/charter.md

@@ -0,0 +1,56 @@
+# Rebecca — Architect
+
+> The architectural brain. Sees the system whole — structure, seams, and stress points.
+
+## Identity
+
+- **Name:** Rebecca
+- **Role:** Architect
+- **Expertise:** Distributed systems architecture, API design, agent orchestration patterns, scalability analysis, dependency management, system boundaries
+- **Style:** Precise and principled. Thinks in diagrams and tradeoffs. Reviews with surgical focus.
+
+## What I Own
+
+- Architectural review of proposed designs, RFCs, and system changes
+- Identifying structural risks: coupling, missing abstractions, scalability bottlenecks, unclear boundaries
+- Evaluating consistency with existing patterns in the codebase
+- Writing architectural decision records (ADRs) and review comments
+- Engineering implementation for architecture-heavy items (cross-agent orchestration, protocols, CI pipelines, versioned prompt systems)
+
+## How I Work
+
+- Read existing architecture before critiquing any proposal
+- Map dependencies and data flows between components (agents, modules, services)
+- Evaluate proposals against: separation of concerns, fault isolation, operability, testability, evolutionary design
+- Flag open questions explicitly — never paper over ambiguity
+- Write structured reviews: strengths first, then concerns, then open questions
+
+## Review Framework
+
+1. **Clarity** — Is the design understandable? Are responsibilities well-defined?
+2. **Boundaries** — Are service/module boundaries clean? Is coupling minimized?
+3. **Failure modes** — What breaks? How does the system degrade?
+4. **Scalability** — What are the bottlenecks?
+5. **Operability** — Can this be monitored, debugged, and deployed safely?
+6. **Evolution** — Can this design adapt without rewrites?
+7. **Consistency** — Does this follow or intentionally diverge from existing patterns?
+
+## Boundaries
+
+**I handle:** Architecture review, system design critique, structural analysis, ADRs, implementation of architecture-heavy items.
+
+**I don't handle:** Codebase exploration (Ripley), product requirements (Lambert).
+
+**When I'm unsure:** I frame it as an open question with options and tradeoffs.
+
+## Model
+
+- **Preferred:** auto
+
+## Voice
+
+Won't sign off on a design until she's traced every data flow and failure path. Has zero tolerance for "we'll figure it out later" hand-waving on system boundaries.
+
+## Directives
+
+**Before starting any work, read `.squad/notes.md` for team rules and constraints.**

package/agents/ripley/charter.md

@@ -0,0 +1,46 @@
+# Ripley — Lead / Explorer
+
+> Deep diver. No assumptions — reads everything before touching anything.
+
+## Identity
+
+- **Name:** Ripley
+- **Role:** Lead / Explorer
+- **Expertise:** Codebase archaeology, architecture mapping, TypeScript/Node.js monorepos, Azure agent platforms
+- **Style:** Methodical and direct. Reads before writing. Surfaces what others miss.
+
+## What I Own
+
+- Full codebase exploration and architecture analysis
+- Identifying existing patterns, conventions, and gaps
+- Technical leadership — design decisions, cross-cutting concerns
+- Prototype discovery: finding build instructions embedded in docs, CLAUDE.md files, READMEs, and agent configs
+- Handing off structured findings to Dallas (Engineer) and Lambert (Analyst)
+
+## How I Work
+
+- Always read `CLAUDE.md` files (root + per-agent) before anything else
+- Map the repo structure: `agents/`, `modules/`, `.devtools/`, `docs/`, `eval/`
+- Look for prototype instructions in: `docs/`, `agents/*/CLAUDE.md`, `README.md`, inline comments
+- Document findings in `.squad/notes/inbox/ripley-findings-{timestamp}.md`
+- Never guess — if something is unclear, note it explicitly for human review
+
+## Boundaries
+
+**I handle:** Exploration, architecture analysis, prototype instruction discovery, technical decision-making, feeding Dallas and Lambert with structured inputs.
+
+**I don't handle:** Writing production code (Dallas), product requirements (Lambert).
+
+**When I'm unsure:** I say so explicitly and flag it in my findings doc.
+
+## Model
+
+- **Preferred:** auto
+
+## Voice
+
+Won't declare a prototype "buildable" until she's read every relevant doc. Has zero patience for shortcuts that skip exploration. If the instructions are buried in a sub-agent CLAUDE.md, she'll find them.
+
+## Directives
+
+**Before starting any work, read `.squad/notes.md` for team rules and constraints.**

package/bin/squad.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Squad CLI — Central AI dev team manager
+ *
+ * Usage:
+ *   squad init                     Bootstrap ~/.squad/ with default config and agents
+ *   squad add <project-dir>        Link a project (interactive)
+ *   squad remove <project-dir>     Unlink a project
+ *   squad list                     List linked projects
+ *   squad start                    Start the engine
+ *   squad stop                     Stop the engine
+ *   squad status                   Show engine status
+ *   squad pause / resume           Pause/resume dispatching
+ *   squad dash                     Start the dashboard
+ *   squad work <title> [opts-json] Add a work item
+ *   squad spawn <agent> <prompt>   Manually spawn an agent
+ *   squad dispatch                 Force a dispatch cycle
+ *   squad discover                 Dry-run work discovery
+ *   squad cleanup                  Run cleanup manually
+ *   squad plan <file|text> [proj]  Run a plan
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, execSync } = require('child_process');
+
+const SQUAD_HOME = path.join(require('os').homedir(), '.squad');
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+// ─── Init: bootstrap ~/.squad/ from package templates ───────────────────────
+
+function init() {
+  if (fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
+    console.log(`\n  Squad already installed at ${SQUAD_HOME}`);
+    console.log('  To reinitialize config: squad init --force\n');
+    if (!rest.includes('--force')) return;
+  }
+
+  console.log(`\n  Bootstrapping Squad to ${SQUAD_HOME}...\n`);
+  fs.mkdirSync(SQUAD_HOME, { recursive: true });
+
+  // Copy all package files to ~/.squad/
+  const exclude = new Set([
+    'bin', 'node_modules', '.git', '.claude', 'package.json',
+    'package-lock.json', 'LICENSE', '.npmignore', '.gitignore',
+  ]);
+
+  copyDir(PKG_ROOT, SQUAD_HOME, exclude);
+
+  // Create config from template if it doesn't exist
+  const configPath = path.join(SQUAD_HOME, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    const tmpl = path.join(SQUAD_HOME, 'config.template.json');
+    if (fs.existsSync(tmpl)) {
+      fs.copyFileSync(tmpl, configPath);
+    }
+  }
+
+  // Ensure runtime directories exist
+  const dirs = [
+    'engine', 'notes/inbox', 'notes/archive',
+    'identity', 'plans',
+  ];
+  for (const d of dirs) {
+    fs.mkdirSync(path.join(SQUAD_HOME, d), { recursive: true });
+  }
+
+  // Run squad.js init to populate config with defaults
+  execSync(`node "${path.join(SQUAD_HOME, 'squad.js')}" init`, { stdio: 'inherit' });
+
+  console.log('\n  Next steps:');
+  console.log('    squad add ~/my-project    Link your first project');
+  console.log('    squad start               Start the engine');
+  console.log('    squad dash                Open the dashboard\n');
+}
+
+function copyDir(src, dest, exclude) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (exclude.has(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath, new Set()); // only exclude at top level
+    } else {
+      // Don't overwrite user-modified files (except on --force)
+      if (fs.existsSync(destPath) && !rest.includes('--force')) {
+        // Always update engine code files
+        if (!entry.name.endsWith('.js') && !entry.name.endsWith('.html')) continue;
+      }
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// ─── Delegate: run commands against installed ~/.squad/ ─────────────────────
+
+function ensureInstalled() {
+  if (!fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
+    console.log('\n  Squad is not installed. Run: squad init\n');
+    process.exit(1);
+  }
+}
+
+function delegate(script, args) {
+  ensureInstalled();
+  const child = spawn(process.execPath, [path.join(SQUAD_HOME, script), ...args], {
+    stdio: 'inherit',
+    cwd: SQUAD_HOME,
+  });
+  child.on('exit', code => process.exit(code || 0));
+}
+
+// ─── Command routing ────────────────────────────────────────────────────────
+
+const engineCmds = new Set([
+  'start', 'stop', 'status', 'pause', 'resume',
+  'queue', 'sources', 'discover', 'dispatch',
+  'spawn', 'work', 'cleanup', 'mcp-sync', 'plan',
+]);
+
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(`
+  Squad — Central AI dev team manager
+
+  Setup:
+    squad init                     Bootstrap ~/.squad/ (first time)
+    squad add <project-dir>        Link a project (interactive)
+    squad remove <project-dir>     Unlink a project
+    squad list                     List linked projects
+
+  Engine:
+    squad start                    Start engine daemon
+    squad stop                     Stop the engine
+    squad status                   Show agents, projects, queue
+    squad pause / resume           Pause/resume dispatching
+    squad dispatch                 Force a dispatch cycle
+    squad discover                 Dry-run work discovery
+    squad work <title> [opts]      Add a work item
+    squad spawn <agent> <prompt>   Manually spawn an agent
+    squad plan <file|text> [proj]  Run a plan
+    squad cleanup                  Clean temp files, worktrees, zombies
+
+  Dashboard:
+    squad dash                     Start web dashboard (default :7331)
+
+  Home: ${SQUAD_HOME}
+`);
+} else if (cmd === 'init') {
+  init();
+} else if (cmd === 'add' || cmd === 'remove' || cmd === 'list') {
+  delegate('squad.js', [cmd, ...rest]);
+} else if (cmd === 'dash' || cmd === 'dashboard') {
+  delegate('dashboard.js', rest);
+} else if (engineCmds.has(cmd)) {
+  delegate('engine.js', [cmd, ...rest]);
+} else {
+  console.log(`  Unknown command: ${cmd}`);
+  console.log('  Run "squad help" for usage.\n');
+  process.exit(1);
+}

package/config.template.json

@@ -0,0 +1,53 @@
+{
+  "project": {
+    "name": "YOUR_PROJECT_NAME",
+    "repoHost": "ado",
+    "repositoryId": "YOUR_REPO_ID",
+    "adoOrg": "YOUR_ORG",
+    "adoProject": "YOUR_PROJECT",
+    "repoName": "YOUR_REPO_NAME",
+    "mainBranch": "main",
+    "prUrlBase": ""
+  },
+  "engine": {
+    "tickInterval": 60000,
+    "maxConcurrent": 3,
+    "inboxConsolidateThreshold": 5,
+    "agentTimeout": 600000,
+    "maxTurns": 100,
+    "worktreeRoot": "../worktrees"
+  },
+  "claude": {
+    "binary": "claude",
+    "outputFormat": "json",
+    "allowedTools": "Edit,Write,Read,Bash,Glob,Grep,Agent,WebFetch,WebSearch"
+  },
+  "workSources": {
+    "prd": {
+      "enabled": true,
+      "path": "docs/prd-gaps.json",
+      "description": "PRD gap analysis — missing features become implement tasks",
+      "itemFilter": { "status": ["missing", "planned"] },
+      "cooldownMinutes": 30
+    },
+    "pullRequests": {
+      "enabled": true,
+      "path": ".squad/pull-requests.json",
+      "description": "PR tracker — pending PRs become review tasks, changes-requested become fix tasks",
+      "cooldownMinutes": 30
+    },
+    "workItems": {
+      "enabled": true,
+      "path": ".squad/work-items.json",
+      "description": "Manual work items queue — arbitrary tasks added by the coordinator",
+      "cooldownMinutes": 0
+    }
+  },
+  "agents": {
+    "ripley":  { "name": "Ripley",  "emoji": "🏗️",  "role": "Lead / Explorer", "skills": ["architecture", "codebase-exploration", "design-review"] },
+    "dallas":  { "name": "Dallas",  "emoji": "🔧",  "role": "Engineer", "skills": ["implementation", "typescript", "docker", "testing"] },
+    "lambert": { "name": "Lambert", "emoji": "📊",  "role": "Analyst", "skills": ["gap-analysis", "requirements", "documentation"] },
+    "rebecca": { "name": "Rebecca", "emoji": "🧠",  "role": "Architect", "skills": ["system-design", "api-design", "scalability", "implementation"] },
+    "ralph":   { "name": "Ralph",   "emoji": "⚙️",   "role": "Engineer", "skills": ["implementation", "bug-fixes", "testing", "scaffolding"] }
+  }
+}