agent-pmo

name	agent-pmo
description	Apply portfolio-wide repository standards (Makefile, CI, linting, coverage) to a new or existing repo. Use when user says "enforce standards", "fix repo", "make compliant", "set up repo", or "apply repo standards". Reads the authoritative spec and creates/updates config files. NEVER commits or pushes.
disable-model-invocation	true

Portable skill. This skill adapts to the current repository. The agent MUST inspect the repo structure and use judgment to apply these instructions appropriately.

Enforce Repository Standards

This skill is a process wrapper around the spec. The spec is authoritative for every rule, table, config file, command, and threshold. This file tells you the order of operations, what to inspect in the target repo, and what decisions to make. Do not duplicate spec content here — point to the relevant spec ID and read it.

• Spec: {{STANDARDS_REPO}}/docs/specs/REPO-STANDARDS-SPEC.md
• Templates: {{STANDARDS_REPO}}/agent-pmo-skill/templates/

If the paths above do not exist, report an error and stop. Do not search the filesystem or guess paths.

NEVER run git commit, git push, or any git write command. Read-only git commands (status, log, diff) are fine.

How to use this skill

1. Read the spec. When a step references a spec ID (e.g. [MAKE-TARGETS]), open that section and follow it. The spec contains the rules; this file is the workflow.
2. Before touching files, read the universal rules below — they apply to every step.
3. Execute Steps 1–5 in order.

Universal rules (apply to EVERY step)

• Token discipline. Try to be economical with token usage while carrying out this skill.
• Merge, don't clobber. If a compliant equivalent exists → leave it. If an equivalent exists under a wrong name → rename/update in place. Only create from scratch if nothing equivalent exists.
• No duplicates. The target repo must not end up with two files serving the same purpose. Rename or delete the old one.
• Templates are starting points, not copy-paste targets. See spec [MODES-CUSTOMIZE]. Strip every language/tool section that does not apply. Fill every {{placeholder}}. Zero irrelevant content in the output.
• Stamp every file you create or substantively modify with agent-pmo:<hash> per spec [MARKER] / [MARKER-FORMAT]. Get the hash with git -C "{{STANDARDS_REPO}}" rev-parse --short HEAD.
• Never stamp a file whose source does not exist in {{STANDARDS_REPO}}/agent-pmo-skill/templates/. Verify by reading the source first. Applies especially to skills — list templates/skills/ and only create what is actually there.
• Never run git write commands. Read-only git is fine.
• Release tags build immutable source. For tag-triggered releases, build the tagged SHA. Do not check out main, commit/push version bumps, or move tags/branches during release. See [CI-RELEASE].
• Version stamping is a build input. Deployable repos SHOULD keep source versions at 0.0.0-dev and stamp the tag/test version via a first-class script or build target before build, verify, package, and publish. Do not use ad hoc sed against structured files.
• Developer-tool repos MUST run the shipwright-compliance skill. It is authoritative for VSIX bundling, manifest, version stamping, and publishing. See [CI-SHIPWRIGHT].

Instructions

Step 1 — Read the spec and detect context

1. Read {{STANDARDS_REPO}}/docs/specs/REPO-STANDARDS-SPEC.md. All file contents, configs, CI workflows, and commands come from the spec. Do not improvise.
2. Detect languages from build files (Cargo.toml, package.json, pubspec.yaml, *.csproj/*.fsproj/*.sln, go.mod, pyproject.toml, setup.py, requirements.txt).
3. Determine repo type (library, CLI, app/service, extension, static site) for the coverage threshold per spec [COVERAGE-THRESHOLDS]. Default 90%. If the repo ships a developer tool (VS Code .vsix, CLI/binary published to Homebrew/Scoop/npm/NuGet/PyPI/crates.io, IDE plugin, installer), flag it for the mandatory Shipwright audit in Step 3c per spec [CI-SHIPWRIGHT].
4. Identify the canonical instruction file per spec [AGENT-CANONICAL] and [AGENT-PLACEMENT]:
   • AGENTS.md with substantial content (>10 lines, not a pointer) → canonical.
   • Else CLAUDE.md with substantial content → canonical.
   • Else (uninitiated repo) create the generic AGENTS.md from templates/AGENTS.md as canonical — for EVERY agent, Claude included ([DESIGN] 5a). Other agent files (CLAUDE.md via @AGENTS.md, etc.) become pointers per [AGENT-POINTERS]. Prefer generic over Claude-specific, but never break Claude.
5. Read the target agent's official docs (spec [AGENT-DOCS]) before touching instruction/skill files. Syntax and placement differ per agent.

Step 2 — Audit existing artifacts

Before creating anything, inventory what already exists so Step 3 can merge instead of duplicate.

For each area below, record: what exists, what's missing, what's under a wrong name, what duplicates a standard artifact.

• 2a. Docs folder. Look for docs/ (standard) or variants doco/, documentation/, doc/, documents/. Check for docs/specs/ and docs/plans/ subdirs. Flag loose markdown files in docs/ for classification.

• 2b. CI workflows. List .github/workflows/*.yml. Identify any existing workflow that does what ci.yml/release.yml/deploy-pages.yml should do, under any filename. Per spec [CI-WORKFLOWS] / [CI-JOBS] these will be renamed in Step 3, not re-created. Also note whether .github/workflows/dependabot-automerge.yml exists and whether the dependabot-upgrades staging branch exists (git ls-remote --heads origin dependabot-upgrades) — both are required by [GITHUB-DEPENDABOT], created in Step 3g-dep if missing. Flag these trigger violations per [CI-WORKFLOWS]:

  • ci.yml triggering on push: branches: [main] (merges to main must trigger nothing — PR-only, unless the repo allows non-PR commits to main, which must be commented).
  • ci.yml or codeql.yml triggering on branches: [dependabot-upgrades] (breaks the no-CI-on-staging guarantee — staging PRs must run zero CI; [GITHUB-DEPENDABOT]).
  • release.yml triggering on anything other than a v* tag push (no release on merge/schedule).
  • A repo that HAS a website but whose release.yml has no website-deploy step (release MUST deploy the site). For release workflows, also flag these as critical blockers: checkout ref: main in tag jobs, any git commit/git push/tag mutation, source-control version bumps after the tag, ad hoc sed stamping of structured files, missing tests for build-time version stamping, and — for any repo with a codeql.yml — a release.yml whose publish jobs do NOT needs: a gated CodeQL job (a release that cannot be stopped by a security finding is a critical blocker, see [GITHUB-CODE-SCANNING]).

• 2c. Makefile. If present, read in full. Classify every public target per spec [MAKE-TARGETS]:

Step 3 — Apply standards (merge-first, DO NOT commit/push)

For every item: (1) compliant equivalent exists → leave alone; (2) equivalent exists under wrong name/content → rename/update in place; (3) nothing equivalent → create from template.

• 3a. Docs folder. Rename doco//documentation//doc//documents/ → docs/. Merge if both exist, then delete the non-standard one. Create docs/specs/ and docs/plans/. Classify loose markdown files: specs = behavior/requirements; plans = how-to with TODO checklists. Update internal references that pointed to the old folder name.

• 3a-ii. Spec ID rule. Ensure the rule is present in the canonical instruction file. Validation/renaming of existing spec IDs is the spec-check skill's job, not this one.

• 3b. Makefile. Per spec [MAKE-TARGETS], [MAKE-REPO-SPECIFIC], [MAKE-IDE-EXT], [MAKE-TEMPLATE]. Edit the existing Makefile surgically — never overwrite the whole file to "regenerate" it. The Makefile has two sections:

  • Standard Targets — canonical names (build, test, lint, fmt, clean, ci, setup), but ONLY the subset that applies to this repo. No synonyms, no extras here, and no hollow no-op target added just to complete the set.
  • Repo-Specific Targets — a separate section below, owned by the repo, varies per repo, preserved byte-for-byte unless agent-pmo stamped it.

  Act on the Step 2c classification:

  • (i) applicable standard target missing/wrong → add/fix in Standard Targets. A standard target that doesn't apply here is NOT missing — leave it out.
  • (ii) synonym/duplicate of a standard target → merge useful logic into the standard target, delete the duplicate, update callers.
  • (iii) orphan → [MARKER-CLEANUP]: merge useful logic into the correct standard target, delete the orphan.
  • (iv) genuine repo-specific target → leave it exactly as-is. If it sits inside Standard Targets, move it down into Repo-Specific Targets unchanged. Never delete, rename, reorder, or "tidy up".
  • (v) editor extension with no rebuild-install-<kind> target → add one in Repo-Specific Targets ([MAKE-IDE-EXT]): uninstall → clean → rebuild → package → install-if-supported, via underscore-prefixed sub-recipes. Enforce parity ([MAKE-IDE-EXT-PARITY]): factor packaging into ONE recipe shared by rebuild-install-<kind>, the test/e2e target (which runs it BEFORE testing), and the release workflow, so the tested bundle is byte-for-byte the shipped bundle. Fold any separate "test build" into that one recipe.

Step 4 — Deduplication check

After all changes, verify:

1. CI workflows — exactly one ci.yml, at most one release.yml, at most one deploy-pages.yml. Delete any legacy siblings.
2. Linter configs — one config per tool per language. No both-of pairs (e.g. eslint.config.mjs AND .eslintrc.json; .prettierrc AND .prettierrc.json; .golangci.yml AND .golangci.yaml; .flake8 AND pyproject.toml [tool.ruff]).
3. Coverage configs — no both-of (.coveragerc AND [tool.coverage]). No leftover coverage shell scripts.
4. Formatter configs — one per tool. No both-of ([tool.black] AND [tool.ruff.format]).
5. Build files — no competing systems with identical targets (e.g. Makefile AND Taskfile.yml). 5b. Deslop (supported-language repos) — exactly one .deslop.toml holding the threshold; ci.yml has the deslop . gate with no hardcoded threshold; no duplicate threshold in env vars/GH variables. ([CI-DESLOP])
6. Docs folders — exactly one, called docs/. docs/specs/ and docs/plans/ exist. No loose markdown that belongs in a subdir.
7. Skills — no duplicates across agent-native skill directories. Consolidate to the primary agent's dir per spec [SKILL-PLACEMENT].
8. Agent instruction files — exactly ONE canonical file with full rules. All others are pointers (marker + @<canonical> only). Rename legacy pointer filenames (.clinerules/00-read-claude-md.md → .clinerules/00-read-instructions.md).
9. Orphaned agent-pmo: files — per spec [MARKER-CLEANUP]: for every marked file, verify the source still exists in {{STANDARDS_REPO}}/agent-pmo-skill/templates/. If not, delete the orphan.
10. Stale markers — flag files more than 50 commits behind current standards HEAD per spec [MARKER-AUDIT].
11. Report all duplicates deleted, orphans removed, stale markers found. When unsure whether something is a duplicate or a genuine repo-specific artifact, — never delete "to be tidy".

Merging multiple files into one is a valid outcome and overrides the no-delete default.

Step 5 — Verify (DO NOT commit)

1. List every file created, modified, renamed, or deleted (including Make targets merged/removed).

2. If possible, run make lint and make test to validate. Report errors so the user can fix them.

3. LICENSE check. If no license file was found in Step 2h, emit the banner at the top of the final report — impossible to miss, do not soften, do not omit:

   ================================================================================
   !!!  WARNING — NO LICENSE FILE FOUND  !!!
   ================================================================================
   This repository has NO LICENSE file. Under default copyright law this means
   "all rights reserved" — nobody (including contributors) has permission to use,
   copy, modify, or distribute this code.
   
   You MUST add a LICENSE file. Common choices:
     - MIT          — permissive, simple
     - Apache-2.0   — permissive, patent grant
     - GPL-3.0      — copyleft
     - BSD-3-Clause — permissive
     - Proprietary  — all rights reserved (explicit)
   
   This skill will NOT create a LICENSE file for you — the choice has legal
   consequences and must be made deliberately.
   ================================================================================
   

4. Remind the user: No commits or pushes were made. Review the changes and commit when ready.