squadfoundry 0.1.0

package/docs/superpowers/specs/2026-04-01-host-native-cli-shell-design.md

@@ -0,0 +1,253 @@
+# Squad Foundry Design Spec: Host-Native CLI Shell
+
+Date: 2026-04-01
+Status: Draft (design approved in conversation)
+Owner: Squad Foundry
+
+## 1) Context and Goal
+
+Squad Foundry already has a strong architecture in `orchestrator/core`, `orchestrator/runtime`, and `orchestrator/builder`, with clear adapter interfaces and test coverage. The product goal for this phase is to deliver an experience similar in usability to OpenSquad (command-first, low-friction workflow) while preserving Squad Foundry's own identity and architecture.
+
+This phase is explicitly CLI-first. MCP remains available but is secondary.
+
+Primary outcomes:
+- Keep the core host/model/tool/domain agnostic.
+- Provide a command flow that feels native in real IDE usage.
+- Use the active IDE model for guided interviews (`create`/`edit`) and runtime execution (`run`).
+- Avoid mandatory API key setup for the primary host-native workflow.
+
+## 2) Product Principles
+
+1. **Do not copy OpenSquad internals**: borrow interaction ergonomics only.
+2. **Core remains pure**: `orchestrator/core/*` and runtime internals do not hardcode host vendors.
+3. **Host-native first**: if running inside Claude Code, OpenCode, Codex, Antigravity, Zed, etc., use that host's active model.
+4. **No silent fallback to API-key providers**: fallback is explicit and user-visible.
+5. **Deterministic traceability**: every job records chosen host, model, confidence, and fallback reasons.
+
+## 3) Scope
+
+### In Scope
+- New CLI shell layer for command UX.
+- Host detection and host resolution with confidence scoring.
+- Assisted host selection when auto-detection is ambiguous or fails.
+- Interview bridge using host-native model for `create` and `edit`.
+- Runtime invocation through resolved host adapter.
+- Improved CLI diagnostics and run reporting.
+- Tests and docs for the new flow.
+
+### Out of Scope (This Phase)
+- Replacing the core state machine or guardrail engine.
+- MCP as primary transport.
+- Full parity across every host on day one.
+- Real deploy/publish side effects without explicit approval gates.
+
+## 4) Target User Experience
+
+### Core Commands
+- `squad-foundry init`
+- `squad-foundry create`
+- `squad-foundry edit <squad-id>`
+- `squad-foundry run <squad-id>`
+- `squad-foundry list`
+- `squad-foundry status <squad-id> <job-id>`
+- `squad-foundry hosts`
+
+### UX Guarantees
+- `init` configures project for host-native usage first.
+- `create` and `edit` interview turns run on the active IDE model.
+- `run` uses the same resolved host unless user overrides.
+- If host is not confidently detected, CLI asks user which IDE to use and persists that decision.
+
+## 5) Architecture
+
+### 5.1 Existing Layers (Preserved)
+- `orchestrator/core/*`
+- `orchestrator/runtime/*`
+- `orchestrator/builder/*`
+- `orchestrator/adapters/*`
+- `orchestrator/context/*`
+- `orchestrator/artifacts/*`
+
+### 5.2 New CLI Shell Layer
+Add:
+- `orchestrator/shell/cli.ts`
+- `orchestrator/shell/commands/init.command.ts`
+- `orchestrator/shell/commands/create.command.ts`
+- `orchestrator/shell/commands/edit.command.ts`
+- `orchestrator/shell/commands/run.command.ts`
+- `orchestrator/shell/commands/list.command.ts`
+- `orchestrator/shell/commands/status.command.ts`
+- `orchestrator/shell/commands/hosts.command.ts`
+
+Support services:
+- `orchestrator/shell/services/project-bootstrap.service.ts`
+- `orchestrator/shell/services/squad-scaffold.service.ts`
+- `orchestrator/shell/services/job-execution.service.ts`
+- `orchestrator/shell/services/active-host-detector.service.ts`
+- `orchestrator/shell/services/host-resolution.service.ts`
+- `orchestrator/shell/services/interview-host-bridge.service.ts`
+
+### 5.3 Config Files
+- `squad-foundry.config.json`
+- `squad-foundry.hosts.json`
+
+`squads/<id>/config/squad.json` remains source of truth for squad definitions.
+
+## 6) Host-Native Strategy
+
+### 6.1 Detection Model
+`ActiveHostDetector` scores candidate hosts using:
+- Strong signals: host-specific command context / known workspace entrypoints.
+- Medium signals: host config files in repo.
+- Weak signals: environment/process hints.
+
+Output:
+- `detectedHostId`
+- `confidence` (`high | medium | low`)
+- `reasons[]`
+
+### 6.2 Resolution Flow
+1. If confidence is high, use detected host.
+2. If confidence is medium and a previously validated host exists and matches current host-family signals, use it; otherwise prompt user.
+3. If confidence is low, always run assisted selection prompt.
+4. Persist selected host and last-validation metadata (timestamp + matched signals).
+
+Persisted host validity requirements:
+- adapter initializes successfully;
+- capability check passes for requested command;
+- at least one current medium/strong detection signal matches prior validation.
+
+If any validity requirement fails, force assisted selection.
+
+### 6.3 Mandatory User Prompt on Uncertain Detection
+When no host reaches required confidence:
+- Prompt user with supported options (installed and configured hosts first).
+- Configure or install bridge files for the selected host.
+- Continue flow using that host.
+
+### 6.4 Model Selection Rule
+`create`, `edit`, and `run` must all use the active model provided by resolved host adapter when available. If model cannot be read, log `model=host-default` in reports.
+
+## 7) Adapter Contract Updates
+
+`IHostAdapter` must support both interview and runtime paths:
+- `detect(context): DetectionResult`
+- `initialize(): Promise<void>`
+- `runInterviewTurn(input, state): Promise<InterviewTurnResult>`
+- `sendPrompt(prompt, agent, job, step, options?): Promise<AgentResponse>`
+- `getCapabilities(): HostCapabilities`
+- `getActiveModel(): Promise<string | null>`
+
+Notes:
+- Runtime core still consumes `AgentResponse` only.
+- Shell owns resolution logic; runtime must never hardcode host selection.
+
+## 8) Priority Support Matrix
+
+Tier 1 (this cycle):
+1. `claude-code`
+2. `opencode`
+
+Tier 2 (next cycle):
+- `codex`
+- `antigravity`
+- `zed`
+
+Tier 3:
+- `cursor`
+- `vscode-copilot`
+- additional hosts via plugin adapters
+
+## 9) Known Issues to Fix in Existing Code
+
+1. **MCP host hardcode**: remove forced `AntigravityHostAdapter` behavior and route through normal resolution.
+2. **IDE handoff parsing bug**: fix `IDEHostAdapter` handoff extraction logic (agent list source).
+3. **CLI squad path mismatch**: support `squads/examples/*` and generated squads consistently.
+
+## 10) Error Handling and Observability
+
+Standardized CLI error categories:
+- `host_detection_error`
+- `host_execution_error`
+- `invalid_squad_config`
+- `guardrail_block`
+- `approval_pending`
+
+For each error, present:
+- human-readable summary
+- technical cause
+- actionable next step
+
+Each job report includes:
+- resolved host
+- detection confidence and reasons
+- active model (or `host-default`)
+- fallback path (if used)
+
+## 11) Testing Strategy
+
+Add tests for:
+- host detection scoring and tie-break rules
+- assisted host selection path
+- host-native interview flow in `create` and `edit`
+- runtime execution through resolved host
+- fallback behavior without silent API-key switching
+- path resolution for examples and generated squads
+
+Keep existing unit/integration tests green.
+
+## 12) Implementation Plan (Phased)
+
+Phase 1:
+- Add CLI shell command structure.
+- Wire existing runtime/builder through shell services.
+
+Phase 2:
+- Implement detector + resolver + persisted host preferences.
+
+Phase 3:
+- Implement interview host bridge for `create` and `edit`.
+
+Phase 4:
+- Harden Tier 1 adapters (Claude Code then OpenCode).
+- Fix known bugs (handoff, pathing, MCP hardcode).
+
+Phase 5:
+- Improve CLI diagnostics and run status reporting.
+
+Phase 6:
+- Add tests and docs updates.
+
+## 13) Risks and Mitigations
+
+Risks:
+- Host capability differences can create uneven UX.
+- Ambiguous environments can reduce detection reliability.
+- Upstream IDE changes may break adapters.
+
+Mitigations:
+- Capability negotiation via adapter contract.
+- Assisted selection as required fallback.
+- Compatibility docs and adapter tests per host.
+
+## 14) Definition of Done
+
+Done means:
+1. `init/create/edit/run` work through the new shell layer.
+2. Interviews use active IDE model through resolved host adapter.
+3. `run` uses resolved host and records host/model provenance.
+4. Uncertain host detection triggers user selection and persistence.
+5. No silent fallback to API-key provider paths.
+6. Existing tests pass; new host-shell tests pass.
+7. Documentation explains setup, operation, and extension.
+8. Acceptance checks in CI:
+   - `npm test` includes shell detection/resolution/interview/runtime/fallback coverage.
+   - E2E verifies `init -> create -> run -> status` for Tier 1 hosts.
+   - Golden report assertions include `resolvedHost`, `confidence`, `reasons[]`, `activeModel`, and `fallbackPath`.
+
+## 15) Non-Goals and Guardrails
+
+- Do not embed host-vendor logic into core state machine or guardrails.
+- Do not claim unsupported host integrations as complete.
+- Do not auto-execute deploy/publish side effects without explicit approvals.
+- Do not break domain-agnostic squad behavior.

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "squadfoundry",
+  "version": "0.1.0",
+  "description": "Local extensible multi-agent squad orchestration platform — model-agnostic, host-agnostic, domain-agnostic",
+  "type": "module",
+  "main": "./dist/orchestrator/index.js",
+  "types": "./dist/orchestrator/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/orchestrator/index.js",
+      "types": "./dist/orchestrator/index.d.ts"
+    },
+    "./adapters/host/ide": {
+      "import": "./dist/orchestrator/adapters/host/ide.adapter.js",
+      "types": "./dist/orchestrator/adapters/host/ide.adapter.d.ts"
+    },
+    "./adapters/host/claude-code": {
+      "import": "./dist/orchestrator/adapters/host/claude-code.adapter.js",
+      "types": "./dist/orchestrator/adapters/host/claude-code.adapter.d.ts"
+    },
+    "./adapters/host/opencode": {
+      "import": "./dist/orchestrator/adapters/host/opencode.adapter.js",
+      "types": "./dist/orchestrator/adapters/host/opencode.adapter.d.ts"
+    },
+    "./adapters/host/anthropic": {
+      "import": "./dist/orchestrator/adapters/host/anthropic.adapter.js",
+      "types": "./dist/orchestrator/adapters/host/anthropic.adapter.d.ts"
+    },
+    "./adapters/host/openai": {
+      "import": "./dist/orchestrator/adapters/host/openai.adapter.js",
+      "types": "./dist/orchestrator/adapters/host/openai.adapter.d.ts"
+    },
+    "./adapters/host/local": {
+      "import": "./dist/orchestrator/adapters/host/local.adapter.js",
+      "types": "./dist/orchestrator/adapters/host/local.adapter.d.ts"
+    }
+  },
+  "bin": {
+    "squadfoundry": "./dist/orchestrator/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "squads/",
+    "templates/",
+    "docs/",
+    "README.md",
+    "PROJECT.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "cli": "node dist/orchestrator/cli/index.js",
+    "dev:cli": "tsx orchestrator/cli/index.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.82.0",
+    "commander": "^12.1.0",
+    "glob": "^11.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "agents",
+    "multi-agent",
+    "orchestration",
+    "squad",
+    "ai",
+    "automation",
+    "workflow",
+    "claude-code",
+    "opencode",
+    "cursor",
+    "codex",
+    "ai-native"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cubocompany/squadfoundry"
+  },
+  "homepage": "https://github.com/cubocompany/squadfoundry",
+  "bugs": {
+    "url": "https://github.com/cubocompany/squadfoundry/issues"
+  },
+  "license": "MIT"
+}

package/squads/examples/instagram-content/AGENTS.md

@@ -0,0 +1,63 @@
+# Agents — Instagram Content Squad
+
+## Strategy Agent
+
+**ID:** `strategy-agent` | **Role:** Content Strategist
+
+Defines target audience, tone of voice, content pillars, post objective, and success metrics. Does not write captions.
+
+---
+
+## Research Agent
+
+**ID:** `research-agent` | **Role:** Content Researcher
+
+Researches trending hashtags, competitor content, and audience insights. Never fabricates statistics.
+
+---
+
+## Copy Agent
+
+**ID:** `copy-agent` | **Role:** Copywriter
+
+Writes Instagram caption within constraints: max 2200 chars, max 30 hashtags, must include CTA, must follow brand voice. This agent is the revision hub — loops back from review failures.
+
+---
+
+## Creative Review Agent
+
+**ID:** `creative-review-agent` | **Role:** Creative Director
+
+Reviews for creativity, engagement, and tone. Issues PASS or REVISE. Does not rewrite — provides specific feedback. Loops back to Copy Agent on REVISE.
+
+---
+
+## Brand/Compliance Agent
+
+**ID:** `brand-agent` | **Role:** Brand Guardian
+
+Validates against brand guidelines (reads brand/** context files). Checks: prohibited words, legal risks, hashtag policy, brand voice. Issues PASS or FAIL.
+
+---
+
+## Approval Agent
+
+**ID:** `approval-agent` | **Role:** Human Approval Coordinator
+
+Presents the full content package to the human. NEVER auto-approves. Waits for explicit APPROVE or REJECT. Records decision with timestamp.
+
+---
+
+## Publisher Agent
+
+**ID:** `publisher-agent` | **Role:** Content Publisher
+
+Publishes content to Instagram ONLY after human approval is recorded. Never publishes if approval is missing. Reports post URL and metadata.
+
+---
+
+## Analytics Agent
+
+**ID:** `analytics-agent` | **Role:** Performance Analyst
+
+Retrieves post analytics and generates a performance report with recommendations. Reports "not yet available" honestly if data isn't ready.

package/squads/examples/instagram-content/POLICIES.md

@@ -0,0 +1,45 @@
+# Policies — Instagram Content Squad
+
+## Guardrails
+
+### 1. Require Minimum Context (`grail-min-context`)
+- **Severity:** warn
+- **Rule:** `require_minimum_context`
+- **Description:** Brand guidelines context recommended (brand/** files)
+
+### 2. Require Approval Before Publish (`grail-approval-publish`)
+- **Severity:** block
+- **Rule:** `require_approval_before_publish`
+- **Description:** No content is ever published without explicit human approval
+
+## Prohibited Actions
+
+- Auto-publish without human approval
+- Post content that fails brand compliance check
+- Use more than 30 hashtags
+- Post content rejected by Creative Review
+- Delete published posts automatically
+- Fabricate engagement metrics or statistics
+- Use competitor brand names in captions without approval
+
+## Required Approvals
+
+| Action | Requirement |
+|--------|-------------|
+| publish | Human must see full caption and explicitly approve before any Instagram post is created |
+
+## Brand Guidelines
+
+All agents should read from `brand/**` context files when available, including:
+- `brand/voice-guidelines.md`
+- `brand/prohibited-words.md`
+- `brand/hashtag-policy.md`
+- `brand/visual-guidelines.md`
+
+## Caption Rules
+
+- Maximum 2,200 characters
+- Maximum 30 hashtags
+- Must include a clear call-to-action
+- Must match brand tone of voice
+- No promotional claims without compliance review

package/squads/examples/instagram-content/SQUAD.md

@@ -0,0 +1,63 @@
+# Instagram Content Squad
+
+**ID:** `instagram-content`
+**Domain:** social-media
+**Version:** 1.0.0
+
+## Objective
+
+Create, review, approve, and publish high-quality Instagram content from concept to post.
+
+## Agents
+
+| Agent | Role | Responsibility |
+|-------|------|---------------|
+| Strategy Agent | Content Strategist | Define content strategy and brief |
+| Research Agent | Content Researcher | Hashtags, trends, audience insights |
+| Copy Agent | Copywriter | Write Instagram caption + CTA |
+| Creative Review Agent | Creative Director | Review for engagement and tone |
+| Brand/Compliance Agent | Brand Guardian | Check brand guidelines and compliance |
+| Approval Agent | Human Coordinator | Present to human for final sign-off |
+| Publisher Agent | Content Publisher | Publish to Instagram (never without approval) |
+| Analytics Agent | Performance Analyst | Track and report post performance |
+
+## Workflow
+
+```
+Campaign Brief
+  ↓
+Strategy Agent → Strategy Brief
+  ↓
+Research Agent → Research Summary + Hashtags
+  ↓
+Copy Agent → Caption Draft
+  ↓
+Creative Review Agent → PASS or REVISE (loops to Copy Agent)
+  ↓
+Brand/Compliance Agent → PASS or FAIL (loops to Copy Agent)
+  ↓
+[HUMAN APPROVAL REQUIRED]
+  ↓
+Publisher Agent → Published Post
+  ↓
+Analytics Agent → Performance Report
+```
+
+## Key Policies
+
+- **No auto-publish**: Content is never published without explicit human approval
+- **Brand compliance gate**: All content must pass brand/compliance review
+- **Caption limits**: Max 2200 characters, max 30 hashtags
+- **Revision loop**: Copy Agent loops until creative + compliance review passes
+- **Analytics follow-up**: Every published post is tracked and reported
+
+## Guardrails
+
+- `require_minimum_context` — Brand guidelines context recommended
+- `require_approval_before_publish` — Blocks publishing without human approval
+
+## Integrations
+
+| Integration | Status |
+|-------------|--------|
+| Instagram Graph API | stub |

package/squads/examples/instagram-content/WORKFLOW.md

@@ -0,0 +1,58 @@
+# Workflow: Instagram Content Pipeline
+
+End-to-end content workflow with review loops and a mandatory human approval gate before publishing.
+
+## Steps
+
+### 1. Content Strategy (`step-strategy`)
+- **Agent:** Strategy Agent
+- **Input:** Campaign brief or topic request
+- **Output:** strategy_brief.md
+- **Approval:** None
+
+### 2. Research (`step-research`)
+- **Agent:** Research Agent
+- **Input:** Strategy brief
+- **Output:** research_summary.md (hashtags, trends, insights)
+- **Approval:** None
+
+### 3. Copywriting (`step-copy`)
+- **Agent:** Copy Agent
+- **Input:** Strategy brief, research summary
+- **Output:** caption_draft.md
+- **Approval:** None
+- **Loop:** Returns here from Creative Review (REVISE) or Compliance (FAIL)
+
+### 4. Creative Review (`step-creative-review`)
+- **Agent:** Creative Review Agent
+- **Input:** Caption draft, strategy brief
+- **Output:** creative_review.md (PASS or REVISE)
+- **Approval:** None
+- **Loop:** REVISE → Copy Agent
+
+### 5. Brand & Compliance Review (`step-brand`)
+- **Agent:** Brand/Compliance Agent
+- **Input:** Caption draft, creative review
+- **Output:** compliance_review.md (PASS or FAIL)
+- **Approval:** None
+- **Loop:** FAIL → Copy Agent
+
+### 6. Human Approval (`step-approval`)
+- **Agent:** Approval Agent
+- **Input:** Caption draft, compliance review
+- **Output:** approval_decision.json
+- **Approval:** **REQUIRED** — human must explicitly approve
+- **Guardrail:** `require_approval_before_publish`
+
+### 7. Publishing (`step-publish`)
+- **Agent:** Publisher Agent
+- **Input:** Caption draft, approval_decision
+- **Output:** published_post.json
+- **Approval:** **REQUIRED** — publish gate blocks without approval record
+- **Guardrail:** `require_approval_before_publish`
+
+### 8. Analytics (`step-analytics`)
+- **Agent:** Analytics Agent
+- **Input:** Published post metadata
+- **Output:** analytics_report.md
+- **Approval:** None