# Onboarding

> Route contributors through mecatl's human-reviewed development spine: contract PR, approved baseline, autonomous TDD implementation, final code-review PR. A router, not an executor. Use for onboarding or workflow questions.

- Skill: `stacklok/onboarding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stacklok/onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stacklok/onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: stacklok (https://skillmd.com/u/stacklok)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stacklok/onboarding

---


# onboarding

Read `AGENTS.md`, `docs/architecture.md`, and relevant `docs/adr/` records before changing the
repository.

## Route by work class

Classify by decision and blast radius, never diff size:

- **Spike:** explicit-question evidence gathering that is not shipped as-is. It bypasses the
  spine only with explicit human authorization and must be reclassified before shipping.
- **Routine:** an established or mechanical, reversible change with no new durable decision or
  durable-contract change; it bypasses acceptance planning regardless of file count.
- **Bounded:** substantive contract work with no durable architecture decision; use the spine.
- **Architectural:** a durable public/API, persistence/data ownership, security/trust,
  deployment/operator, module/system-boundary, or cross-subsystem-invariant decision; use the
  spine and a new or superseding ADR.

If the lower class is not supported by evidence, escalate rather than silently downgrade. Choose
Split or Combined only after classification: it is a delivery choice, not a work class. For
classification detail and plan drafting, use `/to-acceptance-plan`.

## The spine

Bounded and Architectural work use two human checkpoints:

1. **`/to-acceptance-plan`** writes `docs/acceptance/<slug>.md`, including exact
   `**Contract:** human-reviewed/v2` metadata, a Bounded/Architectural classification with
   matching decision-record outcome, interfaces, verifiable behavior, and a machine-readable
   `## Human decisions` section.
   Unchecked decisions keep it `draft`; `proposed` means every human decision needed for
   implementation is resolved and recorded. It opens a **Plan / Interface** PR, then stops.
2. **Human contract review** merges the plan PR. Merging is the approval event;
   no separate status-line edit is required. `/plan-orchestrate` proves approval by git
   ancestry and corrects a lagging `proposed` label on entry.
3. **`/plan-orchestrate <slug>`** starts from the merged approved commit, uses run-local
   `.scratch/orchestrate/<slug>/` state and isolated TDD workers, gates and panel-reviews
   the implementation, then opens only the **Implementation** PR.
4. **Human code review** merges the implementation.

Combined delivery is a narrow exception for a compact one-task plan with exactly one
`### Scenario`, exact `**Expected tasks:** 1` metadata, and a non-placeholder
`**Combined rationale:**` explaining why separate plan review adds no value. gRPC/protobuf,
exported Go APIs/interfaces, tool schemas, CLI/config, events/persistence, and
security/authority each begin `None — <rationale>`.
Compatibility/migration may describe workflow migration, and splitting must add no review
value. A workflow-only meta-change may review its process-document/skill interface in the
same PR. `/to-acceptance-plan` prepares
the plan on the eventual combined branch and stops without opening a plan PR; only an
explicit `/plan-orchestrate` invocation adds implementation and opens the sole Combined PR.
Routine work remains exempt. Every path preserves human merge authority.

Two carve-outs put discretion with the human, never the agent: explicitly
requested **exploratory/spike work** skips the plan and orchestration entirely — build it
locally, never merge it to `main` as-is, and re-enter the spine normally if it's worth
shipping. Separately, the directing human may **explicitly waive the spine** for a named
piece of work; the waiver lifts only the plan/interface ceremony, not the layering rules, the
AGENTS.md invariants, or the human-merge requirement. Do not infer either carve-out yourself
or push the spine onto a request that already named one.

Issue references on plan PRs are non-closing (`Relates to #N` or `Tracking: #N`). Only a
final implementation PR that fully completes the issue uses `Closes #N` or `Fixes #N`.
Contract drift, including a worker discovering an unrecorded human decision, blocks
orchestration; the worker does not make that decision. Only a separately, explicitly
authorized `/to-acceptance-plan` amendment mode may open the required Split Plan / Interface
PR for human approval and merge before work resumes.

## Specialists

- `/panel-review` — final Spec / Standards / Test adequacy / Domain review.
- `/test-writer` — invariant-first failing tests.
- `/cut-release` — release workflow.
- `/perf-optimization` and `/perf-mcp-interpretation` — performance work.
- `/mecatl-model-router-config` — model-routing configuration.

This skill only routes. Use `/to-acceptance-plan` for classification detail and acceptance-plan
authoring, and `docs/acceptance/README.md` for acceptance-plan repository navigation.