Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
100 lines (77 loc) · 4.41 KB

ARCHITECTURE.md

File metadata and controls

100 lines (77 loc) · 4.41 KB
Raw

Architecture Overview

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)