{"id":51139013,"url":"https://github.com/ybenitezf/spec-teams","last_synced_at":"2026-06-25T20:30:44.825Z","repository":{"id":364908928,"uuid":"1267987142","full_name":"ybenitezf/spec-teams","owner":"ybenitezf","description":"Pi extension for multi-agent SDD workflow","archived":false,"fork":false,"pushed_at":"2026-06-15T02:57:25.000Z","size":545,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T04:19:56.510Z","etag":null,"topics":["agents","pi-coding-agent","pi-extension","sdd"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ybenitezf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-13T03:23:26.000Z","updated_at":"2026-06-15T02:57:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ybenitezf/spec-teams","commit_stats":null,"previous_names":["ybenitezf/spec-teams"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ybenitezf/spec-teams","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ybenitezf%2Fspec-teams","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ybenitezf%2Fspec-teams/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ybenitezf%2Fspec-teams/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ybenitezf%2Fspec-teams/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ybenitezf","download_url":"https://codeload.github.com/ybenitezf/spec-teams/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ybenitezf%2Fspec-teams/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34792208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","pi-coding-agent","pi-extension","sdd"],"created_at":"2026-06-25T20:30:44.137Z","updated_at":"2026-06-25T20:30:44.818Z","avatar_url":"https://github.com/ybenitezf.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spec Teams 🧠 → 👥\n\n\u003e **A Pi coding agent extension that transforms a single AI agent into a multi-agent team orchestrator for the OpenSpec spec-driven development workflow.**\n\u003e\n\u003e *Built on [disler's agent-team.ts](https://github.com/disler/pi-vs-claude-code/blob/main/extensions/agent-team.ts) foundation.*\n\n[![CI](https://github.com/ybenitezf/spec-teams/actions/workflows/ci.yml/badge.svg)](https://github.com/ybenitezf/spec-teams/actions/workflows/ci.yml)\n[![Pi Extension](https://img.shields.io/badge/Pi-Extension-6C47FF)](https://github.com/earendil-works/pi-coding-agent)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n---\n\n## Overview\n\nSpec Teams extends the [Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent) with a **multi-agent orchestration layer** purpose-built for the [OpenSpec](https://github.com/earendil-works/OpenSpec) spec-driven development (SDD) methodology.\n\nInstead of one agent doing everything, Spec Teams registers a `dispatch_agent` tool that spawns and coordinates **specialist sub-agents** — each with its own session persistence, tool set, and focused system prompt. The result is a structured, disciplined development workflow where every phase of the OpenSpec lifecycle has a dedicated agent tuned for that job.\n\n```\nUser Request → Dispatcher → Explore → Propose → Apply → Verify → Archive\n                                ↕\n                            Worker (git, files, scripts)\n```\n\n---\n\n## How It Works\n\n### 🧭 Intelligent Routing\n\nThe dispatcher agent understands the OpenSpec lifecycle and intelligently routes user requests to the right specialist. Stuck during exploration? It sends you to the Explore agent. Ready to implement? It routes to Apply. Need a final check? Verify takes it from there.\n\n### 🧩 Specialist Sub-Agents\n\nEach sub-agent runs as its own headless Pi process with:\n\n- **Dedicated session persistence** — memory and context carry across invocations\n- **Scoped tool access** — agents only get the tools they need\n- **Specialized system prompts** — deep expertise in their phase of the workflow\n- **Structured status signals** — `need-input`, `ready-to-propose`, `done`, `blocked`\n\n### 📋 OpenSpec Convention\n\nThe team follows the OpenSpec change lifecycle rigorously:\n\n1. **Change proposal** — `proposal.md`, `design.md`, `tasks.md`, and delta specs are generated as structured artifacts\n2. **Implementation** — tasks are executed, code is written, files are edited\n3. **Verification** — spec compliance is audited, scenarios are traced to code, tests are run\n4. **Archival** — completed changes are finalized, delta specs synced, moved to `archive/`\n\n### ⚙️ Configurable Teams\n\nTeam composition is defined in `teams.yaml`. Two teams ship by default:\n\n- **`openspec`** — the core OpenSpec lifecycle agents\n- **`full`** — includes the Worker agent for general-purpose tasks\n\nSwitch teams on the fly with the `/specs-team` command.\n\n---\n\n## The Specialist Agents\n\n| Agent | Purpose |\n|---|---|\n| **Explore** | Investigates problems, explores the codebase, clarifies requirements through multi-turn conversation. High reasoning depth for open-ended analysis. |\n| **Propose** | Creates structured OpenSpec change proposals — generates `proposal.md`, `design.md`, `tasks.md`, and delta specs from briefs. Balanced reasoning for structured creativity. |\n| **Apply** | Implements tasks directly — writes code, edits files, runs CLI commands, and marks tasks complete. Low latency for fast iteration. |\n| **Verify** | Read-only auditor that checks spec compliance, traces scenarios to code, runs tests, and reports findings without making changes. Medium reasoning for thorough analysis. |\n| **Archive** | Finalizes completed changes — syncs delta specs, moves artifacts to `archive/`, and cleans up. Minimal reasoning for mechanical tasks. |\n| **Worker** | General-purpose executor for git operations, file operations, scripts, and quick edits. The utility player of the team. |\n\n---\n\n## Key Design Patterns\n\n### 🏗️ Headless Sub-Agent Architecture\n\nSpecialist agents are spawned as independent Pi processes with no TUI or user interaction. They communicate via structured **Status signals** (`done`, `blocked`, `need-input`, `ready-to-propose`), making the orchestration predictable and inspectable.\n\n### 📡 Signal-Based Orchestration\n\nThe dispatcher and sub-agents coordinate through a lightweight signal protocol:\n- **`need-input`** — agent requires more information before proceeding\n- **`ready-to-propose`** — agent has produced artifacts for review\n- **`done`** — task completed successfully\n- **`blocked`** — unrecoverable issue encountered\n\n### 🔄 OpenSpec Delta Pattern\n\nChanges are structured as incremental, reviewable deltas. Each phase produces artifacts that feed naturally into the next, making the development process transparent and auditable.\n\n### 🖥️ Real-Time Streaming\n\nSub-agent output streams live to the Pi terminal UI, so you can watch progress as it happens. Use `/specs-dashboard` to open a detailed agent dashboard overlay showing per-agent status, metrics, and configuration.\n\n### 💾 Session Persistence\n\nEach sub-agent maintains its own Pi session across invocations, preserving context, conversation history, and working state. The dispatcher knows which agents have active sessions and can route follow-up requests accordingly.\n\n---\n\n## Agent System\n\n### Dispatcher / Sub-Agent Architecture\n\nSpec Teams uses a **dispatcher/sub-agent architecture** to orchestrate work:\n\n- **Dispatcher agent** — The central coordinator that understands the OpenSpec lifecycle and routes user requests to the right specialist agent.\n- **Sub-agents** — Each specialist (Explore, Propose, Apply, Verify, Archive, Worker) runs as an **independent headless Pi process**. They have no TUI or direct user interaction. The dispatcher spawns them, sends instructions, and receives structured status signals back.\n\nThis separation means each sub-agent maintains its own session, tools, and context independently. The dispatcher knows which agents have active sessions and can route follow-up requests to the same agent for continuity.\n\n### Signal-Based Orchestration\n\nThe dispatcher and sub-agents coordinate through a lightweight signal protocol. Every sub-agent returns one of four status signals:\n\n| Signal | Meaning |\n|---|---|\n| `done` | Task completed successfully |\n| `blocked` | Unrecoverable issue encountered — cannot proceed without intervention |\n| `need-input` | Agent requires more information from the user before proceeding |\n| `ready-to-propose` | Agent has produced artifacts (proposal, design, specs) ready for review |\n\nThe dispatcher interprets these signals to decide what happens next: route to another agent, pause for user input, or report completion.\n\n### Agent .md Files: Dual-Purpose Format\n\nEach agent is defined by a single `.md` file that serves two purposes:\n\n1. **YAML frontmatter** — Configuration metadata (name, description, tools, thinking level, model)\n2. **Markdown body** — The system prompt that defines the agent's behavior and expertise\n\n```markdown\n---\nname: explore\ndescription: Investigates problems and clarifies requirements\ntools: read, write, bash, grep\nthinking: high\nmodel: provider-id/some-model\n---\n\nYou are the Explore agent in the spec-teams extension. Your role is to...\n```\n\nThis format makes agents easy to read, edit, and share. The frontmatter is parsed by the extension at load time; the markdown body becomes the system prompt for that agent's Pi session.\n\n---\n\n## Creating Custom Agents\n\nYou can create your own specialist agents or use third-party agent definitions. Spec Teams follows Pi's standard agent definition convention.\n\n### Agent Frontmatter Format\n\nEach agent `.md` file uses YAML frontmatter with these fields:\n\n| Field | Required | Description | Example |\n|---|---|---|---|\n| `name` | Yes | Agent identifier (used in teams.yaml) | `explore` |\n| `description` | Yes | Short description of the agent's role | `Investigates problems and clarifies requirements` |\n| `tools` | Yes | Comma-separated list of allowed tools | `read, write, bash, grep` |\n| `thinking` | No | Reasoning depth: `low`, `medium`, `high` | `high` |\n| `model` | No | Default model override | `anthropic/claude-sonnet-4` |\n| `opt-in` | No | When `true`, agent is opt-in only — won't be included in default teams; must be explicitly added to `teams.yaml` | `true` |\n\nThe markdown body below the frontmatter is the agent's system prompt.\n\n### Agent Discovery Priority Order\n\nPi loads agent definitions from these locations in priority order (first match wins):\n\n1. **Project `agents/`** — Agents in the project root's `agents/` directory\n2. **`.claude/agents/`** — Claude Code-style agent definitions\n3. **`.pi/agents/`** — Pi-specific agent directory in the project\n4. **`~/.pi/agent/agents/`** — User-level Pi agent directory\n5. **`~/.agents/agents/`** — User-level global agents\n\nTo add a custom agent, place its `.md` file in any of these directories. Project-level agents take precedence over user-level ones.\n\n### Team Configuration (`teams.yaml`)\n\nAfter creating an agent, add it to a team in `teams.yaml`. The file is discovered across multiple directories using first-seen-wins priority:\n\n1. `\u003ccwd\u003e/agents/teams.yaml`\n2. `\u003ccwd\u003e/.claude/agents/teams.yaml`\n3. `\u003ccwd\u003e/.pi/agents/teams.yaml`\n4. `\u003cgetAgentDir()\u003e/agents/teams.yaml` (user-level, typically `~/.pi/agent/agents/teams.yaml`)\n5. `~/.agents/agents/teams.yaml` (user-level)\n\nThe first `teams.yaml` found wins — project-level files shadow user-level ones.\n\n```yaml\nopenspec:\n  - explore\n  - propose\n  - apply\n  - verify\n  - archive\n  - my-custom-agent    # Add your agent here\n\nfull:\n  - explore\n  - propose\n  - apply\n  - verify\n  - archive\n  - worker\n  - my-custom-agent    # Or add it to the full team\n```\n\nSwitch between teams using the `/specs-team` command in Pi.\n\n### Model Overrides\n\nThe `model` field in agent frontmatter specifies a **default model**, not a requirement. Users should override this with their own provider and model ID. The models shipped in the example agents (e.g., `opencode-go/glm-5`) are specific to certain providers and may not be available to you.\n\nTo use a different model:\n\n1. **Edit the agent .md file** — Change the `model` field directly\n2. **Override per-session** — Some Pi configurations allow model overrides at runtime\n\nIf no `model` field is specified, the agent uses Pi's default model configuration.\n\n### External Agent Compatibility\n\nSpec Teams is compatible with agent definitions from other Pi extensions and projects that follow the same `.md` frontmatter convention:\n\n- **[pi-vs-claude-code](https://github.com/disler/pi-vs-claude-code)** — disler's repository contains various agent definitions that work with spec-teams\n- **[Pi subagent examples](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/subagent)** — Official Pi examples of sub-agent patterns\n\nAny agent `.md` file following the Pi frontmatter format (YAML metadata + markdown body) can be used with spec-teams. Simply place the file in one of the discovery directories listed above and add it to your team.\n\n---\n\n## Tech Stack\n\n| Component | Technology |\n|---|---|\n| **Runtime** | TypeScript / Node.js |\n| **Agent SDK** | [Pi Coding Agent SDK](https://github.com/earendil-works/pi-coding-agent) |\n| **Validation** | [TypeBox](https://github.com/sinclairzx81/typebox) |\n| **Terminal UI** | [Pi TUI](https://github.com/earendil-works/pi-tui) |\n| **Spec SDD** | [OpenSpec](https://github.com/earendil-works/OpenSpec) |\n| **Agent Format** | Markdown + YAML frontmatter (`agents/*.md`) |\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- [Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent) installed globally\n- Node.js 18+\n- **[OpenSpec](https://github.com/earendil-works/OpenSpec)** — This is a **hard dependency**. Spec Teams agents rely on OpenSpec skill files located in `.pi/skills/openspec-*` and the `openspec` CLI command that drives the SDD lifecycle. Without OpenSpec installed, agents will hard-stop at startup.\n\n  Install OpenSpec via one of these methods:\n  ```bash\n  # Option 1: Use the openspec CLI directly\n  openspec init\n\n  # Option 2: Via the Pi extension system (if available)\n  ```\n\n  The skills provide expert procedures for each phase of the OpenSpec lifecycle (explore, propose, apply, archive). They are required for the specialist agents to function correctly.\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/ybenitezf/spec-teams-extension.git\ncd spec-teams-extension\n\n# Load the extension with Pi\npi -e ./extensions/spec-teams.ts\n```\n\nThe extension registers itself on load. Once active, you'll have access to the `dispatch_agent` tool and the `/specs-*` commands.\n\n#### Using in an Existing Project\n\nIf you want to use spec-teams in another project without cloning this repo separately:\n\n1. **Ensure OpenSpec is initialized** — Run `openspec init` in your project if it isn't already configured. This creates the `.pi/skills/` and `.pi/prompts/` directories that Spec Teams depends on.\n2. **Copy or link the extension files** — You only need two things from this repository:\n   - `extensions/` — The spec-teams extension entry point\n   - `agents/` — Agent definitions (place in any of the discovery directories)\n3. **Place `teams.yaml` in a discovery directory** — The teams configuration file follows the same multi-directory discovery as agent `.md` files. Place it alongside your agents in any of the 5 scan directories (see Team Configuration section above).\n3. **Load the extension** — Point Pi at the extension file:\n   ```bash\n   pi -e ./path/to/spec-teams-extension/extensions/spec-teams.ts\n   ```\n\nPlace the `agents/` directory (with agent `.md` files and `teams.yaml`) where you want it discovered:\n- **Project-level** — Copy into your project root for project-specific agents\n- **User-level** — Copy into your user agents directory (e.g., `~/.pi/agent/agents/`) for user-wide availability\n\n---\n\n## Configuration\n\n### Teams (`teams.yaml`)\n\nDefine which agents are available in each team:\n\n```yaml\nopenspec:\n  - explore\n  - propose\n  - apply\n  - verify\n  - archive\n\nfull:\n  - explore\n  - propose\n  - apply\n  - verify\n  - archive\n  - worker\n```\n\n### Agent Definitions (`agents/*.md`)\n\nEach agent is defined as a Markdown file with YAML frontmatter:\n\n```markdown\n---\nname: my-agent\ndescription: Does something useful\ntools: read,write,bash\nthinking: medium\nmodel: provider-id/some-model\n---\n\nYou are a specialist agent in the spec-teams extension…\n```\n\n### Skills (`.pi/skills/`)\n\nOpenSpec lifecycle phases have corresponding skill files that provide expert procedures for each phase (explore, propose, apply, archive).\n\n### Agent Discovery\n\nAgent definitions are loaded from (in priority order):\n1. `agents/`\n2. `.claude/agents/`\n3. `.pi/agents/`\n\nUser-level overrides can be placed in `~/.agents/agents/`.\n\n---\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `/specs-team` | Open the team selector to switch between configured teams |\n| `/specs-list` | Display all loaded agents with their current status |\n| `/specs-dashboard` | Open the detailed agent dashboard overlay (per-agent cards with full state) |\n\n---\n\n## Project Structure\n\n```\nspec-teams-extension/\n├── agents/                # Agent definitions (Markdown + YAML frontmatter)\n│   ├── apply.md\n│   ├── archive.md\n│   ├── explore.md\n│   ├── propose.md\n│   ├── verify.md\n│   └── worker.md\n├── extensions/\n│   └── spec-teams.ts      # Main extension entry point\n├── .pi/\n│   ├── prompts/           # OpenSpec lifecycle prompts\n│   └── skills/            # OpenSpec skill procedures\n├── package.json\n└── README.md\n```\n\n---\n\n## Acknowledgments\n\n### OpenSpec\n\nSpec Teams depends entirely on [OpenSpec](https://github.com/earendil-works/OpenSpec) for its spec-driven development methodology, skill system, and CLI. The `.pi/skills/openspec-*` skill files provide expert procedures for each phase of the lifecycle (explore, propose, apply, archive), and the `openspec` command drives the entire SDD workflow. Without OpenSpec, the specialist agents cannot function.\n\n### disler / pi-vs-claude-code\n\n**Spec Teams is based on and forked from** [disler](https://github.com/disler)'s [`agent-team.ts`](https://github.com/disler/pi-vs-claude-code/blob/main/extensions/agent-team.ts) extension from the [pi-vs-claude-code](https://github.com/disler/pi-vs-claude-code) repository. That work pioneered the multi-agent team orchestration pattern that Spec Teams builds upon — demonstrating how a single Pi agent can be transformed into an orchestrator of specialist sub-agents. The `spec-teams.ts` implementation descends directly from disler's original design, extended with OpenSpec integration, signal-based orchestration, and session persistence.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n*Built for the [Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent) ecosystem. Powered by the [OpenSpec](https://github.com/earendil-works/OpenSpec) spec-driven development methodology.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fybenitezf%2Fspec-teams","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fybenitezf%2Fspec-teams","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fybenitezf%2Fspec-teams/lists"}