micronaut-quality-gates

Files (1)

• SKILL.md

SKILL.md (first lines)

# Micronaut Quality Gates

This skill defines the minimum bar each role must protect before its handoff step or execution-policy review stage can resolve as `approved`.

## Shared Stage Contract

Before any role resolves its stage:

- the role has read the current execution stage, current stage participant, latest linked GitHub context, and any linked approval
- the role has read `executionState.returnAssignee` when the issue is in active review
- the role has produced one durable stage artifact that explains the decision
- QA does not collapse intake and verification into one artifact; use separate durable issue documents such as `qa-intake` and `qa-verification`
- when the role is the active execution-stage participant, it resolves `approved` with `status: done` plus a decision comment and resolves `changes_requested` with a non-`done` status, preferably `in_progress`, so Paperclip routes automatically through `currentParticipant` and `returnAssignee`
- manual `TODO` assignment is the mechanism for every pre-delivery handoff (intake, Security pre-triage, Architect planning, implementation) and for publication; execution-policy stages exist only in the review chain the delivery owner creates when it submits the immutable SHA
- for synced GitHub delivery work, `approved` advances the issue to the next stage or PR follow-through; it is not permission to mark the Paperclip item `DONE`
- if a human governance decision is required, the role creates or updates a real Paperclip approval instead of treating a comment as approval
- if non-governance board or user input is required, the role uses an issue-thread interaction instead of a loose comment: `suggest_tasks` for selectable task lists, `ask_user_questions` for bounded questions, and `request_confirmation` for explicit plan or proposal confirmation
- the role advances or assigns the issue correctly and lets Paperclip routing wake the next participant; an agent-authenticated caller must not attempt to invoke another agent's heartbeat
- the role re-opens the issue and verifies the execution state matches the intended outcome before finishing

## Intake Gate

Before an actionable issue moves out of QA intake:

- a human has moved the synced issue from `BACKLOG` to `TODO`
- deduplication has been performed against open and closed GitHub issues in the same synced repository, and closed GitHub issues were evaluated by why they were closed, including closure disposition, duplicate links, closure comments, and already-implemented evidence, before QA forms the triage opinion
- the issue has the correct `type:` label, unless it is on a documented immediate-closure path
- QA has identified the repository's actual current default branch, the latest stable non-pre-release release, the next release implied by that branch, the SemVer delta from latest stable to next release, and the target branch decision; GitHub prereleases such as milestones (`-M<number>`) and release candidates (`-RC<number>`) do not count as the default branch having already shipped
- QA has decided whether the issue's SemVer impact fits the default branch's major/minor/patch release target and recorded any mismatch instead of inventing a non-default target branch; the PR target branch is not automatically the default branch, and an alternative target requires a maintainer, Architect-approved plan, or linked human approval
- QA has chosen the best-fit Micronaut organization project set for the eventual PR, or recorded that no matching project exists yet or tooling cannot apply it; Micronaut organization projects represent Micronaut Platform BOM release boards, not repository module or project versions. When a GA target has both matching milestone or release candidate boards and a GA release board open, the set includes all matching projects, such as both `5.0.0-M3` and `5.0.0 Release`
- any linked contributor PR has been evaluated for whether it should stay on the normal gates or be replaced by a separate maintainer-owned PR while staying open
- confident questions use the documented `type: question` plus `closed: question` direct-answer path
- clarification requests use the documented `status: awaiting feedback` path and may close after 30 days with `closed: question`
- bugs have a reproducer or a precise non-reproducer record
- direct QA triage closures that are not duplicates use GitHub's native `Close as not planned` reason instead of `Close as completed`
- unreproduced bugs that now point toward closure use the documented `closed: cannot reproduce` path instead of falling back to `changes_requested`
- duplicates use the documented `closed: duplicate` path with GitHub's native `Close as duplicate` reason and a link to the superseding GitHub issue
- already-implemented closures cite the exact version, PR, release, or documentation evidence and use QA's direct closure path
- closure comments contain detailed evidence, are not short generic close notes, and cite the exact facts that justify the closure
- the authoritative `qa-intake` booleans and ordered `stageSequence` encode the correct downstream route; issue type is only a surface label and does not select the route
- required all-of review gates are modeled as separate sequential stages in the review chain instead of one multi-participant stage; QA does not create that policy at intake
- if the issue needs a public answer or closure outside QA's direct GitHub authority, the board-approval path is explicit
- if intake needs bounded maintainer input rather than open-ended discussion, QA uses `ask_user_questions` with clear options and a continuation policy so the issue resumes when answered

## Planning Gate

Before implementation starts, the plan artifact must state:

- target repository and branch
- target release or release line
- the QA-derived release-targeting facts still hold, or any revision is explicitly justified
- problem statement and expected outcome
- acceptance criteria
- compatibility and migration impact
- test strategy
- documentation impact
- whether the change must remain non-breaking
- the plan matches the recorded `planningDepth`: a `lightweight` plan (routine localized bugs, compatible dependency upgrades, `training-route` and skill-sync children) may state the items above briefly as a reproduction summary, root-cause hypothesis, exact change scope, and tests to add; a `full` plan expands every item
- the QA-selected Micronaut organization project set, or the recorded ambiguity or tooling gap that explains why the live PR may not carry it yet
- explicit human approval when the change needs one
- when the plan needs confirmation but not governance approval, a `request_confirmation` interaction targets the latest `plan` document revision with a stable idempotency key and a continuation policy

If any required items above are missing, planning does not resolve as `approved`. The QA-selected organization-project set or ambiguity note should be carried forward, but missing live linkage alone does not block planning approval.

## Implementation Gate

Before code or docs leave implementation:

- the change is the smallest safe diff
- the change follows the approved plan or makes the QA reproducer pass
- tests cover the changed behavior, or the implementation artifact explains why that is impossible
- docs impact is addressed or explicitly ruled out
- branch and release-line choices are correct
- git work used the local git CLI
- hidden cleanup has not been bundled without approval
- the next QA stage can verify the work without reconstructing intent from scratch
- repository-changing work has one immutable full commit SHA and a `publication-manifest` containing the proposed base, title, body, linkage, labels, projects, reviewers, and PR-visible assets; no agent-owned PR is created before internal approval

## QA Gate

The QA Engineer verifies:

- intake decisions are correct and the downstream stage sequence is correct
- release-targeting facts, SemVer delta, approved target branch, allowed change class, and organization-project selection from QA intake are correct, including any GA-plus-prerelease project set
- the implementation still matches the approved plan or the reproducer
- when a linked contributor PR exists, QA has correctly decided whether it remains the implementation vehicle or should be replaced
- the original issue or PR concern is actually resolved
- tests and documentation support the claimed change
- visual, browser-rendered, or file-based evidence has been captured locally and named in `publication-manifest`; the publication owner must upload and verify the same evidence after approval without changing the reviewed commit
- no important acceptance criteria were silently dropped
- public answers and closure paths use the correct GitHub labels when applicable, use GitHub's native `Close as not planned` or `Close as duplicate` reason as appropriate, include detailed evidence rather than short generic close notes, treat evidence-backed already-implemented issues as part of QA's direct closure authority, and only require Paperclip board approval when the path is outside QA's direct GitHub authority

Work that passes QA intake is handed `TODO` to the next handoff-chain entry with a clear next-action comment, or, after an allowed direct GitHub answer or closure, is parked `in_review` on the human owner for GitHub Sync to transition (`CANCELLED` for not-planned or duplicate closures). Work that passes QA verification is approved inside the execution-policy stage, and QA lets Paperclip move the issue to the next `in_review` participant automatically. Work that needs a board-approved public answer or closure resolves as `request_board_approval`. Work that fails QA resolves as `changes_requested`.

## Security Gates

Security participates only when the authoritative ordered `qa-intake.stageSequence` includes it. In either Security stage, the Security Engineer checks for:

- source-code exploit paths and attack-surface changes
- authentication, authorization, secret handling, serialization, filesystem, process, and network risk
- dependency, build, CI/CD, release, and supply-chain risk
- insecure defaults or examples that would steer users into unsafe deployment or configuration choices
- whether blocking findings are concrete enough to justify `changes_requested`

Approved pre-triage hands the issue `TODO` only to the next entry in the authoritative ordered `qa-intake.stageSequence`, which is Architect for Micronaut Engineer-owned work and for Technical Writer-owned work with `planningRequired: true`, and otherwise Technical Writer. Pre-triage does not skip Architect, implementation, QA verification, or final Security review. Approved final Security review advances the execution policy to Code Reviewer. A rejected pre-triage returns `TODO` to QA naming the gap; a rejected final review returns through the execution policy as `changes_requested`.

## Code Review Gate

The Code Reviewer checks for:

- correctness beyond the happy path
- maintainability and readability
- performance and regression risk
- API, config, and developer-experience quality
- missing or weak tests
- for unpublished agent-owned work, exact-SHA diff quality and the complete `publication-manifest`; for an already-open surviving PR, live linkage, label, reviewers, and project associations
- if `approved` is chosen for unpublished work, every applicable upstream gate names the same immutable SHA and the implementation owner is recorded for publication-only follow-through
- if a human maintainer changed, rescheduled, or retargeted the PR organization project after PR creation, that maintainer project change is authoritative and must remain; code review must not restore, reapply, re-add, or reset the original QA-selected organization project set over the maintainer's choice
- once the approved target branch is identified, the work branch is fetched and updated from the target branch before starting work, editing, committing, opening, creating, or updating a PR; target branch rebase or merge conflicts are recorded as blockers instead of publishing conflicting PRs

From alvarosanchez/micronaut-agent-company, MIT.

More from alvarosanchez/micronaut-agent-company