mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
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:
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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": {}
|
||||
}
|
||||
Executable
+144
@@ -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))
|
||||
@@ -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 |
|
||||
@@ -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
|
||||
```
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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
@@ -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.
|
||||
Reference in New Issue
Block a user