Prime

/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.

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.

Playbooks, not generic advice

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.

Modes

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

/flow-next:prime

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.

Tips

• 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:

• Evidence-first - prime’s substance-over-existence rule is the same bias the rest of the pipeline runs on.
• 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.