Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

feat(readiness): Maturity "report card" output with tiered levels and next-step guidance

Open
  • Is something wrong?
#127 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
typescript
Domain
cli, tooling, web-dev

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.

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/
Dominant language
TypeScript
Stars
1.1k
Forks
94
Avg merge
1d 20h
Merged PRs (30d)
37

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/agentrc

All issues in microsoft/agentrc

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.