@docsworth/cli 0.0.0-stage → 0.3.0

package/plugin/skills/polish-page/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: polish-page
+description: Tidy a Docsworth page without changing what it says, by restructuring and rewording it and opening a polish PR for the owning team. Use when someone says "clean up this runbook", "this page is hard to follow", "polish the docs for X", or asks to reformat a page to the runbook sections.
+---
+
+# Polish a page
+
+A polish makes a page easier to read and act on. It never changes a fact. The server
+backs that up with a structural guard: `propose_edit` with `polish: true` refuses a
+change to the page's code blocks, inline code, links, numbers or negation words. The
+guard can't see meaning, or a command written as plain prose, so the owners still
+review the diff.
+
+## 1. Read the page
+
+Call `read` with the page id. Work from `content` exactly as returned: it's the page
+body, without the frontmatter, which a polish never touches. If the user named a topic
+rather than a page, `search` first and confirm which page they mean.
+
+## 2. Rewrite the body
+
+You may:
+
+- move sections that hold no code
+- split long paragraphs
+- turn a run of steps into a numbered list
+- fix or add headings. A runbook reads best with `## When to use`, `## Steps`,
+  `## Checks` and `## Rollback`.
+- tighten wording
+
+Keep these exactly as they are:
+
+- every command and code block (fenced or inline), in the same order and under the same
+  headings, and each fence's language tag (the word after ```): don't add or drop one
+- every inline code span, link target and URL, and each link's text with its target
+- any struck-through text, and nothing newly struck through
+- each task-list item's box and text, as written
+- every number with the word after it (`5 minutes`, `3 retries`)
+- how often each negation or modal word appears: not, never, no, must, should,
+  cannot, can't, don't, doesn't, won't, shouldn't, mustn't, isn't, aren't, only,
+  without, unless, except, nor, none, neither, always
+
+Don't add or drop facts, and keep steps in their order. If something looks wrong or
+out of date, leave it and say so in the reason. Fixing it is an ordinary edit, which the owners review as one.
+
+## 3. Propose it
+
+Call `propose_edit` with `id`, `polish: true`, the rewritten text as `body`, and a
+`reason` describing what you restructured. The server keeps the frontmatter as it is.
+
+If it refuses, the message names each change the guard saw. Put those back exactly
+and try again. Don't switch to an ordinary edit to get past the guard.
+
+If the page shows `[restricted page]`, it links to pages you can't see, and the server
+won't take a polish of it from this session (or any whole-body rewrite). Tell the user
+rather than working around it.
+
+If it refuses because this session read pages with a narrower audience, don't work
+around it. Tell the user which page to polish in a fresh session.
+
+## 4. Report
+
+Give the PR URL and the owning team. Mention anything you noticed that looked wrong,
+since a polish deliberately left it alone.

package/plugin/skills/update-after-incident/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: update-after-incident
+description: After an incident or postmortem, find the runbooks and service pages it touched and propose corrections to each as pull requests for the owning teams. Use when someone says "update the docs after this incident", "the runbook was wrong during the outage", or shares a postmortem and asks what knowledge needs fixing.
+---
+
+# Update knowledge after an incident
+
+Incidents are when runbooks prove wrong. The goal is a small, reviewable PR on each
+affected page, each with its evidence from the incident. A rewrite is never the goal.
+
+## 1. Extract what actually happened
+
+From the postmortem or notes the user gave you, list:
+
+- the symptoms and alerts
+- the services involved
+- every command or step responders actually ran
+- what didn't work, and what they did instead
+- any new check or rollback they discovered
+
+## 2. Find the affected pages
+
+Use the Docsworth `search` tool with the symptoms, then with each service name, passing
+`include_stale: true`. `read` every candidate. A page is affected when the incident
+showed that one of these is wrong or missing:
+
+- a step
+- a command
+- a threshold
+- a check
+- a rollback
+
+The search results also list excluded pages: overdue, deprecated or draft. Tell the
+user which of those the incident touched and which team owns each. An overdue runbook
+that failed during an incident is the most important thing to surface.
+
+## 3. Propose edits, one PR per page
+
+For each affected page, call `propose_edit` with:
+
+- **`edits`:** exact `old` → `new` replacements. Copy `old` verbatim from the `read`
+  result, and include enough surrounding text that it matches exactly once. Prefer
+  several small edits to replacing the whole `content`.
+- **`reason`:** the incident id or date, what happened, and which edit fixes what.
+  Reviewers read this first.
+- **`draft`:** `true` when you're unsure whether a change is right.
+
+Never try to change `id`, `owner_team`, `acl` or `last_verified`; the tool refuses.
+Verification belongs to the owners, through the `verify` tool.
+
+If `propose_edit` refuses because this session read pages with a narrower audience,
+don't work around it. Tell the user which page needs the edit and let them open it
+separately.
+
+## 4. Report
+
+List each PR URL with its page and owning team. Then list the gaps the incident
+revealed where no page exists yet. Each gap is a candidate for the `draft-runbook`
+skill.

package/plugin/skills/verify-page/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: verify-page
+description: Walk a page's owner through checking that a knowledge page is still true, fix what is not via a proposed edit, then open the verify PR that resets its review clock. Use when someone says "verify this runbook", "this page is overdue", "re-verify our team's docs", or after the weekly owner digest lists pages due for review.
+---
+
+# Verify a page
+
+Verification is the owning team saying "this is still true", and it's what lets agents
+cite the page. Only a member of the page's `owner_team` can verify it. The `verify` tool
+enforces that, so check membership before doing a long walkthrough.
+
+## 1. Pick the page
+
+If the user named a page, `read` it. If they named a team, call `stale` with
+`owner_team` and offer the overdue pages oldest first, then the pages that are due soon.
+Show the page's `owner_team`, `last_verified`, `due` and `flags` before starting.
+
+## 2. Walk through it with the owner
+
+Go section by section: *When to use*, *Steps*, *Checks*, *Rollback*. For each one, ask
+the owner a concrete question rather than "is this right?". For example:
+
+- "Is `shipyard deploy` still the command?"
+- "Is the canary still 5% → 25% → 100%?"
+- "Does this alert still exist under this name?"
+
+Where a step names something you can check without changing anything, offer to check it
+and run it only after the owner agrees. Examples are a CLI's `--help`, a file in the
+repo, or a dashboard URL. Never run a mutating command as part of verification.
+
+Record every answer. Anything wrong or out of date becomes an edit in step 3.
+
+## 3. Fix first, then verify
+
+- **If anything needs changing:** call `propose_edit` with the exact edits and a
+  `reason` that says it came from verification. Verify only once those changes are
+  agreed. Verifying a page you know is wrong defeats the gate.
+- **If everything is still true:** call `verify` with the page id. It opens a PR that
+  sets `last_verified` to today. If it's refused because the user isn't on the owning
+  team, say which team can verify it and stop.
+
+## 4. Report
+
+Give the PR URL or URLs, the new review due date, and anything the owner was unsure
+about. Log the unsure items as `TODO(owner):` lines in a proposed edit rather than
+dropping them.

package/templates/github/knowledge.yml

@@ -0,0 +1,51 @@
+# Docsworth CI for a knowledge repo. Copy to .github/workflows/knowledge.yml
+# (`docsworth init --ci` does this).
+#  - Pull requests: lint frontmatter, ownership and links; dry-run the skills compiler.
+#  - Merges to the default branch: recompile skills and commit any changes.
+#    If the default branch is protected against bot pushes, replace the commit step
+#    with a PR (e.g. peter-evans/create-pull-request) or publish skills as an artifact.
+name: knowledge
+
+on:
+  pull_request:
+    paths: ["knowledge/**", "CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS", ".knowledge/config.yaml"]
+  push:
+    branches: [main]
+    paths: ["knowledge/**"]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+      - run: npx -y "__DOCSWORTH_PACKAGE__" lint .
+      - run: npx -y "__DOCSWORTH_PACKAGE__" compile . --dry-run
+
+  compile:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+      - run: npx -y "__DOCSWORTH_PACKAGE__" compile .
+      - run: npx -y "__DOCSWORTH_PACKAGE__" compile . --check
+      - name: Commit regenerated skills
+        run: |
+          if [ -n "$(git status --porcelain -- skills)" ]; then
+            git config user.name "docsworth[bot]"
+            git config user.email "docsworth-bot@users.noreply.github.com"
+            git add skills
+            git commit -m "skills: recompile from knowledge [skip ci]"
+            git push
+          fi