squadfoundry 0.1.0

package/dist/tests/unit/state-machine.test.js

@@ -0,0 +1,133 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createStateMachine } from '../../orchestrator/core/state-machine.js';
+function makeJob(status) {
+    return {
+        id: 'test-job',
+        squadId: 'test-squad',
+        status,
+        objective: 'test',
+        initialInput: 'test input',
+        loadedContext: {
+            docs: [],
+            specs: [],
+            playbooks: [],
+            policies: [],
+            templates: [],
+            custom: [],
+        },
+        artifacts: [],
+        approvals: [],
+        currentStepId: null,
+        currentAgentId: null,
+        history: [],
+        startedAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+}
+describe('StateMachine', () => {
+    let sm;
+    beforeEach(() => {
+        sm = createStateMachine();
+    });
+    it('transitions from INTAKE_PENDING to CONTEXT_LOADING', () => {
+        const job = makeJob('INTAKE_PENDING');
+        const result = sm.transition(job, 'START_CONTEXT_LOADING');
+        expect(result.success).toBe(true);
+        expect(result.newStatus).toBe('CONTEXT_LOADING');
+    });
+    it('transitions from CONTEXT_LOADING to JOB_CREATED', () => {
+        const job = makeJob('CONTEXT_LOADING');
+        const result = sm.transition(job, 'CREATE_JOB');
+        expect(result.success).toBe(true);
+        expect(result.newStatus).toBe('JOB_CREATED');
+    });
+    it('transitions from JOB_CREATED to READY_FOR_EXECUTION', () => {
+        const job = makeJob('JOB_CREATED');
+        const result = sm.transition(job, 'MARK_READY');
+        expect(result.success).toBe(true);
+        expect(result.newStatus).toBe('READY_FOR_EXECUTION');
+    });
+    it('transitions from READY_FOR_EXECUTION to RUNNING_STEP', () => {
+        const job = makeJob('READY_FOR_EXECUTION');
+        const result = sm.transition(job, 'START_STEP');
+        expect(result.success).toBe(true);
+        expect(result.newStatus).toBe('RUNNING_STEP');
+    });
+    it('transitions from RUNNING_STEP to WAITING_APPROVAL', () => {
+        const job = makeJob('RUNNING_STEP');
+        const result = sm.transition(job, 'STEP_NEEDS_APPROVAL');
+        expect(result.success).toBe(true);
+        expect(result.newStatus).toBe('WAITING_APPROVAL');
+    });
+    it('transitions from WAITING_APPROVAL to READY_FOR_EXECUTION on grant', () => {
+        const job = makeJob('WAITING_APPROVAL');
+        const result = sm.transition(job, 'APPROVAL_GRANTED');
+        expect(result.success).toBe(true);
+        expect(result.newStatus).toBe('READY_FOR_EXECUTION');
+    });
+    it('transitions from WAITING_APPROVAL to BLOCKED on rejection', () => {
+        const job = makeJob('WAITING_APPROVAL');
+        const result = sm.transition(job, 'APPROVAL_REJECTED');
+        expect(result.success).toBe(true);
+        expect(result.newStatus).toBe('BLOCKED');
+    });
+    it('rejects invalid transitions', () => {
+        const job = makeJob('COMPLETED');
+        const result = sm.transition(job, 'START_STEP');
+        expect(result.success).toBe(false);
+        expect(result.reason).toBeDefined();
+    });
+    it('blocks via guard function', () => {
+        sm.registerTransition({
+            from: 'READY_FOR_EXECUTION',
+            event: 'CUSTOM_GUARDED_START',
+            to: 'RUNNING_STEP',
+            guard: () => ({ allowed: false, reason: 'Guard blocked' }),
+            description: 'Guarded start',
+        });
+        const job = makeJob('READY_FOR_EXECUTION');
+        const result = sm.transition(job, 'CUSTOM_GUARDED_START');
+        expect(result.success).toBe(false);
+        expect(result.reason).toBe('Guard blocked');
+    });
+    it('identifies terminal states correctly', () => {
+        expect(sm.isTerminal('COMPLETED')).toBe(true);
+        expect(sm.isTerminal('FAILED')).toBe(true);
+        expect(sm.isTerminal('RUNNING_STEP')).toBe(false);
+        expect(sm.isTerminal('WAITING_APPROVAL')).toBe(false);
+    });
+    it('lists valid events from a given status', () => {
+        const events = sm.validEventsFrom('READY_FOR_EXECUTION');
+        expect(events).toContain('START_STEP');
+        expect(events).toContain('COMPLETE');
+    });
+    it('allows registering and using custom transitions', () => {
+        sm.registerTransition({
+            from: 'RUNNING_STEP',
+            event: 'CUSTOM_EVENT',
+            to: 'BLOCKED',
+            description: 'Custom squad-specific transition',
+        });
+        const job = makeJob('RUNNING_STEP');
+        const result = sm.transition(job, 'CUSTOM_EVENT');
+        expect(result.success).toBe(true);
+        expect(result.newStatus).toBe('BLOCKED');
+    });
+    it('transitions through a full happy path', () => {
+        const states = [
+            ['INTAKE_PENDING', 'START_CONTEXT_LOADING', 'CONTEXT_LOADING'],
+            ['CONTEXT_LOADING', 'CREATE_JOB', 'JOB_CREATED'],
+            ['JOB_CREATED', 'MARK_READY', 'READY_FOR_EXECUTION'],
+            ['READY_FOR_EXECUTION', 'START_STEP', 'RUNNING_STEP'],
+            ['RUNNING_STEP', 'STEP_COMPLETE', 'READY_FOR_EXECUTION'],
+            ['READY_FOR_EXECUTION', 'COMPLETE', 'COMPLETED'],
+        ];
+        for (const [from, event, expectedTo] of states) {
+            const job = makeJob(from);
+            const result = sm.transition(job, event);
+            expect(result.success, `Expected ${from} + ${event} → ${expectedTo}`).toBe(true);
+            expect(result.newStatus).toBe(expectedTo);
+        }
+    });
+});
+//# sourceMappingURL=state-machine.test.js.map

package/dist/tests/unit/state-machine.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.test.js","sourceRoot":"","sources":["../../../tests/unit/state-machine.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACzD,OAAO,EAAE,kBAAkB,EAAgB,MAAM,0CAA0C,CAAA;AAG3F,SAAS,OAAO,CAAC,MAA+B;IAC9C,OAAO;QACL,EAAE,EAAE,UAAU;QACd,OAAO,EAAE,YAAY;QACrB,MAAM;QACN,SAAS,EAAE,MAAM;QACjB,YAAY,EAAE,YAAY;QAC1B,aAAa,EAAE;YACb,IAAI,EAAE,EAAE;YACR,KAAK,EAAE,EAAE;YACT,SAAS,EAAE,EAAE;YACb,QAAQ,EAAE,EAAE;YACZ,SAAS,EAAE,EAAE;YACb,MAAM,EAAE,EAAE;SACX;QACD,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,EAAE;QACb,aAAa,EAAE,IAAI;QACnB,cAAc,EAAE,IAAI;QACpB,OAAO,EAAE,EAAE;QACX,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAA;AACH,CAAC;AAED,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,IAAI,EAAgB,CAAA;IAEpB,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,GAAG,kBAAkB,EAAE,CAAA;IAC3B,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,GAAG,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;QACrC,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAA;QAC1D,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;IAClD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;QACtC,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;QAC/C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IAC9C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;QAClC,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;QAC/C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IACtD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;QAC1C,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;QAC/C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;QACnC,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAA;QACxD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAA;IACnD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,MAAM,GAAG,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;QACvC,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAA;QACrD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IACtD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,GAAG,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;QACvC,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAA;QACtD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;QAChC,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;QAC/C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,EAAE,CAAC,kBAAkB,CAAC;YACpB,IAAI,EAAE,qBAAqB;YAC3B,KAAK,EAAE,sBAAsB;YAC7B,EAAE,EAAE,cAAc;YAClB,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;YAC1D,WAAW,EAAE,eAAe;SAC7B,CAAC,CAAA;QACF,MAAM,GAAG,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;QAC1C,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAA;QACzD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IAC7C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7C,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC1C,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACjD,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,MAAM,GAAG,EAAE,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAA;QACxD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAA;QACtC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAA;IACtC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,EAAE,CAAC,kBAAkB,CAAC;YACpB,IAAI,EAAE,cAAc;YACpB,KAAK,EAAE,cAAc;YACrB,EAAE,EAAE,SAAS;YACb,WAAW,EAAE,kCAAkC;SAChD,CAAC,CAAA;QACF,MAAM,GAAG,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;QACnC,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,cAAc,CAAC,CAAA;QACjD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,MAAM,GAAG;YACb,CAAC,gBAAgB,EAAE,uBAAuB,EAAE,iBAAiB,CAAC;YAC9D,CAAC,iBAAiB,EAAE,YAAY,EAAE,aAAa,CAAC;YAChD,CAAC,aAAa,EAAE,YAAY,EAAE,qBAAqB,CAAC;YACpD,CAAC,qBAAqB,EAAE,YAAY,EAAE,cAAc,CAAC;YACrD,CAAC,cAAc,EAAE,eAAe,EAAE,qBAAqB,CAAC;YACxD,CAAC,qBAAqB,EAAE,UAAU,EAAE,WAAW,CAAC;SACxC,CAAA;QAEV,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,EAAE,CAAC;YAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,IAA+B,CAAC,CAAA;YACpD,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACxC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,IAAI,MAAM,KAAK,MAAM,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAChF,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/docs/architecture/overview.md

@@ -0,0 +1,115 @@
+# Architecture Overview
+
+Squad Foundry is built around five core principles:
+
+1. **Core never imports adapters** — dependency inversion always
+2. **State machine is explicit** — every transition is declared, no implicit changes
+3. **All artifacts are human-readable** — JSON + Markdown, inspectable without tooling
+4. **Squad = portable config** — reusable across hosts, models, and environments
+5. **Guardrails are first-class** — enforced programmatically, not just in prompts
+
+## Layers
+
+```
+┌─────────────────────────────────────────────┐
+│               CLI / Host Interface          │
+├─────────────────────────────────────────────┤
+│          Squad Builder | Squad Runtime      │
+├────────────────────────┬────────────────────┤
+│     Context Layer      │   Artifact Store   │
+├────────────────────────┴────────────────────┤
+│               Core Layer                    │
+│  (types, state machine, guardrails)         │
+├─────────────────────────────────────────────┤
+│             Adapter Layer                   │
+│  host | model | tools | vcs | publishing   │
+│  deploy | context                           │
+└─────────────────────────────────────────────┘
+```
+
+## Core Layer (`orchestrator/core/`)
+
+Pure TypeScript, zero external runtime dependencies. Contains:
+- **`types.ts`** — All portable interfaces and type definitions
+- **`state-machine.ts`** — Explicit state machine with guard functions
+- **`guardrails.ts`** — Policy constraint evaluator
+
+The core never imports from adapters. All coupling flows upward.
+
+## Adapter Layer (`orchestrator/adapters/`)
+
+Pluggable implementations for every external system:
+
+| Interface | Purpose |
+|-----------|---------|
+| `IHostAdapter` | LLM execution runtime (Anthropic, OpenAI, local) |
+| `IModelAdapter` | AI model provider selection |
+| `IToolAdapter` | Tool/integration invocation |
+| `IVCSAdapter` | Git operations and PRs |
+| `ISocialMediaAdapter` | Social media publishing |
+| `IDeployAdapter` | Deployment operations |
+| `IContextAdapter` | Context file discovery and loading |
+
+All adapters implement a clear interface. Swap implementations without touching core logic.
+
+## Context Layer (`orchestrator/context/`)
+
+Discovers and loads project documentation:
+- `context-loader.ts` — Orchestrates discovery + loading via `IContextAdapter`
+- `context-index.ts` — In-memory search index over loaded files
+
+Priority order: PROJECT.md > TASKS.md > AGENTS.md > README.md > docs/** > specs/** > ...
+
+## Artifact Store (`orchestrator/artifacts/`)
+
+Filesystem-based persistence for all job data:
+```
+artifacts/<squad_id>/<job_id>/
+  state.json       — full job state
+  handoffs.json    — agent handoff records
+  events.json      — history entries
+  approvals.json   — approval records
+  outputs/         — agent-produced artifacts
+  reports/         — human-readable reports
+```
+
+## Squad Builder (`orchestrator/builder/`)
+
+Interview-driven squad generation:
+1. `interview-questions.ts` — Question bank organized by topic
+2. `domain-classifier.ts` — Maps answers to SquadDomain
+3. `squad-generator.ts` — Generates SquadDefinition + files
+4. `squad-builder.ts` — Orchestrates the interview process
+
+## Squad Runtime (`orchestrator/runtime/`)
+
+Execution engine:
+1. `job-manager.ts` — Job creation, state updates, history
+2. `agent-dispatcher.ts` — Step → agent resolution + prompt building
+3. `handoff-manager.ts` — Records and validates handoffs
+4. `approval-gate.ts` — Human-in-the-loop pause/resume
+5. `squad-runtime.ts` — Main coordinator
+
+## Data Flow
+
+```
+User input
+  ↓ SquadBuilder (interview)
+  ↓ DomainClassifier
+  ↓ SquadGenerator → squad.json files written to disk
+  ↓
+SquadRuntime.startJob()
+  ↓ ContextLoader.load() → LoadedContext
+  ↓ JobManager.create() → JobDefinition (persisted)
+  ↓ StateMachine.transition('MARK_READY')
+  ↓
+Loop: SquadRuntime.executeStep()
+  ↓ GuardrailEngine.evaluateAll() → block or pass
+  ↓ ApprovalGate.isPending() → wait or continue
+  ↓ AgentDispatcher.plan() → prompt
+  ↓ IHostAdapter.sendPrompt() → AgentResponse
+  ↓ ArtifactStore.persistArtifact() → ArtifactRef
+  ↓ HandoffManager.record() → HandoffEvent
+  ↓ StateMachine.transition('STEP_COMPLETE')
+  ↓ next step or COMPLETE
+```

package/docs/development/adding-agents.md

@@ -0,0 +1,75 @@
+# Adding New Agents
+
+Agents are defined in `config/squad.json` — no code changes required.
+
+## Step 1: Define the Agent
+
+Add to `agents[]` in `squads/<squad_id>/config/squad.json`:
+
+```json
+{
+  "id": "my-new-agent",
+  "name": "My New Agent",
+  "role": "Specific Role",
+  "domain": "software-development",
+  "objective": "What this agent achieves",
+  "instructions": "You are the My New Agent. [Full instructions here...]",
+  "inputs": [
+    { "name": "input_name", "description": "What comes in", "required": true }
+  ],
+  "outputs": [
+    { "name": "output_name", "description": "What goes out", "required": true, "format": "markdown" }
+  ],
+  "allowedTools": ["filesystem", "git"],
+  "constraints": ["Do not do X", "Always do Y"],
+  "successCriteria": ["Output produced"],
+  "failureCriteria": ["Cannot produce output"],
+  "allowedStates": ["READY_FOR_EXECUTION", "RUNNING_STEP"],
+  "blockingConditions": [],
+  "handoffRules": [
+    {
+      "condition": "step_completed",
+      "targetAgentId": "next-agent-id",
+      "description": "Pass to next agent",
+      "requiresApproval": false
+    }
+  ],
+  "responseFormat": "markdown"
+}
+```
+
+## Step 2: Add a Workflow Step
+
+Add to `workflow.steps[]`:
+
+```json
+{
+  "id": "step-my-new-agent",
+  "name": "My New Step",
+  "agentId": "my-new-agent",
+  "description": "What this step does",
+  "dependsOn": ["step-previous"],
+  "guardrails": [],
+  "requiresApprovalBefore": false,
+  "requiresApprovalAfter": false,
+  "requiredArtifacts": ["previous-output"],
+  "producedArtifacts": ["my-output"],
+  "nextStepId": "step-next"
+}
+```
+
+## Step 3: Update the Previous Step
+
+Point its `nextStepId` to your new step.
+
+## Step 4: Document
+
+Update `squads/<squad_id>/AGENTS.md` and `WORKFLOW.md`.
+
+## Agent Instructions Best Practices
+
+1. **Start with identity**: "You are the [Role]. [What you do]."
+2. **Be explicit about inputs**: "Given [X] and [Y], ..."
+3. **Specify outputs precisely**: "Produce [Z] as [format]."
+4. **List constraints**: "Do NOT [X]. ALWAYS [Y]."
+5. **Define handoff signal**: "When complete, signal: [condition]."

package/docs/development/adding-hosts.md

@@ -0,0 +1,104 @@
+# Adding a New Host Runtime Adapter
+
+A "host" is the execution environment that runs the LLM.
+
+## Step 1: Implement `IHostAdapter`
+
+Create `orchestrator/adapters/host/myhost.adapter.ts`:
+
+```typescript
+import type {
+  IHostAdapter,
+  PromptOptions,
+  HostCapabilities,
+  HostDetectionContext,
+  HostDetectionResult,
+  InterviewTurnInput,
+  InterviewTurnState,
+  InterviewTurnResult,
+} from './IHostAdapter.js'
+import type { AgentDefinition, AgentResponse, JobDefinition, WorkflowStep } from '../../core/types.js'
+
+export class MyHostAdapter implements IHostAdapter {
+  readonly id = 'myhost'
+  readonly name = 'My Host'
+
+  detect(_context: HostDetectionContext): HostDetectionResult {
+    return { isDetected: false, confidence: 'low', reasons: [] }
+  }
+
+  async initialize(): Promise<void> {
+    // Connect, validate credentials, etc.
+  }
+
+  async runInterviewTurn(input: InterviewTurnInput, _state: InterviewTurnState): Promise<InterviewTurnResult> {
+    return { content: input.prompt, status: 'continue' }
+  }
+
+  async getActiveModel(): Promise<string | null> {
+    return 'my-model'
+  }
+
+  async sendPrompt(
+    prompt: string,
+    agent: AgentDefinition,
+    job: JobDefinition,
+    step: WorkflowStep,
+    options?: PromptOptions,
+  ): Promise<AgentResponse> {
+    // Call your LLM/host here
+    const content = await callMyLLM(prompt, options)
+
+    return {
+      agentId: agent.id,
+      stepId: step.id,
+      jobId: job.id,
+      content,
+      artifacts: [],    // parse from content if needed
+      status: 'success',
+    }
+  }
+
+  getCapabilities(): HostCapabilities {
+    return {
+      supportsStreaming: false,
+      supportsToolUse: false,
+      supportsVision: false,
+      maxContextTokens: 32000,
+      supportedModels: ['my-model'],
+    }
+  }
+
+  async healthCheck(): Promise<boolean> {
+    // Verify connectivity
+    return true
+  }
+}
+```
+
+## Step 2: Parse Agent Response
+
+The key contract is the `AgentResponse` type. Your adapter must parse the LLM output and return:
+- `content` — the text response
+- `artifacts` — any `PendingArtifact[]` the agent wants to persist
+- `handoffSignal` — optional, if the agent signals handoff explicitly
+- `status` — `'success' | 'failure' | 'needs_input' | 'loop_back'`
+
+## Step 3: Use the Adapter
+
+```typescript
+import { MyHostAdapter } from './orchestrator/adapters/host/myhost.adapter.js'
+import { createSquadRuntime } from './orchestrator/runtime/squad-runtime.js'
+
+const runtime = createSquadRuntime({
+  hostAdapter: new MyHostAdapter(),
+  artifactsDir: 'artifacts',
+})
+```
+
+## Notes
+
+- The `SquadRuntime` never imports a specific host adapter — it only uses `IHostAdapter`
+- You can have different agents use different host adapters by extending `SquadRuntime`
+- For IDE-native agents (Claude Code, Cursor, etc.), the host adapter can simply relay to the IDE's built-in agent API
+- `sendPrompt` receives `options.metadata.allowedAgentIds` from runtime; use this to validate explicit handoff targets when parsing response text.

package/docs/development/adding-integrations.md

@@ -0,0 +1,83 @@
+# Adding New Integrations
+
+All integrations implement one of the existing adapter interfaces. Each integration is isolated — the core and runtime never import integrations directly.
+
+## Adapter Interfaces by Integration Type
+
+| Integration type | Interface | Example |
+|-----------------|-----------|---------|
+| Git + PR platform | `IVCSAdapter` | GitHub, GitLab, Bitbucket |
+| Social media publishing | `ISocialMediaAdapter` | Instagram, LinkedIn, Twitter/X |
+| Deployment | `IDeployAdapter` | Vercel, AWS, Railway, Fly.io |
+| Context/docs | `IContextAdapter` | Notion, Confluence, GitHub Wiki |
+| Tools/APIs | `IToolAdapter` | Web search, database, custom APIs |
+
+## Example: Adding a GitLab Adapter
+
+```typescript
+// orchestrator/adapters/vcs/gitlab.adapter.ts
+import type { IVCSAdapter, ... } from './IVCSAdapter.js'
+
+export class GitLabVCSAdapter implements IVCSAdapter {
+  readonly id = 'gitlab'
+  readonly name = 'GitLab'
+
+  // Implement all IVCSAdapter methods
+  // ...
+}
+```
+
+## Example: Adding a LinkedIn Publisher
+
+```typescript
+// orchestrator/adapters/publishing/linkedin.adapter.ts
+import type { ISocialMediaAdapter, ... } from './ISocialMediaAdapter.js'
+
+export class LinkedInAdapter implements ISocialMediaAdapter {
+  readonly id = 'linkedin'
+  readonly platform = 'LinkedIn'
+
+  // Implement all ISocialMediaAdapter methods
+  // ...
+}
+```
+
+## Registering Integrations in a Squad
+
+In `config/squad.json`:
+
+```json
+{
+  "allowedIntegrations": [
+    {
+      "id": "gitlab",
+      "type": "vcs",
+      "name": "GitLab",
+      "required": true,
+      "status": "real"
+    }
+  ]
+}
+```
+
+## Making Stubs Real
+
+All stubs follow this pattern:
+1. They log `[STUB]` messages
+2. They return mock data
+3. They have `TODO:` comments marking where real API calls go
+
+To activate a stub:
+1. Set the required environment variables
+2. Install the SDK (`npm install @anthropic-ai/sdk`, etc.)
+3. Replace the stub implementation with real API calls
+4. Update the adapter's `status` field from `'stub'` to `'real'`
+
+## Safety
+
+Always ensure:
+- Publishing adapters check for human approval before acting
+- Deploy adapters check for human confirmation before any deploy
+- VCS adapters never force-push to protected branches
+
+These checks belong in the runtime guardrail layer — the adapter implements the API call only.

package/docs/development/host-detection-and-resolution.md

@@ -0,0 +1,59 @@
+# Host Detection and Resolution
+
+This document explains how Squad Foundry resolves host adapters in CLI-first mode.
+
+## Overview
+
+Resolution happens in three stages:
+
+1. `ActiveHostDetector` collects host signals from argv, files, env, and process hints.
+2. `HostResolutionService` applies confidence + validity rules.
+3. `HostRuntimeService` materializes the adapter and persists preference metadata.
+
+## Confidence and Resolution Rules
+
+- `high`: use detected host only if adapter initializes and supports command.
+- `medium`: reuse persisted host only if:
+  - adapter initializes,
+  - command is supported,
+  - at least one medium/strong signal still matches prior validation.
+- `low`: use assisted selection (interactive CLI) or fail with explicit message in non-interactive mode.
+
+## Persisted Preference Format
+
+File: `squad-foundry.hosts.json`
+
+Example:
+
+```json
+{
+  "preferredHost": "local",
+  "validation": {
+    "timestamp": "2026-04-02T12:00:00.000Z",
+    "matchedSignals": ["file:CLAUDE.md"]
+  },
+  "lastValidated": "2026-04-02T12:00:00.000Z",
+  "hosts": ["antigravity", "anthropic", "local", "openai"]
+}
+```
+
+## Runtime Provenance
+
+Each `run` writes:
+
+- `artifacts/<squad>/<job>/reports/runtime-metadata.json`
+
+Fields:
+
+- `resolvedHost`
+- `confidence`
+- `reasons`
+- `activeModel`
+- `fallbackPath`
+
+`status` prints these fields for quick diagnosis.
+
+## MCP Mode
+
+MCP uses the same resolution pipeline but does not run interactive selection.
+If no valid detected/persisted host is available, MCP returns an explicit error asking for `SQUAD_FOUNDRY_ADAPTER`.

package/docs/squads/how-to-create.md

@@ -0,0 +1,85 @@
+# How to Create a Squad
+
+Squads are created via the **Squad Builder** — an interview-driven system that generates all necessary files.
+
+## Method 1: CLI Interview
+
+```bash
+node dist/cli/index.js build
+```
+
+The CLI will ask you a series of questions and generate the squad files.
+
+## Method 2: Programmatic API
+
+```typescript
+import { createSquadBuilder } from './orchestrator/builder/squad-builder.js'
+import type { InterviewAnswer } from './orchestrator/core/types.js'
+
+const builder = createSquadBuilder({
+  contextRootPath: process.cwd(),
+  outputDir: process.cwd(),
+})
+
+const answers: InterviewAnswer[] = [
+  { questionId: 'q_objective', answer: 'Create and publish Instagram content' },
+  { questionId: 'q_domain', answer: '3' },  // social-media
+  { questionId: 'q_description', answer: 'End-to-end Instagram content pipeline' },
+  { questionId: 'q_inputs', answer: 'Campaign brief or topic' },
+  { questionId: 'q_outputs', answer: 'Published Instagram post with analytics' },
+  { questionId: 'q_steps', answer: '1. Strategy, 2. Write, 3. Review, 4. Approve, 5. Publish' },
+  { questionId: 'q_approvals', answer: 'Publishing requires human approval' },
+  { questionId: 'q_human_in_loop', answer: 'Never auto-publish' },
+  { questionId: 'q_squad_name', answer: 'instagram-content' },
+]
+
+const result = await builder.build(answers)
+console.log('Generated files:', result.generatedFiles.map(f => f.path))
+```
+
+## Method 3: Manual Creation
+
+Copy the template from `templates/SQUAD.md` and create:
+
+```
+squads/my-squad/
+  SQUAD.md
+  WORKFLOW.md
+  AGENTS.md
+  POLICIES.md
+  config/
+    squad.json
+```
+
+The `config/squad.json` is the source of truth. See `squads/examples/software-development/config/squad.json` for a complete example.
+
+## Generated Files
+
+| File | Purpose |
+|------|---------|
+| `SQUAD.md` | Human-readable squad overview |
+| `WORKFLOW.md` | Step-by-step workflow documentation |
+| `AGENTS.md` | Agent descriptions and responsibilities |
+| `POLICIES.md` | Guardrails and prohibited actions |
+| `config/squad.json` | Machine-readable squad definition (source of truth) |
+
+## Interview Questions
+
+The builder asks about:
+- **Objective** — What does the squad achieve?
+- **Domain** — What type of work (software, social media, docs, etc.)?
+- **I/O** — What goes in? What comes out?
+- **Steps** — What are the workflow steps?
+- **Approvals** — What requires human sign-off?
+- **Tools** — What integrations are needed?
+- **Policies** — What is prohibited?
+- **Risks** — What could go wrong?
+
+## Customizing After Generation
+
+Edit `config/squad.json` to:
+- Add/remove agents
+- Add/remove workflow steps
+- Change guardrail severity
+- Add approval requirements
+- Update agent instructions