Architecture Overview

June 1, 2026 · View on GitHub

Generated by /shipwithai-starter on 2026-05-28. Edit directly.

System overview

shipwithai-plugins is a plugin monorepo for the ShipWithAI Claude Code ecosystem. Architecture style: monorepo — one directory per plugin, no runtime, no compiled artifacts.

All artifacts are Markdown (SKILL.md, references), JSON (manifest, evals, settings), and Python hooks. Claude Code loads plugins via manifest.json at session start or on-demand via skill invocation.

Key layers

Layer	Directory	Responsibility
Plugin root	`plugins/<plugin-name>/`	One Claude Code plugin per directory
Skills	`plugins/<plugin-name>/skills/<skill-name>/`	SKILL.md + assets + references + evals
Hooks	`.claude/hooks/`	Python safety hooks (validate-command, protect-files, observe)
Docs	`docs/`	Architecture, ADRs, CODEMAPS
Scripts	`scripts/`	publish-plugin.sh — always confirm before running
Harness	`.claude/`	settings.json, agents/, memory/, starter-context.json

Entry points

File	Purpose
`plugins/*/manifest.json`	Claude Code skill registry — lists all skills in a plugin
`.claude-plugin/marketplace.json`	Marketplace registry metadata
`.claude/settings.json`	Permission rules + safety hooks

External dependencies

None. All data is static files read by Claude Code at session start or on-demand.

Key directories

shipwithai-plugins/
├── plugins/
│   └── <plugin-name>/
│       ├── skills/<skill-name>/
│       │   ├── SKILL.md            ← 500-line hard cap (ideal < 300)
│       │   ├── assets/             ← templates used verbatim in user projects
│       │   ├── references/         ← lazy-loaded reference docs (< 300 lines each)
│       │   └── evals/evals.json    ← 5+ test prompts
│       ├── manifest.json           ← skill registry (must match skills/ structure)
│       ├── plugin.json             ← plugin metadata (name, version)
│       ├── CHANGELOG.md
│       └── README.md               ← live SSOT, update after every change
├── .claude/
│   ├── settings.json               ← permissions + hooks
│   ├── starter-context.json        ← harness interview answers
│   ├── agents/                     ← specialized agents (drift-monitor)
│   ├── memory/                     ← project facts + team preferences
│   └── hooks/
│       ├── validate-command.py
│       ├── protect-files.py
│       └── observe.py
├── docs/
│   ├── ARCHITECTURE.md             ← this file
│   ├── adr/                        ← Architecture Decision Records
│   └── CODEMAPS/                   ← codebase navigation guides
└── scripts/
    └── publish-plugin.sh           ← plugin release script (confirm before running)

What to know before touching code

Gotchas

Area	Rule
`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/`	Templates consumed verbatim by Claude Code in user projects — edits have downstream impact
`.claude-plugin/marketplace.json`	Plugin registry metadata — update when adding/removing plugins
`README.md` + plugin docs	Live SSOT — must be updated after every plugin or skill change

Sensitive areas

Directory	Why it needs extra care
`assets/` directories	Template files copied into real user projects during skill execution
`manifest.json` files	Skill registry — out-of-sync causes skills to disappear or error
`SKILL.md` files	Published to users; 500-line hard cap enforced; descriptions < 200 chars
`evals/evals.json` files	Test prompts — must remain runnable and cover the full skill

Build order

None — content-only workspace, no compilation step.

Test isolation

No automated tests. Validate skills manually with eval prompts on 2+ real projects before shipping.

Future work

GitHub Actions: auto-validate plugin structure on PR (not yet implemented)
GitHub Actions: Telegram notification when release tag is pushed to main (not yet implemented)