@lovehlmmm/primekit 1.0.0

package/skills/agentize/references/monorepo-layout.md

@@ -0,0 +1,164 @@
+# Monorepo Layout
+
+Canonical tree for `--both` mode (Node/TypeScript). Adapt paths for other ecosystems.
+
+## Tree
+
+```
+.
+├── packages/
+│   ├── core/
+│   │   ├── src/
+│   │   │   ├── capabilities/       # one file per capability
+│   │   │   ├── config/             # config schema + loader
+│   │   │   ├── errors.ts           # typed error classes
+│   │   │   └── index.ts            # public exports
+│   │   ├── test/
+│   │   ├── package.json            # private: true (not published)
+│   │   └── tsconfig.json
+│   ├── cli/
+│   │   ├── src/
+│   │   │   ├── commands/           # one file per command
+│   │   │   ├── credentials.ts      # resolution chain
+│   │   │   ├── formatter.ts        # json + text renderers
+│   │   │   └── bin.ts              # #!/usr/bin/env node entry
+│   │   ├── test/
+│   │   ├── package.json            # bin, files, engines, publishConfig
+│   │   └── tsconfig.json
+│   └── mcp/
+│       ├── src/
+│       │   ├── tools/              # one file per tool
+│       │   ├── transports/
+│       │   │   ├── stdio.ts
+│       │   │   ├── sse.ts
+│       │   │   └── streamable-http.ts
+│       │   ├── auth.ts
+│       │   └── server.ts           # transport-agnostic server factory
+│       ├── test/
+│       ├── package.json
+│       ├── wrangler.toml           # Cloudflare Workers
+│       ├── Dockerfile
+│       └── tsconfig.json
+├── claude/skills/<tool-name>/      # companion skill (staged for marketplace)
+├── docs/
+│   ├── cli.md
+│   ├── mcp.md
+│   ├── architecture.md
+│   └── contributing.md
+├── scripts/
+├── .github/workflows/
+│   ├── ci.yml
+│   └── release.yml
+├── .changeset/                     # changesets for release
+├── package.json                    # workspaces
+├── pnpm-workspace.yaml             # or workspaces field
+├── tsconfig.base.json
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+## Root `package.json`
+
+```json
+{
+  "name": "<tool-name>-monorepo",
+  "private": true,
+  "workspaces": ["packages/*"],
+  "scripts": {
+    "build": "pnpm -r build",
+    "test": "pnpm -r test",
+    "lint": "pnpm -r lint",
+    "typecheck": "pnpm -r typecheck",
+    "release": "changeset publish"
+  },
+  "packageManager": "pnpm@9"
+}
+```
+
+## `packages/core/package.json`
+
+```json
+{
+  "name": "@<scope>/<tool-name>-core",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+## `packages/cli/package.json`
+
+```json
+{
+  "name": "<tool-name>",
+  "version": "0.1.0",
+  "description": "CLI for <tool-name>",
+  "bin": { "<tool-name>": "dist/bin.js" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public", "provenance": true },
+  "dependencies": {
+    "@<scope>/<tool-name>-core": "workspace:*",
+    "commander": "^12",
+    "dotenv": "^16",
+    "keytar": "^7"
+  },
+  "scripts": {
+    "build": "tsc -p . && chmod +x dist/bin.js",
+    "prepublishOnly": "pnpm build && pnpm test"
+  }
+}
+```
+
+## `packages/mcp/package.json`
+
+```json
+{
+  "name": "<tool-name>-mcp",
+  "version": "0.1.0",
+  "bin": { "<tool-name>-mcp": "dist/bin.js" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public", "provenance": true },
+  "dependencies": {
+    "@<scope>/<tool-name>-core": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1",
+    "hono": "^4"
+  }
+}
+```
+
+## Core/adapter boundary
+
+`core/` rules:
+- No `process.argv`, no `console.log` as control flow, no HTTP server code.
+- Accepts config via explicit parameters; returns plain data or throws typed errors.
+- Pure functions where feasible; side-effects isolated into injected clients.
+
+`cli/` and `mcp/` rules:
+- Import only from `core/` (and formatting/transport deps).
+- Translate argv / MCP arguments → core params.
+- Translate core results/errors → CLI output / MCP response.
+- No business logic.
+
+If you find yourself adding business logic to an adapter, it belongs in `core/`.
+
+## Single-package fallback (`--cli` or `--mcp` alone)
+
+```
+.
+├── src/
+│   ├── core/           # same boundary, just not a separate package yet
+│   ├── cli/  (or mcp/)
+│   └── index.ts
+├── package.json
+└── tsconfig.json
+```
+
+Keep the `src/core/` folder even when there's only one adapter — it makes adding the other surface later a file move, not a rewrite.

package/skills/agentize/references/oauth-streamable-http.md

@@ -0,0 +1,110 @@
+# OAuth 2.1 for MCP over Streamable HTTP
+
+Remote MCP over Streamable HTTP uses OAuth 2.1 with mandatory PKCE (S256), Protected Resource Metadata (RFC 9728), and resource-bound tokens (RFC 8707). stdio does not use this flow — resolve credentials from the env/config chain instead.
+
+**Sources:** [MCP Authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728), [OAuth 2.1 draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13)
+
+## End-to-end flow
+
+1. Client calls MCP without a token → server returns `401` with `WWW-Authenticate` pointing at `resource_metadata`.
+2. Client GETs RFC 9728 Protected Resource Metadata (`/.well-known/oauth-protected-resource`) → learns `authorization_servers`.
+3. Client GETs RFC 8414 Authorization Server metadata (`/.well-known/oauth-authorization-server`).
+4. Optional: RFC 7591 Dynamic Client Registration → client_id (and secret if confidential).
+5. Client generates PKCE S256 `code_verifier` / `code_challenge`, opens browser authorize URL with `resource=<canonical MCP URI>`.
+6. User consents → redirect with authorization code → token request includes `code_verifier` + `resource` → RFC 8707 resource-bound access token.
+7. Client retries MCP with `Authorization: Bearer <token>`; server validates audience and scopes.
+
+```mermaid
+sequenceDiagram
+  participant C as MCP Client
+  participant RS as MCP Server (RS)
+  participant AS as Authorization Server
+  participant B as Browser
+  C->>RS: MCP request (no token)
+  RS-->>C: 401 + WWW-Authenticate
+  C->>RS: GET /.well-known/oauth-protected-resource
+  RS-->>C: authorization_servers
+  C->>AS: GET /.well-known/oauth-authorization-server
+  AS-->>C: AS metadata
+  C->>AS: POST /register (RFC 7591, optional)
+  AS-->>C: client_id
+  C->>B: authorize + PKCE S256 + resource
+  B->>AS: user consent
+  AS-->>C: authorization code
+  C->>AS: token + code_verifier + resource
+  AS-->>C: access token (aud=MCP)
+  C->>RS: MCP + Bearer token
+  RS-->>C: MCP response
+```
+
+## Best practices
+
+- **Audience binding** — Always send `resource` on authorize + token requests; MCP server MUST reject tokens not issued for its canonical URI.
+- **No token passthrough** — Never forward the client's bearer token to upstream APIs; obtain a separate upstream token if needed.
+- **Exact redirect URIs** — Register and validate exact matches (`localhost` or HTTPS only).
+- **Issuer validation** — Trust only AS entries from RS metadata; verify `iss` and JWKS before accepting tokens.
+- **Short-lived tokens** — Prefer rotating refresh tokens for public clients; store tokens securely.
+
+**Sources:** [MCP security best practices](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices), [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `redirect_uri_mismatch` | URI not exact match | Register exact callback; no trailing-slash drift |
+| Token rejected / missing audience | Missing `resource` param | Send canonical MCP URI on auth + token requests |
+| Confused deputy | Proxy uses static client_id without per-user consent | Consent per dynamic client before upstream AS |
+| Mix-up attack (wrong AS) | Client trusts attacker-supplied issuer | Pin AS from RS metadata; validate `iss` |
+| 401 loops | Expired / wrong-aud token | Re-run PKCE flow; check clock skew + audience |
+| DCR blocked | AS disables RFC 7591 | Pre-register client_id or collect credentials in UI |
+
+## AI-tool integration matrix
+
+| Client | Command / config |
+| --- | --- |
+| Claude Code | `claude mcp add --transport http <name> https://mcp.example.com/mcp` — browser OAuth on first use |
+| Claude Desktop | Customize → Connectors → Add custom connector → paste MCP URL; OAuth 2.1 + PKCE handled in browser |
+| Codex CLI | `codex mcp add <name> --url https://mcp.example.com/mcp` then `codex mcp login <name>` |
+| Cursor | `.cursor/mcp.json`: `{ "mcpServers": { "name": { "url": "https://mcp.example.com/mcp" } } }` — auth prompt if DCR available |
+| VS Code | MCP servers in user/workspace settings with `"type": "http"` / `"url"`; completes OAuth in browser |
+
+**Sources:** [Claude Code MCP](https://code.claude.com/docs/en/mcp), [Cursor MCP](https://cursor.com/docs/mcp), [Codex MCP](https://developers.openai.com/codex)
+
+## Cloudflare Zero Trust + workers-oauth-provider
+
+Put Access in front of the MCP URL (or host the RS on Workers). Managed OAuth returns `401` + `WWW-Authenticate` for non-browser agents and exposes RFC 8414 discovery. Free Access tier covers up to 50 users.
+
+```ts
+import { OAuthProvider } from "@cloudflare/workers-oauth-provider";
+
+export default new OAuthProvider({
+  apiRoute: "/mcp",
+  apiHandler: MyMcpWorker,
+  defaultHandler: MyAuthUi,
+  authorizeEndpoint: "/oauth/authorize",
+  tokenEndpoint: "/oauth/token",
+  clientRegistrationEndpoint: "/oauth/register",
+});
+```
+
+Wire Access policy → identity provider; enable Managed OAuth on the MCP application so agents complete PKCE without scraping a login HTML page.
+
+**Sources:** [Managed OAuth](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/), [workers-oauth-provider](https://github.com/cloudflare/workers-oauth-provider), [Cloudflare Zero Trust Access](https://www.cloudflare.com/sase/products/access/)
+
+## Free / low-cost authorization servers
+
+| Option | Cost shape | Notes |
+| --- | --- | --- |
+| **Keycloak** (self-hosted) | Free OSS; you pay infra | Full OAuth 2.1, DCR, PKCE policies; best for on-prem / air-gap |
+| Auth0 | Free tier (~25k MAU typical) | Managed AS; enable PKCE + Resource Indicators |
+| Stytch | Free developer tier | B2B/B2C auth; confirm RFC 8707 `resource` support |
+| WorkOS | Free tier for early apps | Strong MCP / enterprise SSO story |
+
+Prefer Keycloak when you need full control; use Auth0/Stytch/WorkOS free tiers for managed AS without running IdP ops.
+
+**Sources:** [Keycloak MCP authz](https://www.keycloak.org/securing-apps/mcp-authz-server), [WorkOS MCP auth](https://workos.com/blog/best-mcp-server-authentication-providers)
+
+## Related
+
+- `mcp-transports.md` — Streamable HTTP transport modes
+- `auth-resolution-chain.md` — stdio / CLI credential chain (non-OAuth)

package/skills/agentkit/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: pk:primekit
+description: "Task router for PrimeKit installs. Classifies the task, activates the right installed skills, chains them into the shortest workflow that fits, and spawns installed subagents at defined trigger points to raise output quality. Use at the start of multi-step, multi-domain, or ambiguous work, or when unsure which skill or agent applies."
+user-invocable: true
+when_to_use: "Invoke at the start of multi-step or multi-domain work, when the right skill is unclear, when skills need sequencing into a workflow, or when deciding whether and when to spawn subagents."
+category: utilities
+keywords: [routing, dispatch, skills, chaining, subagents, delegation, workflow, quality]
+argument-hint: "[task to route]"
+metadata:
+  author: primekit
+  version: "1.0.0"
+---
+
+# PrimeKit Router
+
+Route any task to the right installed capability: the correct skill, the
+shortest skill chain that fits, and the right subagents at the right moments.
+This skill decides and dispatches — the routed skills and agents do the work.
+
+Routing tables live with their owning skills. This skill adds the decision
+protocol on top of them and duplicates none of their content. Output quality
+comes from four levers this protocol controls: the right specialist per step,
+fresh-context subagents for noisy or parallel work, verification steps matched
+to risk, and refusing to orchestrate what a single skill does better.
+
+## Boundaries
+
+| Situation | Owner |
+|---|---|
+| Pick and sequence installed skills, time subagent spawns, in this session | this skill |
+| Coordinate headless CLI jobs across runtimes, models, worktrees | the orchestrate skill (`primekit-orchestrate`, engineer installs) |
+| Run multi-session agent teams | the team skill (`primekit-team`, engineer installs) |
+| Discover or install skills you do not have yet | the find-skills skill (`primekit-find-skills`, engineer installs) |
+| Execute the domain work itself | the routed skill or agent owns execution |
+
+If the task is explicitly about running jobs headlessly, across CLIs, or in
+parallel worktrees, hand off to the orchestrate skill now (when installed) and
+stop.
+
+## The Protocol
+
+Six steps. Steps 0-2 are cheap and mandatory; steps 3-5 scale with the task.
+
+### Step 0 — Proportionality gate (always run first)
+
+Routing ceremony on a trivial task is itself a quality failure.
+
+| Condition | Action |
+|---|---|
+| User names a skill to use | Invoke that skill. Stop routing. |
+| Single domain, single step, one obviously matching installed skill | Invoke it directly. Stop routing. |
+| Pure conversation, opinion, or fact question | Answer. No skills, no agents. |
+| Multi-step, multi-domain, ambiguous match, high risk, or no obvious skill | Continue to Step 1. |
+
+### Step 1 — Classify the task
+
+Load [references/task-taxonomy.md](references/task-taxonomy.md). Output one
+line before acting:
+
+```
+Route: <workflow class> | size: <trivial|standard|epic> | risk: <low|elevated|high> | domains: <n>
+```
+
+The class gives the default route shape; the modifiers bend it (bigger size
+adds planning and delegation, higher risk adds verification, more domains add
+domain-skill links).
+
+### Step 2 — Inventory what is actually installed
+
+Never route to a capability that is not installed. Discovery is
+runtime-native:
+
+- **Claude Code**: installed skills and their descriptions are listed in your
+  context (Skill tool); installed agents are the available subagent types
+  (Agent tool). Trust that list, not memory.
+- **Codex**: skills auto-discovered from `~/.agents/skills/` and the repo's
+  `.agents/skills/`; agents are `agent_<slug>` MCP tools when the
+  `primekit-codex-agent-runtime` MCP server is registered, or TOML files under
+  `~/.codex/agents/` / project `.codex/agents/`.
+
+Capability missing? Use the find-skills skill (`primekit-find-skills`) to discover
+and install it when present; otherwise do the work inline and name the gap in
+your final report. Do not silently pretend the capability exists.
+
+### Step 3 — Select and chain skills
+
+Selection precedence:
+
+1. Skill the user named.
+2. Domain-specific skill over workflow-generic skill (a React feature routes
+   to the frontend skill first, then executes through the workflow skills).
+3. One primary skill per distinct intent; secondary skills are follow-up
+   helpers, not co-owners.
+
+Consult the owning routing references instead of guessing — and instead of
+re-deriving what they already encode:
+
+| Decision | Load |
+|---|---|
+| Which domain skill fits this intent | `../primekit-find-skills/references/domain-routing.md` (engineer installs; if absent, match installed skill descriptions) |
+| Which sequence fits multi-step dev work | `../primekit-cook/references/workflow-routing.md` |
+| Which visual/preview mode fits | `../primekit-preview/references/visual-explanation-routing.md` |
+| How to compose, pass context, and recover mid-chain | [references/chaining-patterns.md](references/chaining-patterns.md) |
+
+Chain rules are in
+[references/chaining-patterns.md](references/chaining-patterns.md): the
+understand → decide → execute → verify → deliver skeleton, entry/exit criteria
+per link, artifact passing through report files, and the collapse rule that
+keeps chains short.
+
+### Step 4 — Spawn subagents at trigger points
+
+Subagents raise quality when they add a fresh context window, an enforced tool
+boundary, parallel wall-clock, or a specialist system prompt — and lower it
+when they fragment a task that needed full conversation context.
+
+Load [references/subagent-timing.md](references/subagent-timing.md) for the
+trigger table (stage × condition → role), the delegation contract every spawn
+must carry, parallel-safety rules, and the per-runtime dispatch dialect
+(Claude Code Agent tool vs Codex `agent_<slug>` MCP tools).
+
+Fast triggers you should never miss:
+
+- Investigation spanning more than two areas → parallel read-only explorer
+  agents at the start, not after you are lost.
+- Implementation finished → tester role before you claim done.
+- Ship, publish, or public-contract change ahead → reviewer role first.
+- Same failure twice → debugger role with the evidence so far.
+
+### Step 5 — Quality gates by risk
+
+Verification is part of done, not optional polish:
+
+| Risk class | Mandatory before delivering |
+|---|---|
+| low (internal, reversible) | Executor skill's own checks |
+| elevated (user-visible behavior, cross-module) | Test/verification link + self-review of the diff or draft |
+| high (public contract, security, data, money, destructive, mass-audience send) | Verification link + independent reviewer role + explicit user confirmation before the irreversible step |
+
+Report outcome-first when the chain completes: what was delivered, which
+links ran, which agents were used, what was verified, what gaps remain.
+
+## Worked Routes
+
+Every route below first applies the bounded outcome gate in
+`../../rules/primary-workflow.md`. The examples describe only the routing that
+follows; they are not alternate workflow authorities.
+
+**"Fix the failing CI on this branch"** — after framing the repaired behavior
+and safety boundary, Step 0 finds a single domain and obvious owner. Route to
+`/pk:fix`. No chain, no agents unless `/pk:fix`
+itself escalates. Total router overhead: one classification line.
+
+**"Add team billing with Stripe and a settings page"** — class:
+build-feature, size: epic, risk: high (money), domains: 3 (backend, payments,
+frontend). After the opening outcome gate, chain: scout → plan → implement (payment + frontend domain skills
+under the workflow skill) → test → review. Agents: explorer roles scout
+payment and settings code in parallel; implementer roles take disjoint file
+sets per plan phase; tester after implementation; reviewer before ship (high
+risk makes it mandatory).
+
+**"Launch a campaign for the new feature"** (marketing install) — class:
+plan-campaign, size: standard, domains: 2+. Chain per the marketing sequences
+in chaining-patterns: research → persona/funnel → campaign brief → per-channel
+content production → analytics setup. Agents: researcher roles in parallel at
+the start; content-creator/copywriter roles per channel; content-reviewer role
+before anything publishes (mass-audience send = high risk).
+
+## Anti-Patterns
+
+| Do not | Because |
+|---|---|
+| Spawn a subagent for a two-minute single-file edit | Delegation overhead exceeds the work; quality drops with context loss |
+| Build a five-link chain for a single-domain ask | Every link adds handoff loss; the collapse rule exists for this |
+| Route to a skill or agent you have not confirmed installed | Broken dispatch mid-task; inventory is Step 2 for a reason |
+| Re-route mid-chain without new evidence | Thrash; reroute once per link on evidence, else surface to the user |
+| Copy routing tables from owning references into prompts or docs | They drift; load them at decision time instead |
+| Use this skill for headless cross-CLI or multi-worktree runs | That is the orchestrate skill's layer |
+| Skip the reviewer role on high-risk work because the diff "looks clean" | The gate exists precisely for confident mistakes |
+
+## Failure Handling
+
+A link that fails does not advance the chain. Detour (fix or debug the
+blocker, or rescope the link), then resume at the failed link. Two consecutive
+failures on the same link: stop, report what was attempted, what failed, and
+the smallest missing input — do not loop.
+
+Subagent status handling: `BLOCKED` or `NEEDS_CONTEXT` means change the
+context, scope, or approach before re-delegating. Never resend the same
+failing prompt.
+
+## Handoffs
+
+- Work should run headlessly, across CLIs, or in parallel worktrees → the
+  orchestrate skill (`primekit-orchestrate`, engineer installs).
+- Work needs multiple coordinated sessions → the team skill (`primekit-team`,
+  engineer installs).
+- Needed capability is not installed → the find-skills skill
+  (`primekit-find-skills`, engineer installs), else proceed inline and report the
+  gap.

package/skills/agentkit/references/chaining-patterns.md

@@ -0,0 +1,126 @@
+# Chaining Patterns
+
+How to compose installed skills into a workflow: the skeleton, the link
+contract, context passing, when to collapse, and how to recover. Sequences for
+engineer development work are owned by
+`../../primekit-cook/references/workflow-routing.md` — load that file for them; this
+file never re-lists its tables. Marketing sequences live here because no
+installed reference owns them today; if a marketing routing reference ships
+later, this section slims to a pointer.
+
+## The Skeleton
+
+Every chain is a subset of:
+
+```
+understand → decide → execute → verify → deliver
+```
+
+| Link | Purpose | Typical owners |
+|---|---|---|
+| understand | Gather the facts the next link needs | scout/research skills, explorer roles |
+| decide | Turn facts into an approach the user would accept | brainstorm/plan skills |
+| execute | Produce the artifact | domain skill under a workflow skill |
+| verify | Prove the artifact does what was decided | test/review skills, tester + reviewer roles |
+| deliver | Ship, publish, schedule, or report | ship/publish skills, outcome-first report |
+
+Chains run forward only. A discovered problem creates a detour, not a
+reshuffle.
+
+## Link Contract
+
+- **Entry criteria**: the inputs the link needs exist and are named (a file, a
+  report, a decision). If entry criteria are not met, the previous link is not
+  done — do not start the link anyway.
+- **Exit criteria**: the link produced its artifact and it is verifiable
+  (file written, tests green, draft complete). "Mostly done" does not exit.
+- **Single owner**: one skill or agent owns each link. Helpers feed the owner;
+  they do not share the pen.
+
+## Context Passing
+
+- Chains of one or two links pass context in-conversation.
+- Longer chains write artifacts to files (reports, plans, drafts) and pass
+  paths, not prose summaries — the next link rereads the artifact, so nothing
+  is lost to compression. Use the project's existing report/plan directories
+  (`plans/reports/` where the convention exists).
+- A link's report states: what was produced, where, what the next link needs
+  to know, open concerns. Nothing else.
+
+## Collapse Rule (keep chains short)
+
+Merge or drop a link when ALL of:
+
+1. Its owner would spend under ~5 minutes of focused work.
+2. It produces no artifact a later link rereads.
+3. Skipping it removes no verification demanded by the risk class.
+
+A three-link chain that fits the task beats a five-link chain that fits the
+diagram. Verification links are exempt from collapse at elevated and high
+risk.
+
+## Insertion Rule
+
+Modifiers add links; nothing else does:
+
+- size epic → insert `decide` (planning) if absent, split `execute` by phase.
+- risk elevated → insert `verify` if absent.
+- risk high → insert `verify` AND an independent review, plus user
+  confirmation before the irreversible step.
+- domains 2+ → one execute sub-link per domain, dependency-ordered.
+
+## Engineer Development Sequences
+
+Owned by `../../primekit-cook/references/workflow-routing.md` (ships with every
+PrimeKit install). Load it when the class is build-feature, fix-defect,
+investigate-explain, review-audit, or ship-release on a codebase. If domain
+choice is ambiguous first, `../../primekit-find-skills/references/domain-routing.md`
+resolves it on installs that ship find-skills; otherwise match installed skill
+descriptions.
+
+## Marketing Sequences
+
+For marketing installs. Names below are skill names (`primekit-<name>`) to invoke on
+installs that ship them; guard each link with the Step 2 inventory:
+
+**Campaign** (class plan-campaign):
+
+```
+primekit-marketing-research → primekit-persona → primekit-funnel → primekit-campaign (brief)
+  → per-channel production: primekit-write | primekit-social | primekit-email | primekit-paid-ads
+  → primekit-analytics (tracking setup)
+```
+
+Researcher roles run the research links in parallel; content roles produce
+channels in parallel once the brief exists; content-reviewer role gates every
+channel before publish (mass-audience send = high risk).
+
+**Single content piece** (class create-content):
+
+```
+brand voice input (primekit-brand if installed) → primekit-write → primekit-seo (organic reach
+only) → content-reviewer role → publish or schedule (primekit-social)
+```
+
+**Launch** (class plan-campaign, launch flavor):
+
+```
+primekit-launch-strategy → primekit-campaign → assets (primekit-banner-design, primekit-video as
+needed) → distribution channels → primekit-analytics
+```
+
+**Funnel diagnosis** (class analyze-performance):
+
+```
+primekit-analyze → primekit-funnel (bottleneck) → primekit-form-cro or primekit-onboarding-cro (fix)
+  → primekit-ab-test-setup (prove it)
+```
+
+## Failure and Detours
+
+- A failed link never advances the chain. Detour: diagnose (fix/debug skill or
+  debugger role), or rescope the link, then resume AT the failed link.
+- Two consecutive failures of the same link: stop the chain, report what ran,
+  what failed, and the smallest missing input.
+- New information that invalidates a completed link: say so explicitly, redo
+  from that link forward. Silent partial redo corrupts the chain's artifacts.