@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-agent-instructions-analyze/references/analysis-artifact-template.md

@@ -0,0 +1,248 @@
+---
+oat_generated: true
+oat_generated_at: { YYYY-MM-DD }
+oat_analysis_type: agent-instructions
+oat_analysis_mode: { full|delta }
+oat_analysis_providers: [{ providers }]
+oat_analysis_commit: { commitHash }
+---
+
+# Agent Instructions Analysis: {repo-name}
+
+**Date:** {YYYY-MM-DD}
+**Mode:** {full|delta}
+**Providers:** {agents_md, claude, cursor, ...}
+**Commit:** {short-hash}
+
+## Bundle Outputs
+
+The companion bundle for this analysis lives beside the markdown artifact and is the primary generation contract for
+`oat-agent-instructions-apply` when present.
+
+| Path                                | Purpose                                       |
+| ----------------------------------- | --------------------------------------------- |
+| `{artifact-path}`                   | Human-readable review artifact                |
+| `{bundle-dir}/summary.md`           | Compact bridge summary for apply-time context |
+| `{bundle-dir}/recommendations.yaml` | Manifest of executable recommendations        |
+| `{bundle-dir}/packs/`               | Recommendation-scoped packs                   |
+
+Every recommendation below should include a stable `Recommendation ID` that maps to exactly one pack file.
+
+## Summary
+
+- **Files evaluated:** {N}
+- **Coverage:** {N}% of assessed directories have instruction files
+- **Findings:** {N} Critical, {N} High, {N} Medium, {N} Low
+- **Delta scope:** {N/A or "N files changed since {base-commit}"}
+- **Evidence-backed recommendations:** {N}
+- **Open questions / ask-user items:** {N}
+
+## Documentation Inventory
+
+Available documentation surfaces discovered in this repository. Used to populate link targets for `link_only` disclosure decisions and to evaluate Criterion 14 (Available Documentation Is Referenced).
+
+| #   | Type                                   | Path     | Topics/Scope     | Current?            | Notes                                              |
+| --- | -------------------------------------- | -------- | ---------------- | ------------------- | -------------------------------------------------- |
+| 1   | {docs-app/readme/knowledge/standalone} | `{path}` | {topics covered} | {current/stale/N/A} | {e.g., OAT config root, package-level, thin index} |
+| ... |                                        |          |                  |                     |                                                    |
+
+{Or: "No documentation surfaces discovered."}
+
+## Instruction File Inventory
+
+| #   | Provider  | Format    | Path                     | Lines | Quality       |
+| --- | --------- | --------- | ------------------------ | ----- | ------------- |
+| 1   | agents_md | AGENTS.md | `AGENTS.md`              | {N}   | {pass/issues} |
+| 2   | agents_md | AGENTS.md | `packages/cli/AGENTS.md` | {N}   | {pass/issues} |
+| 3   | claude    | CLAUDE.md | `CLAUDE.md`              | {N}   | {pass/issues} |
+| ... |           |           |                          |       |               |
+
+## Instruction Load Budget
+
+Computed task-load scenarios used to evaluate instruction size in practice.
+
+| Scenario                | Includes                                            | Size  | Assessment              | Notes                                      |
+| ----------------------- | --------------------------------------------------- | ----- | ----------------------- | ------------------------------------------ |
+| Always-on baseline load | {e.g., root `AGENTS.md` + root compatibility shim}  | {N} B | {healthy / high / over} | {what loads at task start}                 |
+| Typical task load       | {root + one realistic scoped file + matching rules} | {N} B | {healthy / high / over} | {most common working set}                  |
+| Worst-case task load    | {heaviest realistic scope + matching rules}         | {N} B | {healthy / high / over} | {deepest realistic working set}            |
+| Aggregate repo total    | {all instruction files across all formats}          | {N} B | {awareness only}        | {report separately; not the operative cap} |
+
+{Or: "Load budget not computed."}
+
+## Existing Rule Validation
+
+Validation status for already-checked-in glob-scoped rules. Every numeric or named-file claim should be exhaustively verified here before the analysis recommends a correction.
+
+| #   | Rule Path | Target Globs | Validation Status                     | Claim Corrections                     | Evidence     | Severity          |
+| --- | --------- | ------------ | ------------------------------------- | ------------------------------------- | ------------ | ----------------- |
+| 1   | `{path}`  | `{glob}`     | {verified / needs update / conflicts} | {`old claim -> verified replacement`} | {exact refs} | {High/Medium/Low} |
+| ... |           |              |                                       |                                       |              |                   |
+
+{Or: "No existing glob-scoped rules to validate."}
+
+## Findings
+
+### Critical
+
+{Findings that actively mislead agents or miss security non-negotiables.}
+
+None | {numbered list}
+
+1. **{Title}**
+   - File: `{path}:{line}`
+   - Issue: {description}
+   - Evidence: {exact file refs, config/docs, or representative code samples}
+   - Confidence: {high | medium | low}
+   - Disclosure: {inline | link_only | omit | ask_user}
+   - Fix: {specific guidance}
+
+### High
+
+{Significant gaps — important directories without coverage, major drift.}
+
+None | {numbered list}
+
+### Medium
+
+{Quality issues — over size budget, duplication, stale commands, cross-format body divergence.}
+
+None | {numbered list}
+
+### Low
+
+{Polish — could be better structured, minor staleness.}
+
+None | {numbered list}
+
+## Provider Baseline Gaps
+
+Missing always-on provider compatibility files that should exist even when no corresponding file was discovered during inventory.
+
+| #   | Provider  | Required Path                     | Format             | Reason                                             | Evidence     | Severity      |
+| --- | --------- | --------------------------------- | ------------------ | -------------------------------------------------- | ------------ | ------------- |
+| 1   | `claude`  | `CLAUDE.md`                       | Claude import shim | {claude active + AGENTS.md present + shim missing} | {exact refs} | {High/Medium} |
+| 2   | `copilot` | `.github/copilot-instructions.md` | Copilot shim       | {copilot active + shim missing}                    | {exact refs} | {High/Medium} |
+| ... |           |                                   |                    |                                                    |              |               |
+
+{Or: "No provider baseline gaps identified."}
+
+## Coverage Gaps
+
+### Directory Coverage
+
+Directories assessed as needing instruction files but currently uncovered.
+
+| #   | Directory | Reason                                         | Evidence     | Disclosure                       | Link Target       | Severity      |
+| --- | --------- | ---------------------------------------------- | ------------ | -------------------------------- | ----------------- | ------------- |
+| 1   | `{path/}` | {Has own package.json / distinct domain / ...} | {exact refs} | {inline/link_only/omit/ask_user} | {path/URL or N/A} | {High/Medium} |
+| ... |           |                                                |              |                                  |                   |               |
+
+{Or: "No directory coverage gaps identified."}
+
+### Glob-Scoped Rule Opportunities
+
+File-type patterns with recurring conventions that would benefit from targeted rules files. These are cross-cutting structural concerns that often span multiple directories, but they can also be concentrated in one architectural area and still justify glob-scoped rules.
+
+Discovered using the systematic file-type pattern discovery process from `references/file-type-discovery-checklist.md`.
+
+High/Medium opportunities that warrant creating, updating, or splitting a rule should also appear as explicit entries in **Recommendations** below. Do not rely on this table alone as the apply contract.
+
+| #   | Pattern  | Count | Consistency | Competing Sub-Patterns                                        | Convention Summary                                      | Correctness Impact                        | Exception to Project Rule? | Recommended Action                          | Evidence     | Disclosure                       | Severity          |
+| --- | -------- | ----- | ----------- | ------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------- | -------------------------- | ------------------------------------------- | ------------ | -------------------------------- | ----------------- |
+| 1   | `{glob}` | {N}   | {N/M files} | {none / `A: 9/18, B: 9/18` / version split / directory split} | {brief description of conventions agents should follow} | {crashes/visual bugs/security/lint/style} | {yes: which rule / no}     | {create rule / update rule / split / watch} | {exact refs} | {inline/link_only/omit/ask_user} | {High/Medium/Low} |
+| ... |          |       |             |                                                               |                                                         |                                           |                            |                                             |              |
+
+**Severity calibration:**
+
+- **High:** `40–60%` split with correctness/security impact; OR security-sensitive exception pattern; OR exception to project-wide rule AND code breaks/fails lint; OR >20 files AND correctness impact (crashes, visual bugs)
+- **Medium:** `40–60%` split with lint/behavioral differences only; OR >20 files AND lint/CI failures; OR 5–20 files with correctness impact
+- **Low:** Style consistency only, no correctness impact
+
+{Or: "No glob-scoped rule opportunities identified."}
+
+## Cross-Format Consistency
+
+{For repos with multiple providers: body divergence between glob-scoped rules targeting the same paths.}
+
+| Rule Target | Claude Body Hash | Cursor Body Hash | Copilot Body Hash | Status           |
+| ----------- | ---------------- | ---------------- | ----------------- | ---------------- |
+| `{glob}`    | {hash/N/A}       | {hash/N/A}       | {hash/N/A}        | {match/diverged} |
+
+{Or: "Single provider — cross-format check not applicable."}
+
+## Progressive Disclosure Decisions
+
+Capture which details should live in always-on instructions versus linked documentation/config.
+
+| Topic     | Decision                         | Keep Inline In                     | Link Target     | Evidence     |
+| --------- | -------------------------------- | ---------------------------------- | --------------- | ------------ |
+| `{topic}` | {inline/link_only/omit/ask_user} | `{AGENTS.md / scoped file / rule}` | `{path or URL}` | {exact refs} |
+| ...       |                                  |                                    |                 |              |
+
+{Or: "No additional progressive disclosure decisions beyond the findings/recommendations below."}
+
+## Recommendations
+
+Prioritized actions based on findings above.
+
+1. **{Action}** — {rationale} (addresses finding #{N})
+   - Recommendation ID: `rec-001`
+   - Target: `{path}`
+   - Provider/Format: {provider / format}
+   - Bundle Pack: `{bundle-dir}/packs/rec-001.md`
+   - Evidence: {exact refs}
+   - Confidence: {high | medium | low}
+   - Disclosure: {inline | link_only | omit | ask_user}
+   - Link Targets: {path/URL or N/A}
+   - Content Guidance: {high-level generation guidance}
+   - Must Include: {claims, commands, references, or examples that must survive generation}
+   - Must Not Include: {unsupported claims or stale guidance to avoid}
+   - Preferred Default for New Files: {pattern A / pattern B / N/A}
+   - Claim Corrections: {`old claim -> verified replacement` or `none`}
+2. **{Action}** — {rationale} (addresses provider baseline gap #{N})
+   - Recommendation ID: `rec-002`
+   - Target: `{path}`
+   - Provider/Format: {provider / format}
+   - Bundle Pack: `{bundle-dir}/packs/rec-002.md`
+   - Evidence: {exact refs}
+   - Confidence: {high | medium | low}
+   - Disclosure: {inline | link_only | omit | ask_user}
+   - Link Targets: {path/URL or N/A}
+   - Content Guidance: {high-level generation guidance}
+   - Must Include: {claims, commands, references, or examples that must survive generation}
+   - Must Not Include: {unsupported claims or stale guidance to avoid}
+   - Preferred Default for New Files: {pattern A / pattern B / N/A}
+   - Claim Corrections: {`old claim -> verified replacement` or `none`}
+3. **{Action}** — {rationale} (addresses gap #{N})
+   - Recommendation ID: `rec-003`
+   - Target: `{path}`
+   - Provider/Format: {provider / format}
+   - Bundle Pack: `{bundle-dir}/packs/rec-003.md`
+   - Evidence: {exact refs}
+   - Confidence: {high | medium | low}
+   - Disclosure: {inline | link_only | omit | ask_user}
+   - Link Targets: {path/URL or N/A}
+   - Content Guidance: {high-level generation guidance}
+   - Must Include: {claims, commands, references, or examples that must survive generation}
+   - Must Not Include: {unsupported claims or stale guidance to avoid}
+   - Preferred Default for New Files: {pattern A / pattern B / N/A}
+   - Claim Corrections: {`old claim -> verified replacement` or `none`}
+4. ...
+
+## Apply Contract
+
+- `oat-agent-instructions-apply` may only implement recommendations backed by evidence in this artifact and its
+  companion bundle.
+- When the companion bundle exists, apply should treat `recommendations.yaml` plus `packs/*.md` as the primary
+  generation contract and use this markdown artifact as reviewer context.
+- Recommendations marked `omit` must stay out of generated instructions.
+- Recommendations marked `ask_user` require explicit user confirmation before generation.
+- If cited config/docs/files are missing at apply time, stop and re-run analyze or ask the user rather than inventing a replacement rule.
+- If formatter/linter config already enforces a style rule, generated instructions should prefer commands and links over prose restatement.
+- If a recommendation updates or contradicts an existing rule, apply should follow the `Claim Corrections`,
+  `Must Include`, `Must Not Include`, and `Preferred Default for New Files` fields rather than improvising.
+
+## Next Step
+
+Run `oat-agent-instructions-apply` with this artifact to generate or update instruction files.

package/assets/skills/oat-agent-instructions-analyze/references/bundle-summary-template.md

@@ -0,0 +1,31 @@
+---
+bundle_version: 1
+analysis_artifact: { artifact-path }
+manifest: recommendations.yaml
+pack_count: { N }
+generated_at: { YYYY-MM-DD }
+---
+
+# Agent Instructions Analysis Bundle Summary
+
+Companion bundle for `{artifact-path}`.
+
+## Purpose
+
+This bundle is the machine-oriented handoff for `oat-agent-instructions-apply`.
+The markdown analysis artifact remains the reviewer-facing summary. If they diverge, the bundle wins for generation.
+
+## Recommendation Index
+
+| ID        | Action          | Target   | Provider / Format   | Pack               | Notes             |
+| --------- | --------------- | -------- | ------------------- | ------------------ | ----------------- |
+| `rec-001` | {create/update} | `{path}` | {provider / format} | `packs/rec-001.md` | {short rationale} |
+| ...       |                 |          |                     |                    |                   |
+
+## Validation Rules
+
+- Every recommendation in `recommendations.yaml` must appear in this table.
+- Every listed pack file must exist under `packs/`.
+- Recommendation IDs must match across the markdown artifact, the manifest, and the pack filename.
+- Apply may use this summary for quick context, but it should load the manifest and matching pack before generating
+  output.

package/assets/skills/oat-agent-instructions-analyze/references/directory-assessment-criteria.md

@@ -0,0 +1,93 @@
+# Directory Assessment Criteria
+
+When does a directory need its own instruction file? Use these criteria to identify coverage gaps during analysis. The full guidance lives in `docs/agent-instruction.md` — this is a distilled, actionable checklist.
+
+## Primary Indicators (any one = likely needs instructions)
+
+### 1. Has Own Build Configuration
+
+- Contains `package.json`, `tsconfig.json`, `Cargo.toml`, `go.mod`, or similar
+- Has its own build/test/lint commands distinct from the root
+- **Signal strength:** Strong — this is a semi-independent unit with its own workflow
+
+### 2. Different Tech Stack from Parent
+
+- Uses a different language, framework, or runtime than the parent directory
+- Example: root is TypeScript/Node but this directory is Python or Rust
+- **Signal strength:** Strong — agents need different conventions and commands
+
+### 3. Public API Surface
+
+- Exposes APIs consumed by external callers (REST endpoints, library exports, CLI commands)
+- Has consumers outside the repo or outside the directory
+- **Signal strength:** Strong — API contracts and conventions must be explicit
+
+### 4. Distinct Domain Boundary
+
+- Represents a bounded context or module with domain-specific business logic
+- Has its own data models, terminology, or invariants
+- Example: `packages/billing/`, `services/auth/`, `lib/search-engine/`
+- **Signal strength:** Moderate — depends on complexity
+
+### 5. Significant Codebase (>10 source files)
+
+- Contains more than ~10 source files with specialized conventions
+- Has patterns or conventions that differ from the rest of the repo
+- **Signal strength:** Moderate — larger directories benefit more from explicit guidance
+
+## Large Directory Decomposition
+
+When a directory meets 1+ primary indicators and contains **more than 50 source files**, assess its major
+subdirectories starting at depth 1-2 before writing a single broad recommendation.
+
+If the first pass still leaves a sub-area that is large or clearly heterogeneous, keep decomposing deeper until the
+distinct conventions are visible or the analysis stops yielding materially different guidance.
+
+Check whether subdirectories differ by:
+
+- tech stack or runtime (for example, embedded React client vs Node server code)
+- dominant file-type patterns (for example, resolvers vs repositories vs jobs)
+- build or tooling configuration (separate tsconfigs, bundlers, framework configs)
+- domain boundary or API surface
+
+Record distinct sub-areas in the coverage gap assessment. A scoped `AGENTS.md` recommendation for a large directory
+should enumerate the major sub-areas and their conventions, not just report the total file count.
+
+## Secondary Indicators (strengthen the case but not sufficient alone)
+
+### 6. Has Specialized Testing Patterns
+
+- Uses different test frameworks or patterns than the root
+- Has integration tests, E2E tests, or performance tests with specific setup requirements
+
+### 7. Has Deployment or Infrastructure Concerns
+
+- Contains IaC, deployment configs, or CI/CD pipelines
+- Has environment-specific configuration
+
+### 8. Multiple Contributors with Different Conventions
+
+- Directory is a common source of style inconsistencies or review feedback
+- Has implicit conventions that are not documented anywhere
+
+## Assessment Output
+
+For each directory meeting 1+ primary indicators:
+
+| Directory | Indicators       | Severity    | Recommendation                                     |
+| --------- | ---------------- | ----------- | -------------------------------------------------- |
+| `{path/}` | {which criteria} | High/Medium | Create scoped AGENTS.md / Create rules for {topic} |
+
+**Severity mapping:**
+
+- **High:** Primary indicators 1-3 (own build, different stack, public API) — these are clear gaps
+- **Medium:** Primary indicators 4-5 (domain boundary, large codebase) — beneficial but not urgent
+
+## Exclusions
+
+Do NOT flag these as needing instructions:
+
+- `node_modules/`, `dist/`, `build/`, `.git/` — generated/external
+- Directories with <5 source files and no build config — too small to warrant overhead
+- Test directories that follow the same patterns as their parent — covered by parent instructions
+- Directories already covered by a parent's scoped rules (e.g., Cursor rule with `globs: packages/cli/**`)