# Prime

Source: https://flow-next.dev/skills/prime/

Opinionated agent-readiness assessment - classifies your project, judges substance over existence, and leads with a verdict + ranked next-actions.

`/flow-next:prime` runs a structured assessment of how ready a repo is for agentic work.

From 2.13.0 prime is **opinionated and structure-aware**: it first classifies what kind of project it is looking at, then judges **substance, not existence**, and leads with a **verdict + ranked next-actions** instead of a maturity percentage. It is inspired by Factory.ai’s Agent Readiness framework; the 8-pillar scan remains as the evidence layer underneath.

## Why this matters

Existence checks lie. A repo can carry a `CLAUDE.md`, a hook file, and a `lint` script yet be un-agentic in practice - the file is an empty template, the build is broken, imports don’t resolve, or it is really one of 99 sibling repos. Agents waste cycles when:

* **No closed verify loop** - can’t confirm a change works without a full CI round-trip.
* **Undocumented env vars** - guesses, fails, guesses again.
* **No agent instruction file (or a generic/stale one)** - re-discovers conventions every run.
* **The app can’t be built or driven** - a legacy stack with no headless build has no feedback loop at all.

These are environment problems, not agent problems. Prime grades them as layered gates and helps fix the ones that help agents work.

Readiness is also where automation pays out now. The best engineers always multiplied their own output by automating - lint rules, e2e suites, editor tooling; with agents in the loop, every rule, doc, and verified command in the repo multiplies every agent run that follows. Claude Code’s creator [makes the same case](https://x.com/bcherny/status/2077460395279692197): when a PR gets rejected for picking the wrong framework or breaking an architectural pattern, the repo failed to encode knowledge it already had. Prime audits whether your repo would pass that bar - CLAUDE.md substance, commands that actually execute, the eight pillars below.

## Classification first (Phase 0.5)

Before scoring anything, prime builds a five-axis profile that parameterizes everything downstream (scout dispatch, N/A denominators, report shape, playbook selection):

| Axis              | Values                                                                   |
| ----------------- | ------------------------------------------------------------------------ |
| Lifecycle         | greenfield / hybrid / brownfield                                         |
| Topology          | two independent bits: monorepo, constellation member                     |
| Size / legibility | small / medium / large / huge (LOC band + file counts)                   |
| Stack(s)          | manifest-gated, 15+ stack rows incl. legacy (Delphi, PL/SQL, VB6, COBOL) |
| Delivery shape(s) | web service, CLI, library, desktop, … (multi-valued)                     |

Plus an `assessment_scope`: `repository`, `workspace-member` (classified against the repo root), or `constellation-home-base` (a non-git folder of sibling repos - priming each repo stays valid; the home base adds a coordination layer).

The deterministic half ships as a pure-stdlib emitter, `flowctl prime classify [root] --json` - bounded, no LLM, \~seconds even on multi-million-LOC repos, with per-collector completeness diagnostics and a strict redaction contract (key names only, never secret values). All judgment stays in the skill.

## The operability ladder + hard gates

Phase 2 judges whether an agent can actually *operate* the repo from **executed evidence**, per surface and per workspace member:

| Tier | Evidence                        |
| ---- | ------------------------------- |
| 1    | The build actually runs         |
| 2    | Tests are discoverable and run  |
| 3    | The app boots to a ready signal |

Three **hard gates** are named in the headline and cap the maturity level at 2 when failing: **G1** (build actually runs), **G2** (tests discoverable when a framework is claimed), **G3** (agent-file quoted commands resolve and execute). The old maturity level still exists but is demoted to secondary metadata.

New agent-readiness groups feed the verdict: agent observability & drivability (AO/DR), tooling/operability (TO), and harness & permissions (HP - including P0 flags for inline MCP secrets and suspicious hook content). The enable-QA recommendation fires only at operability tier 3 with the DR core passing.

## Stack-specific playbooks

Five delivery-shape playbooks (greenfield / standard / monorepo / huge-legacy / constellation) plus the LEG1-LEG9 legacy legibility patterns drive the ranked next-actions. The per-stack matrix is **data, not skill logic** - adding a stack is a table row; an unknown stack degrades honestly to the generic operability ladder.

## The eight pillars (evidence layer)

Agent readiness (1-5) is scored and fixed. Production readiness (6-8) is reported only.

| # | Pillar             | What it checks                                                                                               |
| - | ------------------ | ------------------------------------------------------------------------------------------------------------ |
| 1 | Style & validation | Linters, formatters, type checking, feedback gates at the right layer.                                       |
| 2 | Build system       | Build tools, commands, lock files, monorepo tooling - executed, not assumed.                                 |
| 3 | Testing            | Test framework, commands, coverage substance (a zero threshold is a stub).                                   |
| 4 | Documentation      | README, `CLAUDE.md` substance, setup docs, freshness vs. churn.                                              |
| 5 | Dev environment    | `.env.example` cross-referenced against real env reads, Docker, devcontainer.                                |
| 6 | Observability      | Logging, tracing, metrics, error tracking, health endpoints.                                                 |
| 7 | Security           | Branch protection (incl. rulesets), enforced secret scanning, CODEOWNERS, Dependabot.                        |
| 8 | Workflow & process | CI that *actually gates* (trigger + test/lint in the same workflow), PR/issue templates, release automation. |

## Invocation

| Mode              | Behavior                                                                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Default           | Classify, full scan, verdict + ranked actions, interactive remediation for pillars 1-5.                                                                                  |
| `--report-only`   | Scan and report; offer no fixes.                                                                                                                                         |
| `--fix-all`       | Apply every scaffold-safe agent-readiness fix without asking.                                                                                                            |
| `--classify-only` | Print the classification block and exit in seconds - the portfolio-triage entry point for sweeping 100+ repos. Never asks; prints confidence + a would-ask list instead. |
| `<path>`          | Assess a different repo root.                                                                                                                                            |

When prime can’t infer the structure (ambiguous topology, thin constellation signals), it asks a bounded set of clarification questions and records the answers to the agent instruction file - autonomous runs never block.

## What gets fixed vs reported

| Pillars | Category             | Remediation                                                                         |
| ------- | -------------------- | ----------------------------------------------------------------------------------- |
| 1-5     | Agent readiness      | Fixes offered via blocking questions (scaffold-safe artifacts only in `--fix-all`). |
| 6-8     | Production readiness | Reported only; address independently.                                               |

## Worked example

```plaintext
/flow-next:prime
```

```text
Classification: brownfield / single-repo / medium / TypeScript + Postgres / web-service
Operability: tier 2 of 3 (build runs, tests run; no boot-to-ready signal detected)
Hard gates: G1 pass, G2 pass, G3 FAIL - CLAUDE.md quotes `npm run typecheck`, script missing
Verdict: agent-ready with one blocker. Ranked next actions:
  1. Fix or remove the dead typecheck command (G3)
  2. Add a boot health signal to reach operability tier 3
```

Everything above is executed evidence - commands actually ran; nothing passed on file existence alone.

* Run it before pointing any agent workflow at an unfamiliar repo; a failing hard gate (dead documented commands are the classic) sabotages every future agent session quietly.
* `--classify-only` is the cheap portfolio triage mode - classification without the full scan.
* The verdict names the single cheapest move up the ladder - do that one first, then re-run; readiness compounds.

## Dynamic usage

Recipes that compose with prime in the [cookbook](https://flow-next.dev/guides/cookbook/):

* [Evidence-first](https://flow-next.dev/guides/cookbook/#evidence-first) - prime’s substance-over-existence rule is the same bias the rest of the pipeline runs on.
* [Integration tricks](https://flow-next.dev/guides/cookbook/#integration-tricks) - prime’s fixes (agent docs, runnable commands) improve every tool that reads the repo, not just flow-next.

## Next step

After remediation, re-run prime to confirm the verdict improved. Then move on to whatever spec the readiness gap was blocking.