docs/codex-plugin.md

# Codex plugin support

This repository can be installed as a Codex plugin. The plugin packages the existing planning skills under `skills/` and exposes them through the Codex plugin manifest at `.codex-plugin/plugin.json`.

## What is included

The Codex plugin includes these skills:

- `planning-router`
- `wayfinding`
- `framing-doc`
- `shaping`
- `sketch-reconciliation`
- `breadboarding`
- `statechart`
- `interface-contracts`
- `executable-breadboards`
- `dumplink`
- `breadboard-reflection`
- `kickoff-doc`
- `feed-planning-context`
- `lead-user-research`

The repo also includes tool-neutral orchestration and harnessing docs:

- `.agent-orchestration.yaml`
- `docs/codex-usage.md`
- `docs/agent-workflow.md`
- `docs/loop-prompting.md`
- `docs/agent-run-records.md`
- `docs/lifecycle-hooks.md`

## Planning profiles

For interactive work, Codex should default to **collaborative shaping**:

> Start from R, S, evidence, or a focused uncertainty. Let Working R/S/fit/spikes/candidate breadboards inform one another. Gate what becomes Accepted and what gets built.

Use the **gated/orchestrated profile** only when the user, team policy, or automation explicitly requests deterministic prerequisites. Both profiles preserve the same hard promotion gates before selection, selected-design authority, slice selection, and build.

See `docs/codex-usage.md` for prompt recipes.

## Operational boundary

This is intentionally a skill-only plugin. It guides Codex's existing repository tools but does not grant access to external systems. Add required or optional apps only when the workflow must reach a separate repository service, document store, issue tracker, design system, or other connected source. App permissions and source-system permissions remain authoritative. The optional MCP server in this repository is a separate adapter and is not silently activated by installing the Codex plugin.

## Repo-local marketplace

The repo includes a local marketplace file at:

```text
.agents/plugins/marketplace.json
```

That marketplace points Codex at this repository as a local plugin source.

## Install from GitHub

### Codex CLI

Add this repository as a marketplace source, then install the plugin explicitly:

```bash
codex plugin marketplace add mattlane66/planning-skills-for-agents-and-humans --ref main
codex plugin add planning-skills-for-agents-and-humans@planning-skills-marketplace
```

Start a new Codex task after installation so the skill inventory is rediscovered. You can also open `/plugins` inside Codex to inspect the installed marketplace and plugin. Then open the **product repository** where planning artifacts and implementation live and invoke the installed skills there. Preserve that repository's existing `AGENTS.md`; do not copy this repository's root instructions over product-specific build, test, security, or architecture rules.

### Codex app / managed workspace

Eligible workspace admins can import this repository directly as a GitHub plugin marketplace from **Workspace settings → Plugins → Add → Import marketplace**. Use the repository URL as the source and leave **Path** blank because `.agents/plugins/marketplace.json` is at the repository root. After the plugin is installed for the relevant role or user, select it from **Sources → Use plugins** in a supported Codex task view.

The CLI marketplace command and managed-workspace import are two installation surfaces for the same packaged method; neither changes the product repository's own authority.

## Use

### Collaborative solution-first shaping

```text
Use the shaping skill in collaborative mode. I already have a rough solution. Capture it as Shape A, extract the provisional requirements it implies, and move among R, S, fit checks, focused spikes, and candidate breadboarding as useful. Keep Working material separate from Accepted intent and do not select for me.
```

### Collaborative requirements-first shaping

```text
Use the shaping skill in collaborative mode. Start from these requirements and constraints, let shapes emerge, and return to R whenever fit, spikes, or candidate evidence reveal something missing.
```

### Focused spike

```text
Use the shaping skill to run a focused spike on this one unknown. Return explicit implications for R, S, fit, and Appetite. Do not make the product decision.
```

### Candidate breadboard

```text
Use the breadboarding skill in candidate-shape mode for Shape A. Requirements are Working and Appetite is unset. Clarify only this named behavioral uncertainty, label all dependent fit claims provisional, and return the implications to shaping.
```

### Gated / orchestrated planning

```text
Use the gated/orchestrated profile from .agent-orchestration.yaml. Enforce the strict prerequisites and stop at every human promotion gate.
```

### Other capabilities

```text
Use the wayfinding skill to chart this bounded multi-session planning effort as dependent decision tickets. Keep accepted results in canonical planning artifacts.
```

```text
Use the framing-doc skill because the problem, outcome, and boundary are genuinely unclear.
```

```text
Use the statechart skill to derive transitions for a selected stateful portion of an accepted breadboard without replacing the breadboard as source of truth.
```

```text
Use the interface-contracts skill to define the plain-language boundary contracts for this selected slice.
```

```text
Use the executable-breadboards skill to create examples, fixtures, expected outputs, edge cases, and acceptance tests before implementation.
```

```text
Use the dumplink skill to turn this selected, bounded project into vertical task groups with dependency-aware sequence, risk states, and scope cuts. Treat each task group as a judgeable implementation slice. Stop for approval and active task-group selection before creating a build handoff.
```

```text
Use the feed-planning-context skill to package only the accepted planning material relevant to the active implementation slice. Exclude Working alternatives and candidate breadboards as build scope.
```

```text
Use docs/loop-prompting.md and templates/drift-check.md to check whether implementation has drifted from the selected planning artifacts.
```

## Maintenance

Keep the root skill folders and the `skills/` copies aligned:

```text
planning-router/              -> skills/planning-router/
wayfinding/                   -> skills/wayfinding/
framing-doc/                  -> skills/framing-doc/
shaping/                      -> skills/shaping/
sketch-reconciliation/        -> skills/sketch-reconciliation/
breadboarding/                -> skills/breadboarding/
statechart/                   -> skills/statechart/
interface-contracts/          -> skills/interface-contracts/
executable-breadboards/       -> skills/executable-breadboards/
dumplink/                     -> skills/dumplink/
breadboard-reflection/        -> skills/breadboard-reflection/
kickoff-doc/                  -> skills/kickoff-doc/
feed-planning-context/        -> skills/feed-planning-context/
lead-user-research/          -> skills/lead-user-research/
```

The root folders are canonical. `skill-inventory.txt` defines the complete packaged set, and the `skills/` folder is the generated form Codex reads through `.codex-plugin/plugin.json`.

After changing a canonical skill, run:

```bash
bash scripts/sync-packaged-skills.sh
bash scripts/check-repo-health.sh
```