How to use this plugin

This plugin assesses a UK public sector service against the Service Standard at Discovery, Alpha, Beta, and Live. The panel is four disciplines: lead, user research, design, and technical. A fifth skill writes the report.

Use it on a pack of evidence for one service at one phase. The blank files, the fictional example, and the report downloader ship in this skill as scripts. Run the scripts. They write the folders into the current project. Copying a folder from the gds-assessor project, or from any other project, leaves the files outside this project.

When someone asks how to use this plugin

Give these three steps, in this order. Do not stop after the first.

1. Try the example. Run create-example.py, then assess docs/examples/apply-for-a-blue-badge/alpha.
2. Create the past-reports library. Run scrape_gds_reports.py from their project root. It writes docs/past-assessments/. Until that exists, an assessment has no published reports to cite.
3. Create a blank evidence kit for their own service. Run create-evidence-kit.py. The default folder is docs/evidence-kit.

The sections below are the commands and the detail for those three steps.

Install

From a project that should run assessments:

tessl install service-factory/gds-assessment-plugin

The registry package contains the skills, the rules, and this guide. It does not contain the published GOV.UK assessment reports. A project has no past assessments until it generates them. The panel can still score a service. It then has no published precedent to cite.

Create the evidence kit

The blank templates are evidence-kit/ in this skill directory. create-evidence-kit.py sits next to this file. When someone asks for the kit, run that script and write into the folder they name. Use docs/evidence-kit when they do not name one.

From the skill directory:

python3 create-evidence-kit.py /path/to/project/docs/evidence-kit

One phase only:

python3 create-evidence-kit.py /path/to/project/docs/evidence-kit --phase alpha

The script leaves files that are already there. Pass --force only when the blanks should replace them.

Try the example

The fictional Alpha pack is stored in this skill. It is not already in the user's project. create-example.py sits next to this file. When someone wants to see the plugin work, run that script first. It writes Northshire Council, Apply for a Blue Badge, into the project. This is not the real Blue Badge service.

From the skill directory, with the path to their project:

python3 create-example.py /path/to/project/docs/examples/apply-for-a-blue-badge

If they do not name a folder, run it from their project root. The default destination is docs/examples/apply-for-a-blue-badge. The script leaves files that are already there. Pass --force only when the example should replace them.

Then assess the alpha folder the script created. Start with assessment-panel-orchestrator. The first message is a question in the chat. A point that would be Not Met is always a question. Ask one question, then wait for the reply. Keep asking until the reply names a record, the reply is only anecdotal, or the team says to skip. A story with no record leaves the evidence outstanding. Store the full exchange in panel/dialogue.md beside the phase folder after the question is closed. Do not score the README beside the alpha folder. That file says what the run should find, and what the team would do to pass.

Run an Alpha assessment of docs/examples/apply-for-a-blue-badge/alpha. Use assessment-panel-orchestrator, then the four Alpha assessor skills, then assessment-report-synthesis. Cite past assessments through the gds-assessment-reports tools. Do not read docs/examples/apply-for-a-blue-badge/README.md while scoring.

What the team prepares

Fill the phase the service is in. Do not fill a later phase early. Production code in Discovery, or a production environment treated as the beta platform in Alpha, fails that phase.

coverage.md in the created kit is the same map, plus the red lines each pack is there to catch.

Where a template asks for something the team does not have, they write Not held and the owner. An empty heading is missing evidence. The panel can only score what is in the pack.

panel/dialogue.md sits beside the phase folders. It stores the dialogue after it has happened in the chat. The panel asks one question at a time and waits. Later assessments read that file with the other evidence.

Each phase folder has its own README.md. Read that before filling the files.

Discovery

The decision at the end can be to proceed, to join another service, or to stop.

Do not add prototypes, a schema, an accessibility audit, performance figures, or a runbook.

Alpha

Prototypes and spikes are meant to be thrown away. Keep the Discovery journey and point at it. Do not redraw it as the future service.

Point 5 is not a fail at Alpha. Record the assisted-digital sketch in design/prototypes.md. Do not commission a WCAG audit. Do not describe a production environment as the beta platform.

Beta

The private beta build is the evidence. The panel scores all 14 points. Assistive-technology sessions and an independent WCAG 2.2 AA audit are both required. The audit does not replace the sessions.

The disaster-recovery result is a Live requirement. Beta records the planned date.

Live

Show that the service is being run and changed. Do not resubmit the beta pack. Points 2, 11, 12, and 13 stay on the previous evidence unless 00-what-changed.md says the purpose, journey, stack, or contract has changed.

Run the assessment

Tell the agent the phase and the path to the pack. For a Beta of a pack you copied to docs/evidence/receipt-of-waste/:

Run a Beta assessment of docs/evidence/receipt-of-waste. Use assessment-panel-orchestrator, then the four Beta assessor skills, then assessment-report-synthesis. Cite past assessments through the gds-assessment-reports tools.

The agent should do this, and not import another phase's bar:

1. Read rules/gds-service-standard.md, rules/phase-expectations.md, and rules/past-assessments.md.
2. Run assessment-panel-orchestrator. The first message is a question in the chat. Ask one question at a time and wait for the reply. A point that would be Not Met is always a question. Keep asking until the reply names a record, the reply is only anecdotal, or the team says to skip. Store the full exchange in panel/dialogue.md after the question is closed.
3. When every question is closed, run the four skills for that phase. Each skill scores only the points in its SKILL.md and works through its lines-of-questioning.md. The red lines for the phase are in context/rubrics/.
4. Pass the four JSON outputs, the service name, and the phase to skills/assessment-report-synthesis.
5. The report follows skills/assessment-report-synthesis/report-template.md. The synthesis skill writes it with skills/plain-english and edits it with skills/no-ai-slop. A story with no record, or a skipped question, leaves that point Not Met when the pack still lacks the record.

Who scores which points

Beta is the first phase that scores all 14 points. The technical skill also records point 5 when the independent audit is missing. At Live, points 2, 11, 12, and 13 are Not reassessed unless the service, the stack, or the contract has changed.

How a report is decided

Each point is Met, Not Met, Not assessed, or Not reassessed.

Not assessed means the point is outside this phase. Not reassessed means Live left an unchanged point on its previous evidence. Neither fails the service.

The overall result is Not Met if any in-scope point is Not Met, or if a red line fired. A recommendation does not change a Met into a Not Met. There is no "met with conditions".

The failures that decide most packs:

• Discovery. Production code, a signed-off interface, or a decision that Alpha will happen.
• Alpha. A production environment described as the beta platform. One design presented as the beta interface. Concept tests only with confident users, colleagues, or stakeholders. A log in which every experiment succeeded.
• Beta. No participant used a screen reader, a magnifier, or speech input. No independent WCAG 2.2 AA audit. No working end-to-end journey. No staffed alternative for people who cannot use the digital service. Real personal data without a privacy assessment, a pipeline scan, and a tested rollback. A homegrown identity, payment, notification, or form service with no tested decision against the GOV.UK equivalent.
• Live. An incident runbook that has not been used or rehearsed. No disaster-recovery drill result. No exercised exit. The department cannot change the service without the supplier. Research or published performance stopped at launch. A known drop-off with no owner.

Past assessments

The published plugin does not include other services' assessment reports. A new project gets none until someone generates the library. Without that library, the assessment still runs, and the report cites no published precedent.

scrape_gds_reports.py sits next to this file. This is step 2 when someone asks how to use the plugin. Run it from their project root so the files land in that project. Install the two libraries first:

pip install requests beautifulsoup4
python3 /path/to/gds-assessment-how-to/scrape_gds_reports.py

The script reads the GOV.UK search index and writes one Markdown file per published service standard report into docs/past-assessments/reports/. It then writes a catalogue into docs/past-assessments/catalogue/. A full run takes a few minutes. It does not need to be run again before every assessment.

To rebuild the catalogue without downloading again:

python3 /path/to/gds-assessment-how-to/build_past_assessment_catalogue.py docs/past-assessments

The gds-assessment-reports server is reports_mcp_server.py next to this file. It reads docs/past-assessments in the project. Restart that server after the first download. During an assessment it returns at most eight reports, and it does not call GOV.UK.

In this plugin checkout, the same scripts keep using context/ when that library is already there.