@open-agent-toolkit/cli 0.1.21 → 0.1.22

package/assets/skills/authoring-docs/references/review-rubric.md

@@ -0,0 +1,169 @@
+---
+title: Documentation Review Rubric
+description: Checklist for reviewing documentation quality, accuracy, safety, and maintainability.
+---
+
+# Documentation Review Rubric
+
+Use this rubric to review documentation changes and audit existing docs. The
+goal is not perfection. The goal is to identify whether docs are accurate,
+useful, safe, and maintainable.
+
+## Quick Review Checklist
+
+A documentation change is ready when:
+
+- The page has a clear purpose.
+- The reader persona is obvious.
+- The page belongs to the right documentation type.
+- The page is in the right location.
+- The title describes the task or topic.
+- Commands are accurate.
+- Examples are realistic and grounded in evidence.
+- Links work.
+- Code blocks specify a language.
+- Prerequisites are listed for task pages.
+- Verification steps are included for tasks.
+- Rollback steps are included for risky operations.
+- Reference tables include types, defaults, required fields, and descriptions.
+- Internal-only details are not included in public docs.
+- No secrets or sensitive data are present.
+- Terminology is consistent.
+- Uncertainty is marked clearly.
+- The docs are useful without external tribal knowledge.
+
+## Scoring Model
+
+Score each area from 0 to 3.
+
+| Score | Meaning                                     |
+| ----: | ------------------------------------------- |
+|     0 | Missing or harmful                          |
+|     1 | Present but incomplete, stale, or confusing |
+|     2 | Useful but has gaps                         |
+|     3 | Strong, accurate, and maintainable          |
+
+## Core Areas
+
+Review purpose, accuracy, structure, task support, reference quality,
+operational safety, agent usefulness, maintainability, public/internal boundary,
+and links or navigation.
+
+Production runbooks should be especially strong on operational safety.
+Public-facing docs should be especially strong on examples, accuracy, and
+audience boundary.
+
+| Area                     | 0                           | 1                      | 2                           | 3                                                          |
+| ------------------------ | --------------------------- | ---------------------- | --------------------------- | ---------------------------------------------------------- |
+| Purpose                  | No clear reason page exists | Purpose is implied     | Purpose is stated           | Purpose, reader, and outcome are clear                     |
+| Accuracy                 | Incorrect or invented       | Partially accurate     | Mostly accurate             | Grounded and verified                                      |
+| Structure                | Hard to scan                | Some headings          | Clear sections              | Predictable IA and strong headings                         |
+| Task support             | Cannot complete task        | Can partially complete | Can complete with some gaps | Can complete safely with verification                      |
+| Reference quality        | Missing facts               | Facts scattered        | Most fields documented      | Types, defaults, constraints, examples, errors documented  |
+| Operational safety       | Risky or absent             | Mentions risk          | Includes basic verification | Includes verification, rollback, escalation, failure modes |
+| Agent usefulness         | Ambiguous                   | Some exact data        | Mostly explicit             | Exact commands, paths, constraints, and uncertainty        |
+| Maintainability          | Duplicated or stale         | Hard to update         | Mostly maintainable         | Clear source of truth and generated markers where needed   |
+| Public/internal boundary | Leaks or omits key context  | Boundary unclear       | Mostly appropriate          | Correct assumptions and safe content                       |
+| Links and navigation     | Broken or absent            | Sparse                 | Useful                      | Strong cross-links and clear next steps                    |
+
+## Minimum Acceptable Scores
+
+For internal docs:
+
+- no area below 1
+- purpose, accuracy, task support, and operational safety at least 2
+- production runbooks at 3 for operational safety
+
+For public docs:
+
+- no area below 2
+- accuracy, structure, examples, and public/internal boundary at 3
+
+## Definition of Done for a Docs Migration
+
+A repo docs migration is done when:
+
+- docs have a clear landing page
+- local development works from documented steps
+- test commands are documented
+- deployment behavior is documented or explicitly marked unknown
+- configuration is documented
+- API or CLI reference exists if applicable
+- architecture summary exists for non-trivial systems
+- operations docs exist for production systems
+- ownership is documented or explicitly marked missing
+- old docs are redirected, moved, or deleted
+- duplicate docs are removed or linked to the source of truth
+- public/internal boundary is reviewed
+
+## Red Flags
+
+Block publishing until fixed or explicitly marked when docs include invented
+deployment steps, undocumented production mutation commands, missing rollback
+for risky operations, secrets or tokens, stale commands that fail, public docs
+with internal URLs, internal docs with no owner, runbooks with no verification,
+or generated reference edited manually without a regeneration path.
+
+## Good Enough vs Done
+
+Sometimes a repo starts with no docs. A first pass can be good enough if it is
+honest.
+
+Acceptable first pass:
+
+- grounded overview
+- local setup from repo scripts
+- test commands
+- config table from source
+- explicit missing deployment or ownership notes
+
+Not acceptable:
+
+- plausible but unverified architecture
+- fake owner
+- guessed deploy process
+- copied templates with empty sections
+
+## Review Comment Patterns
+
+Use direct, actionable comments.
+
+Weak:
+
+```txt
+This needs more detail.
+```
+
+Stronger:
+
+```txt
+Add the expected output for `pnpm dev` so readers can verify local startup.
+```
+
+Weak:
+
+```txt
+This is confusing.
+```
+
+Stronger:
+
+```txt
+This page mixes API reference and architecture explanation. Split endpoint
+fields into `reference/api.md` and keep the auth model explanation here.
+```
+
+## Agent Self-Check
+
+Before finishing a documentation task, verify:
+
+- Did I inspect enough source files?
+- Did I avoid inventing facts?
+- Did I mark uncertainty?
+- Did I use the right page type and structure?
+- Did I include prerequisites and verification?
+- Did I include rollback for risky operations?
+- Did I document exact commands and paths?
+- Did I preserve useful existing content?
+- Did I avoid public/private leakage?
+- Did I leave a useful handoff summary?

package/assets/skills/authoring-docs/references/templates.md

@@ -0,0 +1,549 @@
+---
+title: Documentation Templates
+description: Rules for using reusable documentation templates without keeping empty boilerplate.
+---
+
+# Documentation Templates
+
+Use templates as starting points, not as forms to fill mechanically. Delete
+sections that do not apply, merge sections when the repo is small, and add
+sections when the evidence requires them.
+
+## Template Rules
+
+- Keep placeholders only while drafting; replace or remove them before
+  publishing.
+- Do not keep empty headings for symmetry.
+- Preserve accurate existing content before introducing a new shape.
+- Add frontmatter only when the target docs system uses it.
+- Use exact commands, paths, versions, configuration keys, and source links.
+- Mark missing ownership, deployment, or operations facts explicitly.
+- Include verification for task pages.
+- Include rollback or cleanup for risky operations.
+- Prefer local repository templates when they exist.
+
+## Landing Page
+
+````md
+# <Project name>
+
+<One short paragraph explaining what this project is and why it exists.>
+
+## Who this is for
+
+- <Persona>
+
+## What this project does
+
+- <Responsibility>
+
+## What this project does not do
+
+- <Non-goal>
+
+## Quick start
+
+```sh
+<command>
+```
+
+## Common tasks
+
+- [Run locally](./how-to/local-development.md)
+- [Run tests](./how-to/testing.md)
+- [Deploy](./how-to/deployment.md)
+- [Troubleshoot](./how-to/troubleshooting.md)
+
+## Architecture
+
+<Summarize major components and link to concepts.>
+
+## Operations
+
+<Link to runbooks, dashboards, alerts, and rollback.>
+
+## Reference
+
+- [Configuration](./reference/configuration.md)
+- [Environment variables](./reference/environment-variables.md)
+- [API reference](./reference/api.md)
+- [Commands](./reference/commands.md)
+
+## Ownership
+
+| Area | Owner    | Contact     | Escalation |
+| ---- | -------- | ----------- | ---------- |
+| Code | `<team>` | `<channel>` | `<path>`   |
+````
+
+## Getting Started Tutorial
+
+````md
+# Getting started
+
+Use this tutorial to get `<project>` running for the first time.
+
+## Prerequisites
+
+| Requirement   | Version or access | Source or notes |
+| ------------- | ----------------- | --------------- |
+| <Requirement> | <Version/access>  | <Source>        |
+
+## What you will do
+
+By the end, you will have installed dependencies, configured local environment,
+started the project, and verified it works.
+
+## 1. Install dependencies
+
+```sh
+<install-command>
+```
+
+## 2. Configure environment
+
+```sh
+<config-command>
+```
+
+## 3. Start the project
+
+```sh
+<start-command>
+```
+
+## 4. Verify
+
+```sh
+<verification-command>
+```
+
+Expected output:
+
+```txt
+<expected output or UI state>
+```
+
+## Troubleshooting
+
+| Problem   | Cause   | Fix   |
+| --------- | ------- | ----- |
+| <Problem> | <Cause> | <Fix> |
+
+## Next steps
+
+- [Local development](./how-to/local-development.md)
+- [Testing](./how-to/testing.md)
+````
+
+## How-To Guide
+
+````md
+# How to <complete a task>
+
+Use this guide when you need to <specific outcome>.
+
+## Prerequisites
+
+- <Requirement>
+
+## Steps
+
+### 1. <Do the first thing>
+
+```sh
+<command>
+```
+
+<Explain what this does.>
+
+### 2. <Do the next thing>
+
+```sh
+<command>
+```
+
+## Verify
+
+```sh
+<verification-command>
+```
+
+Expected output:
+
+```txt
+<expected output>
+```
+
+## Roll back
+
+<Explain how to undo the change safely.>
+
+## Troubleshooting
+
+| Problem   | Cause   | Fix   |
+| --------- | ------- | ----- |
+| <Problem> | <Cause> | <Fix> |
+
+## Related docs
+
+- [Configuration](../reference/configuration.md)
+````
+
+## Configuration Reference
+
+```md
+# Configuration reference
+
+This page lists supported configuration options.
+
+## Environment variables
+
+| Name   | Type   | Required | Default | Environments | Description      |
+| ------ | ------ | -------: | ------- | ------------ | ---------------- |
+| `PORT` | number |       No | `3000`  | local        | Local HTTP port. |
+
+## Configuration files
+
+| File         | Purpose                   |
+| ------------ | ------------------------- |
+| `.env.local` | Local environment values. |
+
+## Configuration precedence
+
+1. Command flags
+2. Environment variables
+3. Project config file
+4. Built-in defaults
+```
+
+## API Endpoint Reference
+
+````md
+# `POST /examples`
+
+Creates an example resource.
+
+## Authentication
+
+Requires <auth method> with <scope or permission>.
+
+## Request
+
+```json
+{
+  "name": "Example"
+}
+```
+
+| Field  | Type   | Required | Description          |
+| ------ | ------ | -------: | -------------------- |
+| `name` | string |      Yes | Human-readable name. |
+
+## Response
+
+```json
+{
+  "id": "example_123",
+  "name": "Example"
+}
+```
+
+| Field | Type   | Description        |
+| ----- | ------ | ------------------ |
+| `id`  | string | Unique identifier. |
+
+## Errors
+
+| Status | Code              | Meaning                 | Fix                    |
+| -----: | ----------------- | ----------------------- | ---------------------- |
+|    400 | `invalid_request` | The request is invalid. | Check required fields. |
+
+## Example
+
+```sh
+curl -X POST "$BASE_URL/examples" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Example"}'
+```
+````
+
+## CLI Command Reference
+
+````md
+# `<tool> <command>`
+
+<Describe what the command does.>
+
+## Usage
+
+```sh
+<tool> <command> [arguments] [flags]
+```
+
+## Examples
+
+```sh
+<tool> <command> <example>
+<tool> <command> <example> --json
+```
+
+## Arguments
+
+| Argument     | Required | Description   |
+| ------------ | -------: | ------------- |
+| `<argument>` |      Yes | <Description> |
+
+## Flags
+
+| Flag     | Type    | Default | Description                   |
+| -------- | ------- | ------- | ----------------------------- |
+| `--json` | boolean | `false` | Output machine-readable JSON. |
+
+## Output
+
+```txt
+<example output>
+```
+
+## JSON output
+
+```json
+{
+  "status": "ok"
+}
+```
+
+## Exit codes
+
+Only include this table when exit-code meanings are explicit in source or
+existing documentation. If they are not explicit, say exit codes are not
+documented.
+
+| Code     | Source-backed meaning  |
+| -------- | ---------------------- |
+| `<code>` | `<documented meaning>` |
+
+## Related commands
+
+- [`<tool> <related-command>`](./related-command.md)
+````
+
+## Architecture Page
+
+```md
+# Architecture
+
+This page explains how `<system>` works and why it is designed this way.
+
+## Summary
+
+<One or two paragraphs.>
+
+## Goals
+
+- <Goal>
+
+## Non-goals
+
+- <Non-goal>
+
+## System context
+
+<Describe users, external systems, and dependencies.>
+
+## Components
+
+| Component   | Responsibility   | Notes   |
+| ----------- | ---------------- | ------- |
+| <Component> | <Responsibility> | <Notes> |
+
+## Data flow
+
+<Explain request, event, job, or user-action flow.>
+
+## Key decisions
+
+- <Decision and rationale>
+
+## Failure modes
+
+| Failure mode | Symptom   | Impact   | Recovery   |
+| ------------ | --------- | -------- | ---------- |
+| <Failure>    | <Symptom> | <Impact> | <Recovery> |
+
+## Related docs
+
+- [Runbook](../operations/runbook.md)
+- [Deployment](../how-to/deployment.md)
+```
+
+## Runbook
+
+````md
+# Runbook
+
+Use this runbook when `<system>` is unhealthy or degraded.
+
+## Service summary
+
+| Field               | Value        |
+| ------------------- | ------------ |
+| Owner               | `<team>`     |
+| Support channel     | `<channel>`  |
+| Production location | `<location>` |
+| Dashboard           | `<link>`     |
+| Logs                | `<link>`     |
+| Alerts              | `<link>`     |
+
+## Health checks
+
+```sh
+curl <health-url>
+```
+
+Expected output:
+
+```json
+{
+  "status": "ok"
+}
+```
+
+## Common incidents
+
+### Symptom: <symptom>
+
+Impact:
+
+- <Impact>
+
+Checks:
+
+1. <Check>
+2. <Check>
+
+Mitigation:
+
+1. <Step>
+2. <Step>
+
+Verification:
+
+- <Verification step>
+
+Escalation:
+
+- <Escalation path>
+````
+
+## Architecture Decision Record
+
+```md
+# ADR <number>: <decision>
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded
+
+## Context
+
+What problem, constraint, or pressure led to this decision?
+
+## Decision
+
+What decision was made?
+
+## Consequences
+
+What are the benefits, costs, tradeoffs, and risks?
+
+## Alternatives considered
+
+What options were considered and rejected?
+
+## Related docs
+
+- <Links>
+```
+
+## Documentation Audit Summary
+
+````md
+# Documentation audit: <repo>
+
+## Summary
+
+<Short summary of current docs quality.>
+
+## Project type
+
+- <frontend app/backend service/API/CLI/library/framework/etc.>
+
+## Current docs
+
+| Page        | Type    | Quality | Notes                          |
+| ----------- | ------- | ------- | ------------------------------ |
+| `README.md` | Landing | 2       | Useful but missing deployment. |
+
+## Missing docs
+
+| Missing page     | Priority | Why it matters                                     |
+| ---------------- | -------: | -------------------------------------------------- |
+| Deployment guide |     High | Production changes need verification and rollback. |
+
+## Stale or risky docs
+
+| Page        | Issue                    | Recommended action          |
+| ----------- | ------------------------ | --------------------------- |
+| `README.md` | Command no longer exists | Update from `package.json`. |
+
+## Recommended structure
+
+```txt
+docs/
+├── index.md
+├── getting-started.md
+├── how-to/
+├── reference/
+├── concepts/
+└── operations/
+```
+
+## Follow-up questions
+
+- <Question that needs owner verification>
+````
+
+## Documentation Handoff Summary
+
+```md
+## Summary
+
+- <Change>
+
+## Sources inspected
+
+- `<file>`
+
+## Docs structure
+
+- Added/updated landing page
+- Added/updated how-to guides
+- Added/updated reference pages
+- Added/updated concepts
+- Added/updated operations docs
+
+## Verification
+
+- `<command>`: pass/fail
+
+## Needs owner review
+
+- <Unverified fact or missing context>
+
+## Not included
+
+- <Explicitly out-of-scope docs>
+```