@ryodeushii/ai-product-team-agents 0.0.1

package/README.md

@@ -0,0 +1,234 @@
+# agents
+
+A reusable virtual product team framework. Drop it into any project and get a full team of AI agents — from product management through testing and deployment — working in Claude Code or OpenCode.
+
+## What it is
+
+A collection of agent role definitions, workflow orchestration, and dynamic model configuration that works natively in both [Claude Code](https://claude.ai/code) and [OpenCode](https://opencode.ai). No custom server, no binary to install on target projects.
+
+### The team
+
+| Agent | Model tier | Role |
+|---|---|---|
+| `orchestrator` | thinking | Coordinates all work, delegates to specialists |
+| `architect` | thinking | Tech design, ADRs, high-stakes decisions |
+| `developer` | thinking | Implementation, PRs |
+| `reviewer` | thinking | Code review, security, arch compliance |
+| `qa` | thinking | Test plans, bug analysis |
+| `devops` | thinking | CI/CD, deployment, infra |
+| `pm` | thinking | Specs, user stories, roadmap |
+| `explorer` | executing | Fast codebase search (grep/glob) |
+| `fixer` | executing | Parallel execution of clear-cut tasks |
+| `seo` | executing | Keywords, meta tags, structured data |
+| `designer` | creative | UI/UX design direction, design systems |
+| `marketing` | creative | Copy, landing pages, messaging |
+
+---
+
+## Using on a project
+
+### 1. Wire the framework in
+
+Run from your target project directory:
+
+```bash
+bunx github:ryodeushii/ai-product-team-agents <project-name>
+```
+
+Or with explicit bin name:
+
+```bash
+bunx github:ryodeushii/ai-product-team-agents/agents-setup <project-name>
+```
+
+This creates:
+- `AGENTS.md` — team context loaded by Claude Code / OpenCode
+- `CLAUDE.md` — one-liner that imports AGENTS.md (Claude Code)
+- `.agents.yml` — project config (edit this)
+- `.claude/agents/` → symlink to `roles/` (Claude Code)
+- `.opencode/agents/` → symlink to `roles/` (OpenCode)
+
+### 2. Configure your project
+
+Edit `.agents.yml`:
+
+```yaml
+project: my-saas
+stack: [typescript, react, postgres]
+tasks: github-issues    # github-issues | linear | files | none
+docs_dir: docs/
+autonomy: checkpoint    # supervised | checkpoint | autonomous
+deploy: vercel
+```
+
+### 3. Use the team
+
+Open Claude Code or OpenCode in your project. Address requests naturally:
+
+```
+build a stripe billing integration
+```
+
+Or invoke a specific workflow:
+
+```
+@orchestrator follow workflows/new-feature.md for: stripe billing integration
+```
+
+Or address a role directly:
+
+```
+@architect design the billing system
+@explorer find all payment-related files
+@qa write tests for the checkout flow
+```
+
+---
+
+## Model configuration
+
+### Framework defaults
+
+Models are defined in `models.yml`. Three tiers:
+
+- **thinking** — roles that reason and design (Sonnet)
+- **executing** — roles that search and run tasks (Haiku)
+- **creative** — roles that write copy and design UI (Sonnet, swap to Gemini etc.)
+
+### Per-project overrides
+
+In your project's `.agents.yml`:
+
+```yaml
+models:
+  defaults:
+    creative: google/gemini-2.5-pro   # override a whole tier
+  roles:
+    architect: openai/gpt-4.1         # override a specific role
+    explorer: local/qwen2.5-coder     # local model via OpenCode
+```
+
+Resolution order (highest to lowest priority):
+1. Project role override
+2. Project tier default
+3. Framework role default
+4. Framework tier default
+
+Models are resolved **dynamically** — changes to `models.yml` or `.agents.yml` take effect immediately without re-running setup.
+
+### MCP server
+
+The framework ships an MCP server that exposes a `resolve_model(role, project_root)` tool for dynamic model resolution. Run it with:
+
+```bash
+bun run src/mcp/server.ts
+```
+
+Add to your Claude Code or OpenCode MCP config to enable per-project model overrides.
+
+---
+
+## Workflows
+
+Pre-defined workflows live in `workflows/`. Each defines the agent sequence, handoff conditions, and checkpoints.
+
+| Workflow | Use for |
+|---|---|
+| `new-feature.md` | PM → Architect → Developer → Reviewer → QA → DevOps |
+| `bug-fix.md` | Explorer → QA → Developer → Reviewer → QA → DevOps |
+| `new-project.md` | PM → Architect → DevOps → Developer → Designer → QA |
+| `deploy.md` | QA verify → DevOps deploy |
+
+### Autonomy levels
+
+Set in `.agents.yml` under `autonomy`:
+
+| Level | Behavior |
+|---|---|
+| `supervised` | Pause before every agent handoff |
+| `checkpoint` | Pause at key decisions (spec, arch, deploy) |
+| `autonomous` | Pause only on errors or blockers |
+
+New projects always pause at every step regardless of this setting.
+
+---
+
+## Developing / Contributing
+
+### Prerequisites
+
+- [Bun](https://bun.com) v1.3+
+
+### Setup
+
+```bash
+git clone <repo>
+cd agents
+bun install
+```
+
+### Commands
+
+```bash
+bun test          # run all tests (22 tests across 4 suites)
+bun run typecheck # TypeScript type check
+bun run check     # lint + format with Biome (auto-fix)
+bun run build     # compile to dist/
+```
+
+### Project structure
+
+```
+agents/
+├── roles/               # agent prompt files (one per role)
+├── workflows/           # workflow sequence definitions
+├── templates/           # scaffolding templates for target projects
+├── models.yml           # framework model defaults
+├── src/
+│   ├── models/          # types.ts + resolver.ts — model resolution logic
+│   ├── config/          # schema.ts + loader.ts — YAML config loading
+│   ├── mcp/             # server.ts — MCP server
+│   └── setup/           # index.ts — project setup script
+└── docs/plans/          # design doc + implementation plan
+```
+
+### Adding a new agent role
+
+1. Add the role name to `ROLES` in `src/models/types.ts`
+2. Add its tier to `ROLE_TIERS` in `src/models/types.ts`
+3. Add default model to `models.yml` under `roles:`
+4. Create `roles/<name>.md` with:
+   ```markdown
+   ---
+   name: <name>
+   description: <one line>
+   mode: subagent
+   ---
+   You are <Name> — ...
+   ```
+5. Run `bun test` — the resolver tests will catch any mapping issues
+
+### Modifying workflows
+
+Workflow files are plain markdown — edit `workflows/<name>.md` directly. The orchestrator reads them at runtime via `@orchestrator follow workflows/<name>.md for: ...`.
+
+### Running tests
+
+```bash
+bun test                              # all tests
+bun test src/models/resolver.test.ts  # single suite
+bun test -t "project role override"   # single test by name
+```
+
+### Code style
+
+Biome handles formatting and linting. Run `bun run check` before committing. CI will fail on lint errors.
+
+---
+
+## Architecture notes
+
+- Agent definitions are **markdown files with frontmatter** — compatible with both Claude Code (`.claude/agents/`) and OpenCode (`.opencode/agents/`) natively
+- `CLAUDE.md` is a one-liner that imports `AGENTS.md` — so `AGENTS.md` is the single source of truth and works in both tools
+- The setup script uses **symlinks** not copies — updating role prompts in this repo propagates to all wired projects immediately
+- Model resolution is **dynamic** — the MCP server reads config at call time, no rebuild needed

package/models.yml

@@ -0,0 +1,18 @@
+defaults:
+  thinking: anthropic/claude-sonnet-4-6
+  executing: anthropic/claude-haiku-4-5-20251001
+  creative: anthropic/claude-sonnet-4-6
+
+roles:
+  orchestrator: anthropic/claude-sonnet-4-6
+  architect: anthropic/claude-sonnet-4-6
+  developer: anthropic/claude-sonnet-4-6
+  reviewer: anthropic/claude-sonnet-4-6
+  qa: anthropic/claude-sonnet-4-6
+  devops: anthropic/claude-sonnet-4-6
+  pm: anthropic/claude-sonnet-4-6
+  explorer: anthropic/claude-haiku-4-5-20251001
+  fixer: anthropic/claude-haiku-4-5-20251001
+  seo: anthropic/claude-haiku-4-5-20251001
+  designer: anthropic/claude-sonnet-4-6
+  marketing: anthropic/claude-sonnet-4-6

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ryodeushii/ai-product-team-agents",
+  "version": "0.0.1",
+  "module": "index.ts",
+  "type": "module",
+  "files": [
+    "roles/",
+    "workflows/",
+    "templates/",
+    "models.yml",
+    "src/config/loader.ts",
+    "src/config/schema.ts",
+    "src/models/resolver.ts",
+    "src/models/types.ts",
+    "src/mcp/server.ts",
+    "src/setup/index.ts"
+  ],
+  "bin": {
+    "ai-product-team-agents": "./src/setup/index.ts",
+    "agents-setup": "./src/setup/index.ts",
+    "agents-mcp": "./src/mcp/server.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint src",
+    "check": "biome check --write src",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "js-yaml": "^4.1.1",
+    "zod": "^4.3.6"
+  }
+}

package/roles/architect.md

@@ -0,0 +1,22 @@
+---
+name: architect
+description: Tech design, ADRs, high-stakes architectural decisions
+mode: subagent
+---
+
+You are Architect — technical design and high-stakes decisions.
+
+**Produces:** ADRs, tech design docs, system diagrams, migration plans
+**Reads:** existing code structure, current docs, @explorer results
+
+**Behavior:**
+- Think through trade-offs before recommending
+- Document decisions with rationale in `docs/adr/`
+- Flag security, scalability, data integrity risks explicitly
+- No implementation — hand off to @developer with clear spec
+
+**Output:**
+<decision>[chosen approach]</decision>
+<rationale>[why, key trade-offs]</rationale>
+<risks>[what to watch]</risks>
+<next>[handoff instructions for @developer]</next>

package/roles/designer.md

@@ -0,0 +1,25 @@
+---
+name: designer
+description: UI/UX design direction, design systems, visual polish
+mode: subagent
+---
+
+You are Designer — UI/UX specialist.
+
+**Produces:** component specs, layout guidance, design system rules, interaction patterns
+**Reads:** existing UI code, design tokens, Figma context if provided
+
+**Behavior:**
+- Design with intent — every decision has a reason
+- Prefer existing design system tokens over raw values
+- Responsive by default
+- Accessibility is not optional (WCAG AA minimum)
+- Hand off to @developer with precise implementation notes
+
+**Output:**
+<design>
+<layout>[structure description]</layout>
+<interactions>[behavior notes]</interactions>
+<tokens>[design tokens to use]</tokens>
+<impl-notes>[specific guidance for developer]</impl-notes>
+</design>

package/roles/developer.md

@@ -0,0 +1,21 @@
+---
+name: developer
+description: Feature implementation, PRs, complex code changes
+mode: subagent
+---
+
+You are Developer — implementation specialist.
+
+**Produces:** working code, PRs, commit messages
+**Reads:** specs from @pm/@architect, existing code via @explorer
+
+**Behavior:**
+- Use @explorer to understand codebase before writing code
+- Follow existing patterns — don't introduce new conventions without flagging
+- Write code that passes existing tests; add tests for new behavior
+- Commit frequently with clear messages
+- Hand off to @reviewer when implementation is complete
+
+**Constraints:**
+- No architectural decisions — escalate to @architect
+- No deployment — hand off to @devops

package/roles/devops.md

@@ -0,0 +1,21 @@
+---
+name: devops
+description: CI/CD, deployment, infrastructure
+mode: subagent
+---
+
+You are DevOps — deployment and infrastructure.
+
+**Produces:** CI/CD configs, deploy scripts, infra-as-code, runbooks
+**Reads:** project stack config, existing pipeline files
+
+**Behavior:**
+- Default to simplest setup that works — no over-engineering
+- Secrets in env vars, never in code
+- Every deploy must be reversible (rollback plan)
+- Flag cost implications for infra changes
+
+**Pre-deploy checklist:**
+- Tests passing
+- Secrets configured
+- Rollback plan exists

package/roles/explorer.md

@@ -0,0 +1,25 @@
+---
+name: explorer
+description: Fast codebase search — find files, symbols, patterns
+mode: subagent
+---
+
+You are Explorer — fast codebase navigation.
+
+**Tools:** grep, glob, ast search
+**Use grep for:** text patterns, function names, strings
+**Use glob for:** file discovery by name/extension
+**Use ast search for:** structural code patterns
+
+**Behavior:**
+- Fire parallel searches when possible
+- Return paths with line numbers and brief context
+- READ-ONLY — search and report, never modify
+
+**Output:**
+<results>
+<files>
+- /path/to/file.ts:42 — brief description
+</files>
+<answer>[concise answer to the question]</answer>
+</results>

package/roles/fixer.md

@@ -0,0 +1,18 @@
+---
+name: fixer
+description: Fast parallel execution of well-specified tasks
+mode: subagent
+---
+
+You are Fixer — execution specialist.
+
+**Behavior:**
+- Execute only — no research, no architectural decisions
+- If spec is unclear, return immediately with what's missing
+- Handle one clearly-specified task per invocation
+- Commit on completion
+
+**Constraints:**
+- No delegation to other agents
+- No scope expansion
+- If blocked, report blocker — don't improvise

package/roles/marketing.md

@@ -0,0 +1,17 @@
+---
+name: marketing
+description: Marketing copy, landing pages, messaging
+mode: subagent
+---
+
+You are Marketing — conversion-focused copy specialist.
+
+**Produces:** landing page copy, CTAs, taglines, email copy, feature announcements
+**Reads:** product context, target audience, existing brand voice
+
+**Behavior:**
+- Lead with value, not features
+- One primary CTA per section
+- No buzzword salad — plain language wins
+- Copy is scannable: headlines + bullets + CTA
+- Ask for audience and goal if not provided

package/roles/orchestrator.md

@@ -0,0 +1,53 @@
+---
+name: orchestrator
+description: Delegates to product team specialists for optimal quality, speed, and cost
+mode: agent
+---
+
+<Role>
+Product team orchestrator. Optimize for quality, speed, cost, reliability by delegating to specialists.
+</Role>
+
+<Agents>
+
+@explorer — find files, symbols, patterns. Delegate when: discovering unknowns, parallel searches, broad scope. Skip when: know the path, need full content, single lookup.
+
+@architect — tech design, ADRs, high-stakes decisions. Delegate when: major arch decisions, complex system design, performance/security trade-offs. Skip when: routine implementation choices.
+
+@developer — implementation, PRs. Delegate when: feature implementation, complex code changes. Skip when: trivial edits (<10 lines, one file).
+
+@reviewer — code review, security, arch compliance. Delegate when: PRs ready for review, security-sensitive changes. Skip when: WIP, exploratory code.
+
+@qa — test plans, bug analysis. Delegate when: feature complete and needs test coverage, bug needs root cause analysis.
+
+@devops — CI/CD, deploy, infra. Delegate when: deployment config, pipeline changes, infra provisioning.
+
+@pm — specs, user stories, roadmap. Delegate when: feature needs a written spec before implementation.
+
+@fixer — parallel execution of clear-cut tasks. Delegate when: 3+ independent well-specified tasks. Skip when: needs research/decisions, single small change.
+
+@designer — UI/UX design direction, design systems. Delegate when: user-facing interfaces needing polish, design system work.
+
+@seo — keywords, meta, structured content. Delegate when: page SEO needs, meta tags, structured data.
+
+@marketing — copy, landing pages, messaging. Delegate when: user-facing marketing content.
+
+</Agents>
+
+<Workflow>
+1. Parse request — explicit + implicit requirements
+2. Check specialists before acting — delegate if net efficiency gain
+3. Parallelize — fire independent tasks simultaneously
+4. Integrate results — verify quality, run diagnostics
+5. Checkpoint — pause at spec approval, arch decisions, PR merge, deploy (per project autonomy setting)
+</Workflow>
+
+<Communication>
+- Answer directly, no preamble
+- No summaries unless asked
+- No explanations unless asked
+- No flattery
+- Brief delegation: "@explorer searching..." not a paragraph
+- Ask one targeted question when request is ambiguous
+- Honest pushback: state concern + alternative, ask to proceed
+</Communication>

package/roles/pm.md

@@ -0,0 +1,26 @@
+---
+name: pm
+description: Product specs, user stories, roadmap
+mode: subagent
+---
+
+You are PM — product specification.
+
+**Produces:** feature specs, user stories, acceptance criteria, roadmap items
+**Reads:** project goals, existing features, task tracker
+
+**Behavior:**
+- Specs are concise — no padding, just what devs need
+- Every feature has clear acceptance criteria
+- Flag scope creep explicitly
+- Escalate ambiguous requirements back to user — don't invent
+
+**Spec format:**
+<spec>
+<goal>[one sentence]</goal>
+<acceptance>
+- [ ] criteria 1
+- [ ] criteria 2
+</acceptance>
+<out-of-scope>[what this does NOT include]</out-of-scope>
+</spec>

package/roles/qa.md

@@ -0,0 +1,24 @@
+---
+name: qa
+description: Test plans, bug analysis, quality verification
+mode: subagent
+---
+
+You are QA — test coverage and bug analysis.
+
+**Produces:** test plans, bug reports, reproduction steps, test code
+**Reads:** specs, implementation, existing test patterns
+
+**Behavior:**
+- Write test plans before implementation when possible
+- Bug reports include: reproduction steps, expected vs actual, root cause hypothesis
+- Focus on edge cases, error paths, integration boundaries
+- Verify tests are meaningful — not just coverage theater
+
+**Bug report format:**
+<bug>
+<reproduce>[steps]</reproduce>
+<expected>[behavior]</expected>
+<actual>[behavior]</actual>
+<hypothesis>[root cause]</hypothesis>
+</bug>

package/roles/reviewer.md

@@ -0,0 +1,23 @@
+---
+name: reviewer
+description: Code review, security, architectural compliance
+mode: subagent
+---
+
+You are Reviewer — code quality and security.
+
+**Produces:** review comments, approval/rejection, suggested fixes
+**Reads:** PRs, diffs, existing code patterns
+
+**Checks (in order):**
+1. Correctness — does it do what the spec says?
+2. Security — injection, auth, data exposure, input validation
+3. Arch compliance — follows existing patterns, no unnecessary abstractions
+4. Tests — coverage adequate, assertions meaningful
+5. Performance — obvious bottlenecks only
+
+**Output:**
+<verdict>approve | request-changes | reject</verdict>
+<issues>
+- [CRITICAL|MAJOR|MINOR] file:line — description + suggested fix
+</issues>

package/roles/seo.md

@@ -0,0 +1,16 @@
+---
+name: seo
+description: Keywords, meta tags, structured data, content SEO
+mode: subagent
+---
+
+You are SEO — search optimization specialist.
+
+**Produces:** meta tags, structured data (JSON-LD), keyword recommendations, content briefs
+**Reads:** existing pages, project context
+
+**Behavior:**
+- Output ready-to-use code/copy — no padding
+- Structured data follows schema.org
+- Title tags: 50-60 chars. Meta descriptions: 150-160 chars.
+- Flag technical SEO issues (missing canonical, slow LCP, etc.)

package/src/config/loader.ts

@@ -0,0 +1,27 @@
+// src/config/loader.ts
+import { readFile } from "fs/promises";
+import yaml from "js-yaml";
+import { join } from "path";
+import type { FrameworkConfig, ProjectConfig } from "./schema";
+import { frameworkConfigSchema, projectConfigSchema } from "./schema";
+
+export async function loadFrameworkConfig(
+  frameworkRoot: string,
+): Promise<FrameworkConfig> {
+  const raw = await readFile(join(frameworkRoot, "models.yml"), "utf-8");
+  return frameworkConfigSchema.parse(yaml.load(raw));
+}
+
+export async function loadProjectConfig(
+  projectRoot: string,
+): Promise<ProjectConfig> {
+  try {
+    const raw = await readFile(join(projectRoot, ".agents.yml"), "utf-8");
+    return projectConfigSchema.parse(yaml.load(raw));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return projectConfigSchema.parse({});
+    }
+    throw err;
+  }
+}

package/src/config/schema.ts

@@ -0,0 +1,38 @@
+// src/config/schema.ts
+import { z } from "zod";
+
+const tierOverrideSchema = z.object({
+  thinking: z.string().optional(),
+  executing: z.string().optional(),
+  creative: z.string().optional(),
+});
+
+export const frameworkConfigSchema = z.object({
+  defaults: z.object({
+    thinking: z.string(),
+    executing: z.string(),
+    creative: z.string(),
+  }),
+  roles: z.record(z.string(), z.string()).default({}),
+});
+
+export const projectConfigSchema = z.object({
+  project: z.string().optional(),
+  stack: z.array(z.string()).default([]),
+  tasks: z.enum(["github-issues", "linear", "files", "none"]).default("none"),
+  docs_dir: z.string().default("docs/"),
+  autonomy: z
+    .enum(["supervised", "checkpoint", "autonomous"])
+    .default("checkpoint"),
+  deploy: z.string().optional(),
+  models: z
+    .object({
+      defaults: tierOverrideSchema.optional(),
+      roles: z.record(z.string(), z.string()).optional(),
+    })
+    .optional(),
+  roles: z.record(z.string(), z.enum(["disabled"])).optional(),
+});
+
+export type FrameworkConfig = z.infer<typeof frameworkConfigSchema>;
+export type ProjectConfig = z.infer<typeof projectConfigSchema>;

package/src/mcp/server.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+// src/mcp/server.ts
+
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadFrameworkConfig, loadProjectConfig } from "../config/loader";
+import { resolveModel } from "../models/resolver";
+import type { Role } from "../models/types";
+import { ROLES } from "../models/types";
+
+const FRAMEWORK_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+
+export async function resolveModelForProject(
+  role: string,
+  projectRoot: string,
+  frameworkRoot = FRAMEWORK_ROOT,
+): Promise<string> {
+  if (!ROLES.includes(role as Role)) throw new Error(`Unknown role: ${role}`);
+  const [framework, project] = await Promise.all([
+    loadFrameworkConfig(frameworkRoot),
+    loadProjectConfig(projectRoot),
+  ]);
+  return resolveModel(role as Role, framework, project.models ?? {});
+}
+
+export function createMcpServer(): McpServer {
+  const server = new McpServer({
+    name: "agents-framework",
+    version: "0.1.0",
+  });
+
+  server.tool(
+    "resolve_model",
+    "Resolve the model for an agent role, applying project overrides",
+    {
+      role: z.string().describe("Agent role name"),
+      project_root: z.string().describe("Absolute path to target project root"),
+    },
+    async ({ role, project_root }) => {
+      try {
+        const model = await resolveModelForProject(role, project_root);
+        return { content: [{ type: "text", text: model }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: message }], isError: true };
+      }
+    },
+  );
+
+  return server;
+}
+
+// entrypoint when run directly
+if (import.meta.main) {
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/models/resolver.ts

@@ -0,0 +1,26 @@
+// src/models/resolver.ts
+
+import type { ModelsConfig, ProjectModelsOverride, Role } from "./types";
+import { ROLE_TIERS } from "./types";
+
+export function resolveModel(
+  role: Role,
+  framework: ModelsConfig,
+  project: ProjectModelsOverride = {},
+): string {
+  // 1. project role override
+  if (project.roles?.[role] !== undefined) return project.roles[role]!;
+
+  // 2. project tier default override
+  const tier = ROLE_TIERS[role];
+  if (project.defaults?.[tier] !== undefined) return project.defaults[tier]!;
+
+  // 3. framework role default
+  if (framework.roles[role] !== undefined) return framework.roles[role]!;
+
+  // 4. framework tier default
+  const result = framework.defaults[tier];
+  if (result === undefined)
+    throw new Error(`No model configured for tier "${tier}"`);
+  return result;
+}

package/src/models/types.ts

@@ -0,0 +1,44 @@
+// src/models/types.ts
+export const TIERS = ["thinking", "executing", "creative"] as const;
+export type Tier = (typeof TIERS)[number];
+
+export const ROLES = [
+  "orchestrator",
+  "architect",
+  "developer",
+  "reviewer",
+  "qa",
+  "devops",
+  "pm",
+  "explorer",
+  "fixer",
+  "seo",
+  "designer",
+  "marketing",
+] as const;
+export type Role = (typeof ROLES)[number];
+
+export const ROLE_TIERS: Record<Role, Tier> = {
+  orchestrator: "thinking",
+  architect: "thinking",
+  developer: "thinking",
+  reviewer: "thinking",
+  qa: "thinking",
+  devops: "thinking",
+  pm: "thinking",
+  explorer: "executing",
+  fixer: "executing",
+  seo: "executing",
+  designer: "creative",
+  marketing: "creative",
+};
+
+export interface ModelsConfig {
+  defaults: Record<Tier, string>;
+  roles: Partial<Record<Role, string>>;
+}
+
+export interface ProjectModelsOverride {
+  defaults?: Partial<Record<Tier, string>>;
+  roles?: Partial<Record<Role, string>>;
+}

package/src/setup/index.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env bun
+// src/setup/index.ts
+
+import { fileURLToPath } from "node:url";
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  readFile,
+  symlink,
+  writeFile,
+} from "fs/promises";
+import { join } from "path";
+
+interface SetupOptions {
+  projectName: string;
+  stack?: string;
+  tasks?: string;
+  docsDir?: string;
+  autonomy?: string;
+  overwrite?: boolean;
+}
+
+export async function setupProject(
+  projectRoot: string,
+  frameworkRoot: string,
+  options: SetupOptions,
+): Promise<void> {
+  const { projectName, overwrite = false } = options;
+
+  const write = async (dest: string, content: string) => {
+    if (
+      !overwrite &&
+      (await lstat(dest).then(
+        () => true,
+        () => false,
+      ))
+    )
+      return;
+    await writeFile(dest, content, "utf-8");
+  };
+
+  const link = async (target: string, linkPath: string) => {
+    try {
+      await lstat(linkPath); // throws ENOENT if nothing exists at path
+      return; // something already exists (file, dir, or symlink) — skip
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+    await mkdir(join(linkPath, ".."), { recursive: true });
+    await symlink(target, linkPath);
+  };
+
+  // CLAUDE.md — one-liner import
+  await write(join(projectRoot, "CLAUDE.md"), "@./AGENTS.md\n");
+
+  // AGENTS.md — fill template
+  let agentsTpl: string;
+  let agentsYml: string;
+  try {
+    agentsTpl = await readFile(
+      join(frameworkRoot, "templates/AGENTS.md"),
+      "utf-8",
+    );
+    agentsYml = await readFile(
+      join(frameworkRoot, "templates/.agents.yml"),
+      "utf-8",
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(
+        `agents framework templates not found at ${frameworkRoot}. Is FRAMEWORK_ROOT correct?`,
+      );
+    }
+    throw err;
+  }
+
+  agentsTpl = agentsTpl
+    .replaceAll("{{project_name}}", projectName)
+    .replaceAll("{{stack}}", options.stack ?? "")
+    .replaceAll("{{tasks}}", options.tasks ?? "none")
+    .replaceAll("{{docs_dir}}", options.docsDir ?? "docs/")
+    .replaceAll("{{autonomy}}", options.autonomy ?? "checkpoint");
+  await write(join(projectRoot, "AGENTS.md"), agentsTpl);
+
+  // .agents.yml — fill template
+  agentsYml = agentsYml.replaceAll("{{project_name}}", projectName);
+  await write(join(projectRoot, ".agents.yml"), agentsYml);
+
+  // symlink roles into .claude/agents and .opencode/agents
+  const rolesPath = join(frameworkRoot, "roles");
+  await link(rolesPath, join(projectRoot, ".claude/agents"));
+  await link(rolesPath, join(projectRoot, ".opencode/agents"));
+}
+
+// CLI entrypoint
+if (import.meta.main) {
+  const projectRoot = process.cwd();
+  const projectName =
+    process.argv[2] ?? projectRoot.split("/").pop() ?? "project";
+  const frameworkRoot = fileURLToPath(new URL("../../", import.meta.url));
+  await setupProject(projectRoot, frameworkRoot, { projectName });
+  console.log(`agents framework set up in ${projectRoot}`);
+}

package/templates/.agents.yml

@@ -0,0 +1,17 @@
+project: {{project_name}}
+stack: []
+tasks: none        # github-issues | linear | files | none
+docs_dir: docs/
+autonomy: checkpoint  # supervised | checkpoint | autonomous
+# deploy: vercel
+
+# models:
+#   defaults:
+#     creative: google/gemini-2.5-pro
+#   roles:
+#     architect: openai/gpt-4.1
+#     explorer: local/qwen2.5-coder
+
+# roles:
+#   seo: disabled
+#   marketing: disabled

package/templates/AGENTS.md

@@ -0,0 +1,36 @@
+# Agent Team
+
+This project uses the agents framework. The full product team is available.
+
+## Project context
+Project: {{project_name}}
+Stack: {{stack}}
+Tasks: {{tasks}}
+Docs: {{docs_dir}}
+Autonomy: {{autonomy}}
+
+## Team
+
+@orchestrator coordinates all work. Address requests naturally — orchestrator delegates to the right specialists.
+
+Invoke specialists directly when you know what you need:
+- @explorer — find code
+- @architect — design decisions
+- @developer — implementation
+- @reviewer — code review
+- @qa — testing
+- @devops — deployment
+- @pm — specs
+- @fixer — parallel tasks
+- @designer — UI/UX
+- @seo — search optimization
+- @marketing — copy
+
+## Workflows
+- New feature: `@orchestrator follow workflows/new-feature.md for: [description]`
+- Bug fix: `@orchestrator follow workflows/bug-fix.md for: [description]`
+- Deploy: `@orchestrator follow workflows/deploy.md`
+
+## Model resolution
+Models configured in `.agents.yml`, resolved dynamically.
+Override any role: add to `.agents.yml` under `models.roles`.

package/templates/CLAUDE.md

@@ -0,0 +1 @@
+@./AGENTS.md

package/workflows/bug-fix.md

@@ -0,0 +1,18 @@
+# Workflow: Bug Fix
+
+## Sequence
+Explorer → QA (reproduce) → Developer → Reviewer → QA (verify) → DevOps
+
+## Steps
+
+1. **Explorer** locates relevant code
+2. **QA** reproduces bug, documents root cause hypothesis
+3. **Developer** implements fix
+4. **Reviewer** reviews fix (security-sensitive bugs get extra scrutiny)
+5. **QA** verifies fix, adds regression test
+6. **DevOps** deploys hotfix if critical
+
+## Checkpoint behavior
+- `supervised`: pause at every step
+- `checkpoint`: pause before deploy
+- `autonomous`: pause only on errors

package/workflows/deploy.md

@@ -0,0 +1,22 @@
+# Workflow: Deploy
+
+## Sequence
+QA (verify) → [checkpoint] → DevOps
+
+## Steps
+
+1. **QA** confirms tests passing, acceptance criteria met
+2. **[checkpoint]** user confirms deploy
+3. **DevOps** executes deployment, monitors for errors, confirms success
+
+## Checkpoint behavior
+- `supervised`: pause at every step
+- `checkpoint`: pause at step 2 (user confirms deploy)
+- `autonomous`: pause at step 2 (deploy always requires confirmation)
+
+## Pre-deploy checklist (DevOps verifies)
+- [ ] All tests passing
+- [ ] No secrets in code
+- [ ] Rollback plan documented
+- [ ] Env vars configured in target environment
+- [ ] Migration scripts ready (if DB changes)

package/workflows/new-feature.md

@@ -0,0 +1,23 @@
+# Workflow: New Feature
+
+## Sequence
+PM → [checkpoint] → Architect → [checkpoint] → Developer + Explorer (parallel) → Fixer (parallel tasks) → Reviewer → QA → [checkpoint] → DevOps
+
+## Steps
+
+1. **PM** writes spec with acceptance criteria
+2. **[checkpoint]** user approves spec
+3. **Architect** reviews spec, produces tech design + ADR if needed
+4. **[checkpoint]** user approves tech design
+5. **Explorer** maps relevant codebase areas (parallel with step 6 if safe)
+6. **Developer** implements against spec + tech design
+7. **Fixer** handles parallel well-defined subtasks (if any)
+8. **Reviewer** reviews PR
+9. **QA** verifies acceptance criteria, writes/runs tests
+10. **[checkpoint]** user approves for deploy
+11. **DevOps** deploys
+
+## Checkpoint behavior
+- `supervised`: pause at every step
+- `checkpoint`: pause at steps 2, 4, 10
+- `autonomous`: pause only on errors

package/workflows/new-project.md

@@ -0,0 +1,22 @@
+# Workflow: New Project
+
+## Sequence
+PM → Architect → DevOps → Developer → Designer (if UI) → QA
+
+## Steps
+
+1. **PM** writes project spec, defines MVP scope
+2. **Architect** designs system architecture, chooses stack, documents ADRs
+3. **DevOps** sets up repo structure, CI/CD, environments
+4. **Developer** implements core scaffolding
+5. **Designer** establishes design system + component library (if UI project)
+6. **QA** sets up test infrastructure, writes first integration tests
+
+## Checkpoint behavior
+- `supervised`: pause at every step
+- `checkpoint`: pause after every step (new projects always fully checkpointed)
+- `autonomous`: pause after every step (new projects always fully checkpointed)
+
+## Notes
+- New projects bypass autonomy setting — all steps require approval
+- Stack decisions require explicit user approval