{"id":43676213,"url":"https://github.com/lgbarn/shipyard","last_synced_at":"2026-04-07T02:01:38.670Z","repository":{"id":335728087,"uuid":"1146807130","full_name":"lgbarn/shipyard","owner":"lgbarn","description":"Structured project lifecycle plugin for Claude Code — from idea to production with discipline, parallel agents, and quality gates.","archived":false,"fork":false,"pushed_at":"2026-04-01T23:40:37.000Z","size":1176,"stargazers_count":50,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-03T01:13:05.463Z","etag":null,"topics":["ai-agents","claude-code","claude-code-plugin","cli-plugin","code-review","developer-tools","infrastructure-as-code","project-management","security-audit","tdd"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/lgbarn.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-01-31T17:58:23.000Z","updated_at":"2026-04-01T23:37:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lgbarn/shipyard","commit_stats":null,"previous_names":["lgbarn/shipyard"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/lgbarn/shipyard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgbarn%2Fshipyard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgbarn%2Fshipyard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgbarn%2Fshipyard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgbarn%2Fshipyard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lgbarn","download_url":"https://codeload.github.com/lgbarn/shipyard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lgbarn%2Fshipyard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31496769,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"online","status_checked_at":"2026-04-07T02:00:07.164Z","response_time":105,"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":["ai-agents","claude-code","claude-code-plugin","cli-plugin","code-review","developer-tools","infrastructure-as-code","project-management","security-audit","tdd"],"created_at":"2026-02-05T01:04:53.976Z","updated_at":"2026-04-07T02:01:38.644Z","avatar_url":"https://github.com/lgbarn.png","language":"Shell","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/shipyard_logo.png\" alt=\"Shipyard Logo\" width=\"400\"\u003e\n\u003c/p\u003e\n\n# Shipyard\n\nA Claude Code plugin for structured project execution. Plan work in phases, build with parallel agents and TDD, review with security audits and quality gates, and ship with confidence.\n\n```\nIDEA → /init → /brainstorm → /plan → /build → /ship → SHIPPED\n         ↑\n         ├── or: /import-spec (from spec-kit) → /plan → /build → /ship\n         └── or: /import-spec-file (handwritten spec) → /plan → /build → /ship\n```\n\n## Prerequisites\n\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and authenticated\n- `jq` (used by session hooks for state injection)\n\n## Installation\n\n### From GitHub (recommended)\n\n```bash\nclaude plugin marketplace add lgbarn/shipyard\nclaude plugin install shipyard@shipyard\n```\n\n### From a local clone\n\n```bash\ngit clone git@github.com:lgbarn/shipyard.git\nclaude plugin marketplace add /absolute/path/to/shipyard\nclaude plugin install shipyard@shipyard\n```\n\n### Verify\n\n```bash\nclaude /shipyard:status\n```\n\n## Quick Start\n\nOnce installed, navigate to any project directory and run:\n\n```bash\n# Configure project preferences\n/shipyard:init\n\n# Explore requirements interactively\n/shipyard:brainstorm\n\n# Plan a phase\n/shipyard:plan 1\n\n# Build it\n/shipyard:build\n\n# Ship it\n/shipyard:ship\n```\n\nFor the full command reference and common workflows, see [docs/QUICKSTART.md](docs/QUICKSTART.md).\n\n## spec-kit Integration\n\nShipyard integrates with [spec-kit](https://github.com/github/spec-kit) (GitHub's Spec-Driven Development toolkit), letting you use spec-kit's structured specification workflow as a higher-quality alternative to `/shipyard:brainstorm`.\n\n### How It Works\n\nspec-kit produces a rich set of artifacts in `specs/[###-feature]/`:\n\n| spec-kit artifact | Mapped to |\n|---|---|\n| `spec.md` (user stories, acceptance criteria) | `.shipyard/PROJECT.md` |\n| `.specify/constitution.md` (project principles) | PROJECT.md constraints section |\n| `plan.md` (technical implementation plan) | Input for ROADMAP.md generation |\n| `research.md` + `data-model.md` + `contracts/` | `.shipyard/phases/1/RESEARCH.md` |\n| `tasks.md` (flat task list with `[P]` markers) | `.shipyard/phases/1/SPECKIT-TASKS.md` — seeds the architect |\n\nThe `/shipyard:plan` command automatically detects these staged artifacts:\n- **Skips the researcher agent** when `RESEARCH.md` already exists\n- **Seeds the architect** with `SPECKIT-TASKS.md` to generate accurate wave/plan decomposition with less hallucination\n\n### Workflow\n\n```bash\n# 1. Use spec-kit to build the spec\n/speckit.specify   My feature description\n/speckit.plan      Tech stack choices\n/speckit.tasks\n\n# 2. Import into Shipyard (replaces /shipyard:brainstorm)\n/shipyard:import-spec specs/001-my-feature\n\n# 3. Continue with the normal Shipyard pipeline\n/shipyard:plan 1   # researcher skipped, architect seeded from tasks.md\n/shipyard:build 1\n/shipyard:ship\n```\n\n`/shipyard:import-spec` also handles:\n- **Auto-discovery**: if no argument is given, lists available `specs/` directories\n- **`[NEEDS CLARIFICATION]` markers**: surfaced as an Open Questions section in PROJECT.md rather than silently dropped\n- **Existing PROJECT.md**: asks whether to replace or merge\n\n## Handwritten Spec Import\n\nDon't have spec-kit? Use `/shipyard:import-spec-file` to import any existing specification document directly — architecture docs, requirements files, validation specs, RFC-style documents, or anything written by hand.\n\n```bash\n# Import a handwritten spec file\n/shipyard:import-spec-file docs/my-feature-spec.md\n/shipyard:import-spec-file /path/to/validation-spec.md\n\n# Or let Shipyard auto-discover spec files in the project root\n/shipyard:import-spec-file\n```\n\nThe command reads the spec, maps its sections to PROJECT.md, then conducts a short interview to fill any gaps the spec doesn't cover (integration context, success criteria, non-goals). The spec itself is staged as `RESEARCH.md` so every downstream agent — architect, builder, reviewer — has full access to the original rules during planning and implementation.\n\n`/shipyard:import-spec-file` handles:\n- **Any spec format**: sections are mapped heuristically (Overview → Description, Rules/Requirements → Functional Requirements, Open Questions → Open Questions, etc.)\n- **Gap-filling interview**: asks 2-5 focused questions about what the spec doesn't define\n- **Brownfield-aware routing**: suggests `/shipyard:map` first if the project has existing source code without codebase docs\n- **Existing PROJECT.md**: asks whether to replace or merge\n\n## Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/shipyard:init` | Configure project preferences and create `.shipyard/` directory |\n| `/shipyard:brainstorm` | Explore requirements through interactive dialogue |\n| `/shipyard:import-spec [feature-path]` | Import a spec-kit feature spec, replacing brainstorming |\n| `/shipyard:import-spec-file [file-path]` | Import a handwritten spec file; interviews to fill gaps |\n| `/shipyard:plan [phase] [--skip-research]` | Plan a phase of work (creates roadmap if needed) |\n| `/shipyard:build [phase] [--plan N] [--light]` | Execute plans with parallel builder agents and review gates |\n| `/shipyard:status` | Show progress dashboard and route to next action |\n| `/shipyard:resume` | Restore context from a previous session |\n| `/shipyard:quick [task]` | Execute a small task with full guarantees |\n| `/shipyard:ship [--phase \\| --milestone \\| --branch]` | Verify and deliver — merge, PR, or preserve |\n| `/shipyard:settings` | View or update workflow settings |\n| `/shipyard:issues [--add \\| --resolve \\| --list]` | View and manage deferred issues across sessions |\n| `/shipyard:rollback [checkpoint] [--list]` | Revert to a previous checkpoint |\n| `/shipyard:recover` | Diagnose and recover from interrupted state |\n| `/shipyard:move-docs` | Move codebase analysis docs between `.shipyard/codebase/` and `docs/codebase/` |\n| `/shipyard:worktree [create\\|list\\|switch\\|remove] [name]` | Manage git worktrees for isolated feature development |\n| `/shipyard:review [target]` | On-demand code review — current changes, diff range, or files |\n| `/shipyard:audit [scope]` | On-demand security audit — OWASP, secrets, dependencies, IaC |\n| `/shipyard:simplify [scope]` | On-demand simplification — duplication, dead code, complexity |\n| `/shipyard:document [scope]` | On-demand documentation generation for changes or modules |\n| `/shipyard:research \u003ctopic\u003e` | On-demand domain/technology research and comparison |\n| `/shipyard:verify [criteria]` | On-demand verification — run tests or check acceptance criteria |\n| `/shipyard:map [focus]` | On-demand codebase analysis — defaults to all 4 focus areas (technology, architecture, quality, concerns) |\n| `/shipyard:help [topic]` | Quick-reference table or detailed help for a specific command/skill |\n| `/shipyard:doctor` | Health-check diagnostic — jq, git, skills, hooks, `.shipyard/` structure |\n| `/shipyard:cancel` | Graceful build interruption — checkpoint, pause, resume later |\n| `/shipyard:debug [description]` | Root-cause analysis with 5 Whys protocol via debugger agent |\n\n## Skills (Auto-Activating)\n\nShipyard includes 19 skills that Claude invokes automatically when trigger conditions match:\n\n| Skill | When It Activates |\n|-------|-------------------|\n| `shipyard-tdd` | Writing any new code, features, or fixes |\n| `shipyard-debugging` | Any error, test failure, or unexpected behavior |\n| `shipyard-verification` | Before claiming any task is complete |\n| `shipyard-brainstorming` | Creative work: features, components, design |\n| `security-audit` | Working with code, configs, dependencies, or IaC |\n| `code-simplification` | After implementation, before shipping, reviewing AI code |\n| `documentation` | After implementation, before shipping, when docs are incomplete |\n| `infrastructure-validation` | Working with Terraform, Ansible, Docker, or IaC files |\n| `parallel-dispatch` | 2+ independent tasks that can run concurrently |\n| `shipyard-writing-plans` | Creating implementation plans |\n| `shipyard-executing-plans` | Implementing from a written plan |\n| `git-workflow` | Branch management, commits, delivery |\n| `using-shipyard` | Every session (skill discovery protocol) |\n| `shipyard-testing` | Writing effective, maintainable tests |\n| `shipyard-writing-skills` | Creating new skills |\n| `shipyard-handoff` | Session transfer: \"handoff\", \"I'm done for now\", \"save context\" |\n| `lessons-learned` | After phase completion, before shipping, reflecting on work |\n| `import-spec` | Importing a spec-kit feature directory into Shipyard |\n| `import-spec-file` | Importing a handwritten spec document into Shipyard |\n\n## Agents\n\nShipyard dispatches 10 specialized agents for different phases of work:\n\n| Agent | Role | Default Model | Dispatched By |\n|-------|------|---------------|---------------|\n| **mapper** | Brownfield codebase analysis (4 parallel instances) | sonnet | `/shipyard:map` |\n| **researcher** | Domain/technology research | sonnet | `/shipyard:plan`, `/shipyard:research` |\n| **architect** | Roadmap + plan decomposition | opus | `/shipyard:brainstorm`, `/shipyard:plan`, `/shipyard:quick` |\n| **builder** | Task execution with TDD, IaC validation, atomic commits | sonnet | `/shipyard:build`, `/shipyard:quick` |\n| **reviewer** | Two-stage code review (spec + quality) | sonnet | `/shipyard:build`, `/shipyard:review` |\n| **auditor** | Comprehensive security \u0026 compliance analysis | sonnet | `/shipyard:build`, `/shipyard:ship`, `/shipyard:audit` |\n| **simplifier** | Cross-task duplication and complexity analysis | sonnet | `/shipyard:build`, `/shipyard:simplify` |\n| **documenter** | Documentation generation \u0026 updates | sonnet | `/shipyard:build`, `/shipyard:ship`, `/shipyard:document` |\n| **verifier** | Post-execution verification (including IaC) | haiku | `/shipyard:plan`, `/shipyard:build`, `/shipyard:ship`, `/shipyard:verify` |\n| **debugger** | Root-cause analysis with 5 Whys protocol | sonnet | `/shipyard:debug` |\n\nAll agents have formal definition files in `.claude/agents/` with tool restrictions and model defaults. See [`docs/AGENT-GUIDE.md`](docs/AGENT-GUIDE.md) for detailed documentation including model assignments, tool access, and composition patterns.\n\n## Agent Teams Support\n\nShipyard now supports [Claude Code Agent Teams](https://docs.anthropic.com/en/docs/claude-code) — an experimental feature where multiple independent Claude Code instances collaborate on the same project by sharing a task list and mailbox.\n\n### How It Works\n\nShipyard's standard execution model uses **subagents** (the Task tool) to dispatch builders, reviewers, and other agents. Each subagent runs within the lead agent's session, sharing its working directory but with a fresh context window. This is efficient for coordinated work where the lead needs to collect results and make decisions.\n\n**Agent Teams** introduces a different model: independent Claude Code instances (teammates) that each have their own full session, context window, and tool access. They coordinate through a shared task list and mailbox rather than through a parent-child relationship.\n\nShipyard detects the teams environment automatically — **no configuration needed:**\n\n| Environment Variable | Set By | Meaning |\n|---------------------|--------|---------|\n| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | You (opt-in) | Enables the teams feature in Claude Code |\n| `CLAUDE_CODE_TEAM_NAME` | Claude Code (automatic) | Identifies this instance as a teammate |\n\nWhen teams are detected, Shipyard adapts its behavior:\n\n| Behavior | Solo Mode (default) | Teammate Mode |\n|----------|-------------------|---------------|\n| Task execution | Dispatches builder subagents | Executes tasks directly (you ARE the builder) |\n| Quality gates | Lead dispatches auditor/simplifier | Lead handles quality gates; teammates skip |\n| State updates | Writes STATE.json directly | Reports via task metadata (lead writes state) |\n| State file locking | No locking needed | mkdir-based locking prevents concurrent writes |\n| Verification | Standard pipeline | Runs locally, reports via task metadata |\n| Stopping work | No gates | `TeammateIdle` hook verifies tests pass first |\n| Completing tasks | No gates | `TaskCompleted` hook verifies evidence exists |\n\n### Enabling Agent Teams\n\n1. **Enable the experimental feature** in your Claude Code configuration:\n   ```bash\n   export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1\n   ```\n\n2. **Use Claude Code normally.** When Claude Code spawns teammates, Shipyard automatically detects the team environment and adapts.\n\n3. **Solo users are completely unaffected.** If you don't set the environment variable, Shipyard behaves exactly as before — no locking, no hooks, no behavioral changes.\n\n### When to Use Teams vs Subagents\n\n- **Use subagents** (Shipyard's default) when tasks are tightly coordinated, results need to flow back to a lead agent, or when you want the standard build pipeline (builder → reviewer → auditor).\n- **Use teams** when tasks are truly independent, each takes significant time, and you want full isolation between workers to prevent context cross-contamination.\n\nTeams and subagents are complementary. A lead agent in a team can still dispatch subagents for tightly-coupled subtasks within its assigned work.\n\nSee [docs/AGENT-TEAMS-GUIDE.md](docs/AGENT-TEAMS-GUIDE.md) for the full Agent Teams usage guide.\n\n## How It Works\n\n### The Lifecycle\n\n```\nIDEA → /init (configure preferences)\n     → /brainstorm (explore requirements)           ← interactive dialogue\n     → OR /import-spec (from spec-kit artifacts)    ← spec-driven alternative\n     → OR /import-spec-file (handwritten spec)      ← existing doc alternative\n     → /plan (research + decompose)\n     → /build (parallel execute + review)\n     → repeat plan→build per phase\n     → /ship (verify + deliver)\n     → SHIPPED\n```\n\n### State Management\n\nShipyard uses a dual state system:\n\n- **File state** (`.shipyard/` directory): Cross-session persistence for project vision, roadmap, plans, and progress. Survives session restarts and can be committed to git. Includes backup-on-write (`.bak`), SHA-256 checksums, and working notes (`NOTES.md`) for compaction resilience.\n- **Native tasks** (TaskCreate/TaskUpdate): In-session UI visibility showing real-time progress of phases and plans.\n\n### Key Design Principles\n\n- **Fresh context per task**: Each builder agent runs in a clean 200k-token context, preventing quality degradation\n- **Two-stage review + security audit**: Spec compliance and code quality per task, comprehensive security audit per phase\n- **Configurable gates**: Security audit, simplification review, and IaC validation can be toggled in `config.json` or skipped with `--light`. Hook kill switch (`SHIPYARD_DISABLE_HOOKS`) available for debugging\n- **Code simplification**: Post-phase analysis catches AI-generated duplication and bloat across tasks\n- **Documentation generation**: Post-phase documentation keeps docs synchronized with code changes\n- **IaC support**: Terraform, Ansible, Docker validation workflows built into the builder and verifier\n- **Context engineering (WISC)**: Phase-scoped loading reduces context noise, handoff protocol enables clean session transfers, micro-lessons provide within-phase feedback, agent metrics surface task sizing issues. See [`docs/CONTEXT-ENGINEERING.md`](docs/CONTEXT-ENGINEERING.md)\n- **Max 3 tasks per plan**: Keeps each agent's workload within the quality budget\n- **Atomic commits**: Every task produces a separate, revertable commit\n- **Phase-based planning**: Break large projects into manageable phases with clear success criteria\n\n## Project State Structure\n\n```\n.shipyard/\n├── PROJECT.md          # Vision, decisions, constraints\n├── ROADMAP.md          # Phase structure with success criteria\n├── STATE.json          # Current position, machine state (JSON)\n├── STATE.json.bak      # Automatic backup (corruption fallback)\n├── STATE.json.sha256   # Checksum for integrity verification\n├── HISTORY.md          # Append-only audit trail\n├── NOTES.md            # Working notes (compaction-resilient, auto-cleared per phase)\n├── HANDOFF.md          # Session transfer context (consumed one-shot on next start)\n├── config.json         # Workflow preferences\n├── codebase/           # Brownfield analysis (default; or docs/codebase/ if configured)\n├── phases/\n│   └── 01-{name}/\n│       ├── RESEARCH.md\n│       ├── 01-PLAN.md\n│       ├── 01-SUMMARY.md\n│       ├── VERIFICATION.md\n│       ├── MICRO-LESSONS.md      # Within-phase builder takeaways\n│       ├── AGENT-METRICS.md      # Agent context consumption log\n│       ├── AUDIT-{N}.md          # Security audit report\n│       ├── SIMPLIFICATION-{N}.md # Code simplification report\n│       └── DOCUMENTATION-{N}.md  # Documentation generation report\n└── quick/              # Ad-hoc tasks\n```\n\n## Plugin Structure\n\n```\nshipyard/\n├── .claude-plugin/\n│   ├── marketplace.json   # Marketplace metadata (version, category)\n│   └── plugin.json        # Plugin definition (name, description)\n├── agents/                # Subagent dispatch prompts (used by commands)\n│   ├── architect.md       # Roadmap and plan decomposition\n│   ├── auditor.md         # Security and compliance analysis\n│   ├── builder.md         # Task execution with TDD\n│   ├── debugger.md        # Root-cause analysis with 5 Whys\n│   ├── documenter.md      # Documentation generation\n│   ├── mapper.md          # Brownfield codebase analysis\n│   ├── researcher.md      # Domain/technology research\n│   ├── reviewer.md        # Two-stage code review\n│   ├── simplifier.md      # Complexity and duplication analysis\n│   └── verifier.md        # Post-execution verification\n├── commands/              # Slash command definitions\n│   ├── audit.md           # /shipyard:audit\n│   ├── brainstorm.md      # /shipyard:brainstorm\n│   ├── build.md           # /shipyard:build\n│   ├── cancel.md          # /shipyard:cancel\n│   ├── debug.md           # /shipyard:debug\n│   ├── doctor.md          # /shipyard:doctor\n│   ├── document.md        # /shipyard:document\n│   ├── help.md            # /shipyard:help\n│   ├── init.md            # /shipyard:init\n│   ├── issues.md          # /shipyard:issues\n│   ├── map.md             # /shipyard:map\n│   ├── move-docs.md       # /shipyard:move-docs\n│   ├── plan.md            # /shipyard:plan\n│   ├── quick.md           # /shipyard:quick\n│   ├── recover.md         # /shipyard:recover\n│   ├── research.md        # /shipyard:research\n│   ├── resume.md          # /shipyard:resume\n│   ├── review.md          # /shipyard:review\n│   ├── rollback.md        # /shipyard:rollback\n│   ├── settings.md        # /shipyard:settings\n│   ├── ship.md            # /shipyard:ship\n│   ├── simplify.md        # /shipyard:simplify\n│   ├── status.md          # /shipyard:status\n│   ├── verify.md          # /shipyard:verify\n│   └── worktree.md        # /shipyard:worktree\n├── docs/\n│   ├── AGENT-GUIDE.md        # Detailed agent documentation\n│   ├── AGENT-TEAMS-GUIDE.md  # Agent teams usage guide\n│   ├── COMPARISON.md         # Feature comparison with other frameworks\n│   ├── CONTEXT-ENGINEERING.md # WISC context engineering design\n│   ├── MIGRATION-v3-v4.md    # Upgrade guide for v4.0 breaking changes\n│   ├── PROTOCOLS.md          # Model routing and config.json reference\n│   ├── QUICKSTART.md         # Command reference and common workflows\n│   └── STATE-SCHEMA.md       # STATE.json field definitions and schema history\n├── .claude/\n│   └── agents/            # Agent definition files with tool restrictions\n│       ├── shipyard-architect.md\n│       ├── shipyard-auditor.md\n│       ├── shipyard-builder.md\n│       ├── shipyard-debugger.md\n│       ├── shipyard-documenter.md\n│       ├── shipyard-mapper.md\n│       ├── shipyard-researcher.md\n│       ├── shipyard-reviewer.md\n│       ├── shipyard-simplifier.md\n│       └── shipyard-verifier.md\n├── hooks/\n│   ├── hooks.json         # Hook registry (SessionStart, TeammateIdle, TaskCompleted, PreToolUse, Stop)\n│   ├── teammate-idle.sh   # TeammateIdle quality gate (teams only)\n│   ├── task-completed.sh  # TaskCompleted quality gate (phase-specific evidence)\n│   ├── pre-tool-use.sh    # PreToolUse protocol compliance nudges\n│   └── stop.sh            # SessionEnd build interruption tracking\n├── scripts/\n│   ├── state-read.sh      # Adaptive context loading on session start\n│   ├── state-write.sh     # Updates .shipyard/STATE.json (teams-aware locking)\n│   ├── team-detect.sh     # Detects Claude Code Agent Teams environment\n│   ├── hook-log.sh        # Hook failure logging with rotation\n│   ├── checkpoint.sh      # Git tag checkpoint management\n│   ├── check-versions.sh  # Version sync validation\n│   └── marketplace-sync.sh # Marketplace metadata sync\n├── skills/                # Auto-activating skill definitions\n│   ├── code-simplification/\n│   ├── documentation/\n│   ├── git-workflow/\n│   ├── infrastructure-validation/\n│   ├── lessons-learned/\n│   ├── parallel-dispatch/\n│   ├── security-audit/\n│   ├── shipyard-brainstorming/\n│   ├── shipyard-debugging/\n│   ├── shipyard-executing-plans/\n│   ├── shipyard-handoff/\n│   ├── shipyard-tdd/\n│   ├── shipyard-testing/\n│   ├── shipyard-verification/\n│   ├── shipyard-writing-plans/\n│   ├── shipyard-writing-skills/\n│   └── using-shipyard/\n├── test/                  # bats-core test suite (dev only)\n│   ├── run.sh             # Test runner\n│   ├── test_helper.bash   # Shared fixtures\n│   ├── state-read.bats\n│   ├── state-write.bats   # Includes teams-aware locking tests\n│   ├── checkpoint.bats\n│   ├── check-versions.bats # Version sync tests\n│   ├── marketplace-sync.bats # Marketplace sync tests\n│   ├── integration.bats\n│   ├── e2e-smoke.bats\n│   ├── hook-log.bats      # Hook failure logging tests\n│   ├── team-detect.bats   # Team detection tests\n│   └── team-hooks.bats    # TeammateIdle and TaskCompleted tests\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── LICENSE\n├── README.md\n├── package.json\n└── package-lock.json\n```\n\n## Configuration\n\nWhen you run `/shipyard:init`, Shipyard creates a `.shipyard/config.json` in your project with these options:\n\n| Option | Values | Default | Description |\n|--------|--------|---------|-------------|\n| `interaction_mode` | `interactive`, `autonomous` | — | Approve each phase or execute full roadmap |\n| `git_strategy` | `per_task`, `per_phase`, `manual` | — | When to create git commits |\n| `review_depth` | `detailed`, `lightweight` | — | Review gate depth between build steps |\n| `security_audit` | `true`, `false` | `true` | Run security audit after each phase |\n| `simplification_review` | `true`, `false` | `true` | Check for duplication and complexity |\n| `iac_validation` | `auto`, `true`, `false` | `auto` | Validate Terraform/Ansible/Docker changes |\n| `documentation_generation` | `true`, `false` | `true` | Generate docs after each phase |\n| `codebase_docs_path` | `.shipyard/codebase`, `docs/codebase` | `.shipyard/codebase` | Where brownfield analysis docs are stored |\n| `model_routing` | object | see `docs/PROTOCOLS.md` | Model selection per task type |\n| `context_tier` | `auto`, `minimal`, `planning`, `execution`, `brownfield`, `full` | `auto` | Context loading at session start |\n| `context_phase_scope` | `true`, `false` | `true` | Scope ROADMAP loading to current phase in execution tier |\n| `context_warn_threshold` | integer (chars) | `8000` | Warn when assembled context exceeds this size |\n| `plan_critique` | `true`, `false` | `true` | Run feasibility stress test on generated plans |\n\nSee `docs/PROTOCOLS.md` for model routing configuration and the full config.json skeleton.\n\n## Environment Variables\n\n**User-configurable:**\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SHIPYARD_LOCK_MAX_RETRIES` | `120` | Max lock acquisition attempts in team mode (range: 1-600) |\n| `SHIPYARD_DISABLE_HOOKS` | unset | Set to `true` to disable all Shipyard hooks |\n| `SHIPYARD_SKIP_HOOKS` | unset | Comma-separated list of hook names to skip (e.g., `stop,teammate-idle`) |\n\n**Auto-detected (do not set manually):**\n\n| Variable | Description |\n|----------|-------------|\n| `SHIPYARD_TEAMS_ENABLED` | `true` when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` |\n| `SHIPYARD_IS_TEAMMATE` | `true` when running as a teammate in agent teams |\n| `SHIPYARD_TEAM_NAME` | Copy of `CLAUDE_CODE_TEAM_NAME` |\n\n**Claude Code-managed:**\n\n| Variable | Description |\n|----------|-------------|\n| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Feature flag for agent teams (`1` = enabled) |\n| `CLAUDE_CODE_TEAM_NAME` | Set when running as teammate |\n\nNote: Lock retry uses exponential backoff (0.05s start, doubles each retry, 1.0s cap). This is not configurable.\n\n## Memory\n\nShipyard v3.0 removed its built-in episodic memory system in favor of Claude's native memory, which provides better recall, zero maintenance, and cross-tool context automatically. See [CHANGELOG.md](CHANGELOG.md) for details on this change.\n\n## Feature Comparison\n\nSee [docs/COMPARISON.md](docs/COMPARISON.md) for a detailed comparison of Shipyard with other Claude Code project frameworks.\n\n## Acknowledgments\n\nShipyard draws inspiration from:\n\n- [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent — composable skills, TDD discipline, two-stage code review\n- [GSD (Get Shit Done)](https://gsd.site/) by TÂCHES — project lifecycle management, phase-based planning, context engineering\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for how to add commands, skills, and agents, run tests, and submit pull requests.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flgbarn%2Fshipyard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flgbarn%2Fshipyard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flgbarn%2Fshipyard/lists"}