OracleDBIQ — Oracle PL/SQL Optimization Starter Pack

A ready-to-use configuration that turns GitHub Copilot and Claude into expert Oracle Database developers, DBAs, and performance engineers. It ships a shared standards document, a task-specific prompt library, chat modes, skills, specialised agents — and a deterministic AWR/ASH diagnostics toolchain so performance findings come from parsed evidence rather than model recall.

Two documents, one job each. AGENTS.md is the source of truth the AI reads; this README is the guide a human reads. The catalogue tables in both are generated from the assets themselves, so neither can drift.

---

Contents

• Repository layout
• How the two tools share configuration
• Evidence-first performance work
• Architecture
• The agent roster
• The skills library
• The prompt library
• Usage
• Worked scenarios
• Best practices for prompting
• Continuous integration
• Maintenance

---

Repository layout

├── AGENTS.md                       # ★ Single source of truth (read by BOTH tools)
├── CLAUDE.md                       # Pointer to AGENTS.md + Claude asset map
├── .github/
│   ├── copilot-instructions.md     # Pointer to AGENTS.md (Copilot native path)
│   ├── agents/                      # 18 Copilot custom agents (*.agent.md) — generated
│   ├── skills/                      # 16 Copilot agent skills (*/SKILL.md) — generated
│   ├── instructions/                # Path-scoped rules (plsql, tests, packages, migrations)
│   ├── prompts/                     # Prompt library (*.prompt.md, with frontmatter)
│   ├── chatmodes/                   # Chat modes (dba-diagnostics, plsql-tuning)
│   └── workflows/                   # CI: markdown-lint, validate-docs,
│                                    #     oracle-validation, diagnostics-toolchain
├── .claude/                         # ★ Authored source for skills and agents
│   ├── skills/                      # 16 task-routed skills (*/SKILL.md)
│   └── agents/                      # 18 specialised Oracle agents incl. the orchestrator
├── tools/
│   ├── oracle_diag/                 # ★ Deterministic diagnostics toolchain (stdlib only)
│   └── tests/                       # Test suite + AWR/ASH/plan fixtures, incl. negatives
├── scripts/
│   ├── sync-copilot-assets.sh           # Generates .github/agents + .github/skills
│   ├── sync_catalogues.py               # Generates the catalogue tables in this file + AGENTS.md
│   ├── validate-prompt-frontmatter.sh   # CI: prompt YAML frontmatter
│   ├── validate-prompt-structure.sh     # CI: prompt section contract
│   ├── validate-skills-and-agents.sh    # CI: skill/agent contract, both runtimes
│   └── validate-test-corpus.sh          # CI: fails if the utPLSQL corpus is empty
├── sql/
│   ├── app/                        # Deployable schema + PKG_BILLING (code under test)
│   ├── tests/                      # utPLSQL suites (characterisation, equivalence, boundary)
│   ├── diagnostics/                # ASH/AWR/SPM evidence queries for a live database
│   └── validation/                 # Self-contained SQL fixtures run in CI
└── docs/
    ├── parser-conformance.md       # Validating the AWR parser against your own reports
    └── TODO.md                     # Open work: blocking items, verification, enhancements

How the two tools share configuration

What	GitHub Copilot loads	Claude loads
Core standards	.github/copilot-instructions.md → AGENTS.md	CLAUDE.md → AGENTS.md
Path-scoped rules	.github/instructions/*.instructions.md	AGENTS.md
Prompts	.github/prompts/*.prompt.md	.github/prompts/*.prompt.md (attach)
Chat modes	.github/chatmodes/*.chatmode.md	(agents cover this)
Skills	.github/skills/*/SKILL.md	.claude/skills/*/SKILL.md
Agents	.github/agents/*.agent.md	.claude/agents/*.md
Diagnostics toolchain	tools/oracle_diag (run it)	tools/oracle_diag (run it)

Both Copilot and Claude read AGENTS.md natively, so it holds all the real content; the other instruction files are thin pointers so nothing is missed on either tool's native discovery path.

Skills and agents are authored once and generated for both runtimes. The .claude/ copies are the source; scripts/sync-copilot-assets.sh produces the .github/ copies, translating the agent tool list to Copilot's aliases. CI runs sync-copilot-assets.sh --check and fails on drift, so the same named agent can never give a Copilot user different advice from a Claude user.

# after editing anything under .claude/skills or .claude/agents
bash scripts/sync-copilot-assets.sh
bash scripts/validate-skills-and-agents.sh

Evidence-first performance work

Two rules in AGENTS.md override everything else:

• Evidence & Diagnostics Doctrine — DB Time is the ranking currency; ratios (Buffer Hit %, Soft Parse %) are never evidence; AWR numbers are parsed, never recalled; an unrepresentative window is refused, not analysed.
• Change Risk & Approval — nothing destructive is executed, and HIGH-risk changes require named human approval.

A raw AWR report is 1–20 MB. Reading one into a model context is expensive, lossy and invites invented numbers, so the toolchain does the arithmetic:

cd tools

# Parse → validate the window → redact → rank by DB Time → correlate SQL_ID to file:line
python -m oracle_diag analyze awrrpt_1_48120_48121.html --repo .. --format md

# Did the database get slower, or did the workload get bigger?
python -m oracle_diag compare before.html after.html --repo ..

# Spikes and blocking chains that AWR averaged away
python -m oracle_diag ash ashrpt_1_48120_48121.html

It exits 2 and refuses to recommend anything when the window cannot support conclusions (instance restart, 24h window, idle instance, wrong period). See tools/README.md.

---

Architecture

Five layers. Each is loaded by both runtimes from the location that runtime natively discovers.

1. The "Brain": system instructions

• Source of truth: AGENTS.md — read natively by both GitHub Copilot and Claude.
• Copilot entry point: .github/copilot-instructions.md, auto-loaded for every interaction in this repo. Claude entry point: CLAUDE.md.
• Sets the persona, the coding standards, and the non-negotiable rules.
• You never attach these. They are always active.

2. The "Specialists": agents

• .github/agents/<name>.agent.md (Copilot) and .claude/agents/<name>.md (Claude) — the same 18 specialists, generated from one source.
• Each owns one review domain, carries its own tool set and hand-off rules, and refuses to answer outside its evidence.
• Usage: in Copilot, pick the custom agent or name it in chat; in Claude Code, it is delegated automatically by task.

3. The "Instincts": task-routed skills

• .github/skills/<name>/SKILL.md and .claude/skills/<name>/SKILL.md — the same 16 skills.
• Each carries a description saying when it applies, so the right one is selected from your request rather than attached by hand. Read by the Copilot cloud agent, Copilot CLI, Copilot code review, and agent mode in VS Code/JetBrains.

4. The "Tools": task-specific prompts

• .github/prompts/*.prompt.md — specialised lenses you invoke deliberately.
• Usage: Copilot Chat → type / and pick the prompt, or attach the file with the + icon.

5. The "Evidence": diagnostics toolchain

• tools/oracle_diag/ (Python, standard library only).
• Parses AWR/ASH reports deterministically so findings rest on parsed numbers rather than model recall. Validates the window, redacts sensitive content, ranks by % of DB Time, and correlates each SQL_ID to file:line.

Generated, not duplicated. .github/agents/ and .github/skills/ are produced from the .claude/ sources by scripts/sync-copilot-assets.sh, and the catalogue tables below are produced from the asset frontmatter by scripts/sync_catalogues.py. CI fails if either drifts.

---

The agent roster

Agents are the specialists. If you know the domain, name the agent; if you do not, use oracle-review-orchestrator and let it route.

Generated from the asset frontmatter by scripts/sync_catalogues.py — do not edit this table by hand.

Agent	Remit
oracle-review-orchestrator	Run a full Oracle optimisation review end to end — evidence, code analysis, security, validation and a risk-classified verdict.
oracle-ash-analyst	Resolve short spikes, blocking chains and plan-line attribution from ASH.
oracle-awr-analyst	Analyse an AWR report into evidence-backed findings ranked by % of DB Time and correlated to repository code.
oracle-bulk-processing-advisor	Decide whether row-by-row PL/SQL should become set-based SQL or BULK COLLECT/FORALL, size LIMIT against PGA, and design SAVE EXCEPTIONS partial-failure handling.
oracle-code-analyst	Parse Oracle SQL/PLSQL, map object dependencies and blast radius, classify units, and detect anti-patterns before any optimisation begins.
oracle-diagnostics-advisor	Choose the right Oracle diagnostic instrument and own statistics and plan stability — AWR vs ASH vs ADDM vs SQL Monitor vs 10046, SQL Plan Baselines, Profiles and Patches, DBMS_STATS strategy, and the Diagnostics/Tuning Pack licensing boundary.
oracle-error-handling-reviewer	Review PL/SQL exception handling — swallowed errors, WHEN OTHERS, propagation, SQLCODE/SQLERRM, FORMAT_ERROR_BACKTRACE, autonomous logging and correlation IDs.
oracle-index-advisor	Justify or reject an index with workload evidence — selectivity, column order, DML cost, storage, partition interaction and redundancy against existing indexes.
oracle-legacy-modernizer	Assess and safely refactor legacy Oracle PL/SQL — risk-classified, behaviour-preserving, with regression tests.
oracle-mview-advisor	Design and review materialized views — fast vs complete refresh, ON COMMIT vs ON DEMAND, MV logs, query rewrite eligibility, refresh cost and staleness.
oracle-partitioning-advisor	Decide whether partitioning is justified and design the scheme — range/list/hash/interval/composite, local vs global indexes, pruning, partition-wise joins and maintenance.
oracle-plsql-optimizer	Optimise PL/SQL execution — context switching, row-by-row processing, BULK COLLECT/FORALL, collection memory, cursor handling, compiler settings and transaction boundaries.
oracle-regression-analyst	Compare two AWR periods per execution to separate a genuine regression from workload growth, detect plan regressions via PLAN_HASH_VALUE, and produce before/after proof that an optimisation worked.
oracle-scheduler-analyst	Review and design DBMS_SCHEDULER workloads — jobs, programs, schedules, chains, retry and failure handling, resource consumption, monitoring and credential security.
oracle-security-reviewer	Review Oracle SQL/PLSQL for SQL injection, unsafe dynamic SQL, privilege escalation, definer/invoker rights, credential exposure and sensitive-data handling.
oracle-sql-tuner	Tune a single Oracle SQL statement from its runtime execution plan — cardinality, access paths, join methods, indexes and hints.
oracle-transaction-analyst	Review transaction boundaries and concurrency — COMMIT/ROLLBACK/SAVEPOINT placement, locking, deadlocks, long transactions, autonomous transactions, read consistency and lost updates.
oracle-version-migration-analyst	Assess Oracle version compatibility and plan an upgrade path across 11g/12c/18c/19c/21c/23ai — deprecated and desupported features, optimizer and SQL behaviour changes, PL/SQL changes, COMPATIBLE staging and plan stability.

The skills library

Skills are the auto-routed counterpart to prompts — selected from your request rather than attached.

Generated from the asset frontmatter by scripts/sync_catalogues.py — do not edit this table by hand.

Skill	Use it for
oracle-ash-analysis	Resolve what AWR averages away: short spikes, blocking chains and plan-line level attribution, using ASH (V$ACTIVE_SESSION_HISTORY / DBA_HIST_ACTIVE_SESS_HISTORY) or an ashrpt.sql report.
oracle-awr-analysis	Turn a raw AWR report into evidence-backed, code-level Oracle findings ranked by % of DB Time.
oracle-awr-period-comparison	Prove whether performance actually regressed by comparing a baseline and a current AWR period, normalised per execution, with PLAN_HASH_VALUE change detection.
oracle-change-risk-approval	Classify any proposed Oracle change by risk and decide what human approval it needs before it can be applied.
plsql-bulk-processing	Convert row-by-row ("slow-by-slow") PL/SQL into set-based and bulk operations for high-throughput data processing.
plsql-code-optimization	Optimize the compiled and runtime behavior of Oracle PL/SQL program units — distinct from SQL statement tuning.
plsql-code-review	Review Oracle PL/SQL against the pre-production checklist and report findings by severity.
plsql-debugging-security	Diagnose and harden Oracle PL/SQL — structured error handling, logging, secure coding, and access/transaction control.
plsql-legacy-refactoring	Modernize legacy Oracle PL/SQL for performance, readability, and current-version features.
plsql-monitoring-automation	Implement proactive Oracle performance monitoring, alerting, and plan-stability automation.
plsql-parallelism-resources	Design parallel execution and instance resource strategies for high-volume Oracle workloads.
plsql-program-development	Build production-grade Oracle PL/SQL program units — procedures, functions, packages, and triggers — following enterprise naming, error-handling, and performance standards.
plsql-query-tuning	Diagnose and optimize slow Oracle SQL statements to reach sub-second OLTP and efficient batch performance.
plsql-schema-dml-design	Design performant Oracle schemas and data-manipulation logic — tables, indexes, constraints, partitioning, sequences, DML, MERGE upserts, and materialized views.
plsql-testing-validation	Author automated tests and data validation for Oracle PL/SQL using utPLSQL and SQL assertions.
plsql-version-migration	Plan and generate an Oracle version upgrade path — adopt new-release features, replace deprecated constructs, and de-risk the migration.

The prompt library

Attach a prompt when you want to force a specific expert lens for one task.

Generated from the asset frontmatter by scripts/sync_catalogues.py — do not edit this table by hand.

Prompt	Use it for
advanced-db-objects.prompt.md	Create advanced database objects: external tables, object types, collections, and DBMS_SCHEDULER jobs.
ash-blocking-analysis.prompt.md	Resolve spikes, blocking chains and plan-line attribution with ASH — the detail AWR averages away.
awr-analysis.prompt.md	Analyse an AWR report into evidence-backed findings ranked by % of DB Time, correlated to repository code, with a mandatory 'not determinable' section.
awr-period-comparison.prompt.md	Compare a baseline and current AWR period per execution to separate a real regression from workload growth, and prove an optimisation worked.
code-review.prompt.md	Review Oracle PL/SQL against the pre-production checklist — code quality, performance, error handling, security, and testing — and report findings by severity.
cursor-and-bulk-processing.prompt.md	Process large datasets efficiently with BULK COLLECT, FORALL, LIMIT batching, and SAVE EXCEPTIONS.
dcl-and-tcl-operations.prompt.md	Manage grants, roles, and privileges (DCL) plus transactions and locking (TCL): COMMIT, ROLLBACK, SAVEPOINT.
ddl-schema-management.prompt.md	Design tables, indexes, constraints, sequences, and partitioning following naming and storage conventions.
debugging-and-security.prompt.md	Diagnose ORA- errors, add structured logging, and harden PL/SQL against SQL injection and privilege misuse.
dml-data-manipulation.prompt.md	Write correct, set-based, performant INSERT, UPDATE, DELETE, and MERGE statements.
function-development.prompt.md	Create scalar, pipelined, and table functions using DETERMINISTIC, RESULT_CACHE, and PARALLEL_ENABLE correctly.
index-strategy-review.prompt.md	Justify or reject every proposed Oracle index with workload evidence, selectivity, DML cost, storage and partition interaction — never in isolation.
legacy-code-refactoring.prompt.md	Modernize legacy PL/SQL: row-by-row to set-based/bulk, legacy joins to ANSI, and modular redesign.
materialized-view-optimization.prompt.md	Design and tune materialized views, MV logs, and FAST vs COMPLETE refresh strategies with EXPLAIN_MVIEW.
monitoring-and-automation.prompt.md	Analyze AWR/ADDM/ASH, configure alerts, manage SQL plan baselines, and schedule automated health checks.
oracle-spatial-development.prompt.md	Work with SDO_GEOMETRY, spatial indexes, and location-based queries in Oracle Spatial.
oracle-text-search.prompt.md	Implement Oracle Text full-text search: CONTAINS queries, domain indexes, and index synchronization.
package-development.prompt.md	Build modular PL/SQL packages with clean specs, bodies, encapsulated state, and private helpers.
parallelism-and-resource-optimization.prompt.md	Tune parallel query and DML, Resource Manager plans, and PGA/SGA memory for throughput.
plsql-code-optimization.prompt.md	Optimize PL/SQL: compiler optimize level, native compilation, subprogram inlining, fast datatypes, DBMS_HPROF profiling.
sql-query-tuning.prompt.md	Diagnose slow SQL using real runtime execution plans (A-Rows, buffers, cardinality) and rewrite for efficiency.
stored-procedure-development.prompt.md	Write transactional stored procedures with parameter validation and robust exception handling.
trigger-development.prompt.md	Implement auditing, validation, and compound triggers safely, avoiding mutating-table pitfalls.
unit-testing-and-validation.prompt.md	Generate utPLSQL test suites, mock data, and reconciliation/validation scripts.
version-migration.prompt.md	Plan and generate an Oracle version upgrade path — adopt new-release features, replace deprecated constructs, and de-risk the migration (19c to 23ai and similar).

Prompts vs skills vs agents: attach a prompt to force a lens on the current conversation. Rely on skills for hands-free routing. Choose an agent when you want a specialist with its own tool set, remit and hand-off rules to own the task end to end.

---

Usage

Once the repo is open in an editor with Copilot and/or Claude enabled, the shared standards in AGENTS.md apply to every interaction automatically — you never attach them. Reach for the task-specific assets below when you want a focused expert lens.

GitHub Copilot

Asset	How to invoke	When to use
Custom instructions	Automatic — always on	Baseline standards for every chat / completion in this repo
Path-scoped instructions	Automatic when you edit a matching file	Extra rules for *.sql / *.pks / *.pkb, tests, packages, migrations
Agents (.github/agents/*.agent.md)	Select the custom agent, or name it in chat	An Oracle specialist with its own tool set and remit — 18 of them; start with oracle-review-orchestrator
Skills (.github/skills/*/SKILL.md)	Automatic — selected when your request matches	Hands-free routing to the right domain procedure
Prompts (.github/prompts/*.prompt.md)	Copilot Chat → type / and pick the prompt, or attach the file with the + icon	Force a specific expert lens for one task (tuning, code review, MV design…)
Chat modes (.github/chatmodes/*.chatmode.md)	Chat mode dropdown → select dba-diagnostics or plsql-tuning	Switch the whole session's persona + tool set for a work stream

Claude / Claude Code

Asset	How to invoke	When to use
CLAUDE.md → AGENTS.md	Automatic	Same baseline standards as Copilot
Agents (.claude/agents/*.md)	Delegated by task	The same 18 specialists Copilot gets
Skills (.claude/skills/*/SKILL.md)	Matched from your request	Hands-free routing to the right domain guidance
Prompts (.github/prompts/*.prompt.md)	Attach the file	Force one specific expert lens

Describe the task ("review this package", "analyse this AWR", "migrate this from 12c to 23ai") and the matching skill or agent takes over.

Choosing the right asset

• Just want good code by default? Do nothing — AGENTS.md is always active.
• Focused task, one shot? A prompt.
• A whole work stream in one persona? A chat mode.
• Let the agent pick? Skills (auto-matched).
• A domain specialist to own the task? An agent.
• A performance question with real evidence? Run oracle_diag first.

Prompts are one-shot lenses you invoke per task; chat modes persist across the session and also constrain which tools Copilot may use.

---

Worked scenarios

Scenario 1: a full review with a verdict

1. Select the oracle-review-orchestrator agent.

2. "Review PKG_BILLING — here is last night's AWR. What do we fix first?"

3. It engages the specialists the request needs (AWR → code → security → regression plan), reconciles their findings, ranks by % of DB Time, classifies each change's risk, and returns one verdict — APPROVE | APPROVE WITH CONDITIONS | REQUEST CHANGES | BLOCK.

Scenario 2: designing a new schema

1. Attach .github/prompts/ddl-schema-management.prompt.md.

2. "Create a schema for an E-commerce Order system. I need an Orders table and an OrderItems table. Include primary keys, foreign keys, and an index on the Order Date. Ensure standard naming conventions."

3. You get CREATE TABLE statements with storage clauses, properly named constraints (pk_orders, fk_order_items_order_id), and table/column comments.

Scenario 3: writing complex business logic

1. Attach .github/prompts/package-development.prompt.md.

2. "Create a package pkg_payroll to calculate monthly salaries. It needs a procedure process_monthly_payroll that takes a department ID. It should calculate tax, update the salary history, and log the action."

3. You get a package specification with public types and exceptions, a body with private helpers, standard error handling, and explicit transaction control.

Scenario 4: optimising slow SQL

1. Attach .github/prompts/sql-query-tuning.prompt.md (or type /sql-query-tuning).
2. Select the slow SQL in your editor and add context:

   "Tune this. Full scan on TRANSACTIONS (50M rows), filter by last month + status='FAILED'."

3. You get baseline → root cause → refactored SQL → index/statistics recommendations → verification steps.

Scenario 5: bulk data migration

1. Attach .github/prompts/cursor-and-bulk-processing.prompt.md.

2. "Write a procedure to migrate data from stg_sales to fact_sales. Use bulk processing with a limit of 5000 rows per batch. Handle exceptions using SAVE EXCEPTIONS."

3. You get BULK COLLECT + FORALL with a justified LIMIT, and SQL%BULK_EXCEPTIONS handling for row-level errors.

Scenario 6: diagnosing a production slowdown from an AWR report

Users reported timeouts between 09:10 and 09:40. Find out why, and what to change.

1. Pick a usable window (do not just grab yesterday's daily report):

   @sql/diagnostics/snapshot_window.sql '2026-08-10 09:00:00' '2026-08-10 10:00:00'

   It flags an instance restart, a snapshot gap, or a window too long to localise the incident.

2. Generate the report (@?/rdbms/admin/awrrpt.sql, or awrgrpt.sql for RAC) and save it next to the code.

3. Parse it — never paste it into chat:

   cd tools
   python -m oracle_diag analyze ../diagnostics/awrrpt_1_48120_48121.html \
       --repo .. --problem-window '2026-08-10 09:10..2026-08-10 09:40'

4. Read the verdict first. If the window is unrepresentative the tool exits 2 and says so instead of guessing — go back to step 1.

5. Work the ranked findings. Each one names its AWR section, its % of DB Time, the file:line it maps to, its risk and confidence, and the validation that would prove the fix. Example output:

   log file sync = 41.2% of DB Time; user commits = 486,190 → pkg_billing.pkb:19 (PKG_BILLING.APPLY_CHARGES) — COMMIT inside a cursor loop → replace with BULK COLLECT ... LIMIT + FORALL and one commit per batch. Risk MEDIUM (transaction boundary changes).

6. Resolve what AWR averaged away with ASH:

   python -m oracle_diag ash ../diagnostics/ashrpt_1_48120_48121.html

7. Prove the fix after deployment:

   python -m oracle_diag compare before.html after.html --repo ..

   Per-execution normalisation separates a real improvement from a quieter day.

The tool refuses to produce recommendations from ratios (Buffer Hit %, Soft Parse %), excludes idle events from ranking, and always ends with "Not Determinable From This AWR" — say what the evidence cannot tell you.

Scenario 7: investigating without touching code

1. Open the chat-mode dropdown and pick dba-diagnostics (read-only).

2. "The DB was slow between 14:00–15:00 yesterday — find the top waits and any blocking."

3. It runs oracle_diag over the AWR/ASH evidence and returns Symptom → Evidence (citing the report section) → Root cause → Recommended action (as commands to review) → How to verify → what the evidence cannot tell you.

---

Best practices for prompting

1. Be specific about the business logic. The technical standards are already handled by the system prompt, so spend your words on intent.
   • Bad: "Make a function."
   • Good: "Create a function calculate_discount that takes customer_id and amount. If the customer is 'VIP', give 10% off. Return the final amount."
2. Iterate. Generate, review against your needs, then refine: "Add logging to this," or "Make the exception handling more granular."
3. Read the Analysis section. Most prompts give you an analysis before the code. It explains why a design choice was made.
4. Bring evidence for performance questions. Without an AWR/ASH report or a runtime plan, every performance statement is labelled Requires runtime validation. — which is honest, but not actionable.

---

Continuous integration

Four workflows guard quality (they run only when this folder is the repository root — see the note below):

Workflow	Checks
markdown-lint.yml	Markdown style across all *.md
validate-docs.yml	Prompt frontmatter + section structure, the skill/agent contract on both runtimes, Copilot-catalogue sync, catalogue-table sync, and broken links
oracle-validation.yml	Compiles sql/validation/*.sql against Oracle 23ai Free and proves the MV is FAST-refreshable via DBMS_MVIEW.EXPLAIN_MVIEW; runs the utPLSQL suites under sql/tests/
diagnostics-toolchain.yml	oracle_diag test suite on Python 3.9 + 3.12; asserts the output contract, that an unrepresentative window is refused, and that no unredacted sensitive content reaches the model-facing pack

Note: GitHub Actions only runs workflows from the repository root's .github/workflows/. If this pack lives as a subdirectory of a larger repo, the workflows are inert until it becomes its own repository (or the jobs are lifted to the root).

---

Maintenance

Updating standards. Team conventions change → edit AGENTS.md, the shared source of truth. That instantly updates behaviour for both Copilot and Claude everywhere.

New or changed skills and agents. Author them under .claude/skills/ or .claude/agents/, then regenerate both the Copilot copies and the catalogue tables:

bash scripts/sync-copilot-assets.sh
python scripts/sync_catalogues.py
bash scripts/validate-skills-and-agents.sh

Never hand-edit anything under .github/agents/, .github/skills/, or between the <!-- catalogue:*:start --> markers in this file and AGENTS.md — all of it is generated, and CI will fail on drift.

New prompts. CI enforces the section contract (Goal, Act as, User Input Needed, Example Prompt to Copilot) plus frontmatter with a mode and a description of at least 20 characters:

bash scripts/validate-prompt-frontmatter.sh
bash scripts/validate-prompt-structure.sh
python scripts/sync_catalogues.py

New wait events / AWR sections. Extend tools/oracle_diag/waits.py (interpretation + code-level cause) or the section registry in awr_parser.py, and add a fixture assertion in tools/tests/. A parser change without a test is how a "parsed" number quietly becomes a guessed one.

Open work is tracked in this repository's GitHub issues.

---