micronaut-repo-operations

Files (8)

• SKILL.md
• github-sync-tools.md · references/
• implementation-hygiene.md · references/
• intake-routing-release.md · references/
• internal-routines-overlays.md · references/
• pr-delivery-evidence.md · references/
• workflow-control-plane.md · references/
• repo-evidence.mjs · scripts/

SKILL.md (first lines)

# Micronaut Repo Operations

Use this skill whenever you act on synced GitHub issues or pull requests for this company. This entrypoint contains only the always-needed contract. Load detailed procedures on demand before the matching action.

## Load The Right Reference

- Stage routing, Paperclip APIs, interactions, approvals, planning confirmation, environments, liveness recovery, dependencies, and final-state checks: `references/workflow-control-plane.md`.
- QA intake, issue types, closure dispositions, release targeting, target branches, Micronaut organization projects, documentation policy, and imported issues with existing PRs: `references/intake-routing-release.md`.
- GitHub Sync tool names, authentication boundaries, footer behavior, PR linking, KPI attribution, monitor ownership, link immutability, review threads, and assets: first follow `micronaut-github-operations`; load `references/github-sync-tools.md` only when an uncommon or legacy detail is still needed.
- Internal routines, project children, no-diff outcomes, product discovery, guide work, package evolution, and `.company-runtime/` overlays: `references/internal-routines-overlays.md`.
- PR creation/readiness, organization-project links, reviewer requests, follow-through, maintainer-wait state, and evidence: `references/pr-delivery-evidence.md`.
- Before editing, building, or committing in a worktree (branch sync, build flags, commit hygiene, security-constraint mapping): `references/implementation-hygiene.md`.

Before mutating issue state, publishing to GitHub, opening or updating a PR, closing an issue, creating routine follow-up, or handling an uncommon release/approval case, load the matching reference.

Use the separately assigned read-only `paperclip-control-plane` skill for deterministic issue/document snapshots, verification, and approval-link checks. This skill remains the Micronaut workflow policy layer; native Paperclip tools perform permitted mutations.

## Efficient Evidence Collection

- For local repository preflight, run `node <skill-directory>/scripts/repo-evidence.mjs --base <ref>` once; omit `--base` until the approved target is known. Resolve `<skill-directory>` from this skill's inventory. The read-only script returns compact machine-readable JSON for repository root, branch, HEAD, upstream, worktree state, base divergence, changed files, build markers, and instruction files. Read raw git output only when `errors` is non-empty or the decision needs omitted evidence.
- Batch independent reads and GitHub Sync lookups. Consume current QA, plan, implementation, and review artifacts instead of rediscovering facts already recorded upstream.
- CodeGraph is optional and only present if the deployment exposes a CodeGraph MCP server to the agent runtime. Use a focused query for unfamiliar or large repositories, cross-module dependency or call-chain analysis, symbol exploration, or when ordinary search/read becomes repetitive or insufficient. Skip CodeGraph for small localized fixes, known files, documentation or configuration changes, and tasks with a precise target. Do not invoke it merely because a task includes code; if it is unavailable or its index is stale, continue with ordinary search/read without treating that as a blocker.
- Prefer structured JSON and stable issue documents. Keep decision-relevant fields in stage artifacts and link to larger evidence instead of copying it.
- Plugin tools arrive through Paperclip's tool gateway (`GET /api/plugins/tools`, `POST /api/plugins/tools/execute` with the run token) filtered by company tool-access policy. Runs may resume persistent ACP session state instead of a fresh process, so re-read the issue state and `PAPERCLIP_WORKSPACE_*` environment on every wake instead of trusting remembered context or working directory.

## Shared Stage Contract

- Act only as the current execution-stage participant, the explicit assignment owner, or the invoked routine owner. If another participant or a human approval owns the next move, stop without changing routing.
- If a wake reveals no new decision-relevant evidence since the latest durable comment or artifact, make no Paperclip mutation: do not post a no-change comment, do not rewrite an unchanged artifact, and do not mutate status, assignment, execution state, or wake another agent. A successful silent no-op is preferable to an audit-trail entry that merely repeats the current state.
- Pre-delivery steps are `TODO` handoffs. The delivery owner creates the review-only execution policy when it submits the SHA; `executionState.currentParticipant` resolves the active stage, `executionState.returnAssignee` (the delivery owner) receives `changes_requested`, and review stays `in_review` until the route advances.
- Every substantive stage produces one durable artifact, written explicitly to a keyed document or comment: the host does not post your reasoning and summarizes only the final output segment. QA keeps `qa-intake` and `qa-verification` separate.
- Approve an active stage with `status: done` and a decision comment. Request changes with a non-`done` status, preferably `in_progress`, and a precise decision comment. Manual `TODO` assignment is only for owner changes outside an active review policy.
- Let execution-policy advancement or assignment wake the next participant. Agent-authenticated callers must not invoke another agent's heartbeat or use `@` mentions as routing.
- For synced GitHub delivery work, `approved` advances the workflow; it never authorizes an agent to mark the Paperclip item `DONE`. GitHub Sync sets `DONE` after a merge and `CANCELLED` after a not-planned or duplicate closure; park closed items `in_review` on the issue's `responsibleUserId` (916 refuses an agent-authored `in_review` with no review path).
- Board governance uses a linked Paperclip approval. Non-governance input uses issue interactions such as `suggest_tasks`, `ask_user_questions`, or `request_confirmation`. Put the exact proposed public comment in `recommendedAction` when approval gates a maintainer-visible write.
- Use standard work mode for delivery, routine project children, product proposals, and PR follow-through. Planning mode is only for explicit plan-only precursors; accepted plans create standard-mode children through accepted-plan decomposition.
- Work only in repositories configured by this company's GitHub Sync plugin. Read repo-local `AGENTS.md`, optional `.company-runtime/` overlays, and project docs for local facts; do not infer membership, branch strategy, release policy, docs layout, or tests from another repository.
- Human merge/release decisions and human post-creation project retargeting are authoritative.

## Route Summary

- The authoritative ordered `qa-intake.stageSequence` selected from `references/intake-routing-release.md` controls every handoff; issue type alone does not select the route.
- Architect plans every Micronaut Engineer implementation: routine non-security bugs and compatible dependency upgrades get a lightweight plan and skip Security; architecture or migration triggers require a full plan before the implementation owner; PR re-entry repairs reuse the existing approved plan (or the lightweight plan recorded in `qa-intake`/`training-route`), and only design changes return to Architect.
- Defined Security triggers add pre-triage before implementation and final review after QA; pre-triage never replaces Architect, implementation, QA verification, or final Security review.
- Routine prose and executable docs use Writer -> QA -> Code Reviewer; security-sensitive docs use both Security stages, and workflow/authority semantics add Architect.
- Questions, clarification waits, unreproducible reports, duplicates, and already-implemented reports may use QA's evidence-backed direct disposition path.
- Existing contributor PRs remain on normal gates when salvageable; replacement work does not require closing the contributor PR.

## Finish

Before stopping, re-read the issue or routine state and verify the intended outcome exists. Record the current state, next action, affected repository/branch, tests or evidence, docs/security/compatibility impact, and exact stage outcome. If a required tool or source is unavailable, name the concrete blocker; never claim a mutation or verification that did not occur.

From alvarosanchez/micronaut-agent-company, MIT.

More from alvarosanchez/micronaut-agent-company