@open-agent-toolkit/cli 0.1.20 → 0.1.22

package/assets/skills/authoring-docs/references/page-types.md

@@ -0,0 +1,119 @@
+---
+title: Documentation Page Types
+description: Guidance for tutorials, how-to guides, reference docs, explanations, and runbooks.
+---
+
+# Documentation Page Types
+
+Most documentation problems come from mixing different kinds of information into
+one page. A page can contain supporting material from another type, but it
+should have one primary job.
+
+## Tutorial
+
+A tutorial teaches through a guided path. Use tutorials when the reader is new
+to the project or workflow.
+
+Good tutorial topics include running the app locally for the first time,
+sending the first API request, running the first CLI command, creating the first
+integration, making the first contribution, or deploying to a non-production
+environment.
+
+Rules:
+
+- Assume the reader is capable but unfamiliar with this system.
+- State prerequisites before steps.
+- Use one successful path.
+- Avoid branching.
+- Show expected output.
+- Explain only enough to keep the reader oriented.
+- End with a working result.
+- Link to deeper docs for next steps.
+
+## How-To Guide
+
+A how-to guide helps a reader complete a specific task.
+
+Good how-to topics include adding a route, adding a CLI command, rotating a
+secret, deploying a service, running a migration, debugging a worker, adding a
+feature flag, creating a webhook consumer, or onboarding a service consumer.
+
+Rules:
+
+- Title the page as a task.
+- Start with when to use the guide.
+- State prerequisites.
+- Use numbered steps.
+- Include verification.
+- Include rollback or cleanup when relevant.
+- Keep conceptual explanation brief.
+- Link to reference and concept pages.
+
+## Reference
+
+Reference documentation provides exact facts.
+
+Good reference topics include API endpoints, GraphQL schema, CLI commands,
+environment variables, configuration, error codes, event schemas, package
+exports, permissions, cache keys, and feature flags.
+
+Rules:
+
+- Do not bury facts in prose.
+- Use tables, lists, and code blocks.
+- Include required vs optional status.
+- Include defaults, types, constraints, examples, and errors.
+- Include versioning and deprecation notes when known.
+- Avoid tutorials inside reference pages.
+
+## Explanation
+
+Explanation helps readers understand how and why the system works.
+
+Good explanation topics include architecture, data flow, rendering model,
+caching strategy, auth model, queueing model, consistency model, failure modes,
+tradeoffs, migration strategy, and design constraints.
+
+Rules:
+
+- Start with the problem or design pressure.
+- Explain the mental model.
+- Be honest about tradeoffs.
+- Include diagrams when helpful.
+- Link to ADRs or RFCs when available.
+- Do not turn explanation pages into step-by-step guides.
+- Do not hide operational instructions only in explanation pages.
+
+## Runbook
+
+A runbook is operational how-to plus reference. Use it when the reader needs to
+recover or safely operate a system.
+
+Rules:
+
+- Start with symptoms and impact.
+- Include first checks, dashboards, logs, metrics, or traces.
+- List likely causes and known false positives.
+- Provide mitigation steps and exact commands or links.
+- Include verification, rollback, and escalation.
+- Avoid long historical background before recovery steps.
+
+## Mixed Pages
+
+Some pages legitimately mix types. A landing page can include orientation,
+links, and a small quick start. A runbook can include reference tables and task
+steps. An API guide can include conceptual auth explanation plus endpoint
+reference links.
+
+The rule is not "never mix." The rule is to know the primary job of the page
+and keep everything else subordinate.
+
+## Smell Test
+
+| If the Reader Asks              | They Need    | Do Not Give Them            |
+| ------------------------------- | ------------ | --------------------------- |
+| I am new. Walk me through this. | Tutorial     | Full API reference          |
+| How do I do X?                  | How-to guide | Architecture essay          |
+| What does this option mean?     | Reference    | A blog post                 |
+| Why does this behave this way?  | Explanation  | A command list              |
+| Production is broken. What now? | Runbook      | Historical background first |

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

@@ -0,0 +1,98 @@
+---
+title: Documentation Principles
+description: Core principles for evidence-first technical documentation.
+---
+
+# Documentation Principles
+
+Documentation is part of the system. Maintain it with the same seriousness as
+code, tests, configuration, infrastructure, and runbooks.
+
+The goal is not to produce many pages. The goal is to reduce confusion, support
+safe change, and make the system legible to humans and agents.
+
+## Start With the Reader's Job
+
+Write from the reader's task, not the source tree.
+
+Weak:
+
+```md
+This service uses HTTP handlers, queues, and PostgreSQL.
+```
+
+Stronger:
+
+```md
+Use this service to publish content lifecycle events. The service accepts HTTP
+requests, persists event state in PostgreSQL, and processes asynchronous work
+through queue-backed workers.
+```
+
+Purpose comes first. Implementation details follow when they help the reader.
+
+## Task Completion Beats Encyclopedic Completeness
+
+Most readers arrive with a problem:
+
+- How do I run this locally?
+- How do I deploy this?
+- What does this flag do?
+- Why did this job fail?
+- What request shape should I send?
+- Can I safely change this config?
+
+Complete docs are useful only when structured around those moments.
+
+## Separate Documentation Modes
+
+Tutorials, how-to guides, reference pages, explanations, and runbooks do
+different jobs. Keep each page's primary job clear. Do not turn a first-run
+tutorial into a full reference manual, or a reference page into a long
+architecture essay.
+
+## Make Context Explicit for Agents
+
+Agents do not know which conventions are local, current, or tribal. Write down
+exact commands, paths, service names, environment names, runtime versions,
+configuration keys, ownership when known, constraints, non-goals, failure modes,
+and uncertainty.
+
+## Prefer Boring Consistency
+
+Across repositories, readers should know where to find setup, commands,
+configuration, API or CLI reference, deployment, observability, runbooks,
+architecture, and ownership. Familiar structure lowers cognitive load.
+
+## Lead With the Safe Path
+
+Document the common path first. Then explain variations, edge cases, production
+caveats, failure modes, unsafe commands, rollback, and compatibility
+boundaries.
+
+## Treat Reference as a Contract
+
+Reference docs for APIs, commands, configuration, events, packages, and
+environment variables should include names, types, required or optional status,
+defaults, allowed values, constraints, examples, errors, version notes, and
+deprecation notes when those facts exist.
+
+## Treat Operations Docs as Safety Equipment
+
+Runbooks are not background reading. They should help someone recover a system
+under pressure with symptoms, impact, likely causes, dashboards, logs, commands,
+verification, rollback, escalation, and known false positives.
+
+## Give Internal Docs the Same Quality Bar
+
+Internal docs can assume more context only when that context is linked or
+explained. They still need accurate examples, safe operations guidance, and
+clear ownership. Internal docs often guide production changes and future agent
+work.
+
+## Make Docs Age Visibly
+
+Docs get stale. Include version compatibility, last-verified dates for
+operational procedures, supported environments, deprecated behavior, ownership,
+source-of-truth links, and generated-reference markers when useful. Avoid
+claims like "new," "soon," or "temporary" without dates or issue links.

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?