Starter Kit · New Cartridge Repo

PayCargo Forge — new cartridge starter kit

Drop-in CLAUDE.md, DESIGN.md, and .claude/skills/forge-sdk/SKILL.md for any repo that ships a Forge cartridge

1What this is

Three files that give a new-cartridge author's Claude Code session the full context it needs to build a Forge-compliant cartridge without re-reading every Step doc. Copy the tree into an empty repo, run ./pull-sdk.sh, and start writing.

The kit codifies the doctrine currently applied in AI-Sandbox — every rule shipped so far, every anti-pattern the platform team catches at review, and the full PayCargo design token set + component patterns. When a rule changes in Doctrine.md, the corresponding file in this kit gets updated. Ship rate stays where the doctrine is.

2Files

CLAUDE.md Project rules — auto-loaded every session. Layout, 13 non-negotiable rules, SDK bundle mechanics, deploy flow, "Anvil first" gate. DESIGN.md Visual reference — --pc-* token catalog (40+ tokens), component patterns (buttons, forms, tables, badges, callouts, sidebar), icon conventions, layout patterns, pre-ship checklist. .claude/skills/forge-sdk/SKILL.md Operational patterns — loaded on demand when Claude touches cartridge code. Handler template, backend.tf template, Bedrock / OAuth / scheduled patterns, anti-patterns table, pre-PR checklist.

3Layout in a new cartridge repo

<new-cartridge-repo>/
├── CLAUDE.md                                    (auto-loaded by Claude Code)
├── DESIGN.md                                    (referenced from CLAUDE.md)
├── .claude/
│   └── skills/
│       └── forge-sdk/
│           └── SKILL.md                         (on-demand skill)
├── ANVIL.md                                     (design sheet — you fill this out per cartridge)
├── forge-sdk.lock                               (created by pull-sdk.sh)
├── pull-sdk.sh                                  (copy from the reference repo)
├── forge-sdk/                                   (created by pull-sdk.sh, gitignored)
├── cartridge.tf, backend.tf, frontend.tf        (Terraform)
├── lambda/
│   ├── handler.js                               (zero-npm)
│   └── _shared/                                 (gitignored — staged at apply time)
└── frontend/
    ├── index.html                               (loads PCSDK from Console origin)
    ├── app.js
    └── locales/
        ├── en.js
        └── es.js                                (optional; auto-generated by translate.mjs)

4Setup — three commands

# From the reference repo (this one — ai-sandbox):
cp cartridges/administrative/obs/docs/Cartridge-Starter.CLAUDE.md <new-repo>/CLAUDE.md
cp cartridges/administrative/obs/docs/Cartridge-Starter.DESIGN.md <new-repo>/DESIGN.md
mkdir -p <new-repo>/.claude/skills/forge-sdk
cp cartridges/administrative/obs/docs/Cartridge-Starter.SKILL.md <new-repo>/.claude/skills/forge-sdk/SKILL.md

# In the new repo:
./pull-sdk.sh v<latest-tag>
git add -A
git commit -m "chore: bootstrap Forge cartridge repo"

After that, opening the repo in Claude Code auto-loads CLAUDE.md. When Claude touches any code under cartridges/, lambda/, frontend/, shared/modules/, or .claude/, the forge-sdk skill auto-loads and gives full operational depth.

5Anvil sheet first

Before writing any code, the cartridge author fills in ANVIL.md. Every row must have an answer — if you cannot answer one, get the answer from the requester before writing code. Do not stub or guess.

Question	Example answer
Purpose	Generate weekly sales summaries from a Salesforce report.
Audience	Cognito group `sales`.
External systems	Salesforce, Bedrock.
OAuth providers	`salesforce-sandbox`.
Data classification	non-pii (aggregates only).
Retention	Logs 90d; DDB items TTL 30d.
Capabilities used	`sf.soql`, `sf.raw` for Reports API, Bedrock guardrailed InvokeModel.
Cost estimate	~500 Bedrock invocations/wk × 5k tokens = ~$4/mo.
Risk callouts	Report scope limited to user's territory; guardrail catches PII leakage.

6Keeping the kit fresh

When Doctrine.md gets a new entry, the corresponding file in the starter kit gets updated in this repo:

New non-negotiable rule → update the "13 rules" list in CLAUDE.md and SKILL.md.
New design token or component → update DESIGN.md.
New anti-pattern → update the table in SKILL.md.
New pre-PR check → update the checklist in SKILL.md.

Existing cartridge repos pull the updated starter kit at their own cadence. The forge SDK pull-sdk.sh bundle carries these files as well, so a new SDK version bumps the starter files automatically on next pull.

7Contact

Platform team owns the doctrine and the starter kit. Questions or gap reports: mtang@paycargo.com.