docs: add task-routed agent wiki

Add a shared instruction kernel and byte-budgeted topic router so agents load only task-relevant repository guidance. Wire drift checks into local and CI workflows and point project skills at the routed topics.
This commit is contained in:
Willie
2026-09-25 02:32:37 +08:00
parent bf32112032
commit 262e639701
27 changed files with 891 additions and 59 deletions
+3 -2
View File
@@ -4,14 +4,12 @@ on:
push:
branches: [main]
paths-ignore:
- "docs/**"
- "website/**"
- "README.md"
- "CHANGELOG.md"
pull_request:
branches: [main]
paths-ignore:
- "docs/**"
- "website/**"
- "README.md"
- "CHANGELOG.md"
@@ -27,6 +25,9 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
- name: Check AI context routes
run: python3 scripts/ai-context.py check
- name: Set up Go
uses: actions/setup-go@v5
with:
+3
View File
@@ -27,6 +27,9 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
- name: Check AI context routes
run: python3 scripts/ai-context.py check
- name: Set up Node.js
uses: actions/setup-node@v4
with:
-2
View File
@@ -18,8 +18,6 @@ Thumbs.db
# Test
coverage.out
.claude/
/AGENTS.md
/CLAUDE.md
docs/plans/
docs/superpowers/
.agents/
@@ -19,6 +19,8 @@ Generate a CHANGELOG.md entry for a release. $ARGUMENTS specifies the tag versio
**Scope**: This skill updates `CHANGELOG.md` and syncs the website changelog (`website/src/pages/changelog.md`). It does NOT generate RELEASE_NOTES, update version numbers, or handle the full release workflow — use `/release` for that.
Before acting, run `python3 scripts/ai-context.py release`. That topic is the source of truth for authorization, changelog content and synchronization rules; this skill retains the entry-generation workflow.
## Workflow
### Step 1: Determine Version Range
@@ -135,9 +137,4 @@ The website has its own changelog page at `website/src/pages/changelog.md`. Afte
## Rules
- **User perspective** — write for users, not developers
- **No fabricated links** — never invent URLs or references
- **Verify features exist** — grep source before claiming a feature was added
- **No internal noise** — exclude test-only, CI-only, or refactor-only changes
- **Conventional format** — follow existing CHANGELOG.md style exactly
- **Always sync both** — `CHANGELOG.md` and `website/src/pages/changelog.md` must have identical release entries
Apply the `release` topic. This adapter is changelog-only and does not broaden authorization to commit, tag, push or publish.
@@ -16,6 +16,8 @@ metadata:
Run isolated E2E tests in devcontainer. $ARGUMENTS specifies runbook name or "new".
Before acting, run `python3 scripts/ai-context.py testing`. The topic is the source of truth for isolation, runbook quality and reporting rules; this skill retains the execution flow and mdproof recipes.
## Flow
### Phase 0: Environment Check
@@ -150,7 +152,7 @@ Prompt user (via AskUserQuestion):
- **Use `jq:` assertions in Expected blocks** for JSON commands — e.g. `- jq: .extras | length == 1`. This is a native mdproof assertion type, NOT a bash `jq` pipe
- **Use `--json` + `jq -e` in bash** for inline verification within multi-command steps
- **Config idempotency** — never bare `cat >> config.yaml`; always prepend `sed -i '/^section:/,$d'` to remove existing section first, or use CLI commands (`ss extras init`, `ss extras remove --force`) that handle duplicates
- **Check `ai_docs/tests/runbook.json`** for project-level config (build, setup, teardown, step_setup, timeout) that affects all runbooks
- **Check `ai_docs/tests/mdproof.json`** for project-level config (build, setup, teardown, step_setup, timeout) that affects all runbooks
- **Check `.mdproof/lessons-learned.md`** for known assertion patterns and gotchas
5. **Run the runbook quality checklist** (see below) before executing
6. Then execute the new runbook (same flow as above)
@@ -258,17 +260,7 @@ mdproof supports 6 assertion types under `Expected:` blocks. Use the most specif
## Rules
- **Always execute inside devcontainer** — use `docker exec`, never run CLI on host
- **Always use `ssenv` for HOME isolation** — don't pollute container default HOME
- **Always create fresh ssenv environments** — never reuse an environment from a previous run; stale config/state causes confusing cascade failures (e.g. duplicate YAML keys, "already exists" errors)
- **ssenv only isolates `$HOME`** — `/tmp/`, `/var/`, and other system paths are shared across all environments. Runbook steps using `/tmp/` must include `rm -rf` cleanup at the start
- **Verify every step** — never skip Expected checks
- **Don't abort on failure** — record FAIL, continue to next step, summarize at end
- **Ask before cleanup** — Phase 4 must prompt user before deleting ssenv environment
- **`ss` = `skillshare`** — same binary in runbooks
- **`~` = ssenv-isolated HOME** — `ssenv enter` auto-sets `HOME`
- **Use `--init`** — simplify setup by using `ssenv create <name> --init`
- **`--init` already runs init** — the env is pre-initialized; runbook steps calling `ss init` again will fail unless the step explicitly resets state first
Apply the `testing` topic. Keep detailed assertion recipes in this workflow consistent with that topic and `.mdproof/lessons-learned.md`.
## ssenv Quick Reference
@@ -400,7 +392,7 @@ This skill (`/cli-e2e-test`) and the `/mdproof` skill are **complementary**, not
|---------|-----------------|------------|
| **Scope** | Skillshare project-specific E2E | General-purpose runbook authoring |
| **Infrastructure** | Devcontainer, ssenv, binary build | None — format and assertions only |
| **Config** | `ai_docs/tests/runbook.json` (build, setup, teardown) | Assertion types, snapshot, coverage |
| **Config** | `ai_docs/tests/mdproof.json` (build, setup, teardown) | Assertion types, snapshot, coverage |
| **Lessons** | Checklist items, CLI flag gotchas | `.mdproof/lessons-learned.md` |
| **When** | Running or debugging a test | Writing or improving a runbook |
@@ -16,13 +16,15 @@ Read-only consistency audit across the skillshare codebase. $ARGUMENTS specifies
**Scope**: This skill only READS and REPORTS. It does not modify any files. Use `implement-feature` to fix issues or `update-docs` to fix documentation gaps.
Before acting, run `python3 scripts/ai-context.py audit`. That topic is the source of truth for audit dimensions, evidence requirements and status meanings; this skill retains the search and report workflow.
## Audit Dimensions
Run all 4 dimensions in parallel where possible. For each, produce a summary table.
### 1. CLI Flag Audit
Compare every flag defined in `cmd/skillshare/*.go` against `website/docs/commands/*.md`.
Compare every flag defined in `cmd/skillshare/*.go` against `website/docs/reference/commands/*.md`.
```bash
# Find all flags in Go source
@@ -223,7 +225,4 @@ Report:
## Rules
- **Read-only** — never modify files, only report
- **Evidence-based** — every finding must include file path and line number
- **No false positives** — verify with grep before flagging
- **Scope $ARGUMENTS** — if user specifies "flags", only run dimension 1; "handlers" for dimension 5, "oplog" for dimension 6, "api" for dimension 7
Apply the `audit` topic and keep this workflow read-only.
@@ -16,6 +16,8 @@ metadata:
Execute CLI commands and tests inside the devcontainer. The host machine is macOS but the project binary is Linux — running CLI commands on the host will silently produce wrong results or fail. This skill prevents that mistake.
Before acting, run `python3 scripts/ai-context.py testing` and follow that topic. The topic is the source of truth for repository execution boundaries and test rules; this skill retains the interactive workflow and command recipes.
## When to Use This
- Running `ss` / `skillshare` commands for verification
@@ -204,8 +206,4 @@ For automation (non-interactive), prefer `ssenv enter <name> -- <command>` over
## Rules
- **All CLI execution inside devcontainer** — no exceptions
- **Use ssenv for stateful tests** — don't pollute default HOME
- **Always verify** — run the command and check output; never assume it worked
- **Clean up** — delete ssenv environments after use (or ask user)
- **Report container ID** — set `$CONTAINER` at the start and reuse throughout
Apply the `testing` topic. If a command recipe here conflicts with that topic or current repo configuration, verify the current configuration and update both in the same change.
@@ -18,6 +18,8 @@ Implement a feature following TDD workflow. $ARGUMENTS is a spec file path (e.g.
**Scope**: This skill writes Go code and tests. It does NOT update website docs (use `update-docs` after) or CHANGELOG (use `changelog` after).
Before acting, run `python3 scripts/ai-context.py cli-development testing`. Those topics are the source of truth for repository patterns, execution boundaries and verification; this skill retains the TDD orchestration.
## Workflow
### Step 1: Understand Requirements
@@ -248,10 +250,4 @@ If the feature does not meet the criteria above, skip this step.
## Rules
- **Test-first** — always write failing test before implementation
- **Minimal code** — only write what's needed to pass tests
- **Follow patterns** — match existing code style in each package
- **3-strike rule** — if a test fails 3 times after fixes, stop and report what's blocking
- **No docs** — this skill writes code only; use `update-docs` for documentation
- **No changelog** — use `changelog` skill for release notes
- **Spec ambiguity** — ask the user rather than guessing
Apply `cli-development` and `testing`. Load `documentation` as well when the authorized task includes user-facing documentation.
@@ -13,6 +13,8 @@ metadata:
End-to-end release workflow for skillshare. $ARGUMENTS specifies the version (e.g., `v0.19.0`).
Before acting, run `python3 scripts/ai-context.py release testing`. Those topics are the source of truth for authorization, release artifacts and verification; this skill retains the release orchestration and draft formats.
## Prerequisites
- All feature work merged to current branch
@@ -120,12 +122,4 @@ git push origin HEAD --tags
## Rules
- **Fix, don't skip** — if tests fail, fix them before continuing
- **User perspective** — all written output is for users, not developers
- **Short drafts** — announcements default to concise; user will ask for more detail if needed
- **No fabricated links** — never invent URLs or references
- **Verify before claiming** — grep source before stating a feature exists
- **Ask before push** — never push or publish without explicit user confirmation
- **Release notes stay local by default** — never force-add or commit `specs/RELEASE_NOTES_*.md` unless the user explicitly asks
- **Commit message** — always `chore: release vX.Y.Z`
- **No competitive references** — never mention competitor repos in commit messages or notes
Apply `release` and `testing`. Never infer permission to push or publish from preparation work.
@@ -16,6 +16,8 @@ metadata:
Enforce the skillshare design system across the two frontends. $ARGUMENTS is the file or area being worked on.
Before acting, run `python3 scripts/ai-context.py frontend`. That topic and the CSS/source files it identifies are the source of truth; this skill retains the component catalog and visual QA checklist.
| Aspect | UI Dashboard (`ui/`) | Website (`website/`) |
|--------|---------------------|----------------------|
| Stack | React 19 + Vite + Tailwind CSS v4 | Docusaurus 3 + custom CSS |
@@ -18,6 +18,8 @@ Sync website documentation with recent code changes. $ARGUMENTS specifies scope:
**Scope**: This skill only updates `website/docs/`. It does NOT write Go code (use `implement-feature`) or CHANGELOG (use `changelog`).
Before acting, run `python3 scripts/ai-context.py documentation`. That topic is the source of truth for documentation ownership, code cross-validation and verification; this skill retains the update workflow.
## Workflow
### Step 1: Detect Changes
@@ -75,7 +77,7 @@ For each affected command:
2. Read the corresponding doc page:
```
website/docs/commands/<cmd>.md
website/docs/reference/commands/<cmd>.md
```
3. Compare and fix:
@@ -121,7 +123,7 @@ List all changes made with rationale:
== Documentation Updates ==
Modified:
website/docs/commands/install.md
website/docs/reference/commands/install.md
- Added --into flag documentation
- Updated install examples
@@ -133,9 +135,4 @@ Build: PASS (no broken links)
## Rules
- **Source of truth is code** — docs must match what the code actually does
- **Every flag claim must be verified** — grep source before writing docs
- **No speculative docs** — never document planned but unimplemented features
- **No code changes** — this skill only touches `website/docs/`, `skills/skillshare/SKILL.md`, and `README.md`
- **Preserve style** — match existing doc page structure and tone
- **Built-in skill desc limit** — must stay under 1024 characters
Apply the `documentation` topic. Keep this adapter scoped to documentation; use the implementation or release workflows for other changes.
+68
View File
@@ -0,0 +1,68 @@
# AGENTS.md — skillshare
skillshare is a Go CLI with a React dashboard and a Docusaurus documentation site. It synchronizes skills, agents, extras, MCP servers, and plugins across AI coding tools. This file contains only rules needed for every task; load task-specific details through the context topics below.
## Language
- Instruction files, internal documentation, public English documentation, code, identifiers, comments, and commit messages use English.
- Reply to users in their language; default to Traditional Chinese when the user writes Chinese.
- `README.md` is the public English source. Keep translated READMEs aligned with its existing localization conventions. Preserve history files in their original language.
## Always Applies
- **Use executable evidence.** Verify facts that affect conclusions or implementation against current source, configuration, installed versions, or actual command output. Distinguish facts, assumptions, and uncertainty.
- **Preserve user changes and keep scope minimal.** Inspect the working tree before editing, then trace relevant definitions, callers, tests, and existing patterns. Never overwrite unrelated changes or perform opportunistic cleanup.
- **Keep the docs true.** When documentation disagrees with code, verify the code and fix the stale documentation in the same task. Update a topic whenever a change alters behavior it describes. Put completed milestone logs in `wiki/history/` and add them to the index. Run `python3 scripts/ai-context.py check` after documentation changes. The maintenance procedure is in the `ai-context` topic.
- **Run commands in the correct environment.** Execute the skillshare CLI, Go builds/tests, UI tooling, and website tooling inside the devcontainer. The host is only for file edits, read-only searches, Git inspection, and the context-router check. Load `testing` before execution or debugging.
- **Verify in proportion to risk.** Start with the narrowest check that proves the change. Reproduce bugs and add regression tests when practical. Never skip, disable, or weaken validation to obtain a passing result.
- **Respect authorization boundaries.** Reviews, investigations, and diagnoses are read-only by default. Do not commit, push, publish, deploy, install global tools, or perform destructive or irreversible actions unless explicitly authorized.
- **Use Git safely.** Never overwrite user changes. When asked to commit, stage only task-owned files and follow repository conventions; otherwise use an English Conventional Commit with a body explaining why.
- **Keep helper files in the repository.** Put reusable helper scripts in `scripts/<area>/` and test runbooks in `ai_docs/tests/`. Do not store persistent task artifacts outside the repository.
- **Report outcomes precisely.** State what changed, why, actual verification results, limitations, and preserved unrelated changes. Explicitly identify checks that were not run.
## Hard Limits
- Never run `ss`, `skillshare`, `go test`, `make test`, or frontend package scripts on the host.
- Never expose, hardcode, or commit secrets, tokens, credentials, or private user-path contents.
- Never bypass audits, hooks, tests, trust prompts, or native client confirmation.
- Never change permissions, delete persistent data, rewrite Git history, commit, tag, push, or release without explicit authorization.
- Resolve and confirm the exact target before a destructive action. Never recursively delete a workspace root, home directory, or unresolved broad path.
## Load Context Per Task
```sh
python3 scripts/ai-context.py list # list topics and selection guidance
python3 scripts/ai-context.py <topic> # print only that topic's sources
python3 scripts/ai-context.py check # validate paths, headings, orphans, and byte budgets
```
| Topic | Use when |
|---|---|
| `architecture` | Tracing repository structure, data flow, or CLI/Web API boundaries |
| `cli-development` | Adding or changing Go CLI commands, flags, handlers, TUIs, or mutating behavior |
| `testing` | Building, testing, reproducing bugs, using the devcontainer/ssenv, or running E2E runbooks |
| `frontend` | Changing React, CSS, layout, or visual behavior in `ui/` or `website/` |
| `documentation` | Updating README files, website docs, command flags, translations, or the built-in skill |
| `release` | Writing changelogs or release notes, bumping versions, tagging, or releasing |
| `audit` | Read-only consistency checks for flags, docs, tests, targets, handler splits, oplog, or Web API |
| `ai-context` | Adding, moving, or splitting wiki topics, or fixing router checks |
Pick the single closest topic by default. Load a second only when a task genuinely crosses two seams. If no topic fits, read `wiki/README.md`.
To add a topic:
1. Put its content in `wiki/`.
2. Map it in `docs/ai-context.json`.
3. Add it to this table and `wiki/README.md`.
4. Run `check`.
Split an over-budget topic instead of raising its cap. Skills are workflow adapters that load topics; they are not the sole source of repository rules.
## Verification
```sh
python3 scripts/ai-context.py check
# Code changes: run inside the devcontainer after loading `testing`
make check
```
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+2
View File
@@ -51,6 +51,8 @@ The language links at the top of each README are sorted by language code (`ja`,
All development and testing should be done inside the **devcontainer**. This ensures a consistent environment (Go toolchain, Node.js, pnpm, and demo content are pre-configured).
Repository-specific task context is indexed in the [developer wiki](wiki/README.md). Agents should load the closest topic with `python3 scripts/ai-context.py <topic>` before making changes.
```bash
git clone https://github.com/runkids/skillshare.git
cd skillshare
+6 -2
View File
@@ -1,4 +1,4 @@
.PHONY: help build build-meta build-windows run test test-unit test-int test-docker test-docker-online test-redteam test-redteam-signal test-redteam-rules-signal playground playground-down devc devc-up devc-down devc-restart devc-reset devc-status dev-docker dev-docker-down docker-build docker-build-multiarch lint fmt fmt-check check install clean ui-install ui-build ui-dev build-all verify verify-shell verify-down verify-status verify-reset
.PHONY: help build build-meta build-windows run test test-unit test-int test-docker test-docker-online test-redteam test-redteam-signal test-redteam-rules-signal playground playground-down devc devc-up devc-down devc-restart devc-reset devc-status dev-docker dev-docker-down docker-build docker-build-multiarch lint fmt fmt-check docs-check check install clean ui-install ui-build ui-dev build-all verify verify-shell verify-down verify-status verify-reset
help:
@echo "Common tasks:"
@@ -27,6 +27,7 @@ help:
@echo " make verify-reset # delete the throwaway HOME"
@echo " make lint # go vet"
@echo " make fmt # format Go files"
@echo " make docs-check # validate AI context routes and budgets"
@echo " make check # fmt-check + lint + test"
@echo " make ui-dev # Go API server + Vite dev server (requires local Go)"
@echo " make dev-docker # Go API in Docker + auto-rebuild (pair with: cd ui && pnpm run dev)"
@@ -139,7 +140,10 @@ fmt:
fmt-check:
test -z "$$(gofmt -l ./cmd ./internal ./tests)"
check: fmt-check lint test
docs-check:
python3 scripts/ai-context.py check
check: docs-check fmt-check lint test
install:
go install ./cmd/skillshare
+85
View File
@@ -0,0 +1,85 @@
{
"rootInstructions": "AGENTS.md",
"budgets": {
"rootInstructionsMaxBytes": 8192,
"defaultTopicMaxBytes": 16384
},
"topics": {
"architecture": {
"description": "Trace repository structure, data flow, and CLI or Web API boundaries.",
"sources": [
{
"path": "wiki/architecture.md"
}
]
},
"cli-development": {
"description": "Add or change Go CLI commands, flags, handlers, TUIs, or mutating behavior.",
"sources": [
{
"path": "wiki/cli-development.md"
}
]
},
"testing": {
"description": "Build, test, reproduce bugs, use the devcontainer or ssenv, and run E2E runbooks.",
"sources": [
{
"path": "wiki/testing.md"
},
{
"path": "CONTRIBUTING.md",
"heading": "Development Setup"
}
]
},
"frontend": {
"description": "Change React, CSS, layout, or visual behavior in the dashboard or website.",
"sources": [
{
"path": "wiki/frontend.md"
},
{
"path": "website/AGENTS.md"
}
]
},
"documentation": {
"description": "Update README files, website docs, command flags, translations, or the built-in skill.",
"sources": [
{
"path": "wiki/documentation.md"
},
{
"path": "CONTRIBUTING.md",
"heading": "Translated READMEs"
}
]
},
"release": {
"description": "Write changelogs or release notes, bump versions, tag, or release.",
"sources": [
{
"path": "wiki/release.md"
}
]
},
"audit": {
"description": "Read-only consistency checks for flags, docs, tests, targets, handler splits, oplog, or Web API.",
"sources": [
{
"path": "wiki/audit.md"
}
]
},
"ai-context": {
"description": "Maintain the documentation router and fix topic, path, budget, or orphan check failures.",
"sources": [
{
"path": "wiki/ai-context.md"
}
]
}
},
"unrouted": {}
}
+144
View File
@@ -0,0 +1,144 @@
#!/usr/bin/env python3
"""Print only the doc sections a task needs.
usage: ai-context.py list | <topic> [<topic>...] | check
Topics live in docs/ai-context.json. A source is a whole file or one exact
heading (the section runs to the next heading of the same or higher level).
check also fails on orphans, so docs cannot silently drift out of the router:
wiki pages no topic loads, history files missing from the router index, and
nested AGENTS.md files no topic loads. List deliberate exceptions under
"unrouted" in the config, each with a reason.
Copy this file to <repo>/scripts/ai-context.py; the repo root is its parent's parent.
No dependencies beyond the Python 3.8+ standard library.
"""
import json, os, re, sys
ROOT = os.path.realpath(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
CFG_PATH = os.path.join(ROOT, 'docs', 'ai-context.json')
HEAD = re.compile(r'^(#{1,6})\s+(.+?)\s*#*\s*$')
FENCE = re.compile(r'^\s{0,3}(`{3,}|~{3,})')
def load_cfg():
if not os.path.exists(CFG_PATH):
sys.exit(f'missing {CFG_PATH}; copy this script to <repo>/scripts/ and create docs/ai-context.json')
with open(CFG_PATH, encoding='utf-8') as f:
return json.load(f)
def headings(lines):
"""Yield (index, level, text), skipping headings inside fenced code (e.g. shell comments)."""
fence = None
for i, ln in enumerate(lines):
m = FENCE.match(ln)
if m:
mark = m.group(1)
if fence is None:
fence = mark[0] * len(mark)
elif mark.startswith(fence):
fence = None
continue
if fence is None and (h := HEAD.match(ln)):
yield i, len(h.group(1)), h.group(2)
def section(src):
path = os.path.realpath(os.path.join(ROOT, src['path']))
if not path.startswith(ROOT + os.sep):
raise ValueError(f'{src["path"]}: outside repo')
with open(path, encoding='utf-8') as f:
lines = f.read().split('\n')
if 'heading' not in src:
return '\n'.join(lines).strip()
hs = list(headings(lines))
hits = [(i, lv) for i, lv, t in hs if t == src['heading']]
if len(hits) != 1: # fail closed: a renamed or duplicated heading must not load the wrong text
raise ValueError(f'{src["path"]}: heading {src["heading"]!r} found {len(hits)}x')
start, level = hits[0]
end = next((i for i, lv, _ in hs if i > start and lv <= level), len(lines))
return '\n'.join(lines[start:end]).strip()
def render(cfg, name):
out = []
for s in cfg['topics'][name]['sources']:
where = s['path'] + (f' § {s["heading"]}' if 'heading' in s else '')
out.append(f'<!-- {where} -->\n{section(s)}')
return '\n\n'.join(out)
def orphans(cfg):
"""Docs that exist on disk but that no agent can reach through the router."""
wiki = cfg.get('wikiDir', 'wiki')
history = cfg.get('historyDir', f'{wiki}/history')
router = cfg.get('routerFile', f'{wiki}/README.md')
root_file = cfg.get('rootInstructions', 'AGENTS.md')
routed = {s['path'] for t in cfg['topics'].values() for s in t['sources']}
allowed = set(cfg.get('unrouted', {}))
router_text = open(os.path.join(ROOT, router), encoding='utf-8').read() if os.path.exists(os.path.join(ROOT, router)) else ''
bad = []
skip = {'.git', 'node_modules', 'dist', 'build', 'vendor', '.venv', 'target'}
for d, dirs, files in os.walk(ROOT):
dirs[:] = [x for x in dirs if x not in skip and not x.startswith('.')]
for f in files:
rel = os.path.relpath(os.path.join(d, f), ROOT)
if rel in allowed or not f.endswith('.md'):
continue
if rel.startswith(history + os.sep):
if os.path.relpath(rel, wiki) not in router_text and rel not in router_text:
bad.append(f'{rel}: history file not indexed in {router}')
elif rel.startswith(wiki + os.sep):
if rel != router and rel not in routed:
bad.append(f'{rel}: wiki page no topic loads (map it, or list it under "unrouted" with a reason)')
elif f == 'AGENTS.md' and rel != root_file and rel not in routed:
bad.append(f'{rel}: scoped instructions no topic loads')
return bad
def check(cfg):
bad = orphans(cfg)
budgets = cfg.get('budgets', {})
root_file = cfg.get('rootInstructions', 'AGENTS.md')
root_text = open(os.path.join(ROOT, root_file), encoding='utf-8').read()
root_size = len(root_text.encode())
root_cap = budgets.get('rootInstructionsMaxBytes', 8192)
print(f'{root_file:18} {root_size:6} B (cap {root_cap})')
if root_size > root_cap:
bad.append(f'{root_file} {root_size} B > {root_cap}')
for name, t in cfg['topics'].items():
if f'`{name}`' not in root_text:
bad.append(f'{name}: not listed in {root_file} (agents will not know it exists)')
try:
size = len(render(cfg, name).encode())
except (ValueError, OSError) as e:
bad.append(f'{name}: {e}')
continue
cap = t.get('maxBytes', budgets.get('defaultTopicMaxBytes', 16384))
print(f'{name:18} {size:6} B (cap {cap})')
if size > cap:
bad.append(f'{name}: {size} B > {cap} (split the topic; do not raise the cap)')
for b in bad:
print('FAIL', b)
print('ok' if not bad else f'{len(bad)} problem(s)')
return 1 if bad else 0
def main(argv):
cfg = load_cfg()
args = argv[1:] or ['list']
if args == ['list']:
for n, t in cfg['topics'].items():
print(f'{n:18} {t["description"]}')
return 0
if args == ['check']:
return check(cfg)
unknown = [a for a in args if a not in cfg['topics']]
if unknown:
sys.exit(f'unknown topic {unknown[0]!r}; run: python3 scripts/ai-context.py list')
print('\n\n'.join(render(cfg, a) for a in args))
return 0
if __name__ == '__main__':
sys.exit(main(sys.argv))
+31
View File
@@ -0,0 +1,31 @@
# skillshare Wiki Router
The wiki stores development background, procedures, references, and history, but no task needs all of it at once. Rules that apply to every task live in the root `AGENTS.md`. `docs/ai-context.json` is the only source of truth for topic-to-source mappings.
```sh
python3 scripts/ai-context.py list
python3 scripts/ai-context.py <topic>
```
## Task Routing
| Topic | Use when | Main sources |
|---|---|---|
| `architecture` | Tracing repository structure, data flow, or CLI/Web API boundaries | `architecture.md` |
| `cli-development` | Adding or changing Go CLI commands, flags, handlers, TUIs, or mutating behavior | `cli-development.md` |
| `testing` | Building, testing, reproducing bugs, using the devcontainer/ssenv, or running E2E runbooks | `testing.md`, `CONTRIBUTING.md` |
| `frontend` | Changing React, CSS, layout, or visual behavior in the dashboard or website | `frontend.md`, `website/AGENTS.md` |
| `documentation` | Updating README files, website docs, flags, translations, or the built-in skill | `documentation.md`, `CONTRIBUTING.md` |
| `release` | Writing changelogs or release notes, bumping versions, tagging, or releasing | `release.md` |
| `audit` | Running read-only consistency audits | `audit.md` |
| `ai-context` | Maintaining router topics, budgets, and orphan checks | `ai-context.md` |
Run `python3 scripts/ai-context.py check` after changing topics. This table is the human entry point; the JSON configuration controls what the loader renders.
## History (Milestone Logs; Read on Demand)
No milestone logs have been moved yet. When adding `wiki/history/<milestone>.md`, add a row to this table.
| File | Contents |
|---|---|
| — | None yet |
+59
View File
@@ -0,0 +1,59 @@
# AI Context Router
This page is the complete in-repository manual for maintaining agent documentation routing without an external skill. Load it with `python3 scripts/ai-context.py ai-context`.
## Layers
1. **Kernel:** root `AGENTS.md`, loaded for every task. It contains only universal rules and topic triggers.
2. **Scoped instructions:** package- or app-specific nested `AGENTS.md` files. Every scoped file must be loaded by at least one topic.
3. **Topics:** `docs/ai-context.json` maps topics to complete files or exact headings. `scripts/ai-context.py <topic>` prints only those sections.
4. **History:** `wiki/history/` stores milestone logs in their original language. History is not loaded by default and is indexed in `wiki/README.md`.
`docs/ai-context.json` is the single source of truth. The tables in `AGENTS.md` and `wiki/README.md` are discovery mirrors.
## When Documentation Must Change
Update documentation in the same change that makes it stale:
| Change | Update |
|---|---|
| Changed behavior described by a topic | That topic page |
| Found documentation that contradicts code | Verify the code, fix the documentation, and mention it in the handoff |
| Learned a cross-task lesson from a failure | A one-line behavior rule in the kernel plus the procedure in its topic |
| Finished a milestone | `wiki/history/<milestone>.md` and the `wiki/README.md` history index |
| Added a recurring kind of task | A new topic, JSON entry, and both topic tables |
| Added a nested `AGENTS.md` | Map it to a topic |
Do not put volatile state in the wiki, including progress counts, current owners, or today's blocker. Keep that information in the tracker.
## Adding or Changing a Topic
1. Put the content in `wiki/<page>.md`. A topic should represent a recognizable kind of work, not one ticket or file.
2. Map it in `docs/ai-context.json` using a complete file or exact heading.
3. Add it to the tables in `AGENTS.md` and `wiki/README.md`.
4. Run `python3 scripts/ai-context.py check`.
5. Render the topic and read it as an agent would; it must be sufficient on its own for the task.
Heading references must be unique and exact. A section ends at the next heading of the same or higher level. Never use line ranges.
## What Check Enforces
- Every path stays inside the repository and exists, and every heading matches exactly once.
- `AGENTS.md` and every topic stay within byte budgets. Split an over-budget topic instead of raising its cap.
- Every JSON topic appears in `AGENTS.md`.
- There are no orphans:
- every non-history wiki page is loaded by a topic;
- every history file is indexed in `wiki/README.md`;
- every nested `AGENTS.md` is loaded by a topic.
Only genuine human-only exceptions belong in the JSON `unrouted` map, and every exception requires a reason.
## Skills and CI
Skills retain workflow phases, report templates, and helper invocation. They load the applicable topic before acting; repository rules must not exist only in a skill.
The router check runs through the `Makefile` `docs-check`/`check` targets and the test and website workflows. After changing the router, run:
```sh
python3 scripts/ai-context.py check
```
+61
View File
@@ -0,0 +1,61 @@
# Repository Architecture
Use when deciding which layer should own a change, tracing CLI or Web API data flow, or building an initial mental model of the codebase.
## Product Boundaries
skillshare's source of truth is either the global configuration directory (`~/.config/skillshare/` by default on macOS/Linux) or project-local `.skillshare/` state. The CLI transforms or synchronizes skills, agents, extras, MCP servers, and plugins into each AI tool's native locations. Never infer runtime behavior from README files or documentation alone; verify the current implementation and embedded configuration.
## Repository Map
| Path | Responsibility |
|---|---|
| `cmd/skillshare/` | CLI entry point, flag parsing, mode routing, TUIs, and command orchestration |
| `internal/config/` | Global/project configuration, registry, migrations, and target resolution; `targets.yaml` defines built-in targets |
| `internal/<domain>/` | Domain logic such as install, sync, audit, MCP, plugins, and backup |
| `internal/server/` | Dashboard HTTP API; routes are registered in `server.go` and handlers live in `handler_*.go` |
| `internal/testutil/` | Shared isolated `Sandbox` and CLI runner for integration tests |
| `tests/integration/` | CLI integration tests |
| `ui/` | React 19 and Vite dashboard; its API client corresponds to `internal/server/` |
| `website/` | Docusaurus public documentation and marketing pages |
| `ai_docs/tests/` | Reproducible CLI E2E runbooks |
| `skills/skillshare/` | Built-in skill for skillshare users, not internal development instructions |
| `schemas/` | Public YAML/JSON schemas; inspect these when configuration shapes change |
| `scripts/`, `Makefile`, `mise.toml` | Build, test, devcontainer, and verification entry points |
## Request Flow
A typical CLI request follows this path:
1. The `commands` map in `cmd/skillshare/main.go` dispatches the command.
2. `cmd/skillshare/<command>.go` parses flags and selects global or project mode.
3. `cmd/skillshare/<command>_*.go` composes domain operations, prompts, and output.
4. `internal/<domain>/` performs filesystem, Git, configuration, or audit logic.
5. Mutating operations write to `operations.log` through `internal/oplog`; security scans use the audit log.
A typical dashboard request follows this path:
1. `ui/src/api/client.ts` sends the request.
2. A route registered in `internal/server/server.go` enters `handler_<domain>.go`.
3. The handler uses the same `internal/` domain package as the CLI. Do not duplicate core behavior in the frontend or handler.
4. Project/global differences use the server mode and existing helpers rather than a separate data model.
## Sources of Truth
- Command flags and behavior: `cmd/skillshare/*.go`.
- Target names, aliases, and default paths: `internal/config/targets.yaml`.
- Built-in audit rules: `internal/audit/rules.yaml` and related table-driven analyzers.
- Public configuration contracts: `schemas/*.json` and configuration parsing/validation code.
- Dashboard design values: `ui/src/components.css` and `ui/src/index.css`.
- Website design values: `website/src/css/custom.css` and page CSS modules.
- Build and test commands: `Makefile`, `mise.toml`, and CI workflows.
## Trace Checklist
Before changing code:
1. Search for the existing symbol, flag, or route and find its definition, callers, and tests.
2. Determine whether both global and project mode are affected.
3. If the CLI and Web API expose the same behavior, verify that they share domain logic.
4. For state changes, inspect backup, rollback, oplog, dry-run, and audit implications.
5. Load `documentation` for public contract changes, `cli-development` for implementation, and `testing` before execution.
+51
View File
@@ -0,0 +1,51 @@
# Codebase Consistency Audit
Use when asked to audit the codebase, flags, documentation, tests, targets, handler splits, oplog coverage, or Web API consistency. This topic is read-only: report findings without modifying files.
## Evidence Rules
- Give every finding a file path, line number, and direct evidence.
- Search before deciding so naming differences do not become false positives.
- Base conclusions on current code and configuration rather than stale documentation or memory.
- When the user names a dimension, inspect only that scope. Run every dimension only for a full audit.
## Dimensions
### CLI Flags
Compare flag, usage, and argument definitions in `cmd/skillshare/*.go` with `website/docs/reference/commands/*.md`:
- `UNDOCUMENTED`: present in code but absent from documentation.
- `STALE`: documented but absent from code, or behavior has changed.
- `OK`: name, mode, default, and semantics agree.
### Specifications and Tests
- For completed `specs/`, verify the implementation and testable acceptance criteria.
- For each command handler, inspect unit and integration coverage. A matching filename alone does not prove coverage.
- Use `IMPLEMENTED/MISMATCH/PENDING` and `COVERED/PARTIAL/MISSING` classifications.
### Targets and Schemas
Inspect `internal/config/targets.yaml` for names, aliases, global/project paths, and collisions, then compare configuration validation, schemas, and target tests. Never assume every target supports the same resource kinds.
### Handler Split
Find large `cmd/skillshare/*.go` files and verify that dispatch files contain only flags and mode routing while core logic, rendering, prompts, TUIs, batching, and resolution follow `cli-development` conventions. Roughly 300 lines is a review trigger, not an automatic failure.
### Oplog
Mutating commands should write the operations log; read-only commands should not write merely for consistency. Inspect success and error paths, duration, arguments, and the audit-log boundary. Determine which commands mutate state from current behavior rather than a fixed historical list.
### Web API
Compare routes in `internal/server/server.go`, `handler_*.go` files, handler tests, and `ui/src/api/client.ts`. CLI-only or API-only behavior may be intentional; inspect the product surface before reporting an issue.
## Report
Use a concise table for each dimension:
| Item | Status | Evidence | Impact |
|---|---|---|---|
End with confirmed issues, intentional differences, uncertainty, and recommended priority. Do not fix findings during an audit. If the user later requests fixes, load the appropriate implementation topic.
+94
View File
@@ -0,0 +1,94 @@
# CLI Development
Use when adding or changing Go CLI commands, flags, handlers, interactive TUIs, domain packages, or any mutating behavior.
## Before Starting
- Search for the closest existing command pattern instead of guessing APIs from memory or documentation.
- List affected command, domain, test, schema, documentation, and Web API files.
- Define acceptance criteria before changing public behavior. Ask only when ambiguity would materially change scope or interfaces.
- Use TDD: create a reproducible failing test, then write the smallest implementation that passes it.
## Command Layering
`cmd/skillshare/<command>.go` should contain only flag parsing, validation, and mode dispatch. When a handler approaches roughly 300 lines or mixes concerns, split it using existing suffixes:
| Suffix | Responsibility |
|---|---|
| `_handlers.go` | Core orchestration |
| `_project.go` | Project-mode behavior |
| `_render.go` / `_format.go` | Output rendering and formatting |
| `_prompt.go` / `_prompt_tui.go` | Decisions and prompts |
| `_tui.go` | Full-screen Bubble Tea UI |
| `_batch.go` | Batch orchestration |
| `_resolve.go` | Target/resource resolution |
| `_context.go` | Mode-specific context |
Put testable core logic in `internal/<domain>/`. Do not let the CLI, Web API, and UI implement separate versions of the same business logic.
## Global and Project Mode
Most commands route through `parseModeArgs()` for global (`-g`) or project (`-p`) mode. Before changing behavior, verify:
- whether the modes use different configuration, registry, source, or target paths;
- whether project mode needs a separate handler;
- whether their flag sets are actually the same;
- whether tests cover mode precedence, working directory, and missing configuration.
## Output and Interaction
- Reuse `internal/ui` and existing Bubble Tea components instead of introducing another prompt framework.
- Preserve dispatch order: structured JSON → TUI when interactive and allowed → empty state → plain text.
- Structured-output stdout must remain machine-readable; progress, spinners, and diagnostics must not contaminate JSON.
- When adding or changing a flag, inspect `--help`, completions, website command documentation, and tests.
- Noninteractive automation should use explicit flags. Never treat `--force` as a universal prompt bypass.
## Mutating Behavior
Operations that change configuration, sources, targets, or managed files must:
- follow existing dry-run, backup, rollback, and conflict-handling patterns;
- write an oplog entry to `operations.log` with the operation, status, duration, and necessary arguments;
- send security scan events to the audit log rather than the regular operation log;
- preserve path validation, scope checks, and ownership checks;
- use domain uninstall/remove flows for managed state rather than replacing them with filesystem deletion.
## Tests
Integration tests use `internal/testutil.NewSandbox(t)` and `RunCLI` or `RunCLIInDir`:
```go
func TestFeature_BasicCase(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
sb.CreateSkill("test-skill", map[string]string{
"SKILL.md": "---\nname: test-skill\n---\n# Content",
})
result := sb.RunCLI("command", "args...")
result.AssertSuccess()
result.AssertOutputContains("expected output")
}
```
For a bug fix, prove that the test fails before the fix. Add an E2E runbook in `ai_docs/tests/<slug>_runbook.md` for new commands, install/uninstall/sync flows, security behavior, multi-step workflows, or OS/network/permission cases that integration tests cannot cover.
All command execution and isolation rules live in `testing`. Never run the CLI or tests on the host.
## Web API
When a dashboard endpoint is needed:
1. Use existing `writeJSON` and `writeError` helpers in `internal/server/handler_<name>.go`.
2. Register the method and route in `internal/server/server.go`.
3. Handle scope explicitly through `s.IsProjectMode()` or the existing guards.
4. Add handler tests and verify UI client types and query invalidation.
5. Share an `internal/` package when the CLI and API expose the same operation; do not shell out between them.
## Completion Criteria
- The failing test now passes, along with proportionate neighboring tests.
- Handler split, dual-mode behavior, structured output, oplog, and Web API implications were reviewed.
- Public behavior changes were synchronized after loading `documentation`.
- Commands were verified inside the devcontainer using `testing` guidance.
+48
View File
@@ -0,0 +1,48 @@
# Documentation
Use when updating `README*`, `website/docs/`, command/reference/how-to/troubleshooting pages, the built-in `skills/skillshare` skill, or any code/documentation drift.
## Source First
Documentation must describe implemented behavior:
- Commands, flags, usage, and output: verify `cmd/skillshare/`.
- Targets: verify `internal/config/targets.yaml`.
- Audit rules: verify `internal/audit/rules.yaml` and analyzer code.
- Configuration fields: verify `internal/config/` and `schemas/`.
- UI behavior: verify `internal/server/`, `ui/src/api/`, and component code.
Every `--flag` claim must exist in current source or actual `--help` output. Never document planned behavior or preserve stale paths.
## Documentation Ownership
| Change | Inspect |
|---|---|
| CLI command, flag, or output | `website/docs/reference/commands/<command>.md` |
| Configuration, targets, or formats | `website/docs/reference/` and `schemas/` |
| User workflow | `website/docs/how-to/` or `getting-started/` |
| Concepts or architecture | `website/docs/understand/` |
| Error or recovery behavior | `website/docs/troubleshooting/` |
| New tool integration | `website/docs/learn/` |
| Headline feature or quickstart | `README.md` and required translations |
| Agent-facing CLI guidance | `skills/skillshare/SKILL.md` and its references |
Follow neighboring command pages for frontmatter, usage, flag tables, and examples. Use relative Markdown links. Put screenshots in `website/static/img/` using the existing `<feature>-demo.png` naming pattern.
## Built-in Skill
When public CLI behavior changes, inspect `skills/skillshare/SKILL.md` and its applicable `references/*.md`. Its frontmatter description has a consumer size limit; measure it after editing rather than assuming it still fits. The built-in skill is end-user guidance and must not contain internal development rules.
## README and Translations
`README.md` is the English source. This topic also loads the applicable `CONTRIBUTING.md` section for translation-link order and filename conventions. When English copy changes, explicitly determine whether translations must also change. Command names, versions, and installation instructions must not contradict one another across languages.
All root instructions and wiki topics are English. Preserve historical documents in their original language.
## Verification
1. Search for every changed flag, path, configuration key, and command name in source.
2. Check relative links, frontmatter, and sidebar placement.
3. Build the website inside the devcontainer to validate types and broken links.
4. For public behavior changes, inspect README, built-in skill, and changelog impact. Update release history only when explicitly requested.
5. After wiki/router changes, run `python3 scripts/ai-context.py check`.
+57
View File
@@ -0,0 +1,57 @@
# Frontend Development
Use when changing React components, pages, CSS, responsive layouts, interactions, or visual behavior in the `ui/` dashboard or `website/`.
## Shared Workflow
1. Decide whether the target is the dashboard or public website; they use different visual languages.
2. Search neighboring pages/components and existing tokens/classes before creating anything new.
3. Preserve data, loading, error, empty, keyboard, and accessibility states.
4. Build and test inside the devcontainer, then capture and inspect screenshots for visual changes.
5. Check Clean/Playful × light/dark for the dashboard, and light/dark plus affected breakpoints for the website.
## Dashboard Sources of Truth
| Concern | Source |
|---|---|
| Tokens and `ss-*` classes | `ui/src/components.css` |
| Tailwind token mapping | `ui/src/index.css` |
| Theme selection | `ui/src/context/ThemeContext.tsx` |
| Shared components | `ui/src/components/` |
| Query keys | `ui/src/lib/queryKeys.ts` |
| API client | `ui/src/api/client.ts` |
| Translation strings | `ui/src/i18n/` |
The dashboard supports Clean and Playful styles plus light, dark, and system modes. New UI must use CSS variables, token utilities, and existing `ss-*` classes. Never hardcode colors, radii, shadows, or fonts. Scope Playful-only pastels to the Playful theme.
## Dashboard Composition
- Use `ss-wrap animate-fade-in` on the page root and place `PageHeader` first.
- Prefer `ss-list` and `ss-r` for lists, `ss-note bad` for errors, and `EmptyState` for empty states.
- Use existing shared components such as `Button`, `IconButton`, `Card`, `DialogShell`, `ConfirmDialog`, `Input`, `Select`, `Checkbox`, `Pagination`, and `Tooltip`.
- Route destructive actions through `ConfirmDialog`; never use `window.confirm()`.
- Use `lucide-react` icons. Use `AgentIcon` for real agents/tools rather than emoji or generic icons.
- Icon-only controls require accessible names, and interactive targets must be at least 24 px.
- Route user-visible strings through `useT()`. Preserve existing English technical labels for status, mode, and kind values.
- Use existing TanStack Query keys, client helpers, and stale-time patterns. Invalidate the correct queries after mutations.
Do not run an unconfigured Prettier in `ui/` because it creates broad unrelated diffs. When Tailwind utilities conflict with the `ss-*` component layer, inspect the cascade before adding more complex selectors.
## Website Boundary
This topic also loads `website/AGENTS.md` for website-specific commands, structure, and deployment rules. Additional boundaries:
- Documentation chrome uses the clean treatment. The hand-drawn string-board treatment belongs only to the homepage and feature map.
- The website keeps its existing `--color-pencil` and `--color-paper` token names. Do not import the dashboard's `--ink` and `--bg` naming.
- Mermaid uses the global configuration. Keep labels short, use `<br/>` for line breaks, and verify rendered output with a screenshot.
- Load `documentation` for content changes. Verify public behavior against Go source before writing it.
## Verification
Run all package commands inside the devcontainer. Select checks according to scope:
- Dashboard: targeted Vitest, `pnpm run lint`, `pnpm run build`, and visual screenshots.
- Website: `pnpm run typecheck` and `pnpm run build`; the build validates broken links.
- API-connected UI: compare `internal/server/server.go` routes, handler tests, and client types.
Report the themes, modes, and viewport sizes inspected, plus any visual verification that could not be performed.
View File
+40
View File
@@ -0,0 +1,40 @@
# Changelog and Release
Use when writing a version changelog, release notes, version bump, tag, announcement, or full release.
## Authorization Boundary
A changelog-only request does not authorize commits, tags, pushes, publication, or version bumps. A full release request authorizes preparation and explicitly included local Git actions, but pushing or publishing still requires user confirmation. Never mix unrelated working-tree changes into staging.
## Changelog
1. Determine the range from the requested version or tags, then collect commits with `git log <previous>..<current> --no-merges`.
2. Read the newest two or three `CHANGELOG.md` entries and follow the current style.
3. Categorize user-visible features, bug fixes, performance improvements, and breaking changes. Exclude test-only, CI-only, pure refactoring, and internal implementation noise.
4. Verify every feature claim against source and never fabricate links.
5. Add the entry at the top of `CHANGELOG.md` and insert the same release entry after the frontmatter/intro separator in `website/src/pages/changelog.md`.
Version headings use `[X.Y.Z]` without a `v` prefix and include the date. Feature bullets use a bold name, an em dash, and a real usage example. Create only sections that contain content.
## Full Release
Before starting:
- Confirm the requested version and branch.
- Use `git status` to separate task-owned changes from existing work.
- Run the complete `make check` inside the devcontainer and never skip a failure.
Then:
1. Generate and review the changelog.
2. For maintainer-only release notes, follow the newest `specs/RELEASE_NOTES_*.md` and write user-facing prose to `specs/RELEASE_NOTES_<version>.md`.
3. Verify the current version location from source before bumping it; do not assume a fixed field still exists.
4. Commit or tag only when explicitly requested. Stage only task-owned files and follow recent repository release commits.
5. Draft concise GitHub release notes and a social announcement.
6. Present tests, diffs, local-only artifacts, and commit/tag state; obtain confirmation before pushing or publishing.
Release notes are local maintainer artifacts by default. Never force-add an ignored file unless explicitly requested. Never infer authorization for credentials, registry login, or external publication.
## Verification and Report
Report actual test results, whether both changelog copies match, the verified version location, commit/tag state, and external actions not performed. If the working tree is dirty, list the unrelated changes that were preserved.
+110
View File
@@ -0,0 +1,110 @@
# Build, Test, and E2E
Use when building, running the skillshare CLI, executing Go or frontend tests, reproducing bugs, using the devcontainer/ssenv, or creating and running E2E runbooks.
## Execution Boundary
The host is macOS; the project verification environment is the Linux devcontainer. Run these inside the devcontainer:
- `ss` and `skillshare` commands;
- `go build`, `go test`, `make test`, and `make check`;
- dashboard and website package scripts;
- bug reproductions and E2E runbooks.
The host may be used for source edits, `git status/diff/log`, read-only searches, `python3 scripts/ai-context.py check`, and documentation checks that do not execute the product binary.
## Devcontainer
```sh
make devc # start, initialize, and enter
make devc-up # start without opening a shell
make devc-status
make devc-down
```
For programmatic access, resolve the container first:
```sh
CONTAINER=$(docker compose -f .devcontainer/docker-compose.yml ps -q skillshare-devcontainer)
```
If it is empty, stop and ask the user to run `make devc-up` before executing product commands. The source tree is bind-mounted at `/workspace`. The `ss` wrapper automatically builds current source, so ordinary CLI verification does not need a separate `make build`.
## Narrow Verification First
Change to `/workspace` inside the container:
```sh
docker exec "$CONTAINER" bash -lc 'cd /workspace && go test ./internal/<package>/... -count=1'
docker exec "$CONTAINER" bash -lc 'cd /workspace && go test ./tests/integration -run TestName -count=1'
docker exec "$CONTAINER" bash -lc 'cd /workspace && make test-unit'
docker exec "$CONTAINER" bash -lc 'cd /workspace && make test-int'
docker exec "$CONTAINER" bash -lc 'cd /workspace && make check'
```
Start with the specific package or test that proves the change. Broaden only when new risk, failure evidence, or a release gate requires it. Base retries on new evidence and distinguish pre-existing failures from regressions.
## Stateful CLI Isolation
Use a fresh `ssenv` for tests that modify configuration or state:
```sh
ENV_NAME="task-<descriptive-id>"
docker exec "$CONTAINER" ssenv create "$ENV_NAME" --init
docker exec "$CONTAINER" ssenv enter "$ENV_NAME" -- ss status --json
```
Rules:
- Create a fresh environment for every E2E run; never reuse stale state.
- `ssenv` isolates only `HOME`. `/tmp` and other system paths are shared, so runbooks must use unique paths or clean an exact target first.
- Use `bash -c` for multi-command sequences and `cd /workspace` before Go commands.
- `--init` already performs global initialization and creates the default `rules` extra; a runbook must not assume an empty environment.
- Report the environment after execution. Delete or preserve it for debugging according to user direction; never discard requested evidence silently.
## E2E Runbooks
Runbooks live in `ai_docs/tests/*_runbook.md` and are executed by mdproof. Before creating or changing one:
1. Read `ai_docs/tests/mdproof.json` when present and `.mdproof/lessons-learned.md`.
2. Verify every command and flag against source or `--help` inside the container.
3. Use YAML-free Markdown with Scope, Environment, Steps, and Pass Criteria.
4. Give every step a `bash` block and a machine-checkable `Expected` section.
5. Prefer `--json` or `--format json` with `jq:` assertions over unstable human-readable text.
Execute a runbook with:
```sh
docker exec "$CONTAINER" /workspace/.devcontainer/ensure-mdproof.sh
docker exec "$CONTAINER" env SKILLSHARE_DEV_ALLOW_WORKSPACE_PROJECT=1 \
ssenv enter "$ENV_NAME" -- \
mdproof --report json /workspace/ai_docs/tests/<runbook>.md
```
Do not abort the whole runbook after the first failed step. Preserve every step result, then classify the failure:
- **Runbook bug:** stale flag, path, or assertion.
- **Product bug:** CLI behavior contradicts source or acceptance criteria.
- **Environment issue:** container, network, credential, or shared-path state.
## Runbook Quality Checklist
- Verify every flag against `cmd/skillshare/` or `--help`.
- Verify project-init and global-init flag sets separately.
- `registry.yaml` appears only after install/reconcile; installed resources do not belong in `config.yaml`.
- Project state uses `.skillshare/` and global state uses the configuration directory.
- Audit customization uses rule IDs, not pattern-group names.
- Expected results use actual substrings, exit codes, regular expressions, `jq:`, or snapshots rather than prose wishes.
- Prefer `jq:` for JSON assertions; `log --json` emits JSONL, not an array.
- Never append YAML with a non-idempotent bare `cat >>`; prefer the CLI or full replacement.
- Writing through a symlink changes its target. Remove the exact symlink first or use another filename when a local file is required.
- Clean exact `/tmp` targets at the beginning of a step.
- Never assume a repository name equals an installed skill name; verify with `ss list --json`.
## Frontend and Website Verification
Start the dashboard through the devcontainer `ui` command. Run website package commands according to `website/AGENTS.md`. Visual changes require inspected screenshots in addition to builds and tests. Load `frontend` for design-specific checks.
## Reporting
Report the exact commands, pass/fail status, failure location, and limitations. Starting a command is not proof of success. Never disable tests, hooks, audits, or trust prompts to obtain a pass.