feat(readiness): Maturity "report card" output with tiered levels and next-step guidance
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1.1k
- Forks
- 94
- Avg merge
- 8d 3h
- Merged PRs (30d)
- 7
Description
Problem
The current readiness report outputs pass/fail criteria grouped by pillar (repo health, AI tooling). This is useful for engineers, but not actionable enough for customer-facing engagements. Field teams (FDEs, CSAs) need a higher-level view that maps a repo's current state to a named maturity tier with clear guidance on what to do next.
In the AgentRC futures discussion with Barton Mathis, he described a ring-based maturity model for AI adoption. AgentRC's readiness scoring already captures the underlying signals — what's missing is a presentation layer that synthesizes those signals into a maturity narrative.
Proposal
1. Define maturity tiers
Map readiness scores to named tiers (names TBD, example below):
| Tier | Score range | Description |
|---|---|---|
| Foundational | 0–39 | Basic repo hygiene missing; not ready for AI tooling |
| Structured | 40–59 | Good repo health; AI tooling setup is minimal |
| Optimized | 60–79 | AI instructions and tooling configured; some gaps |
| Advanced | 80–100 | Comprehensive AI-readiness; instructions, MCP, agents, CI integration |
Thresholds should be configurable via policy or config.
2. Add "next steps" to report output
For each tier below Advanced, surface the top 3 actions that would move the repo to the next tier — derived from the highest-impact failing criteria (using existing impact and effort metadata).
Example output:
Maturity: Structured (score: 52/100)
To reach Optimized:
1. Add custom instructions (.github/copilot-instructions.md) — high impact, low effort
2. Configure MCP servers for your toolchain — high impact, medium effort
3. Add a lockfile for dependency pinning — medium impact, low effort
3. Surfaces
- CLI:
agentrc readiness --report-card(or integrate into default output) - CLI HTML report: Add a hero banner with tier name + score + next steps
- Webapp: Replace or augment the current score display with tier visualization
- JSON output: Include
maturity.tier,maturity.score,maturity.nextSteps[]in the machine-readable output
Context
- Discussed in "AgentRC: Quick Chat on Futures" meeting
- Related: existing readiness pillar system in
packages/core/src/services/readiness/
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the existing readiness pillar system in packages/core/src/services/readiness/ and trace how readiness scores reach the CLI, HTML report, webapp, and JSON output. Define the maturity tiers, configurable thresholds, and next-step selection across those surfaces. Done means the report card is represented consistently in each requested output, including tier, score, and next steps.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli, tooling, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100