company-package-evolution

Files (1)

• SKILL.md

SKILL.md (first lines)

# Company Package Evolution

Use this skill whenever the company learns something about its own operating system instead of a managed Micronaut repository.

CEO classifies, governs, prioritizes, and creates/assigns scoped QA intake children with evidence and acceptance criteria, then stops. Technical Writer owns prose docs, guides, repository `AGENTS.md`, company role instructions, and textual control-plane delivery. Executable package scripts/tests/config behavior and plugin/adapter code route to Engineer. Architect plans every Engineer-owned child. Executability alone does not require a full plan: a full plan requires a named cross-module compatibility, materially different fixes, migration, compatibility-matrix, or design-ambiguity trigger; otherwise Architect produces a lightweight plan. Every child states observable before/after behavior and regression or verification evidence for its artifact; only executable adapter/config findings must name that boundary. Security pre-triages security-sensitive work and performs final review. The implementation owner owns branch, commits, PR creation/update, CI repair, review replies, and PR follow-through; CEO owns none of those actions. For out-of-pipeline delivery, before opening the PR create one Paperclip child issue per affected project, place each child issue in the actual corresponding Paperclip project, assign it to the actual implementation owner, and ensure that child links any resulting PR. When a Paperclip child issue owns a PR, leave it `in_review` and do not close or mark it `DONE` until merge.

<!-- ceo-self-improvement-routing -->
```yaml
textual-finding:
  deliveryOwner: technical-writer
  planningRequired: false
  planningDepth: none
  adapterBoundaryRequired: false
  acceptanceEvidence: exact stale wording and expected corrected wording
executable-adapter-config-finding:
  deliveryOwner: micronaut-engineer
  planningRequired: true
  planningDepth: lightweight
  adapterBoundaryRequired: true
  acceptanceEvidence: observable adapter or configuration behavior plus regression assertions
architectural-adapter-config-finding:
  deliveryOwner: micronaut-engineer
  planningRequired: true
  planningDepth: full
  adapterBoundaryRequired: true
  architectureTriggers: [cross-module compatibility, materially different fixes, migration, compatibility matrix, design ambiguity]
  acceptanceEvidence: observable adapter or configuration behavior plus regression assertions
```

## Route By The Nature Of The Rule

Before choosing an owner, decide what kind of change the evidence supports; the surface decides the owner, not the other way round:

- an agent-specific rule that is narrow and cheap to state (one sentence, one trigger) goes into that role's `AGENTS.md`;
- a generalizable, multi-step procedure with its own when-to-use logic goes into a reusable skill (company-owned here, or a pinned referenced skill through the Training route), never into a role file;
- when both apply, update or create the skill and add a one-line pointer in the role file so the agent knows when to reach for it;
- a plugin tool description changes only when the failure was the agent not knowing when to use that tool, and the fix fits in the description; that is an upstream plugin change, not package prose;
- an existing-but-unfollowed rule (`instruction-miss` in the evidence taxonomy) becomes a make-it-stick change: move it into that role's own always-loaded surface (the `micronaut-repo-operations` entrypoint only for roles that load it; CEO does not, so a CEO rule stays in its `AGENTS.md` or `ceo-issue-history`), add a negative example, or strengthen the trigger, instead of restating it.

Sanity-check reuse honestly: a rule that applies to every delivery role belongs in a shared skill, and a "reusable skill" that only fits one role belongs in that role's file.

Every proposal is bounded: a role `AGENTS.md` may grow by at most 20% per proposal and never past the package-wide agent instruction budget (`scripts/agent-efficiency.test.mjs`, currently 125,000 bytes across all role files, with almost no headroom), so a proposal that adds text names what it trims; the always-loaded `micronaut-repo-operations` entrypoint has a stricter 9,000-byte cap in the same test and any other skill stays at or under 15 KB; a larger idea is split into several proposals rather than one rewrite.

Every proposal is replay-gated: name three to five past issues from the evidence window that the new rule must still resolve, walk each one, and drop or reword any rule that would have blocked a past success without a clear reason. Record the walk as "expected still-passes" in the candidate.

## Choose The Right Surface

Pick the smallest surface that solves the problem:

- If the learning is local to one Paperclip company instance, one maintainer group, or one temporary operating condition, keep it additive in extension instructions or `.company-runtime/` overlays.
- If the learning belongs to a managed Micronaut repository as a product artifact, update that repository's `AGENTS.md` guidance through a branch and PR in the managed Micronaut repository, and keep this company package unchanged.
- If the root cause clearly lives in a company-owned upstream dependency, such as `alvarosanchez/paperclip-github-plugin`, fix that upstream project directly instead of layering more package prose on top of it.
- If the gap is about how to use a bundled Paperclip system skill such as `paperclip`, `paperclip-create-agent`, `paperclip-create-plugin`, or `para-memory-files`, do not propose editing that bundled skill from this package. Add company-owned guidance, examples, or a companion skill here instead.
- If the gap is best solved by a reusable external skill or a live company-skill installation, prefer the company skill library and agent skill assignment model over copying ad hoc instructions into package core.
- If the learning should improve the default behavior of future imports of this company, promote it into the package core with a PR to `https://github.com/alvarosanchez/micronaut-agent-company`.

Portable package defaults should help most future imports, not just the current local runtime, and root-cause fixes should land in the owning upstream when that owner is outside the package repo.

## Package-Core PR Path

When the change belongs in the package core:

- create a QA-assigned child scoped to `alvarosanchez/micronaut-agent-company` and record the delivery owner
- Technical Writer delivers textual package instructions; Micronaut Engineer delivers executable package scripts/tests/config behavior behind an Architect plan; QA records the plan depth, Architect for Writer-owned work, and Security from the intake classification
- the delivery owner works only in a clone of `alvarosanchez/micronaut-agent-company`
- once the target branch is identified, the delivery owner fetches and updates the work branch from the target branch before editing or PR work; conflicts become a named blocker
- make the smallest portable diff across package-owned files such as `COMPANY.md`, `README.md`, `.paperclip.yaml`, `agents/`, `skills/`, `projects/`, `tasks/`, or `teams/`
- keep runtime-only learnings out of the diff; those still belong in additive extension instructions or `.company-runtime/`
- keep skills compatible with the Agent Skills model and prefer portable shortname references instead of machine-local skill wiring
- update both behavioral instructions and human-facing docs when policy changes
- run `npm test` or `npm run test:node22` when supported
- the delivery owner creates/updates the PR and owns follow-through until healthy maintainer wait
- when the change needs non-governance confirmation, use a Paperclip `request_confirmation`; keep linked approvals for governance-sensitive action
- before an out-of-pipeline PR, create one Paperclip child per affected project when that project exists, place it in the actual project, assign the implementation owner, and link the PR through GitHub Sync
- leave merge and release decisions to humans

## Managed Repository AGENTS.md PR Path

When the change belongs in a managed Micronaut repository's `AGENTS.md`:

- Technical Writer works in a clone of that managed repository and makes the smallest repo-local guidance change
- mechanical/stale/missing text uses QA -> Writer -> QA -> Reviewer; workflow/authority semantics add Architect before Writer; authority/tool/security changes also add Security
- Technical Writer creates/updates the PR and owns follow-through until healthy maintainer wait
- keep package-core files unchanged unless future imports also need a reusable default
- unavailable access or required governance approval becomes a linked approval or named blocker
- before an out-of-pipeline PR, create a child in the actual project, assign Technical Writer, and link the PR through GitHub Sync

The monthly CEO self-improvement report must include a `Managed Repository AGENTS.md Audit` section. For each active managed Micronaut repository considered, record whether root `AGENTS.md` exists, whether it is durable/current or stale/generated/missing, and the exact outcome: no action needed, repo-local PR opened or updated, linked follow-up issue created, linked approval requested, or blocker named. A bounded metadata/readability check is enough unless recent execution evidence points to a deeper repository-specific guidance problem.

When the change belongs in a company-owned upstream dependency:

- Micronaut Engineer works in a clone of the upstream repository and makes the smallest root-cause fix
- update this package only when future imports also need durable instruction/routing changes
- run the relevant upstream tests
- Engineer creates/updates the upstream PR and owns follow-through
- before an out-of-pipeline PR, create a child in the actual project, assign Engineer, and link the PR through GitHub Sync

For all package-core, managed repository, upstream dependency, or other PRs created outside the normal synced GitHub issue delivery pipeline, create the Paperclip child first. If one routine can affect more than one project, create one child per affected project; each child belongs to the actual corresponding project and is assigned to the implementation owner. Synced GitHub issues are already linked. Use `paperclip-github-plugin:link_github_item` with `kind: "pull_request"`, `paperclipIssueId`, and `pullRequestUrl` or `reference`. PR children remain `in_review` until merge; healthy maintainer wait carries no agent assignee and parks on the human owner. If durable linking is unavailable, record the blocker.

## PR Follow-Through Contract

The implementation owner owns follow-through: Engineer for code/build/dependency/plugin work and Writer for docs/AGENTS/instructions. No repository change returns to that owner only for a required response, then healthy maintainer wait. Routine source/test/dependency/build changes rerun Engineer -> QA -> Reviewer under the PR's existing approved plan (or the lightweight plan recorded in `qa-intake`/`training-route`), and routine prose or executable docs rerun Writer -> QA -> Reviewer. Behavior-changing executable instructions may add final Security review after QA without pre-triage when no defined Security trigger is established. Defined Security triggers add pre-triage before the owner and final Security review after QA. Only design-changing requests add Architect before the owner and gates. A clean rebase with green CI returns to maintainer wait; conflicts or semantic changes rerun applicable gates. Escalate unresolved behavior, compatibility, or security. GitHub Sync should persist a company-validated `followThroughAssigneeAgentId`; this package documents but does not implement that plugin contract.

## When The Repo Or PR Path Is Unavailable

If you do not have a working copy of the package repo or cannot send a PR from the current environment:

- do not mutate an imported company instance's core files in place
- create a linked board approval request for the exact next action when human authorization or repo access is what is missing
- create a Paperclip issue-thread interaction when the missing input is a bounded choice, suggested task selection, or non-governance confirmation rather than authorization
- record a maintainer-ready package proposal in the current Paperclip report only as support for that linked approval or clearly documented blocker
- use additive extension instructions or `.company-runtime/` overlays only for the local guidance that cannot wait for a published package update

## Reporting

Every accepted candidate records: the one-sentence quotable pattern, the root-cause hypothesis, the evidence tuples (issue, comment or run, verbatim fragment), the target surface (role file, skill, both, tool description, managed repository, upstream, or local overlay), the minimal inline diff or exact wording change rather than prose about it, the expected still-passes replay set, and one or two sentences on why this change and not something bigger.

When you propose or send a package-core change, explain:

From alvarosanchez/micronaut-agent-company, MIT.

More from alvarosanchez/micronaut-agent-company