@open-agent-toolkit/cli 0.0.10

package/assets/templates/discovery.md

@@ -0,0 +1,135 @@
+---
+oat_status: in_progress
+oat_ready_for: null
+oat_blockers: []
+oat_last_updated: YYYY-MM-DD
+oat_generated: false
+oat_template: true
+oat_template_name: discovery
+---
+
+# Discovery: {Project Name}
+
+## Phase Guardrails (Discovery)
+
+Discovery is for requirements and decisions, not implementation details.
+
+- Prefer outcomes and constraints over concrete deliverables (no specific scripts, file paths, or function names).
+- If an implementation detail comes up, capture it as an **Open Question** for design (or a constraint), not as a deliverable list.
+
+## Initial Request
+
+{Copy of user's initial request}
+
+## Clarifying Questions
+
+### Question 1: {Topic}
+
+**Q:** {Question}
+**A:** {User's answer}
+**Decision:** {What this means for the project}
+
+## Solution Space
+
+_Include this section only when the request is exploratory or multiple viable approaches exist. For well-understood requests with an obvious approach, omit or replace with a single sentence stating the chosen direction._
+
+{Divergent exploration of the problem space before converging on an approach. Capture genuinely distinct strategies, not minor variations. Include 2-3 approaches as needed.}
+
+### Approach 1: {Strategy Name} _(Recommended)_
+
+**Description:** {What this approach involves}
+**When this is the right choice:** {Conditions under which this approach is best}
+**Tradeoffs:** {What you give up by choosing this}
+
+### Approach 2: {Strategy Name}
+
+**Description:** {What this approach involves}
+**When this is the right choice:** {Conditions under which this approach is best}
+**Tradeoffs:** {What you give up by choosing this}
+
+### Chosen Direction
+
+**Approach:** {Which approach was selected}
+**Rationale:** {Why this approach over the alternatives}
+**User validated:** {Yes/No — explicit buy-in before proceeding}
+
+## Options Considered
+
+{Specific implementation options within the chosen approach. More granular than Solution Space — captures decisions about libraries, patterns, data formats, etc.}
+
+### Option A: {Option Name}
+
+**Description:** {What this option involves}
+
+**Pros:**
+
+- {Benefit 1}
+- {Benefit 2}
+
+**Cons:**
+
+- {Drawback 1}
+- {Drawback 2}
+
+**Chosen:** {A/B/Neither}
+
+**Summary:** {1-2 sentence summary of the chosen option and why}
+
+## Key Decisions
+
+1. **{Decision Category}:** {Decision made and why}
+2. **{Decision Category}:** {Decision made and why}
+
+## Constraints
+
+- {Constraint 1}
+- {Constraint 2}
+
+## Success Criteria
+
+- {Criterion 1}
+- {Criterion 2}
+
+## Out of Scope
+
+- {Thing we explicitly decided not to do}
+- {Thing we explicitly decided not to include in this phase}
+
+## Deferred Ideas
+
+{Ideas that came up during discovery but are intentionally out of scope for now}
+
+- {Idea 1} - {Why deferred}
+- {Idea 2} - {Why deferred}
+
+## Open Questions
+
+{Questions that need resolution before or during specification (and later design)}
+
+- **{Question Category}:** {Question that needs answering}
+- **{Question Category}:** {Question that needs answering}
+
+## Assumptions
+
+{Assumptions we're making that need validation}
+
+- {Assumption 1}
+- {Assumption 2}
+
+## Risks
+
+{Potential risks identified during discovery}
+
+- **{Risk Name}:** {Description}
+  - **Likelihood:** Low / Medium / High
+  - **Impact:** Low / Medium / High
+  - **Mitigation Ideas:** {How to address}
+
+## Next Steps
+
+Use this discovery artifact to drive the next workflow step:
+
+- **Quick mode → straight to plan:** proceed directly to `plan.md` when scope is clear and no architecture decisions remain.
+- **Quick mode → optional lightweight design:** produce a focused `design.md` (architecture, components, data flow, testing) before planning. Choose this when discovery surfaced architecture choices or component boundaries.
+- **Quick mode → promote:** escalate to spec-driven if discovery revealed the scope is larger or more complex than expected.
+- **Spec-driven mode:** continue to `oat-project-spec` (after HiLL approval if configured).

package/assets/templates/docs-app-fuma/app/[[...slug]]/page.tsx

@@ -0,0 +1,30 @@
+import { DocsPage, Mermaid, Tab, Tabs } from '@open-agent-toolkit/docs-theme';
+import defaultComponents from 'fumadocs-ui/mdx';
+import { notFound } from 'next/navigation';
+
+import { source } from '@/lib/source';
+
+const mdxComponents = { ...defaultComponents, Mermaid, Tab, Tabs };
+
+export default async function Page(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc}>
+      <MDX components={mdxComponents} />
+    </DocsPage>
+  );
+}
+
+export function generateStaticParams() {
+  return [
+    { slug: undefined },
+    ...source.generateParams().filter((p) => p.slug.length > 0),
+  ];
+}

package/assets/templates/docs-app-fuma/app/api/search/route.ts

@@ -0,0 +1,8 @@
+import { createFromSource } from 'fumadocs-core/search/server';
+
+import { source } from '@/lib/source';
+
+const search = createFromSource(source);
+
+export const revalidate = false;
+export const { staticGET: GET } = search;

package/assets/templates/docs-app-fuma/app/globals.css

@@ -0,0 +1,69 @@
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/black.css';
+@import 'fumadocs-ui/css/preset.css';
+
+@source '../node_modules/fumadocs-ui/dist/**/*.js';
+
+/* remark-github-blockquote-alert callout styling (fd-* design tokens) */
+@layer base {
+  .markdown-alert {
+    border-radius: 0.75rem;
+    border: 1px solid var(--color-fd-border);
+    border-left: 3px solid var(--callout-color, var(--color-fd-border));
+    background: var(--color-fd-card);
+    color: var(--color-fd-card-foreground);
+    padding: 0.75rem 1rem;
+    margin: 1rem 0;
+    font-size: 0.875rem;
+    box-shadow: 0 1px 3px rgb(0 0 0 / 0.1);
+  }
+
+  .markdown-alert > :first-child {
+    margin-top: 0;
+  }
+
+  .markdown-alert > :last-child {
+    margin-bottom: 0;
+  }
+
+  .markdown-alert .markdown-alert-title {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 500;
+    margin-bottom: 0.25rem;
+    color: var(--callout-color, var(--color-fd-foreground));
+  }
+
+  .markdown-alert .markdown-alert-title svg {
+    fill: currentColor;
+    width: 1rem;
+    height: 1rem;
+    flex-shrink: 0;
+  }
+
+  .markdown-alert p:not(.markdown-alert-title) {
+    color: var(--color-fd-muted-foreground);
+    margin: 0.25rem 0 0;
+  }
+
+  .markdown-alert-note {
+    --callout-color: var(--color-fd-info, #3b82f6);
+  }
+
+  .markdown-alert-tip {
+    --callout-color: #22c55e;
+  }
+
+  .markdown-alert-important {
+    --callout-color: #a855f7;
+  }
+
+  .markdown-alert-warning {
+    --callout-color: #eab308;
+  }
+
+  .markdown-alert-caution {
+    --callout-color: #ef4444;
+  }
+}

package/assets/templates/docs-app-fuma/app/layout.tsx

@@ -0,0 +1,26 @@
+import { DocsLayout } from '@open-agent-toolkit/docs-theme';
+import { RootProvider } from 'fumadocs-ui/provider/next';
+import type { ReactNode } from 'react';
+
+import './globals.css';
+import { source } from '@/lib/source';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang='en' suppressHydrationWarning>
+      <body>
+        <RootProvider search={{ options: { type: 'static' as const } }}>
+          <DocsLayout
+            branding={{
+              title: '{{SITE_NAME}}',
+              description: '{{SITE_DESCRIPTION}}',
+            }}
+            tree={source.getPageTree()}
+          >
+            {children}
+          </DocsLayout>
+        </RootProvider>
+      </body>
+    </html>
+  );
+}

package/assets/templates/docs-app-fuma/docs/contributing.md

@@ -0,0 +1,71 @@
+---
+title: Contributing
+description: ''
+---
+
+# Contributing to {{SITE_NAME}}
+
+Documentation should ship with the code it explains. This docs app is scaffolded to give contributors and agents a shared contract for navigation, Markdown features, and local tooling.
+
+## Navigation contract
+
+- Every documentation directory must contain an `index.md`.
+- Each `index.md` must include a `## Contents` section.
+- The `## Contents` section is the machine-readable local map for sibling pages and child directories.
+- `overview.md` is deprecated in favor of `index.md`.
+
+## Local workflow
+
+1. Install dependencies:
+
+   ```bash
+   pnpm install
+   ```
+
+2. Run the live preview:
+
+   ```bash
+   pnpm dev
+   ```
+
+3. Run Markdown formatting and linting as configured for this docs app.
+
+## Supported Markdown features
+
+### GFM alerts
+
+Styled callout blocks using GitHub-flavored Markdown syntax:
+
+> [!NOTE]
+> Useful supporting context.
+
+> [!WARNING]
+> Important information to be aware of.
+
+### Mermaid diagrams
+
+Fenced code blocks with the `mermaid` language identifier are rendered as diagrams:
+
+````text
+```mermaid
+flowchart LR
+  A[Read index.md] --> B[Generate nav]
+```
+````
+
+### Code blocks
+
+Syntax-highlighted fenced code blocks with a copy button included by default.
+
+### Full-text search
+
+Built-in FlexSearch-powered static search for discovering content without browsing the full tree.
+
+### Dark/light mode
+
+Theme toggle is included in the layout. Mermaid diagrams re-render on mode switch.
+
+## Agent guidance
+
+- Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
+- Prefer linking to source files and commands explicitly when documenting behavior.

package/assets/templates/docs-app-fuma/docs/getting-started.md

@@ -0,0 +1,40 @@
+---
+title: Getting Started
+description: ''
+---
+
+# Getting Started
+
+Use this guide to set up your local environment and preview {{SITE_NAME}}.
+
+## Prerequisites
+
+- Node.js 22+
+- pnpm 10+ (or npm/yarn)
+
+## Install dependencies
+
+```bash
+pnpm install
+```
+
+## Run the docs locally
+
+```bash
+pnpm dev
+```
+
+## Build for production
+
+```bash
+pnpm build
+```
+
+The static output is generated in the `out/` directory.
+
+## Editing workflow
+
+1. Update Markdown files under `docs/`.
+2. Check the preview site for formatting and navigation.
+3. Run the formatter and linter before committing.
+4. Keep every directory discoverable through its `index.md` file.

package/assets/templates/docs-app-fuma/docs/index.md

@@ -0,0 +1,13 @@
+---
+title: '{{SITE_NAME}}'
+description: '{{SITE_DESCRIPTION}}'
+---
+
+# {{SITE_NAME}}
+
+Use this file as the map to the repository's central documentation site. The site is organized to support both human readers and AI agents, with every directory exposing an `index.md` entrypoint.
+
+## Contents
+
+- [Getting Started](getting-started) - Set up the local docs toolchain and preview the site.
+- [Contributing](contributing) - Authoring conventions and navigation rules.

package/assets/templates/docs-app-fuma/lib/source.ts

@@ -0,0 +1,8 @@
+import { loader } from 'fumadocs-core/source';
+
+import { docs } from '@/.source/server';
+
+export const source = loader({
+  baseUrl: '/',
+  source: docs.toFumadocsSource(),
+});

package/assets/templates/docs-app-fuma/next.config.js

@@ -0,0 +1,6 @@
+import { createDocsConfig } from '@open-agent-toolkit/docs-config';
+
+export default createDocsConfig({
+  title: '{{SITE_NAME}}',
+  description: '{{SITE_DESCRIPTION}}',
+});

package/assets/templates/docs-app-fuma/package.json.template

@@ -0,0 +1,38 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "type": "module",
+  "private": true,
+  "version": "0.1.0",
+  "description": "{{SITE_DESCRIPTION}}",
+  "scripts": {
+    "predev": "fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
+    "dev": "next dev",
+    "prebuild": "fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
+    "build": "next build",
+    "start": "next start",
+    "docs:lint": "{{DOCS_LINT_SCRIPT}}",
+    "docs:format": "{{DOCS_FORMAT_SCRIPT}}",
+    "docs:format:check": "{{DOCS_FORMAT_CHECK_SCRIPT}}"
+  },
+  "dependencies": {
+    "@open-agent-toolkit/docs-config": "{{OAT_DOCS_CONFIG_DEP}}",
+    "@open-agent-toolkit/docs-theme": "{{OAT_DOCS_THEME_DEP}}",
+    "@open-agent-toolkit/docs-transforms": "{{OAT_DOCS_TRANSFORMS_DEP}}",
+    "fumadocs-core": "^16.6.13",
+    "fumadocs-mdx": "^14.2.9",
+    "fumadocs-ui": "^16.6.13",
+    "next": "^16.1.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@open-agent-toolkit/cli": "{{OAT_CLI_DEP}}",
+    "@tailwindcss/postcss": "^4.2.1",
+    "@types/mdx": "^2.0.13",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "tailwindcss": "^4.2.1",
+    "typescript": "^5.8.3"{{FUMA_DEV_DEPENDENCIES}}
+  }
+}

package/assets/templates/docs-app-fuma/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;

package/assets/templates/docs-app-fuma/source.config.ts

@@ -0,0 +1,14 @@
+import { createSourceConfig } from '@open-agent-toolkit/docs-config';
+import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
+
+const sourceConfig = createSourceConfig();
+
+export const docs = defineDocs({
+  dir: sourceConfig.contentDir,
+});
+
+export default defineConfig({
+  mdxOptions: {
+    remarkPlugins: sourceConfig.remarkPlugins,
+  },
+});

package/assets/templates/docs-app-fuma/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"],
+      "fumadocs-mdx:collections/*": [".source/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".source/**/*"],
+  "exclude": ["node_modules"]
+}

package/assets/templates/docs-app-mkdocs/docs/contributing.md

@@ -0,0 +1,122 @@
+# Contributing to {{SITE_NAME}}
+
+Documentation should ship with the code it explains. This docs app is scaffolded to give contributors and agents a shared contract for navigation, Markdown features, and local tooling.
+
+## Navigation contract
+
+- Every documentation directory must contain an `index.md`.
+- Each `index.md` must include a `## Contents` section.
+- The `## Contents` section is the machine-readable local map for sibling pages and child directories.
+- `overview.md` is deprecated in favor of `index.md`.
+
+## Local workflow
+
+1. Install Python dependencies:
+
+   ```bash
+   pnpm docs:setup
+   ```
+
+2. Run the live preview:
+
+   ```bash
+   pnpm docs:dev
+   ```
+
+3. Run Markdown formatting and linting as configured for this docs app.
+
+## Installed plugins
+
+### `search`
+
+Adds full-text search to the generated docs site so readers can discover content without browsing the full tree.
+
+### `git-revision-date`
+
+Shows file revision dates using Git history, which helps surface stale pages during maintenance reviews.
+
+### `macros`
+
+Enables variable-style content reuse and small computed fragments inside MkDocs pages.
+
+### `glightbox`
+
+Adds lightbox behavior for linked images so diagrams and screenshots can be expanded in-place.
+
+### `callouts`
+
+Supports GitHub-style callout blocks in Markdown for note, warning, and tip content.
+
+## Enabled Markdown extensions
+
+### `admonition`
+
+Supports MkDocs callout syntax:
+
+```markdown
+!!! note
+Useful supporting context.
+```
+
+### `attr_list`
+
+Lets you attach attributes such as classes or IDs to Markdown elements.
+
+### `md_in_html`
+
+Allows Markdown content inside raw HTML blocks when layout needs extra structure.
+
+### `nl2br`
+
+Treats single newlines as line breaks in rendered output.
+
+### `pymdownx.caret`, `pymdownx.mark`, `pymdownx.tilde`
+
+Adds inline formatting helpers for insertions, highlights, and strikethrough-like syntax.
+
+### `pymdownx.details`
+
+Supports collapsible details blocks for optional reference content.
+
+### `pymdownx.emoji`
+
+Enables emoji shortcodes and richer emoji rendering.
+
+### `pymdownx.inlinehilite`
+
+Adds inline code highlighting helpers for short syntax examples.
+
+### `pymdownx.highlight`
+
+Provides fenced code block highlighting.
+
+### `pymdownx.snippets`
+
+Supports file and snippet inclusion patterns for reusable documentation fragments.
+
+### `pymdownx.superfences`
+
+Extends fenced code support and enables custom fences such as Mermaid:
+
+````text
+```mermaid
+flowchart LR
+  A[Read index.md] --> B[Generate nav]
+````
+
+```
+
+### `pymdownx.tabbed`
+
+Supports tabbed content blocks for related workflows or platform variants.
+
+### `toc`
+
+Adds table-of-contents anchors and permalinks for headings.
+
+## Agent guidance
+
+- Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
+- Prefer linking to source files and commands explicitly when documenting behavior.
+- When adding a new plugin or extension, update this guide with what it does and how to use it.
+```

package/assets/templates/docs-app-mkdocs/docs/getting-started.md

@@ -0,0 +1,28 @@
+# Getting Started
+
+Use this guide to set up your local environment and preview {{SITE_NAME}}.
+
+## Prerequisites
+
+- Node.js 22+
+- pnpm 10+
+- Python 3.11+ for MkDocs tooling
+
+## Install documentation tooling
+
+```bash
+pnpm docs:setup
+```
+
+## Run the docs locally
+
+```bash
+pnpm docs:dev
+```
+
+## Editing workflow
+
+1. Update Markdown files under `docs/`.
+2. Check the preview site for formatting and navigation.
+3. Run the formatter and linter before committing.
+4. Keep every directory discoverable through its `index.md` file.

package/assets/templates/docs-app-mkdocs/docs/index.md

@@ -0,0 +1,8 @@
+# {{SITE_NAME}}
+
+Use this site as the central documentation hub for the repository. It is organized to support both human readers and AI agents, with every directory exposing an `index.md` entrypoint.
+
+## Contents
+
+- [Getting Started](getting-started.md) - Set up the local docs toolchain and preview the site.
+- [Contributing](contributing.md) - Authoring conventions, plugin inventory, and navigation rules.