| name | agent-readiness |
| description | Interpret and act on the Agent Readiness score produced by /project-metrics: 8 Factory pillars × 5 maturity levels × 80%-per-level gate + Praxion-native Pillar 9 Manageability sub-score. Read the readiness block from METRICS_REPORT_*.json, understand the LLM-judged criteria (naming_conventions, test_quality, readme_quality, docs_agent_friendliness), prioritize remediation by failing criterion → pipeline handoff, and interpret level-by-level progress. Triggers: reading or acting on an agent readiness report, understanding why a project scored a given level, deciding how to improve readiness, interpreting mechanical vs LLM criteria, running readiness without an API key, grounding a new readiness run on a prior report.
|
| allowed-tools | ["Read","Glob","Grep","Bash"] |
| compatibility | Claude Code |
Agent Readiness
Interpretation and remediation skill for the /project-metrics Agent Readiness
capability — a Factory-aligned rubric that scores a project's readiness for
autonomous agent collaboration across 8 industry-standard pillars and one
Praxion-native sub-score.
This skill does NOT have a standalone /readiness command. Readiness runs
through /project-metrics, writing its results into the readiness block of
METRICS_REPORT_*.json.
Satellite files (loaded on-demand):
- references/rubric.md — full criterion table (id, pillar, level, scope, llm-or-mechanical), applicability predicates, kodus-seed attribution, 80%-per-level gate mechanics
How Readiness Rides /project-metrics
The readiness engine is a ReadinessCollector embedded in the metrics runner.
It always resolves as Available (pure filesystem reads) and always runs by
default. The readiness block appears at the root of METRICS_REPORT_*.json
under readiness.data — the readiness block sits at the metrics-report JSON
root, not nested under a collectors key.
Invocation patterns
| Goal | Command |
|---|
| Full run with LLM scoring (default when auth present) | /project-metrics |
| Mechanical-only, fast, free, no API key needed | /project-metrics --mechanical-only |
| Hard-fail if LLM tier cannot run | /project-metrics --require-readiness-ai |
| Combine with coverage refresh | /project-metrics --refresh-coverage |
The --mechanical-only flag is the recommended mode for CI pipelines and
offline environments. It scores all 25 mechanical criteria and marks the
4 LLM-judged criteria as llm_skipped in the output.
Auth detection
The judge checks environment variables in this order:
ANTHROPIC_API_KEY → API-key auth (x-api-key header)CLAUDE_CODE_OAUTH_TOKEN → OAuth auth (Authorization: Bearer header)
When neither is set: the run still exits 0, all 4 LLM criteria are set to
passed: null, and readiness.data.llm.status == "llm_skipped". The level is
computed from mechanical criteria only with readiness.data.note == "mechanical-only".
Grounding on prior reports
When the LLM tier runs, the judge loads the most-recent
METRICS_REPORT_*.json from .ai-state/metrics_reports/, extracts the
readiness.data.criteria block, and passes each criterion's prior verdict to
the LLM call as grounding context. readiness.data.llm.grounded_on names the
prior report file, or null on the first run. This grounding reduces scoring
variance from run to run (Factory's 7%→0.6% variance reduction).
The Rubric — Two-Layer Score
Layer 1: 8 Factory Pillars × 5 Levels (the comparable number)
| Pillar | ID | Description |
|---|
| Style & Validation | style_validation | Linter, formatter, editorconfig, pre-commit, naming conventions |
| Build System | build_system | Build manifest, lockfile, CI pipeline |
| Testing | testing | Test directory, CI runs tests, test quality |
| Documentation | documentation | README, contributing guide, README quality, agent-friendliness |
| Dev Environment | dev_environment | .gitignore, container config, .env.example |
| Debugging & Observability | observability | Logging config, health check |
| Security & Governance | security | Dependency scanning, secrets policy, license |
| Code Quality | code_quality | Type-checker config, complexity gate |
Level gate: a project achieves level N when ≥80% of applicable criteria
at levels 1 through N collectively pass. Non-applicable criteria are excluded
from both numerator and denominator. This is the number that compares to the
kodus/Factory benchmark.
Level interpretation:
| Level | Signal | Typical state |
|---|
| 1 | Minimal | Has test dir, build manifest, README, .gitignore, license |
| 2 | Structured | Adds lockfile, formatter, .env.example, secrets policy, README quality |
| 3 | Practiced | CI pipeline + tests, pre-commit, contributing guide, container, observability, type-checker, dep-scanning |
| 4 | Advanced | Health check, complexity gate, test quality, agent-friendly docs |
| 5 | Factory-ready | All criteria at or above 80% pass rate across all 8 pillars |
Layer 2: Pillar 9 Manageability (the Praxion sub-score)
Pillar 9 is never folded into the 8-pillar level. It appears separately as
readiness.data.manageability so the Factory-comparable level stays clean.
| Criterion | Level | What it checks |
|---|
c.manage.claudemd | 1 | CLAUDE.md project block present |
c.manage.agents_md | 2 | AGENTS.md present (INFO — not counted as failure if absent) |
c.manage.git_hooks | 3 | Project git hooks installed |
c.manage.ai_state | 3 | .ai-state/ intelligence directory present |
c.manage.agents_md is an informational criterion: its absence is noted but
does not count as a failed criterion in the manageability denominator.
The 4 LLM-Judged Criteria
These criteria require LLM scoring and carry llm: true in the output. They
are excluded from every denominator when llm_skipped.
| Criterion ID | Pillar | Level | What the judge evaluates |
|---|
c.style.naming_conventions | style_validation | 3 | Naming conventions are consistent and intention-revealing across the codebase |
c.testing.test_quality | testing | 4 | Tests are behavior-focused and meaningfully cover the code (not just line coverage) |
c.docs.readme_quality | documentation | 2 | README explains setup, usage, and architecture clearly |
c.docs.agent_friendliness | documentation | 4 | Documentation is structured for agent consumption (clear headings, CLAUDE.md, structured context) |
When LLM criteria are scored, the judge uses forced tool-calling to get a
structured {passed: bool, rationale: str} verdict. The model is
claude-haiku-4-5 with a 30-second timeout.
Reading the Readiness Block
The readiness namespace in the JSON report has this shape:
{
"readiness": {
"status": "ok",
"duration_seconds": 0.42,
"issues": [],
"data": {
"level": 3,
"pass_pct": 0.81,
"note": null,
"pillars": [
{
"id": "style_validation",
"name": "Style & Validation",
"level_pass": [1, 2],
"pass_pct": 1.0,
"numerator": 4,
"denominator": 4
}
],
"manageability": {
"id": "manageability",
"name": "Praxion Manageability",
"pass_pct": 0.75,
"numerator": 3,
"denominator": 4
},
"criteria": [
{
"id": "c.style.linter_config",
"pillar": "style_validation",
"level": 1,
"scope": "repo",
"applicable": true,
"passed": true,
"llm": false,
"rationale": "a linter configuration is present"
}
],
"llm": {
"status": "llm_skipped",
"model": null,
"grounded_on": null
}
}
}
}
note: "mechanical-only" appears when LLM criteria were skipped.
llm.status is one of: "pending" (before enrichment), "llm_skipped",
"scored", or "llm_error".
Prioritized Remediation Workflow
When a project is at level N and you want to reach level N+1:
-
Identify failing criteria — filter data.criteria where passed == false
and level <= N+1. These are the blockers for the next level.
-
Sort by urgency — mechanical criteria first (no API key needed; fast to
fix); LLM criteria second.
-
Assess pillar coverage — if one pillar is dragging pass_pct below 80%,
focus there before spreading effort.
-
Handoff to the pipeline:
- For the universal code-quality baselines (
c.style.precommit_config,
c.codequality.typecheck_config, c.docs.contributing, plus the L1–L2
linter/formatter/editorconfig criteria): the fastest remediation is
/onboard-project Phase 8e, which installs all of them idempotently
from Praxion's canonical baseline assets (never overwriting an existing
config). Re-run it; only escalate to a feature pipeline for project-specific
tuning of the installed configs.
- For other infrastructure / config gaps (missing lockfile, CI):
hand off to
implementation-planner with the failing criterion as a
concrete acceptance criterion.
- For
c.testing.test_quality (LLM-judged — behavior-focused tests that
meaningfully cover the code, not just line %): hand off to test-engineer
to add/strengthen behavior-focused tests (describe behavior, not IDs), and
publish coverage via /project-coverage (the test-coverage skill) so the
quality is visible. Line coverage alone does not move this criterion — the
judge weighs whether tests assert meaningful behavior.
- For other quality improvements (naming conventions, README):
hand off to
researcher first to gather current state, then systems-architect
to design the improvement.
- For
c.observability.logging_config / c.observability.healthcheck:
these are service-conditional. If the project is a runtime service, follow
the observability skill's Service Observability Baseline (declare a logging
dependency + wire a health surface). If it is a library / CLI / harness, do
not add a vanity dependency — weight the Observability pillar down in
.ai-state/readiness_config.json instead (see rubric § Pillar Weighting).
- For Praxion manageability gaps: use
/onboard-project (idempotent) to
install missing surfaces (CLAUDE.md block, git hooks, .ai-state/).
-
Re-run and compare — after fixes, run /project-metrics again. The
new report grounds on the prior one if LLM criteria were scored.
Gotchas
-
Pillar 9 is never in the level. Do not interpret manageability.pass_pct
as contributing to the 8-pillar level. It is a separate Praxion-specific
signal.
-
Non-applicable criteria are excluded. A monorepo may have scope="app"
criteria that produce applicable: false; these never appear in any
denominator, so a project with 0 apps that scores 100% on repo criteria is
not being "cheated" — it simply has no app-scoped surface yet.
-
--require-readiness-ai hard-fails before any write. If auth is absent
and this flag is set, the process exits non-zero and no report is written.
Do not use this flag in offline CI.
-
llm.status == "pending" means the collect pass completed but enrichment
has not run yet. This state should not appear in the written report — if it
does, the enrichment step was skipped or errored without updating the block.
-
The 80% gate is cumulative through levels. A project that passes 100% of
level-1 criteria but only 50% of level-2 criteria scores level 1, not level 2,
even if level-2 criteria represent the minority. The gate requires ≥80% of
all applicable criteria at level 1 and below — levels are additive.
Related Skills and Commands
/project-metrics — the command that runs the readiness engine. All
readiness flags are arguments to this command./onboard-project Phase 8e — installs the universal code-quality baselines
(linter/formatter/editorconfig, pre-commit, type-check config, CONTRIBUTING.md)
from canonical assets; the fastest path to the L1–L3 Style/Code-Quality/Docs
mechanical criteria (c.style.*, c.codequality.typecheck_config, c.docs.contributing).python-development / typescript-development — own the canonical
linter/formatter/type-check baseline assets Phase 8e installs.doc-management — improves README quality and contributing guide
presence (affects c.docs.readme, c.docs.contributing, c.docs.readme_quality).observability — improves logging config and health-check presence, and
carries the Service Observability Baseline + the service-vs-library decision
(affects c.observability.logging_config, c.observability.healthcheck).test-engineer / testing-strategy / test-coverage — improve
behavior-focused test quality and make coverage visible (affects
c.testing.test_quality).cicd — improves CI pipeline and test execution, and wires type-checking
into CI (affects c.build.ci_pipeline, c.testing.ci_runs_tests).architectural-fitness-functions — improves type-checker and complexity
gate presence (affects c.codequality.typecheck_config,
c.codequality.complexity_gate).
