@chuckssmith/agentloom 0.2.0

package/README.md

@@ -0,0 +1,100 @@
+# agentloom
+
+A workflow layer for Claude Code. Better routing, reusable roles, and multi-agent crew coordination — built natively on what Claude Code already provides.
+
+```bash
+npm install -g agentloom
+loom setup
+```
+
+---
+
+## What this is
+
+Claude Code is the execution engine. agentloom adds:
+- **`$grind`** — persistence loop that keeps working until a task is verified complete
+- **`$crew`** — parallel workers that decompose and execute simultaneously
+- **`$architect`** — deep analysis mode before major decisions
+- **`loom crew`** — CLI to spawn a crew of workers from your terminal
+
+It does not replace Claude Code. It wraps it.
+
+---
+
+## Quick start
+
+```bash
+npm install -g agentloom
+loom setup          # installs skills, validates deps
+
+# From your terminal:
+loom crew "audit every API endpoint for security issues"
+loom crew 2:explore+1:code-reviewer "review the payment flow"
+
+# Or from inside a Claude Code session:
+# $grind "port the auth module to the new interface"
+# $crew "analyze all three data pipeline stages in parallel"
+```
+
+---
+
+## Skills
+
+Install with `loom setup`. Then use inside any Claude Code session:
+
+| Skill | What it does |
+|---|---|
+| `$grind` | Persistence loop with mandatory verification gate |
+| `$crew` | Parallel workers — decomposes task, runs simultaneously, verifies |
+| `$architect` | Deep analysis — maps system, finds real problems, recommends approach |
+
+---
+
+## CLI
+
+```
+loom crew [N] "<task>"                  Spawn N general-purpose workers
+loom crew 3 "<task>"                    Spawn 3 workers
+loom crew 2:explore "<task>"            Spawn 2 Explore-type workers
+loom crew 2:explore+1:code-reviewer     Spawn typed crew
+loom status                             Show active session
+loom setup                              Install skills + validate
+```
+
+### Worker types
+
+Matches Claude Code's built-in subagent types:
+
+| Type | Best for |
+|---|---|
+| `explore` | Read-only research, codebase mapping |
+| `plan` | Architecture decisions, approach planning |
+| `code-reviewer` | Audits, security reviews, quality checks |
+| `frontend-developer` | UI and component work |
+| `general-purpose` | General implementation (default) |
+
+---
+
+## State directory
+
+```
+.agentloom/
+  tasks/          Task queue — workers claim atomically
+  workers/        Worker status and results
+  context/        Shared context snapshots
+  session.json    Active session metadata
+```
+
+---
+
+## Requirements
+
+- Node.js 20+
+- Claude Code CLI (`claude`)
+- tmux (optional — used for crew mode on Mac/Linux; falls back to background processes on WSL/Windows)
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { setup } from './commands/setup.js';
+import { crew } from './commands/crew.js';
+import { status } from './commands/status.js';
+const [, , command, ...args] = process.argv;
+const usage = `
+agentloom (loom) — workflow layer for Claude Code
+
+Usage:
+  loom setup                       Install skills and initialize state dir
+  loom crew [N] "<task>"           Spawn N parallel workers on a task
+  loom crew 2:explore "<task>"     Spawn typed workers (explore/plan/code-reviewer)
+  loom status                      Show active crew session
+
+Modes (use $grind or $crew inside a Claude Code session):
+  $grind   Persistence loop — keeps working until verified complete
+  $crew    Parallel workers — decompose and execute simultaneously
+
+Examples:
+  loom setup
+  loom crew "refactor the auth module"
+  loom crew 3 "audit every API endpoint for security issues"
+  loom crew 2:explore+1:code-reviewer "review the payment flow"
+`;
+switch (command) {
+    case 'setup':
+        await setup();
+        break;
+    case 'crew':
+        await crew(args);
+        break;
+    case 'status':
+        await status();
+        break;
+    default:
+        console.log(usage);
+        process.exit(command ? 1 : 0);
+}

package/dist/commands/crew.d.ts

@@ -0,0 +1 @@
+export declare function crew(args: string[]): Promise<void>;

package/dist/commands/crew.js

@@ -0,0 +1,103 @@
+import { execSync, spawn } from 'child_process';
+import { writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { parseWorkerSpec, initSession, writeContextSnapshot, decomposeTasks, } from '../team/orchestrator.js';
+import { STATE_DIR } from '../state/session.js';
+const hasTmux = () => {
+    try {
+        execSync('tmux -V', { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const isWSL = () => process.platform === 'linux' && !!process.env.WSL_DISTRO_NAME;
+export async function crew(args) {
+    if (args.length === 0) {
+        console.error('Usage: loom crew [N] "<task>"');
+        process.exit(1);
+    }
+    const { specs, task } = parseWorkerSpec(args);
+    const totalWorkers = specs.reduce((sum, s) => sum + s.count, 0);
+    const slug = task.slice(0, 30).toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
+    console.log(`\nagentloom crew`);
+    console.log(`Task:    ${task}`);
+    console.log(`Workers: ${totalWorkers}`);
+    console.log(`Mode:    ${hasTmux() && !isWSL() ? 'tmux' : 'background processes'}\n`);
+    const session = await initSession(task, totalWorkers);
+    const contextPath = await writeContextSnapshot(slug, task);
+    const tasks = await decomposeTasks(task, specs);
+    console.log(`Session: ${session.id}`);
+    console.log(`Tasks:   ${tasks.length} created`);
+    console.log(`Context: ${contextPath}\n`);
+    const workerPrompt = buildWorkerPrompt(task, contextPath, session.id);
+    if (hasTmux() && !isWSL()) {
+        await launchTmux(session.id, totalWorkers, specs, workerPrompt);
+    }
+    else {
+        await launchBackground(session.id, totalWorkers, specs, workerPrompt);
+    }
+    console.log(`\nWorkers launched. Monitor with: loom status`);
+    console.log(`State dir: ${STATE_DIR}/`);
+}
+function buildWorkerPrompt(task, contextPath, sessionId) {
+    return `You are a worker agent in an agentloom crew session (${sessionId}).
+
+Your job: help complete this task: "${task}"
+
+## Your protocol
+
+1. Read the shared context at: ${contextPath}
+2. Check ${STATE_DIR}/tasks/ for unclaimed work (files ending in -pending.json)
+3. Claim a task by reading it and noting the task ID
+4. Do the work thoroughly using all tools available to you
+5. Write your result back to ${STATE_DIR}/workers/
+6. Repeat until no pending tasks remain
+
+## Rules
+- Claim only one task at a time
+- Write your findings to the context file so other workers can see them
+- Do not stop until you have completed at least one task
+- If all tasks are claimed, do exploratory work relevant to the main task
+
+Begin now. Check for pending tasks and start working.`;
+}
+async function launchBackground(sessionId, count, specs, prompt) {
+    await mkdir(join(STATE_DIR, 'workers'), { recursive: true });
+    let workerIdx = 0;
+    for (const spec of specs) {
+        for (let i = 0; i < spec.count; i++) {
+            const workerId = `w${String(workerIdx).padStart(2, '0')}`;
+            workerIdx++;
+            const promptFile = join(STATE_DIR, 'workers', `${workerId}-prompt.md`);
+            await writeFile(promptFile, prompt);
+            const child = spawn('claude', ['--print', '--dangerously-skip-permissions', '-p', prompt], {
+                detached: true,
+                stdio: ['ignore', 'ignore', 'ignore'],
+                env: { ...process.env, AGENTLOOM_WORKER_ID: workerId, AGENTLOOM_SESSION: sessionId },
+            });
+            child.unref();
+            console.log(`  ✓ Worker ${workerId} (${spec.agentType}) launched [pid ${child.pid}]`);
+        }
+    }
+}
+async function launchTmux(sessionId, count, specs, prompt) {
+    const tmuxSession = `loom-${sessionId}`;
+    execSync(`tmux new-session -d -s ${tmuxSession} -x 220 -y 50`);
+    let workerIdx = 0;
+    for (const spec of specs) {
+        for (let i = 0; i < spec.count; i++) {
+            const workerId = `w${String(workerIdx).padStart(2, '0')}`;
+            workerIdx++;
+            if (workerIdx > 1) {
+                execSync(`tmux split-window -h -t ${tmuxSession}`);
+                execSync(`tmux select-layout -t ${tmuxSession} tiled`);
+            }
+            const cmd = `AGENTLOOM_WORKER_ID=${workerId} AGENTLOOM_SESSION=${sessionId} claude --print --dangerously-skip-permissions -p '${prompt.replace(/'/g, "'\"'\"'")}'; echo '[worker done]'; read`;
+            execSync(`tmux send-keys -t ${tmuxSession} "${cmd}" Enter`);
+            console.log(`  ✓ Worker ${workerId} (${spec.agentType}) launched in tmux pane`);
+        }
+    }
+    execSync(`tmux attach-session -t ${tmuxSession}`);
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1 @@
+export declare function setup(): Promise<void>;

package/dist/commands/setup.js

@@ -0,0 +1,40 @@
+import { mkdir, copyFile, readdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_SRC = join(__dirname, '../../skills');
+const SKILLS_DEST = join(homedir(), '.claude', 'skills');
+export async function setup() {
+    console.log('agentloom setup\n');
+    // 1. Validate claude CLI exists
+    const { execSync } = await import('child_process');
+    try {
+        execSync('claude --version', { stdio: 'ignore' });
+        console.log('✓ claude CLI found');
+    }
+    catch {
+        console.error('✗ claude CLI not found — install Claude Code first');
+        process.exit(1);
+    }
+    // 2. Install skills
+    await mkdir(SKILLS_DEST, { recursive: true });
+    const skills = await readdir(SKILLS_SRC);
+    for (const skill of skills.filter(f => f.endsWith('.md'))) {
+        const dest = join(SKILLS_DEST, skill);
+        await copyFile(join(SKILLS_SRC, skill), dest);
+        console.log(`✓ skill installed: ${skill}`);
+    }
+    // 3. Check tmux (optional)
+    try {
+        execSync('tmux -V', { stdio: 'ignore' });
+        console.log('✓ tmux found — crew mode will use split panes');
+    }
+    catch {
+        console.log('~ tmux not found — crew mode will use background processes');
+    }
+    console.log('\nSetup complete.');
+    console.log('\nGet started:');
+    console.log('  loom crew "your task here"');
+    console.log('  or use $grind / $crew inside a Claude Code session');
+}

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function status(): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,34 @@
+import { readSession, readTasks, readWorkers } from '../state/session.js';
+import { existsSync } from 'fs';
+import { STATE_DIR } from '../state/session.js';
+export async function status() {
+    if (!existsSync(STATE_DIR)) {
+        console.log('No active session. Run: loom crew "<task>"');
+        return;
+    }
+    const session = await readSession();
+    if (!session) {
+        console.log('No session found.');
+        return;
+    }
+    const tasks = await readTasks();
+    const workers = await readWorkers();
+    const pending = tasks.filter(t => t.status === 'pending').length;
+    const claimed = tasks.filter(t => t.status === 'claimed').length;
+    const done = tasks.filter(t => t.status === 'done').length;
+    const failed = tasks.filter(t => t.status === 'failed').length;
+    console.log(`\nSession: ${session.id}`);
+    console.log(`Status:  ${session.status}`);
+    console.log(`Task:    ${session.description}`);
+    console.log(`Started: ${session.createdAt}`);
+    console.log(`\nTasks:   ${pending} pending  ${claimed} active  ${done} done  ${failed} failed`);
+    console.log(`Workers: ${workers.length} (${session.workerCount} total)`);
+    if (workers.length > 0) {
+        console.log('\nWorker status:');
+        for (const w of workers) {
+            const task = w.currentTaskId ? tasks.find(t => t.id === w.currentTaskId) : null;
+            const desc = task ? `  → ${task.description.slice(0, 60)}` : '';
+            console.log(`  [${w.id}] ${w.status}${desc}`);
+        }
+    }
+}

package/dist/state/session.d.ts

@@ -0,0 +1,39 @@
+export declare const STATE_DIR = ".claude-team";
+export type TaskStatus = 'pending' | 'claimed' | 'done' | 'failed';
+export type Task = {
+    id: string;
+    description: string;
+    agentType?: string;
+    status: TaskStatus;
+    workerId?: string;
+    result?: string;
+    error?: string;
+    createdAt: string;
+    claimedAt?: string;
+    completedAt?: string;
+};
+export type Worker = {
+    id: string;
+    agentType: string;
+    status: 'idle' | 'working' | 'done';
+    currentTaskId?: string;
+    startedAt: string;
+    completedAt?: string;
+};
+export type Session = {
+    id: string;
+    description: string;
+    status: 'running' | 'verifying' | 'done' | 'failed';
+    workerCount: number;
+    createdAt: string;
+    completedAt?: string;
+    verificationResult?: 'pass' | 'fail';
+    verificationNotes?: string;
+};
+export declare function ensureStateDir(): Promise<void>;
+export declare function writeSession(session: Session): Promise<void>;
+export declare function readSession(): Promise<Session | null>;
+export declare function writeTask(task: Task): Promise<void>;
+export declare function writeWorker(worker: Worker): Promise<void>;
+export declare function readWorkers(): Promise<Worker[]>;
+export declare function readTasks(): Promise<Task[]>;

package/dist/state/session.js

@@ -0,0 +1,40 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+export const STATE_DIR = '.claude-team';
+export async function ensureStateDir() {
+    await mkdir(join(STATE_DIR, 'tasks'), { recursive: true });
+    await mkdir(join(STATE_DIR, 'workers'), { recursive: true });
+    await mkdir(join(STATE_DIR, 'context'), { recursive: true });
+}
+export async function writeSession(session) {
+    await writeFile(join(STATE_DIR, 'session.json'), JSON.stringify(session, null, 2));
+}
+export async function readSession() {
+    const path = join(STATE_DIR, 'session.json');
+    if (!existsSync(path))
+        return null;
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+export async function writeTask(task) {
+    await writeFile(join(STATE_DIR, 'tasks', `${task.id}-${task.status}.json`), JSON.stringify(task, null, 2));
+}
+export async function writeWorker(worker) {
+    await writeFile(join(STATE_DIR, 'workers', `${worker.id}.json`), JSON.stringify(worker, null, 2));
+}
+export async function readWorkers() {
+    const { readdir } = await import('fs/promises');
+    const dir = join(STATE_DIR, 'workers');
+    if (!existsSync(dir))
+        return [];
+    const files = await readdir(dir);
+    return Promise.all(files.filter(f => f.endsWith('.json')).map(async (f) => JSON.parse(await readFile(join(dir, f), 'utf8'))));
+}
+export async function readTasks() {
+    const { readdir } = await import('fs/promises');
+    const dir = join(STATE_DIR, 'tasks');
+    if (!existsSync(dir))
+        return [];
+    const files = await readdir(dir);
+    return Promise.all(files.filter(f => f.endsWith('.json')).map(async (f) => JSON.parse(await readFile(join(dir, f), 'utf8'))));
+}

package/dist/team/orchestrator.d.ts

@@ -0,0 +1,12 @@
+import { type Task, type Session } from '../state/session.js';
+export type WorkerSpec = {
+    count: number;
+    agentType: string;
+};
+export declare function parseWorkerSpec(args: string[]): {
+    specs: WorkerSpec[];
+    task: string;
+};
+export declare function initSession(description: string, workerCount: number): Promise<Session>;
+export declare function writeContextSnapshot(slug: string, task: string): Promise<string>;
+export declare function decomposeTasks(task: string, specs: WorkerSpec[]): Promise<Task[]>;

package/dist/team/orchestrator.js

@@ -0,0 +1,101 @@
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { execSync } from 'child_process';
+import { STATE_DIR, ensureStateDir, writeSession, writeTask } from '../state/session.js';
+export function parseWorkerSpec(args) {
+    // Formats:
+    //   omc team "task description"
+    //   omc team 3 "task description"
+    //   omc team 2:explore "task description"
+    //   omc team 2:explore+1:code-reviewer "task description"
+    const task = args[args.length - 1] ?? '';
+    const specArg = args.length > 1 ? args[0] ?? '' : '';
+    if (!specArg) {
+        return { specs: [{ count: 2, agentType: 'general-purpose' }], task };
+    }
+    // Plain number: "3"
+    if (/^\d+$/.test(specArg)) {
+        return { specs: [{ count: parseInt(specArg), agentType: 'general-purpose' }], task };
+    }
+    // Typed specs: "2:explore+1:code-reviewer"
+    const parts = specArg.split('+');
+    const specs = parts.map(part => {
+        const [countStr, agentType] = part.split(':');
+        return {
+            count: parseInt(countStr ?? '1'),
+            agentType: agentType ?? 'general-purpose',
+        };
+    });
+    return { specs, task };
+}
+export async function initSession(description, workerCount) {
+    await ensureStateDir();
+    const session = {
+        id: randomUUID().slice(0, 8),
+        description,
+        status: 'running',
+        workerCount,
+        createdAt: new Date().toISOString(),
+    };
+    await writeSession(session);
+    return session;
+}
+export async function writeContextSnapshot(slug, task) {
+    const path = join(STATE_DIR, 'context', `${slug}.md`);
+    const content = `# Task Context\n\n**Task:** ${task}\n\n**Started:** ${new Date().toISOString()}\n\n## Notes\n\n_Workers will append findings here._\n`;
+    await writeFile(path, content);
+    return path;
+}
+export async function decomposeTasks(task, specs) {
+    const totalWorkers = specs.reduce((sum, s) => sum + s.count, 0);
+    const subtasks = await callClaudeDecompose(task, totalWorkers);
+    const tasks = [];
+    let idx = 0;
+    for (const spec of specs) {
+        for (let i = 0; i < spec.count; i++) {
+            const t = {
+                id: randomUUID().slice(0, 8),
+                description: subtasks[idx] ?? task,
+                agentType: spec.agentType,
+                status: 'pending',
+                createdAt: new Date().toISOString(),
+            };
+            tasks.push(t);
+            await writeTask(t);
+            idx++;
+        }
+    }
+    return tasks;
+}
+function callClaudeDecompose(task, n) {
+    if (n <= 1)
+        return [task];
+    const prompt = `Decompose this task into exactly ${n} independent subtasks that can run in parallel. Each must be specific and actionable. Respond with a JSON array of ${n} strings — no explanation, no markdown, just the array.
+
+Task: "${task}"`;
+    try {
+        const escaped = prompt.replace(/'/g, `'"'"'`);
+        const raw = execSync(`claude --print -p '${escaped}'`, {
+            encoding: 'utf8',
+            timeout: 30_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        // Extract JSON array from the response (strip any surrounding prose)
+        const match = raw.match(/\[[\s\S]*\]/);
+        if (!match)
+            throw new Error('No JSON array in response');
+        const parsed = JSON.parse(match[0]);
+        if (!Array.isArray(parsed) || parsed.length === 0)
+            throw new Error('Empty array');
+        const subtasks = parsed.map(String);
+        // Pad or trim to exactly n
+        while (subtasks.length < n)
+            subtasks.push(task);
+        return subtasks.slice(0, n);
+    }
+    catch {
+        // Fallback: every worker gets the same task description
+        return Array(n).fill(task);
+    }
+}

package/dist/team/queue.d.ts

@@ -0,0 +1,6 @@
+import { type Task } from '../state/session.js';
+export declare function claimTask(workerId: string): Promise<Task | null>;
+export declare function completeTask(task: Task, result: string): Promise<void>;
+export declare function failTask(task: Task, error: string): Promise<void>;
+export declare function pendingCount(): Promise<number>;
+export declare function allDone(): Promise<boolean>;

package/dist/team/queue.js

@@ -0,0 +1,62 @@
+import { readdir, readFile, rename, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { STATE_DIR } from '../state/session.js';
+const TASKS_DIR = join(STATE_DIR, 'tasks');
+export async function claimTask(workerId) {
+    if (!existsSync(TASKS_DIR))
+        return null;
+    const files = await readdir(TASKS_DIR);
+    const pending = files.filter(f => f.endsWith('-pending.json'));
+    for (const file of pending) {
+        const oldPath = join(TASKS_DIR, file);
+        const task = JSON.parse(await readFile(oldPath, 'utf8'));
+        const newFile = file.replace('-pending.json', `-claimed-${workerId}.json`);
+        const newPath = join(TASKS_DIR, newFile);
+        // Atomic rename = claim. First writer wins.
+        try {
+            await rename(oldPath, newPath);
+            task.status = 'claimed';
+            task.workerId = workerId;
+            task.claimedAt = new Date().toISOString();
+            await writeFile(newPath, JSON.stringify(task, null, 2));
+            return task;
+        }
+        catch {
+            // Another worker claimed it first — try next
+            continue;
+        }
+    }
+    return null;
+}
+export async function completeTask(task, result) {
+    const claimedFile = join(TASKS_DIR, `${task.id}-claimed-${task.workerId}.json`);
+    const doneFile = join(TASKS_DIR, `${task.id}-done-${task.workerId}.json`);
+    task.status = 'done';
+    task.result = result;
+    task.completedAt = new Date().toISOString();
+    await writeFile(claimedFile, JSON.stringify(task, null, 2));
+    await rename(claimedFile, doneFile);
+}
+export async function failTask(task, error) {
+    const claimedFile = join(TASKS_DIR, `${task.id}-claimed-${task.workerId}.json`);
+    const failedFile = join(TASKS_DIR, `${task.id}-failed-${task.workerId}.json`);
+    task.status = 'failed';
+    task.error = error;
+    task.completedAt = new Date().toISOString();
+    await writeFile(claimedFile, JSON.stringify(task, null, 2));
+    await rename(claimedFile, failedFile);
+}
+export async function pendingCount() {
+    if (!existsSync(TASKS_DIR))
+        return 0;
+    const files = await readdir(TASKS_DIR);
+    return files.filter(f => f.includes('-pending.json')).length;
+}
+export async function allDone() {
+    if (!existsSync(TASKS_DIR))
+        return true;
+    const files = await readdir(TASKS_DIR);
+    const active = files.filter(f => f.includes('-pending.json') || f.includes('-claimed-'));
+    return active.length === 0;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@chuckssmith/agentloom",
+  "version": "0.2.0",
+  "description": "A workflow layer for Claude Code — reusable roles, persistence loops, and multi-agent crew coordination",
+  "keywords": [
+    "ai",
+    "agent",
+    "workflow",
+    "multi-agent"
+  ],
+  "homepage": "https://github.com/cssmith615/agentloom",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cssmith615/agentloom.git"
+  },
+  "license": "MIT",
+  "author": "cssmith615",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "bin": {
+    "loom": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/skills/architect.md

@@ -0,0 +1,53 @@
+---
+name: architect
+description: Deep analysis and architecture review. Use before major implementation decisions or to audit existing systems. Returns a structured assessment with specific recommendations.
+---
+
+# $architect — Deep Analysis
+
+You are now in **architect mode**. You will analyze deeply, not implement.
+
+## Your job
+Produce a structured architectural assessment. Be specific, cite file paths and line numbers, identify actual problems — not hypothetical ones.
+
+## Process
+
+### Step 1 — Explore (parallel)
+Spawn `Explore` subagents in parallel to map the relevant systems simultaneously.
+Use `run_in_background: true`.
+
+### Step 2 — Synthesize
+From the exploration results, identify:
+- What exists and how it works
+- Boundaries and contracts between components
+- Actual problems (with evidence)
+- Risks (specific, not generic)
+- Recommended approach with tradeoffs
+
+### Step 3 — Deliver
+Return a structured report:
+
+```
+## System map
+[What exists, how it's connected]
+
+## Findings
+[Numbered list, each with: what, where (file:line), why it matters]
+
+## Recommendation
+[Specific approach, not "consider refactoring"]
+
+## Risks
+[What could go wrong with the recommendation]
+
+## Open questions
+[What you'd need to know before proceeding]
+```
+
+## Rules
+- Cite specific files and line numbers for every finding
+- Do not recommend changes you haven't verified are needed
+- "Consider refactoring" is not a recommendation — say what to refactor and why
+- If the system is fine, say so
+
+Begin analysis now.

package/skills/crew.md

@@ -0,0 +1,56 @@
+---
+name: crew
+description: Spawn parallel workers on a task. Decomposes the work, runs workers simultaneously, then runs a verification pass. Use when the task is clearly decomposable into independent streams.
+---
+
+# $crew — Parallel Workers
+
+You are now in **crew mode**. You will decompose this task, run workers in parallel, and verify the result.
+
+## When to use
+- Task has clearly independent work streams (e.g. audit 5 modules, port 3 subsystems)
+- Work would benefit from simultaneous execution
+- You want one worker per concern (explore / implement / verify)
+
+## When NOT to use
+- Task must be done sequentially (each step depends on the last) — use `$grind` instead
+- Task is a quick single fix — just do it directly
+
+## Execution rules
+- Decompose into **truly independent** subtasks only
+- Default crew: 1 `Explore` + 1 `general-purpose` + 1 `code-reviewer`
+- For large tasks: up to 4 workers; beyond that, coordination cost exceeds benefit
+- Use `run_in_background: true` for all worker spawns
+- Collect all results before running the verification pass
+
+## Crew structure
+
+### Step 1 — Decompose
+Break the task into N independent subtasks. Write them to `.agentloom/tasks/`.
+
+For each subtask, decide the right agent type:
+- `Explore` — research, read files, understand structure (read-only)
+- `Plan` — architecture decisions, approach planning
+- `general-purpose` — implementation work
+- `code-reviewer` — audit, security review, quality check
+- `frontend-developer` — UI/component work
+
+### Step 2 — Launch crew (parallel)
+Spawn all workers simultaneously with `run_in_background: true`.
+Each worker gets: the subtask description + the shared context path.
+
+### Step 3 — Collect results
+Wait for all background workers to complete.
+Read each result from `.agentloom/workers/`.
+
+### Step 4 — Verify
+Spawn a `code-reviewer` subagent across all completed work.
+Return PASS or FAIL with evidence.
+
+### Step 5 — Report
+Summarize what each worker did and the final verification result.
+
+## Completion contract
+Same as `$grind` — only done when verification passes with evidence.
+
+Begin now. Decompose the task, then launch the crew.

package/skills/grind.md

@@ -0,0 +1,53 @@
+---
+name: grind
+description: Persistence loop — keeps working on a task until it is fully complete and verified. Use when you need guaranteed completion, not "do your best".
+---
+
+# $grind — Persistence Loop
+
+You are now in **grind mode**. You will not stop until this task is genuinely complete and passes verification.
+
+## When to use
+- Task requires guaranteed completion with verification
+- Multi-step work that may span many iterations
+- User says "don't stop", "keep going", "finish this", "must work"
+
+## Execution rules
+- Fire independent sub-agent calls **simultaneously** using `run_in_background: true`
+- Use the `Explore` subagent type for research/read-only work
+- Use the `Plan` subagent type before major implementation decisions
+- Use the `code-reviewer` subagent type for verification
+- Do NOT declare done until verification passes
+- Do NOT reduce scope to make the task easier
+- Do NOT delete or skip tests to make them pass
+
+## Loop structure
+
+### Step 0 — Context snapshot
+Before starting, write a context file to `.agentloom/context/{task-slug}.md` with:
+- Task statement
+- Desired outcome
+- Known facts
+- Constraints
+- Unknowns
+
+### Step 1 — Plan
+Spawn a `Plan` subagent to map the implementation approach. Save the plan.
+
+### Step 2 — Execute (parallel)
+Spawn parallel subagents for independent work streams. Use `run_in_background: true`.
+
+### Step 3 — Verify
+Spawn a `code-reviewer` subagent with this prompt:
+> "Review the completed work. Run all tests. Check that the original task requirements are met. Return PASS or FAIL with specific evidence."
+
+### Step 4 — Iterate or complete
+- **PASS** → report completion with evidence
+- **FAIL** → go back to Step 2 with the reviewer's specific findings
+
+## Completion contract
+You may only declare this task done when:
+1. A `code-reviewer` subagent has returned PASS
+2. You can cite specific evidence (test output, file paths, behavior observed)
+
+Begin now. State the task, write the context snapshot, then start the loop.