workbench-docs
Documentation workflows for Workbench CLI. Use when creating or updating specs, ADRs, runbooks, guides, or general docs, and when syncing backlinks or change notes.
When & Why to Use This Skill
The Workbench Docs skill automates professional documentation workflows within the Workbench CLI environment. It streamlines the creation, management, and synchronization of essential technical assets including Architecture Decision Records (ADRs), system specifications, runbooks, and project guides. By integrating documentation directly with work items and automating backlink synchronization, it ensures that project knowledge remains consistent, searchable, and up-to-date throughout the software development lifecycle.
Use Cases
- Project Planning: Rapidly generating technical specifications and system design documents before starting major implementation phases.
- Architecture Governance: Creating and managing Architecture Decision Records (ADRs) to document key design choices and linking them to specific development tasks.
- Knowledge Maintenance: Automatically syncing front matter and backlinks across a documentation repository to ensure metadata consistency and prevent broken references.
- Release Management: Summarizing staged documentation changes to provide clear, concise change notes for stakeholders during the publishing process.
- Operations: Creating and updating standardized runbooks and guides to ensure team alignment on operational procedures.
| name | workbench-docs |
|---|---|
| description | Documentation workflows for Workbench CLI. Use when creating or updating specs, ADRs, runbooks, guides, or general docs, and when syncing backlinks or change notes. |
Key settings
.workbench/config.json: paths.docsRoot, paths.templatesDir, ids.width, prefixes, git.defaultBaseBranch, github.owner, github.repository.- Use
workbench config show --format jsonto verify effective settings.
Core workflows
- Planning phase: create specs and architecture docs before major changes.
- Doing phase: keep docs updated as implementation decisions change.
- Keep doc front matter and backlinks in sync.
- Summarize doc changes when publishing.
Commands
Create a doc:
workbench doc new --type doc --title "Title" --path docs/10-product/title.md --work-item TASK-0001
Create a spec:
workbench doc new --type spec --title "Title" --path docs/10-product/title.md --work-item TASK-0001
Create an architecture doc:
workbench doc new --type doc --title "System design" --path docs/20-architecture/system-design.md --work-item TASK-0001
Create an ADR:
workbench doc new --type adr --title "Decision" --path docs/40-decisions/ADR-YYYY-MM-DD-title.md --work-item TASK-0001
Link a doc to work items:
workbench doc link --type spec --path docs/10-product/title.md --work-item TASK-0001
Unlink a doc from work items:
workbench doc unlink --type adr --path docs/40-decisions/ADR-YYYY-MM-DD-title.md --work-item TASK-0001
Sync front matter and backlinks:
workbench doc sync --all --dry-run
workbench doc sync --all
Summarize doc changes:
workbench doc summarize --staged --update-index
Output
- Markdown docs with Workbench front matter and backlinks.
- Updated work item references in docs and work items.
Guardrails
- Keep doc types aligned with folder intent (product, architecture, decisions, runbooks).
- Always link docs to relevant work items with
--work-itemorworkbench item link. - For major changes, write a spec before implementation.
- When decisions change, update or create the ADR.
- Prefer
workbench doccommands;workbench specandworkbench adrare deprecated.