{"id":39909006,"url":"https://github.com/spec2ship/spec2ship","last_synced_at":"2026-01-18T16:03:55.660Z","repository":{"id":330831302,"uuid":"1124098568","full_name":"spec2ship/spec2ship","owner":"spec2ship","description":"Spec-driven, multi-agent AI development for Claude Code: from specs to shipping via roundtable collaboration","archived":false,"fork":false,"pushed_at":"2026-01-15T22:06:45.000Z","size":3016,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T01:41:35.486Z","etag":null,"topics":["ai-agents","ai-workflow","claude","claude-code","llm","multi-agent","prompt-engineering","requirements-engineering","roundtable","software-architecture","software-design","spec-driven","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":null,"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/spec2ship.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2025-12-28T10:30:12.000Z","updated_at":"2026-01-15T18:08:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/spec2ship/spec2ship","commit_stats":null,"previous_names":["spec2ship/spec2ship"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/spec2ship/spec2ship","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spec2ship%2Fspec2ship","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spec2ship%2Fspec2ship/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spec2ship%2Fspec2ship/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spec2ship%2Fspec2ship/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spec2ship","download_url":"https://codeload.github.com/spec2ship/spec2ship/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spec2ship%2Fspec2ship/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28541068,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T14:59:57.589Z","status":"ssl_error","status_checked_at":"2026-01-18T14:59:46.540Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agents","ai-workflow","claude","claude-code","llm","multi-agent","prompt-engineering","requirements-engineering","roundtable","software-architecture","software-design","spec-driven","spec-driven-development"],"created_at":"2026-01-18T16:03:54.881Z","updated_at":"2026-01-18T16:03:55.654Z","avatar_url":"https://github.com/spec2ship.png","language":null,"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/hero.png\" alt=\"Spec2Ship\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003e\n  Spec-driven development framework that orchestrates multi-agent workflows on top of Claude Code\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://claude.ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/requires-Claude%20Code-blueviolet.svg\" alt=\"Requires Claude Code\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 🎯 What Spec2Ship Is\n\nSpec2Ship is a **Claude Code plugin** that adds structured orchestration for requirements, architecture, and implementation planning.\n\nThe core idea: instead of prompting Claude Code directly, you run **roundtable discussions** where multiple agents, each representing a real role, debate and refine decisions collaboratively.\n\n**It is:**\n- A spec-driven framework where specifications are treated as executable intent\n- An orchestration layer built on Claude Code primitives\n- A deliberation system with configurable facilitation strategies\n\n**It is not:**\n- A standalone CLI or generic tool (requires Claude Code)\n- A prompt library or template pack\n- A code generator (it produces specs and plans; you write the code)\n\n\u003e [!NOTE]\n\u003e Spec2Ship requires [Claude Code](https://claude.ai) to run. It extends Claude Code with structured workflows, not replaces it.\n\n---\n\n## ❓ Why Not Just Prompt Claude Code Directly?\n\nWhen you prompt Claude Code directly for requirements or architecture decisions:\n\n| What happens | The problem |\n|--------------|-------------|\n| Single perspective | Optimized for agreement rather than rigorous challenge |\n| No adversarial review | Security gaps, edge cases, feasibility issues missed |\n| Freeform output | Hard to review, audit, or hand off to team |\n| Ephemeral sessions | Context lost between conversations |\n| No structure | Each session starts from scratch |\n\n**Spec2Ship solves this** by:\n- Convening **12 specialized agents** with distinct viewpoints\n- Enforcing **structured discussion** via facilitation strategies\n- Producing **standards-based artifacts** (arc42, ISO 25010, MADR)\n- Persisting **sessions with full audit trail**\n- Supporting **escalation triggers** for human review\n\n---\n\n## ⚖️ How Spec2Ship Compares\n\n| Aspect | Spec2Ship | [Claude-Flow](https://github.com/ruvnet/claude-flow) | [Spec-Kit](https://github.com/github/spec-kit) | [OpenSpec](https://github.com/Fission-AI/OpenSpec) |\n|--------|-----------|-------------|----------|----------|\n| **Approach** | Multi-agent deliberation | Swarm task execution | Document checkpoints | Lightweight diffs |\n| **Agents** | 12 specialized roles debating | 54+ task workers | Single agent | Single agent |\n| **Quality mechanism** | Adversarial review built-in | Speed optimization | Human review points | Minimal overhead |\n| **Strategies** | 5 facilitation methods | Hierarchical/mesh | Linear | Linear |\n| **Output** | arc42, ISO 25010, MADR | Custom | Markdown | Diff-based |\n| **Best for** | Decisions needing debate | Parallel task execution | Greenfield features | Brownfield changes |\n\n**Choose Spec2Ship when:**\n- Decisions need multiple expert perspectives\n- You want adversarial review (security, scalability, edge cases)\n- Artifacts must be auditable and standards-based\n- You're already using Claude Code\n\n**Choose alternatives when:**\n- **Claude-Flow**: Parallel execution of many independent tasks\n- **Spec-Kit**: Simple greenfield specs with checkpoint review\n- **OpenSpec**: Incremental changes to existing codebases\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# 1. Add the plugin\n/plugin marketplace add spec2ship/spec2ship\n\n# 2. Install it\n/plugin install s2s\n\n# 3. Initialize your project\n/s2s:init\n\n# 4. Run your first roundtable\n/s2s:specs\n```\n\nAfter `/s2s:specs` completes, you'll have:\n- `.s2s/sessions/YYYYMMDD-specs-*.yaml`: full discussion transcript\n- `.s2s/requirements.md`: structured requirements with IDs (REQ-001, REQ-002...)\n\n\u003e [!TIP]\n\u003e For your first run, use `/s2s:specs --interactive` to pause after each round and see how the discussion unfolds.\n\n---\n\n## 🔄 Roundtable: The Core Primitive\n\nRoundtable is **the fundamental abstraction** of Spec2Ship.\n\nEvery major decision flows through a structured discussion:\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                        ROUNDTABLE                            │\n│                                                              │\n│  FACILITATOR                                                 │\n│  ├── Generates questions from agenda                         │\n│  ├── Prepares context for each participant                   │\n│  └── Synthesizes responses into artifacts                    │\n│                                                              │\n│  PARTICIPANTS (respond in parallel, blind to each other)     │\n│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐         │\n│  │    PM    │ │ Architect│ │ QA Lead  │ │ Security │  ...    │\n│  │          │ │          │ │          │ │ Champion │         │\n│  │  Value   │ │  System  │ │  Edge    │ │  Threat  │         │\n│  │ \u0026 scope  │ │  design  │ │  cases   │ │  model   │         │\n│  └──────────┘ └──────────┘ └──────────┘ └──────────┘         │\n│                                                              │\n│  OUTPUT: Numbered artifacts with provenance                  │\n│  REQ-001, ARCH-002, CONF-003...                              │\n└──────────────────────────────────────────────────────────────┘\n```\n\n### Why This Matters\n\n**Blind voting**: Participants respond without seeing each other. This prevents anchoring, reduces sycophancy, and surfaces genuine disagreements.\n\n**Role-based expertise**: Each agent anchors to domain principles:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eView all 12 specialized agents\u003c/strong\u003e\u003c/summary\u003e\n\n| Agent | Focus |\n|-------|-------|\n| **Product Manager** | User value, priorities, scope |\n| **Software Architect** | System structure, patterns, scalability |\n| **Technical Lead** | Implementation feasibility, effort |\n| **QA Lead** | Testability, edge cases, acceptance criteria |\n| **Security Champion** | Vulnerabilities, compliance, threat modeling |\n| **DevOps Engineer** | Deployment, monitoring, operational burden |\n| **UX Researcher** | Usability, accessibility, user journeys |\n| **Business Analyst** | Domain rules, use cases, requirements clarity |\n| **Documentation Specialist** | Clarity, completeness, maintainability |\n| **Claude Code Expert** | Platform constraints, best practices |\n| **OSS Community Manager** | Contributor experience, governance |\n\n\u003c/details\u003e\n\n**Concrete output**: Not chat transcripts, but structured artifacts:\n\n```markdown\n## REQ-001: User Authentication\n**Priority**: Must-have\n**Source**: Roundtable 20250117-specs-auth, Round 2\n**Acceptance Criteria**:\n- User can log in with email/password\n- Session expires after 24h inactivity\n- Failed attempts rate-limited (5/min)\n\n**Participants**: PM (proposed), Architect (refined), Security (hardened)\n**Agreement**: Consensus\n```\n\n### Facilitation Strategies\n\nDifferent decisions need different discussion structures:\n\n| Strategy | Phases | When to use |\n|----------|--------|-------------|\n| **Standard** | Single round | General input, simple decisions |\n| **Disney** | Dreamer → Realist → Critic | Creative exploration, new features |\n| **Debate** | Opening → Rebuttal → Closing | Trade-offs, technology choices |\n| **Consensus-Driven** | Propose → Refine → Converge | Requirements, team alignment |\n| **Six Hats** | Facts → Emotions → Risks → Benefits → Ideas → Process | Complex decisions needing thorough analysis |\n\nStrategies are auto-detected from topic keywords or explicitly specified:\n\n```bash\n/s2s:roundtable \"new payment flow\"           # → Disney (creative keyword)\n/s2s:roundtable \"REST vs GraphQL\"            # → Debate (comparison keyword)\n/s2s:design --strategy six-hats              # → Explicit override\n```\n\n---\n\n## 📋 Operational Flow\n\nSpec2Ship guides you through a real development pipeline:\n\n```\n┌──────────┐    ┌───────────┐    ┌───────┐    ┌────────┐    ┌──────┐\n│   init   │───▶│ brainstorm│───▶│ specs │───▶│ design │───▶│ plan │\n│          │    │ (optional)│    │       │    │        │    │      │\n│ Analyze  │    │ Explore   │    │ Define│    │ Decide │    │ Break│\n│ project  │    │ ideas     │    │ WHAT  │    │ HOW    │    │ down │\n└──────────┘    └───────────┘    └───────┘    └────────┘    └──────┘\n```\n\n### What happens at each phase\n\n| Command | What runs | What's produced |\n|---------|-----------|-----------------|\n| `/s2s:init` | Project analysis | `.s2s/CONTEXT.md`, `config.yaml` |\n| `/s2s:brainstorm \"topic\"` | Disney roundtable | Ideas, risks, mitigations |\n| `/s2s:specs` | Consensus-driven roundtable | `requirements.md` with REQ-*, BR-*, NFR-* |\n| `/s2s:design` | Debate roundtable | `architecture.md` + ADRs with ARCH-*, COMP-* |\n| `/s2s:plan` | Plan generation | `plans/*.md` with tasks and dependencies |\n\nEach phase can run independently. Missing prerequisites trigger prompts, not failures.\n\n---\n\n## 🤖 Autonomous vs Interactive Mode\n\nSpec2Ship supports both modes. This is a **design choice**, not a limitation.\n\n### Autonomous Mode (default)\n\nRoundtables run end-to-end without interruption:\n\n```bash\n/s2s:specs    # Runs complete requirements roundtable\n```\n\nThe facilitator manages all rounds automatically. Results are written to session files for review after completion.\n\n### Interactive Mode\n\nHuman-in-the-loop when you want control:\n\n```bash\n/s2s:specs --interactive    # Pauses after each round\n```\n\nYou review each round's output and can redirect the discussion.\n\n### Escalation Triggers\n\nEven in autonomous mode, the system pauses for human input when:\n- **Low confidence** (\u003c50%) on a decision\n- **Critical keywords**: \"security vulnerability\", \"legal requirement\", \"breaking change\"\n- **Unresolved conflicts** after maximum rounds\n- **Blocking questions** that prevent progress\n\n\u003e [!IMPORTANT]\n\u003e Spec2Ship knows when to ask for help. It's not a black-box generator.\n\n\u003e [!TIP]\n\u003e **Disable auto-compact for better control.** Run `/config` and set \"Auto-compact\" to `false`. Auto-compact triggers at ~85% context and may interrupt the facilitator mid-round, compromising context passed to participants. Sessions save all artifacts, so you can resume if needed, but completing each round uninterrupted produces better results.\n\n\u003e [!WARNING]\n\u003e **Avoid permission interrupts.** Start Claude Code with `claude --dangerously-skip-permissions` to prevent permission prompts during roundtable execution. Workflows invoke multiple tools in sequence, and permission dialogs can disrupt the facilitator's flow.\n\n---\n\n## 📐 Supported Standards\n\nSpecifications and designs use established formats:\n\n| Standard | Used for | Output example |\n|----------|----------|----------------|\n| **arc42** | Architecture documentation | Context, components, runtime views |\n| **ISO 25010** | Quality requirements | Performance, security, maintainability targets |\n| **MADR** | Decision records | Options, rationale, consequences |\n| **STRIDE** | Threat modeling | Threat categories, mitigations |\n| **Conventional Commits** | Commit messages | `feat(auth): add OAuth2 support` |\n\nWhy this matters:\n- **Determinism**: Same input → predictable structure\n- **Reviewability**: Teams can audit decisions\n- **Handoff**: Artifacts work across tools and people\n\n---\n\n## 💻 Commands\n\n### Workflow\n\n| Command | Purpose | Default strategy |\n|---------|---------|------------------|\n| `/s2s:init` | Analyze project, create context | - |\n| `/s2s:brainstorm \"topic\"` | Creative exploration | Disney |\n| `/s2s:specs` | Define requirements | Consensus-driven |\n| `/s2s:design` | Design architecture | Debate |\n| `/s2s:plan` | Generate implementation plan | - |\n| `/s2s:roundtable \"topic\"` | Generic roundtable | Auto-detected |\n\n### Session management\n\n| Command | Purpose |\n|---------|---------|\n| `/s2s:session` | Current session status |\n| `/s2s:session:list` | List all sessions |\n| `/s2s:session:validate` | Check consistency |\n| `/s2s:session:close` | Close active session |\n\n### Flags\n\n| Flag | Effect |\n|------|--------|\n| `--strategy \u003cname\u003e` | Override facilitation strategy |\n| `--participants \u003clist\u003e` | Specify which agents participate |\n| `--interactive` | Pause after each round |\n| `--verbose` | Save detailed round dumps |\n\n---\n\n## 🔧 Extensibility\n\nSpec2Ship is designed to be extended:\n\n| What | How |\n|------|-----|\n| New agent role | Add `agents/roundtable/{name}.md` |\n| New strategy | Add to `skills/roundtable-strategies/` |\n| New output format | Add template to `templates/` |\n| New workflow | Add `commands/{name}.md` |\n\n\u003e [!TIP]\n\u003e For extension guides, ask Claude: `\"how to extend s2s\"` (loads the s2s-guide skill with step-by-step instructions).\n\n---\n\n## 📚 Documentation\n\n- [Core Concepts](docs/): workflows, roundtables, sessions\n- [Architecture](docs/architecture/): system design and ADRs\n\nFor interactive help:\n- `\"what commands does s2s have\"`: command reference\n- `\"how do roundtables work\"`: detailed explanation\n- `\"how to create a new agent\"`: extension guide\n\n---\n\n## 🗺️ Roadmap\n\nSee [BACKLOG.md](.s2s/BACKLOG.md) for planned work.\n\n---\n\n## 🤝 Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## 📄 License\n\nMIT - see [LICENSE](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspec2ship%2Fspec2ship","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspec2ship%2Fspec2ship","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspec2ship%2Fspec2ship/lists"}