@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-agent-instructions-analyze/references/file-type-discovery-checklist.md

@@ -0,0 +1,273 @@
+# File-Type Pattern Discovery Checklist
+
+Systematic methodology for identifying glob-scoped rule opportunities. These are structural file-type patterns that
+agents need when creating or editing files. They often span multiple directories, but they can still justify a
+glob-scoped rule even when concentrated in a single architectural area.
+
+File-type patterns are often the **highest-value** glob-scoped rules because they directly prevent agents from
+producing broken code across many files.
+
+A file-type pattern is a rule candidate even if all matching files live in one directory. The question is whether
+agents need a repeatable template for that file type, not whether the files are distributed widely.
+
+The goal of this checklist is to **find ambiguity and hidden conventions**, not just to confirm that filenames look
+consistent. File counts are only the starting point. The actual signal comes from reading files and identifying
+semantic patterns, split conventions, and failure modes.
+
+## Discovery Process
+
+### 1. Build a Baseline Inventory
+
+Start with a two-phase inventory so discovery is not limited to today's known naming conventions.
+
+**1a. Inventory primary file extensions**
+
+Use a repo-wide count to identify common authored file types such as `.tsx`, `.css`, `.graphql`, or `.sql`.
+Exclude generated and external directories so the inventory reflects source patterns rather than build output.
+
+```bash
+find . -type f \
+  -not -path '*/node_modules/*' \
+  -not -path '*/.git/*' \
+  -not -path '*/dist/*' \
+  -not -path '*/__generated__/*' \
+  | sed -E 's|^.*/||' \
+  | awk -F. 'NF >= 2 { print "." $NF }' \
+  | sort | uniq -c | sort -rn | head -20
+```
+
+**1b. Inventory repeated compound suffixes**
+
+Use a repo-wide count to identify common multi-part suffixes such as `.stories.tsx`, `.test.ts`, `.resolver.ts`,
+or `.repository.ts`. Do not limit analysis to the pre-listed patterns below.
+
+```bash
+find . -type f \
+  -not -path '*/node_modules/*' \
+  -not -path '*/.git/*' \
+  -not -path '*/dist/*' \
+  -not -path '*/__generated__/*' \
+  | sed -E 's|^.*/||' \
+  | awk -F. 'NF >= 3 { print "." $(NF-1) "." $NF }' \
+  | sort | uniq -c | sort -rn | head -20
+```
+
+**1c. Select candidates for sampling**
+
+Proceed to sampling for:
+
+- any primary extension with **5+** non-generated source files
+- any compound suffix with **5+** files
+- any smaller pattern that clearly overrides a project-wide rule or has high correctness impact
+- any repeated compound suffix discovered from the inventory, even if it is not listed in the known patterns below
+
+**Primary extensions to pay attention to when counts are significant:**
+
+- Component/client files: `*.tsx`, `*.jsx`
+- Style files: `*.css`, `*.scss`, `*.less`
+- Schema/query files: `*.graphql`, `*.gql`, `*.sql`
+- Source/config/content files: `*.ts`, `*.js`, `*.json`, `*.yaml`, `*.yml`, `*.mdx`
+
+**Known compound naming patterns to check:**
+
+- Test files: `*.test.ts`, `*.test.tsx`, `*.spec.ts`, `*.spec.tsx`, `*.test.js`, `*.test.jsx`
+- Story files: `*.stories.tsx`, `*.stories.ts`, `*.stories.jsx`, `*.stories.js`
+- Style files: `styles.ts`, `*.styles.ts`, `*.module.css`, `*.module.scss`, `*.styled.ts`
+- Schema/type files: `*.schema.ts`, `*.types.ts`, `*.d.ts`
+- Hook files: `*.hooks.ts`, `use*.ts` (in hooks directories)
+- Utility files: `*.utils.ts`, `*.helpers.ts`, `*.constants.ts`
+- Mock/fixture files: `*.mock.ts`, `*.fixture.ts`, `*.fixtures.ts`
+- Config files: `*.config.ts`, `*.config.js`, `*.config.mjs`
+- E2E/integration files: `*.e2e.ts`, `*.integration.ts`, `*.e2e-spec.ts`
+- Generated files: `*.generated.ts`, `*.gen.ts`, `*.graphql.ts`
+
+**Also check for co-located naming conventions:**
+
+- Component directories: `Component.tsx` + `styles.ts` + `Component.stories.tsx` + `Component.test.tsx`
+- Feature modules: `index.ts` + `types.ts` + `utils.ts` + `*.test.ts`
+- Domain bundles: repeated directory structures containing metadata + implementation + template/rendering files
+  Example: `feature.json` + `handler.ts` + `template.tsx`
+- Schema bundles: repeated directories where one file implies required siblings (schema + loader + tests + fixtures)
+  Example: `schema.graphql` + `loader.ts` + `schema.test.ts` + `fixtures/`
+
+Treat directory-level co-location as a first-class investigation target. Some of the highest-value rules are not "all `*.x` files look the same" but "every directory matching this pattern must contain these files and use one of two competing structures."
+
+### 2. Calibrate Sample Size to Detect Inconsistency
+
+For every selected pattern with **5+ files**, reading the sampled files is mandatory. Do not stop at naming
+consistency.
+
+Use these minimum sample sizes:
+
+- **5–10 matching files:** Read **all** files
+- **11–30 files:** Sample **8–12** files across different directories and different git ages
+- **30+ files:** Sample **12–15** files across directories; if any inconsistency appears, expand the sample until you
+  can describe the split ratio with confidence
+
+The goal is not to confirm a pattern with the smallest possible sample. The goal is to discover whether the repo
+contains a meaningful split that would cause an agent to guess wrong.
+
+When sampling:
+
+- Mix directories; do not sample from a single subtree
+- If the pattern appears under multiple top-level subdirectories or architectural buckets, sample each bucket rather
+  than letting one subtree dominate the sample
+- Mix older and newer files when possible; convention changes often correlate with time
+- If the first sample looks perfectly consistent, still pressure-test it with files from other directories before
+  concluding
+
+If many patterns qualify, prioritize sampling in this order before spending context on lower-value patterns:
+
+1. security-sensitive patterns or exception-to-project-rule patterns
+2. competing sub-patterns or known migration-era splits
+3. patterns with high suspected correctness impact
+4. lower-risk consistency-only patterns
+
+### 3. Deep-Read Investigation
+
+Inspect the sample for:
+
+- **Structural consistency:** Do they share the same import pattern, export pattern, or boilerplate?
+- **Required wrapping/setup:** Do they require specific providers, decorators, helper classes, test harnesses, or framework extensions that aren't obvious from the file suffix?
+- **Behavioral consistency:** Do they use the same registration flow, setup/teardown style, instantiation pattern, schema version, or rendering mechanism?
+- **Directory assumptions:** Do files assume the presence of sibling files or a repeated directory structure?
+- **Security-sensitive behavior:** Do they contain escaping/sanitization, raw HTML insertion, raw SQL, shell execution, `phpcs:ignore`, or other exception-worthy safety patterns?
+
+For each pattern, explicitly answer:
+
+1. What non-obvious setup is required?
+2. What would break if an agent copied the wrong example?
+3. Are there competing sub-patterns inside the same suffix or directory structure?
+4. Are there version splits or old/new style splits that matter for new files?
+
+### 4. Keep Glob Rules Separate from Directory Coverage
+
+Do **not** dismiss a file-type pattern because it may also be covered by a directory-level `AGENTS.md`.
+
+- Directory `AGENTS.md` files cover commands, architecture, workflows, and local context.
+- Glob-scoped rules cover the structural template that should fire when an agent creates or edits a specific file type.
+
+A directory note like "resolvers use GraphContext" is weaker than a glob-scoped rule that fires for resolver files
+and shows the expected imports, signature, and delegation pattern.
+
+### 5. Quantify the Real Pattern, Including Splits
+
+Sampling discovers candidate patterns. It does **not** justify numeric claims on its own.
+
+Before writing any numeric claim into the artifact or a generated rule, verify it with an exhaustive repo-wide count.
+This applies to:
+
+- file counts and split ratios
+- "only N files use X" statements
+- claims that a pattern is unused or obsolete
+- any recommendation that removes or contradicts an existing rule
+
+If a sample suggests "Pattern A is gone" or "only 3 files still use Pattern B", stop and verify across the whole repo
+before writing the claim.
+
+Quantify the behavior you found, not just the filename suffix:
+
+- `12/14 files use Pages utility wrapper`
+- `9/18 directories use static registration, 9/18 use instance registration`
+- `7/10 block manifests use apiVersion 3, older files use apiVersion 2`
+
+Interpret the result this way:
+
+- `>80%` consistency = useful rule candidate
+- `60–80%` consistency = pattern with notable exceptions; capture both dominant pattern and exceptions
+- `40–60%` consistency = **highest-priority ambiguity**; agents are likely to choose wrong without guidance
+- `<40%` consistency = may still matter if the split tracks security, framework version, or generation age; do not automatically discard without checking impact
+
+### 5a. Decide Whether to Split into Separate Rules
+
+Do not assume one discovered pattern should become one umbrella rule.
+
+Prefer **separate** rules when:
+
+- activation targets differ materially (for example `*.spec.ts` vs `*.page.ts`)
+- the required setup, helper imports, or wrappers differ
+- the failure mode differs enough that irrelevant guidance would distract or mislead
+- the split tracks distinct directory buckets that agents enter independently
+
+Prefer a **single** rule only when the same concise guidance is genuinely helpful across all matching targets.
+
+### 6. Check for Exception Patterns
+
+**This is the highest-value check.** Look for file-type or directory-level patterns that require an **exception** to a project-wide rule:
+
+- Storybook files needing `export default` when the project bans default exports
+- Test files needing specific imports/setup that bypass normal module rules
+- Config files that use CommonJS (`module.exports`) in an ESM project
+- Generated files that should never be hand-edited despite appearing in source
+- Template/render files that require escaping/sanitization patterns different from the general codebase
+- File types that use different instantiation, registration, or API-version rules than the surrounding project
+- File types that intentionally carry lint suppressions (`phpcs:ignore`, `eslint-disable`, etc.) for narrow, documented reasons
+
+Exception-to-rule patterns are the most important to capture because agents will follow the general project rule and produce incorrect code.
+
+Do not reduce this check to "default export exception." Investigate any deviation from general project norms that is scoped to a particular file or directory pattern.
+
+### 7. Assess Correctness and Security Impact
+
+For each pattern, determine what happens when an agent writes a new file of this type **without** the rule:
+
+| Impact Level               | Description                                      | Examples                                                                |
+| -------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------- |
+| **Crashes/breaks**         | Code won't compile, tests won't run, app crashes | Missing test providers, wrong export type, missing required boilerplate |
+| **Visual/behavioral bugs** | Code runs but produces wrong results             | Hardcoded colors breaking dark mode, missing accessibility wrappers     |
+| **Security vulnerability** | Code introduces unsafe output or dangerous flows | Missing escaping, unsafe HTML injection, raw SQL without safeguards     |
+| **Lint/CI failures**       | Code works but fails automated checks            | Wrong export style, missing eslint-disable for known exceptions         |
+| **Style inconsistency**    | Code works but doesn't match conventions         | Different file structure, inconsistent naming                           |
+
+Security-sensitive file types deserve explicit scrutiny. In PHP/WordPress repos, inspect template/rendering files for escaping, sanitization, and `phpcs:ignore` directives. In React/JS repos, inspect `dangerouslySetInnerHTML`, raw HTML rendering helpers, and any documented exception zones.
+
+## Assessment Output
+
+For each discovered pattern, record:
+
+| Field                          | Description                                                            |
+| ------------------------------ | ---------------------------------------------------------------------- |
+| **Pattern**                    | Extension or glob pattern (e.g., `**/*.stories.tsx`, `**/*.css`)       |
+| **File count**                 | Total files matching                                                   |
+| **Consistency**                | `N/M files follow pattern` (e.g., `72/72`)                             |
+| **Competing sub-patterns**     | Split details when multiple valid patterns exist                       |
+| **Convention summary**         | Specific shared import/export/template requirements from sampled files |
+| **Correctness impact**         | What breaks without the rule                                           |
+| **Exception to project rule?** | Yes/No — if yes, which rule is overridden                              |
+| **Evidence**                   | 3–5 sampled file paths                                                 |
+| **Severity**                   | See calibration below                                                  |
+
+## Severity Calibration
+
+Glob-scoped rule severity should account for:
+
+1. **File count** — More files = more likely an agent encounters this pattern
+2. **Correctness impact** — Will code crash, produce wrong output, or fail lint?
+3. **Exception patterns** — Does this contradict a project-wide rule?
+4. **Split ratio** — Will an agent effectively guess between competing patterns?
+5. **Security sensitivity** — Could the wrong pattern create a vulnerability?
+
+| Criteria                                                  | Severity   |
+| --------------------------------------------------------- | ---------- |
+| `40–60%` split with correctness or security impact        | **High**   |
+| Security-sensitive exception pattern                      | **High**   |
+| Exception to project-wide rule AND code breaks/fails lint | **High**   |
+| >20 files AND correctness impact (crashes, visual bugs)   | **High**   |
+| >20 files AND lint/CI failures                            | **Medium** |
+| `40–60%` split with lint/behavioral differences only      | **Medium** |
+| 5–20 files with any correctness impact                    | **Medium** |
+| Style consistency only, no correctness impact             | **Low**    |
+
+## Co-Location Conventions
+
+Beyond individual file types, check for **co-location patterns** — conventions about which files must exist together in a directory:
+
+- Does every component directory require a `styles.ts`?
+- Does every feature module require an `index.ts` barrel export?
+- Are test files always co-located with source files, or in a separate `__tests__/` directory?
+- Do component directories follow a category system with different rules per category?
+- Do repeated directories split between two structural approaches, and if so which one should new directories follow?
+- Do metadata files imply required implementation siblings, templates, or registration code?
+- Do older directories and newer directories use different schema/API versions?
+
+Co-location patterns often indicate the need for a glob-scoped rule at the directory pattern level (e.g., `src/components/**/*.tsx`).

package/assets/skills/oat-agent-instructions-analyze/references/quality-checklist.md

@@ -0,0 +1,125 @@
+# Instruction File Quality Checklist
+
+Per-file evaluation criteria for agent instruction files. Use this checklist to score each instruction file during analysis. The full quality guidance lives in `docs/agent-instruction.md` — this is a distilled, actionable checklist.
+
+## Evaluation Criteria
+
+### 1. Commands Correct and Runnable
+
+- [ ] All referenced commands exist in package.json scripts or are valid shell commands
+- [ ] Command sequences match the documented build/test/lint workflow
+- [ ] No placeholder commands (`{command}`, `TODO`, etc.) in non-template files
+- **Severity if failing:** Medium (stale commands) or Critical (commands that would break builds)
+
+### 2. Non-Negotiables Near Top
+
+- [ ] Security rules, access controls, and data handling requirements appear in the first screenful (~30 lines)
+- [ ] Canonical commands (install, dev, build, test, lint) appear before detailed conventions
+- [ ] "Definition of Done" or acceptance criteria are present early
+- **Severity if failing:** High (security non-negotiables missing) or Medium (ordering issue)
+
+### 3. No Duplication Across Files
+
+- [ ] Root file does not repeat content that scoped files cover
+- [ ] Scoped files do not copy-paste root-level sections
+- [ ] Cross-file `@import` or reference directives are used where appropriate
+- **Severity if failing:** Medium
+
+### 4. Size Within Budget
+
+- [ ] Root files (AGENTS.md, CLAUDE.md): <300 lines (hard max 500)
+- [ ] Scoped/package files: 40–150 lines
+- [ ] Individual rules files: <80 lines
+- [ ] Always-on baseline load is estimated and kept comfortably below the task budget
+- [ ] Typical task load (root + one realistic scoped file + matching rules) is estimated and fits within the 32 KiB task budget
+- [ ] Worst-case task load is estimated and explicitly called out if it is likely to strain the budget
+- [ ] Aggregate repo total is reported separately for awareness, not treated as the operative task budget by itself
+- **Severity if failing:** Medium (over budget) or Low (close to limit)
+
+### 5. Scoped Only for Real Divergence
+
+- [ ] Scoped files exist only where the directory has genuinely different stack, workflow, or domain requirements
+- [ ] No scoped files that merely repeat root-level guidance
+- **Severity if failing:** Low
+
+### 6. Precedence Clear
+
+- [ ] Override semantics are explicit (nearest-wins for AGENTS.md, import directives for CLAUDE.md)
+- [ ] No ambiguous or conflicting instructions across scope levels
+- **Severity if failing:** Medium
+
+### 7. No Circular Imports
+
+- [ ] File A does not import File B which imports File A
+- [ ] Import chains are acyclic
+- **Severity if failing:** High
+
+### 8. Definition of Done Present
+
+- [ ] Objective, verifiable criteria for when work is "done"
+- [ ] Not vague ("write good code") — concrete checks (tests pass, lint clean, types valid)
+- **Severity if failing:** Medium
+
+### 9. Staleness
+
+- [ ] Referenced file paths still exist in the repo
+- [ ] Referenced commands still work
+- [ ] Technology/framework references match current stack
+- [ ] No references to removed features or deprecated patterns
+- **Severity if failing:** Medium (stale references) or High (actively misleading)
+
+### 10. Cross-Format Body Consistency
+
+- [ ] Glob-scoped rules targeting the same paths have identical body content across providers
+- [ ] Only frontmatter differs between Claude rules, Cursor rules, and Copilot instructions
+- [ ] Body divergence is flagged as drift
+- **Severity if failing:** Medium
+
+### 11. Claims Are Evidence-Backed
+
+- [ ] Every non-obvious convention is backed by a concrete repo source (config, docs, existing instructions, or representative code samples)
+- [ ] Numeric claims (`N files`, split ratios, "only X uses Y") are backed by exhaustive repo-wide counts, not samples
+- [ ] Recommendations that remove or contradict an existing rule cite the verification evidence that justifies the correction
+- [ ] Formatting/style claims are omitted unless supported by repo evidence
+- [ ] If a formatter or linter enforces the rule, the file prefers commands/links over prose restatement
+- **Severity if failing:** High (actively misleading) or Medium (unsupported claim)
+
+### 12. Progressive Disclosure Is Used
+
+- [ ] Always-on instructions keep only the minimal essential guidance inline
+- [ ] Deeper detail links to canonical docs/config/examples instead of copying them into the instruction file
+- [ ] The file clearly distinguishes inline essentials from optional deeper reading
+- **Severity if failing:** Medium
+
+### 13. File-Type Conventions Covered
+
+This criterion applies to the **overall instruction set**, not to individual files. Evaluate once per analysis.
+
+- [ ] Common file-type patterns (tests, stories, styles, configs) with 5+ files have been evaluated for rule opportunities
+- [ ] Patterns with >80% consistency and correctness impact are flagged as glob-scoped rule opportunities
+- [ ] Patterns with competing sub-patterns (especially `40–60%` splits) are explicitly evaluated and flagged when agents are likely to guess wrong
+- [ ] Materially different activation targets are split into separate rule recommendations when that improves precision
+- [ ] Security-sensitive file-type patterns are explicitly evaluated for rule opportunities and severity
+- [ ] Patterns that are exceptions to project-wide rules are explicitly called out (these are highest-value)
+- [ ] Existing glob-scoped rules cover the identified patterns, or coverage gaps are recorded
+- **Severity if failing:** Medium (missed pattern) or High (missed exception-to-rule pattern)
+
+### 14. Available Documentation Is Referenced
+
+This criterion uses the documentation inventory from Step 2 (Discover Documentation Surfaces).
+
+- [ ] Instruction files reference relevant available documentation (READMEs, docs pages, architecture docs) in their References section
+- [ ] Scoped instruction files reference docs topically relevant to their directory scope (e.g., a package AGENTS.md references the package's README or docs subtree)
+- [ ] References point to existing, current documentation (not stale or removed)
+- [ ] Content duplicated from available docs is flagged for `link_only` disclosure instead of inline repetition
+- **Severity if failing:** Low (missing references) or Medium (duplicates content that exists in available docs)
+
+## Scoring
+
+For each file, count passing criteria out of the applicable set (some criteria only apply to certain file types).
+A "miss" means one numbered criterion does not pass for that file after ignoring non-applicable checks within the criterion:
+
+- **All applicable passing** → Quality: pass
+- **1-2 misses** → Quality: minor issues
+- **3-5 misses** → Quality: significant issues
+- **6+ misses** → Quality: major issues

package/assets/skills/oat-agent-instructions-analyze/references/recommendation-pack-template.md

@@ -0,0 +1,45 @@
+# Recommendation Pack: `rec-001`
+
+## Target
+
+- Action: {create / update}
+- Path: `{path}`
+- Provider / Format: {provider / format}
+- Disclosure: {inline / link_only / omit / ask_user}
+
+## Evidence
+
+- `{path}:{line}` - {why this evidence matters}
+- `{path}:{line}` - {supporting configuration, docs, or code pattern}
+
+## Structural Conventions
+
+- {imports, exports, file layout, frontmatter, or structural template rules}
+
+## Behavioral Conventions
+
+- {delegation, sequencing, runtime behavior, workflow rules, or architecture expectations}
+
+## Counter-Examples
+
+- {common mistake or anti-pattern}
+- {structurally valid but architecturally wrong output}
+
+## New-File Workflow
+
+1. {creation or wiring step}
+2. {registration, sync, or follow-up step}
+
+## Preferred Default for New Files
+
+{pattern A / pattern B / N/A}
+
+## Claim Corrections
+
+- `{old claim -> verified replacement}`
+
+## Generation Constraints
+
+- Must Include: {required claims, commands, references, examples, or behavior}
+- Must Not Include: {unsupported or stale guidance}
+- Link Targets: {path / URL or `N/A`}

package/assets/skills/oat-agent-instructions-analyze/references/recommendations-manifest-template.yaml

@@ -0,0 +1,27 @@
+bundleVersion: 1
+analysisArtifact: { artifact-path }
+summary: summary.md
+recommendations:
+  - id: rec-001
+    action: create
+    target: path/to/file
+    provider: agents_md
+    format: AGENTS.md
+    severity: high
+    confidence: high
+    disclosure: inline
+    pack: packs/rec-001.md
+  - id: rec-002
+    action: update
+    target: path/to/existing-file
+    provider: cursor
+    format: glob-rule
+    severity: medium
+    confidence: medium
+    disclosure: link_only
+    pack: packs/rec-002.md
+
+# Rules:
+# - Every recommendation referenced here must also exist in the markdown analysis artifact.
+# - `pack` must be a relative path under this bundle directory.
+# - The manifest is the primary index used by oat-agent-instructions-apply when the bundle exists.

package/assets/skills/oat-agent-instructions-analyze/scripts/resolve-instruction-files.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# resolve-instruction-files.sh — Discover instruction files by provider
+#
+# Usage:
+#   resolve-providers.sh --non-interactive | resolve-instruction-files.sh
+#   resolve-instruction-files.sh --providers agents_md,claude,cursor
+#
+# Input: newline-separated provider names (stdin or --providers arg)
+# Output: tab-separated "provider\tpath" per line, sorted
+#
+# File patterns per provider:
+#   agents_md → **/AGENTS.md
+#   claude    → **/CLAUDE.md, .claude/rules/*.md
+#   cursor    → .cursor/rules/*.mdc, .cursor/rules/*.md
+#   copilot   → .github/copilot-instructions.md, .github/instructions/*.instructions.md
+#   cline     → .cline/rules/*
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+# Exclusion: prune repo-root node_modules, .worktrees, .git, and .oat directories,
+# plus nested node_modules anywhere below REPO_ROOT. Using -prune avoids traversing
+# excluded trees while preserving worktrees whose absolute path contains ".worktrees".
+find_exclude() {
+  find "$REPO_ROOT" \
+    \( -path "${REPO_ROOT}/node_modules" \
+      -o -path "${REPO_ROOT}/.worktrees" \
+      -o -path "${REPO_ROOT}/.git" \
+      -o -path "${REPO_ROOT}/.oat" \
+      -o -path '*/node_modules' \) -prune -o \
+    \( "$@" \) -print \
+    2>/dev/null || true
+}
+
+# Parse providers from --providers arg or stdin
+PROVIDERS=()
+if [[ "${1:-}" == "--providers" ]]; then
+  IFS=',' read -ra PROVIDERS <<< "${2:-}"
+else
+  # Read from stdin
+  while IFS= read -r line; do
+    line="$(echo "$line" | tr -d '[:space:]')"
+    [[ -n "$line" ]] && PROVIDERS+=("$line")
+  done
+fi
+
+if [[ ${#PROVIDERS[@]} -eq 0 ]]; then
+  echo "Error: no providers specified. Pipe from resolve-providers.sh or use --providers." >&2
+  exit 1
+fi
+
+discover_agents_md() {
+  find_exclude -name 'AGENTS.md' | while read -r f; do
+    local rel="${f#"$REPO_ROOT"/}"
+    printf 'agents_md\t%s\n' "$rel"
+  done
+}
+
+discover_claude() {
+  # CLAUDE.md files
+  find_exclude -name 'CLAUDE.md' | while read -r f; do
+    local rel="${f#"$REPO_ROOT"/}"
+    printf 'claude\t%s\n' "$rel"
+  done
+
+  # Claude rules
+  if [[ -d "${REPO_ROOT}/.claude/rules" ]]; then
+    find "${REPO_ROOT}/.claude/rules" -name '*.md' -type f 2>/dev/null | while read -r f; do
+      local rel="${f#"$REPO_ROOT"/}"
+      printf 'claude\t%s\n' "$rel"
+    done
+  fi
+}
+
+discover_cursor() {
+  if [[ -d "${REPO_ROOT}/.cursor/rules" ]]; then
+    find "${REPO_ROOT}/.cursor/rules" \( -name '*.mdc' -o -name '*.md' \) -type f 2>/dev/null | while read -r f; do
+      local rel="${f#"$REPO_ROOT"/}"
+      printf 'cursor\t%s\n' "$rel"
+    done
+  fi
+}
+
+discover_copilot() {
+  # Root copilot instructions
+  if [[ -f "${REPO_ROOT}/.github/copilot-instructions.md" ]]; then
+    printf 'copilot\t%s\n' ".github/copilot-instructions.md"
+  fi
+
+  # Scoped instructions
+  if [[ -d "${REPO_ROOT}/.github/instructions" ]]; then
+    find "${REPO_ROOT}/.github/instructions" -name '*.instructions.md' -type f 2>/dev/null | while read -r f; do
+      local rel="${f#"$REPO_ROOT"/}"
+      printf 'copilot\t%s\n' "$rel"
+    done
+  fi
+}
+
+discover_cline() {
+  if [[ -d "${REPO_ROOT}/.cline/rules" ]]; then
+    find "${REPO_ROOT}/.cline/rules" -type f 2>/dev/null | while read -r f; do
+      local rel="${f#"$REPO_ROOT"/}"
+      printf 'cline\t%s\n' "$rel"
+    done
+  fi
+}
+
+# Run discovery for each provider
+for provider in "${PROVIDERS[@]}"; do
+  case "$provider" in
+    agents_md)  discover_agents_md ;;
+    claude)     discover_claude ;;
+    cursor)     discover_cursor ;;
+    copilot)    discover_copilot ;;
+    cline)      discover_cline ;;
+    codex)      ;; # codex reads AGENTS.md natively, no additional files
+    *)          echo "Warning: unknown provider '$provider', skipping" >&2 ;;
+  esac
+done | sort -t$'\t' -k1,1 -k2,2