Skip to content

Software Project Maturity Assessment

Spec version: 0.3.0

Read it on the web: https://dzyanis.github.io/software-project-maturity-assessment/

A structured framework for auditing the maturity of a software project. The team rates how important each engineering practice is for this project, then measures its current state on a common 0–4 scale. The weighted gap becomes a prioritized improvement roadmap. Incomplete ratings remain visible and make scores provisional. The audit can be conducted manually by an assessor, or an LLM agent can take the assessor's role: it interviews the team and produces the report.

Quick start

With a coding agent (Claude Code, Cursor, etc.):

git clone https://github.com/dzyanis/software-project-maturity-assessment.git
cd software-project-maturity-assessment
claude "Read AGENT.md and run the assessment interview with me"

To assess a different repository, run the same claude command from that repository and point it at this checkout's AGENT.md.

With a web chat (claude.ai, ChatGPT, etc.): attach service-audit-full.md, the whole assessment in one file, to a conversation and say "Run this assessment with me." To download it directly:

curl -O https://raw.githubusercontent.com/dzyanis/software-project-maturity-assessment/main/service-audit-full.md

The agent interviews your team one question at a time and produces a report you can keep next to your repo and compare against future runs.

Philosophy

Engineering leaders and the people writing the code rarely have a shared way to talk about the state of a project. One side asks about dates and risk, the other answers in tech debt and missing tests, and neither has evidence the other can act on. This assessment is meant to be that shared interface: one artifact both sides can point at.

That works because the team sets the importance of each practice before measuring its current state. The importance weight reflects local priorities; the score reference remains level 4 for every item.

For engineers, the priorities are theirs. A lower gap priority on something the team deliberately deprioritized is a decision, not a failure. What remains is a structured case for work they already know is needed, plus the blind spots a checklist surfaces that nobody thought to ask about. It also forces the team to agree on what "good" means here, instead of everyone carrying a private standard.

For engineering leaders, it is a read on the project that does not require sitting in every standup or pulling it out of people one by one. Re-run it with the same spec version, scope, selected items, and importance weights to make progress visible rather than inferred.

This is a self-assessment, not a grade. It weights maturity gaps by the importance the team assigns to each practice, using the same state-4 reference for every item.

How to use it

  1. Read ASSESSMENT.md: the index, scoring scales, and links to the seven category files in assessment/.
  2. Run the assessment:
    • Manually: walk the categories with your team and fill in templates/report.md.
    • With an LLM: give your AI assistant AGENT.md and the assessment/ files; it interviews the team one question at a time and produces the report. To pause and resume later, save the current answers in the interview checkpoint.
  3. Re-run it periodically (e.g. every 6–12 months). Keep the spec version, scope, selected items, and importance weights the same when comparing aggregate scores.

For a 30–60 minute first pass or focused re-check, use the lite assessment profile. It samples 15 items and is not a substitute for a full assessment.

To calculate standard category scores, supplemental custom scores, and gap priorities from confirmed answers, use the score calculator. After changing item headings in assessment/, regenerate it with python3 scripts/build-calculator.py.

The optional future guided interview interface is scoped in docs/guided-interview-ui-scope.md; it has not been built.

The pilot method and current prompt count explain how to measure real interview time and rating differences.

See the fictional sample report for a full run, including rating rationale, calculations, an N/A item, and an unknown answer.

Versioning

The spec follows SemVer: MAJOR versions change, remove, or renumber items in ways that break report comparability; MINOR versions add items, questions, or additive scoring/report behavior; PATCH versions fix wording without changing meaning. See CHANGELOG.md. Reports record the spec version they were produced with.

After changing any assessment content, regenerate the single-file bundle with ./scripts/build-bundle.sh.

How this assessment covers each framework is documented point-by-point in coverage/.

Planned mappings are tracked in the area:coverage issues.

Website development

The documentation website is built from the existing Markdown without changing the source files. From the repository root, create an isolated environment and install the fully pinned build toolchain:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-docs.txt
export PATH="$PWD/.venv/bin:$PATH"

Build the site into site/, run all verification checks, or preview it locally:

./scripts/build-site.sh
./scripts/test-site.sh
./scripts/build-site.sh --stage-only && mkdocs serve

The preview is available at http://127.0.0.1:8000/. Run the staging command again after editing source Markdown. To update the dependency lock after changing requirements-docs.in:

.venv/bin/python -m pip install "pip==25.3" "pip-tools==7.5.2"
.venv/bin/python -m piptools compile --strip-extras \
  --output-file requirements-docs.txt requirements-docs.in

Website maintainers: see the search engine registration guide for Google Search Console and Bing Webmaster Tools setup.

Roadmap

Planned work lives in GitHub issues, grouped by area label and by release milestone:

Issues labelled spec-change alter the assessment items themselves and ship as a MINOR or MAJOR release. See CONTRIBUTING.md for how to propose one.

License

Creative Commons Attribution 4.0 International (CC BY 4.0). See LICENSE.