squadfoundry 0.1.0

package/AGENTS.md

@@ -0,0 +1,76 @@
+# Agent Conventions — Squad Foundry
+
+This file describes how agents are defined, how they behave, and what conventions apply across all squads on this platform.
+
+## Agent Identity
+
+Every agent has a unique `id` within its squad. IDs are kebab-case slugs (e.g., `code-agent`, `publisher-agent`).
+
+## Agent Instructions Pattern
+
+Agent instructions follow this structure:
+1. **Identity statement** — "You are the [Role]. [Short description]."
+2. **Core task** — What to do given the inputs
+3. **Output contract** — What to produce and in what format
+4. **Constraints** — What NOT to do
+5. **Handoff signal** — When and how to signal completion
+
+## Handoff Protocol
+
+When an agent completes its step, it signals handoff via `HandoffSignal` in the `AgentResponse`:
+```json
+{
+  "handoffSignal": {
+    "targetAgentId": "next-agent-id",
+    "condition": "step_completed_successfully",
+    "payload": { "summary": "..." }
+  }
+}
+```
+
+If no handoff signal is present, the runtime auto-generates one based on the workflow's `nextStepId`.
+
+## Artifact Protocol
+
+Agents produce artifacts via `PendingArtifact[]` in the `AgentResponse`:
+```json
+{
+  "artifacts": [
+    {
+      "name": "prd",
+      "content": "# PRD\n...",
+      "format": "markdown"
+    }
+  ]
+}
+```
+
+The ArtifactStore persists these and creates `ArtifactRef` entries in the job.
+
+## State Constraints
+
+Each agent declares `allowedStates[]`. The guardrail `block_invalid_state_transition` enforces this — an agent cannot act outside its allowed states.
+
+## Approval Protocol
+
+If an agent needs human approval, it sets `approvalNeeded: true` and `approvalReason: "..."` in the response. The ApprovalGate handles this — execution pauses until a human resolves it.
+
+## Prohibited Behaviors (All Agents)
+
+- Never execute real side effects (deploy, publish, merge) without an explicit approval record
+- Never fabricate metrics, test results, or compliance outcomes
+- Never skip required artifacts
+- Never act in disallowed states
+
+## Model Preferences
+
+Agents may specify `modelPreference` to request a specific model or provider. If absent, the squad runtime uses the host adapter's default.
+
+## Adding a New Agent
+
+1. Define the agent in `squads/<squad_id>/config/squad.json` under `agents[]`
+2. Add a workflow step in `workflow.steps[]` that references the agent
+3. Document the agent in `squads/<squad_id>/AGENTS.md`
+4. Update `squads/<squad_id>/WORKFLOW.md` with the new step
+
+See `docs/development/adding-agents.md` for full guide.

package/PROJECT.md

@@ -0,0 +1,79 @@
+# Project: Squad Foundry
+
+## Overview
+
+Squad Foundry is a local, extensible multi-agent squad orchestration platform. It enables the design, configuration, and execution of collaborative AI agent squads for any domain — from software development to social media content to documentation and research.
+
+## Domain
+
+platform / meta-tooling
+
+## Stack / Technology
+
+- **Language:** TypeScript (strict mode, ESM)
+- **Runtime:** Node.js >= 20
+- **Test runner:** Vitest
+- **Package manager:** npm
+- **Core dependencies:** `commander` (CLI), `glob` (file discovery), `zod` (schema validation)
+- **No framework dependencies** in the core layer
+
+## Key Conventions
+
+- **Naming:** kebab-case for files and folders, PascalCase for classes, camelCase for functions/variables
+- **Modules:** ESM-only (`"type": "module"`)
+- **Imports:** Always use `.js` extension in imports (required for ESM + TypeScript)
+- **Adapter pattern:** Core never imports adapters. Always depend on interfaces.
+- **No magic state:** All state transitions are explicit and logged
+- **Artifacts:** All job outputs are human-readable files (JSON + Markdown)
+
+## Project Structure
+
+```
+orchestrator/
+  core/           Types, state machine, guardrails (zero external deps)
+  adapters/       Pluggable interface implementations (host, model, vcs, etc.)
+  context/        Context discovery and loading
+  artifacts/      Job artifact persistence
+  runtime/        Squad execution engine
+  builder/        Squad design interview + generation
+  cli/            CLI entrypoint
+
+squads/
+  examples/       Ready-to-use squad examples
+  templates/      Reusable squad template patterns
+
+templates/        Document templates (PROJECT.md, TASKS.md, etc.)
+docs/             Platform documentation
+tests/            Unit and integration tests
+```
+
+## Goals for Current Phase
+
+- [x] Core type system
+- [x] Explicit state machine
+- [x] Guardrail engine
+- [x] All adapter interfaces
+- [x] Adapter stubs (host, VCS, publishing, deploy, context)
+- [x] Context loader + index
+- [x] Artifact store
+- [x] Squad runtime (full execution engine)
+- [x] Squad builder (interview + generation)
+- [x] CLI entrypoint
+- [x] Software development squad example
+- [x] Instagram content squad example
+- [x] Templates
+- [x] Tests (unit + integration)
+- [ ] Activate real adapters (Anthropic, GitHub, Instagram)
+- [ ] Dashboard / status UI
+- [ ] Multi-squad job scheduler
+
+## Known Constraints / Non-Goals
+
+- All external adapters are stubs — real API calls require configuration
+- No persistent database — filesystem only
+- No real-time collaboration between agents (sequential execution only in v0.1)
+- No authentication layer (local use only)
+
+## Host Compatibility
+
+Designed to work with: Claude Code, OpenCode, Cursor, Codex, Zed, Antigravity, any host that can invoke a Node.js CLI or import TypeScript modules.

package/README.md

@@ -0,0 +1,255 @@
+# Squad Foundry
+
+**Local extensible multi-agent squad orchestration platform.**
+
+Model-agnostic. Host-agnostic. Tool-agnostic. Domain-agnostic.
+
+---
+
+## What is Squad Foundry?
+
+Squad Foundry lets you design and run **collaborative multi-agent squads** for any domain:
+
+- Software development (spec → code → review → test → PR → deploy)
+- Instagram content (strategy → copy → review → approval → publish → analytics)
+- Documentation, research, marketing, operations — anything task-and-handoff-oriented
+
+Squads are **portable JSON configurations**. The same squad runs in Claude Code, OpenCode, Cursor, Codex, Zed, or any compatible host — just swap the adapter.
+
+---
+
+## Quickstart
+
+### Instalar como pacote npm
+
+```bash
+npm install squad-foundry
+```
+
+### Usar no Claude Code / OpenCode / Cursor / Codex / Zed
+
+Você não precisa de API key — a IDE já é o modelo. O `IDEHostAdapter` recebe um callback que a IDE executa:
+
+```typescript
+import {
+  IDEHostAdapter,
+  createSquadRuntime,
+  createSquadBuilder,
+} from 'squad-foundry'
+
+// O callback que você fornece É o modelo — a IDE executa isso
+const runtime = createSquadRuntime({
+  hostAdapter: new IDEHostAdapter(async (prompt) => {
+    // Aqui você integra com o modelo que já está rodando na sua IDE.
+    // Em Claude Code: use o agente atual para responder o prompt.
+    // Em OpenCode: use opencode.complete(prompt)
+    // Em Cursor: use cursor.chat(prompt)
+    return yourIDEModel.complete(prompt)
+  }),
+})
+
+// Carregar um squad e executar um job
+import squadJson from './squads/examples/software-development/config/squad.json' assert { type: 'json' }
+const job = await runtime.startJob(squadJson, 'Implement dark mode', 'Add toggle to settings page')
+await runtime.runAll(squadJson, job)
+```
+
+### CLI (uso local)
+
+```bash
+# Instalar globalmente
+npm install -g squad-foundry
+
+# Inicializar config host-native
+squad-foundry init
+
+# Criar um novo squad (entrevista guiada via host ativo)
+squad-foundry create
+
+# Editar um squad existente
+squad-foundry edit software-development
+
+# Executar um job
+squad-foundry run software-development --objective "Implement dark mode"
+
+# Ver status
+squad-foundry status software-development <job-id>
+
+# Listar squads
+squad-foundry list
+
+# Ver host resolvido e preferencia persistida
+squad-foundry hosts
+```
+
+### Desenvolvimento local
+
+```bash
+# Clonar e instalar
+npm install
+
+# Compilar
+npm run build
+
+# Testes
+npm test
+```
+
+---
+
+## Architecture
+
+```
+Squad Foundry
+├── Core Layer          orchestrator/core/
+│   ├── types.ts        All portable type definitions
+│   ├── state-machine.ts Explicit state transitions
+│   └── guardrails.ts   Policy enforcement engine
+│
+├── Adapter Layer       orchestrator/adapters/
+│   ├── host/           IHostAdapter + stubs (Anthropic, OpenAI, Local)
+│   ├── model/          IModelAdapter
+│   ├── tools/          IToolAdapter
+│   ├── vcs/            IVCSAdapter + GitHub stub
+│   ├── publishing/     ISocialMediaAdapter + Instagram stub
+│   ├── deploy/         IDeployAdapter + Vercel stub
+│   └── context/        IContextAdapter + filesystem adapter
+│
+├── Context Layer       orchestrator/context/
+│   ├── context-loader.ts Discovers and loads PROJECT.md, TASKS.md, docs/**
+│   └── context-index.ts  In-memory search index
+│
+├── Artifact Store      orchestrator/artifacts/
+│   └── artifact-store.ts Persists all job state, handoffs, outputs
+│
+├── Squad Runtime       orchestrator/runtime/
+│   ├── squad-runtime.ts  Main execution engine
+│   ├── job-manager.ts    Job lifecycle
+│   ├── agent-dispatcher.ts Step → Agent routing
+│   ├── handoff-manager.ts Agent handoff records
+│   └── approval-gate.ts  Human-in-the-loop mechanism
+│
+├── Squad Builder       orchestrator/builder/
+│   ├── squad-builder.ts  Interview orchestrator
+│   ├── interview-questions.ts Question bank
+│   ├── domain-classifier.ts  Domain detection
+│   └── squad-generator.ts    File generation
+│
+├── CLI                 orchestrator/cli/index.ts
+│
+├── Squad Examples      squads/examples/
+│   ├── software-development/
+│   └── instagram-content/
+│
+├── Templates           templates/
+└── Docs                docs/
+```
+
+---
+
+## Key Concepts
+
+### Squad
+A portable, reusable configuration defining: agents, workflow, policies, guardrails, expected artifacts. Stored as `squads/<squad_id>/config/squad.json`.
+
+### Job
+A runtime instance of a squad. Has a unique ID, state machine status, history, artifacts, and approvals. Stored under `artifacts/<squad_id>/<job_id>/`.
+
+### Agent
+A portable definition of an AI agent: role, instructions, allowed tools, handoff rules. Not tied to any specific model or host.
+
+### Workflow
+Ordered steps with dependencies, loops, approval gates, and guardrails. Fully declarative — no hardcoded logic.
+
+### Guardrail
+A programmatically enforced policy constraint. Examples: "no deploy without human approval", "no publish without compliance review".
+
+### Adapter
+An implementation of a well-defined interface (host, model, VCS, publish, deploy). Swap adapters to change the execution environment without touching core logic.
+
+---
+
+## Squad Examples
+
+| Squad | Domain | Agents |
+|-------|--------|--------|
+| `software-development` | software-development | Product, Code, Reviewer, Test, Commit, PR, Deploy |
+| `instagram-content` | social-media | Strategy, Research, Copy, Creative Review, Brand, Approval, Publisher, Analytics |
+
+---
+
+## Adapter Status
+
+| Adapter | Tipo | Status | Quando usar |
+|---------|------|--------|-------------|
+| `ClaudeCodeHostAdapter` | host | **real** | Bridge CLI nativa do Claude Code (sem API key) |
+| `OpenCodeHostAdapter` | host | **real** | Bridge CLI nativa do OpenCode (sem API key) |
+| `IDEHostAdapter` | host | **real** | Claude Code, OpenCode, Cursor, Codex, Zed — **a IDE é o modelo** |
+| `LocalHostAdapter` | host | stub | Ollama, LM Studio, llama.cpp local |
+| `AnthropicHostAdapter` | host | stub | API Anthropic direta (`ANTHROPIC_API_KEY`) |
+| `OpenAIHostAdapter` | host | stub | API OpenAI direta (`OPENAI_API_KEY`) |
+| `GitHubVCSAdapter` | vcs | stub | `GITHUB_TOKEN` + `GITHUB_REPO` |
+| `InstagramAdapter` | publishing | stub | `INSTAGRAM_ACCESS_TOKEN` |
+| `VercelDeployAdapter` | deploy | stub | `VERCEL_TOKEN` |
+| `FilesystemContextAdapter` | context | **real** | Lê arquivos locais automaticamente |
+
+> **Nota sobre IDEs AI-nativas:** Claude Code, OpenCode, Cursor, Codex e similares **já são o modelo**. Use `IDEHostAdapter` com um callback que delega para o mecanismo nativo da IDE. Nenhum API key adicional é necessário nesses ambientes.
+
+---
+
+## Context Files
+
+Squad Foundry automatically reads:
+
+| File | Priority | Purpose |
+|------|----------|---------|
+| `PROJECT.md` | 1 (highest) | Project overview, conventions |
+| `TASKS.md` | 2 | Current task state |
+| `AGENTS.md` | 3 | Agent conventions |
+| `README.md` | 4 | General project info |
+| `docs/**` | 5 | Documentation |
+| `specs/**` | 6 | Specifications |
+| `playbooks/**` | 7 | Playbooks |
+| `policies/**` | 8 | Policies |
+
+---
+
+## Human-in-the-Loop
+
+Approvals are always explicit. The system never auto-approves publishing or deployment.
+
+Configure required approvals in the squad's `POLICIES.md` and `config/squad.json`.
+
+---
+
+## Host-native Resolution
+
+Host resolution is CLI-first and explicit:
+
+- Detector scores strong/medium/weak host signals.
+- Resolver uses detected host when valid, then persisted host when still valid.
+- If unresolved, interactive CLI asks for host selection.
+- Runtime writes host provenance at `artifacts/<squad>/<job>/reports/runtime-metadata.json`.
+- `status` prints `resolvedHost`, `confidence`, `reasons`, `activeModel`, and `fallbackPath`.
+
+---
+
+## Creating a New Squad
+
+```bash
+# Interactive interview
+node dist/cli/index.js build
+
+# Or programmatically
+import { createSquadBuilder } from './orchestrator/builder/squad-builder.js'
+const builder = createSquadBuilder()
+const result = await builder.build(answers)
+```
+
+See [`docs/squads/how-to-create.md`](docs/squads/how-to-create.md) for full guide.
+
+---
+
+## License
+
+MIT

package/dist/orchestrator/adapters/context/IContextAdapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * IContextAdapter — Context/Documentation Adapter Interface
+ *
+ * Abstracts how context files are discovered and loaded.
+ * Default implementation reads from the local filesystem, but this
+ * interface allows future adapters to read from Notion, Confluence,
+ * GitHub wikis, or any other documentation source.
+ *
+ * STATUS: Interface defined. Concrete adapter: filesystem (real implementation)
+ */
+import type { ContextDiscoveryResult, DiscoveredFile, LoadedContext, ContextFileCategory } from '../../core/types.js';
+export interface ContextLoadOptions {
+    /** Root path to scan for context files */
+    rootPath: string;
+    /** Maximum file size in bytes to load (default: 500KB) */
+    maxFileSizeBytes?: number;
+    /** File categories to include (default: all) */
+    includeCategories?: ContextFileCategory[];
+    /** Glob patterns to explicitly exclude */
+    excludePatterns?: string[];
+    /** Whether to load recursively into subdirectories */
+    recursive?: boolean;
+}
+export interface ContextSummary {
+    totalFiles: number;
+    totalBytes: number;
+    categoryCounts: Record<ContextFileCategory, number>;
+    missingRecommended: string[];
+    hasProjectMd: boolean;
+    hasTasksMd: boolean;
+    hasAgentsMd: boolean;
+}
+/**
+ * Interface for context/documentation loading adapters.
+ * The context adapter is responsible for discovering and ingesting
+ * all human-authored documentation that informs agent behavior.
+ */
+export interface IContextAdapter {
+    readonly id: string;
+    readonly name: string;
+    /**
+     * Discover all context files in the given root path.
+     * Returns metadata without loading file contents.
+     */
+    discover(options: ContextLoadOptions): Promise<ContextDiscoveryResult>;
+    /**
+     * Load and return the full structured context.
+     * This is what gets attached to a JobDefinition.loadedContext.
+     */
+    load(options: ContextLoadOptions): Promise<LoadedContext>;
+    /**
+     * Load a single file by path.
+     */
+    loadFile(path: string): Promise<string>;
+    /**
+     * Get a summary of what context is available.
+     */
+    summarize(rootPath: string): Promise<ContextSummary>;
+    /**
+     * List all files in a specific category.
+     */
+    listByCategory(rootPath: string, category: ContextFileCategory): Promise<DiscoveredFile[]>;
+    healthCheck(): Promise<boolean>;
+}
+//# sourceMappingURL=IContextAdapter.d.ts.map

package/dist/orchestrator/adapters/context/IContextAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IContextAdapter.d.ts","sourceRoot":"","sources":["../../../../orchestrator/adapters/context/IContextAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAErH,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,mBAAmB,EAAE,CAAA;IACzC,0CAA0C;IAC1C,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,sDAAsD;IACtD,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAA;IACnD,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAC5B,YAAY,EAAE,OAAO,CAAA;IACrB,UAAU,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,OAAO,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAEtE;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAEzD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEvC;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAEpD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAA;IAE1F,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAChC"}

package/dist/orchestrator/adapters/context/IContextAdapter.js

@@ -0,0 +1,12 @@
+/**
+ * IContextAdapter — Context/Documentation Adapter Interface
+ *
+ * Abstracts how context files are discovered and loaded.
+ * Default implementation reads from the local filesystem, but this
+ * interface allows future adapters to read from Notion, Confluence,
+ * GitHub wikis, or any other documentation source.
+ *
+ * STATUS: Interface defined. Concrete adapter: filesystem (real implementation)
+ */
+export {};
+//# sourceMappingURL=IContextAdapter.js.map

package/dist/orchestrator/adapters/context/IContextAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IContextAdapter.js","sourceRoot":"","sources":["../../../../orchestrator/adapters/context/IContextAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/orchestrator/adapters/context/filesystem.context-adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * FilesystemContextAdapter — Real Implementation
+ *
+ * Discovers and loads context files from the local filesystem.
+ * This is the primary context adapter for local development.
+ *
+ * Priority order (highest to lowest):
+ * 1. PROJECT.md
+ * 2. TASKS.md
+ * 3. AGENTS.md
+ * 4. README.md
+ * 5. docs/**
+ * 6. specs/**
+ * 7. playbooks/**
+ * 8. policies/**
+ * 9. templates/**
+ * 10. workflows/**
+ * 11. brand/**
+ */
+import type { IContextAdapter, ContextLoadOptions, ContextSummary } from './IContextAdapter.js';
+import type { ContextDiscoveryResult, DiscoveredFile, LoadedContext, ContextFileCategory } from '../../core/types.js';
+export declare class FilesystemContextAdapter implements IContextAdapter {
+    readonly id = "filesystem";
+    readonly name = "Filesystem Context Adapter";
+    initialize(): Promise<void>;
+    discover(options: ContextLoadOptions): Promise<ContextDiscoveryResult>;
+    load(options: ContextLoadOptions): Promise<LoadedContext>;
+    loadFile(path: string): Promise<string>;
+    summarize(rootPath: string): Promise<ContextSummary>;
+    listByCategory(rootPath: string, category: ContextFileCategory): Promise<DiscoveredFile[]>;
+    healthCheck(): Promise<boolean>;
+}
+//# sourceMappingURL=filesystem.context-adapter.d.ts.map

package/dist/orchestrator/adapters/context/filesystem.context-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.context-adapter.d.ts","sourceRoot":"","sources":["../../../../orchestrator/adapters/context/filesystem.context-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC/F,OAAO,KAAK,EACV,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,mBAAmB,EAEpB,MAAM,qBAAqB,CAAA;AAkC5B,qBAAa,wBAAyB,YAAW,eAAe;IAC9D,QAAQ,CAAC,EAAE,gBAAe;IAC1B,QAAQ,CAAC,IAAI,gCAA+B;IAEtC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAkEtE,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IA6CzD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAqBpD,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK1F,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAGtC"}