Test Roadmap

On invocation: announce "Running paad:test-roadmap v1.31.0-preview", then immediately proceed with the steps below — do not stop after announcing.

EXPERIMENTAL SKILL. Its arguments, output paths, and behavior may change or be withdrawn in any release, including patch releases. It is not covered by the semver guarantees the other paad skills carry. Unlike every other paad skill, this one writes code and commits it — tests, one commit per phase, onto your working branch. Report rough edges at https://github.com/Ovid/paad/issues.

test-roadmap

This file is the router. The routing itself stays dumb on purpose: one check, two routes, nothing else. A couple of preconditions guard it first. All the substance — grading, planning, writing tests, bug injection — lives in references/ and loads only once routing has picked a mode.

Pre-flight and routing:

digraph route {
  "Inside a git repo?" [shape=diamond];
  "STOP: needs a git checkout" [shape=box, style=bold];
  "Detached HEAD?" [shape=diamond];
  "origin/HEAD pointer resolves?" [shape=diamond];
  "Current branch == default branch?" [shape=diamond];
  "Name matches a well-known primary (main/master/trunk/develop/...)?" [shape=diamond];
  "ASK: is this your main development line?" [shape=diamond];
  "OFFER: create a working branch" [shape=box];
  "Developer agrees?" [shape=diamond];
  "STOP: never build on the primary branch" [shape=box, style=bold];
  "git switch -c <name>" [shape=box];
  "paad/test-roadmap/test-roadmap.md exists?" [shape=diamond];
  "Load references/build-test-roadmap.md (Detect, Grade, Plan, Critique, Write)" [shape=box];
  "Load references/execute-test-roadmap.md (next phase, break-it-check, commit)" [shape=box];

  "Inside a git repo?" -> "STOP: needs a git checkout" [label="no"];
  "Inside a git repo?" -> "Detached HEAD?" [label="yes"];
  "Detached HEAD?" -> "OFFER: create a working branch" [label="yes"];
  "Detached HEAD?" -> "origin/HEAD pointer resolves?" [label="no"];
  "origin/HEAD pointer resolves?" -> "Current branch == default branch?" [label="yes (authoritative)"];
  "origin/HEAD pointer resolves?" -> "Name matches a well-known primary (main/master/trunk/develop/...)?" [label="no"];
  "Current branch == default branch?" -> "OFFER: create a working branch" [label="yes"];
  "Current branch == default branch?" -> "paad/test-roadmap/test-roadmap.md exists?" [label="no"];
  "Name matches a well-known primary (main/master/trunk/develop/...)?" -> "OFFER: create a working branch" [label="yes"];
  "Name matches a well-known primary (main/master/trunk/develop/...)?" -> "ASK: is this your main development line?" [label="no"];
  "ASK: is this your main development line?" -> "OFFER: create a working branch" [label="yes / unsure"];
  "ASK: is this your main development line?" -> "paad/test-roadmap/test-roadmap.md exists?" [label="no"];
  "OFFER: create a working branch" -> "Developer agrees?";
  "Developer agrees?" -> "STOP: never build on the primary branch" [label="no"];
  "Developer agrees?" -> "git switch -c <name>" [label="yes"];
  "git switch -c <name>" -> "paad/test-roadmap/test-roadmap.md exists?";
  "paad/test-roadmap/test-roadmap.md exists?" -> "Load references/execute-test-roadmap.md (next phase, break-it-check, commit)" [label="yes"];
  "paad/test-roadmap/test-roadmap.md exists?" -> "Load references/build-test-roadmap.md (Detect, Grade, Plan, Critique, Write)" [label="no"];
}

Before routing: confirm you're in a repo

compatibility: Requires git above means this skill needs a working git checkout — build mode fans out grading subagents against the tree as it stands, and execute mode's break-it-check gate runs bug injection in a disposable git worktree. If the current directory isn't inside a git repo, say so and stop before loading either mode file.

Before routing: confirm you're on a working branch

This skill commits as it goes — build mode commits the roadmap, execute mode commits each phase's tests — all onto the branch you are on right now. A half-built test suite landing on the developer's main development line is exactly what this check prevents, the same spirit as running a code review on a feature branch rather than on main. So before routing, confirm the current branch is a working branch, not the primary one.

Identify the primary branch from repo signals, in order — stop at the first that decides:

1. Detached HEAD — git symbolic-ref -q HEAD prints nothing. There is no branch for the suite to accumulate on at all; treat it like being on the primary branch and offer a working branch (below).
2. The repo's own default-branch pointer — git symbolic-ref -q --short refs/remotes/origin/HEAD resolves to e.g. origin/main; strip the remote prefix for the default branch name. If the current branch (git symbolic-ref -q --short HEAD) equals it, you are on the primary branch. This is the authoritative signal and needs no built-in list of names.
3. No such pointer (a local-only repo, or one where it was never set) — fall back to the well-known primary names: main, master, trunk, develop, devel, and the like — examples, not a closed list, the same stance Stage 1 takes on manifests. If the current branch name matches one, treat it as primary. If it matches none and step 2 could not confirm, ask the developer once, in plain words, whether this is their main development line — never silently proceed on a branch that might be it. Being wrong toward asking costs a keystroke; being wrong toward building on the main line is the harm this check exists to prevent.

When the current branch is the primary one (or HEAD is detached), do not route yet. Say why in plain words — "I build the test suite up commit by commit, and you don't want those landing on your main branch while it's half-done, so let's put them on a working branch" — then offer to make one: propose a name (test-roadmap is a fine default), and on the developer's OK run git switch -c <name> (or git checkout -b <name> on older git) and continue to routing. If they decline, stop — never build or execute on the primary branch.

This is the skill's one branch: a single working branch, created at invocation only when needed. It is not a per-phase branch — execute mode still commits every phase onto whatever working branch you are on, and the suite accumulates there (see references/execute-test-roadmap.md § What execute mode writes). Both mode files assume this check has already passed and never re-run it; the guard lives here, once.

Route

paad/test-roadmap/test-roadmap.md exists?  →  load references/execute-test-roadmap.md
                       absent  →  load references/build-test-roadmap.md

That is the entire routing logic — one file existence check, two branches. paad/test-roadmap/test-roadmap.md is the roadmap this skill itself writes at the end of build mode, so its presence is exactly the signal that a previous run already did Detect/Grade/Plan/Critique/Write and there is a phased plan to execute against. Its absence means this is either the first run against this repo, or a run after that file was deleted — either way, build it.

If it ever grows a third condition, that is a signal something has been put in the wrong place — take it back to build-test-roadmap.md or execute-test-roadmap.md, not to this file.

This router never loads references/break-it-check.md, references/test-pushback.md, or references/test-theater.md directly. Those three are loaded by whichever of the two mode files needs them, at the point in their own protocol that needs them — not from here.

Entering build mode

Before build mode can plan anything, it needs to know what it's planning for. The first thing it does — Stage 1, Detect — is identify the stack from manifests and config rather than assumption (package.json, pyproject.toml, go.mod, Cargo.toml, Gemfile, and so on: examples, not a closed table), then determine how tests are invoked and what test files already exist. The skill must never hardcode a language; where it needs a per-ecosystem fact, it looks for the signal in the repo instead of consulting a built-in list.

The full five-stage protocol — Detect, Grade, Plan, Critique, Write — lives in references/build-test-roadmap.md. Load it now if paad/test-roadmap/test-roadmap.md is absent.

Entering execute mode

Load references/execute-test-roadmap.md now if paad/test-roadmap/test-roadmap.md exists. It reads that file's ## Decisions section once, selects the next phase per the completion protocol, and gets on with writing tests — it does not re-detect or re-ask anything build mode already settled.