shipwithai-plugins

June 1, 2026 · View on GitHub

Generated by /shipwithai-starter on 2026-05-28. Edit directly — every skill reads this before doing anything.

Project identity

Name: shipwithai-plugins Type: Monorepo Team size: 1 developer Stage: Active

Tech stack

Language(s): Markdown + JSON (plugin authoring) Framework(s): ShipWithAI Claude Code plugin standard Build tool: None Test framework: None (evals/evals.json per skill) Package manager: None Safety hooks: Python 3 (stdlib only)

Architecture overview

Style: Monorepo — one directory per plugin

Key layers:

  • Plugin layer: plugins/<plugin-name>/ — one Claude Code plugin per directory
  • Skills layer: plugins/<plugin-name>/skills/<skill-name>/ — SKILL.md + assets + references + evals
  • Hooks layer: .claude/hooks/ — validate-command.py, protect-files.py, observe.py
  • Docs layer: docs/ — architecture, ADRs, CODEMAPS
  • Scripts layer: scripts/ — publish-plugin.sh for releasing plugins

Entry points:

  • plugins/*/manifest.json — Claude Code reads this to discover skills

Key directories:

shipwithai-plugins/
├── plugins/
│   └── <plugin-name>/
│       ├── skills/<skill-name>/
│       │   ├── SKILL.md          ← 500-line hard cap
│       │   ├── assets/           ← templates for user codegen (handle with care)
│       │   ├── references/       ← lazy-loaded reference docs (< 300 lines)
│       │   └── evals/evals.json  ← 5+ test prompts
│       ├── manifest.json         ← skill registry (must stay in sync)
│       ├── plugin.json           ← plugin metadata
│       ├── CHANGELOG.md
│       └── README.md             ← live SSOT, update after every change
├── .claude/
│   ├── settings.json
│   ├── starter-context.json
│   └── hooks/                    ← validate-command.py, protect-files.py, observe.py
├── docs/
│   ├── ARCHITECTURE.md
│   ├── adr/                      ← Architecture Decision Records
│   ├── CODEMAPS/                 ← codebase navigation guide
│   ├── starter/                  ← starter plugin PRDs and specs
│   └── superpowers/              ← plans and specs for superpowers skills
│       ├── plans/
│       └── specs/
└── scripts/
    └── publish-plugin.sh         ← always confirm before running

External dependencies: None

Key conventions

Code style: None (content-only workspace) Branch strategy: Gitflow (feature/ → develop → main) Commit format: Conventional commits (feat/fix/chore/docs:) Test coverage target: N/A — validate with evals/evals.json (5+ prompts per skill)

Plugin file naming:

  • Skill directories: lowercase with dashes (e.g. auth-setup)
  • SKILL.md: always uppercase filename
  • Reference files: lowercase with dashes
  • Database tables: n/a

What Claude should know before touching code

Gotchas:

  • plugins/*/manifest.json — must stay in sync with actual skills/ subdirectories; never add a skill without updating the manifest
  • .claude/hooks/*.py — safety hooks, must not be removed or broken
  • plugins/*/skills/*/assets/ — template files consumed verbatim by Claude Code in user projects; edits change what gets generated downstream
  • .claude-plugin/marketplace.json — plugin registry metadata
  • README.md and plugin docs — live SSOT, must be updated whenever a plugin or skill is added or changed

Build order: None

Test isolation: None — run eval prompts manually on 2+ real projects before shipping

Sensitive areas (extra care):

  • assets/ directories — template files for user project codegen
  • manifest.json files — skill registry, must stay in sync with skills/ directory
  • SKILL.md files — published to users; 500-line hard cap, ideal < 300 lines
  • evals/evals.json files — test prompts must remain runnable and cover the skill

Workflow

  • New plugin/skill: Read plugin-blueprint-standard.md and plugin-blueprint-advanced.md from the blueprint path before any work. Create PLAN.md and wait for approval before writing files.
  • Updating existing plugin: Read UPDATE-WORKFLOW.md from the blueprint path. Audit all SKILL.md files and manifest before proposing changes.
  • Never create or modify skills without an approved plan.
  • After every change: Update the relevant README.md and plugin docs (live SSOT).

Commands

No build/test commands — content-only workspace. Plugin files are SKILL.md, manifest.json, and reference assets consumed by Claude Code.

Development workflow

When working on any task, Claude must follow these gates:

  • Plan first: For any task > 30 min, create a plan and get approval before writing code.
  • TDD: Write failing tests first. Never write implementation without a corresponding test.
  • Code review: Run the code-reviewer agent after every significant change. Address all CRITICAL and HIGH findings.
  • Security review: Before committing to assets/ directories, manifest.json files, SKILL.md files, or evals/evals.json files, run security-reviewer agent.

Harness config

Tier: Full (Tier 3) Last updated: 2026-06-01

Hooks: see .claude/settings.json MCP servers: see .mcp.json Agents: see .claude/agents/ Memory: see .claude/memory/