cartridge-forge

Cartridge Forge

Forge a new cartridge end-to-end using the skill-creator cartridge CLI. The forge is the toolchain that builds cartridges; this skill is the playbook that drives it.

When to invoke

Trigger on any of:

• "create a cartridge for X"
• "forge a new cartridge"
• "scaffold a department" / "generate a department cartridge"
• "build a content cartridge"
• "make a chipset bundle for X"

Do not trigger for migrating legacy cartridges (that is cartridge migrate) or for forking an existing one (that is cartridge fork).

Prerequisites

1. docs/cartridge/FORGING-GUIDE.md and

docs/cartridge/CARTRIDGE-SPEC.md are the normative references. Read them once per session if the context is not already loaded.

1. Pick the target directory. Convention:
2. examples/cartridges/<slug>/ for in-repo cartridges
3. ./my-cartridges/<slug>/ for ad-hoc / user-local work
4. Pick the slug. Drop the -department suffix unless the

cartridge is directly tied to a college department in .college/. "systems-administration" — not "systems-administration-department".

1. Pick the template: department (skills + agents + teams),

content (deepMap + story arc), coprocessor (pure functional tooling), or graphics (GLSL / OpenGL / WebGL / Vulkan shader pipeline; grounded in the GFX research series at /Research/GFX/ on tibsfox.com).

The Forge Loop

scaffold → fill → validate → eval → dedup → metrics → commit

Every step is idempotent and JSON-capable. eval is the gate — if it exits non-zero, the cartridge is not ready to ship.

1. Scaffold

skill-creator cartridge scaffold <template> <dir> <slug>

Writes an 8-file skeleton: cartridge.yaml, chipsets/*.yaml, one placeholder skill, agent, and team, plus a README.md. Round-trips through load → validate with zero errors before any edits.

2. Fill

Replace placeholder content with real content. A full department cartridge typically wants:

• Skills — one per daily responsibility surface (10–15 is a

comfortable size; fewer feels thin, more suggests a split)

• Agents — an Opus capcom + hands-on Sonnet executors;

router topology with is_capcom: true on the capcom

• Teams — one per recurring workflow (author, review,

incident, drill) — each team names its roster and use_when

• Grove record types — 4–8 record types that capture the

durable outputs this cartridge produces

• Evaluation domains — one per skill domain; keep them

aligned with the domain: field on each skill

Replace the skeleton's cartridge.yaml header:

• id: slug
• name: title case, human-readable
• author: real author
• description: one-paragraph, no marketing tone
• provenance.origin, provenance.createdAt
• metadata.tags

Delete the three placeholder markdown files (skills/placeholder-skill.md, agents/placeholder-agent.md, teams/placeholder-team.md) and replace them with one markdown file per real skill / agent / team. Each companion file is informational — the loader does not scan them, but a "full" cartridge ships them.

3. Validate

skill-creator cartridge validate <dir>/cartridge.yaml --json

valid: true is the required outcome. If there are validation-debt errors (e.g. around agent_affinity or domains_covered), add --allow-validation-debt and track the debt per docs/cartridge/KNOWN-VALIDATION-DEBT.md.

4. Eval

skill-creator cartridge eval <dir>/cartridge.yaml

Runs the pre-deploy gates declared in chipsets/evaluation.yaml. Default gates:

• all_skills_have_descriptions
• all_agents_have_roles
• grove_record_types_defined
• has_evaluation_chipset

Exit code 0 is required before commit.

5. Dedup

skill-creator cartridge dedup <dir>/cartridge.yaml

no collisions is required. Collisions mean a skill or agent is defined twice across chipsets — either intentional merge (refactor) or typo (fix).

6. Metrics

skill-creator cartridge metrics <dir>/cartridge.yaml

Informational, not a gate. Captures shape (skill / agent / team / record-type counts) for the commit message.

7. Commit

Conventional Commits, scope cartridge:

feat(cartridge): forge <slug> cartridge

N skills / M agents / K teams / J grove record types.
Forged via cartridge-forge from the <template> template.
All forge gates green: validate, eval, dedup.

Rules

1. Never hand-author a cartridge.yaml from scratch. Always

scaffold first — the template encodes the current schema.

1. Never skip eval. It is the ship gate.
2. **kind: department is a schema discriminator, not a college

tie.** The chipset kind stays department even when the cartridge is not tied to a college department.

1. Drop -department from the slug unless the cartridge is

tied to an entry under .college/.

1. The companion markdown files are not validated. Write

them anyway — a cartridge without them is scaffold-quality.

1. Backup and DR content belongs in a dedicated team

(<slug>-dr-drill-team or equivalent) if the cartridge has data-durability responsibilities.

Reference walkthrough

A complete worked example: examples/cartridges/systems-administration/ — 12 skills, 5 agents, 4 teams, 6 grove record types, all forge gates green.

Output contract

After the loop completes, report to the user:

• Final id, name, and path
• Chipset list
• Counts: skills / agents / teams / grove record types
• validate / eval / dedup verdicts
• Any validation debt accepted and the follow-up note

Do not report "done" before all four forge gates (validate, eval, dedup, metrics) have been run and shown green.