@xcraftmind/mastermind 0.24.0 → 0.26.0

package/share/commands/api-shape-explorer.md

@@ -0,0 +1,107 @@
+---
+name: api-shape-explorer
+description: Generate three radically different API/interface shapes for the same problem so you can compare tradeoffs before committing. Use when you're about to design a new module, service boundary, or public API and want to avoid anchoring on the first idea.
+metadata:
+  version: 0.1.0
+  authors:
+    - mastermind
+  tags:
+    - workflow
+    - design
+  role: user
+  variables:
+    - name: PROBLEM
+      required: true
+      description: What the API needs to do. Concrete use cases, not abstract goals.
+    - name: CONSTRAINTS
+      required: false
+      description: Hard constraints — language, framework, latency, compatibility.
+---
+
+# API Shape Explorer
+
+A user prompt that asks the model to generate three meaningfully different interface designs for the same problem, with tradeoffs. The goal is to force a comparison before you anchor on the first shape that comes to mind.
+
+## When to use
+
+- Designing a new module's public API
+- Choosing between an SDK shape, a CLI shape, and a config-file shape
+- Service boundary discussions — "should this be one endpoint or three?"
+- Before writing a design doc, to populate the "alternatives considered" section
+- Do NOT use this for implementation — use it only at the interface-design stage
+
+## Variables
+
+| Name | Required | Description |
+|---|---|---|
+| `PROBLEM` | yes | What the API needs to do. Concrete use cases beat abstract goals. |
+| `CONSTRAINTS` | no | Hard constraints — language, framework, latency targets, compatibility requirements. |
+
+## Prompt
+
+```text
+I'm designing an API/interface for the following problem. Before I commit to one shape, I want to see three meaningfully different options.
+
+PROBLEM:
+{{PROBLEM}}
+
+{{#if CONSTRAINTS}}
+CONSTRAINTS:
+{{CONSTRAINTS}}
+{{/if}}
+
+Generate exactly three interface designs. They must be *qualitatively* different — not three variations of the same idea. Examples of "qualitatively different": object-oriented vs. functional vs. data-pipeline; sync vs. async vs. streaming; one big call vs. many small calls vs. configuration-driven.
+
+For each, give me:
+
+## Option <N>: <short name>
+
+**Shape:** A code snippet showing how a caller would actually use it. 10-20 lines, realistic.
+
+**Mental model:** One sentence describing how a user has to think about this API to use it correctly.
+
+**Strengths:**
+- <thing 1>
+- <thing 2>
+
+**Weaknesses:**
+- <thing 1>
+- <thing 2>
+
+**Best when:** <one sentence on the situation this is the right shape for>
+
+After the three options, give me a short comparison:
+
+## Comparison
+
+| Dimension | Option 1 | Option 2 | Option 3 |
+|---|---|---|---|
+| Learning curve | low / medium / high | … | … |
+| Composability | … | … | … |
+| Testability | … | … | … |
+| Extensibility | … | … | … |
+
+End with one paragraph: "If forced to pick one without more information, I'd choose Option X because…"
+
+Do not hedge. Do not say "all three have merit." Pick one and defend it.
+```
+
+## Example invocation
+
+```text
+I'm designing an API/interface for the following problem. Before I commit to one shape, I want to see three meaningfully different options.
+
+PROBLEM:
+A library that retries flaky operations. Used in Python services. Needs to support: exponential backoff, max attempts, retry only on specific exception types, callback on retry, async and sync code paths. Typical caller wraps a single function call.
+
+CONSTRAINTS:
+- Python 3.11+, no external runtime deps
+- Must work in both sync and async code (one library, not two)
+- Should be debuggable — users have to be able to see *why* a retry happened
+```
+
+## Notes
+
+- The prompt deliberately forbids "all three are good" answers. Forcing a pick exposes which dimensions matter most to the model.
+- Re-run with the same `PROBLEM` and a slightly different `CONSTRAINTS` to see how the recommendation shifts. That's often where the real insight is.
+- Works well with Opus. Sonnet tends to make the three options closer to each other than they should be.

package/share/skills/doc-stub-sync/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: doc-stub-sync
+description: 'Sync local documentation stubs with their current online versions — finds files matching a stub pattern (default `Fetch live documentation: <URL>`), compares content hashes, refetches changed pages, reports diffs. Use when the user says "update docs", "sync docs with online sources", "refresh local docs", or has a folder of stub files pointing at upstream URLs.'
+metadata:
+  version: 0.1.0
+  authors:
+    - mastermind
+  tags:
+    - docs
+    - automation
+    - sync
+  model: sonnet
+  requires:
+    - Bash
+    - Python 3.10+ (for the bundled script), OR any HTTP-capable runtime if doing it manually
+---
+
+# Documentation Stub Sync
+
+Keeps a tree of local documentation files in sync with their online sources. Works on the **stub-link pattern**: each local file contains a marker line like `Fetch live documentation: https://...` pointing at the canonical upstream URL. The skill finds those stubs, checks whether the upstream changed, and refetches only what's stale.
+
+This is for the specific workflow where you maintain a local mirror of upstream docs (vendor reference, framework docs, internal wiki snapshots) as part of your personal or team knowledge base. **Not** a general "fix all my docs" tool.
+
+## When to use
+
+- User says "update docs", "sync docs with online sources", "refresh local docs"
+- User points at a folder and says "the stubs in here are stale"
+- A local docs tree has files matching the stub pattern and the user wants them current
+- Do NOT use to *write* new documentation. Use a writing-focused skill for that.
+- Do NOT use on files that don't have the stub marker — the skill will skip them, but you shouldn't even point it there.
+
+## Prerequisites
+
+- A local directory containing markdown files with the stub pattern
+- Bash + Python 3.10+ if using the bundled script (`scripts/doc_update.py`)
+- Network access for the URLs in the stubs
+- Optional: configurable stub pattern (default `Fetch live documentation: <URL>`)
+
+## Steps
+
+### 1. Inventory
+
+Find every file matching the stub pattern under the target directory:
+
+```bash
+grep -rl "Fetch live documentation:" <target-dir> --include="*.md"
+```
+
+Then for each matched file, extract the URL. Report: total count, list of unique URLs, files-per-URL if any URL repeats. Show this to the user **before** any network requests — confirm scope.
+
+### 2. Confirm with the user
+
+Show the inventory and ask before proceeding. For >10 files, also note expected time (rule of thumb: ~1.5s/file with rate limiting). For >100 files, suggest breaking into batches by subdirectory.
+
+### 3. Detect what changed
+
+For each stub file:
+- Fetch the upstream URL (with timeout, single retry on transient failure)
+- Extract the main content region (`<main>`, `<article>`, or the largest content block)
+- Compute a hash (SHA-256 of normalized text — strip whitespace at line ends, collapse runs of blank lines)
+- Compute the same hash on the local file's content body (excluding the stub line)
+- If hashes match: **skip** (already current)
+- If hashes differ: **mark for update**
+- If URL returns ≥400 or times out: **mark unreachable**
+
+Rate limit: minimum 1 second between requests to the same host. Use the bundled script — `scripts/doc_update.py` — for the actual implementation. The script handles rate limiting, retry, and parallelism within rate limits.
+
+### 4. Update changed files
+
+For each "mark for update" file:
+- Build the new body: extracted content + the stub line preserved at the bottom
+- Write atomically (tmp file + rename) to avoid partial writes
+- Log: old hash → new hash, byte delta
+
+Never delete files. Never modify files that don't have the stub marker. Never touch files outside the target directory.
+
+### 5. Report
+
+Output a two-part report:
+
+**Machine-readable JSON** (for downstream tooling):
+```json
+{
+  "summary": {
+    "scanned": 96,
+    "updated": 12,
+    "skipped_current": 82,
+    "unreachable": 2,
+    "errors": 0,
+    "duration_seconds": 187
+  },
+  "updated": [
+    {"path": "anthropic/configuration/settings.md", "url": "...", "old_hash": "a1b2...", "new_hash": "c3d4...", "delta_bytes": 412}
+  ],
+  "unreachable": [
+    {"path": "...", "url": "...", "reason": "404 Not Found"}
+  ],
+  "errors": []
+}
+```
+
+**Human summary** (one paragraph + the deltas):
+```
+Synced 96 stubs in 3 minutes. Updated 12 files (largest delta: configuration/settings.md +412 B). 82 already current. 2 unreachable (404): see report. No write errors.
+```
+
+## Outputs
+
+- The JSON + human summary shown above
+- Optionally write the JSON to `<target-dir>/.doc-stub-sync-report.json` if the user asks for it
+- Only file modifications: the stub files themselves, atomically rewritten
+
+## ALWAYS / NEVER
+
+**ALWAYS**
+- Rate-limit (≥1s between requests to the same host)
+- Show inventory and ask for confirmation before any network requests
+- Preserve the stub marker line in the rewritten file
+- Atomic writes (tmp + rename)
+- Continue on individual file failures; never abort the whole batch on one error
+- Report unreachable URLs in the final summary
+
+**NEVER**
+- Modify files outside the target directory
+- Modify files that don't contain the stub marker
+- Delete files
+- Overwrite files where the hash is unchanged (it's a no-op, but skip the write — preserves mtime for downstream tools that watch it)
+- Fire requests at the same host faster than the rate limit, even on retries
+- Trust the upstream content blindly — strip scripts, styles, and tracking elements before hashing/storing
+
+## Examples
+
+### Full sync
+
+**User:** "Sync everything under `~/Documents/kb/anthropic/`."
+
+**Agent:**
+```
+Found 96 stub files under ~/Documents/kb/anthropic/. They reference 96 unique URLs across 3 hosts (docs.claude.com, www.anthropic.com, github.com/anthropics).
+
+Estimated time: ~3 minutes with rate limiting.
+
+Proceed? [yes / no / dry-run]
+```
+
+After confirmation, runs `scripts/doc_update.py` and emits the JSON + summary report.
+
+### Targeted
+
+**User:** "Just the configuration subdirectory."
+
+**Agent:**
+```
+Found 5 stub files under ~/Documents/kb/anthropic/configuration/:
+  - settings.md → docs.claude.com/.../settings
+  - model-config.md → docs.claude.com/.../model-config
+  - terminal-config.md → docs.claude.com/.../terminal
+  - memory.md → docs.claude.com/.../memory
+  - statusline.md → docs.claude.com/.../statusline
+
+Estimated time: ~10 seconds. Proceed?
+```
+
+### Dry-run
+
+**User:** "What would change if I ran it now?"
+
+**Agent:** Runs the hash comparison only, skipping the update step. Reports which files *would* change and which would stay.
+
+## References
+
+- [`references/url-patterns.md`](references/url-patterns.md) — recognized stub formats and how to add a new one
+- [`references/error-handling.md`](references/error-handling.md) — HTTP error codes and how the skill responds to each
+- [`scripts/doc_update.py`](scripts/doc_update.py) — bundled implementation (Python 3.10+)
+- [`scripts/requirements.txt`](scripts/requirements.txt) — Python deps for the script
+
+## Customizing the stub pattern
+
+Default: `Fetch live documentation: <URL>` (case-sensitive, URL is the rest of the line).
+
+To use a different pattern, pass `--stub-pattern` to the script with a regex containing one capture group for the URL. Example for a different convention:
+
+```bash
+python scripts/doc_update.py --stub-pattern 'Source: (https?://\S+)' <target-dir>
+```
+
+The skill body assumes the default pattern unless the user tells you otherwise. If you see they're using a different convention, ask first before assuming.

package/share/skills/doc-stub-sync/references/error-handling.md

@@ -0,0 +1,79 @@
+# Error handling — HTTP responses and how the skill reacts
+
+Reference for the [`doc-stub-sync`](../SKILL.md) skill. The script behavior is in [`../scripts/doc_update.py`](../scripts/doc_update.py).
+
+## How errors are classified
+
+Every stub processed ends up in one of four buckets in the report:
+
+- `updated` — content changed, file rewritten
+- `current` — content unchanged, file untouched
+- `unreachable` — request failed or returned ≥400, file untouched
+- `error` — local issue (permissions, disk, encoding), file untouched
+
+A stub never silently fails. Every problem lands in one bucket and is reported.
+
+## HTTP response handling
+
+| Status | Bucket | Skill action |
+|---|---|---|
+| 2xx | `current` / `updated` | Parse, hash, compare, maybe rewrite |
+| 301, 302, 307, 308 | (followed) | The HTTP client follows redirects automatically; the *final* response is what the skill evaluates. If the final response is ≥400, treat as unreachable. |
+| 304 Not Modified | `current` | Treated as no-change. (Note: the bundled script doesn't send `If-Modified-Since` yet — 304 in practice means the server volunteered it.) |
+| 401, 403 | `unreachable` | Auth required or forbidden. Don't retry with credentials — surface to user and stop. |
+| 404, 410 | `unreachable` | Upstream page is gone. The user has to decide: update the stub's URL, delete the file, or accept the staleness. The skill does NOT auto-delete. |
+| 408, 429, 503, 504 | `unreachable` (after one retry) | Transient. Script retries once after a 2-second pause. Still failing → unreachable. |
+| 5xx (other) | `unreachable` (after one retry) | Same handling as transient. |
+| Network timeout | `unreachable` (after one retry) | Single retry with backoff, then give up for this run. |
+| DNS / connection refused | `unreachable` | No retry — the host isn't there. |
+
+## Retry policy
+
+The script retries **once** on a network-level failure (timeout, connection error, DNS). It does **not** retry on HTTP status codes ≥400 — those represent a definitive answer from the server, not a transient transport issue.
+
+Why one retry, not more:
+- Most transient failures are resolved by waiting 1-2 seconds
+- More retries on a doc-sync job means slowing down the whole batch by minutes
+- 429 (rate limit) deserves a different response: respect the limit, don't hammer
+
+If the user is hitting 429 repeatedly, the fix is `--rate-limit` (raise it), not more retries.
+
+## Rate limiting
+
+The script enforces a per-host minimum interval between requests. Default: 1.0 second.
+
+This applies *per host*, not globally: syncing 50 stubs from `docs.claude.com` and 30 from `github.com` runs them in parallel as far as the rate limiter is concerned. Within each host, requests are serialized with the minimum gap.
+
+Raise `--rate-limit` to 2.0 or higher if the upstream is sensitive (small docs site, single-server) or you've seen 429s.
+
+## Local errors
+
+| Situation | Bucket | What to do |
+|---|---|---|
+| File not writable (permissions) | `error` | Surface to user. They fix the perms and re-run. |
+| Disk full | `error` | Surface. Don't keep trying. |
+| File contains invalid UTF-8 | (skipped at discovery) | These files aren't even inventoried. If the user expects them to be stubs, they have a separate problem. |
+| Atomic rename fails (race, cross-device tmp) | `error` | Surface the underlying OS error verbatim. Often means `tempfile.mkstemp` landed on a different filesystem than the target — usually a misconfigured `TMPDIR`. |
+
+## What the user sees on error
+
+Every error appears in two places:
+1. The JSON report (`errors` array, with `path`, `url`, `reason`)
+2. The human summary (count + first 3 reasons inline, full list pointer)
+
+Example human summary on errors:
+
+```
+Synced 96 stubs in 4 minutes. Updated 8. 80 already current. 6 unreachable (4×404, 2×timeout): see report. 2 errors (permission denied): see report.
+```
+
+If the run had *only* errors and no updates, exit code is non-zero — pipelines and cron jobs that depend on the script can detect this.
+
+## What the agent does with the report
+
+The skill's job is to **report**, not to **act on** errors. The user decides:
+- A 404 on a doc → maybe the upstream renamed it. Update the stub URL or delete the local file.
+- 401/403 → maybe the doc moved behind auth. Out of scope for this skill.
+- A permissions error → the user fixes the OS-level perms and re-runs.
+
+The skill does **not** edit stub URLs, delete files, or modify other files in response to errors. Those are destructive operations and they belong to the user (or to a separate, explicitly-invoked tool).

package/share/skills/doc-stub-sync/references/url-patterns.md

@@ -0,0 +1,83 @@
+# Stub URL patterns
+
+This reference covers stub formats the [`doc-stub-sync`](../SKILL.md) skill recognizes, and how to add new ones.
+
+## The default pattern
+
+```
+Fetch live documentation: https://docs.example.com/path/to/page
+```
+
+Regex: `Fetch live documentation:\s*(https?://\S+)`
+
+This is the format the bundled `scripts/doc_update.py` looks for unless overridden.
+
+### Why this pattern
+
+- **Easy to grep**: single grep across the whole tree finds every stub
+- **Self-documenting**: a human reading the file knows where the canonical source is
+- **One URL per file**: forces one-doc-per-stub-file, which simplifies sync logic
+- **Tool-agnostic prefix**: the words `Fetch live documentation:` are unlikely to appear in normal prose, so false matches are rare
+
+## Where the pattern goes inside the file
+
+The skill doesn't care about position — it greps the whole file. By convention:
+
+- **At the end of the file**, after a `---` separator, as a "source" footer
+- **In a frontmatter field** (e.g., `source: https://...`) — for that, switch to a frontmatter-aware pattern (see below)
+
+## Common alternative patterns
+
+If your knowledge base uses a different convention, pass `--stub-pattern` to the script. The pattern must be a Python regex with **exactly one capture group** that captures the URL.
+
+### Source-line convention
+
+```
+Source: https://docs.example.com/page
+```
+
+```bash
+python scripts/doc_update.py --stub-pattern 'Source:\s*(https?://\S+)' ./docs
+```
+
+### HTML-comment marker
+
+```html
+<!-- mirror: https://docs.example.com/page -->
+```
+
+```bash
+python scripts/doc_update.py --stub-pattern '<!--\s*mirror:\s*(https?://\S+)\s*-->' ./docs
+```
+
+### Frontmatter `source:` field
+
+```yaml
+---
+title: API Reference
+source: https://docs.example.com/api
+---
+```
+
+```bash
+python scripts/doc_update.py --stub-pattern '^source:\s*(https?://\S+)$' ./docs
+```
+
+Frontmatter matching is best done with the multiline flag — wrap the pattern in `(?m)` if needed: `'(?m)^source:\s*(https?://\S+)$'`.
+
+## Adding a new pattern to the standard
+
+If you find yourself using a new pattern across multiple projects, send a PR adding:
+
+1. An entry to this file under "Common alternative patterns"
+2. An example command line
+3. A short note on when this pattern is preferable
+
+Don't add a flag to the script for every pattern — the regex flag is general enough. Only the default in `DEFAULT_STUB_PATTERN` is special, and we don't change the default casually (it would break every existing local KB using this skill).
+
+## Pattern gotchas
+
+- **Greediness**: `https?://.+` will eat trailing punctuation. Use `\S+` to stop at whitespace.
+- **Multiline**: stubs that wrap across lines aren't supported — keep the URL on the same line as the marker.
+- **Query strings and fragments**: included by default. If you want to strip `?utm_*` and `#fragments` for hashing, do it in the script, not the regex.
+- **Multiple stubs per file**: only the *first* match wins. If a file points at multiple URLs, it's not a stub file — it's a hand-edited doc, leave it alone.