Maturity audit

Know where the codebase stands

One command scores a codebase on eleven engineering dimensions, stops for your review, and only then writes the documents for your executive, business and technical readers. It is a separate workflow from the six phases, and it never changes code.

Run an audit Read the skills

Two questions, kept apart

Can you keep running this as-is?

The production-readiness gate. It is the lowest level among the critical dimensions: security, testing and reliability.

How much is it holding you back?

Modernization pressure and a relative cost-of-ownership signature, driven by the legacy cluster. Adaptability weighs the most.

Use it for a production readiness review, a tech debt assessment, a legacy modernization decision, or a plain "is this ready to ship or scale" check. The audit is static by default: it reads the code and does not run it. Every level cites the file paths that justify it.

Run it

/speccen:audit

Not installed yet? Install speccen first.

The application name comes from the repository. To name it yourself, pass it as an argument:

/speccen:audit 'my-app'

You never pick an output path. Each run gets a folder in .speccen/audits/. The first run of a codebase is the baseline, YYYY-MM-DD.baseline. Every later run is compared with the previous run and the baseline. To resume an audit, run the command again and pick the run from the list.

Four stages, one gate

  1. Recon

    Scaffolds the run and orients on the codebase. It records a system profile: composition, tiers, topology, coupling and data architecture. The profile calibrates the rubrics. It is not scored.

  2. Scoring

    Each dimension is scored 0 to 4 against its rubric, with evidence. Every dimension gets a result.json, a full detail.md and a bounded summary.md.

  3. Review

    A script computes the scorecard and the trend against earlier runs. The audit then stops with the status AWAITING ARCHITECT REVIEW. Correct any level you disagree with. The scorecard is recomputed, never hand-edited. Say "generate the documents" to release the next stage.

    Nothing is written for your readers before this go

  4. Synthesis

    Writes three audience documents from the reviewed scores: executive, business and technical.

Eleven dimensions, five levels

  • Security
  • Testing
  • Reliability
  • Performance and scalability
  • Adaptability
  • CI/CD and deployment
  • Observability
  • Dependency health
  • Code quality
  • Architecture
  • Documentation

Outlined in rose: the critical dimensions behind the readiness gate.

  • 0Absent. Not present at all.
  • 1Initial. Ad hoc, inconsistent, undocumented.
  • 2Emerging. A basic version exists, with real gaps.
  • 3Established. Consistent, documented, covers the common cases.
  • 4Optimized. Comprehensive, automated, monitored, improved.

A dimension sits at the highest level whose criteria are substantially met. The criteria it misses become findings and recommendations.

What you get

.speccen/audits/<id>/
  index.md        regenerable listing
  STATE.md        where the run is now
  log.md          prompts and stage timeline
  recon.md        the orientation pass
  run.json        run stamp: date, commit, rubric hash
  scorecard.md    the four signals, machine-written
  summary.json    the same aggregate, machine-readable
  trend.md        against the previous run and the baseline
  trend-notes.md  evidence for each level change (not on the baseline)
  dimensions/     one folder per dimension
    <name>/       result.json, detail.md, summary.md
  docs/           doc-executive.md, doc-business.md, doc-technical.md

The scorecard carries four signals: the weighted average, the readiness gate, modernization pressure and the cost-of-ownership signature. A script computes them. The AI never hand-computes a score signal.

A scoreboard of all runs sits in .speccen/audits/history.md, with history.json beside it. Keep the audits in git: the trend only means something when earlier runs are there.