---
name: cartridge-forge
description: Use when the user asks to forge, scaffold, or author a new cartridge — content cartridge, department cartridge, or chipset bundle. Drives the cartridge-forge loop (scaffold → fill → gate checks → commit) via the skill-creator cartridge CLI.
description-frequency: on-demand
user-invocable: true
---

# 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.
2. Pick the target directory. Convention:
   - `examples/cartridges/<slug>/` for in-repo cartridges
   - `./my-cartridges/<slug>/` for ad-hoc / user-local work
3. 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".
4. 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/](https://tibsfox.com/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.
2. **Never skip `eval`.** It is the ship gate.
3. **`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.
4. **Drop `-department` from the slug** unless the cartridge is
   tied to an entry under `.college/`.
5. **The companion markdown files are not validated.** Write
   them anyway — a cartridge without them is scaffold-quality.
6. **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.