<!--
  scaffold: role-ladder.md
  bucket: engineering-discipline (Bucket 5)
  what belongs here: the CORE role ladder pattern + tier-selection heuristics.
    - tool-developer → web-developer → product-engineer → rcf-engineer.
    - Selection heuristics — when each tier is right.
    - Wrong-tier failure mode.
    - Operator overlay carries the specific role LIST beyond the base ladder.
-->

# Engineering role ladder

## The core ladder

Four base tiers, ordered by scope:

| Tier | Ships | When to reach for it |
|---|---|---|
| `tool-developer` | Shared internal CLIs, scripts, integrations. Node.js only. Small surface, no product concerns. | A CLI, script, or integration for the PA's own tool estate. Cross-platform Node. |
| `web-developer` | Content-led brochure / marketing sites. HTML/CSS/JS + a static site framework. | A single site the operator publishes. Content over interaction. No stateful backend. |
| `product-engineer` | Shippable single-app software. Any language / framework as fits the target. May include backend, database, integrations. | A product the operator ships to end users. Persistent state, multi-page, multi-role usage. |
| `rcf-engineer` (planned) | Enterprise product with full RCF traceability. | Enterprise-grade software where PRD → REQ → US → AC → TS → TC traceability is mandatory. |

The ladder is a **scope escalation**, not a skill escalation. A tool-developer doesn't "graduate" to product-engineer; they're different roles for different work shapes.

## Selection heuristics

Ask three questions:

1. **What's the surface?** A CLI, a site, an app, an enterprise product? Maps to a tier.
2. **What's the persistence model?** No state → tool-developer or web-developer. Persistent state → product-engineer+. Traceability-required → rcf-engineer.
3. **Who's the user?** The operator only → tool-developer. The operator's audience → web-developer / product-engineer. External enterprise buyers → rcf-engineer.

## Wrong-tier failure modes

- **product-engineer for a CLI.** Overengineered — you'll get a full DI container, a service layer, and a config framework for something that should have been 200 lines of Node.
- **tool-developer for a shippable product.** Underengineered — you'll get a script that works in the operator's machine and breaks on any real user's.
- **web-developer for a stateful app.** Wrong toolchain — you'll get an SSG template forced to serve mutable state.
- **rcf-engineer for anything without an enterprise traceability requirement.** Ceremony without benefit — the RCF discipline earns its cost only when the traceability is mandatory.

## Operator overlay: the role LIST

The base ladder is CORE. The operator ships a specific role LIST above it — the specialisations the operator's work needs.

Examples (operator-specific, do not encode in core):
- Website-adjacent: `site-cloner`, `seo-analyser`, `seo-rewriter`, `infographic-designer`.
- Surface-specialised writers: `linkedin-writer`, `newsletter-writer`.
- Domain-specialised analysts.

Each overlay role names its base-ladder position (a `linkedin-writer` extends the base `writer` role, not tool-developer) so the specialisation inherits without overriding.

## Related

- CLAUDE.md.template Bucket 5 rule 1.
- `packages/core/roles/` — the base roles the ladder is expressed through.
- `packages/core/roles/tool-developer/definition.md` — the tool-developer tier.
- `dispatch-envelope.md` — dispatch mechanics that apply regardless of tier.