diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 744ff49a0..6833e0df2 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -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: diff --git a/.github/workflows/website-pages.yml b/.github/workflows/website-pages.yml index 1a9cd2bf4..e75fac88b 100644 --- a/.github/workflows/website-pages.yml +++ b/.github/workflows/website-pages.yml @@ -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: diff --git a/.gitignore b/.gitignore index 589aac0b0..194fe6308 100644 --- a/.gitignore +++ b/.gitignore @@ -18,8 +18,6 @@ Thumbs.db # Test coverage.out .claude/ -/AGENTS.md -/CLAUDE.md docs/plans/ docs/superpowers/ .agents/ diff --git a/.skillshare/skills/skillshare-changelog/SKILL.md b/.skillshare/skills/skillshare-changelog/SKILL.md index 9002dad15..42c36da01 100644 --- a/.skillshare/skills/skillshare-changelog/SKILL.md +++ b/.skillshare/skills/skillshare-changelog/SKILL.md @@ -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. diff --git a/.skillshare/skills/skillshare-cli-e2e-test/SKILL.md b/.skillshare/skills/skillshare-cli-e2e-test/SKILL.md index ca2f7a8e0..41b600ba4 100644 --- a/.skillshare/skills/skillshare-cli-e2e-test/SKILL.md +++ b/.skillshare/skills/skillshare-cli-e2e-test/SKILL.md @@ -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 --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 | diff --git a/.skillshare/skills/skillshare-codebase-audit/SKILL.md b/.skillshare/skills/skillshare-codebase-audit/SKILL.md index ae25356fc..89d15347c 100644 --- a/.skillshare/skills/skillshare-codebase-audit/SKILL.md +++ b/.skillshare/skills/skillshare-codebase-audit/SKILL.md @@ -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. diff --git a/.skillshare/skills/skillshare-devcontainer/SKILL.md b/.skillshare/skills/skillshare-devcontainer/SKILL.md index 58b7a7fe1..06058db00 100644 --- a/.skillshare/skills/skillshare-devcontainer/SKILL.md +++ b/.skillshare/skills/skillshare-devcontainer/SKILL.md @@ -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 -- ` 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. diff --git a/.skillshare/skills/skillshare-implement-feature/SKILL.md b/.skillshare/skills/skillshare-implement-feature/SKILL.md index 8857f7c18..85c300f48 100644 --- a/.skillshare/skills/skillshare-implement-feature/SKILL.md +++ b/.skillshare/skills/skillshare-implement-feature/SKILL.md @@ -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. diff --git a/.skillshare/skills/skillshare-release/SKILL.md b/.skillshare/skills/skillshare-release/SKILL.md index 79be227a6..f9652c159 100644 --- a/.skillshare/skills/skillshare-release/SKILL.md +++ b/.skillshare/skills/skillshare-release/SKILL.md @@ -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. diff --git a/.skillshare/skills/skillshare-ui-website-style/SKILL.md b/.skillshare/skills/skillshare-ui-website-style/SKILL.md index 2b84663f4..758c4b559 100644 --- a/.skillshare/skills/skillshare-ui-website-style/SKILL.md +++ b/.skillshare/skills/skillshare-ui-website-style/SKILL.md @@ -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 | diff --git a/.skillshare/skills/skillshare-update-docs/SKILL.md b/.skillshare/skills/skillshare-update-docs/SKILL.md index 94cd8b8ea..f3713f4cb 100644 --- a/.skillshare/skills/skillshare-update-docs/SKILL.md +++ b/.skillshare/skills/skillshare-update-docs/SKILL.md @@ -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/.md + website/docs/reference/commands/.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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..e286a193c --- /dev/null +++ b/AGENTS.md @@ -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//` 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 # 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 +``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b079a1671..c629850d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 ` before making changes. + ```bash git clone https://github.com/runkids/skillshare.git cd skillshare diff --git a/Makefile b/Makefile index 9c97a5a93..1c8b8a780 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/docs/ai-context.json b/docs/ai-context.json new file mode 100644 index 000000000..22604b996 --- /dev/null +++ b/docs/ai-context.json @@ -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": {} +} diff --git a/scripts/ai-context.py b/scripts/ai-context.py new file mode 100755 index 000000000..1ed18d211 --- /dev/null +++ b/scripts/ai-context.py @@ -0,0 +1,144 @@ +#!/usr/bin/env python3 +"""Print only the doc sections a task needs. + +usage: ai-context.py list | [...] | 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 /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 /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'\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)) diff --git a/wiki/README.md b/wiki/README.md new file mode 100644 index 000000000..ac4cb348f --- /dev/null +++ b/wiki/README.md @@ -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 +``` + +## 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/.md`, add a row to this table. + +| File | Contents | +|---|---| +| — | None yet | diff --git a/wiki/ai-context.md b/wiki/ai-context.md new file mode 100644 index 000000000..4c6ef61bd --- /dev/null +++ b/wiki/ai-context.md @@ -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 ` 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/.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/.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 +``` diff --git a/wiki/architecture.md b/wiki/architecture.md new file mode 100644 index 000000000..32539e552 --- /dev/null +++ b/wiki/architecture.md @@ -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 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/.go` parses flags and selects global or project mode. +3. `cmd/skillshare/_*.go` composes domain operations, prompts, and output. +4. `internal//` 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_.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. diff --git a/wiki/audit.md b/wiki/audit.md new file mode 100644 index 000000000..fe7e18843 --- /dev/null +++ b/wiki/audit.md @@ -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. diff --git a/wiki/cli-development.md b/wiki/cli-development.md new file mode 100644 index 000000000..a5e249d97 --- /dev/null +++ b/wiki/cli-development.md @@ -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/.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//`. 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/_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_.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. diff --git a/wiki/documentation.md b/wiki/documentation.md new file mode 100644 index 000000000..58dd2addc --- /dev/null +++ b/wiki/documentation.md @@ -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/.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 `-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`. diff --git a/wiki/frontend.md b/wiki/frontend.md new file mode 100644 index 000000000..bb26a1498 --- /dev/null +++ b/wiki/frontend.md @@ -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 `
` 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. diff --git a/wiki/history/.gitkeep b/wiki/history/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/wiki/release.md b/wiki/release.md new file mode 100644 index 000000000..ca5408190 --- /dev/null +++ b/wiki/release.md @@ -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 .. --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_.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. diff --git a/wiki/testing.md b/wiki/testing.md new file mode 100644 index 000000000..9116d392f --- /dev/null +++ b/wiki/testing.md @@ -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//... -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-" +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/.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.