diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md index fc78c0c..52fa102 100644 --- a/.github/CHANGELOG.md +++ b/.github/CHANGELOG.md @@ -6,7 +6,15 @@ Use this format for new updates: - One bullet per meaningful change. - Include file/path scope when useful. +## 2026-04-19 +- Renamed the root `Makefile` target from `catalog-validation` to `github-catalog-validation` for nomenclature consistency with the `_github-catalog-validation` workflow and refreshed `.github/README.md` plus `.github/agents/README.md` to remove remaining live `internal-router` wording in favor of the direct-entry operational model. +- Renamed the canonical execution and challenge agents from `.github/agents/internal-fast-executor.agent.md` and `.github/agents/internal-critical-challenger.agent.md` to `.github/agents/internal-delivery-operator.agent.md` and `.github/agents/internal-critical-master.agent.md`, then realigned the live operational contracts, prompt references, shared boundary skills, and tests to the new canonical names. +- Renamed `.github/workflows/catalog-validation.yml` to `.github/workflows/_github-catalog-validation.yml`, replaced the old Bash-only `catalog_validation` entrypoint with the new `.github/scripts/github_catalog_validation.py` plus matching Bash wrappers, and realigned `Makefile`, script coverage tests, and security-baseline references to the new workflow and script names. +- Codified the pending retained-learning lessons into `.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md`, `.github/skills/internal-agent-development/SKILL.md`, and `.github/skills/internal-agent-development/references/subagent-patterns.md`, added contract tests for the new guidance, and cleared the now-codified rows from `LESSONS_LEARNED.md`. + ## 2026-04-18 +- Centralized lane-mismatch handling into the new repository-owned skill `.github/skills/internal-agent-boundary-recommendation-engine/`, realigned the four canonical operational agents plus the two sync command centers to stop and recommend the right owner through one shared protocol, removed the unused `agent` tool from the sync agents, and retired the orphaned `internal-agent-routing-engine` bundle from the live catalog. +- Removed `internal-router` and the paired `internal-agent-routing-engine` from the live canonical operational model, left the four direct owners as the only canonical lanes, defaulted ambiguous entry to `internal-planning-leader`, platform-enforced no hidden peer dispatch by setting the canonical owners to `disable-model-invocation: true`, and realigned the active contracts, references, and tests away from router-centric dispatch. - Narrowed `.github/workflows/catalog-validation.yml` so it no longer repeats `_pre-commit` coverage: the workflow now runs the new `make catalog-lint` target for Bash syntax plus Python bytecode compilation, skips the duplicate YAML lint step, and leaves Markdown lint available as a manual target instead of failing the catalog-specific gate on long-standing repo-wide style debt. - Expanded `.github/scripts/requirements.txt` so the locked `PyYAML==6.0.2` hashes cover the published CPython 3.13 source and wheel artifacts used by GitHub Actions Linux and local macOS installs, preventing `.github/scripts/run.sh` from failing on valid platform-specific downloads. - Consolidated the repository pre-commit baseline onto `.github/workflows/_pre-commit.yml`, removed the duplicate `_terraform-pre-commit.yml` and `terraform-pre-commit.yml` workflows, and realigned the sync baseline, deprecation log, README, and sync tests to the single canonical workflow. @@ -39,7 +47,7 @@ Use this format for new updates: - Closed the remaining behavior gap between `internal-critical-challenger` and the imported `awesome-copilot-critical-thinking` / `awesome-copilot-devils-advocate` agents by making non-assumption about user expertise explicit, enforcing one narrow objection or probing move per turn, and allowing the user to end the challenge flow directly into synthesis. - Expanded `internal-critical-challenger` so it may persist its analysis when asked, defaulting retained challenge artifacts to `tmp/superpowers/` unless the user requests another path, and so implementation requests now explicitly redirect back to `internal-router` after first asking whether the current analysis should be saved. - Added a narrow second-lane exception to the canonical operating model: `internal-critical-challenger` may now invoke `internal-router` as a parallel lane only when the user explicitly asks to keep the challenge lane active while opening an operational lane, with the router remaining the sole downstream routing authority. -- Removed `.github/instructions/awesome-copilot-copilot-sdk-python.instructions.md` from the live catalog and realigned `.github/INVENTORY.md`, `.github/README.md`, `.github/agents/internal-sync-control-center.agent.md`, and `tmp/superpowers/2026-04-10-audit-catalogo-copilot.md` so the imported Python SDK instruction is no longer treated as active. +- Removed `.github/instructions/awesome-copilot-copilot-sdk-python.instructions.md` from the live catalog and realigned `.github/INVENTORY.md`, `.github/README.md`, `.github/agents/internal-sync-external-resources.agent.md`, and `tmp/superpowers/2026-04-10-audit-catalogo-copilot.md` so the imported Python SDK instruction is no longer treated as active. ## 2026-04-10 - Added the provider skill rollout beyond AWS by creating repository-owned Azure, GCP, and GitHub skill families under `.github/skills/internal-{azure,gcp,github}-*`, keeping the AWS boundary model as the baseline with short adaptive strategic skills, separate organization/governance/operations lanes where justified, minimal `references/`, and `agents/openai.yaml` metadata for every new skill. @@ -73,7 +81,7 @@ Use this format for new updates: ## 2026-04-04 - Added a mandatory end-of-operation completion report contract to `.github/copilot-instructions.md`, documented the same emoji-based `Outcome` / `Agents` / `Instructions` / `Skills` structure in `.github/README.md`, and kept root `AGENTS.md` on a thin bridge pointer to the detailed policy. - Extended `INTERNAL_CONTRACT.md`, `tests/test_contract_runner.py`, `tests/test_validate_copilot_customizations.py`, and `.github/scripts/validate-copilot-customizations.py` so the completion-report contract is now source-governed and strict-validator enforced. -- Updated `internal-sync-control-center`, `internal-sync-global-copilot-configs-into-repo`, and the sync skill workflow so completed sync runs must also end with the same completion-report categories and explicit unused-category explanations. +- Updated `internal-sync-external-resources`, `internal-sync-global-copilot-configs-into-repo`, and the sync skill workflow so completed sync runs must also end with the same completion-report categories and explicit unused-category explanations. - Updated sync governance and `.github/scripts/internal-sync-copilot-configs.py` so retained sync plans now live under repository-root `tmp/` instead of `.github/`, and the tracking-plan flow creates `tmp/` automatically when it is missing. - Updated `.github/copilot-instructions.md`, `.github/instructions/internal-python.instructions.md`, and `.github/skills/internal-script-python/SKILL.md` so new Python scripts must make an explicit stdlib-vs-library decision, prefer mature third-party packages when they clearly simplify the final code, and record that choice in a short dependency decision note before implementation. diff --git a/.github/INVENTORY.md b/.github/INVENTORY.md index 2750ac1..972884a 100644 --- a/.github/INVENTORY.md +++ b/.github/INVENTORY.md @@ -40,10 +40,10 @@ This file is the exact path inventory for the live GitHub Copilot catalog in thi - `.github/skills/awesome-copilot-codeql/SKILL.md` - `.github/skills/awesome-copilot-dependabot/SKILL.md` - `.github/skills/awesome-copilot-secret-scanning/SKILL.md` +- `.github/skills/internal-agent-boundary-recommendation-engine/SKILL.md` +- `.github/skills/internal-agent-cross-lane-engine/SKILL.md` - `.github/skills/internal-agent-development/SKILL.md` -- `.github/skills/internal-agent-operating-model-engine/SKILL.md` -- `.github/skills/internal-agent-routing-engine/SKILL.md` -- `.github/skills/internal-agent-sync-control-center/SKILL.md` +- `.github/skills/internal-agent-sync-external-resources/SKILL.md` - `.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md` - `.github/skills/internal-aws-governance/SKILL.md` - `.github/skills/internal-aws-mcp-research/SKILL.md` @@ -118,10 +118,9 @@ These imported `openai-*` office skills remain support-only depth for repositori ## Agents -- `.github/agents/internal-critical-challenger.agent.md` -- `.github/agents/internal-fast-executor.agent.md` +- `.github/agents/internal-critical-master.agent.md` +- `.github/agents/internal-delivery-operator.agent.md` - `.github/agents/internal-planning-leader.agent.md` - `.github/agents/internal-review-guard.agent.md` -- `.github/agents/internal-router.agent.md` -- `.github/agents/internal-sync-control-center.agent.md` +- `.github/agents/internal-sync-external-resources.agent.md` - `.github/agents/internal-sync-global-copilot-configs-into-repo.agent.md` diff --git a/.github/README.md b/.github/README.md index df82c05..318e15a 100644 --- a/.github/README.md +++ b/.github/README.md @@ -3,7 +3,7 @@ This directory is the source-side catalog for reusable GitHub Copilot customization assets maintained in `cloud-strategy.github`. - `.github/copilot-instructions.md` is the primary detailed policy layer. -- Root [`AGENTS.md`](../AGENTS.md) is the strategic entrypoint, precedence anchor, and bridge for routing, naming, discovery, and the pointer to exact path inventory. +- Root [`AGENTS.md`](../AGENTS.md) is the strategic entrypoint, precedence anchor, and bridge for operational ownership, naming, discovery, and the pointer to exact path inventory. - [`INVENTORY.md`](INVENTORY.md) is the exact path inventory for the live catalog. - This README is an orientation guide for maintainers of the source catalog. It should describe the live on-disk catalog only. @@ -21,7 +21,7 @@ This directory is the source-side catalog for reusable GitHub Copilot customizat | Path | Purpose | | --- | --- | -| `copilot-instructions.md` | Primary detailed policy, validation baseline, routing model, and completion-report contract. | +| `copilot-instructions.md` | Primary detailed policy, validation baseline, direct-entry operating model, and completion-report contract. | | `INVENTORY.md` | Exact path inventory for live instructions, skills, and agents. | | `copilot-code-review-instructions.md` | Review-specific severity and defect-first guidance. | | `copilot-commit-message-instructions.md` | Commit message conventions. | @@ -45,7 +45,7 @@ Use instructions as automatic file-path guidance. Do not restate path-driven beh Skills are grouped into three functional lanes plus imported support families. -- `internal-*`: repository-owned governance, routing, review, execution, project, sync, platform, and provider skill families for AWS, Azure, GCP, and GitHub +- `internal-*`: repository-owned governance, ownership, review, execution, project, sync, platform, and provider skill families for AWS, Azure, GCP, and GitHub - `obra-*`: strategic workflow support for brainstorming, planning, debugging, verification, worktree usage, and skill authoring - Imported support families: - `awesome-copilot-*` @@ -66,12 +66,11 @@ Use [`INVENTORY.md`](INVENTORY.md) for the exact path inventory. Use root [`AGEN See [`agents/README.md`](agents/README.md) for the selection guide. -- Canonical repository-owned operational agents: `internal-router`, `internal-fast-executor`, `internal-planning-leader`, `internal-review-guard`, `internal-critical-challenger` -- Repository-owned source-side sync and governance agents: `internal-sync-control-center`, `internal-sync-global-copilot-configs-into-repo` +- Canonical repository-owned operational agents: `internal-delivery-operator`, `internal-planning-leader`, `internal-review-guard`, `internal-critical-master` +- Repository-owned source-side sync and governance agents: `internal-sync-external-resources`, `internal-sync-global-copilot-configs-into-repo` - No imported support agents currently ship in the live catalog. -The current repository-owned operating model is the internal router plus the four canonical internal owners. Do not document retired operational routes here. -Only `internal-router` actively routes between canonical owners; the four canonical owners stay boundary-driven and user-directed. +The current repository-owned operating model uses direct entry to the four canonical internal owners. When the right owner is unclear, default to `internal-planning-leader`. Do not document retired operational routes here. ### Scripts and workflow diff --git a/.github/agents/README.md b/.github/agents/README.md index 9bec5ed..4158889 100644 --- a/.github/agents/README.md +++ b/.github/agents/README.md @@ -1,6 +1,6 @@ # Agents Catalog -This folder contains deliberate custom agents for repository-owned operational routing plus repo-only sync workflows. +This folder contains deliberate custom agents for repository-owned direct-owner operations plus repo-only sync workflows. ## Resolution order 1. Apply repository non-negotiables from `copilot-instructions.md`. @@ -8,31 +8,30 @@ This folder contains deliberate custom agents for repository-owned operational r 3. Apply matching `instructions/*.instructions.md` (`applyTo` by path). 4. Apply referenced skill details. -## Recommended routing -- Default operational front door: `internal-router` (routes only; it does not edit files or implement changes). -- Direct canonical owners: `internal-fast-executor`, `internal-planning-leader`, `internal-review-guard`, `internal-critical-challenger`. -- Source-side catalog sync, rationalization, overlap cleanup, and governance drift correction in this repository: `internal-sync-control-center`. +## Recommended owner selection +- Safe fallback when the right operational lane is still ambiguous: `internal-planning-leader`. +- Direct canonical owners: `internal-delivery-operator`, `internal-planning-leader`, `internal-review-guard`, `internal-critical-master`. +- Source-side catalog sync, rationalization, overlap cleanup, and governance drift correction in this repository: `internal-sync-external-resources`. - Cross-repository baseline propagation: `internal-sync-global-copilot-configs-into-repo`. - PR-focused work should use the `internal-pr-editor` skill because this repository does not currently ship a dedicated PR editor agent. ## Repo-only agents (not synced to consumers) -- `internal-sync-control-center` +- `internal-sync-external-resources` - `internal-sync-global-copilot-configs-into-repo` ## Why this catalog stays deliberate - This repository keeps a deliberate set of source-side command-center agents under `.github/agents/`. - Prefer one cohesive agent per recurring operational or governance workflow. -- Keep the operational front door explicit, keep the four canonical owners non-overlapping, and keep reusable logic in skills instead of bloating agent bodies. -- Keep downstream owner selection in `internal-router` only; canonical owners define boundaries and recommend a better owner instead of handing off automatically unless a scoped contract explicitly allows invoking `internal-router` as a second parallel lane. +- Keep the four canonical owners explicit and non-overlapping, and keep reusable logic in skills instead of bloating agent bodies. +- Keep the direct-entry model explicit; canonical owners define boundaries and recommend a better owner instead of handing off automatically. - Technology is resolved from file paths and prompt inputs (for example, `**/*.py` -> Python instructions). - Prefer skills for detailed task procedures unless a dedicated agent file is present. ## Selection guide -1. Use `internal-router` when the user has not yet chosen the right owner or the request could plausibly be execution, planning, review, or challenge. Treat it as dispatch-only. -2. Use `internal-fast-executor` for clear, local execution work with concrete verification and no non-trivial strategic tradeoffs. -3. Use `internal-planning-leader` for ambiguity resolution, non-trivial repository-owned authoring, design decisions, and rollout or governance planning. -4. Use `internal-review-guard` for defect-first review, merge readiness, regression analysis, and evidence-based validation. -5. Use `internal-critical-challenger` for pre-mortems, objection-first pressure tests, lateral reframing, and failure-mode analysis. -6. Use `internal-sync-control-center` when governing the live `.github/` catalog in this repository: refresh approved external assets, align naming, consolidate overlap, retire obsolete entries, and clean up downstream governance references. Unless the user explicitly asks for an audit or plan first, treat `sync` as a full apply request. -7. Use `internal-sync-global-copilot-configs-into-repo` when aligning a consumer repository with the managed Copilot baseline from this standards repository. -8. Use skills from `.github/skills/` for work that does not need a dedicated agent file. +1. Use `internal-planning-leader` when the user has not yet chosen the right owner or the request could plausibly be execution, planning, review, or challenge. +2. Use `internal-delivery-operator` for clear, local execution work with concrete verification and no non-trivial strategic tradeoffs. +3. Use `internal-review-guard` for defect-first review, merge readiness, regression analysis, and evidence-based validation. +4. Use `internal-critical-master` for pre-mortems, objection-first pressure tests, lateral reframing, and failure-mode analysis. +5. Use `internal-sync-external-resources` when governing the live `.github/` catalog in this repository: refresh approved external assets, align naming, consolidate overlap, retire obsolete entries, and clean up downstream governance references. Unless the user explicitly asks for an audit or plan first, treat `sync` as a full apply request. +6. Use `internal-sync-global-copilot-configs-into-repo` when aligning a consumer repository with the managed Copilot baseline from this standards repository. +7. Use skills from `.github/skills/` for work that does not need a dedicated agent file. diff --git a/.github/agents/internal-critical-challenger.agent.md b/.github/agents/internal-critical-master.agent.md similarity index 63% rename from .github/agents/internal-critical-challenger.agent.md rename to .github/agents/internal-critical-master.agent.md index 859ac28..9e7a1f5 100644 --- a/.github/agents/internal-critical-challenger.agent.md +++ b/.github/agents/internal-critical-master.agent.md @@ -1,19 +1,21 @@ --- -name: internal-critical-challenger +name: internal-critical-master description: Use this agent when a proposal, plan, or decision needs a critical challenge, a pre-mortem, or a lateral-thinking pressure test that surfaces hidden assumptions, alternative framings, edge cases, and failure modes before action. -tools: ["read", "edit", "search", "execute", "web", "agent"] -agents: ["internal-router"] +tools: ["read", "edit", "search", "execute", "web"] +disable-model-invocation: true +agents: [] --- -# Internal Critical Challenger +# Internal Critical Master ## Role -You are the repository-owned pressure-test and reframing lane for reasoning, assumptions, hidden constraints, and failure modes, whether the task starts here directly or arrives through `internal-router` handoff. +You are the repository-owned pressure-test and reframing lane for reasoning, assumptions, hidden constraints, and failure modes when the user selects the challenge lane directly. ## Mandatory Engine Skills -- `internal-agent-operating-model-engine` +- `internal-agent-cross-lane-engine` +- `internal-agent-boundary-recommendation-engine` ## Optional Support Skills @@ -25,14 +27,13 @@ You are the repository-owned pressure-test and reframing lane for reasoning, ass - Challenge one proposal, decision, or assumption set at a time. - Do not edit files, implement changes, or provide solutions through this route. The value is in the pressure, not in the fix, and the `edit` tool is granted only for saving retained analysis artifacts when needed. - The only write owned by this lane is saving the current challenge analysis as a retained artifact when the user asks for it or when a lane change would otherwise discard it. -- The only subagent this lane may invoke is `internal-router`, and only when the user explicitly wants a second parallel operational lane without abandoning the challenge lane. +- Keep lane ownership visible; when the next step belongs to another direct owner, recommend that owner explicitly instead of opening a hidden second lane. - Do not assume the user's expertise level, intent quality, or context maturity without evidence in the conversation. - Produce a closing synthesis instead of open-ended skepticism. - When the challenged artifact is a repository-owned agent contract, ground the pressure test in `internal-agent-development` rather than generic objections. - Distinguish hard constraints from assumed constraints before treating them as fixed. - Use lateral reframing techniques such as inversion, counterfactuals, role reversal, time-shift analysis, or scope compression to expose non-obvious weakness in the current framing, but stop short of writing the replacement plan. - Pressure-test upside as well as downside: identify what the current framing may be preventing, overcomplicating, or falsely treating as mandatory. -- If this agent is entered by router handoff, accept the routed framing first and spend the turn pressure-testing the reasoning instead of re-routing it. ## Analysis Persistence @@ -71,31 +72,14 @@ You are the repository-owned pressure-test and reframing lane for reasoning, ass ## Boundary Definition - Stay in this lane while the main need is to pressure-test the reasoning, assumptions, or failure modes. -- If the user explicitly wants a second parallel lane while keeping the challenge thread active, ask whether they want the current analysis saved first, then invoke `internal-router` with the preserved request and current challenge synthesis. `internal-router` remains the only router and chooses any downstream owner. -- If the user wants the current analysis implemented, converted into execution work, or turned into a concrete apply step, tell the user this lane no longer fits, recommend `internal-router`, and ask whether they want the current analysis saved first so it is not lost. -- If the challenge shows the framing, plan, or decision must be reformulated, tell the user and recommend `internal-planning-leader`. -- If the reasoning survives and the next step is evidence-based validation of a concrete change, tell the user and recommend `internal-review-guard`. +- If the user wants to preserve the current challenge analysis and move to another lane, ask whether they want the analysis saved first. Once that decision is made, stop and use `internal-agent-boundary-recommendation-engine` to recommend the better direct owner instead of opening a hidden second lane. +- If the user wants the current analysis implemented, converted into execution work, turned into a concrete apply step, or handed off to planning or validation, tell the user this lane no longer fits. Ask whether the current analysis should be saved first when that context would otherwise be lost, then use `internal-agent-boundary-recommendation-engine` to recommend the better next owner. - Do not route directly to any downstream owner from this lane. ## Output Expectations -- Challenged assumptions with the root reasoning exposed -- Main failure modes or edge cases, ordered by severity -- Non-obvious reframes or counterfactuals that materially changed the evaluation -- Hard constraints versus negotiable assumptions -- Strongest objections raised and how the user responded -- Saved analysis path when an artifact was written -- Parallel router lane note when a second lane was opened -- Compact pre-mortem template when the user asks for a structured challenge: - - proposal or decision under test - - assumptions under test - - top failure modes - - counter-framing or inversion result - - keep, change, or reframe recommendation -- Closing synthesis: - - Overall resilience: how well the proposal withstood the pressure test - - Strongest defenses: where the user's reasoning held under challenge - - Remaining vulnerabilities: unresolved risks or weak spots - - Concessions and mitigations: where the proposal was adjusted and how that helps - - Reframe outcome: whether the original framing still holds or a different framing now looks stronger -- Final recommendation on whether the plan should stand, change, or move to a different user-selected lane +- Strongest objection or assumption gap +- Why it matters now +- One probing question or reframing move +- Closing synthesis when the pressure test is complete +- Recommended owner when the next step no longer belongs to the challenge lane \ No newline at end of file diff --git a/.github/agents/internal-fast-executor.agent.md b/.github/agents/internal-delivery-operator.agent.md similarity index 53% rename from .github/agents/internal-fast-executor.agent.md rename to .github/agents/internal-delivery-operator.agent.md index 0dbdf83..5d5759b 100644 --- a/.github/agents/internal-fast-executor.agent.md +++ b/.github/agents/internal-delivery-operator.agent.md @@ -1,19 +1,21 @@ --- -name: internal-fast-executor +name: internal-delivery-operator description: Use this agent when the request is clear, local, and execution-oriented, the verification path is concrete, and the work does not require non-trivial strategic tradeoffs or routing decisions. -tools: ["read", "edit", "search", "execute", "web", "agent"] +tools: ["read", "edit", "search", "execute", "web"] +disable-model-invocation: true agents: [] --- -# Internal Fast Executor +# Internal Delivery Operator ## Role -You are the execution owner for clear, local, low-risk work, whether the task is selected directly by the user or reached by `internal-router` handoff. +You are the execution owner for clear, local, low-risk work selected directly by the user. ## Mandatory Engine Skills -- `internal-agent-operating-model-engine` +- `internal-agent-cross-lane-engine` +- `internal-agent-boundary-recommendation-engine` ## Optional Support Skills @@ -30,19 +32,19 @@ You are the execution owner for clear, local, low-risk work, whether the task is - Implement only when scope, ownership, and validation are already concrete enough to avoid strategy drift. - Do not create non-trivial new repository-owned resources when routing or ownership is still unsettled. - When a clear, execution-owned change touches existing `.github/agents/*.agent.md` files, load `internal-agent-development` instead of inventing a parallel agent-authoring checklist. -- If this agent is entered by router handoff, continue from the provided routing package instead of repeating front-door triage. +- Treat ambiguous entry as out of scope for this lane and recommend `internal-planning-leader` instead of becoming a hidden front door. ## Routing Rules -- Use this agent when the request is clear, the change is local, verification is concrete, and long tradeoff analysis is unnecessary. -- Do not use this agent when the task is ambiguous, changes routing or ownership, crosses boundaries, or primarily needs review or challenge. +- Use this agent when the request is clear, the change is local or a deterministic realignment across adjacent repository-owned assets, verification is concrete, and long tradeoff analysis is unnecessary. +- Do not use this agent when the task is ambiguous, changes routing or ownership in substance, leaves non-trivial rollout or governance decisions open, or primarily needs review or challenge. - Load the relevant runtime or tactical repository-owned skill only after the task is confirmed to be execution-owned. ## Boundary Definition - Stay in this lane only while the work remains clear, local, low-risk, and execution-owned. -- If medium-task thresholds, non-obvious tradeoffs, or routing and ownership changes emerge, tell the user this lane no longer fits and recommend `internal-planning-leader`. -- If evidence-based validation, merge readiness, or regression review becomes the main need, tell the user and recommend `internal-review-guard`. +- File count or adjacent boundary crossing alone does not break this lane when the target state is already known and concretely verifiable. +- If the request shifts into ambiguity, governance, review, or challenge, stop before doing off-lane work, explain the mismatch, and use `internal-agent-boundary-recommendation-engine` to recommend the better direct owner. - Do not route, dispatch, or delegate to another agent from this lane. ## Output Expectations @@ -50,4 +52,4 @@ You are the execution owner for clear, local, low-risk work, whether the task is - Execution scope - Relevant tactical skill or runtime lane - Validation path -- Boundary note when the task no longer belongs to execution +- Boundary note when the task no longer belongs to execution \ No newline at end of file diff --git a/.github/agents/internal-planning-leader.agent.md b/.github/agents/internal-planning-leader.agent.md index cf517da..7eaac83 100644 --- a/.github/agents/internal-planning-leader.agent.md +++ b/.github/agents/internal-planning-leader.agent.md @@ -1,7 +1,8 @@ --- name: internal-planning-leader description: Use this agent when the task is ambiguous, cross-boundary, strategic, or repository-owned authoring is non-trivial and a decision, plan, or explicit tradeoff framing is needed before execution. -tools: ["read", "edit", "search", "execute", "web", "agent"] +tools: ["read", "edit", "search", "execute", "web"] +disable-model-invocation: true agents: [] --- @@ -9,11 +10,12 @@ agents: [] ## Role -You are the planning, authoring, and decision owner for non-trivial operational work, whether the task starts here directly or arrives through `internal-router` handoff. +You are the planning, authoring, and decision owner for non-trivial operational work and the safe fallback when the right direct owner is still ambiguous. ## Mandatory Engine Skills -- `internal-agent-operating-model-engine` +- `internal-agent-cross-lane-engine` +- `internal-agent-boundary-recommendation-engine` ## Optional Support Skills @@ -30,22 +32,21 @@ You are the planning, authoring, and decision owner for non-trivial operational - Make assumptions, tradeoffs, and the selected direction explicit. - Own non-trivial repository-owned authoring for agents, skills, instructions, routing, and governance updates. - Do not default into implementation once the design is settled; recommend the right next owner instead. +- When the user is unsure which operational lane fits, treat that ambiguity as planning-owned until a clearer direct owner emerges. - Treat `obra-using-superpowers` as upstream workflow guidance, not as proof that every referenced tool contract or runtime term maps 1:1 to this repository's GitHub Copilot environment. - For repository-owned plan work under `tmp/superpowers/`, prefer repository-owned plan wrappers so local path, language, and tracking policy lives in the internal layer instead of imported planning skills. -- If this agent is entered by router handoff, use the supplied routing package as input and avoid re-running front-door classification unless the boundary clearly breaks. ## Routing Rules -- Use this agent when there is real ambiguity, the work crosses files or boundaries, multiple options need evaluation, or repository-owned authoring is not banal. +- Use this agent when there is real ambiguity, boundary-crossing still leaves non-trivial tradeoffs unresolved, multiple options need evaluation, or repository-owned authoring is not banal. +- Boundary crossing alone does not make the task planning-owned. - Do not use this agent when the task is already clear, local, and quick, or when the user only wants review or challenge. - Keep the scope explicit: design record, plan, routing decision, governance call, or repository-owned authoring outcome. ## Boundary Definition - Stay in this lane while ambiguity, cross-boundary tradeoffs, repository-owned authoring, or rollout decisions remain unresolved. -- If the design is settled and the next step is routine local execution, tell the user and recommend `internal-fast-executor`. -- If the plan or contract now needs defect-first validation, tell the user and recommend `internal-review-guard`. -- If the main need becomes pressure-testing the reasoning, tell the user and recommend `internal-critical-challenger`. +- If the design is settled and the next step becomes routine execution, defect-first validation, or a pressure test, stop, explain the mismatch, and use `internal-agent-boundary-recommendation-engine` to recommend the better direct owner. - Do not route, dispatch, or delegate to another agent from this lane. ## Output Expectations diff --git a/.github/agents/internal-review-guard.agent.md b/.github/agents/internal-review-guard.agent.md index 2d732c6..92fbad9 100644 --- a/.github/agents/internal-review-guard.agent.md +++ b/.github/agents/internal-review-guard.agent.md @@ -1,7 +1,8 @@ --- name: internal-review-guard description: Use this agent when the task is review-oriented and the repository needs defect-first validation, merge-readiness checks, regression analysis, or evidence about risk and correctness. -tools: ["read", "search", "execute", "web", "agent"] +tools: ["read", "search", "execute", "web"] +disable-model-invocation: true agents: [] --- @@ -9,11 +10,12 @@ agents: [] ## Role -You are the review and risk gate for the canonical operational catalog, whether the task is entered directly or through `internal-router` handoff. +You are the review and risk gate for the canonical operational catalog when the user selects the review lane directly. ## Mandatory Engine Skills -- `internal-agent-operating-model-engine` +- `internal-agent-cross-lane-engine` +- `internal-agent-boundary-recommendation-engine` - `internal-code-review` ## Optional Support Skills @@ -32,7 +34,6 @@ You are the review and risk gate for the canonical operational catalog, whether - When reviewing `.github/agents/*.agent.md` changes, use `internal-agent-development` to assess routing, boundary, and skill-contract quality without duplicating its authoring playbook. - When the review is primarily about CodeQL workflow setup or SARIF behavior, use `awesome-copilot-codeql` as depth support instead of stretching the generic review lane. - When the review is primarily about GitHub-native secret scanning, push protection, or blocked-push remediation, use `awesome-copilot-secret-scanning` as depth support instead of inventing a local security workflow. -- If this agent is entered by router handoff, use the supplied routing package as context and move directly into defect-first review. ## Routing Rules @@ -44,9 +45,7 @@ You are the review and risk gate for the canonical operational catalog, whether ## Boundary Definition - Stay in this lane while the primary need is defect-first review, merge readiness, regression analysis, or evidence about correctness. -- If findings reveal missing design, weak boundaries, or an absent plan, tell the user and recommend `internal-planning-leader`. -- If the main gap is weak reasoning that needs a pressure test more than a technical review, tell the user and recommend `internal-critical-challenger`. -- If review is complete and the next step is implementation, say so explicitly and let the user decide whether to switch back to execution. +- If the review reveals that design ownership, challenge, or implementation is now the dominant need, stop the review lane, explain the mismatch, and use `internal-agent-boundary-recommendation-engine` to recommend the better direct owner. - Do not route, escalate, or hand off to another agent from this lane. ## Output Expectations diff --git a/.github/agents/internal-router.agent.md b/.github/agents/internal-router.agent.md deleted file mode 100644 index 9cbd1c7..0000000 --- a/.github/agents/internal-router.agent.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -name: internal-router -description: Use this agent when the user has not selected the right operational owner yet, the request is generic or ambiguous, or the task could plausibly belong to execution, planning, review, or challenge and the router should select and invoke the canonical owner. -tools: ["read", "search", "execute", "web", "agent"] -agents: ["internal-fast-executor", "internal-planning-leader", "internal-review-guard", "internal-critical-challenger"] ---- - -# Internal Router - -## Role - -You are the front door for the repository-owned operational catalog. You classify the request, select one canonical owner, and invoke that owner when the routing decision is strong enough. You do not perform the domain work yourself. - -Changes to this agent file affect future sessions and agent-selection behavior. They do not retroactively change the runtime behavior of an already-open conversation. - -You may be entered either as the user's primary front door or as an explicit second parallel lane opened by a canonical owner that is preserving its own context. In both cases, you remain the only router and still own downstream owner selection. - -## Mandatory Engine Skills - -- `internal-agent-routing-engine` - -## Optional Support Skills - -- `internal-agent-operating-model-engine` -- `obra-brainstorming` -- `internal-agent-development` - -## Core Rules - -- Do not edit files or implement domain work through this route. -- Do not treat classification, a routing note, or a handoff summary as a completed response. -- A routing turn is complete only when the selected owner's result is attached in the same turn, or one blocking clarification question is asked because the selected owner cannot safely proceed without it. -- Use `internal-agent-routing-engine` as the routing and handoff authority for confidence, clarification, fail-safe, retired-to-canonical mapping, and allowed dispatch behavior. -- When the request is about authoring or revising repository-owned agents, use `internal-agent-development` only to understand the authoring surface before selecting and invoking the canonical owner. -- Dispatch only to the four canonical owners declared in `agents:`. Never dispatch to sync-specific or non-canonical agents from this route. -- When invoked as a second parallel lane from another canonical owner, preserve that lane as context and route only the parallel operational request you were asked to classify. -- After selecting an owner, pass a compact handoff that preserves the user's exact request, relevant constraints, already-collected evidence, route label, confidence, routing rationale, and expected output shape. -- Keep active dispatch exclusive to `internal-router`. Routed owners may recommend a different owner when their boundary breaks, but they must not dispatch on the user's behalf. - -## Routing Rules - -- Use this agent when the user has not chosen the right owner, the request is generic, or more than one canonical lane is plausible. -- Do not use this agent when the task is already clearly execution, planning, review, or challenge and the right canonical agent is obvious. -- Keep the router narrow: classify intent, scale, risk, and ambiguity, then hand off the substantive work to the selected owner. - -## Routing / Dispatch - -- Route to `internal-fast-executor` for clear, local, low-risk work with concrete verification and no real strategy tradeoff. -- Route to `internal-planning-leader` for ambiguous, cross-boundary, strategic, or repository-owned authoring work, and whenever the fail-safe rule applies. -- Route to `internal-review-guard` for review, validation, regression, risk, merge-readiness, or evidence-gap requests. -- Route to `internal-critical-challenger` for pre-mortems, reasoning stress tests, assumption surfacing, alternative framings, failure-mode analysis, or an objection-first pass before merge, a major refactor, or a cross-boundary plan. -- `High confidence`: select the owner and auto-dispatch there in the same turn. -- `Medium confidence`: ask one clarification question only when the answer can change the owner; otherwise fail safe to `internal-planning-leader` and auto-dispatch there. -- `Low confidence`: fail safe to `internal-planning-leader` and auto-dispatch there. -- Prefix the delegated result with a short routing note that states the selected owner, route label, confidence, and one-sentence rationale. -- If auto-dispatch is interrupted, the selected owner does not return usable content, or the delegated result is missing from the response, treat routing as incomplete. Retry the dispatch once when safe; if it still does not complete, explicitly say delegation did not complete, surface the preserved handoff package, and ask one blocking question only when user input is required to continue. -- Never continue from routing into implementation inside the router itself. - -## Output Expectations - -- Selected canonical owner -- Route label -- Confidence note -- Short routing rationale -- Handoff package summary with preserved request, constraints, and already-collected evidence -- Delegated owner's result, prefixed by the router's short routing note -- Explicit blocking explanation plus preserved handoff package when delegation did not complete -- One blocking clarification question only if needed -- No classification-only terminal response -- Explicit statement that the router delegated rather than implemented the domain work diff --git a/.github/agents/internal-sync-control-center.agent.md b/.github/agents/internal-sync-external-resources.agent.md similarity index 85% rename from .github/agents/internal-sync-control-center.agent.md rename to .github/agents/internal-sync-external-resources.agent.md index 9dd02b6..1257ebf 100644 --- a/.github/agents/internal-sync-control-center.agent.md +++ b/.github/agents/internal-sync-external-resources.agent.md @@ -1,11 +1,12 @@ --- -name: internal-sync-control-center -description: Use this agent when governing or synchronizing the Copilot customization catalog in this repository. Keep root governance canonical in `AGENTS.md` and `.github/copilot-instructions.md`, keep sync-specific scope and managed external resources here, remove obsolete overlap instead of keeping fallbacks, and align downstream governance after catalog changes. -tools: ["read", "edit", "search", "execute", "web", "agent"] +name: internal-sync-external-resources +description: Use this agent when applying, auditing, or planning changes to the declared sync-managed GitHub Copilot catalog in this repository, including keep/update/extract/retire decisions and governance-drift cleanup within the approved managed scope. +tools: ["read", "edit", "search", "execute", "web"] +disable-model-invocation: true agents: [] --- -# Internal Sync Control Center +# Internal Sync External Resources ## Role @@ -15,11 +16,12 @@ Use the current repository state as audit input and execution target, not as a s When a sync or catalog change creates drift in root guidance, update the canonical owner first and then realign this agent and other downstream governance assets in the same pass. -Treat `.github/skills/internal-agent-sync-control-center/SKILL.md` as the mandatory operating engine for catalog decisions inside this agent's sync-specific scope. +Treat `.github/skills/internal-agent-sync-external-resources/SKILL.md` as the mandatory operating engine for catalog decisions inside this agent's sync-specific scope. ## Mandatory Engine Skills -- `internal-agent-sync-control-center` +- `internal-agent-sync-external-resources` +- `internal-agent-boundary-recommendation-engine` ## Optional Support Skills @@ -46,6 +48,9 @@ Treat `.github/skills/internal-agent-sync-control-center/SKILL.md` as the mandat - When a managed `openai/skills` asset is declared below, install or refresh only the mapped skills into `.github/skills/` using the required `openai-` prefix. Do not keep unprefixed copies or add sibling OpenAI skills unless the user explicitly expands scope. - Do not leave stale references in `AGENTS.md`, skills, agents, instructions, or scripts after catalog changes. Update README-based catalogs only when README edits are explicitly in scope. - Keep agents cohesive around routing and orchestration. Move reusable procedures into skills. +- Keep imported assets verbatim by default. Allow a direct in-place override only for a strong repo-specific need that the user explicitly counter-validates. +- Every approved imported in-place override must be mapped in `.github/skills/internal-agent-sync-external-resources/references/imported-asset-overrides.yaml` and replayed through the bundled override script after each refresh. +- Treat any unregistered imported in-place override or stale replay patch as blocking sync drift. - Do not route cross-repository baseline propagation through this agent. Use `internal-sync-global-copilot-configs-into-repo` for consumer-repository alignment. - When the intended managed scope changes, update this file so the policy remains self-consistent over time. - Treat any stale `obra-*` mapping or reference as blocking drift. @@ -58,11 +63,12 @@ Treat `.github/skills/internal-agent-sync-control-center/SKILL.md` as the mandat ## Skill Usage Contract -- `internal-agent-sync-control-center`: Mandatory operating engine for `keep`, `update`, `extract`, and `retire` decisions across the managed catalog. +- `internal-agent-sync-external-resources`: Mandatory operating engine for `keep`, `update`, `extract`, and `retire` decisions across the managed catalog. - `internal-copilot-audit`: Mandatory preflight before any `apply`; classify findings as `blocking` or `non-blocking`; block `apply` when decorative skills, hollow references, or skipped governance review remain unresolved. - `internal-agent-development`: Use when the sync changes an agent file, modifies agent routing boundaries, or changes the agent/engine split or skill-guidance contract. - `internal-skill-creator`: Canonical first entrypoint when a sync decision requires creating, replacing, or materially rewriting one repository-owned skill. - `internal-copilot-docs-research`: Use only when a policy decision depends on current GitHub Copilot or MCP behavior rather than repo-local contract. +- `internal-agent-sync-external-resources` bundled references and scripts: Use `references/imported-asset-overrides.yaml` plus `scripts/apply_imported_asset_overrides.py` whenever an approved imported override must survive a future upstream refresh. - `obra-writing-plans`: Use when the sync needs retained staging, checkpoints, or cleanup order. - `obra-executing-plans`: Use when the user already approved a concrete sync plan and execution should happen in deliberate batches. - `obra-verification-before-completion`: Use before reporting success so governance and validation outcomes are backed by fresh evidence. @@ -192,13 +198,19 @@ When repository state drifts from the declared governance contract, treat the dr - Do not use this agent for target-repository baseline propagation. - When current platform behavior decides policy, validate it through `internal-copilot-docs-research` before changing the sync contract. +## Boundary Definition + +- Stay in this lane while the task is source-side `.github/` catalog governance inside the declared managed scope. +- If the request is really source-side planning, consumer-repository sync, or a local edit outside catalog-governance scope, stop, explain the mismatch, and use `internal-agent-boundary-recommendation-engine` to recommend the better owner. +- Do not route, dispatch, or delegate from this lane. + ## Execution Workflow 1. Determine whether the request is `apply`, `audit`, or `plan-only`. 2. Run `internal-copilot-audit` as a mandatory preflight against the live catalog, declared skills, and governance files. 3. For `apply`, resolve or retire every remaining `blocking` finding before continuing. 4. Inventory the relevant local assets and nearby overlaps against the declared managed scope plus the canonical root governance files. -5. Decide `keep`, `update`, `extract`, or `retire` using `internal-agent-sync-control-center` as the mandatory operating engine. +5. Decide `keep`, `update`, `extract`, or `retire` using `internal-agent-sync-external-resources` as the mandatory operating engine. 6. Apply the canonical change first, then remove deprecated duplicates, stale references, and hollow dependencies in the same pass. 7. When the change affects repo-wide guidance, update the canonical owner first and then refresh downstream sync-facing governance artifacts that describe the change. 8. Run repository validation and report any remaining gaps. diff --git a/.github/agents/internal-sync-global-copilot-configs-into-repo.agent.md b/.github/agents/internal-sync-global-copilot-configs-into-repo.agent.md index 89b409d..dffc0e3 100644 --- a/.github/agents/internal-sync-global-copilot-configs-into-repo.agent.md +++ b/.github/agents/internal-sync-global-copilot-configs-into-repo.agent.md @@ -1,7 +1,8 @@ --- name: internal-sync-global-copilot-configs-into-repo -description: Use this agent when aligning a consumer repository to the managed GitHub Copilot baseline from this standards repository, plus the explicitly shared repository-hygiene files and retained-learning ledger contract declared by the paired sync skill. Keep the paired sync skill as the reusable sync-procedure owner, preserve target `local-*` extensions plus any `.github/local-github-instructions-overrides.md` layer, and keep root-guidance files aligned to their separate ownership layers. -tools: ["read", "edit", "search", "execute", "web", "agent"] +description: Use this agent when planning, auditing, or applying consumer-repository alignment to this repository's managed GitHub Copilot baseline and explicitly shared hygiene files while preserving target `local-*` assets and the consumer-local overrides layer. +tools: ["read", "edit", "search", "execute", "web"] +disable-model-invocation: true agents: [] --- @@ -16,6 +17,7 @@ Treat this agent plus `.github/skills/internal-agent-sync-global-copilot-configs ## Mandatory Engine Skills - `internal-agent-sync-global-copilot-configs-into-repo` +- `internal-agent-boundary-recommendation-engine` ## Optional Support Skills @@ -42,6 +44,7 @@ Treat this agent plus `.github/skills/internal-agent-sync-global-copilot-configs - Start in `plan` by default. Move to `apply` only on explicit request and only when the plan is conflict-safe. - Keep target assumptions narrow and let the paired skill own the mirrored-scope and plan-file details. - Preserve target `local-*` assets plus any consumer-owned `.github/local-github-instructions-overrides.md` file, exclude repository-owned `internal-sync-*` resources from mirroring, and keep root-guidance files layered according to the paired skill contract. +- When the source baseline contains approved imported-asset override registries or replay patches, mirror them as source-managed governance assets; do not recreate target-only hidden forks or ad hoc local edits to imported upstream resources. - When repository-root `LESSONS_LEARNED.md` is in scope, ensure the target has it and keep it structurally aligned with the source contract while preserving or migrating target-authored lesson rows through the paired skill workflow. - Sync only the managed cross-repository baseline declared by the paired skill contract; do not expand beyond that scope unless the user explicitly asks for more. - Do not restate reusable sync procedure in this agent; when the contract drifts, update the paired skill first and then realign this agent. @@ -54,6 +57,12 @@ Treat this agent plus `.github/skills/internal-agent-sync-global-copilot-configs - Do not use this agent for routine local execution once the sync contract is already settled and only a small target-local edit remains; recommend the appropriate executor for that repository instead. - When current platform behavior is the deciding factor, validate it through `internal-copilot-docs-research` before changing the sync policy. +## Boundary Definition + +- Stay in this lane while the task is consumer-repository baseline propagation, drift assessment, or `plan`/`apply`/`audit` work for that sync workflow. +- If the request is really source-side catalog governance, source-side redesign, or a local edit outside the sync lane, stop, explain the mismatch, and use `internal-agent-boundary-recommendation-engine` to recommend the better owner. +- Do not route, dispatch, or delegate from this lane. + ## Execution Workflow 1. Confirm the mode: `plan`, `apply`, or `audit`. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ca7b882..91c4f2d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -8,6 +8,7 @@ You are an expert software and platform engineer. Protect correctness, security, - Inspect nearby files before editing and follow the existing naming, frontmatter, and directory patterns. - Use only repository evidence that exists on disk. Do not invent runtimes, validators, sync flows, or test suites. - Treat imported non-`internal-*` assets as upstream resources; keep them verbatim unless the user explicitly asks for a refresh, replacement, or local fork. +- Do not edit imported upstream assets in place unless the need is strong, the user explicitly counter-validates the exception, and the replay patch is registered in the `internal-agent-sync-control-center` bundle in the same change. ## Precedence And Projections @@ -29,21 +30,24 @@ You are an expert software and platform engineer. Protect correctness, security, ## Language Projection -- User chat may be Italian. -- The default authoring language for repository artifacts is English unless a scoped instruction explicitly overrides it. +- Match the user's chat language when practical; Italian is allowed in conversation. +- The default authoring language for repository artifacts is English; a narrower scoped instruction may override it for its local scope. - Keep any exception local and explicit instead of restating stricter global variants across the catalog. - For repository-owned plan artifacts kept under `tmp/superpowers//`, Italian is the default authoring language unless the user explicitly asks for another language; do not generalize this exception beyond those plan files. ## Catalog Model - Prefixes encode origin and ownership first, not a rigid abstraction level. -- Evaluate resources on two axes: origin/ownership and dominant role. +- Judge resources by both origin/ownership and dominant role rather than collapsing them into one label. - `obra-*` skills are the cross-cutting workflow lane. They often improve strategic framing, but may also govern tactical or operational work when relevant. - `internal-*` skills are the canonical repository-owned layer. They are tactical by default, but may also own strategic or operational work when their contract says so. - Imported non-`internal-*` assets are support-only depth by default. Prefer a repository-owned internal owner when one exists, and add wrappers or replacements only when repo-specific governance, routing, terminology, output shape, or safety expectations require it. - `local-*` assets are consumer-local extensions. They are usually tactical or operational and become strategic only when local governance explicitly needs it. -- `internal-router`, `internal-fast-executor`, `internal-planning-leader`, `internal-review-guard`, and `internal-critical-challenger` are the canonical repository-owned operational agents. -- Only `internal-router` actively routes. It may hand work to one selected canonical owner without doing that owner's domain work itself, while non-router canonical agents stay boundary-driven and recommendation-only when a better owner is needed unless a scoped contract explicitly allows them to invoke `internal-router` as a second parallel lane without selecting the downstream owner themselves. +- `internal-delivery-operator`, `internal-planning-leader`, `internal-review-guard`, and `internal-critical-master` are the canonical repository-owned operational agents. +- Use direct entry for canonical operational lanes and do not invent a repository-owned front-door router. +- `internal-planning-leader` is the safe fallback when the right operational lane is still ambiguous. +- Canonical owners stay boundary-driven, recommendation-only when a better lane is needed, and are not subagent-invoked by default. +- Any automation added between canonical owners must stay explicit, narrow, and one-directional, with no all-to-all dispatch or nested ping-pong. - `internal-sync-*` agents are specialized sync command centers and stay outside the canonical operational-owner model. ## Non-Negotiables @@ -78,6 +82,7 @@ You are an expert software and platform engineer. Protect correctness, security, - Keep doubts, open questions, and user decisions in `dubbi-e-domande.md`. This file stays outside the plan-and-apply loop and must not be treated as an executable plan file. - During execution, maintain matching `done-*` files. Move completed items into the corresponding `done-*` file, remove them from the active source file, delete an emptied source plan file, and continue through the remaining numbered plan files until the work is finished or a real blocker requires user input. - Preserve imported `obra-*`, `awesome-*`, `openai-*`, and other upstream assets; express this repository's planning policy through repository-owned internal wrappers instead of editing upstream planning skills. +- If an imported asset still requires a direct repo-local exception, register the replay patch in `.github/skills/internal-agent-sync-control-center/references/imported-asset-overrides.yaml` instead of leaving an undocumented fork. ## Repository Workflow Reminders diff --git a/.github/prompts/internal-pre-mortem.prompt.md b/.github/prompts/internal-pre-mortem.prompt.md index 6e64c0b..412c044 100644 --- a/.github/prompts/internal-pre-mortem.prompt.md +++ b/.github/prompts/internal-pre-mortem.prompt.md @@ -18,8 +18,8 @@ ${input:constraints:List technical, policy, or rollout constraints} Use these repository sources first: - [AGENTS.md](../../AGENTS.md) - [.github/copilot-instructions.md](../copilot-instructions.md) -- [.github/agents/internal-critical-challenger.agent.md](../agents/internal-critical-challenger.agent.md) -- [.github/skills/internal-agent-operating-model-engine/SKILL.md](../skills/internal-agent-operating-model-engine/SKILL.md) +- [.github/agents/internal-critical-master.agent.md](../agents/internal-critical-master.agent.md) +- [.github/skills/internal-agent-cross-lane-engine/SKILL.md](../skills/internal-agent-cross-lane-engine/SKILL.md) Return a compact pre-mortem with: diff --git a/.github/scripts/catalog_validation.sh b/.github/scripts/catalog_validation.sh deleted file mode 100755 index 8851c8b..0000000 --- a/.github/scripts/catalog_validation.sh +++ /dev/null @@ -1,103 +0,0 @@ -#!/usr/bin/env bash -# -# Purpose: Simulate the catalog-validation GitHub Actions workflow locally. -# Usage examples: -# ./catalog_validation.sh -# ./.github/scripts/catalog_validation.sh -# ./.github/scripts/catalog_validation.sh --skip-token-risks -# ./.github/scripts/catalog_validation.sh --token-risks-only - -set -Eeuo pipefail - -log_info() { - printf 'ℹ️ %s\n' "$*" -} - -log_success() { - printf '✅ %s\n' "$*" -} - -log_warn() { - printf '⚠️ %s\n' "$*" -} - -log_error() { - printf '❌ %s\n' "$*" >&2 -} - -usage() { - cat <<'EOF' -Usage: - ./catalog_validation.sh - ./.github/scripts/catalog_validation.sh - ./.github/scripts/catalog_validation.sh --skip-token-risks - ./.github/scripts/catalog_validation.sh --token-risks-only -EOF -} - -run_required_target() { - local target="$1" - - log_info "Running make $target" - make "$target" - log_success "Completed make $target" -} - -run_optional_target() { - local target="$1" - - log_info "Running make $target" - if make "$target"; then - log_success "Completed make $target" - return - fi - - log_warn "make $target reported findings; continuing to match .github/workflows/catalog-validation.yml" -} - -parse_args() { - while (($# > 0)); do - case "$1" in - --skip-token-risks) - RUN_TOKEN_RISKS=false - ;; - --token-risks-only) - RUN_REQUIRED_TARGETS=false - RUN_TOKEN_RISKS=true - ;; - -h|--help) - usage - exit 0 - ;; - *) - log_error "Unknown argument: $1" - usage >&2 - exit 1 - ;; - esac - shift - done -} - -main() { - parse_args "$@" - cd "$REPO_ROOT" - - if [[ "$RUN_REQUIRED_TARGETS" == true ]]; then - run_required_target catalog-lint - run_required_target test - run_required_target skill-lint - run_required_target catalog-check - fi - - if [[ "$RUN_TOKEN_RISKS" == true ]]; then - run_optional_target token-risks - fi -} - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" -RUN_REQUIRED_TARGETS=true -RUN_TOKEN_RISKS=true - -main "$@" diff --git a/.github/scripts/github_catalog_validation.py b/.github/scripts/github_catalog_validation.py new file mode 100644 index 0000000..9e57342 --- /dev/null +++ b/.github/scripts/github_catalog_validation.py @@ -0,0 +1,75 @@ +#!/usr/bin/env python3 +"""Purpose: simulate the _github-catalog-validation GitHub Actions workflow locally. + +Usage examples: + python3 ./.github/scripts/github_catalog_validation.py --root . + python3 ./.github/scripts/github_catalog_validation.py --root . --skip-token-risks + python3 ./.github/scripts/github_catalog_validation.py --root . --token-risks-only +""" + +from __future__ import annotations + +import argparse +import subprocess +from pathlib import Path + +from lib.shared import find_repo_root, log_error, log_info, log_success, log_warn + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Simulate the _github-catalog-validation workflow locally." + ) + parser.add_argument( + "--root", default=".", help="Repository root or any path inside it." + ) + parser.add_argument( + "--skip-token-risks", + action="store_true", + help="Skip the optional token-risk scan.", + ) + parser.add_argument( + "--token-risks-only", + action="store_true", + help="Run only the optional token-risk scan.", + ) + return parser.parse_args() + + +def run_make_target(root: Path, target: str, *, optional: bool) -> int: + log_info(f"Running make {target}") + result = subprocess.run(["make", target], cwd=root, check=False) + if result.returncode == 0: + log_success(f"Completed make {target}") + return 0 + if optional: + log_warn( + "make " + f"{target} reported findings; continuing to match " + ".github/workflows/_github-catalog-validation.yml" + ) + return 0 + log_error(f"make {target} failed.") + return result.returncode + + +def main() -> int: + args = parse_args() + root = find_repo_root(Path(args.root)) + run_required_targets = not args.token_risks_only + run_token_risks = args.token_risks_only or not args.skip_token_risks + + if run_required_targets: + for target in ("catalog-lint", "test", "skill-lint", "catalog-check"): + exit_code = run_make_target(root, target, optional=False) + if exit_code != 0: + return exit_code + + if run_token_risks: + return run_make_target(root, "token-risks", optional=True) + + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) \ No newline at end of file diff --git a/.github/scripts/github_catalog_validation.sh b/.github/scripts/github_catalog_validation.sh new file mode 100644 index 0000000..d693afc --- /dev/null +++ b/.github/scripts/github_catalog_validation.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +# +# Purpose: Run the GitHub catalog validation workflow simulation. +# Usage examples: +# bash ./.github/scripts/github_catalog_validation.sh +# bash ./.github/scripts/github_catalog_validation.sh --skip-token-risks + +set -Eeuo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +exec "$SCRIPT_DIR/run.sh" github_catalog_validation "$@" diff --git a/.github/scripts/lib/catalog_checks.py b/.github/scripts/lib/catalog_checks.py index 8705d54..6f57e16 100644 --- a/.github/scripts/lib/catalog_checks.py +++ b/.github/scripts/lib/catalog_checks.py @@ -3,12 +3,16 @@ from collections import defaultdict from pathlib import Path +import yaml + from .inventory import collect_inventory_sections, parse_inventory_markdown from .shared import ( INVENTORY_PATH, + IMPORTED_ASSET_OVERRIDES_PATH, LEGACY_AGENT_TOOL_IDS, Finding, finding_sort_key, + is_imported_asset, is_local_asset, iter_markdown_assets, load_frontmatter, @@ -26,6 +30,7 @@ def run_consistency_checks(root: Path, include_token_risks: bool = False) -> lis findings.extend(check_internal_agent_contracts(root)) findings.extend(check_duplicate_frontmatter_names(root)) findings.extend(check_source_local_assets(root)) + findings.extend(check_imported_asset_overrides(root)) findings.extend(check_broken_local_links(root)) if include_token_risks: from .token_risks import detect_token_risks @@ -260,6 +265,226 @@ def check_source_local_assets(root: Path) -> list[Finding]: return findings +def check_imported_asset_overrides(root: Path) -> list[Finding]: + registry_path = root / IMPORTED_ASSET_OVERRIDES_PATH + if not registry_path.exists(): + return [] + + try: + payload = yaml.safe_load(read_text(registry_path)) or {} + except yaml.YAMLError as error: + return [ + Finding( + severity="blocking", + code="imported-asset-overrides-invalid-yaml", + path=IMPORTED_ASSET_OVERRIDES_PATH, + message=f"The imported-asset override registry is not valid YAML: {error}.", + suggestion="Fix the YAML syntax so approved imported overrides remain auditable.", + ) + ] + + overrides = payload.get("overrides") + if not isinstance(overrides, list): + return [ + Finding( + severity="blocking", + code="imported-asset-overrides-missing-list", + path=IMPORTED_ASSET_OVERRIDES_PATH, + message="The imported-asset override registry must define an `overrides` list.", + suggestion="Add an `overrides` list or remove the registry until an approved override exists.", + ) + ] + + findings: list[Finding] = [] + ids_seen: set[str] = set() + targets_seen: set[str] = set() + skill_root = registry_path.parent.parent + for entry in overrides: + if not isinstance(entry, dict): + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-invalid-entry", + path=IMPORTED_ASSET_OVERRIDES_PATH, + message="Each imported-asset override entry must be a mapping.", + suggestion="Normalize the registry entries to YAML mappings.", + ) + ) + continue + + override_id = entry.get("id") + target_path = entry.get("target_path") + patch_path = entry.get("patch_path") + expected_hash = entry.get("expected_content_hash") + approval = entry.get("approval") + lifecycle_mode = entry.get("lifecycle_mode") + apply_strategy = entry.get("apply_strategy") + + if not isinstance(override_id, str) or not override_id.strip(): + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-missing-id", + path=IMPORTED_ASSET_OVERRIDES_PATH, + message="An imported-asset override entry is missing a non-empty `id`.", + suggestion="Give every override a stable id so sync replay can target it explicitly.", + ) + ) + elif override_id in ids_seen: + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-duplicate-id", + path=IMPORTED_ASSET_OVERRIDES_PATH, + message=f"The imported-asset override id `{override_id}` is declared more than once.", + suggestion="Keep one unique registry entry per approved imported override.", + ) + ) + else: + ids_seen.add(override_id) + + if not isinstance(target_path, str) or not target_path.strip(): + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-missing-target", + path=IMPORTED_ASSET_OVERRIDES_PATH, + message="An imported-asset override entry is missing `target_path`.", + suggestion="Point each override at the imported asset it patches.", + ) + ) + continue + + if target_path in targets_seen: + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-duplicate-target", + path=target_path, + message="The imported-asset override registry maps the same target more than once.", + suggestion="Keep one canonical override entry per imported target path.", + ) + ) + else: + targets_seen.add(target_path) + + if not is_imported_asset(target_path): + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-target-not-imported", + path=target_path, + message="Imported-asset override targets must point to non-internal, non-local catalog assets.", + suggestion="Move repository-owned behavior into an internal asset instead of registering it as an imported override.", + ) + ) + continue + + target_file = root / target_path + if not target_file.exists(): + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-target-missing", + path=target_path, + message="The imported-asset override target does not exist on disk.", + suggestion="Restore the target asset or remove the stale override entry.", + ) + ) + continue + + if approval != "explicit-user-counter-validated": + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-approval-missing", + path=target_path, + message="Imported-asset overrides require `approval: explicit-user-counter-validated`.", + suggestion="Record the explicit user counter-validation before keeping the override active.", + ) + ) + + if lifecycle_mode != "post-refresh-patch": + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-invalid-lifecycle", + path=target_path, + message="Imported-asset overrides must use `lifecycle_mode: post-refresh-patch`.", + suggestion="Keep the override replay model explicit instead of inventing ad hoc lifecycle states.", + ) + ) + + if apply_strategy not in {"git-apply", "git-apply-3way"}: + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-invalid-apply-strategy", + path=target_path, + message=( + "Imported-asset overrides must declare `apply_strategy` as " + "`git-apply` or `git-apply-3way`." + ), + suggestion=( + "Keep the replay mechanism explicit so upstream-refresh " + "behavior stays auditable and repeatable." + ), + ) + ) + + if not isinstance(patch_path, str) or not patch_path.strip(): + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-missing-patch", + path=target_path, + message="Imported-asset overrides must declare a replay patch path.", + suggestion="Add a patch file under the internal-agent-sync-external-resources skill bundle.", + ) + ) + else: + patch_file = skill_root / patch_path + if not patch_file.exists(): + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-patch-missing", + path=patch_file.relative_to(root).as_posix() + if patch_file.is_relative_to(root) + else patch_path, + message="The replay patch declared for an imported override is missing on disk.", + suggestion="Restore the patch file or remove the stale override entry.", + ) + ) + + if not isinstance(expected_hash, str) or len(expected_hash) != 64: + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-invalid-hash", + path=target_path, + message="Imported-asset overrides must declare a 64-character expected content hash.", + suggestion="Store the normalized content hash so validator and replay can detect drift.", + ) + ) + else: + from .fingerprinting import build_fingerprint + + actual_hash = build_fingerprint(root, target_file).content_hash + if actual_hash != expected_hash: + findings.append( + Finding( + severity="blocking", + code="imported-asset-override-hash-mismatch", + path=target_path, + message="The imported-asset override target no longer matches the registry hash.", + suggestion="Refresh the registry and replay patch together, or revert the untracked drift.", + ) + ) + + return findings + + def check_broken_local_links(root: Path) -> list[Finding]: findings: list[Finding] = [] for path in collect_repository_owned_markdown_paths(root): diff --git a/.github/scripts/lib/shared.py b/.github/scripts/lib/shared.py index 37f3531..8f55111 100644 --- a/.github/scripts/lib/shared.py +++ b/.github/scripts/lib/shared.py @@ -41,6 +41,7 @@ LOCAL_GITHUB_INSTRUCTIONS_OVERRIDES_TEMPLATE_PATH = ".github/local-github-instructions-overrides.md.template" LOCAL_GITHUB_INSTRUCTIONS_OVERRIDES_PATH = ".github/local-github-instructions-overrides.md" INVENTORY_PATH = ".github/INVENTORY.md" +IMPORTED_ASSET_OVERRIDES_PATH = ".github/skills/internal-agent-sync-external-resources/references/imported-asset-overrides.yaml" @dataclass(frozen=True) @@ -267,6 +268,19 @@ def is_local_asset(relative_path: str) -> bool: return path.name.startswith("local-") +def is_imported_asset(relative_path: str) -> bool: + path = Path(relative_path) + parts = path.parts + if len(parts) < 3 or parts[0] != ".github": + return False + if parts[1] == "skills": + prefix = parts[2] + return not prefix.startswith(("internal-", "local-")) + if parts[1] in {"agents", "instructions"}: + return not path.name.startswith(("internal-", "local-")) + return False + + def is_consumer_sync_excluded_path(relative_path: str) -> bool: path = Path(relative_path) return any(part.startswith(CONSUMER_SYNC_EXCLUDED_PREFIX) for part in path.parts) diff --git a/.github/scripts/run.sh b/.github/scripts/run.sh index 8a9ae29..3e099a9 100755 --- a/.github/scripts/run.sh +++ b/.github/scripts/run.sh @@ -32,6 +32,7 @@ Usage: ./.github/scripts/run.sh [tool-args...] Tools: + github_catalog_validation build_inventory check_catalog_consistency audit_copilot_catalog @@ -111,6 +112,9 @@ verify_venv_version() { resolve_script() { local tool_name="$1" case "$tool_name" in + github_catalog_validation|github_catalog_validation.py) + printf '%s\n' "$SCRIPT_DIR/github_catalog_validation.py" + ;; build_inventory|build_inventory.py) printf '%s\n' "$SCRIPT_DIR/build_inventory.py" ;; diff --git a/.github/security-baseline.md b/.github/security-baseline.md index cec881c..47d49c7 100644 --- a/.github/security-baseline.md +++ b/.github/security-baseline.md @@ -50,13 +50,13 @@ Provide a portable baseline that teams can apply before enabling repository-wide | Third-party action SHA pinning | Manual review | `internal-github-actions.instructions.md` + PR review | | Minimal workflow permissions | Manual review | `internal-github-actions.instructions.md` + PR review | | Docker image digest pinning | Manual review | `internal-docker.instructions.md` + PR review | -| Validate `.github/**` in CI | Automated | `.github/workflows/catalog-validation.yml` | +| Validate `.github/**` in CI | Automated | `.github/workflows/_github-catalog-validation.yml` | | `shellcheck` on `.github/scripts/` | Automated | pre-commit + CI | | Secret placeholder avoidance in examples/generated artifacts | Partial | pre-commit hooks + review | | OIDC over long-lived secrets | Manual review | `internal-github-actions.instructions.md` | | IAM least privilege (AWS/Azure/GCP) | Manual review | `internal-code-review` + `internal-terraform` | | Supply chain hardening | Manual review | `internal-github-actions.instructions.md` + `internal-code-review` | -| Branch protection for `.github/**` | Manual review | repository settings requiring `catalog-validation` | +| Branch protection for `.github/**` | Manual review | repository settings requiring `_github-catalog-validation` | | Read-only reviewer agents | Manual review | agent review | | CHANGELOG-based change governance | Manual review | PR review | diff --git a/.github/skills/internal-agent-boundary-recommendation-engine/SKILL.md b/.github/skills/internal-agent-boundary-recommendation-engine/SKILL.md new file mode 100644 index 0000000..220b440 --- /dev/null +++ b/.github/skills/internal-agent-boundary-recommendation-engine/SKILL.md @@ -0,0 +1,67 @@ +--- +name: internal-agent-boundary-recommendation-engine +description: Use when a repository-owned internal agent needs a consistent stop-and-recommend response after the user selected the wrong lane or the current lane stops being the best fit. +--- + +# Internal Agent Boundary Recommendation Engine + +Use this skill as the shared lane-mismatch engine for repository-owned internal agents that must stop, explain the mismatch, and recommend the better next option without hidden delegation. + +## When to use + +- A repository-owned internal agent was selected for a request it is not optimized to own. +- New information changes the winning lane after the current agent already started. +- Several related agents need the same stop-and-recommend behavior and that logic should not be duplicated in every agent body. + +## Goals + +- Stop before doing off-lane work. +- Explain the concrete mismatch in plain language. +- Recommend exactly one better owner when the next lane is clear. +- Fail safe to `internal-planning-leader` when more than one plausible owner remains. +- Keep the recommendation user-visible and recommendation-only. + +## Shared Stop Protocol + +1. State that the current lane is not the best fit. +2. Name the concrete reason the boundary broke. +3. Recommend one better owner and give one reason. +4. If the next owner is still ambiguous, recommend `internal-planning-leader` instead of offering multiple half-confident options. +5. Do not open a hidden second lane and do not continue with off-lane work. + +## Recommendation Matrix + +| Current agent | When the boundary breaks | Recommend | +| --- | --- | --- | +| `internal-delivery-operator` | Ambiguity, governance, or non-trivial authoring dominates | `internal-planning-leader` | +| `internal-delivery-operator` | Review, regression, or validation becomes the main need | `internal-review-guard` | +| `internal-delivery-operator` | Assumption stress-testing becomes the main need | `internal-critical-master` | +| `internal-planning-leader` | The next step is clear local execution with concrete verification | `internal-delivery-operator` | +| `internal-planning-leader` | Defect-first validation or merge readiness is now the main need | `internal-review-guard` | +| `internal-planning-leader` | The plan must be pressure-tested before action | `internal-critical-master` | +| `internal-review-guard` | Findings show missing design, routing, or plan ownership | `internal-planning-leader` | +| `internal-review-guard` | Weak reasoning needs a pressure test more than a technical review | `internal-critical-master` | +| `internal-review-guard` | The review lane is done and the next step is a clear local fix | `internal-delivery-operator` | +| `internal-critical-master` | The next step is a clear implementation or apply action | `internal-delivery-operator` | +| `internal-critical-master` | The framing or plan must be reformulated first | `internal-planning-leader` | +| `internal-critical-master` | The next step is evidence-based validation of a concrete change | `internal-review-guard` | +| `internal-sync-external-resources` | The source-side catalog direction is still ambiguous or needs repo-owned authoring decisions first | `internal-planning-leader` | +| `internal-sync-external-resources` | The real job is consumer-repository baseline propagation | `internal-sync-global-copilot-configs-into-repo` | +| `internal-sync-external-resources` | The work reduced to a clear local edit outside catalog-governance scope | `internal-delivery-operator` | +| `internal-sync-global-copilot-configs-into-repo` | The real job is source-side catalog governance in this repository | `internal-sync-external-resources` | +| `internal-sync-global-copilot-configs-into-repo` | The request is source-side redesign, agent authoring, or governance restructuring | `internal-planning-leader` | +| `internal-sync-global-copilot-configs-into-repo` | Only a clear target-local execution step remains after the sync contract is settled | `internal-delivery-operator` | + +## Agent-Specific Notes + +- `internal-critical-master` may need to ask whether the current analysis should be saved before recommending another owner. +- Repo-only sync agents may name the mode or scope mismatch before giving the shared recommendation. +- Do not recommend returning to the same agent. +- Do not recommend multiple alternatives unless the user explicitly asks for options. + +## Validation + +- The recommendation names an exact next owner unless ambiguity still remains. +- The response stops before off-lane execution starts. +- The mismatch reason is concrete, not prestige-based. +- The recommendation stays user-visible and does not rely on hidden agent dispatch. diff --git a/.github/skills/internal-agent-boundary-recommendation-engine/agents/openai.yaml b/.github/skills/internal-agent-boundary-recommendation-engine/agents/openai.yaml new file mode 100644 index 0000000..1f4056d --- /dev/null +++ b/.github/skills/internal-agent-boundary-recommendation-engine/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Internal Agent Boundary Recommendation Engine" + short_description: "Shared stop-and-recommend boundary guidance" + default_prompt: "Use $internal-agent-boundary-recommendation-engine when a repository-owned internal agent needs the shared stop-and-recommend boundary workflow." diff --git a/.github/skills/internal-agent-cross-lane-engine/SKILL.md b/.github/skills/internal-agent-cross-lane-engine/SKILL.md new file mode 100644 index 0000000..2a77762 --- /dev/null +++ b/.github/skills/internal-agent-cross-lane-engine/SKILL.md @@ -0,0 +1,124 @@ +--- +name: internal-agent-cross-lane-engine +description: Use when one of the four canonical operational agents needs the shared cross-lane boundary, medium-task, and anti-overlap policy. +--- + +# Internal Agent Cross-Lane Engine + +Use this skill as the shared engine for the four canonical operational agents in the direct-entry operational model. + +This skill is intentionally shared. It owns the reusable rules that would otherwise drift across `internal-delivery-operator`, `internal-planning-leader`, `internal-review-guard`, and `internal-critical-master`. It is not a copy of the agents. + +## When to use + +- One of the four canonical operational agents needs the shared cross-lane boundary and anti-overlap logic. +- A planning, execution, review, or challenge decision depends on the shared medium-task thresholds. +- Canonical-agent ownership drift needs to be resolved without rewriting the same rules into multiple agents. + +## Shared Core Rule + +Check relevant OBRA skills before starting any task. If a workflow is relevant, it is mandatory, not optional. Do not preload irrelevant workflows. + +Implications: + +- Apply OBRA only when the task shape actually triggers the workflow. +- Keep small tasks small. +- Do not skip a relevant OBRA workflow just because the agent already knows what to do. + +## Boundary Model + +| Canonical owner | Owns | Does not own | +| --- | --- | --- | +| `internal-delivery-operator` | Clear, local execution and deterministic repository-owned maintenance or realignment with concrete verification and limited risk | Strategic tradeoffs, ambiguous scope, non-trivial repository-owned authoring, review-first asks, or critical challenge | +| `internal-planning-leader` | Ambiguity resolution, decision records, plans, non-trivial repository-owned authoring, and rollout or governance decisions that remain open | Default local execution once the design is settled, deterministic maintenance whose target state is already known, defect-first review, or pure challenge | +| `internal-review-guard` | Review, validation, merge readiness, regression risk, evidence gaps, and defect-first findings | Implementation, initial design ownership, or open-ended strategic challenge | +| `internal-critical-master` | Pre-mortems, assumption stress tests, alternative framings, failure modes, and strong objections | Implementation, routine technical review, or final operational planning | + +## Medium-Task Thresholds + +`internal-delivery-operator` stays owner only when all of these are true: + +- The outcome is already clear and concrete verification exists. +- The work is deterministic implementation or repository-owned maintenance or realignment with no non-trivial strategy tradeoff. +- File count and adjacent boundary crossing stay within one coherent area, or do not create a new ownership or catalog decision. +- Routing, ownership, naming contracts, and catalog boundaries are being applied rather than redesigned. + +File count and adjacent boundary crossing are heuristics, not automatic planning triggers. + +A clear realignment across more than two adjacent `.github/` assets can stay with `internal-delivery-operator` when the target state is already known and validation is concrete. + +`internal-planning-leader` becomes owner when at least one of these is true: + +- Real ambiguity remains about the right shape, contract, or rollout. +- There are `>= 2` credible solution paths with non-trivial tradeoffs. +- The change affects routing, ownership, naming contracts, or catalog boundaries in substance, not just by touching adjacent files. +- The task needs rollout, regression, governance, or rollback decisions. +- The task creates a new repository-owned resource instead of a banal update to an existing one. + +## Lane-Change Protocol + +The canonical operational model uses direct entry: users select one of the four canonical owners directly, and ambiguous entry fails safe to `internal-planning-leader`. + +Once active, each owner stays inside its boundary. When the boundary no longer holds, use `internal-agent-boundary-recommendation-engine` for the user-visible stop-and-recommend behavior instead of cloning that protocol or matrix here. + +The four canonical owners are not subagent-invoked by default. Any future exception must be explicit, narrow, one-directional, and must not create an all-to-all mesh or nested ping-pong. + +## Mandatory Engine vs Optional Support + +Use this policy across all canonical agents: + +- `## Mandatory Engine Skills` lists only the skill or skills required before the agent can operate correctly. +- `## Optional Support Skills` lists conditional helpers, tactical specialists, or OBRA workflows that matter only for some tasks. +- Do not place required engines inside the optional list. +- Do not create 1:1 decorative engine skills for symmetry alone. +- A shared engine is preferable when the same reusable rules would otherwise drift across multiple agents. + +Load `references/ownership-maps.md` when you need: + +- the current canonical skill-to-owner lookup +- the retired-to-canonical owner mapping +- the shorthand rules for cloud and runtime skills inside the operational model + +## Relationship Model + +- The direct-entry model has no repository-owned front-door router above the four canonical owners. +- `internal-planning-leader` is the safe fallback when the right lane is not clear yet. +- The four canonical owners should stay user-selectable and `disable-model-invocation: true` by default so hidden peer dispatch stays opt-in instead of ambient. +- If a narrower scoped contract ever allows one canonical owner to invoke another, the exception must be explicit, one-directional, auditably bounded, and must not create ping-pong or hidden route selection. +- `internal-planning-leader` absorbs the role previously covered by `internal-ai-resource-creator` when the work is non-trivial repository-owned authoring. +- `internal-review-guard` must reuse `internal-code-review` instead of restating the review playbook in the agent body. +- `internal-delivery-operator` should stay light and load runtime or domain skills only when the task already belongs to execution. +- `internal-critical-master` should stay narrow: challenge the reasoning, reframe hidden constraints when useful, synthesize the pressure test, and tell the user when planning should resume. +- `internal-sync-*` and `awesome-*` assets stay outside this canonical operational model. + +## Anti-Overlap Checklist + +Before finalizing any operational routing or agent edit, check these questions: + +- Is the request primarily execution, planning, review, or challenge? +- Would the same request cause two canonical agents to claim ownership? +- Is a required engine hiding inside `## Optional Support Skills`? +- Is a new skill being created only for symmetry instead of real shared logic? +- Is the agent body repeating logic that belongs in a shared skill? +- Is an imported or sync-only asset being treated as a canonical operational owner? +- Would a power user know when to pick this agent directly without reading three files? + +If any answer points to overlap, narrow the agent or move the shared logic into a skill. + +## Common Mistakes + +| Mistake | Why it matters | Instead | +| --- | --- | --- | +| Letting `internal-delivery-operator` keep medium tasks by momentum | Execution becomes accidental planning | Tell the user the boundary broke and recommend `internal-planning-leader` on the first medium-task threshold hit | +| Treating file count or adjacent boundary crossing as automatic planning triggers | Deterministic realignments get over-routed into planning | Check for real ambiguity, tradeoffs, or ownership change before leaving execution | +| Letting `internal-planning-leader` execute by default | The planner becomes a catch-all generalist | Tell the user when the design is settled and recommend `internal-delivery-operator` | +| Rewriting the review playbook inside `internal-review-guard` | Review logic drifts from the tactical skill | Reuse `internal-code-review` as the mandatory tactical engine | +| Treating challenge as generic negativity | The agent stops producing useful decision pressure | Keep one challenge thread, then synthesize clear failure modes | +| Creating one dedicated engine skill per agent for symmetry | The catalog grows without adding real structure | Use shared engines or existing skills unless a real gap exists | + +## Output Expectations + +- Current owner and boundary rationale +- Whether the boundary still holds and why +- Which OBRA workflows are relevant for this task +- Which tactical internal skill should be loaded next, if any diff --git a/.github/skills/internal-agent-cross-lane-engine/agents/openai.yaml b/.github/skills/internal-agent-cross-lane-engine/agents/openai.yaml new file mode 100644 index 0000000..6cd7dd9 --- /dev/null +++ b/.github/skills/internal-agent-cross-lane-engine/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Internal Agent Cross-Lane Engine" + short_description: "Help with Internal Agent Cross-Lane Engine tasks" + default_prompt: "Use $internal-agent-cross-lane-engine for this task and follow the repository-owned workflow in the skill." diff --git a/.github/skills/internal-agent-operating-model-engine/references/ownership-maps.md b/.github/skills/internal-agent-cross-lane-engine/references/ownership-maps.md similarity index 59% rename from .github/skills/internal-agent-operating-model-engine/references/ownership-maps.md rename to .github/skills/internal-agent-cross-lane-engine/references/ownership-maps.md index f997285..36e2935 100644 --- a/.github/skills/internal-agent-operating-model-engine/references/ownership-maps.md +++ b/.github/skills/internal-agent-cross-lane-engine/references/ownership-maps.md @@ -2,12 +2,14 @@ Use this reference when the operational model needs a lookup table instead of a narrative boundary explanation. +The canonical operational model uses direct owner selection. When the winning owner is unclear, fail safe to `internal-planning-leader` instead of a dedicated routing skill. + ## Skill Ownership Model | Skill | Primary owner | When it wins | | --- | --- | --- | -| `internal-agent-routing-engine` | `internal-router` | Front-door classification, fail-safe selection, and dispatch to one canonical owner | -| `internal-agent-operating-model-engine` | Shared by the four canonical agents | Shared boundary, recommendation, and anti-overlap logic | +| `internal-agent-boundary-recommendation-engine` | Shared by the canonical operational agents and repo-only sync command centers | Shared stop-and-recommend protocol when the selected lane no longer fits | +| `internal-agent-cross-lane-engine` | Shared by the four canonical agents | Shared cross-lane boundary, medium-task, and anti-overlap logic | | `internal-code-review` | `internal-review-guard` | Tactical review engine for findings and defect-first analysis | | `internal-agent-development` | `internal-planning-leader` | Non-trivial repository-owned agent authoring | | `internal-copilot-audit` | `internal-planning-leader` | Catalog audit, drift analysis, and stale-reference review | @@ -15,7 +17,7 @@ Use this reference when the operational model needs a lookup table instead of a | `internal-change-impact-analysis` | `internal-planning-leader` | Change-impact and architecture-risk analysis | | `internal-writing-plans` | `internal-planning-leader` | Repository-owned execution-plan authoring under `tmp/superpowers//` with local structure, path, and language rules | | `internal-executing-plans` | `internal-planning-leader` | Repository-owned plan application with `done-*` tracking, sequential continuation, and blocker stops | -| `internal-terraform`, `internal-github-actions`, and runtime-specific internal skills | `internal-fast-executor` for local execution, `internal-planning-leader` when design or rollout dominates | Tactical delivery versus strategy split | +| `internal-terraform`, `internal-github-actions`, and runtime-specific internal skills | `internal-delivery-operator` for local execution, `internal-planning-leader` when design or rollout dominates | Tactical delivery versus strategy split | | `obra-*` workflows | Cross-agent support | Mandatory when relevant, absent when irrelevant | ## Retired To Canonical Ownership Mapping @@ -24,9 +26,9 @@ Use this reference when the operational model needs a lookup table instead of a | --- | --- | | `internal-ai-resource-creator` | `internal-planning-leader` | | `internal-architect` | `internal-planning-leader` | -| `internal-developer` | `internal-fast-executor` | -| `internal-infrastructure` | `internal-fast-executor` or `internal-planning-leader` when design or rollout dominates | -| `internal-cicd` | `internal-fast-executor` or `internal-planning-leader` when orchestration or tradeoffs dominate | +| `internal-developer` | `internal-delivery-operator` | +| `internal-infrastructure` | `internal-delivery-operator` or `internal-planning-leader` when design or rollout dominates | +| `internal-cicd` | `internal-delivery-operator` or `internal-planning-leader` when orchestration or tradeoffs dominate | | `internal-code-review` | `internal-review-guard` | -| `internal-quality-engineering` | `internal-review-guard` for validation and risk, `internal-fast-executor` for a clear fix | -| `internal-aws-*`, `internal-azure-*`, `internal-gcp-*` | `internal-planning-leader` for strategy or design, `internal-fast-executor` for clear local execution | +| `internal-quality-engineering` | `internal-review-guard` for validation and risk, `internal-delivery-operator` for a clear fix | +| `internal-aws-*`, `internal-azure-*`, `internal-gcp-*` | `internal-planning-leader` for strategy or design, `internal-delivery-operator` for clear local execution | diff --git a/.github/skills/internal-agent-development/SKILL.md b/.github/skills/internal-agent-development/SKILL.md index 1f8cdda..137e749 100644 --- a/.github/skills/internal-agent-development/SKILL.md +++ b/.github/skills/internal-agent-development/SKILL.md @@ -13,8 +13,8 @@ Use `internal-skill-creator` first when the main output is a repository-owned sk Prefer explicit engine-skill architecture for routers and broader command centers: -- keep routing contract, tool contract, boundaries, boundary recommendations, and output shape in the agent -- move long decision matrices, threshold rules, ownership maps, and reusable operating logic into repo-owned engine skills +- keep routing contract, tool contract, positive boundaries, and output shape in the agent +- move reusable boundary-recommendation protocols, long decision matrices, threshold rules, ownership maps, and shared operating logic into repo-owned engine skills when multiple agents need the same behavior - when that engine is required for the agent's core behavior, declare it explicitly instead of burying it in optional skill guidance ## When to use @@ -97,9 +97,10 @@ Use this split when authoring command-center agents: - role and stance - boundary with neighboring agents - tool contract - - boundary definition and user-facing recommendation pattern + - boundary definition and any agent-specific lane-break handling that is not shared elsewhere - output expectations - Engine skill: + - shared stop-and-recommend protocol when several neighboring agents need the same lane-mismatch handling - decision matrix - threshold rules for medium or ambiguous tasks - old-to-new ownership mapping @@ -207,10 +208,12 @@ Load `references/design-patterns.md` for command-center structure questions and - A skill-list section as a dumping ground for unrelated capabilities. - A `## Mandatory Engine Skills` section that merely mirrors the agent body without owning real reusable logic. - Creating one dedicated skill per agent for visual symmetry even when shared or existing engines already solve the problem. +- Repeating the same lane-mismatch recommendation matrix across multiple neighboring agents when one shared boundary engine would be clearer. - Starting from the selected agent file alone and skipping the directly relevant optional support or preferred skills that define how that agent should be applied. - Treating preferred or optional skills as a fake platform-enforced toolchain or as an origin-based priority ladder. - Treating optional support skills as if they were the required engine. -- Creating a dedicated mirror skill for `internal-fast-executor` or `internal-critical-challenger` when the shared operating-model engine already carries the reusable logic. +- Creating a dedicated mirror skill for `internal-delivery-operator` or `internal-critical-master` when the shared operating-model engine already carries the reusable logic. +- Assuming VS Code subagent context isolation means the child loses all inherited defaults; by default, subagents inherit the main session agent, model, and tools, and a custom agent used as a subagent overrides those defaults with its own configuration. - Preserving the route but throwing away the upstream agent's best structure, leaving a compliant internal agent that is harder to use and less decisive. - Treating `tools:` or `model:` as deprecated in current GitHub Copilot custom agents. - Copying multi-screen tool lists from older examples instead of normalizing them to canonical aliases and an explicit minimal contract. @@ -238,6 +241,7 @@ Load `references/design-patterns.md` for command-center structure questions and - If the agent includes a skill-list section, confirm the wording does not imply that `internal-*` skills automatically outrank imported skills. - Confirm any existing command-center agent used as a source or workflow anchor had its directly relevant declared skills loaded before final decisions were made. - Confirm the agent has a meaningful routing boundary and is not just "expert at everything in X." +- If a shared boundary-recommendation engine is used, confirm the agent still keeps a real route and at least one meaningful negative boundary instead of turning into a thin pointer. - Confirm routers keep classification matrices, fallback rules, and old-to-new ownership mapping in an engine skill instead of long body prose when that logic is substantial. - For routers or coordinator-style agents that delegate within the turn, confirm the contract forbids classification-only completion and defines degraded-mode behavior when delegation does not return usable content. - Confirm routers are treated as the strongest case for a dedicated engine and that shared operational logic for the four canonical owners stays in a shared engine instead of branching into decorative mirrors. diff --git a/.github/skills/internal-agent-development/references/agent-contract.md b/.github/skills/internal-agent-development/references/agent-contract.md index 6e9dccf..0726eed 100644 --- a/.github/skills/internal-agent-development/references/agent-contract.md +++ b/.github/skills/internal-agent-development/references/agent-contract.md @@ -34,11 +34,14 @@ Use this reference when editing frontmatter, tool scope, engine-skill sections, - Do not present a skill-list section as a native GitHub Copilot property or as a guarantee that every listed skill will be invoked automatically. - When expressing the resource model, treat `obra-*` as the cross-cutting workflow lane, `internal-*` as the canonical repository-owned layer, imported skills as support depth by default, and `local-*` as consumer-local extensions. Do not infer strategic, tactical, or operational role from prefix alone. - Do not create a 1:1 dedicated skill per agent just for symmetry. Create an engine skill only when it owns real reusable logic that would otherwise bloat the agent or drift. +- When several neighboring repository-owned agents share the same stop-and-recommend behavior, prefer one shared boundary-recommendation engine over repeating the same next-owner matrix in every agent body. Keep the route and at least one real boundary in each agent. - Router agents are the strongest default candidate for a dedicated engine skill because their classification matrix, fallback rules, and ownership mapping are highly procedural. ## Delegation And Invocation Controls -- Only router agents should own active downstream routing logic. Canonical non-router agents should recommend a better owner to the user instead of routing on the user's behalf, unless a narrower scoped contract explicitly allows them to invoke `internal-router` as a second parallel lane while leaving downstream owner selection to the router. +- Only dedicated coordinator or router agents should own active downstream routing logic. Canonical direct owners should recommend a better owner to the user instead of routing on the user's behalf. +- Prefer user-visible lane changes or direct user choice over hidden peer dispatch between canonical owners. +- If a narrower scoped contract allows one canonical owner to invoke another, the exception must be explicit, one-directional, auditably bounded, and must not create an all-to-all mesh or nested ping-pong. - When an agent should dispatch to specific subagents, declare `agents:` with the explicit list of allowed targets. - When an agent must not dispatch subagents, declare `agents: []` to enforce the recommendation-only boundary. - When an agent should only be accessible as a subagent and not appear in the user dropdown, set `user-invocable: false`. diff --git a/.github/skills/internal-agent-development/references/conversion-checklist.md b/.github/skills/internal-agent-development/references/conversion-checklist.md index 2992758..b1f1bb9 100644 --- a/.github/skills/internal-agent-development/references/conversion-checklist.md +++ b/.github/skills/internal-agent-development/references/conversion-checklist.md @@ -37,7 +37,7 @@ Use this checklist when converting an upstream agent or agent-authoring pattern 1. Confirm optional frontmatter is still supported by current GitHub Copilot docs and that the internal agent declares `tools:` with canonical aliases or MCP namespaces. 2. Confirm the agent says when not to use it. -3. If the agent is not `internal-router`, confirm it recommends other owners without actively routing or handing off. +3. If the agent is a direct owner rather than a coordinator, confirm it recommends other owners without actively routing or handing off. 4. Confirm output expectations are observable. 5. Confirm the imported pattern no longer depends on stale runtime behavior or obsolete tool ids. 6. Run repository validation before finishing. diff --git a/.github/skills/internal-agent-development/references/review-checklist.md b/.github/skills/internal-agent-development/references/review-checklist.md index 227792b..508e82e 100644 --- a/.github/skills/internal-agent-development/references/review-checklist.md +++ b/.github/skills/internal-agent-development/references/review-checklist.md @@ -7,7 +7,7 @@ Use this checklist before finalizing a new or revised internal agent. - Does `description:` start with `Use this agent when ...`? - Could a reader tell when this agent wins over neighboring agents? - Does the agent include at least one real negative boundary? -- If the agent is not `internal-router`, does it avoid active delegation and recommend the next owner instead? +- If the agent is a direct owner rather than a coordinator, does it avoid active delegation and recommend the next owner instead? - Is the route behavioral rather than prestige-based? - If the agent works in a fast-moving vendor domain, does the route make current-documentation verification visible? diff --git a/.github/skills/internal-agent-development/references/subagent-patterns.md b/.github/skills/internal-agent-development/references/subagent-patterns.md index 11fc26c..4637e25 100644 --- a/.github/skills/internal-agent-development/references/subagent-patterns.md +++ b/.github/skills/internal-agent-development/references/subagent-patterns.md @@ -17,6 +17,7 @@ Key rules: - If `agents:` is present, `agent` must be in the `tools:` list. - `handoffs` and `argument-hint` are VS Code only; GitHub.com ignores them. - `infer:` is retired. Use `user-invocable` and `disable-model-invocation` instead. +- Context isolation does not mean a subagent starts from zero configuration. By default, a subagent inherits the main session agent, model, and tools; when the subagent is a custom agent, its own configuration overrides those inherited defaults. ## Coordinator and Worker Pattern @@ -72,7 +73,7 @@ Focused instructions for domain A work. ### Router with explicit dispatch targets ```yaml -agents: ['internal-fast-executor', 'internal-planning-leader', 'internal-review-guard', 'internal-critical-challenger'] +agents: ['internal-delivery-operator', 'internal-planning-leader', 'internal-review-guard', 'internal-critical-master'] ``` Only these four agents can be invoked as subagents. The platform enforces this. @@ -85,18 +86,21 @@ agents: [] This makes the "recommendation-only" boundary a platform-enforced fact, not just prose. -### Canonical owner with a router-only second lane +### Rare one-way exception between direct owners ```yaml -agents: ['internal-router'] +agents: ['internal-target-owner'] ``` Use this only when all of these are true: -- `internal-router` remains the only router and still chooses any downstream owner -- the current agent stays in its own lane instead of turning into a router -- the second lane is explicit, narrow, and parallel rather than a hidden handoff -- the agent's body makes the exception and trigger conditions explicit +- the exception is explicit, narrow, and one-directional +- ownership remains readable and auditably bounded +- the called owner does not re-route or call back +- the workflow does not create an all-to-all mesh or nested ping-pong +- a user-visible handoff would add more friction than the single bounded exception + +Do not use this pattern as a default operational mesh. ### Subagent-only agents @@ -113,7 +117,7 @@ Handoffs create guided sequential workflows with user-visible buttons between ag ```yaml handoffs: - label: Start Implementation - agent: internal-fast-executor + agent: internal-delivery-operator prompt: Implement the plan outlined above. send: false ``` diff --git a/.github/skills/internal-agent-operating-model-engine/SKILL.md b/.github/skills/internal-agent-operating-model-engine/SKILL.md deleted file mode 100644 index 21a2bc1..0000000 --- a/.github/skills/internal-agent-operating-model-engine/SKILL.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -name: internal-agent-operating-model-engine -description: Use when one of the four canonical operational agents needs the shared boundary, recommendation, medium-task, and anti-overlap policy. ---- - -# Internal Agent Operating Model Engine - -Use this skill as the shared engine for the four canonical operational agents. - -This skill is intentionally shared. It owns the reusable rules that would otherwise drift across `internal-fast-executor`, `internal-planning-leader`, `internal-review-guard`, and `internal-critical-challenger`. It is not a copy of the agents. - -## When to use - -- One of the four canonical operational agents needs the shared boundary and anti-overlap logic. -- A planning, execution, review, or challenge decision depends on the shared medium-task thresholds. -- Canonical-agent ownership drift needs to be resolved without rewriting the same rules into multiple agents. - -## Shared Core Rule - -Check relevant OBRA skills before starting any task. If a workflow is relevant, it is mandatory, not optional. Do not preload irrelevant workflows. - -Implications: - -- Apply OBRA only when the task shape actually triggers the workflow. -- Keep small tasks small. -- Do not skip a relevant OBRA workflow just because the agent already knows what to do. - -## Boundary Model - -| Canonical owner | Owns | Does not own | -| --- | --- | --- | -| `internal-fast-executor` | Clear, local execution with concrete verification and limited risk | Strategic tradeoffs, ambiguous scope, broad authoring, review-first asks, or critical challenge | -| `internal-planning-leader` | Ambiguity resolution, decision records, plans, repository-owned authoring, rollout and governance decisions | Default local execution once the design is settled, defect-first review, or pure challenge | -| `internal-review-guard` | Review, validation, merge readiness, regression risk, evidence gaps, and defect-first findings | Implementation, initial design ownership, or open-ended strategic challenge | -| `internal-critical-challenger` | Pre-mortems, assumption stress tests, alternative framings, failure modes, and strong objections | Implementation, routine technical review, or final operational planning | - -## Medium-Task Thresholds - -`internal-fast-executor` stays owner only when all of these are true: - -- The likely change touches `<= 2` files. -- The work stays within one directory family or one logical boundary. -- Routing, ownership, naming contracts, and catalog boundaries stay unchanged. -- The task does not require a real strategic comparison. - -`internal-planning-leader` becomes owner when at least one of these is true: - -- The change touches `>= 3` files with lateral impact. -- The change crosses more than one directory family or logical boundary. -- The change affects routing, ownership, naming contracts, or catalog boundaries. -- There are `>= 2` credible solution paths with non-trivial tradeoffs. -- The task needs rollout, regression, governance, or rollback decisions. -- The task creates a new repository-owned resource instead of a banal update to an existing one. - -## Boundary Recommendation Protocol - -Only `internal-router` actively routes between owners and may dispatch to the selected canonical owner. The four canonical owners may be entered either directly by the user or by router handoff, but once active they stay inside their boundary, tell the user when that boundary no longer holds, and recommend the better owner instead of delegating unless a narrower scoped contract explicitly allows invoking `internal-router` as a second parallel lane while leaving downstream owner selection to the router. - -| Agent | Stay owner when | Boundary breaks when | Recommend | -| --- | --- | --- | --- | -| `internal-fast-executor` | The task is clear, local, low-risk, and concretely verifiable. | Medium-task thresholds, non-obvious tradeoffs, or routing and ownership changes appear. | `internal-planning-leader` | -| `internal-planning-leader` | Ambiguity, cross-boundary tradeoffs, repository-owned authoring, or rollout decisions still need active ownership. | The design is settled and the next step is routine local execution. | `internal-fast-executor` | -| `internal-review-guard` | The task is defect-first review, merge readiness, regression analysis, or evidence gathering. | Findings reveal missing design or weak boundaries. | `internal-planning-leader` | -| `internal-review-guard` | The task is still review-owned but weak reasoning becomes the dominant gap. | Pressure-testing the reasoning matters more than technical review. | `internal-critical-challenger` | -| `internal-critical-challenger` | The task is assumption testing, a pre-mortem, lateral reframing, or failure-mode analysis. | The framing or plan must be reformulated. | `internal-planning-leader` | -| `internal-critical-challenger` | The task remains challenge-owned until the reasoning survives scrutiny. | Evidence-based validation becomes the next need. | `internal-review-guard` | - -Recommendation should name the reason, not only the suggested owner, and the user decides whether to switch. - -## Mandatory Engine vs Optional Support - -Use this policy across all canonical agents: - -- `## Mandatory Engine Skills` lists only the skill or skills required before the agent can operate correctly. -- `## Optional Support Skills` lists conditional helpers, tactical specialists, or OBRA workflows that matter only for some tasks. -- Do not place required engines inside the optional list. -- Do not create 1:1 decorative engine skills for symmetry alone. -- A shared engine is preferable when the same reusable rules would otherwise drift across multiple agents. - -Load `references/ownership-maps.md` when you need: - -- the current canonical skill-to-owner lookup -- the retired-to-canonical owner mapping -- the shorthand rules for cloud and runtime skills inside the operational model - -## Relationship Model - -- `internal-router` owns the front door only. It may hand the task to one canonical owner, but it does not implement, plan, review, or challenge by itself. -- The four canonical owners may be entered directly by the user or by router handoff; the entry path does not widen their boundary. -- A canonical non-router may invoke `internal-router` only when a narrower scoped contract explicitly allows a second parallel lane and the non-router does not choose the downstream owner itself. -- `internal-planning-leader` absorbs the role previously covered by `internal-ai-resource-creator` when the work is non-trivial repository-owned authoring. -- `internal-review-guard` must reuse `internal-code-review` instead of restating the review playbook in the agent body. -- `internal-fast-executor` should stay light and load runtime or domain skills only when the task already belongs to execution. -- `internal-critical-challenger` should stay narrow: challenge the reasoning, reframe hidden constraints when useful, synthesize the pressure test, and tell the user when planning should resume. -- `internal-sync-*` and `awesome-*` assets stay outside this canonical operational model. - -## Anti-Overlap Checklist - -Before finalizing any operational routing or agent edit, check these questions: - -- Is the request primarily execution, planning, review, or challenge? -- Would the same request cause two canonical agents to claim ownership? -- Is a required engine hiding inside `## Optional Support Skills`? -- Is a new skill being created only for symmetry instead of real shared logic? -- Is the agent body repeating logic that belongs in a shared skill? -- Is an imported or sync-only asset being treated as a canonical operational owner? -- Would a power user know when to pick this agent directly without reading three files? - -If any answer points to overlap, narrow the agent or move the shared logic into a skill. - -## Common Mistakes - -| Mistake | Why it matters | Instead | -| --- | --- | --- | -| Letting `internal-fast-executor` keep medium tasks by momentum | Execution becomes accidental planning | Tell the user the boundary broke and recommend `internal-planning-leader` on the first medium-task threshold hit | -| Letting `internal-planning-leader` execute by default | The planner becomes a catch-all generalist | Tell the user when the design is settled and recommend `internal-fast-executor` | -| Rewriting the review playbook inside `internal-review-guard` | Review logic drifts from the tactical skill | Reuse `internal-code-review` as the mandatory tactical engine | -| Treating challenge as generic negativity | The agent stops producing useful decision pressure | Keep one challenge thread, then synthesize clear failure modes | -| Creating one dedicated engine skill per agent for symmetry | The catalog grows without adding real structure | Use shared engines or existing skills unless a real gap exists | - -## Output Expectations - -- Current owner and boundary rationale -- Whether the boundary still holds and why -- Which OBRA workflows are relevant for this task -- Which tactical internal skill should be loaded next, if any diff --git a/.github/skills/internal-agent-operating-model-engine/agents/openai.yaml b/.github/skills/internal-agent-operating-model-engine/agents/openai.yaml deleted file mode 100644 index 414f32d..0000000 --- a/.github/skills/internal-agent-operating-model-engine/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Internal Agent Operating Model Engine" - short_description: "Help with Internal Agent Operating Model Engine tasks" - default_prompt: "Use $internal-agent-operating-model-engine for this task and follow the repository-owned workflow in the skill." diff --git a/.github/skills/internal-agent-routing-engine/SKILL.md b/.github/skills/internal-agent-routing-engine/SKILL.md deleted file mode 100644 index cedcb52..0000000 --- a/.github/skills/internal-agent-routing-engine/SKILL.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -name: internal-agent-routing-engine -description: Use when `internal-router` must classify an ambiguous operational request and dispatch it to execution, planning, review, or challenge without doing the domain work itself. ---- - -# Internal Agent Routing Engine - -Use this skill as the mandatory engine for `internal-router`. - -This skill owns the reusable routing logic. The router stays short: classify, ask at most one high-value question when needed, hand off to one canonical owner, and stay out of the domain work. The router never implements. - -Keep the engine boundary explicit: - -- `internal-agent-routing-engine` owns classification, confidence, clarification, and handoff packaging. -- `internal-agent-operating-model-engine` owns the shared medium-task thresholds, owner boundaries, and anti-overlap rules that inform routing but are not rewritten here. - -## When to use - -- `internal-router` must classify an ambiguous request across execution, planning, review, or challenge. -- Router confidence, clarification rules, or handoff packaging need to change without widening the router into domain work. -- Routing behavior must be updated while preserving the separate operating-model engine boundary. - -## Core Rules - -- Classify first by intent: execution, planning, review, or challenge. -- Then classify by scale, ambiguity, risk, and boundary-crossing. -- Ask at most one targeted clarification question with two clear options, and only when it materially improves routing confidence. -- If confidence does not reach a safe routing decision after that question, fail safe to `internal-planning-leader` and hand off there. -- Dispatch only to the four canonical owners: `internal-fast-executor`, `internal-planning-leader`, `internal-review-guard`, and `internal-critical-challenger`. -- If the router is entered as an explicit second parallel lane from another canonical owner, preserve that current lane as context and classify only the parallel operational request. -- Preserve the user's exact request plus any already-collected evidence instead of forcing the selected owner to re-triage from scratch. -- Treat the routing turn as incomplete until the delegated owner's result is attached in the same turn, or one blocking clarification question is asked because the selected owner cannot safely proceed without it. -- Do not present route selection or the handoff package alone as a completed response. -- If auto-dispatch is interrupted, yields no usable owner result, or the delegated result is missing from the response, retry once when safe. If it still does not complete, state that delegation did not complete, surface the preserved handoff package, and ask one blocking question only when user input is required. -- Do not implement through the router. - -## Primary Route Labels - -| Label | Canonical owner | Route when | -| --- | --- | --- | -| `route-to-execute` | `internal-fast-executor` | The task is clear, local, low-risk, and has concrete verification. | -| `route-to-plan` | `internal-planning-leader` | The task is ambiguous, cross-boundary, strategic, or changes repository-owned contracts. | -| `route-to-review` | `internal-review-guard` | The user asks for review, validation, merge readiness, regression analysis, or evidence checks. | -| `route-to-challenge` | `internal-critical-challenger` | The user wants assumptions challenged, a pre-mortem, alternative framings pressure-tested, or failure modes surfaced. | - -## Confidence Model - -| Confidence | Meaning | Router action | -| --- | --- | --- | -| `high` | The request has one clear owner and the boundary is stable. | Select the owner and auto-dispatch there. | -| `medium` | Two owners are plausible, but one short question could remove the ambiguity. | Ask one targeted question, then dispatch or fail safe. | -| `low` | The request is underspecified, cross-boundary, or risky enough that premature routing would be noise. | Fail safe to `internal-planning-leader` and auto-dispatch there. | - -Use these heuristics: - -- Treat explicit review language such as `review`, `audit`, `validate`, `risk`, `merge readiness`, or `regression` as `route-to-review` unless the user clearly asks for implementation. -- Treat explicit challenge language such as `challenge this`, `pre-mortem`, `stress-test`, `what am I missing`, `failure modes`, `reframe this`, or `think laterally` as `route-to-challenge`. -- Bias toward `route-to-challenge` when the user asks for a check before merge, before a major refactor, before a cross-boundary plan, or when the framing looks rigid enough that an objection-first pass would materially change the plan. -- Treat repository-owned authoring of agents, skills, instructions, routing, or governance as planning unless the change is trivially local and already designed. -- Treat vague implementation requests as planning when scale, ownership, or rollout is not yet clear. - -## Decision Matrix - -| Task shape | Signals | Route | -| --- | --- | --- | -| Clear execution | One concrete outcome, local scope, obvious validation path, no strategy tradeoff | `route-to-execute` | -| Medium execution | Mostly concrete, but some uncertainty remains about scale or boundaries | Ask one question or route to `internal-planning-leader` | -| Ambiguous or strategic | Cross-file, cross-boundary, naming or ownership changes, or multiple credible options | `route-to-plan` | -| Review-oriented | The output should be findings, evidence, risk, or merge readiness | `route-to-review` | -| Challenge-oriented | The output should be objections, pressure tests, assumption gaps, alternative framings, or failure modes | `route-to-challenge` | - -## Medium-Task Thresholds - -Use `internal-agent-operating-model-engine` for the shared medium-task logic. - -For router purposes, the consequence is simple: - -- if any shared medium-task threshold is hit, fail safe to `route-to-plan` -- stay with `route-to-execute` only when the task remains clearly local, low-risk, and concretely verifiable - -## High-Value Clarification Question Rule - -Only ask one question when the answer will change the owner. - -Prefer A-or-B questions with two clear options over open-ended interviews. If a safe two-option question is not obvious, fail safe to `internal-planning-leader`. - -Good questions: - -- `Is your goal to implement the change now, or to decide the right design and rollout first?` -- `Do you want a defect-first review, or do you want the change implemented?` -- `Should this route stress-test the proposal, or produce the final execution plan?` - -Bad questions: - -- Broad interviews with multiple subquestions. -- Questions that gather details the selected owner should inspect alone. -- Questions that delay an already safe `route-to-plan` fail-safe. - -## Handoff Protocol - -After selecting the canonical owner, hand off a compact package that includes: - -- `selected_owner` -- `route_label` -- `confidence` -- `routing_rationale` -- `current_lane` when the router was entered as a second parallel lane -- `user_request` -- `relevant_constraints` -- `already_collected_evidence` -- `expected_output_shape` - -Keep the handoff compact, preserve the user's wording, and include only the evidence that materially reduces re-triage. - -## Retired To Canonical Mapping - -Load `../internal-agent-operating-model-engine/references/ownership-maps.md` when the request mentions retired owners or cloud-family aliases and you need the canonical owner before dispatch. - -Do not use `internal-sync-*` or `awesome-*` assets as canonical operational owners in this routing model. - -Load `references/owner-examples.md` only when the matrix and confidence model still leave two plausible owners and you need concrete examples to break the tie. - -## Fail-Safe Rule - -When routing is not safely clear, select `route-to-plan` and hand off to `internal-planning-leader`. - -Routing conservatively is cheaper than dispatching the user to the wrong owner and forcing a second triage cycle. - -## Output Expectations - -- Selected route label -- Selected canonical owner -- Confidence level -- One-sentence routing rationale -- Handoff package summary with preserved request, constraints, and already-collected evidence -- Delegated owner's result, prefixed by a short routing note -- Explicit blocking explanation plus preserved handoff package when delegation did not complete -- Single clarification question only when medium-confidence routing or degraded dispatch truly needs user input -- Explicit confirmation that the router delegated instead of performing the domain work - -## Common Mistakes - -| Mistake | Why it matters | Instead | -| --- | --- | --- | -| Routing generic requests straight to execution | Medium tasks silently expand and cause ownership drift | Fail safe to `internal-planning-leader` when boundaries are not stable | -| Asking multiple clarification questions | The router becomes a hidden planner | Ask at most one question that changes the owner | -| Treating review and challenge as the same lane | Findings and pressure tests have different outputs and escalation paths | Keep `review` and `challenge` distinct | -| Letting retired agents stay mentally canonical | Users keep landing on the old overlap model | Translate old names through the old-to-new table and route to a canonical owner | -| Dispatching to non-canonical owners | The front door stops being predictable and enforceable | Dispatch only to the four canonical owners | -| Continuing into implementation after routing | The router turns into a fifth generalist | Hand off to the selected owner and keep the router out of domain work | diff --git a/.github/skills/internal-agent-routing-engine/agents/openai.yaml b/.github/skills/internal-agent-routing-engine/agents/openai.yaml deleted file mode 100644 index 3f868d9..0000000 --- a/.github/skills/internal-agent-routing-engine/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Internal Agent Routing Engine" - short_description: "Help with Internal Agent Routing Engine tasks" - default_prompt: "Use $internal-agent-routing-engine for this task and follow the repository-owned workflow in the skill." diff --git a/.github/skills/internal-agent-routing-engine/references/owner-examples.md b/.github/skills/internal-agent-routing-engine/references/owner-examples.md deleted file mode 100644 index ac66d71..0000000 --- a/.github/skills/internal-agent-routing-engine/references/owner-examples.md +++ /dev/null @@ -1,52 +0,0 @@ -# Canonical Owner Examples - -Use this reference when routing is still ambiguous after applying the main decision matrix and confidence model. - -## `internal-fast-executor` - -Positive examples: - -- `Update the validator to reject missing frontmatter in one script and one test file.` -- `Fix this broken prompt reference and run the relevant tests.` - -Negative examples: - -- `Decide how to redesign the operational catalog.` -- `Figure out whether we should split or merge these command centers.` - -## `internal-planning-leader` - -Positive examples: - -- `Rationalize the internal agent catalog and define the new routing model.` -- `Create a new repository-owned skill and decide where the shared logic should live.` - -Negative examples: - -- `Change this one test assertion in place.` -- `Review my diff for regressions.` - -## `internal-review-guard` - -Positive examples: - -- `Review this change for merge readiness and regression risk.` -- `Validate whether the new catalog leaves stale references or weak evidence.` - -Negative examples: - -- `Implement the missing routing engine.` -- `Challenge whether the strategy itself is sound before we review code.` - -## `internal-critical-challenger` - -Positive examples: - -- `Stress-test this operating model before we adopt it.` -- `Give me the strongest objections and failure modes for this plan.` -- `Reframe this proposal from a lateral-thinking angle and surface the hidden assumptions.` - -Negative examples: - -- `Write the implementation plan and apply the changes.` -- `Perform a normal code review of the diff.` diff --git a/.github/skills/internal-agent-sync-control-center/agents/openai.yaml b/.github/skills/internal-agent-sync-control-center/agents/openai.yaml deleted file mode 100644 index 53b7c0f..0000000 --- a/.github/skills/internal-agent-sync-control-center/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Internal Agent Sync Control Center" - short_description: "Govern sync catalog decisions safely." - default_prompt: "Use $internal-agent-sync-control-center to audit the managed .github catalog, decide keep/update/extract/retire outcomes, and use the bundled fingerprinting script when deterministic change evidence is needed." diff --git a/.github/skills/internal-agent-sync-control-center/SKILL.md b/.github/skills/internal-agent-sync-external-resources/SKILL.md similarity index 73% rename from .github/skills/internal-agent-sync-control-center/SKILL.md rename to .github/skills/internal-agent-sync-external-resources/SKILL.md index ae2e2d1..2011f80 100644 --- a/.github/skills/internal-agent-sync-control-center/SKILL.md +++ b/.github/skills/internal-agent-sync-external-resources/SKILL.md @@ -1,11 +1,11 @@ --- -name: internal-agent-sync-control-center -description: Use when maintaining the sync-managed `.github/` catalog behind `internal-sync-control-center`, especially for keep/update/extract/retire decisions, approved external refreshes, and governance-drift checks. +name: internal-agent-sync-external-resources +description: Use when maintaining the sync-managed `.github/` catalog behind `internal-sync-external-resources`, especially for keep/update/extract/retire decisions, approved external refreshes, and governance-drift checks. --- -# Internal Agent Sync Control Center +# Internal Agent Sync External Resources -Use this skill as the default operating engine for `.github/agents/internal-sync-control-center.agent.md`. +Use this skill as the default operating engine for `.github/agents/internal-sync-external-resources.agent.md`. This skill owns the reusable catalog-governance procedure behind that agent. Keep the agent focused on routing, managed scope, approval posture, and output contract. Keep the reusable sync workflow, decision rules, and anti-drift checks here. @@ -15,21 +15,25 @@ Use `internal-skill-creator` first when a sync decision requires creating, repla Use `openai-skill-creator` only for the remaining bundle anatomy, helper scripts, progressive disclosure, `agents/openai.yaml`, or structural validation work after `internal-skill-creator` has established the repository-owned skill boundary and decided the local ownership outcome. -Use `internal-agent-development` when the sync changes the control-center agent, rewrites agent routing boundaries, or changes how the agent/skill split is structured. +Use `internal-agent-development` when the sync changes this external-resources agent, rewrites agent routing boundaries, or changes how the agent/skill split is structured. When deterministic change detection matters, read `references/fingerprinting-contract.md`, use the canonical repository implementation in `.github/scripts/lib/fingerprinting.py`, and use `scripts/sync_resource_fingerprint.py` from this skill only as a thin workflow wrapper. +When an imported upstream asset has an exceptionally approved repo-local override, read `references/imported-asset-overrides.yaml` and use `scripts/apply_imported_asset_overrides.py` to replay the registered patch bundle after refreshing the upstream content. + ## When to use -- Maintain the sync-managed `.github/` catalog behind `internal-sync-control-center`. +- Maintain the sync-managed `.github/` catalog behind `internal-sync-external-resources`. - Make keep, update, extract, retire, or approved external-refresh decisions across the managed catalog. +- Keep approved imported-asset override exceptions explicit, replayable, and auditable instead of leaving hidden forks. - Resolve governance drift, overlap, or managed-scope ambiguity in the source repository. ## Goals - Keep one clear canonical asset per intent across the managed `.github/` catalog. -- Make `internal-sync-control-center` visibly depend on one named operating engine instead of an implicit catalog skill. +- Make `internal-sync-external-resources` visibly depend on one named operating engine instead of an implicit catalog skill. - Refresh only approved in-scope external-prefixed assets without expanding scope accidentally. +- Keep approved imported in-place exceptions narrow, mapped, and re-applicable after future refreshes. - Move reusable sync procedure into this skill instead of bloating the agent body. - Keep naming, frontmatter, links, descriptions, and governance references deterministic. - Remove fallback, alias, deprecated, or compatibility-only drift in the same pass that introduces the canonical replacement. @@ -39,20 +43,23 @@ When deterministic change detection matters, read `references/fingerprinting-con ## Agent Coupling Contract -For `internal-sync-control-center`, keep the split strict: +For `internal-sync-external-resources`, keep the split strict: - Agent owns routing, scope boundaries, managed resource map, approval posture, and output expectations. - This skill owns audit order, keep/update/extract/retire decisions, anti-overlap heuristics, and sync execution discipline. - `internal-agent-development` owns structural changes to the agent itself, including mandatory engine-skill architecture and boundary rewrites. - `internal-skill-creator` owns repository-owned skill authoring and should be the first local route when one concrete skill needs creation, replacement, or major redesign. - `openai-skill-creator` covers only the remaining bundle mechanics during that work; it should not replace the local decision gate or duplicate repository-owned routing logic. +- `references/imported-asset-overrides.yaml` owns the approved imported in-place override registry for this repository. +- `scripts/apply_imported_asset_overrides.py` owns patch replay after an upstream refresh; prefer a clean replay first, allow a registered `git apply --3way` fallback when upstream text drift is compatible, and stop for review instead of forcing a hidden fork. Do not collapse these roles back into one file just because the current task touches all of them. ## Decision Order -1. Check the declared managed scope in `internal-sync-control-center` plus the live local inventory and nearby trigger space. +1. Check the declared managed scope in `internal-sync-external-resources` plus the live local inventory and nearby trigger space. 2. Decide whether the capability should remain an `internal-*` asset, remain an approved in-scope external-prefixed asset, or be retired. +3. For imported assets, prefer verbatim refresh first. Allow a direct in-place override only when the reason is strong, the user explicitly counter-validates it, and the replay patch is registered in this skill bundle. 3. Prefer consolidation over coexistence when two assets compete for the same trigger space. 4. Repair broken references only when the asset still adds distinct value to the declared catalog. 5. Apply the canonical change first, then remove deprecated duplicates, stale references, and hollow dependencies in the same pass. @@ -63,8 +70,9 @@ Do not collapse these roles back into one file just because the current task tou | Case | Action | | --- | --- | | Repo-specific sync workflow or governance logic | Create or update an `internal-*` asset | -| Control-center reusable operating logic | Keep it in this skill | +| External-resources reusable operating logic | Keep it in this skill | | Installed external-prefixed asset still useful and declared in scope | Refresh in place | +| Imported asset needs a rare repo-local exception after refresh | Require explicit user counter-validation, register the patch in `references/imported-asset-overrides.yaml`, and replay it with `scripts/apply_imported_asset_overrides.py` | | Thin alias, fallback copy, or deprecated variant | Delete the weaker asset | | Broken or stale asset with no unique value | Retire it | | Installed capability is still distinct but low-frequency or on-demand | Keep it as dormant support depth and document why; do not wrap it unless the root wrapper threshold is met | @@ -94,6 +102,7 @@ Use these heuristics: - Keep dormant imported or internal capabilities when they still provide distinct on-demand value and the root wrapper threshold is not met. - Create or update an internal asset when the capability is strategic for this repository and should not depend on external wording or lifecycle. - Refresh an in-scope external-prefixed asset only when it still adds distinct value to the declared managed catalog. +- For imported assets with approved repo-local exceptions, refresh the upstream content first and replay only the registered patch bundle afterward. ### 3. Author or Refresh Carefully @@ -129,7 +138,17 @@ When a sync workflow needs evidence that a managed resource truly changed: - Do not introduce hashing manifests or helper scripts as decorative machinery; add them only when they clearly reduce false positives, repeated work, or unsafe refresh decisions. - Use the normalization rules, manifest schema, and output defaults from `references/fingerprinting-contract.md` instead of forking them inline. -### 5. Re-check Governance Immediately +### 5. Replay Approved Imported Overrides + +When an imported upstream asset has an approved repo-local exception: + +1. Refresh the imported asset verbatim from the declared upstream source. +2. Check that the target path is listed in `references/imported-asset-overrides.yaml`. +3. Run `scripts/apply_imported_asset_overrides.py --id ` or the full bundle when replaying every approved override after the refresh. +4. If clean replay fails, allow only the registered `git apply --3way` fallback. If that also fails, or if the post-apply content hash does not match the registry, stop and review the exception instead of forcing the patch through. +5. Reassess whether an `internal-*` wrapper or replacement now serves the repository better than continuing the imported override. + +### 6. Re-check Governance Immediately After catalog changes: @@ -152,11 +171,14 @@ Before finishing: - Confirm the agent still names this skill explicitly as its engine or default operating workflow. - Confirm the change did not leave decorative skill declarations behind. - Confirm no fallback alias or compatibility-only duplicate remains beside the canonical asset. +- Confirm every approved imported in-place override is registered in `references/imported-asset-overrides.yaml`, has a live patch file, and still matches the expected normalized content hash. ## Anti-Patterns - Keeping duplicate assets "just in case." - Refreshing an external asset just because upstream changed when the local catalog does not need it. +- Leaving a repo-local imported override undocumented, unapproved, or without a replay patch. +- Forcing a replay patch after `git apply --check` failed. - Creating machinery-heavy sync helpers that never become part of a real workflow. - Creating a control-center engine skill that merely says "see another skill." - Leaving retired or deprecated assets in the live catalog. @@ -164,7 +186,7 @@ Before finishing: ## Handoff -When this skill is used from `internal-sync-control-center`: +When this skill is used from `internal-sync-external-resources`: 1. Audit the catalog. 2. Decide keep, refresh, replace, extract, or retire. diff --git a/.github/skills/internal-agent-sync-external-resources/agents/openai.yaml b/.github/skills/internal-agent-sync-external-resources/agents/openai.yaml new file mode 100644 index 0000000..3e5a93a --- /dev/null +++ b/.github/skills/internal-agent-sync-external-resources/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Internal Agent Sync External Resources" + short_description: "Govern sync catalog decisions safely." + default_prompt: "Use $internal-agent-sync-external-resources to audit the managed .github catalog, decide keep/update/extract/retire outcomes, and use the bundled fingerprinting script when deterministic change evidence is needed." diff --git a/.github/skills/internal-agent-sync-external-resources/patches/obra-brainstorming.patch b/.github/skills/internal-agent-sync-external-resources/patches/obra-brainstorming.patch new file mode 100644 index 0000000..67c7b69 --- /dev/null +++ b/.github/skills/internal-agent-sync-external-resources/patches/obra-brainstorming.patch @@ -0,0 +1,51 @@ +diff --git a/.github/skills/obra-brainstorming/SKILL.md b/.github/skills/obra-brainstorming/SKILL.md +index dc61439..7be32fc 100644 +--- a/.github/skills/obra-brainstorming/SKILL.md ++++ b/.github/skills/obra-brainstorming/SKILL.md +@@ -1,6 +1,6 @@ + --- + name: obra-brainstorming +-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." ++description: "Use before creative or design-ambiguous work that needs option exploration and design approval before implementation." + --- + + # Brainstorming Ideas Into Designs +@@ -9,13 +9,17 @@ Help turn ideas into fully formed designs and specs through natural collaborativ + + Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval. + ++Use this workflow only when the work still needs option exploration, design decisions, or explicit user approval before implementation. ++ ++Do not use this workflow for deterministic repository-owned maintenance of prompt, skill, agent, instruction, or Markdown assets when the target state is already clear and concrete verification exists. ++ + +-Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity. ++Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies when the task is creative or design-ambiguous enough that the implementation path is not already settled. + + +-## Anti-Pattern: "This Is Too Simple To Need A Design" ++## Anti-Pattern: "Every Change Needs Brainstorming" + +-Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval. ++Not every change needs this process. Use it for creative work, unclear requirements, or design ambiguity. Deterministic maintenance, governed text realignment, and other already-designed updates should skip brainstorming and move straight to the right execution or review workflow. + + ## Checklist + +@@ -26,7 +30,7 @@ You MUST create a task for each of these items and complete them in order: + 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria + 4. **Propose 2-3 approaches** — with trade-offs and your recommendation + 5. **Present design** — in sections scaled to their complexity, get user approval after each section +-6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit ++6. **Write design doc** — save to `tmp/superpowers/specs/YYYY-MM-DD--design.md` and commit + 7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below) + 8. **User reviews written spec** — ask user to review the spec file before proceeding + 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan +@@ -108,7 +112,7 @@ digraph brainstorming { + + **Documentation:** + +-- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD--design.md` ++- Write the validated design (spec) to `tmp/superpowers/specs/YYYY-MM-DD--design.md` + - (User preferences for spec location override this default) + - Use elements-of-style:writing-clearly-and-concisely skill if available + - Commit the design document to git diff --git a/.github/skills/internal-agent-sync-external-resources/patches/obra-requesting-code-review.patch b/.github/skills/internal-agent-sync-external-resources/patches/obra-requesting-code-review.patch new file mode 100644 index 0000000..de64835 --- /dev/null +++ b/.github/skills/internal-agent-sync-external-resources/patches/obra-requesting-code-review.patch @@ -0,0 +1,34 @@ +diff --git a/.github/skills/obra-requesting-code-review/SKILL.md b/.github/skills/obra-requesting-code-review/SKILL.md +index b447a98..00cfb2f 100644 +--- a/.github/skills/obra-requesting-code-review/SKILL.md ++++ b/.github/skills/obra-requesting-code-review/SKILL.md +@@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m + + # Requesting Code Review + +-Dispatch internal-code-review subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work. ++Dispatch `internal-review-guard` to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work. + + **Core principle:** Review early, review often. + +@@ -31,7 +31,7 @@ HEAD_SHA=$(git rev-parse HEAD) + + **2. Dispatch code-reviewer subagent:** + +-Use Task tool with internal-code-review type, fill template at `code-reviewer.md` ++Use Task tool with `internal-review-guard` type, fill template at `code-reviewer.md` + + **Placeholders:** + - `{WHAT_WAS_IMPLEMENTED}` - What you just built +@@ -56,9 +56,9 @@ You: Let me request code review before proceeding. + BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}') + HEAD_SHA=$(git rev-parse HEAD) + +-[Dispatch internal-code-review subagent] ++[Dispatch internal-review-guard] + WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index +- PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md ++ PLAN_OR_REQUIREMENTS: Task 2 from tmp/superpowers/plans/deployment-plan.md + BASE_SHA: a7981ec + HEAD_SHA: 3df7661 + DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types diff --git a/.github/skills/internal-agent-sync-external-resources/patches/obra-subagent-driven-development.patch b/.github/skills/internal-agent-sync-external-resources/patches/obra-subagent-driven-development.patch new file mode 100644 index 0000000..6a993d3 --- /dev/null +++ b/.github/skills/internal-agent-sync-external-resources/patches/obra-subagent-driven-development.patch @@ -0,0 +1,13 @@ +diff --git a/.github/skills/obra-subagent-driven-development/SKILL.md b/.github/skills/obra-subagent-driven-development/SKILL.md +index ef032b4..0f4bc53 100644 +--- a/.github/skills/obra-subagent-driven-development/SKILL.md ++++ b/.github/skills/obra-subagent-driven-development/SKILL.md +@@ -128,7 +128,7 @@ Implementer subagents report one of four statuses. Handle each appropriately: + ``` + You: I'm using Subagent-Driven Development to execute this plan. + +-[Read plan file once: docs/superpowers/plans/feature-plan.md] ++[Read plan file once: tmp/superpowers/plans/feature-plan.md] + [Extract all 5 tasks with full text and context] + [Create TodoWrite with all tasks] + diff --git a/.github/skills/internal-agent-sync-external-resources/patches/obra-test-driven-development.patch b/.github/skills/internal-agent-sync-external-resources/patches/obra-test-driven-development.patch new file mode 100644 index 0000000..2619481 --- /dev/null +++ b/.github/skills/internal-agent-sync-external-resources/patches/obra-test-driven-development.patch @@ -0,0 +1,31 @@ +diff --git a/.github/skills/obra-test-driven-development/SKILL.md b/.github/skills/obra-test-driven-development/SKILL.md +index a64beb0..1da6c6e 100644 +--- a/.github/skills/obra-test-driven-development/SKILL.md ++++ b/.github/skills/obra-test-driven-development/SKILL.md +@@ -9,13 +9,17 @@ description: Use when implementing any feature or bugfix, before writing impleme + + Write the test first. Watch it fail. Write minimal code to pass. + ++Use this workflow when the outcome is executable and a failing test can prove the contract. ++ ++Do not treat this workflow as the default for prompt, skill, agent, instruction, or Markdown authoring when the change is textual or governance-only and no meaningful test-first loop exists. ++ + **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing. + + **Violating the letter of the rules is violating the spirit of the rules.** + + ## When to Use + +-**Always:** ++**Always for executable behavior:** + - New features + - Bug fixes + - Refactoring +@@ -25,6 +29,7 @@ Write the test first. Watch it fail. Write minimal code to pass. + - Throwaway prototypes + - Generated code + - Configuration files ++- Textual or governance-only authoring with no meaningful executable contract + + Thinking "skip TDD just this once"? Stop. That's rationalization. + diff --git a/.github/skills/internal-agent-sync-external-resources/patches/obra-writing-plans.patch b/.github/skills/internal-agent-sync-external-resources/patches/obra-writing-plans.patch new file mode 100644 index 0000000..e3bfc41 --- /dev/null +++ b/.github/skills/internal-agent-sync-external-resources/patches/obra-writing-plans.patch @@ -0,0 +1,41 @@ +diff --git a/.github/skills/obra-writing-plans/SKILL.md b/.github/skills/obra-writing-plans/SKILL.md +index f5243fb..bf18631 100644 +--- a/.github/skills/obra-writing-plans/SKILL.md ++++ b/.github/skills/obra-writing-plans/SKILL.md +@@ -1,6 +1,6 @@ + --- + name: obra-writing-plans +-description: Use when you have a spec or requirements for a multi-step task, before touching code ++description: Use when a multi-step implementation effort still needs an explicit plan before execution + --- + + # Writing Plans +@@ -9,13 +9,17 @@ description: Use when you have a spec or requirements for a multi-step task, bef + + Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. + ++Use this workflow when the steps, sequencing, or validation still need an explicit written plan before execution. ++ ++Do not use this workflow as the default gate for deterministic repository-owned maintenance or realignment when the desired change is already clear and concretely verifiable. ++ + Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well. + + **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." + +-**Context:** This should be run in a dedicated worktree (created by brainstorming skill). ++**Context:** If brainstorming created a dedicated worktree, keep using it. Otherwise, use this workflow only when the task is already scoped enough to plan directly. + +-**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-.md` ++**Save plans to:** `tmp/superpowers/plans/YYYY-MM-DD-.md` + - (User preferences for plan location override this default) + + ## Scope Check +@@ -135,7 +139,7 @@ If you find issues, fix them inline. No need to re-review — just fix and move + + After saving the plan, offer execution choice: + +-**"Plan complete and saved to `docs/superpowers/plans/.md`. Two execution options:** ++**"Plan complete and saved to `tmp/superpowers/plans/.md`. Two execution options:** + + **1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration + diff --git a/.github/skills/internal-agent-sync-control-center/references/catalog-decision-checklist.md b/.github/skills/internal-agent-sync-external-resources/references/catalog-decision-checklist.md similarity index 64% rename from .github/skills/internal-agent-sync-control-center/references/catalog-decision-checklist.md rename to .github/skills/internal-agent-sync-external-resources/references/catalog-decision-checklist.md index ed0508e..face649 100644 --- a/.github/skills/internal-agent-sync-control-center/references/catalog-decision-checklist.md +++ b/.github/skills/internal-agent-sync-external-resources/references/catalog-decision-checklist.md @@ -24,9 +24,21 @@ When refreshing an installed external-prefixed asset: 4. Do not add new sibling assets from the same family unless the user explicitly expands scope. 5. Update governance files only when routing or inventory meaningfully changes. +## Approved Imported Override Rules + +Use a direct imported in-place override only when all of these are true: + +- the repo-specific need is strong enough that a wrapper or replacement is not the better immediate fix +- the user explicitly counter-validates the exception +- the target is registered in `references/imported-asset-overrides.yaml` +- the replay patch lives under `patches/` +- the override can be replayed after a verbatim upstream refresh without manual guesswork + +Refresh upstream content first, then replay the registered patch. Prefer a clean replay first; if the registry allows `git apply --3way`, use that fallback only when upstream text drift is still compatible. If neither path applies cleanly, stop and review the exception instead of forcing it. + ## Extraction Rules -When `internal-sync-control-center` or a nearby sync asset is turning into a knowledge dump: +When `internal-sync-external-resources` or a nearby sync asset is turning into a knowledge dump: 1. Keep the agent cohesive around routing, managed scope, approval posture, and orchestration. 2. Move long reusable procedures into this skill or the right existing internal skill. diff --git a/.github/skills/internal-agent-sync-control-center/references/fingerprinting-contract.md b/.github/skills/internal-agent-sync-external-resources/references/fingerprinting-contract.md similarity index 100% rename from .github/skills/internal-agent-sync-control-center/references/fingerprinting-contract.md rename to .github/skills/internal-agent-sync-external-resources/references/fingerprinting-contract.md diff --git a/.github/skills/internal-agent-sync-external-resources/references/imported-asset-overrides.yaml b/.github/skills/internal-agent-sync-external-resources/references/imported-asset-overrides.yaml new file mode 100644 index 0000000..9f570c9 --- /dev/null +++ b/.github/skills/internal-agent-sync-external-resources/references/imported-asset-overrides.yaml @@ -0,0 +1,82 @@ +version: 1 +policy: + default_rule: keep imported upstream assets verbatim + exception_rule: >- + Allow a direct imported-asset override only for a strong repo-specific need + that the user explicitly counter-validates, then register the replay patch + in this bundle before treating the override as active. + replay_rule: >- + Prefer a clean patch replay first, then allow a registered `git apply + --3way` fallback when upstream text drift is compatible. Stop for review if + neither path applies cleanly. +overrides: + - id: obra-brainstorming-workflow-review + target_path: .github/skills/obra-brainstorming/SKILL.md + source_family: obra/superpowers + lifecycle_mode: post-refresh-patch + apply_strategy: git-apply-3way + approval: explicit-user-counter-validated + reason: >- + Narrow brainstorming to creative or design-ambiguous work and align + transient spec artifacts to tmp/superpowers. + patch_path: patches/obra-brainstorming.patch + expected_content_hash: 9e0c6c59b1138312f6cff04f33f4e56e51b442a1df68f3cf04d1a5d276e4a101 + baseline_repo_commit: "5930521" + local_change_commit: "c4b33b4" + validation_note: Stop the refresh if the patch does not apply cleanly; review whether an internal wrapper should replace the override. + - id: obra-writing-plans-workflow-review + target_path: .github/skills/obra-writing-plans/SKILL.md + source_family: obra/superpowers + lifecycle_mode: post-refresh-patch + apply_strategy: git-apply-3way + approval: explicit-user-counter-validated + reason: >- + Remove planning as the default gate for deterministic maintenance and + align retained plan artifacts to tmp/superpowers. + patch_path: patches/obra-writing-plans.patch + expected_content_hash: 5d997b257b261082b03d48d4bb763140f1b4381450dec0b37639718a4fb9411f + baseline_repo_commit: "5930521" + local_change_commit: "c4b33b4" + validation_note: Stop the refresh if the patch does not apply cleanly; review whether an internal wrapper should replace the override. + - id: obra-test-driven-development-workflow-review + target_path: .github/skills/obra-test-driven-development/SKILL.md + source_family: obra/superpowers + lifecycle_mode: post-refresh-patch + apply_strategy: git-apply-3way + approval: explicit-user-counter-validated + reason: >- + Keep TDD strong for executable behavior without making it a rigid default + for textual governance authoring. + patch_path: patches/obra-test-driven-development.patch + expected_content_hash: f52f1aa7de5190cb0d881553b2a0d4dcc370085868fa78234de6178973115ab9 + baseline_repo_commit: "5930521" + local_change_commit: "c4b33b4" + validation_note: Stop the refresh if the patch does not apply cleanly; review whether an internal wrapper should replace the override. + - id: obra-subagent-driven-development-workflow-review + target_path: .github/skills/obra-subagent-driven-development/SKILL.md + source_family: obra/superpowers + lifecycle_mode: post-refresh-patch + apply_strategy: git-apply-3way + approval: explicit-user-counter-validated + reason: >- + Keep the example plan path aligned with tmp/superpowers so imported + execution guidance does not reintroduce deprecated transient paths. + patch_path: patches/obra-subagent-driven-development.patch + expected_content_hash: e2f01c2c8a79b6e6a05cb3e7315f01c50daabeefce72f251dd6b86a02035180f + baseline_repo_commit: "5930521" + local_change_commit: "c4b33b4" + validation_note: Stop the refresh if the patch does not apply cleanly; review whether an internal wrapper should replace the override. + - id: obra-requesting-code-review-workflow-review + target_path: .github/skills/obra-requesting-code-review/SKILL.md + source_family: obra/superpowers + lifecycle_mode: post-refresh-patch + apply_strategy: git-apply-3way + approval: explicit-user-counter-validated + reason: >- + Keep the reviewer handoff aligned with the canonical internal reviewer and + with tmp/superpowers plan paths. + patch_path: patches/obra-requesting-code-review.patch + expected_content_hash: 404a24c62b9cf001a7b38463dab2a67fe70fb78b6c6c64ae0678697f6833675b + baseline_repo_commit: "5930521" + local_change_commit: "c4b33b4" + validation_note: Stop the refresh if the patch does not apply cleanly; review whether an internal wrapper should replace the override. diff --git a/.github/skills/internal-agent-sync-external-resources/scripts/apply_imported_asset_overrides.py b/.github/skills/internal-agent-sync-external-resources/scripts/apply_imported_asset_overrides.py new file mode 100644 index 0000000..5a36a2c --- /dev/null +++ b/.github/skills/internal-agent-sync-external-resources/scripts/apply_imported_asset_overrides.py @@ -0,0 +1,207 @@ +#!/usr/bin/env python3 +"""Replay registered imported-asset override patches after an upstream refresh.""" + +from __future__ import annotations + +import argparse +import subprocess +import sys +from pathlib import Path + +import yaml + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Apply registered imported-asset override patches." + ) + parser.add_argument( + "--registry", + help="Path to imported-asset-overrides.yaml.", + ) + parser.add_argument( + "--repo-root", + help="Repository root. Defaults to the nearest parent that contains .github/.", + ) + parser.add_argument( + "--id", + action="append", + dest="selected_ids", + help="Apply only the selected override id. Repeatable.", + ) + parser.add_argument( + "--dry-run", + action="store_true", + help="Check patch applicability without writing changes.", + ) + return parser.parse_args() + + +def main() -> int: + args = parse_args() + repo_root = ( + find_repo_root(Path(args.repo_root)) + if args.repo_root + else find_repo_root(Path.cwd()) + ) + skill_root = ( + Path(args.registry).resolve().parent.parent + if args.registry + else Path(__file__).resolve().parent.parent + ) + registry_path = ( + Path(args.registry).resolve() + if args.registry + else skill_root / "references/imported-asset-overrides.yaml" + ) + overrides = load_registry(registry_path) + selected = select_overrides(overrides, args.selected_ids) + if not selected: + print("No imported-asset overrides selected.", file=sys.stderr) + return 1 + + sys.path.insert(0, str((repo_root / ".github/scripts").resolve())) + from lib.fingerprinting import build_fingerprint # pylint: disable=import-error + + for override in selected: + override_id = override["id"] + patch_path = (skill_root / override["patch_path"]).resolve() + target_path = repo_root / override["target_path"] + if not patch_path.is_file(): + print(f"[error] missing patch file for {override_id}: {patch_path}", file=sys.stderr) + return 1 + if not target_path.is_file(): + print(f"[error] missing target file for {override_id}: {target_path}", file=sys.stderr) + return 1 + + apply_strategy = override.get("apply_strategy", "git-apply") + patch_status = detect_patch_status(repo_root, patch_path, apply_strategy=apply_strategy) + if patch_status == "conflict": + print( + f"[error] patch does not apply cleanly for {override_id}; stop and review the override.", + file=sys.stderr, + ) + return 1 + + if args.dry_run: + if patch_status == "already-applied": + print(f"[dry-run] {override_id}: patch already applied") + elif patch_status == "applicable-with-3way": + print( + f"[dry-run] {override_id}: patch needs 3-way replay " + f"({apply_strategy}) because upstream text changed" + ) + else: + print(f"[dry-run] {override_id}: patch applies cleanly") + continue + + if patch_status == "already-applied": + print(f"[skipped] {override_id}: patch already applied") + continue + + apply_cmd = build_apply_command(patch_path, patch_status) + if run_git(apply_cmd, repo_root) != 0: + print(f"[error] failed to apply patch for {override_id}", file=sys.stderr) + return 1 + + expected_hash = override["expected_content_hash"] + actual_hash = build_fingerprint(repo_root, target_path).content_hash + if actual_hash != expected_hash: + print( + f"[error] patched content hash mismatch for {override_id}: " + f"expected {expected_hash}, got {actual_hash}", + file=sys.stderr, + ) + return 1 + + if patch_status == "applicable-with-3way": + print(f"[applied] {override_id}: {override['target_path']} via 3-way replay") + else: + print(f"[applied] {override_id}: {override['target_path']}") + + return 0 + + +def find_repo_root(start: Path) -> Path: + candidate = start.resolve() + for current in (candidate, *candidate.parents): + if (current / ".github").is_dir(): + return current + raise FileNotFoundError(f"Unable to find repository root from {start}") + + +def load_registry(path: Path) -> list[dict[str, str]]: + payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {} + overrides = payload.get("overrides") + if not isinstance(overrides, list): + raise ValueError("Registry must define an overrides list.") + normalized: list[dict[str, str]] = [] + for item in overrides: + if not isinstance(item, dict): + raise ValueError("Each override entry must be a mapping.") + normalized.append({key: str(value) for key, value in item.items()}) + return normalized + + +def select_overrides( + overrides: list[dict[str, str]], selected_ids: list[str] | None +) -> list[dict[str, str]]: + if not selected_ids: + return overrides + selected_set = set(selected_ids) + return [override for override in overrides if override.get("id") in selected_set] + + +def run_git(command: list[str], repo_root: Path, quiet: bool = False) -> int: + completed = subprocess.run( + command, + cwd=repo_root, + text=True, + capture_output=True, + check=False, + ) + if not quiet and completed.stdout.strip(): + print(completed.stdout.strip()) + if not quiet and completed.stderr.strip(): + print(completed.stderr.strip(), file=sys.stderr) + return completed.returncode + + +def build_apply_command(patch_path: Path, patch_status: str) -> list[str]: + command = ["git", "apply"] + if patch_status == "applicable-with-3way": + command.append("--3way") + command.append(patch_path.as_posix()) + return command + + +def detect_patch_status( + repo_root: Path, + patch_path: Path, + apply_strategy: str = "git-apply", +) -> str: + if run_git(["git", "apply", "--check", patch_path.as_posix()], repo_root, quiet=True) == 0: + return "applicable" + if ( + run_git( + ["git", "apply", "--reverse", "--check", patch_path.as_posix()], + repo_root, + quiet=True, + ) + == 0 + ): + return "already-applied" + if apply_strategy == "git-apply-3way" and ( + run_git( + ["git", "apply", "--3way", "--check", patch_path.as_posix()], + repo_root, + quiet=True, + ) + == 0 + ): + return "applicable-with-3way" + return "conflict" + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.github/skills/internal-agent-sync-control-center/scripts/sync_resource_fingerprint.py b/.github/skills/internal-agent-sync-external-resources/scripts/sync_resource_fingerprint.py similarity index 100% rename from .github/skills/internal-agent-sync-control-center/scripts/sync_resource_fingerprint.py rename to .github/skills/internal-agent-sync-external-resources/scripts/sync_resource_fingerprint.py diff --git a/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md b/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md index c1b2d58..69b7ead 100644 --- a/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md +++ b/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md @@ -26,6 +26,7 @@ The paired agent should not restate default mode handling, preserved `local-*` b - Treat this repository as the source of truth. - Keep target assumptions narrow: GitHub Copilot assets live under `.github/` and `AGENTS.md` stays at repository root. - Preserve target `local-*` assets under mirrored categories, preserve the target consumer-local GitHub instructions overrides file after materialization, and delete target-only non-local assets there during `apply`. +- When the source baseline includes an approved imported-asset override registry plus replay patches, mirror that governance bundle as source-managed state instead of recreating target-local hidden forks on imported assets. - Exclude source resources named `internal-sync-*` from consumer mirroring and remove any target copies of those resources during `apply`. - Materialize the source template `.github/local-github-instructions-overrides.md.template` into the consumer target as the consumer-local GitHub instructions overrides file when that target file is missing, then preserve target-authored changes there on later sync runs. - Keep root guidance layered: `AGENTS.md` is the bridge, `.github/copilot-instructions.md` is the repo-wide projection, the consumer-local GitHub instructions overrides file is the consumer-local exception layer, and `.github/INVENTORY.md` is the live catalog. diff --git a/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md b/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md index 636ab51..b35296a 100644 --- a/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md +++ b/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md @@ -79,6 +79,8 @@ Use the closest existing checks for the touched behavior: If a dedicated contract test is missing, call out the gap explicitly. +After `apply`, run the closest target-local catalog or contract validation when preserved `local-*` assets, preserved consumer-local GitHub instructions overrides, or other target-owned assets can still expose latent drift. Treat any resulting fixes as consumer-local follow-up work, not as source-baseline drift, unless the same finding reproduces against the source-managed assets themselves. + ## Reporting Contract Completed runs should make these facts visible: diff --git a/.github/skills/internal-copilot-instructions-creator/SKILL.md b/.github/skills/internal-copilot-instructions-creator/SKILL.md index 37e655b..443c61b 100644 --- a/.github/skills/internal-copilot-instructions-creator/SKILL.md +++ b/.github/skills/internal-copilot-instructions-creator/SKILL.md @@ -59,4 +59,4 @@ Use this skill when the output should be an auto-applied instruction file. If th - Inspect nearby instruction files and follow existing frontmatter and prose patterns. - Re-check that example globs, commands, and snippets are correct enough to survive direct reuse. - Smoke-test the replacement mentally against a representative Copilot authoring request before retiring an imported guide. -- Re-check `.github/INVENTORY.md`, `.github/README.md`, and `.github/agents/internal-sync-control-center.agent.md` when the live instruction catalog changes. +- Re-check `.github/INVENTORY.md`, `.github/README.md`, and `.github/agents/internal-sync-external-resources.agent.md` when the live instruction catalog changes. diff --git a/.github/skills/internal-copilot-instructions-creator/references/review-checklist.md b/.github/skills/internal-copilot-instructions-creator/references/review-checklist.md index 5509e43..9038822 100644 --- a/.github/skills/internal-copilot-instructions-creator/references/review-checklist.md +++ b/.github/skills/internal-copilot-instructions-creator/references/review-checklist.md @@ -22,7 +22,7 @@ Load this file before finalizing, replacing, or deleting an instruction file. - `INVENTORY.md` matches the live instruction list. - `.github/README.md` counts and family summaries match the catalog after adds or removals. -- `.github/agents/internal-sync-control-center.agent.md` still reflects the managed imported instruction list after imported assets are replaced or retired. +- `.github/agents/internal-sync-external-resources.agent.md` still reflects the managed imported instruction list after imported assets are replaced or retired. ## Replacement Checks diff --git a/.github/skills/internal-executing-plans/SKILL.md b/.github/skills/internal-executing-plans/SKILL.md index 12949da..627c3d0 100644 --- a/.github/skills/internal-executing-plans/SKILL.md +++ b/.github/skills/internal-executing-plans/SKILL.md @@ -7,7 +7,7 @@ description: Use when executing a repository-owned plan from tmp/superpowers/ -Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity. +Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies when the task is creative or design-ambiguous enough that the implementation path is not already settled. -## Anti-Pattern: "This Is Too Simple To Need A Design" +## Anti-Pattern: "Every Change Needs Brainstorming" -Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval. +Not every change needs this process. Use it for creative work, unclear requirements, or design ambiguity. Deterministic maintenance, governed text realignment, and other already-designed updates should skip brainstorming and move straight to the right execution or review workflow. ## Checklist @@ -26,7 +30,7 @@ You MUST create a task for each of these items and complete them in order: 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria 4. **Propose 2-3 approaches** — with trade-offs and your recommendation 5. **Present design** — in sections scaled to their complexity, get user approval after each section -6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit +6. **Write design doc** — save to `tmp/superpowers/specs/YYYY-MM-DD--design.md` and commit 7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below) 8. **User reviews written spec** — ask user to review the spec file before proceeding 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan @@ -108,7 +112,7 @@ digraph brainstorming { **Documentation:** -- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD--design.md` +- Write the validated design (spec) to `tmp/superpowers/specs/YYYY-MM-DD--design.md` - (User preferences for spec location override this default) - Use elements-of-style:writing-clearly-and-concisely skill if available - Commit the design document to git diff --git a/.github/skills/obra-brainstorming/spec-document-reviewer-prompt.md b/.github/skills/obra-brainstorming/spec-document-reviewer-prompt.md index 35acbb6..e21f52f 100644 --- a/.github/skills/obra-brainstorming/spec-document-reviewer-prompt.md +++ b/.github/skills/obra-brainstorming/spec-document-reviewer-prompt.md @@ -4,7 +4,7 @@ Use this template when dispatching a spec document reviewer subagent. **Purpose:** Verify the spec is complete, consistent, and ready for implementation planning. -**Dispatch after:** Spec document is written to docs/superpowers/specs/ +**Dispatch after:** Spec document is written to tmp/superpowers/specs/ ``` Task tool (general-purpose): diff --git a/.github/skills/obra-requesting-code-review/SKILL.md b/.github/skills/obra-requesting-code-review/SKILL.md index 91f8cf5..00cfb2f 100644 --- a/.github/skills/obra-requesting-code-review/SKILL.md +++ b/.github/skills/obra-requesting-code-review/SKILL.md @@ -58,7 +58,7 @@ HEAD_SHA=$(git rev-parse HEAD) [Dispatch internal-review-guard] WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index - PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md + PLAN_OR_REQUIREMENTS: Task 2 from tmp/superpowers/plans/deployment-plan.md BASE_SHA: a7981ec HEAD_SHA: 3df7661 DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types diff --git a/.github/skills/obra-subagent-driven-development/SKILL.md b/.github/skills/obra-subagent-driven-development/SKILL.md index ef032b4..0f4bc53 100644 --- a/.github/skills/obra-subagent-driven-development/SKILL.md +++ b/.github/skills/obra-subagent-driven-development/SKILL.md @@ -128,7 +128,7 @@ Implementer subagents report one of four statuses. Handle each appropriately: ``` You: I'm using Subagent-Driven Development to execute this plan. -[Read plan file once: docs/superpowers/plans/feature-plan.md] +[Read plan file once: tmp/superpowers/plans/feature-plan.md] [Extract all 5 tasks with full text and context] [Create TodoWrite with all tasks] diff --git a/.github/skills/obra-test-driven-development/SKILL.md b/.github/skills/obra-test-driven-development/SKILL.md index a64beb0..1da6c6e 100644 --- a/.github/skills/obra-test-driven-development/SKILL.md +++ b/.github/skills/obra-test-driven-development/SKILL.md @@ -9,13 +9,17 @@ description: Use when implementing any feature or bugfix, before writing impleme Write the test first. Watch it fail. Write minimal code to pass. +Use this workflow when the outcome is executable and a failing test can prove the contract. + +Do not treat this workflow as the default for prompt, skill, agent, instruction, or Markdown authoring when the change is textual or governance-only and no meaningful test-first loop exists. + **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing. **Violating the letter of the rules is violating the spirit of the rules.** ## When to Use -**Always:** +**Always for executable behavior:** - New features - Bug fixes - Refactoring @@ -25,6 +29,7 @@ Write the test first. Watch it fail. Write minimal code to pass. - Throwaway prototypes - Generated code - Configuration files +- Textual or governance-only authoring with no meaningful executable contract Thinking "skip TDD just this once"? Stop. That's rationalization. diff --git a/.github/skills/obra-writing-plans/SKILL.md b/.github/skills/obra-writing-plans/SKILL.md index f5243fb..bf18631 100644 --- a/.github/skills/obra-writing-plans/SKILL.md +++ b/.github/skills/obra-writing-plans/SKILL.md @@ -1,6 +1,6 @@ --- name: obra-writing-plans -description: Use when you have a spec or requirements for a multi-step task, before touching code +description: Use when a multi-step implementation effort still needs an explicit plan before execution --- # Writing Plans @@ -9,13 +9,17 @@ description: Use when you have a spec or requirements for a multi-step task, bef Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. +Use this workflow when the steps, sequencing, or validation still need an explicit written plan before execution. + +Do not use this workflow as the default gate for deterministic repository-owned maintenance or realignment when the desired change is already clear and concretely verifiable. + Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well. **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." -**Context:** This should be run in a dedicated worktree (created by brainstorming skill). +**Context:** If brainstorming created a dedicated worktree, keep using it. Otherwise, use this workflow only when the task is already scoped enough to plan directly. -**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-.md` +**Save plans to:** `tmp/superpowers/plans/YYYY-MM-DD-.md` - (User preferences for plan location override this default) ## Scope Check @@ -135,7 +139,7 @@ If you find issues, fix them inline. No need to re-review — just fix and move After saving the plan, offer execution choice: -**"Plan complete and saved to `docs/superpowers/plans/.md`. Two execution options:** +**"Plan complete and saved to `tmp/superpowers/plans/.md`. Two execution options:** **1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration diff --git a/.github/workflows/catalog-validation.yml b/.github/workflows/_github-catalog-validation.yml similarity index 83% rename from .github/workflows/catalog-validation.yml rename to .github/workflows/_github-catalog-validation.yml index aa8c050..4d231b2 100644 --- a/.github/workflows/catalog-validation.yml +++ b/.github/workflows/_github-catalog-validation.yml @@ -1,4 +1,4 @@ -name: 20 🕵️‍♀️ catalog-validation +name: 20 🕵️‍♀️ _github-catalog-validation on: pull_request: @@ -31,7 +31,7 @@ permissions: contents: read concurrency: - group: catalog-validation-${{ github.ref }} + group: _github-catalog-validation-${{ github.ref }} cancel-in-progress: true jobs: @@ -56,10 +56,10 @@ jobs: - name: Run repository validation targets run: | set -euo pipefail - ./.github/scripts/catalog_validation.sh --skip-token-risks + bash ./.github/scripts/github_catalog_validation.sh --skip-token-risks - name: Run dedicated token-risk scan continue-on-error: true run: | set -euo pipefail - ./.github/scripts/catalog_validation.sh --token-risks-only + bash ./.github/scripts/github_catalog_validation.sh --token-risks-only diff --git a/AGENTS.md b/AGENTS.md index 3501e7b..0ccc836 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,13 +44,17 @@ This file is the stable entrypoint for the repository instruction architecture. - `obra-*` resources are cross-cutting workflow assets. They often help with strategic framing, but may govern tactical or operational work when relevant. - `internal-*` resources are the canonical repository-owned layer. They are tactical by default, but may also be strategic or operational when their contract says so. - Imported upstream resources remain support depth by default. Overlap alone is not enough to fork or wrap them; prefer a repository-owned wrapper or replacement only when routing, governance, terminology, output shape, or safety expectations require repo-local ownership. +- Keep imported upstream assets verbatim by default. Allow a direct in-place override only for a strong repo-specific need that the user explicitly counter-validates, and register that override in the `internal-agent-sync-external-resources` skill bundle so future refreshes can replay it safely. - `local-*` resources remain consumer-local extensions. They are usually tactical or operational, but may be strategic when a consumer repository needs explicit local governance. - When overlap exists, prefer the repository-owned internal owner as canonical and use imported depth as support unless no credible internal owner exists. ## Operational Owner Model -- `internal-router` remains the only active front-door router for the canonical operational catalog. -- `internal-router` may hand work to one selected canonical owner without becoming the domain owner itself; non-router canonical agents may be entered directly or by router handoff, but remain recommendation-only when their boundary breaks unless a narrower scoped contract explicitly allows invoking `internal-router` as a second parallel lane while keeping `internal-router` as the only router. +- `internal-delivery-operator`, `internal-planning-leader`, `internal-review-guard`, and `internal-critical-master` remain the canonical repository-owned operational agents. +- The canonical operational model uses direct entry instead of a repository-owned front-door router. +- When the right lane is unclear, prefer `internal-planning-leader` as the safe fallback. +- Canonical owners remain recommendation-only when their boundary breaks and are not subagent-invoked by default. +- Any future automation between canonical owners must be explicit, narrow, one-directional, and must not create all-to-all dispatch or nested ping-pong. ## Projection Rules diff --git a/INTERNAL_CONTRACT.md b/INTERNAL_CONTRACT.md index b290412..62a4ac7 100644 --- a/INTERNAL_CONTRACT.md +++ b/INTERNAL_CONTRACT.md @@ -179,10 +179,12 @@ Treat the current instruction architecture as the source of truth. Do not infer - canonical operational agents - shared operating-model skills - Expected behavior: - - `internal-router`, `internal-fast-executor`, `internal-planning-leader`, `internal-review-guard`, and `internal-critical-challenger` remain the canonical repository-owned operational agents - - only `internal-router` actively routes and it may invoke one selected canonical owner - - non-router canonical agents may be entered directly by the user or by router handoff - - non-router canonical agents define boundaries and recommendations instead of active delegation + - `internal-delivery-operator`, `internal-planning-leader`, `internal-review-guard`, and `internal-critical-master` remain the canonical repository-owned operational agents + - the default operational model uses direct owner selection instead of a repository-owned front-door router + - ambiguous or mixed-shape entry fails safe to `internal-planning-leader` + - canonical owners define boundaries and recommendations instead of active delegation + - canonical owners are not subagent-invoked by default, so hidden peer dispatch stays opt-in and explicit + - any future peer-automation exception between canonical owners must be narrow, one-directional, auditably bounded, and non-mesh - mandatory and optional skill contracts remain explicit where the operating model depends on them ### Reporting diff --git a/LESSONS_LEARNED.md b/LESSONS_LEARNED.md index ffd99fc..c01540d 100644 --- a/LESSONS_LEARNED.md +++ b/LESSONS_LEARNED.md @@ -22,3 +22,5 @@ This file retains durable lessons discovered while completing tasks in this repo | Date | Lesson | Status | Intended canonical target | | --- | --- | --- | --- | + +No pending lessons currently. diff --git a/Makefile b/Makefile index a47a861..096cbe2 100644 --- a/Makefile +++ b/Makefile @@ -7,10 +7,10 @@ PYTHON_PATHS := .github/scripts/*.py .github/scripts/lib tests .github/skills SCRIPTS_RUNNER := ./.github/scripts/run.sh SCRIPTS_VENV := .github/scripts/.venv -.PHONY: help python-version-check lint catalog-lint catalog-validation test scripts-bootstrap catalog-check catalog-audit inventory-build token-risks skill-lint docs-lint all +.PHONY: help python-version-check lint catalog-lint github-catalog-validation test scripts-bootstrap catalog-check catalog-audit inventory-build token-risks skill-lint docs-lint all help: - @printf '%s\n' 'Targets: lint catalog-lint catalog-validation test scripts-bootstrap catalog-check catalog-audit inventory-build token-risks skill-lint docs-lint all' + @printf '%s\n' 'Targets: lint catalog-lint github-catalog-validation test scripts-bootstrap catalog-check catalog-audit inventory-build token-risks skill-lint docs-lint all' python-version-check: @test -s "$(PYTHON_VERSION_FILE)" || { printf '%s\n' 'Missing or empty .python-version.' >&2; exit 1; } @@ -28,8 +28,8 @@ catalog-lint: python-version-check @if [ -n "$(SHELL_SCRIPTS)" ]; then bash -n $(SHELL_SCRIPTS); else printf '%s\n' 'No Bash scripts to lint.'; fi $(PYTHON) -m compileall $(PYTHON_PATHS) -catalog-validation: python-version-check - @./.github/scripts/catalog_validation.sh +github-catalog-validation: python-version-check + @bash ./github_catalog_validation.sh test: scripts-bootstrap @$(SCRIPTS_VENV)/bin/python -m pytest tests -q diff --git a/catalog_validation.sh b/catalog_validation.sh deleted file mode 100755 index 91ef911..0000000 --- a/catalog_validation.sh +++ /dev/null @@ -1,13 +0,0 @@ -#!/usr/bin/env bash -# -# Purpose: Run the local catalog-validation workflow simulation from the repository root. -# Usage examples: -# ./catalog_validation.sh -# ./catalog_validation.sh --skip-token-risks -# ./catalog_validation.sh --token-risks-only - -set -Eeuo pipefail - -REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -exec "$REPO_ROOT/.github/scripts/catalog_validation.sh" "$@" diff --git a/github_catalog_validation.sh b/github_catalog_validation.sh new file mode 100644 index 0000000..fe38761 --- /dev/null +++ b/github_catalog_validation.sh @@ -0,0 +1,13 @@ +#!/usr/bin/env bash +# +# Purpose: Run the local GitHub catalog validation workflow simulation from the repository root. +# Usage examples: +# bash ./github_catalog_validation.sh +# bash ./github_catalog_validation.sh --skip-token-risks +# bash ./github_catalog_validation.sh --token-risks-only + +set -Eeuo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +exec bash "$REPO_ROOT/.github/scripts/github_catalog_validation.sh" "$@" diff --git a/tests/github/scripts/lib/test_shared.py b/tests/github/scripts/lib/test_shared.py index bc1f139..eac53c1 100644 --- a/tests/github/scripts/lib/test_shared.py +++ b/tests/github/scripts/lib/test_shared.py @@ -61,10 +61,10 @@ def test_local_and_consumer_excluded_path_helpers( def test_find_repo_root_and_resolve_markdown_target(tmp_path: Path) -> None: root = tmp_path - current_file = root / ".github/agents/internal-router.agent.md" + current_file = root / ".github/agents/internal-delivery-operator.agent.md" (root / ".github/agents").mkdir(parents=True, exist_ok=True) (root / "docs").mkdir(parents=True, exist_ok=True) - current_file.write_text("# router\n", encoding="utf-8") + current_file.write_text("# delivery operator\n", encoding="utf-8") assert find_repo_root(root / "nested" / "deeper") == root assert ( diff --git a/tests/github/scripts/test_cli_entrypoints.py b/tests/github/scripts/test_cli_entrypoints.py index d70228f..0329e96 100644 --- a/tests/github/scripts/test_cli_entrypoints.py +++ b/tests/github/scripts/test_cli_entrypoints.py @@ -3,11 +3,13 @@ import argparse import json from pathlib import Path +from types import SimpleNamespace import audit_copilot_catalog import build_inventory import check_catalog_consistency import detect_token_risks +import github_catalog_validation import sync_copilot_catalog import validate_internal_skills @@ -78,6 +80,77 @@ def test_build_inventory_main_rebuilds_inventory_file( assert "Inventory rebuilt successfully." in capsys.readouterr().out +def test_github_catalog_validation_main_runs_required_targets_then_token_risks( + monkeypatch, tmp_path: Path, capsys +) -> None: + initialize_governance_repo(tmp_path, with_inventory=False) + called_targets: list[str] = [] + + def fake_run(command: list[str], cwd: Path, check: bool) -> SimpleNamespace: + assert check is False + assert Path(cwd) == tmp_path + assert command[0] == "make" + called_targets.append(command[1]) + if command[1] == "token-risks": + return SimpleNamespace(returncode=1) + return SimpleNamespace(returncode=0) + + monkeypatch.setattr( + github_catalog_validation, + "parse_args", + lambda: argparse.Namespace( + root=str(tmp_path), + skip_token_risks=False, + token_risks_only=False, + ), + ) + monkeypatch.setattr(github_catalog_validation.subprocess, "run", fake_run) + + exit_code = github_catalog_validation.main() + output = capsys.readouterr().out + + assert exit_code == 0 + assert called_targets == [ + "catalog-lint", + "test", + "skill-lint", + "catalog-check", + "token-risks", + ] + assert ( + "continuing to match .github/workflows/_github-catalog-validation.yml" in output + ) + + +def test_github_catalog_validation_main_honors_token_risks_only( + monkeypatch, tmp_path: Path +) -> None: + initialize_governance_repo(tmp_path, with_inventory=False) + called_targets: list[str] = [] + + def fake_run(command: list[str], cwd: Path, check: bool) -> SimpleNamespace: + assert check is False + assert Path(cwd) == tmp_path + called_targets.append(command[1]) + return SimpleNamespace(returncode=0) + + monkeypatch.setattr( + github_catalog_validation, + "parse_args", + lambda: argparse.Namespace( + root=str(tmp_path), + skip_token_risks=False, + token_risks_only=True, + ), + ) + monkeypatch.setattr(github_catalog_validation.subprocess, "run", fake_run) + + exit_code = github_catalog_validation.main() + + assert exit_code == 0 + assert called_targets == ["token-risks"] + + def test_build_inventory_main_check_detects_inventory_drift( monkeypatch, tmp_path: Path, capsys ) -> None: diff --git a/tests/github/scripts/test_repo_owned_script_coverage.py b/tests/github/scripts/test_repo_owned_script_coverage.py index 4b596db..3112875 100644 --- a/tests/github/scripts/test_repo_owned_script_coverage.py +++ b/tests/github/scripts/test_repo_owned_script_coverage.py @@ -4,6 +4,7 @@ TEST_OWNERS = { "tests/github/scripts/test_cli_entrypoints.py": { + ".github/scripts/github_catalog_validation.py", ".github/scripts/audit_copilot_catalog.py", ".github/scripts/build_inventory.py", ".github/scripts/check_catalog_consistency.py", diff --git a/tests/test_apply_imported_asset_overrides.py b/tests/test_apply_imported_asset_overrides.py new file mode 100644 index 0000000..f1e70ba --- /dev/null +++ b/tests/test_apply_imported_asset_overrides.py @@ -0,0 +1,63 @@ +from __future__ import annotations + +import importlib.util +from pathlib import Path + + +def load_module(): + script_path = Path( + ".github/skills/internal-agent-sync-external-resources/scripts/apply_imported_asset_overrides.py" + ) + spec = importlib.util.spec_from_file_location( + "apply_imported_asset_overrides", script_path + ) + module = importlib.util.module_from_spec(spec) + assert spec is not None + assert spec.loader is not None + spec.loader.exec_module(module) + return module + + +def test_detect_patch_status_uses_registered_3way_fallback(monkeypatch) -> None: + module = load_module() + + commands: list[tuple[str, ...]] = [] + + def fake_run_git(command, repo_root, quiet=False): # noqa: ARG001 + commands.append(tuple(command)) + if command[:3] == ["git", "apply", "--check"]: + return 1 + if command[:4] == ["git", "apply", "--reverse", "--check"]: + return 1 + if command[:4] == ["git", "apply", "--3way", "--check"]: + return 0 + return 1 + + monkeypatch.setattr(module, "run_git", fake_run_git) + + status = module.detect_patch_status( + Path("."), + Path("override.patch"), + apply_strategy="git-apply-3way", + ) + + assert status == "applicable-with-3way" + assert ("git", "apply", "--3way", "--check", "override.patch") in commands + + +def test_build_apply_command_uses_3way_only_when_needed() -> None: + module = load_module() + + patch_path = Path("override.patch") + + assert module.build_apply_command(patch_path, "applicable") == [ + "git", + "apply", + "override.patch", + ] + assert module.build_apply_command(patch_path, "applicable-with-3way") == [ + "git", + "apply", + "--3way", + "override.patch", + ] diff --git a/tests/test_canonical_agents_contract.py b/tests/test_canonical_agents_contract.py index cecf3f0..e86b4f1 100644 --- a/tests/test_canonical_agents_contract.py +++ b/tests/test_canonical_agents_contract.py @@ -5,11 +5,10 @@ import yaml CANONICAL_AGENTS = { - "internal-router": ".github/agents/internal-router.agent.md", - "internal-fast-executor": ".github/agents/internal-fast-executor.agent.md", + "internal-delivery-operator": ".github/agents/internal-delivery-operator.agent.md", "internal-planning-leader": ".github/agents/internal-planning-leader.agent.md", "internal-review-guard": ".github/agents/internal-review-guard.agent.md", - "internal-critical-challenger": ".github/agents/internal-critical-challenger.agent.md", + "internal-critical-master": ".github/agents/internal-critical-master.agent.md", } @@ -25,13 +24,6 @@ def read_body(relative_path: str) -> str: def test_canonical_agents_keep_required_frontmatter_and_engine_contracts() -> None: - expected_router_agents = { - "internal-fast-executor", - "internal-planning-leader", - "internal-review-guard", - "internal-critical-challenger", - } - for agent_name, relative_path in CANONICAL_AGENTS.items(): frontmatter = load_frontmatter(relative_path) body = read_body(relative_path) @@ -39,36 +31,20 @@ def test_canonical_agents_keep_required_frontmatter_and_engine_contracts() -> No assert frontmatter["name"] == agent_name assert isinstance(frontmatter.get("description"), str) assert frontmatter.get("tools") + assert frontmatter.get("disable-model-invocation") is True + assert "agent" not in frontmatter.get("tools", []) + assert frontmatter.get("agents") in (None, []) assert "## Mandatory Engine Skills" in body assert "## Output Expectations" in body - router_frontmatter = load_frontmatter(CANONICAL_AGENTS["internal-router"]) - challenger_frontmatter = load_frontmatter( - CANONICAL_AGENTS["internal-critical-challenger"] - ) - - assert set(router_frontmatter.get("agents", [])) == expected_router_agents - assert challenger_frontmatter.get("agents") == ["internal-router"] - - for agent_name in ( - "internal-fast-executor", - "internal-planning-leader", - "internal-review-guard", - ): - frontmatter = load_frontmatter(CANONICAL_AGENTS[agent_name]) - agents = frontmatter.get("agents") - assert agents in (None, []) - def test_canonical_agents_keep_expected_engine_skill_assignments() -> None: - router_body = read_body(CANONICAL_AGENTS["internal-router"]) - assert "- `internal-agent-routing-engine`" in router_body - for agent_name in ( - "internal-fast-executor", + "internal-delivery-operator", "internal-planning-leader", "internal-review-guard", - "internal-critical-challenger", + "internal-critical-master", ): body = read_body(CANONICAL_AGENTS[agent_name]) - assert "- `internal-agent-operating-model-engine`" in body + assert "- `internal-agent-cross-lane-engine`" in body + assert "- `internal-agent-boundary-recommendation-engine`" in body diff --git a/tests/test_imported_asset_overrides_contract.py b/tests/test_imported_asset_overrides_contract.py new file mode 100644 index 0000000..595782a --- /dev/null +++ b/tests/test_imported_asset_overrides_contract.py @@ -0,0 +1,90 @@ +from __future__ import annotations + +import sys +from pathlib import Path + +import yaml + +sys.path.insert(0, str((Path(".") / ".github/scripts").resolve())) + +from lib.fingerprinting import build_fingerprint # noqa: E402 + +REGISTRY_PATH = Path( + ".github/skills/internal-agent-sync-external-resources/references/imported-asset-overrides.yaml" +) +SKILL_ROOT = REGISTRY_PATH.parent.parent + + +def load_registry() -> dict[str, object]: + return yaml.safe_load(REGISTRY_PATH.read_text(encoding="utf-8")) + + +def test_imported_asset_override_registry_tracks_expected_obra_targets() -> None: + payload = load_registry() + overrides = payload["overrides"] + targets = {entry["target_path"] for entry in overrides} + + assert payload["policy"]["default_rule"] == "keep imported upstream assets verbatim" + assert targets == { + ".github/skills/obra-brainstorming/SKILL.md", + ".github/skills/obra-writing-plans/SKILL.md", + ".github/skills/obra-test-driven-development/SKILL.md", + ".github/skills/obra-subagent-driven-development/SKILL.md", + ".github/skills/obra-requesting-code-review/SKILL.md", + } + assert all( + entry["approval"] == "explicit-user-counter-validated" for entry in overrides + ) + assert all(entry["lifecycle_mode"] == "post-refresh-patch" for entry in overrides) + assert all(entry["apply_strategy"] == "git-apply-3way" for entry in overrides) + assert all((SKILL_ROOT / entry["patch_path"]).is_file() for entry in overrides) + + +def test_imported_asset_override_registry_hashes_match_live_targets() -> None: + payload = load_registry() + repo_root = Path(".").resolve() + + for entry in payload["overrides"]: + target_path = repo_root / entry["target_path"] + assert ( + build_fingerprint(repo_root, target_path).content_hash + == entry["expected_content_hash"] + ) + + +def test_imported_asset_override_policy_is_visible_in_canonical_and_sync_assets() -> ( + None +): + agents_text = Path("AGENTS.md").read_text(encoding="utf-8") + copilot_text = Path(".github/copilot-instructions.md").read_text(encoding="utf-8") + sync_agent_text = Path( + ".github/agents/internal-sync-external-resources.agent.md" + ).read_text(encoding="utf-8") + sync_skill_text = Path( + ".github/skills/internal-agent-sync-external-resources/SKILL.md" + ).read_text(encoding="utf-8") + target_sync_agent_text = Path( + ".github/agents/internal-sync-global-copilot-configs-into-repo.agent.md" + ).read_text(encoding="utf-8") + target_sync_skill_text = Path( + ".github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md" + ).read_text(encoding="utf-8") + + assert ( + "Allow a direct in-place override only for a strong repo-specific need" + in agents_text + ) + assert ( + "Do not edit imported upstream assets in place unless the need is strong" + in copilot_text + ) + assert "Every approved imported in-place override must be mapped" in sync_agent_text + assert "scripts/apply_imported_asset_overrides.py" in sync_skill_text + assert ( + "approved imported-asset override registries or replay patches" + in target_sync_agent_text + ) + assert ( + "approved imported-asset override registry plus replay patches" + in target_sync_skill_text + ) diff --git a/tests/test_inventory_and_consistency.py b/tests/test_inventory_and_consistency.py index 03c6145..98be974 100644 --- a/tests/test_inventory_and_consistency.py +++ b/tests/test_inventory_and_consistency.py @@ -14,8 +14,8 @@ def write_file(path: Path, content: str) -> None: def test_build_inventory_markdown_lists_catalog_sections(tmp_path: Path) -> None: write_file(tmp_path / "AGENTS.md", "# AGENTS\n") write_file( - tmp_path / ".github/agents/internal-fast-executor.agent.md", - "---\nname: internal-fast-executor\ntools: [read]\n---\n", + tmp_path / ".github/agents/internal-delivery-operator.agent.md", + "---\nname: internal-delivery-operator\ntools: [read]\n---\n", ) write_file( tmp_path / ".github/instructions/internal-python.instructions.md", @@ -31,7 +31,7 @@ def test_build_inventory_markdown_lists_catalog_sections(tmp_path: Path) -> None assert "## Instructions" in inventory assert "- `.github/instructions/internal-python.instructions.md`" in inventory assert "- `.github/skills/internal-catalog/SKILL.md`" in inventory - assert "- `.github/agents/internal-fast-executor.agent.md`" in inventory + assert "- `.github/agents/internal-delivery-operator.agent.md`" in inventory def test_run_consistency_checks_flags_inventory_drift_and_missing_tools( @@ -93,3 +93,42 @@ def test_run_consistency_checks_flags_empty_and_invalid_tools_contracts( ".github/agents/internal-invalid.agent.md", "internal-agent-invalid-tools", ) in findings_by_path + + +def test_run_consistency_checks_flags_invalid_imported_asset_override_registry( + tmp_path: Path, +) -> None: + write_file( + tmp_path / "AGENTS.md", + "# AGENTS\n\n- Use `.github/copilot-instructions.md`.\n- Use `.github/INVENTORY.md`.\n", + ) + write_file( + tmp_path / ".github/copilot-instructions.md", + "# Copilot Instructions\n\nSee `AGENTS.md`.\n", + ) + write_file( + tmp_path / ".github/skills/obra-demo/SKILL.md", + "---\nname: obra-demo\ndescription: Imported workflow.\n---\n", + ) + write_file( + tmp_path + / ".github/skills/internal-agent-sync-external-resources/references/imported-asset-overrides.yaml", + "overrides:\n" + " - id: bad-entry\n" + " target_path: .github/skills/obra-demo/SKILL.md\n" + " lifecycle_mode: support-only\n" + " apply_strategy: ad-hoc\n" + " approval: pending\n" + " patch_path: patches/missing.patch\n" + " expected_content_hash: short\n", + ) + write_file(tmp_path / ".github/INVENTORY.md", build_inventory_markdown(tmp_path)) + + findings = run_consistency_checks(tmp_path) + finding_codes = {finding.code for finding in findings} + + assert "imported-asset-override-approval-missing" in finding_codes + assert "imported-asset-override-invalid-lifecycle" in finding_codes + assert "imported-asset-override-invalid-apply-strategy" in finding_codes + assert "imported-asset-override-patch-missing" in finding_codes + assert "imported-asset-override-invalid-hash" in finding_codes diff --git a/tests/test_plan_policy_contract.py b/tests/test_plan_policy_contract.py index cc4f111..213bc3d 100644 --- a/tests/test_plan_policy_contract.py +++ b/tests/test_plan_policy_contract.py @@ -52,7 +52,7 @@ def test_internal_planning_leader_prefers_repository_plan_wrappers() -> None: def test_plan_wrapper_skills_are_listed_in_ownership_map_and_inventory() -> None: ownership_map_text = read_text( - ".github/skills/internal-agent-operating-model-engine/references/ownership-maps.md" + ".github/skills/internal-agent-cross-lane-engine/references/ownership-maps.md" ) inventory_text = read_text(".github/INVENTORY.md") diff --git a/tests/test_repo_only_agents_contract.py b/tests/test_repo_only_agents_contract.py new file mode 100644 index 0000000..b0de8aa --- /dev/null +++ b/tests/test_repo_only_agents_contract.py @@ -0,0 +1,54 @@ +from __future__ import annotations + +from pathlib import Path + +import yaml + +SYNC_AGENTS = { + "internal-sync-external-resources": ".github/agents/internal-sync-external-resources.agent.md", + "internal-sync-global-copilot-configs-into-repo": ".github/agents/internal-sync-global-copilot-configs-into-repo.agent.md", +} + + +def load_frontmatter(relative_path: str) -> dict[str, object]: + text = Path(relative_path).read_text(encoding="utf-8") + frontmatter_text = text.split("---\n", 2)[1] + return yaml.safe_load(frontmatter_text) + + +def read_body(relative_path: str) -> str: + text = Path(relative_path).read_text(encoding="utf-8") + return text.split("---\n", 2)[2] + + +def test_repo_only_sync_agents_keep_boundary_and_tool_contracts() -> None: + for agent_name, relative_path in SYNC_AGENTS.items(): + frontmatter = load_frontmatter(relative_path) + body = read_body(relative_path) + + assert frontmatter["name"] == agent_name + assert isinstance(frontmatter.get("description"), str) + assert frontmatter.get("tools") + assert "agent" not in frontmatter.get("tools", []) + assert frontmatter.get("disable-model-invocation") is True + assert frontmatter.get("agents") in (None, []) + assert "## Mandatory Engine Skills" in body + assert "## Boundary Definition" in body + assert "- `internal-agent-boundary-recommendation-engine`" in body + + +def test_repo_only_sync_agents_keep_their_named_operating_engines() -> None: + sync_control_center = read_body( + ".github/agents/internal-sync-external-resources.agent.md" + ) + sync_global = read_body( + ".github/agents/internal-sync-global-copilot-configs-into-repo.agent.md" + ) + + assert "- `internal-agent-sync-external-resources`" in sync_control_center + assert "- `internal-agent-sync-global-copilot-configs-into-repo`" in sync_global + + +def test_direct_entry_model_keeps_removed_router_assets_out_of_live_catalog() -> None: + assert not Path(".github/agents/internal-router.agent.md").exists() + assert not Path(".github/skills/internal-agent-routing-engine").exists() diff --git a/tests/test_sync_and_token_risks.py b/tests/test_sync_and_token_risks.py index febe882..735af9b 100644 --- a/tests/test_sync_and_token_risks.py +++ b/tests/test_sync_and_token_risks.py @@ -434,9 +434,9 @@ def test_detect_token_risks_reports_internal_root_policy_overlap( ) write_file(tmp_path / ".github/INVENTORY.md", "# Inventory\n") write_file( - tmp_path / ".github/agents/internal-sync-control-center.agent.md", - "---\nname: internal-sync-control-center\ntools: [read]\n---\n\n" - "# Internal Sync Control Center\n\n" + tmp_path / ".github/agents/internal-sync-external-resources.agent.md", + "---\nname: internal-sync-external-resources\ntools: [read]\n---\n\n" + "# Internal Sync External Resources\n\n" "Use `AGENTS.md`, `.github/copilot-instructions.md`, and `.github/INVENTORY.md`.\n\n" f"{root_policy_lines}\n", ) @@ -522,3 +522,18 @@ def test_detect_token_risks_reports_paired_agent_skill_overlap(tmp_path: Path) - finding_codes = {finding.code for finding in findings} assert "paired-agent-skill-overlap" in finding_codes + + +def test_sync_contract_requires_target_local_validation_after_apply() -> None: + sync_contract_text = Path( + ".github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md" + ).read_text(encoding="utf-8") + + assert ( + "run the closest target-local catalog or contract validation" + in sync_contract_text + ) + assert ( + "Treat any resulting fixes as consumer-local follow-up work" + in sync_contract_text + ) diff --git a/tests/test_workflow_review_contract.py b/tests/test_workflow_review_contract.py new file mode 100644 index 0000000..7b9e80d --- /dev/null +++ b/tests/test_workflow_review_contract.py @@ -0,0 +1,93 @@ +from __future__ import annotations + +from pathlib import Path + + +def read_text(relative_path: str) -> str: + return Path(relative_path).read_text(encoding="utf-8") + + +def test_canonical_routing_contract_keeps_deterministic_repo_owned_work_in_execution() -> ( + None +): + delivery_operator_text = read_text( + ".github/agents/internal-delivery-operator.agent.md" + ) + planning_leader_text = read_text(".github/agents/internal-planning-leader.agent.md") + operating_model_text = read_text( + ".github/skills/internal-agent-cross-lane-engine/SKILL.md" + ) + + assert ( + "deterministic realignment across adjacent repository-owned assets" + in delivery_operator_text + ) + assert ( + "Boundary crossing alone does not make the task planning-owned." + in planning_leader_text + ) + assert ( + "File count and adjacent boundary crossing are heuristics, not automatic planning triggers." + in operating_model_text + ) + assert ( + "ambiguous entry fails safe to `internal-planning-leader`" + in operating_model_text + ) + + +def test_obra_assets_use_tmp_superpowers_for_transient_paths() -> None: + obra_paths = ( + ".github/skills/obra-brainstorming/SKILL.md", + ".github/skills/obra-brainstorming/spec-document-reviewer-prompt.md", + ".github/skills/obra-writing-plans/SKILL.md", + ".github/skills/obra-subagent-driven-development/SKILL.md", + ".github/skills/obra-requesting-code-review/SKILL.md", + ) + + for relative_path in obra_paths: + assert "docs/superpowers" not in read_text(relative_path) + + assert "tmp/superpowers/" in read_text(".github/skills/obra-brainstorming/SKILL.md") + assert "tmp/superpowers/" in read_text(".github/skills/obra-writing-plans/SKILL.md") + + +def test_obra_workflows_do_not_claim_deterministic_textual_governance_maintenance() -> ( + None +): + brainstorming_text = read_text(".github/skills/obra-brainstorming/SKILL.md") + writing_plans_text = read_text(".github/skills/obra-writing-plans/SKILL.md") + tdd_text = read_text(".github/skills/obra-test-driven-development/SKILL.md") + + assert ( + "Do not use this workflow for deterministic repository-owned maintenance of prompt, skill, agent, instruction, or Markdown assets" + in brainstorming_text + ) + assert ( + "Do not use this workflow as the default gate for deterministic repository-owned maintenance or realignment" + in writing_plans_text + ) + assert "- New features" in tdd_text + assert "- Bug fixes" in tdd_text + assert ( + "Do not treat this workflow as the default for prompt, skill, agent, instruction, or Markdown authoring" + in tdd_text + ) + + +def test_agent_authoring_docs_preserve_subagent_inherited_defaults_note() -> None: + agent_development_text = read_text( + ".github/skills/internal-agent-development/SKILL.md" + ) + subagent_patterns_text = read_text( + ".github/skills/internal-agent-development/references/subagent-patterns.md" + ) + + assert ( + "subagents inherit the main session agent, model, and tools" + in agent_development_text + ) + assert ( + "a subagent inherits the main session agent, model, and tools" + in subagent_patterns_text + )