Adopt the Five-Phase Agentic Workflow

Set up Discovery → Design → Development → Testing → Released in a repository: the plan lifecycle, plus the skills that serve each phase.

What this does, and what it delegates

Plot owns the plan lifecycle. It is project-agnostic by design, so it knows nothing about this organisation's tooling. Its /plot-init probes the repo and sets up plans, branches, and config — this skill does not reimplement any of that.

This skill owns the connective layer: which of our skills serves which phase, where our Definition of Done lives, and how session logs get written. That mapping is the thing a newcomer (human or agent) cannot infer, and it is what turns a set of installed skills into a workflow.

The dependency runs one way. This skill knows Plot; Plot must never know this skill. If Plot changes, adjust here — not there.

Prerequisites

Plot must be available (plugin, pnpm dlx skills add, or a symlink into ~/.claude/skills/). If /plot-init is not available, say so plainly and stop: the phases below are all anchored to plan states, so there is nothing useful to install without it.

Steps

1. Run Plot's own adoption

/plot-init

It probes the repo (git host, quality-gate scripts, ticket scheme, commit notation, existing planning systems) and proposes a ## Plot Config. Let it run to completion and let the user confirm its proposals — do not answer on their behalf, especially the Definition of Done: /plot-init finds candidate scripts, but only a human knows which gate a merge.

If /plot-init reports that a Plot Config already exists, skip to step 2. This skill is additive over an existing Plot setup.

2. Make sure Claude Code actually loads the hub

Claude Code loads CLAUDE.md on its own; it never loads AGENTS.md. If /plot-init used CLAUDE.md as the hub, skip this step. If it used AGENTS.md, check CLAUDE.md:

• Missing: create it with exactly one line: @AGENTS.md.
• A prose pointer ("see AGENTS.md", "read AGENTS.md before working here"): replace it with the import line @AGENTS.md. An agent can skim past a sentence; it cannot skip an import.
• Own rules already in it: add @AGENTS.md as the first line, keep the rest, and tell the user the file now holds two rule sources — merging them is theirs to decide, not this skill's.

A hub an agent does not load cannot govern anything written into it in the next step.

3. Write the phase-to-skill map into the hub

This is the core of this skill. Append to the hub doc (CLAUDE.md or AGENTS.md — whichever /plot-init used), adapted to what the repo actually has. Only list skills that exist here; a map pointing at absent tools is worse than no map.

## Agentic Workflow

Five phases, each tied to a plan state on Plot's board.

| Phase | Plan state | Commands and skills |
|-------|------------|---------------------|
| **Discovery** | Draft | `triage-ticket` for an incoming ticket · `story-tracking` for multi-session work · `/plot-idea` → `challenge-the-plan` |
| **Design** (optional) | Design | needs-design or spike work before approval → `/plot-approve` |
| **Development** | Approved | `/plot-implement` · `test-driven-development` · `commit-notation` · `handling-pull-requests` → `/plot-deliver` |
| **Testing** | Delivered | `/plot-deliver --verify` · `reality-check` |
| **Released** | Released | `/plot-release rc` → verify the checklist → `/plot-release`, or the project's own release process |

Design is optional: small, well-understood work skips it and goes from a
Draft plan to approval.

**Plans vs. session logs.** A plan says what will be built and is frozen on
approval. A session log says how it was decided — including the alternatives
that were rejected — stays amendable, and outlives the plan. If it must be
true *before* building starts, it belongs in the plan; if it answers "why not
the other way?", it belongs in a log.

Append only. Preserve every existing rule verbatim; this repo's hub may carry conventions that predate any of this.

4. Wire the session-log seam

If this repo keeps session logs (docs/sessionlogs/ or similar) and bye is in use, add the section bye looks for:

## Session Wrap Up

Include the Plot context for this session in the log:

    <plot-skill-dir>/scripts/plot-context.sh   # Plot's plot-context.sh, in the Plot skill's scripts/ directory

It reports the governing plan, its phase, its wave, and its PRs as JSON. An
empty `plan_slug` means the branch belongs to no plan — say that rather than
guessing, because a log attributed to the wrong plan outlives the session that
mis-attributed it.

Record decisions and their **rejected alternatives** here, not in the plan.

bye writes the log; Plot only supplies the facts. Do not build a second log-writer.

5. Record the Definition of Done

/plot-init proposes candidate scripts; this step states the DoD as a rule the repo can be held to. Put it in the hub, in this repo's own terms:

• Which commands must pass before a PR is ready
• Which changes need tests, and of what kind (unit? BDD scenarios?)
• Which changes need documentation
• Whether a changeset is required
• Language and spelling rules for user-facing text (for German repos: schweizer-schreibweise, no ß)

Ask; do not infer. A DoD nobody agreed to is a DoD nobody follows.

6. Point at host and commit conventions — do not restate them

Where the repo is on Bitbucket, note that working-with-bitbucket-api covers PR operations and that gh is not available. Where commit conventions exist, point at commit-notation.

Reference, never duplicate. A copied command table in a hub doc goes stale the day the tool changes, and then two sources disagree. Plot's own plot-host.sh already abstracts the host CLI, so skills never need the translation themselves — the note is for agents that reach for gh out of habit.

7. Offer a dry run

The lifecycle is best learnt by walking it once, and this adoption is a convenient subject:

Want to walk this adoption through the lifecycle as its own plan? /plot-idea → challenge-the-plan → /plot-approve → the changes above → /plot-deliver.

Caveat: if Plot was installed as a plugin this session, its slash commands activate only in a new session. Say so rather than letting the user hit it.

8. Summarise, including what you deferred

State what was installed, what the user must still do (DoD confirmation, plugin activation, anything unwritable), and what the next action is. List deferrals explicitly — an adoption that silently skipped a step is worse than one that reports it.

Guardrails

• Additive only. Never move, rewrite, or delete existing content. A repo with several planning systems keeps them all; describe the boundary and let the humans decide what is canonical.
• Never fail the whole adoption on one blocked step. The steps are largely independent. If a file cannot be written, print exactly what to add and where, then continue.
• Never invent the Definition of Done. Ask.
• Never reimplement Plot. If setup logic seems missing, it belongs in /plot-init, upstream.
• Never copy a command table. Point at the skill that owns it.

Common Mistakes