@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/agents-md-root.md

@@ -0,0 +1,85 @@
+# Root AGENTS.md Template
+
+Use this template when generating a root-level AGENTS.md file. This is the canonical, provider-agnostic instruction file — all providers read it.
+
+## Template
+
+```markdown
+# {Project Name}
+
+## Development Commands
+
+### Essential Commands
+
+- `{install-command}` - Install dependencies
+- `{dev-command}` - Start development server
+- `{build-command}` - Build for production
+- `{test-command}` - Run tests
+- `{lint-command}` - Lint code
+
+### Additional Commands
+
+- {Any project-specific commands}
+- {Point to `package.json`/`composer.json`/task runner config as the canonical command source of truth when applicable}
+
+## Architecture Overview
+
+{2-4 sentences describing the project structure, key modules, and how they relate.}
+
+### Key Directories
+
+- `{dir/}` - {purpose}
+- `{dir/}` - {purpose}
+
+### Technology Stack
+
+- **Runtime:** {e.g., Node.js 22, Python 3.12 — include concrete versions when the repo evidence provides them}
+- **Framework:** {e.g., Next.js 15, FastAPI}
+- **Infrastructure:** {e.g., Docker Compose, local DB, cloud/service environment, wrapper scripts}
+- **Build:** {e.g., Turborepo, Webpack}
+- **Testing:** {e.g., Vitest, pytest}
+- **Commit Format:** {e.g., Conventional Commits with commitlint — only if the repo enforces one}
+
+## Code Conventions
+
+### Style
+
+- {Only repo-specific, evidence-backed rules that are NOT already reliably enforced by formatter/linter}
+- {Prefer links to canonical docs/config when the detail is too deep for always-on instructions}
+
+### Patterns
+
+- {Key architectural patterns — e.g., "prefer composition over inheritance"}
+
+### Non-Negotiables
+
+- {Security rules, access control patterns}
+- {Data handling requirements}
+- {Error handling conventions}
+
+## Definition of Done
+
+- [ ] Tests pass (`{test-command}`)
+- [ ] Lint clean (`{lint-command}`)
+- [ ] Type check passes (`{type-check-command}`)
+- [ ] Build succeeds (`{build-command}`)
+
+## References
+
+- `{doc-path-or-url}` - {when to read it}
+```
+
+## Guidance
+
+- Target: <300 lines (hard max 500)
+- Canonical commands should appear in the first screenful
+- When version numbers are available in repo evidence, include them instead of generic stack names
+- Call out local infrastructure or wrapper scripts when they materially affect how the project runs
+- If commit format is enforced by repo config, mention it explicitly
+- Prefer noting the canonical command source of truth (`package.json`, `composer.json`, Makefile, etc.) so static command lists do not drift
+- Non-negotiables (security, data handling) should be near the top
+- Don't duplicate content that belongs in scoped files
+- This file is read by ALL providers — keep it provider-agnostic
+- Only include conventions that are backed by repo evidence
+- If formatter/linter config already enforces a style rule, prefer commands or links over restating the rule
+- Use progressive disclosure: keep essentials inline and link to deeper docs/config/examples

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/agents-md-scoped.md

@@ -0,0 +1,62 @@
+# Scoped AGENTS.md Template
+
+Use this template when generating an AGENTS.md for a subdirectory (package, service, module). This supplements the root AGENTS.md with directory-specific guidance.
+
+## Template
+
+```markdown
+# {Package/Module Name}
+
+## Commands
+
+- `{test-command}` - Run tests for this package
+- `{build-command}` - Build this package
+- `{lint-command}` - Lint this package
+- {Any package-specific commands}
+
+## Architecture
+
+{2-3 sentences describing this module's purpose, boundaries, and how it fits into the larger project.}
+
+### Key Files
+
+- `{file}` - {purpose}
+- `{file}` - {purpose}
+
+### Technology Stack
+
+- **Runtime:** {e.g., Node.js 22, Python 3.12}
+- **Framework:** {e.g., Express, FastAPI}
+- **Testing:** {e.g., Vitest, pytest}
+
+## Conventions
+
+### Patterns
+
+- {Key patterns specific to this directory — e.g., "all handlers follow the Controller pattern"}
+
+### Non-Negotiables
+
+- {Security or data handling rules specific to this module}
+- {Error handling conventions that differ from root}
+
+## Definition of Done
+
+- [ ] Tests pass (`{test-command}`)
+- [ ] Lint clean (`{lint-command}`)
+- [ ] Type check passes (`{type-check-command}`)
+
+## References
+
+- `{doc-path-or-url}` - {when to read it}
+```
+
+## Guidance
+
+- Target: 40–150 lines
+- Only create when the directory has genuinely different stack, workflow, or domain requirements
+- Do NOT duplicate root-level guidance — only add what's different
+- Commands should be runnable from the package directory
+- Inherits from root AGENTS.md by default; this file adds or overrides
+- Keep only directory-specific essentials inline; link to deeper module docs/config when helpful
+- Only include conventions backed by repo evidence for this subtree

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/frontmatter/claude-rule.md

@@ -0,0 +1,67 @@
+# Claude Rule Frontmatter
+
+Claude Code rules live at `.claude/rules/*.md`. They use `paths` as the only frontmatter field.
+
+## Unconditional (Always-On)
+
+No frontmatter needed — plain markdown files without `---` delimiters are always loaded.
+
+```markdown
+# {Rule Title}
+
+{Rule body — identical to glob-scoped-rule.md template body}
+```
+
+## Conditional (Path-Scoped)
+
+Uses `paths` frontmatter — an array of glob patterns.
+
+```yaml
+---
+paths:
+  - '{glob-pattern-1}'
+  - '{glob-pattern-2}'
+---
+# {Rule Title}
+
+{ Rule body — identical to glob-scoped-rule.md template body }
+```
+
+## Examples
+
+### Single glob
+
+```yaml
+---
+paths:
+  - 'src/api/**/*.ts'
+---
+```
+
+### Multiple globs
+
+```yaml
+---
+paths:
+  - 'src/**/*.test.ts'
+  - 'tests/**/*.ts'
+---
+```
+
+### Brace expansion
+
+```yaml
+---
+paths:
+  - 'src/**/*.{ts,tsx}'
+---
+```
+
+## Reference
+
+- Location: `.claude/rules/*.md`
+- Subdirectories supported and recursively discovered
+- Symlinks supported
+- Only documented frontmatter field: `paths` (array of glob strings)
+- Activation: rule loads when Claude reads files matching any pattern in `paths`
+- See `references/docs/rules-files.md` section 2.5 for full details

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/frontmatter/copilot-instruction.md

@@ -0,0 +1,70 @@
+# Copilot Scoped Instruction Frontmatter
+
+Copilot scoped instructions live at `.github/instructions/*.instructions.md`. They use `applyTo` as the primary activation field.
+
+## Glob-Scoped
+
+```yaml
+---
+applyTo: '{glob-pattern-1},{glob-pattern-2}'
+---
+# {Rule Title}
+
+{ Rule body — identical to glob-scoped-rule.md template body }
+```
+
+## With Optional Fields
+
+```yaml
+---
+applyTo: '{glob-pattern}'
+description: '{Brief purpose — shown on hover in VS Code}'
+---
+# {Rule Title}
+
+{ Rule body — identical to glob-scoped-rule.md template body }
+```
+
+## Frontmatter Fields
+
+| Field          | Required | Description                                                                              |
+| -------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `applyTo`      | No       | Glob pattern(s), comma-separated. Relative to workspace root.                            |
+| `description`  | No       | Short description shown on hover (VS Code). Enables semantic matching when no `applyTo`. |
+| `name`         | No       | Display name in UI (VS Code). Defaults to filename.                                      |
+| `excludeAgent` | No       | Prevents use by a specific agent. Values: `"code-review"` or `"coding-agent"`.           |
+
+## Examples
+
+### TypeScript files
+
+```yaml
+---
+applyTo: '**/*.ts,**/*.tsx'
+---
+```
+
+### Scoped to directory
+
+```yaml
+---
+applyTo: 'src/api/**/*.ts'
+description: 'API development conventions'
+---
+```
+
+### Exclude from code review
+
+```yaml
+---
+applyTo: '**/*.test.ts'
+excludeAgent: 'code-review'
+---
+```
+
+## Reference
+
+- Location: `.github/instructions/*.instructions.md`
+- Scoped instructions are additive — they combine with (not replace) `copilot-instructions.md`
+- `applyTo` uses comma-separated globs (not arrays like Claude/Cursor)
+- See `references/docs/rules-files.md` section 4.2 for full details

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/frontmatter/copilot-shim.md

@@ -0,0 +1,35 @@
+# Copilot Instructions Shim Template
+
+Use this template when generating `.github/copilot-instructions.md`. This is a minimal pointer to AGENTS.md, not a content-bearing file.
+
+## Why This Shim Exists
+
+GitHub Copilot reads AGENTS.md natively, but only when enabled via the VS Code setting `chat.useAgentsMdFile` (default: off). The `.github/copilot-instructions.md` file is always read — no setting required.
+
+This shim ensures Copilot users who haven't enabled the AGENTS.md setting still get baseline project instructions.
+
+## Template
+
+```markdown
+<!--
+  This file exists for GitHub Copilot compatibility.
+
+  Copilot can read AGENTS.md natively, but only when the VS Code setting
+  "chat.useAgentsMdFile" is enabled (default: off). This shim ensures
+  baseline project instructions are always available to Copilot regardless
+  of user settings.
+
+  Canonical project instructions live in AGENTS.md at the repository root.
+  Do not add detailed instructions here — keep this as a minimal pointer.
+-->
+
+See AGENTS.md in the repository root for project conventions and instructions.
+```
+
+## Guidance
+
+- Keep this file minimal — it's a pointer, not a content file
+- The HTML comment explains why the shim exists (for future maintainers)
+- Do not duplicate AGENTS.md content here
+- Copilot's scoped instructions (`.github/instructions/*.instructions.md`) handle glob-targeted rules separately
+- This file is always-on for Copilot chat — no frontmatter needed

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/frontmatter/cursor-rule.md

@@ -0,0 +1,84 @@
+# Cursor Rule Frontmatter
+
+Cursor rules live at `.cursor/rules/*.mdc` (or `.md`). They use three frontmatter fields: `description`, `alwaysApply`, and `globs`.
+
+## Always-On
+
+```yaml
+---
+description: '{Brief purpose — used by agent for relevance decisions}'
+alwaysApply: true
+---
+# {Rule Title}
+
+{ Rule body — identical to glob-scoped-rule.md template body }
+```
+
+## Glob-Scoped (Auto Attached)
+
+```yaml
+---
+description: '{Brief purpose}'
+alwaysApply: false
+globs:
+  - '{glob-pattern-1}'
+  - '{glob-pattern-2}'
+---
+# {Rule Title}
+
+{ Rule body — identical to glob-scoped-rule.md template body }
+```
+
+## Agent Requested (No Globs)
+
+```yaml
+---
+description: '{Descriptive purpose — agent decides when to apply based on this}'
+alwaysApply: false
+---
+# {Rule Title}
+
+{ Rule body — identical to glob-scoped-rule.md template body }
+```
+
+## Activation Mode Matrix
+
+| Configuration                                   | Mode                                                 |
+| ----------------------------------------------- | ---------------------------------------------------- |
+| `alwaysApply: true`                             | Always — included in every session                   |
+| `alwaysApply: false` + `globs` set              | Auto Attached — included when matching files appear  |
+| `alwaysApply: false` + `description` (no globs) | Agent Requested — agent decides based on description |
+| No frontmatter                                  | Manual — user must @-mention the rule                |
+
+## Examples
+
+### TypeScript components
+
+```yaml
+---
+description: 'React component conventions for the frontend'
+alwaysApply: false
+globs:
+  - 'src/components/**/*.tsx'
+---
+```
+
+### Test files
+
+```yaml
+---
+description: 'Testing conventions and patterns'
+alwaysApply: false
+globs:
+  - '**/*.test.ts'
+  - '**/*.spec.ts'
+---
+```
+
+## Reference
+
+- Location: `.cursor/rules/*.mdc` or `.cursor/rules/*.md`
+- Naming: kebab-case recommended (e.g., `code-style-guide.mdc`)
+- Three frontmatter fields: `description` (string), `alwaysApply` (boolean), `globs` (string or array)
+- `@filename.ts` syntax supported for file references within rules
+- See `references/docs/cursor-rules-files.md` section 3 for full field reference

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/glob-scoped-rule.md

@@ -0,0 +1,59 @@
+# Glob-Scoped Rule Body Template
+
+Use this template for the **body content** of glob-scoped rules. This body is shared identically across all providers (Claude, Cursor, Copilot) — only the frontmatter differs per provider.
+
+See `frontmatter/` for provider-specific frontmatter examples.
+
+## Template
+
+````markdown
+# {Rule Title}
+
+{1-2 sentences describing what this rule covers and when it applies.}
+
+## Conventions
+
+- {Convention 1 — e.g., "All components must export a default function component"}
+- {Convention 2}
+- {Convention 3}
+
+## Patterns
+
+{Describe expected patterns for files matching this rule's glob.}
+
+- {Pattern 1 — e.g., "Use `describe`/`it` blocks, not `test` blocks"}
+- {Pattern 2}
+
+## References
+
+- `{doc-path-or-url}` - {when to read it instead of expanding inline}
+
+## Examples
+
+{Optional: include a short before/after or canonical example.}
+
+### Correct
+
+```{lang}
+{example}
+```
+````
+
+### Incorrect
+
+```{lang}
+{counter-example}
+```
+
+```
+
+## Guidance
+
+- Target: <80 lines (body only, excluding frontmatter)
+- Write for the specific file pattern — don't repeat general project conventions
+- Keep instructions concrete and actionable, not aspirational
+- This body is used verbatim across Claude rules, Cursor rules, and Copilot instructions
+- Only the frontmatter wrapper changes per provider (see `frontmatter/` directory)
+- Use progressive disclosure: keep the rule short and link to deeper docs/examples when needed
+- Do not encode style trivia unless it is backed by repo evidence and genuinely helps the matching files
+```

package/assets/skills/oat-docs/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: oat-docs
+version: 1.0.0
+description: Use when a user asks questions about OAT workflows, CLI commands, skill authoring, configuration, or project lifecycle. Answers questions by reading locally-bundled OAT documentation.
+argument-hint: '[question]'
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Read, Glob, Grep, AskUserQuestion
+---
+
+# OAT Docs
+
+Interactive Q&A skill backed by locally-bundled OAT documentation at `~/.oat/docs/`. Answers questions about OAT workflows, CLI commands, skill authoring, configuration, and project lifecycle by reading the actual docs.
+
+## Prerequisites
+
+- OAT documentation bundled at `~/.oat/docs/` (installed via `oat init tools` with the core pack).
+
+## Mode Assertion
+
+**OAT MODE: Docs Q&A (Read-Only)**
+
+**Purpose:** Answer user questions about OAT by reading and synthesizing local documentation. Offer to demonstrate or invoke related skills when appropriate.
+
+**BLOCKED Activities:**
+
+- No editing documentation files.
+- No creating or modifying any files.
+- No running CLI commands that modify state.
+- No falling back to repository paths, general knowledge, or web searches for OAT docs content.
+
+**ALLOWED Activities:**
+
+- Reading documentation files under `~/.oat/docs/` to answer questions.
+- Searching documentation with Glob and Grep within `~/.oat/docs/`.
+- Offering to invoke related skills or run demonstration commands (with user confirmation).
+- Asking clarifying questions to refine the user's query.
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- Editing docs content → STOP and return to read-only Q&A mode.
+- Running mutating commands → STOP and offer the command as a suggestion instead.
+- Reading docs from a repo path instead of `~/.oat/docs/` → STOP and use the bundled location only.
+
+**Recovery:**
+
+1. Return to read-only documentation lookup at `~/.oat/docs/`.
+2. Present information and suggestions, not direct modifications.
+
+## Progress Indicators (User-Facing)
+
+Print a phase banner once at start:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ DOCS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step indicators:
+
+- `[1/4] Resolving docs location…`
+- `[2/4] Understanding your question…`
+- `[3/4] Searching documentation…`
+- `[4/4] Synthesizing answer…`
+
+## Process
+
+### Step 1: Resolve Docs Location
+
+Set `DOCS_ROOT` to `~/.oat/docs/`.
+
+Verify the directory exists and contains markdown files. If it does not exist, inform the user:
+
+```
+OAT documentation not found at ~/.oat/docs/.
+
+To install the bundled docs, run:
+  oat init tools
+
+Select the "core" pack when prompted (or use: oat init tools core).
+```
+
+Stop here if docs are not found. Do NOT fall back to repository paths or other locations.
+
+### Step 2: Understand the Question
+
+Read the user's question from `$ARGUMENTS`. If no question was provided or the question is unclear, ask:
+
+> "What would you like to know about OAT? I can help with workflows, CLI commands, skill authoring, configuration, project lifecycle, and more."
+
+Classify the question into one or more topic areas to guide the search:
+
+| Topic Area       | Docs Path                                   | Key Content                                  |
+| ---------------- | ------------------------------------------- | -------------------------------------------- |
+| Getting started  | `quickstart.md`, `guide/getting-started.md` | Installation, first project setup            |
+| Concepts         | `guide/concepts.md`                         | Core OAT concepts and terminology            |
+| CLI commands     | `guide/cli-reference.md`                    | Full CLI command reference                   |
+| Tool packs       | `guide/tool-packs.md`                       | Installing and managing skill packs          |
+| Skills           | `guide/skills/`                             | Skill authoring, SKILL.md format             |
+| Workflows        | `guide/workflow/`                           | Project lifecycle, state machine, artifacts  |
+| Ideas            | `guide/ideas/`                              | Idea capture and brainstorming               |
+| Provider sync    | `guide/provider-sync/`                      | Multi-provider sync, config, commands        |
+| Documentation    | `guide/documentation/`                      | Docs analysis and apply workflows            |
+| Contributing     | `contributing/`                             | Code contributions, design principles, hooks |
+| File locations   | `reference/file-locations.md`               | Where OAT puts things                        |
+| Directory layout | `reference/oat-directory-structure.md`      | `.oat/` and `.agents/` structure             |
+| Troubleshooting  | `reference/troubleshooting.md`              | Common issues and fixes                      |
+
+### Step 3: Search and Read Documentation
+
+Based on the topic classification:
+
+1. **Read the most relevant docs file(s)** — start with the primary match from the topic table. All paths are relative to `DOCS_ROOT` (`~/.oat/docs/`).
+2. **Search for specific terms** — if the question mentions specific concepts, commands, or features, use Grep to find mentions across `~/.oat/docs/`.
+3. **Follow cross-references** — if the primary doc references other pages, read those for complete context.
+4. **Check the index** — read the `index.md` of relevant directories to discover additional relevant pages.
+
+Limit reads to the minimum needed to answer the question thoroughly. Prefer depth (reading a full relevant page) over breadth (skimming many pages).
+
+### Step 4: Synthesize and Answer
+
+Compose an answer that:
+
+1. **Directly answers the question** — lead with the answer, not background context.
+2. **Cites specific docs** — reference the doc file(s) where the user can read more, using relative paths from `~/.oat/docs/`.
+3. **Includes practical examples** — show commands, config snippets, or SKILL.md excerpts when relevant.
+4. **Stays grounded in docs** — only include information found in the actual documentation. Do not speculate or fill gaps with general knowledge.
+
+### Step 5: Offer Next Actions (When Appropriate)
+
+After answering, consider whether to offer related actions:
+
+- **"Want me to show you?"** — if the question was about a workflow, offer to demonstrate the first step.
+- **"Want me to set that up?"** — if the question was about configuration, offer to run the relevant `oat config set` command.
+- **"Want me to create one?"** — if the question was about projects or ideas, offer to invoke the relevant creation skill.
+- **"Want me to check your setup?"** — if the question reveals potential issues, offer to run `/oat-doctor`.
+
+Frame these as suggestions, not automatic actions. Let the user decide.
+
+**Example:**
+
+```
+Based on the docs, here's how OAT project workflows work: [answer]
+
+You can read more in `guide/workflow/lifecycle.md`.
+
+Would you like me to:
+- Start a new project? (I'd invoke oat-project-quick-start)
+- Check your current project status? (I'd read your active project's state.md)
+```
+
+## Examples
+
+### Basic Q&A
+
+**User:** `/oat-docs how do I create a new project?`
+
+**Response:**
+
+```
+To create a new OAT project, you have two main approaches:
+
+1. **Quick mode** (recommended for most tasks):
+   oat-project-quick-start <project-name>
+
+2. **Spec-driven mode** (for complex features):
+   oat-project-new <project-name>
+
+Quick mode goes straight from discovery to plan. Spec-driven mode adds
+formal spec and design phases.
+
+Both create a project directory under your projects root
+(default: .oat/projects/shared/<project-name>/) with standard artifacts:
+state.md, discovery.md, plan.md, and implementation.md.
+
+See: guide/workflow/lifecycle.md, guide/getting-started.md
+
+Would you like me to create a project for you?
+```
+
+### Exploratory Question
+
+**User:** `/oat-docs what are tool packs?`
+
+**Response:**
+
+```
+Tool packs are bundles of related OAT skills that you install together.
+There are four packs:
+
+- **core** — Diagnostics and docs skills (oat-doctor, oat-docs).
+  Always installed at user level. 2 skills.
+- **workflows** — Project lifecycle skills (discover, plan, implement,
+  review, PR). 26 skills total.
+- **ideas** — Brainstorming and idea capture skills. 4 skills.
+- **utility** — Cross-cutting tools (docs analysis, code review,
+  skill creation). 9 skills.
+
+Install with: oat init tools
+Manage with: oat tools list, oat tools update, oat tools outdated
+
+See: guide/tool-packs.md
+
+Would you like me to check which packs you have installed? (I'd run /oat-doctor --summary)
+```
+
+## Success Criteria
+
+- ✅ Questions are answered using actual documentation content from `~/.oat/docs/`, not general knowledge.
+- ✅ Answers cite specific docs files for further reading.
+- ✅ Practical examples (commands, config) are included when relevant.
+- ✅ Next actions are offered when appropriate, but never executed without user confirmation.
+- ✅ No files are modified — purely read-only Q&A.
+- ✅ Graceful error when docs are not found at `~/.oat/docs/`, with instructions to install the core pack.