@open-agent-toolkit/cli 0.0.10

package/assets/skills/create-agnostic-skill/references/skill-template.md

@@ -0,0 +1,195 @@
+# Skill Template Reference
+
+Annotated template showing the standard structure for skills.
+
+## Section Structure
+
+Adjust based on complexity—not all sections are required:
+
+1. **Title (H1)** - Skill name
+2. **Brief description** - One sentence overview
+3. **When to Use** - Conditions that warrant using this skill
+4. **When NOT to Use** - Anti-patterns or exclusions
+5. **Arguments** - Parameters parsed from `$ARGUMENTS`
+6. **Prerequisites** - Required setup or context (if applicable)
+7. **Workflow/Steps** - Numbered steps using "Step 1, 2, 3..." naming
+8. **Quality Standards** - Checklist format for docs skills (if applicable)
+9. **Examples** - Both "Basic Usage" and "Conversational" styles
+10. **Reference** - Links to relevant documentation
+11. **Troubleshooting** - Common issues and solutions
+12. **Success Criteria** - Checklist of completion conditions
+
+## Annotated Template
+
+````markdown
+---
+# === Portable fields (work across all providers) ===
+name: skill-name
+# Required: kebab-case, max 64 chars, must match directory name
+
+version: 1.0.0
+# Required: semver. Start new skills at 1.0.0.
+
+description: Use when [trigger condition]. [What it does as disambiguation keywords].
+# Required: Single line, ≤ 500 chars. Lead with "when to use" — this is the routing trigger.
+# Agents load ONLY name+description at startup to decide relevance.
+
+# === Spec-optional fields (recognized by some providers) ===
+# license: Apache-2.0
+# compatibility: Requires Node.js 18+
+# metadata:
+#   author: my-org
+#   version: "1.0"
+
+# === Claude Code / Cursor extension fields (ignored by Codex, safe to include) ===
+argument-hint: '[required-arg] [--optional-flag]'
+# Claude Code only: Shows in autocomplete after /skill-name
+
+disable-model-invocation: true
+# Claude Code + Cursor: Set true for command-like skills users invoke explicitly
+
+allowed-tools: Read, Write, Glob, Grep
+# Claude Code only: Tools agent can use without permission prompts
+
+user-invocable: true
+# Claude Code only: Set false for helper skills that shouldn't appear in / menu
+
+# context: fork
+# Claude Code only: Uncomment to run in isolated subagent (rare)
+---
+
+# Skill Title
+
+Brief description of what this skill does and the problem it solves.
+
+## When to Use
+
+Use when:
+
+- Condition that warrants using this skill
+- Another condition
+- Context where this is the right choice
+
+## When NOT to Use
+
+Don't use when:
+
+- The task is a one-time operation (doesn't justify a skill)
+- Simpler approach would suffice
+- Existing skills can be composed to achieve the goal
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+
+- **required-arg**: (required) Description of what this argument does
+- **--optional-flag**: (optional) Description with default value noted
+
+## Workflow
+
+### Step 1: First Step Title
+
+Clear instructions in imperative form. Tell the agent what to do.
+
+Include code blocks for commands:
+
+```bash
+example command
+```
+````
+
+### Step 2: Second Step Title
+
+Continue with next logical step. Keep steps focused on one task.
+
+### Step 3: Verify and Complete
+
+Final step should verify success and summarize what was accomplished.
+
+## Examples
+
+### Basic Usage
+
+```
+/skill-name required-arg --optional-flag
+```
+
+```
+/skill-name another-example
+```
+
+### Conversational
+
+```
+Natural language request that would trigger this skill
+```
+
+```
+Another way a user might ask for this
+```
+
+## Reference
+
+- [Link to relevant documentation](path/to/docs)
+- [External reference](https://example.com)
+
+## Troubleshooting
+
+**Common issue description:**
+
+- First thing to check
+- Second thing to try
+- Solution or workaround
+
+**Another common issue:**
+
+- Diagnostic step
+- Resolution
+
+## Success Criteria
+
+Successful completion means:
+
+- ✅ First condition is met
+- ✅ Second condition is met
+- ✅ Artifacts created or modified as expected
+- ✅ Skill can be invoked with /skill-name
+
+```
+
+## Detail Level Guidelines
+
+| Skill Type | Detail Level | Examples |
+|------------|--------------|----------|
+| Complex workflows | Detailed | docs-new, docs-review |
+| Simple command-like | Concise | update-doc-refs, create-ticket |
+| Reference/standards | Detailed | repo-documentation |
+| Helper (auto-invoked) | Moderate | read-relevant-docs |
+
+## Versioning Guidance
+
+- Include `version:` in frontmatter for every skill and use semver (`MAJOR.MINOR.PATCH`).
+- Start new skills at `1.0.0`.
+- Bump patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes.
+
+## Cross-Provider Portability Notes
+
+**Portable baseline:** `name` + `description` are the only fields that work identically across all providers. Everything else is either spec-optional or provider-specific.
+
+**Safe layering strategy:** Start with the portable fields, then layer provider-specific fields on top. Codex explicitly ignores unknown keys, so including Claude-specific fields (like `allowed-tools`, `user-invocable`) won't break Codex — they just won't have effect there.
+
+**Description constraints for max portability:**
+- Single line (Codex enforces this)
+- ≤ 500 chars (Codex limit; spec allows 1024)
+- Lead with "Use when..." or "Run this when..."
+- Front-load trigger keywords in first 50 chars (may be truncated at scale)
+
+**Skill budget awareness (Claude Code):**
+- Claude Code has a ~16,000 character budget for skill descriptions at startup
+- At 60+ skills, descriptions may be silently truncated
+- Keep descriptions concise; the body handles detail
+
+**Shared references:** If multiple skills need the same document, place it in `.agents/docs/` and reference via relative path (`../../docs/my-guide.md`). Don't duplicate into each skill's `references/` directory.
+
+For the full compatibility matrix and resolved research questions, see `.agents/docs/skills-guide.md`.
+```

package/assets/skills/deep-research/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: deep-research
+version: 0.1.0
+description: Comprehensive research orchestrator that classifies topics, dispatches parallel research-angle workers, and produces structured artifacts using domain-specific schemas.
+argument-hint: 'topic [--depth surface|standard|exhaustive] [--focus angle] [--context path] [output-path]'
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, AskUserQuestion, Agent, mcp__*
+---
+
+# /deep-research
+
+Comprehensive research orchestrator that classifies a topic, selects a domain-specific schema, plans independent research angles, dispatches parallel workers (or executes sequentially), and produces a structured artifact. Output is always a written artifact -- never inline-only.
+
+## When to Use
+
+Use when:
+
+- Deep dive into a technology, pattern, or concept
+- Exploring options before making a decision
+- Building comprehensive knowledge on a topic
+- Producing a shareable research document
+
+## When NOT to Use
+
+Don't use when:
+
+- Quick comparison of 2-3 items (use /compare)
+- Analyzing something you already have (use /analyze)
+- Verifying a specific claim (use /skeptic)
+- Merging existing research (use /synthesize)
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+
+- **topic**: The research subject (required)
+- **--depth**: `surface` | `standard` (default) | `exhaustive` (optional)
+- **--focus**: Narrow to a specific angle, e.g. `--focus security` (optional)
+- **--context path**: File or directory of supplementary context (optional)
+- **output-path**: Where to write the artifact (optional)
+
+## Progress Indicators (User-Facing)
+
+Print this banner once at start:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/deep-research
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then print step indicators before beginning work:
+
+- `[1/10] Parsing arguments…`
+- `[2/10] Reading context…` (if applicable)
+- `[3/10] Classifying topic…`
+- `[4/10] Planning research angles…`
+- `[5/10] Checking sub-agent availability…`
+- `[6/10] Executing research angles…`
+- `[7/10] Checking for comparisons…` (if applicable)
+- `[8/10] Synthesizing findings…`
+- `[9/10] Resolving output target…`
+- `[10/10] Writing artifact…`
+
+For long-running operations (web fetches, multi-angle research), print a start line and a completion line:
+
+```
+  → Researching: {angle}…
+  → Complete.
+```
+
+Keep it concise; don't print a line for every shell command.
+
+## Workflow
+
+### Step 1: Parse arguments
+
+`[1/10] Parsing arguments…`
+
+Parse from `$ARGUMENTS`:
+
+- **topic**: Extract the research subject. May be a bare word, quoted string, or multi-word phrase.
+- **--depth**: `surface` | `standard` (default) | `exhaustive`. Controls breadth and depth of research.
+- **--focus**: Narrow research to a specific angle (e.g. `--focus security`).
+- **--context path**: Path to a file or directory of supplementary context.
+- **output-path**: A trailing path argument specifying where to write the artifact.
+
+If the topic is unclear, ask the user for clarification:
+
+- **Claude Code**: use `AskUserQuestion`
+- **Codex**: use structured user-input tooling when available in the current host/runtime
+- **Fallback**: ask in plain text
+
+The prompt should ask: _"What topic would you like me to research?"_
+
+---
+
+### Step 2: Read context (if provided)
+
+`[2/10] Reading context…`
+
+If `--context` is specified:
+
+- If path is a **file**: read and extract constraints, focus areas, prior art
+- If path is a **directory**: read all `.md` files and incorporate
+- If path is **not found**: warn and proceed without context
+
+Context informs topic classification and angle planning but does not replace the skill's methodology.
+
+If `--context` is not specified, skip this step.
+
+---
+
+### Step 3: Topic classification and schema selection
+
+`[3/10] Classifying topic…`
+
+Classify the topic to select the appropriate extended schema:
+
+| Classification | Extended Schema         | Typical Topics                                     |
+| -------------- | ----------------------- | -------------------------------------------------- |
+| Technical      | schema-technical.md     | packages, libraries, frameworks, tools, languages  |
+| Comparative    | schema-comparative.md   | "X vs Y", choosing between options                 |
+| Conceptual     | schema-conceptual.md    | design patterns, methodologies, concepts, theories |
+| Architectural  | schema-architectural.md | system design, infrastructure, deployment patterns |
+
+Context (if provided) informs classification -- e.g., context with performance constraints might push a general topic toward technical.
+
+Present classification to user briefly: `→ Classified as: {type} → using {schema} template`
+
+---
+
+### Step 4: Research angle planning
+
+`[4/10] Planning research angles…`
+
+Based on the topic and classification, plan 3-6 research angles. Each angle is an independent research question or perspective that can be explored in isolation.
+
+Example angles for "event-driven architecture":
+
+- Core patterns and primitives
+- Framework/tool landscape
+- Operational concerns (monitoring, debugging, testing)
+- Migration patterns from request-response
+- When NOT to use event-driven
+
+Angle planning rules:
+
+- If `--focus` is specified, prioritize that angle and reduce others.
+- If `--context` is provided, let context shape which angles are prioritized and what each angle looks for.
+- If `--depth surface`, use 2-3 angles with lighter research per angle.
+- If `--depth exhaustive`, use 5-6 angles with thorough research per angle.
+
+---
+
+### Step 5: Sub-agent availability probe
+
+```
+[5/10] Checking sub-agent availability…
+  → research workers: {available | not resolved} ({reason})
+  → Selected: Execution Tier {1|2|3} — {description}
+```
+
+**Execution Tier 1 -- Parallel worker dispatch (preferred):**
+
+Detection logic (provider split):
+
+- **Claude Code**: `Agent` tool available -- dispatch multiple concurrent `Agent` tool calls, each with `subagent_type: "general-purpose"` and a structured research prompt. Parallelism comes from concurrent tool invocations.
+- **Cursor**: multiple concurrent agent mentions with distinct prompts
+- **Codex**: worker prompts dispatched as parallel agent tasks when `multi_agent = true`
+- **Claude.ai**: no worker dispatch -- falls through to Execution Tier 2
+
+**Execution Tier 2 -- Sequential self-execution:**
+
+- Execute each research angle sequentially
+- Loses parallelism but preserves completeness
+- Log: `→ research workers: not resolved — falling back to Execution Tier 2 (sequential)`
+
+**Execution Tier 3 -- Inline execution:**
+
+- User explicitly requests inline, or single-angle focus
+- Still produces an artifact (artifact-only is an output contract, not an execution contract)
+
+---
+
+### Step 6: Execute research angles
+
+`[6/10] Executing research angles…`
+
+For each angle, the worker (sub-agent or self) receives:
+
+- Research angle description
+- Available sources list
+- Context summary (if `--context` was provided)
+- Output format instructions (structured findings for this angle)
+
+Each worker returns structured findings inline to the orchestrator (not written to disk).
+
+Print progress per angle:
+
+```
+  → Researching: {angle}…
+  → Complete.
+```
+
+---
+
+### Step 7: Conditional /compare dispatch
+
+`[7/10] Checking for comparisons…`
+
+If competing options emerge during research (e.g. "which library for X?"):
+
+- Dispatch `/compare` as a sub-agent with the competing options
+- `/compare` returns its output inline to the orchestrator (no intermediate file, no model-tagged filename)
+- The orchestrator embeds the comparison as a supplementary section within the main artifact
+- The original extended schema remains the primary structure
+
+If no competing options emerged, skip this step.
+
+---
+
+### Step 8: Aggregate and synthesize
+
+`[8/10] Synthesizing findings…`
+
+- Merge findings from all research angles
+- Identify cross-cutting themes
+- Resolve any contradictions between angle findings
+- Produce executive summary
+
+---
+
+### Step 9: Resolve output target
+
+`[9/10] Resolving output target…`
+
+**If an explicit output path was provided in `$ARGUMENTS`**, use it directly — no prompt.
+
+**Otherwise**, determine a default suggestion using OAT-aware detection:
+
+1. Check for `.oat/` at repo root (project-level OAT) → suggest `.oat/repo/research/`
+2. Check for `~/.oat/` (user-level OAT) → suggest `~/.oat/research/`
+3. Fall back to current directory
+
+Then ask the user via `AskUserQuestion` (Claude Code), structured user-input tooling (Codex), or equivalent:
+
+> "Where would you like to write the artifact? (default: {suggested path})"
+
+- If the user confirms (empty response or "yes"), use the suggested path.
+- If the user provides a different path, use that instead.
+- Create the target directory if it does not exist.
+
+---
+
+### Step 10: Write artifact
+
+`[10/10] Writing artifact…`
+
+Write the structured research artifact using:
+
+- Base schema structure from `references/schema-base.md` (Executive Summary, Methodology, Findings, Sources & References)
+- Extended schema sections based on classification from `references/schema-{type}.md`
+- Artifact frontmatter contract:
+
+  ```yaml
+  ---
+  skill: deep-research
+  schema: { selected schema type }
+  topic: '{topic}'
+  model: { self-detected model identifier }
+  generated_at: { today's date }
+  ---
+  ```
+
+  Plus optional keys when applicable: `context`, `depth`, `focus`
+
+- Model-tagged filename: `{topic-slug}-{model-id}.md` (e.g., `event-driven-architecture-opus-4-6.md`)
+
+Reference schemas live in: `references/schema-base.md` and `references/schema-{type}.md`
+
+---
+
+## Examples
+
+### Basic usage
+
+```
+/deep-research "event-driven architecture"
+```
+
+### Exhaustive research with focus
+
+```
+/deep-research "React state management in 2026" --depth exhaustive --focus performance
+```
+
+### Research with context
+
+```
+/deep-research "authentication patterns for microservices" --context docs/security-requirements.md
+```
+
+### Research with output path
+
+```
+/deep-research "Rust vs Go for CLI tools" ~/research/
+```
+
+## Troubleshooting
+
+**Topic too broad:**
+
+- Suggest narrowing with `--focus` or ask user to scope down
+- Do not proceed with an unmanageably broad topic
+
+**No web search available:**
+
+- Research from local sources and conversation context only
+- Note limitations in the Methodology section of the artifact
+
+**Schema classification unclear:**
+
+- Default to conceptual (most general)
+- Note: if topic is "X vs Y", auto-select comparative
+
+**Sub-agent dispatch fails:**
+
+- Fall back to Execution Tier 2 (sequential)
+- Output quality is preserved; only parallelism is lost
+- Log: `→ research workers: not resolved (dispatch failed) — falling back to Execution Tier 2`
+
+**Output path not writable:**
+
+- Fall back to current directory; warn user
+- Note the fallback in output so the user knows where the artifact landed
+
+## Success Criteria
+
+- Banner printed at start
+- Topic parsed and classified into one of 4 schema types
+- Research angles planned (3-6 angles)
+- Execution tier selected and logged with reason
+- Each angle researched with findings returned
+- /compare conditionally dispatched when competing options emerge
+- Findings aggregated into coherent artifact
+- Artifact written with correct schema, frontmatter contract, and model-tagged filename
+- Output destination resolved via OAT-aware detection and user prompt (unless explicit path given)
+- `--depth`, `--focus`, and `--context` correctly influence research scope and priorities
+- Output is always an artifact (never inline-only)

package/assets/skills/deep-research/references/schema-analysis.md

@@ -0,0 +1,93 @@
+<!-- schema-analysis.md — Extended schema for multi-angle analysis.
+     Used by: /analyze.
+     Inherits: schema-base.md (Executive Summary, Methodology, Sources & References).
+     Replaces: Findings section with per-angle analysis and synthesis below. -->
+
+# Multi-Angle Analysis Schema
+
+Inherits the base artifact template from `schema-base.md`. The Findings section is
+replaced with the per-angle analysis structure below.
+
+---
+
+## Per-Angle Findings
+
+{One subsection per analysis angle. Not all angles apply to every analysis — include
+only those that produce meaningful observations. Each angle subsection follows the
+same internal structure.}
+
+### Adversarial / Critical
+
+{Challenge the subject's assumptions, claims, and design decisions:
+
+- **Weaknesses identified** — flaws, vulnerabilities, or unsupported claims
+- **Stress points** — where the subject would fail under pressure or edge cases
+- **Counter-arguments** — alternative interpretations or opposing perspectives
+- **Severity assessment** — which issues are critical vs. cosmetic}
+
+### Gap Analysis
+
+{What is missing, incomplete, or underdeveloped:
+
+- **Coverage gaps** — areas the subject does not address but should
+- **Depth gaps** — topics touched on superficially that warrant deeper treatment
+- **Audience gaps** — user segments or use cases not served
+- **Dependency gaps** — external requirements not documented or accounted for}
+
+### Opportunity Analysis
+
+{Unrealized potential and improvement vectors:
+
+- **Quick wins** — low-effort improvements with high impact
+- **Strategic opportunities** — larger investments that could unlock significant value
+- **Leverage points** — small changes that would have outsized positive effects
+- **Synergies** — connections to other work that could amplify results}
+
+### Structural / Organizational
+
+{How the subject is organized and whether that organization serves its purpose:
+
+- **Information architecture** — logical flow, hierarchy, navigability
+- **Modularity** — separation of concerns, coupling, cohesion
+- **Scalability** — how well the structure accommodates growth
+- **Consistency** — adherence to patterns, naming conventions, style}
+
+### Consistency / Coherence
+
+{Internal and external consistency:
+
+- **Internal contradictions** — places where the subject disagrees with itself
+- **External alignment** — consistency with related artifacts, documentation, or standards
+- **Terminology** — consistent use of terms and definitions
+- **Behavioral consistency** — predictable patterns vs. surprising exceptions}
+
+### Audience / Clarity
+
+{How well the subject communicates to its intended audience:
+
+- **Clarity** — ease of understanding, jargon management, assumed knowledge
+- **Completeness for audience** — does the target reader have everything they need?
+- **Tone and register** — appropriate formality, voice, and style
+- **Actionability** — can the reader act on what they've read?}
+
+## Cross-Angle Synthesis
+
+{Patterns that emerged across multiple angles:
+
+- **Recurring themes** — issues or opportunities that surfaced in more than one angle
+- **Reinforcing signals** — findings from different angles that point to the same conclusion
+- **Tensions** — where findings from different angles conflict or create tradeoffs
+- **Root causes** — underlying factors that explain multiple surface-level observations}
+
+## Prioritized Recommendations
+
+{Ranked action items with effort/impact assessment:
+
+| Priority | Recommendation | Impact  | Effort  | Angles                       |
+| -------- | -------------- | ------- | ------- | ---------------------------- |
+| 1        | {Action item}  | {H/M/L} | {H/M/L} | {Which angles surfaced this} |
+| 2        | {Action item}  | {H/M/L} | {H/M/L} | {Which angles surfaced this} |
+| ...      | ...            | ...     | ...     | ...                          |
+
+Follow the table with a brief narrative for the top 3-5 recommendations, explaining
+the reasoning and suggested approach.}