micronaut-repo-operations

name: micronaut-repo-operations description: Compact router for Micronaut repository workflow, delivery gates, and on-demand operating references.

Micronaut Repo Operations

Use this skill whenever you act on synced GitHub issues or pull requests for this company. This file is the always-loaded router. It preserves the delivery rules and points to detailed on-demand references under skills/micronaut-repo-operations/references/ when a case needs the full procedure.

Load The Right Reference

• Normal stage routing, Paperclip APIs, issue-thread interactions, planning confirmation, productivity reviews, environments, checkout/liveness recovery, parent/blocked issue modeling, and final state checks: references/workflow-control-plane.md.
• QA intake, issue type routing, closure dispositions, documentation policy, release targeting, Micronaut organization-project selection, approval boundaries, and imported issues with existing PRs: references/intake-routing-release.md.
• GitHub Sync tool names, GITHUB_TOKEN vs plugin-tool behavior, maintainer-visible footer policy, PR-to-Paperclip linking, KPI attribution, link immutability, monitor boundaries, and PR-visible assets: references/github-sync-tools.md.
• Recurring internal routines, project-specific routine subtasks, no-diff/no-PR decisions, Product Manager discovery, Technical Writer guide routines, CEO package/core or managed-repo PR scoping, and .company-runtime/ overlays: references/internal-routines-overlays.md.
• PR creation/readiness rules, selected organization projects, reviewer requests, post-PR follow-through, maintainer-wait state, review-thread settlement, and maintainer-friendly evidence: references/pr-delivery-evidence.md.

If you are about to mutate issue state, publish to GitHub, open/update a PR, close an issue, create routine follow-up work, or handle an uncommon branch/release/approval case, load the matching reference first.

Non-Negotiable Workflow Rules

• Work only inside repositories configured in this company's GitHub sync plugin. Use plugin configuration, optional .company-runtime/ overlays, and repo-local docs or AGENTS.md as supplemental facts, not as proof of repository membership.
• Do not assume Micronaut repositories share branch strategy, release process, docs layout, or test commands. Read the local repository facts before planning or coding.
• Synced GitHub issues and PRs are the normal delivery work items. Do not invent internal starter tasks for routine queue work.
• Paperclip execution policies own review and approval routing. executionState.currentParticipant is the only actor allowed to resolve the active stage; executionState.returnAssignee receives the work back on changes_requested; active review work remains in in_review until the final stage or documented follow-through route.
• Approve an active stage with PATCH /api/issues/{issueId} and status: done plus a decision comment. Request changes with a non-done status, preferably in_progress, plus a precise decision comment so Paperclip routes through returnAssignee.
• A stage artifact is always required: plan, reproducer, QA record, security review, code-review summary, docs artifact, rollout note, or other durable issue/PR document. QA intake and QA verification use separate issue documents named qa-intake and qa-verification.
• Manual TODO assignment is only for non-policy owner changes such as intake-to-planning, planning-to-implementation, or post-PR follow-through. In active review or approval stages, let Paperclip route through currentParticipant and returnAssignee; do not use @ mentions as the routing mechanism.
• If the next stage or owner should run immediately, invoke the appropriate heartbeat only after the stage or assignment has already advanced correctly. Multi-participant stages do not imply unanimous sign-off; model required all-of approval as separate sequential stages.
• For synced GitHub delivery work, approved advances the execution policy or documented follow-through route; it is not permission to mark the Paperclip item DONE. GitHub Sync closes/dones the Paperclip item after merge or after an approved GitHub closure path lands.
• Board approval always means a real linked Paperclip approval, not a free-form comment. Approval requests for maintainer-visible GitHub comments or action payloads with commentBody must put the exact proposed comment body in recommendedAction. After creating or following up on a linked approval, verify GET /api/approvals/{approvalId}/issues instead of relying only on issue.linkedApprovalIds.
• Paperclip issue-thread interactions are for non-governance user input: suggest_tasks, ask_user_questions, and request_confirmation. For plan confirmation, create a request_confirmation interaction against the latest plan issue document revision with an idempotency key such as confirmation:{issueId}:plan:{revisionId} and a continuation policy such as wake_assignee_on_accept.
• Paperclip is single-assignee by design. Linked approvals are governance records, not a second assignee. todo is dispatch state, in_progress is active work, blocked is an external wait, and in_review means the next move belongs to a reviewer or approver.
• For agent-owned in_progress work, inspect checkout, execution run, liveness, continuation-attempt, watchdog, and continuation-summary context before creating duplicate recovery work. Treat stranded or liveness-blocked work as an operational repair/escalation path.
• Paperclip inbox work includes in_review; use GET /api/agents/me/inbox-lite or the company issue fallback before assuming there is no review-stage work.
• Paperclip environments such as local, SSH, or sandbox are live deployment/operator-owned configuration; if sandbox execution is required, the operator installs @paperclipai/plugin-e2b or another environment-driver provider rather than this package adding provider settings.
• Project workspace services and execution workspace services do not auto-start from heartbeats. If a repository task needs a service that is not already running, record the missing runtime setup instead of assuming the heartbeat started it.
• Use parentId for structure, checklist display, and rollup context; use blockParentUntilDone when a known child should hold a parent; use blockedByIssueIds for dependency semantics and automatic wakeup when blockers clear.
• Use standard work mode for normal delivery issues, routine project subtasks, Product Manager feature proposals, and PR follow-through. Planning mode is for planning-only issues; after an accepted plan, create standard-mode child implementation issues through POST /api/issues/{issueId}/accepted-plan-decompositions.
• Paperclip may create productivity review issues with type issue_productivity_review for no-comment, long-active, or high-churn source work. Treat these as queue-health work: inspect the source issue and run evidence, record a manager decision, and fix the source route or review state before forcing resume: true.

Delivery Route Summary

• type: bug: QA intake and reproducer first, then Micronaut Engineer, QA verification, Security Engineer, and Code Reviewer. Unreproduced bugs may use QA's closed: cannot reproduce path with detailed evidence.
• type: docs: QA intake, Technical Writer, QA verification, Security Engineer, and Code Reviewer.
• type: improvement, type: enhancement, type: breaking, and type: dependency-upgrade: QA intake, Architect, implementation or docs work, QA verification, Security Engineer, and Code Reviewer.
• type: question, clarification waits, unreproducible closures, duplicate closures, and already-implemented closures can be resolved by QA intake only when the direct-closure policy and evidence requirements are met.
• Imported issues with existing external-contributor PRs stay in the normal gates if QA decides the PR is salvageable. If the contributor PR needs substantial replacement, leave that contributor PR open, document why it is not the implementation vehicle, and continue toward a separate maintainer-owned PR.
• Direct QA closure comments must be detailed, evidence-rich, and not short generic close notes. Closure comments must cite exact facts that justify the closure, such as non-reproducer steps, timeout date, duplicate overlap and superseding GitHub issue, or the exact version, PR, release, or documentation proving already-implemented.
• Direct non-duplicate closures use GitHub's native Close as not planned rather than Close as completed. Duplicate closures use closed: duplicate, GitHub's native Close as duplicate, and a link to the superseding GitHub issue.
• Deduplication is repository-scoped: search open and closed GitHub issues in the same synced repository, inspect why closed issues were closed, including closure disposition, duplicate links, closure comments, and already-implemented evidence, then decide whether they supersede, block, or leave the work actionable.

Release, Docs, And Project Selection Rules

• QA intake owns release targeting, target-branch selection, and Micronaut organization-project selection. Later stages consume and verify those facts instead of reinventing them from scratch.
• Trust the repository's actual current default branch as the next-release signal, but do not treat the PR target branch as automatically the default branch.
• Determine the next release from the default branch plus the latest stable non-pre-release GitHub release, then compute the SemVer delta from latest stable to next release. GitHub prereleases, including milestones and release candidates, do not count as the default branch having already shipped.
• Do not invent or create another target branch during triage just to fit SemVer. Alternative targets require a maintainer request, Architect-approved plan, or linked human approval that names the branch and release-policy reason.
• If the current default branch has never been released, it may accept type: bug, type: improvement, type: enhancement, docs, CI, or build-only changes when the SemVer delta is minor or major; a new major line can accept type: breaking with required approvals.
• If the current default branch has already been released and the next release is only a patch, it may accept type: bug, type: improvement, docs, CI, or build-only changes; type: enhancement and type: breaking need an explicit approved alternative.
• If the latest stable release is 1.2.3 and the default branch implies 2.0.0, the delta is major; if it implies 1.3.0, the delta is minor; if it implies 1.2.4, the delta is patch. Target branch eligibility follows that delta.
• Example: if the latest stable release is 1.2.3, the next release is 2.0.0, and the SemVer delta is major, the default branch may accept type: bug, type: improvement, type: enhancement, docs, CI, build-only changes, and type: breaking with normal Architect and human approvals.
• Example: if the latest stable release is 1.2.3, the next release is 1.2.4, and the SemVer delta is patch, the branch may accept type: bug, type: improvement, docs, CI, and build-only changes; type: enhancement and type: breaking do not fit and cannot target that patch branch without an approved exception.
• Example: if the latest stable release is 1.2.3, the next release is 1.3.0, and the SemVer delta is minor, the branch may accept type: bug, type: improvement, type: enhancement, docs, CI, and build-only changes; type: breaking does not fit and cannot target that minor branch without an approved exception.
• type: dependency-upgrade follows the actual compatibility impact of the resulting repository release, not the label alone. type: breaking requires explicit Architect approval and, when necessary, linked human approval.
• Micronaut organization projects under https://github.com/orgs/micronaut-projects/projects are Micronaut Platform BOM release boards, not repository module versions. Select the best-fit open, public project set (is:open is:public); for a GA target with both milestone/RC and GA boards open, select all matching projects such as 5.0.0-M3 and 5.0.0 Release.
• QA should choose the best-fit Micronaut organization project during intake; preserve that project set and record ambiguity rather than blocking. If the target branch or release target changes after QA intake, re-check the organization-project set. If no matching project exists or tooling cannot link it, record that gap and continue because missing linkage due to no matching project or tooling gaps does not by itself block PR creation or approval.
• When GITHUB_TOKEN is present, use gh for organization-project lookup and live PR association or PR-to-project association. If GITHUB_TOKEN is not available, use paperclip-github-plugin:list_organization_projects and paperclip-github-plugin:add_pull_request_to_project for organization-project lookup and PR-to-project association when tooling can apply it.
• Naming the chosen board in prose is not a substitute for the live PR association when gh or GitHub Sync tooling can apply the link. Every selected Micronaut organization project should be linked when it exists and tooling can apply it.
• After PR creation, maintainer changes, retargets, or reschedules of the organization project are authoritative and must be preserved. Do not restore, reapply, re-add, or reset the original QA-selected organization project links over a maintainer project change.
• Documentation is part of the fix whenever public API, annotations, configuration properties, defaults, behavior, guides, or setup paths change. Write migration notes when migration pain is plausible. Do not relabel code work as type: docs solely because docs are impacted.
• Before docs PRs, identify where guides, reference docs, release notes, upgrade notes, examples, and validation live. For a guide, docs, or documentation PR where CI is not needed because documentation is not exercised by the build, put a skip-ci keyword such as [skip ci] in the commit message. Do not skip CI for build-validated snippets, executable examples, generated guides, ./gradlew publishGuide, or similar checks.
• Before opening, creating, or updating a guide, docs, or documentation PR, update, rebase, merge, or sync the work branch from the target branch; if that causes a merge or rebase conflict, record the conflict as a blocker and do not open or update the conflicting PR.

GitHub Sync And Direct GitHub Rules

• When GITHUB_TOKEN is present in the environment, prefer the gh CLI for GitHub reads and writes, including organization-project lookup and live PR association. If GITHUB_TOKEN is not available, use the GitHub Sync plugin tools / GitHub Sync plugin agent tools. GITHUB_TOKEN means that exact environment variable; do not search the filesystem, plugin config, or other files for a token.
• Use exact runtime tool IDs with the paperclip-github-plugin: prefix. The manifest id is paperclip-github-plugin; Paperclip namespaces tools as <pluginId>:<toolName>.
• Do not use Paperclip issue monitors to poll GitHub-synced PR state. CI/check status, mergeability, PR file state, review threads, reviewer routing, PR assets, and PR project links must be read or changed through GitHub Sync tools or gh when GITHUB_TOKEN is available. Issue monitors remain valid only for non-GitHub waits or external conditions that GitHub Sync does not own.
• Direct maintainer-visible GitHub body text written with gh or another GITHUB_TOKEN-backed client must separate the footer from the previous sentence with one blank line, then append this GitHub-flavored Markdown footer exactly: --- on its own line, then ###### ✨ This message was AI-generated using <exact model id>. Do not add the footer manually when using GitHub Sync plugin tools; the plugin appends it automatically when you send the human-facing body and llmModel.
• Core tool surface: search_repository_items, get_issue, list_issue_comments, update_issue, add_issue_comment, create_pull_request, get_pull_request, update_pull_request, list_pull_request_files, get_pull_request_checks, list_pull_request_review_threads, reply_to_review_thread, resolve_review_thread, unresolve_review_thread, request_pull_request_reviewers, list_organization_projects, add_pull_request_to_project, upload_pull_request_asset, and link_github_item.
• Prefer paperclipIssueId for synced work. Provide repository only when the plugin cannot infer it. For comments and review-thread replies, send only the human-facing body and set the exact llmModel so the plugin can append the footer.
• For PRs created outside the normal synced delivery pipeline, create one Paperclip child issue or subtask per affected project when the project exists in Paperclip, put it in the actual corresponding Paperclip project, assign it to the routine owner, and then link the PR with paperclip-github-plugin:link_github_item using kind: "pull_request", paperclipIssueId, and pullRequestUrl or reference. Synced GitHub issues are already linked by the sync plugin and do not need this extra out-of-pipeline child/subtask link. The PR creation metric is not the issue link; confirm the link_github_item tool returns status: "linked" before reporting the PR as tracked by GitHub Sync.
• In authenticated gh PR creation runs in mapped repositories, create the durable PR-to-Paperclip link before separately posting the pull_request_created metric to /api/plugins/paperclip-github-plugin/api/company-metrics/events. The metric endpoint is a native plugin JSON route with agent auth, not a plugin-tool call or webhook; authenticate with Authorization: Bearer ${PAPERCLIP_API_KEY}. The Paperclip host authenticates the bearer token, scopes the request to the calling agent's company, and rejects missing, expired, invalid, non-agent, or cross-company calls before plugin worker dispatch. Include companyId only when useful; if present, companyId must match the calling agent's company. Do not send the metric when create_pull_request created the PR, and never send it for PR edits, comments, review replies, or merges. GitHub alone cannot attribute non-plugin PR creation to Paperclip work.
• GitHub Sync issue and pull-request links are durable monitoring records. Agents may create or repair links through link_github_item, but must not unlink, tombstone, delete, or deactivate them; intentional unlinking is an operator UI action or internal repair path.
• For review threads, reply with a decision explanation such as committed the requested change, not applicable, or disagreement with the feedback before resolving; do not silently resolve review threads. Use reply_to_review_thread, resolve_review_thread, and unresolve_review_thread for this workflow.
• Use upload_pull_request_asset for PR-visible assets such as screenshots, generated PDFs, QA reports, logs, dashboards, examples, or browser-rendered evidence. Do not paste base64 assets into comments or claim assets are unavailable merely because GitHub's browser uploader is unavailable.

Routine And Overlay Rules

• Recurring routines are company-operating work, not substitutes for the synced GitHub backlog. The package includes Product Discovery, Security Deep Scan, two Technical Writer guide routines, CEO self-improvement, and Training.
• Exclude micronaut-projects/micronaut-project-template from normal product discovery, guide review, guide topic discovery, standalone guide PRs, and other normal project routines. For guide routines also exclude micronaut-projects/micronaut-build, except when work explicitly concerns template maintenance, shared file synchronization, referenced skills, repository-template infrastructure, or internal build tooling.
• micronaut-projects/micronaut-project-template is a repository template and file sync source, not an actual Micronaut project, so skip or exclude it from user guide, guide topic, standalone guide, and guide routines. micronaut-projects/micronaut-build contains internal Gradle plugins for Micronaut committers and is not intended for end users, so skip or exclude it from user guide, guide topic, standalone guide, and guide routines.
• When a routine spans multiple projects, create one child issue or subtask per affected Paperclip project, put it in the actual corresponding project, and let that project-specific child own validation and PR/no-PR decisions.
• When a routine discovers implementation-ready managed-repository source work, create a managed-repository delivery issue for QA intake with assignee QA (qa-engineer) and workMode: standard; do not directly assign it to Micronaut Engineer, Technical Writer, or another implementation owner.
• Routine-created managed-repository source work follows the normal delivery path after QA intake: planning when needed, implementation, QA verification, security review, code review, PR creation, and PR follow-through. The work is not complete until a linked PR exists or the project child/subtask records a no-diff/no-PR decision or named blocker.
• Routine-created no-diff/no-PR or empty-diff work can close without board approval when the owner records the target branch, comparison command or evidence, and empty-diff reason; do not route that empty work through QA verification, Security Engineer, or Code Reviewer solely to prove no PR should exist.
• Product Manager discovery uses the product-discovery skill and keeps the parent routine issue as coordinator only; the routine issue does not perform deep review, market research, product development issue creation, or feature request creation. Reuse/update existing open or already-created product-discovery child issues/subtasks, look for orphan or top-level product-discovery issues before creating another duplicate, and reparent or record a blocker when needed.
• Product Manager coordinator child issue descriptions must be self-contained and complete and tell Product Manager to use the product-discovery skill. Project subtasks must inspect previous Product Manager reports, prior product-discovery reports, discovery runs, project subtask reports, created product issues, no-create/no issue decisions, rejected candidates, and duplicate decisions before proposing a feature.
• Do not propose, open, or create the same previously proposed feature candidate or gap unless materially new evidence changes the decision.
• Technical Writer guide routines keep the parent routine issue as coordinator or coordination only; the routine issue must not open, create, or update PRs itself. Project child issues or subtasks perform guide assembly, fact-checking, deduplication, validation, PR/no-PR decisions, and direct docs PRs.
• Guide and documentation PR decisions and PR creation happen only inside or from the project subtask/child issue. Do not create or open top-level project-specific Paperclip issues for Weekly User Guide Review, Weekly Guide Topic Discovery, guide routine, or routine issue follow-up.
• Guide PRs must be evidence-backed, labeled type: docs, linked to the child through GitHub Sync, and leave the child in in_review rather than DONE just because a PR exists.
• For guide, docs, or documentation PRs, before opening, creating, or updating the PR, update, rebase, merge, or sync the work branch from the target branch.
• Internal routine-created project issues or subtasks with no linked GitHub issue, no public GitHub action, and an empty comparison against the approved target branch may close as verified no-op when the owner records the target branch, comparison command or evidence, and empty-diff reason. Do not send empty diffs through QA/Security/Code Review just to prove no PR should exist.
• CEO package-core, managed repository AGENTS.md, upstream dependency, and other out-of-pipeline PRs require affected-project child issue/subtask scoping before opening a PR; link the resulting PR to that Paperclip issue and record both URLs plus link status.
• Treat this source package's COMPANY.md, README.md, .paperclip.yaml, agents/, skills/, projects/, tasks/, and teams/ as immutable defaults inside imported company instances. Instance-specific guidance belongs in optional .company-runtime/shared.md, .company-runtime/agents/<agent-slug>.md, or .company-runtime/projects/<project-slug>.md; reusable defaults belong in a PR to alvarosanchez/micronaut-agent-company.

PR Readiness And Evidence

• Once a PR target branch is identified, fetch and update the work branch from that target before starting work, editing, committing, opening, creating, or updating the PR. If that rebase or merge conflicts, record the conflict as a blocker and do not open or update a conflicting PR.
• Code Reviewer creates the normal delivery PR only after QA and Security Engineer approvals. A source-changing branch with no acceptable linked PR is unfinished delivery work even when tests pass.
• Every PR must include a closing keyword such as Fixes #123, exactly one type: label, the correct issue linkage, approved target branch, and all selected organization projects when matching projects exist and GitHub tooling can apply them.
• If GitHub Sync reopens a PR-based issue because the linked PR has failing CI or unresolved review feedback, treat that as actionable PR follow-through even when the failure also reproduces on the target branch. Route to Micronaut Engineer to make the PR mergeable or produce a concrete named blocker; do not restore blocked solely because the failure appears baseline.
• If GitHub Sync or a stale handoff wakes an agent in in_progress for a PR that is open, non-draft, CLEAN, all reported checks are passing, and no actionable unresolved internal review state remains, restore maintainer-wait state: in_review, no internal assignee, no restarted execution policy/state, and a routing-correction comment.
• PRs opened by CEO from recurring routines, including managed repository AGENTS.md PRs, remain on daily self-improvement follow-up until CI is green, reported checks pass, and every unresolved review thread has a decision reply and is settled.
• Every non-trivial artifact should include linked issue/PR context, current state and next action, affected repositories and branches, tests run or still required, documentation impact, security impact, compatibility or migration risk, and the exact outcome recorded for the stage.
• Keep explanations concise and respectful, favor reversible decisions and small diffs, close or decline work with reasons, and maintain an audit trail a Micronaut maintainer can understand quickly.