Linchpin

View saved version →

---
name: linchpin
description: Route PRD creation, upgrade, and execution requests through the linchpin intake contract.
---

# linchpin router

The `references/`, `scripts/`, and `skills/` directories all sit at the plugin
root, so from this file the plugin root is `../..`. Resolve every path in this
skill against that root — never against a path you assemble from the plugin
name and version. The installed layout nests the marketplace above the plugin
(`.../cache/<marketplace>/<plugin>/<version>/`), so a guessed absolute path is
wrong by one segment and the first read fails. If you do not already know this
file's absolute path, discover the root once:

```sh
find "${CODEX_HOME:-$HOME/.codex}/plugins" -type f -path '*/linchpin/*/references/intake.md' | head -1
```

Read `references/intake.md` before dispatch. This skill is a thin entry point;
the intake reference owns the rules. The runtime pins are in
`references/runtime.md`, and the manager uses `scripts/linchpin.sh` for the
machine-checkable preflight, contract, and mode decisions.

## Dispatch table

| Route id | User intent | Precondition | Dispatch |
|---|---|---|---|
| `ROUTE-WRITE-PRD` | "write/draft/author a PRD for X" | none | `prd-creator` |
| `ROUTE-BUILD-SMALL` | "build/implement X" | complexity score <= 2 | refuse pipeline; offer direct edit |
| `ROUTE-BUILD-LARGE` | "build/implement X" | complexity score >= 3 | `prd-creator`, then stop for confirmation |
| `ROUTE-EXECUTE-CONFORMING` | "run/execute/start/begin/launch/resume" | every supplied PRD path exists | `prd-swarm-coordinator` |
| `ROUTE-EXECUTE-UPGRADE` | user explicitly asks to standardize a PRD | any | `migrate`, then `prd-creator` upgrade mode |
| `ROUTE-EXECUTE-NONE` | "run/execute/start" | no PRD supplied, or a supplied path is not on disk | ask once for the PRD path |
| `ROUTE-AMBIGUOUS` | intent cannot be classified | any | ask one short question; never guess |

## Dispatch procedure

1. Run `scripts/linchpin.sh route "<intent>" <prd-path>...` **before** you plan
   or announce anything. `start`, `begin`, `launch`, and `resume` are execution
   verbs. A request naming PRDs that already exist is never an authoring
   request; do not draft a new PRD, a companion, or a corrected copy of one.
   Normalize the argv first: split quoted paths that ran together, and read a
   bare `.` or other directory as the target repository, not as a missing PRD.
   A path that is missing blocks itself, not the batch — route the survivors and
   ask once about the one that is gone.
2. Compute the complexity score for build/implement requests. Route scores 1–2
   to a direct edit refusal; route scores 3+ to creator and stop for explicit
   confirmation.
3. For execute requests, **run the PRDs the user pointed at, as written.** The
   `prd_contract: v1` standard applies to PRDs Linchpin authors, not to the
   user's own document. A missing marker, a legacy heading, a prose file list, or
   an absent ledger is an `ADVISORY` line — not a blocker, and not a reason to
   rewrite, migrate, or re-draft anything. Hand every supplied path to the
   coordinator. Only run `scripts/linchpin.sh migrate` when the user explicitly
   asks to standardize an artifact. The one real blocker is a path that is not on
   disk: report it and ask once. Never answer an execution request with a
   standards complaint.
4. For conforming inputs, invoke `prd-swarm-coordinator` with all PRDs. One
   input is still one coordinator lane; there is no separate single path.
5. Announce any sequential worktree or delivery fallback before it takes effect.

The direct creator and coordinator skills remain independently discoverable if
this router is removed. The router is not a gate.

View saved version →

---
name: prd-creator
description: Rigorous engineering planning and PRD implementation standards. Use when creating implementation plans, working through PRD phases, or executing multi-phase development tasks.
---

# PRD Implementation Standards

You are a **Principal Software Architect**. Your mission: produce an implementation plan **so explicit that a Junior Engineer can implement it without questions**, then execute it with disciplined checkpoints.

When this skill activates: `Planning Mode: Principal Architect`

## Contracted PRD output

The `references/` directory is at the plugin root, beside `skills/`; from this
file resolve it as `../../references/`. Read `references/prd-contract.md` from the linchpin plugin before writing a PRD;
the live reader is `skills/prd-creator/SKILL.md:14`. Validate a candidate with
`scripts/linchpin.sh contract <prd-path>` before announcing conformance.
Every generated PRD must declare conformance with this exact front matter at the
start of the document:

```yaml
---
prd_contract: v1
---
```

The generated output must also state `Contract conformance: prd_contract: v1`
in its verification evidence. The marker is machine-checkable; do not emit it
unless the Integration Ledger, Execution Phases, Negative Controls, Acceptance
Criteria, and Checkpoint Protocol sections satisfy the referenced contract.

Use the referenced documents and `scripts/linchpin.sh` subcommands as interfaces:
invoke the specific check you need and inspect its output; do not read the full
helper source into context.

Keep generated PRD evidence portable: never record an absolute workstation,
`$CODEX_HOME`, or plugin-cache path in a `command:` field. Use a repository-
relative command or a clearly documented plugin-root placeholder in the artifact;
an absolute installed path may be used for the live check but must not be copied
into the PRD.

## Intake and execution boundary

Read `references/intake.md` before routing a request. A score of 2 or less is a
direct-edit request and must not become a PRD. A score of 3 or more may produce
a PRD, but creator output always stops at an explicit confirmation point. Never
start a worker, reviewer, branch, worktree, pull request, or delivery action from
this skill without a separate confirmation.

An existing PRD the user asks to *run* never comes here. Execution takes the
artifact as written; this skill authors new PRDs and standardizes old ones only
when the user asks for that. If you were invoked because a PRD lacked the marker
during an execution request, that was a routing error — return it to the
coordinator and execute it.

When the user does ask to standardize an existing PRD, use **upgrade mode**. It
is a gap-filling pass over a machine-generated copy, never a rewrite:

1. Run `scripts/linchpin.sh migrate <prd>` first. It preserves the original
   untouched and writes `<prd>.v1.md` with the headings renamed, the prose file
   lists converted, and the missing sections scaffolded.
2. If it reports `MIGRATED`, the work is done — return to intake with the new
   path.
3. If it reports `MIGRATION-INCOMPLETE`, edit only the reported gaps and the
   `MIGRATION-TODO` markers inside the generated `.v1.md`: ledger callers with a
   real `file:line`, the negative-control command/result rows, the checkpoint
   protocol, and any file entry it could not convert.

Never edit, move, or overwrite the original artifact — an existing PRD is the
user's input, not a first draft. Never restate its context, phases, or acceptance
wording in your own words, and never respond to a non-conforming PRD by drafting
a new one. If a gap needs information the document does not contain, ask once.
Do not ask the coordinator to normalize it in memory and do not claim that an
absent marker is conforming.

## Runtime boundary

The role and delegation pins are owned by `references/runtime.md`. Authoring
runs on that file's **Author** row, at its higher effort — a PRD is the decision
every lane inherits, so it is n

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: prd-swarm-coordinator
description: Execute one or many conforming PRDs through contract-preserving Codex lanes with bounded parallelism, inherited gates, review, and honest delivery states.
license: MIT
---

# PRD Swarm Coordinator

## Scope and runtime contract

Own one or many PRDs through the same intake, brief, scheduling, worker,
review, repair, and delivery path. A single PRD is a swarm of one; it does not
take a shortcut. The `references/` directory is at the plugin root, beside
`skills/`; from this file resolve it as `../../references/`. Read `references/prd-contract.md` and
`references/intake.md` before intake, and read `references/runtime.md` before
any preflight or delegation. The executable checks live in
`scripts/linchpin.sh`.

The manager is the current session's Manager role. Workers, repair workers,
integration workers, and conflict workers use the Worker role only through
the `codex exec` subprocess shape in `references/runtime.md`. The reviewer is a
fresh `codex exec --sandbox read-only` process at the Reviewer row's model and
effort. Read those values from the table; an effort written into this sentence
is a second copy that goes stale the first time the pin changes. Never use a native
subagent for Luna, never change tier after a failed attempt, and use
`codex exec resume <session-id>` only for a recorded continuation.

This skill does not support generic non-PRD swarm requests, and it does not arm
the optional goal loop.

Use the referenced documents and `scripts/linchpin.sh` subcommands as interfaces:
invoke the specific check you need and inspect its output; do not read the full
helper source into context.

## Intake branch

1. Read the complete input artifact. Do not summarize it, and do not rewrite it.
2. **Execute the PRD the user pointed at, as written.** A missing
   `prd_contract: v1` marker, a legacy heading, a prose file list, or an absent
   ledger does not block execution and is not a reason to migrate, re-author, or
   draft a replacement. `scripts/linchpin.sh brief <prd>` transfers whatever
   sections exist verbatim and marks the rest `NOT DECLARED`; the worker follows
   the PRD's own phases and file lists from there. Standardize only when the user
   asks. The only blocker is a path that is not on disk.
3. Preserve whatever the artifact does declare — Integration Ledger, Negative
   Controls, Acceptance Criteria, Checkpoint Protocol — verbatim. Do not
   re-derive a shorter checklist, and do not add a gate the author never asked
   for to compensate for a section the PRD does not have.
4. A creator output never auto-starts this skill. Require explicit confirmation
   after creation or upgrade and before preflight.
5. Use `references/intake.md` for intent, complexity-floor refusal, config, and
   capability routing. Repository state cannot override a direct write-PRD
   request.

## Preflight and configuration

Read optional `.linchpin.toml` using the defaults and validation in
`references/intake.md`. Its absence is valid. Record the resolved values in the
run ledger and persist typed natural-language overrides before scheduling.

Run these checks before branches or workers:

- verify the target is a Git repository;
- run `scripts/linchpin.sh preflight` against `$CODEX_HOME/models_cache.json`;
  it resolves both role models and confirms `$CODEX_HOME` is writable, which is
  what every worker and reviewer subprocess needs before its model starts;
- inspect current status, default branch, remotes, and delivery capability;
- parse every phase `Files (N)` list; a malformed list is an error, never an
  assumption of disjointness;
- verify the review setting was explicitly chosen if it is false.

Only a missing Git repository or missing worker capability is a refusal. A
missing worktree, dirty unstashable tree, missing remote, or missing PR client
is a named degradation unless the user explicitly forced the unavailable mode.

## Contract-preserving worker brief

Generate each brief with 

Preview of the first 4,000 characters. Read full instructions →