diff --git a/.gitignore b/.gitignore index bfbe1ed40..624e377b4 100644 --- a/.gitignore +++ b/.gitignore @@ -20,7 +20,11 @@ coverage.out AGENTS.md CLAUDE.md docs/plans/ -.skillshare/ +.agents/ +.skillshare/* +!.skillshare/skills/ +!.skillshare/config.yaml +!.skillshare/.gitignore /specs/ .pnpm-store/ .feature-radar/ diff --git a/.skillignore b/.skillignore new file mode 100644 index 000000000..1d1bd29a9 --- /dev/null +++ b/.skillignore @@ -0,0 +1 @@ +.skillshare/skills/* diff --git a/.skillshare/.gitignore b/.skillshare/.gitignore new file mode 100644 index 000000000..66be43139 --- /dev/null +++ b/.skillshare/.gitignore @@ -0,0 +1,3 @@ +# BEGIN SKILLSHARE MANAGED - DO NOT EDIT +logs/ +# END SKILLSHARE MANAGED diff --git a/.skillshare/config.yaml b/.skillshare/config.yaml new file mode 100644 index 000000000..8741bbed2 --- /dev/null +++ b/.skillshare/config.yaml @@ -0,0 +1,6 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/project-config.schema.json +targets: + - universal + - claude +audit: + block_threshold: CRITICAL diff --git a/.skillshare/skills/changelog/SKILL.md b/.skillshare/skills/changelog/SKILL.md new file mode 100644 index 000000000..2ec482bc5 --- /dev/null +++ b/.skillshare/skills/changelog/SKILL.md @@ -0,0 +1,108 @@ +--- +name: skillshare-changelog +description: Generate CHANGELOG.md entry from recent commits in conventional format +argument-hint: "[tag-version]" +targets: [claude, codex] +--- + +Generate a CHANGELOG.md entry for a release. $ARGUMENTS specifies the tag version (e.g., `v0.16.0`) or omit to auto-detect via `git describe --tags --abbrev=0`. + +**Scope**: This skill only updates `CHANGELOG.md`. It does NOT write code (use `implement-feature`) or update docs (use `update-docs`). + +## Workflow + +### Step 1: Determine Version Range + +```bash +# Auto-detect latest tag +LATEST_TAG=$(git describe --tags --abbrev=0) +# Find previous tag +PREV_TAG=$(git describe --tags --abbrev=0 "${LATEST_TAG}^") + +echo "Generating changelog: $PREV_TAG → $LATEST_TAG" +``` + +### Step 2: Collect Commits + +```bash +git log "${PREV_TAG}..${LATEST_TAG}" --oneline --no-merges +``` + +### Step 3: Categorize Changes + +Group commits by conventional commit type: + +| Prefix | Category | +|--------|----------| +| `feat` | New Features | +| `fix` | Bug Fixes | +| `refactor` | Refactoring | +| `docs` | Documentation | +| `perf` | Performance | +| `test` | Tests | +| `chore` | Maintenance | + +### Step 4: Write User-Facing Entry + +Write from the **user's perspective**. Only include changes users will notice or care about. + +**Include**: +- New features with usage examples (CLI commands) +- Bug fixes that affected user-visible behavior +- Breaking changes (renames, removed flags, scope changes) +- Performance improvements users would notice + +**Exclude**: +- Internal test changes (smoke tests, test refactoring) +- Implementation details (error propagation, internal structs) +- Dev toolchain changes (Makefile cleanup, CI tweaks) +- Pure documentation adjustments + +**Wording guidelines**: +- Don't use "first-class", "recommended" for non-default options +- Be factual: "Added X" / "Fixed Y" / "Renamed A to B" +- Include CLI example when introducing a new feature + +### Step 5: Update CHANGELOG.md + +Read existing `CHANGELOG.md` and insert new entry at the top, after the header. + +Format: +```markdown +## [vX.Y.Z] - YYYY-MM-DD + +### New Features +- **Feature name**: Brief description (`skillshare command --flag`) + +### Bug Fixes +- Fixed issue where X happened when Y + +### Breaking Changes +- Renamed `old-name` to `new-name` +``` + +### Step 6: RELEASE_NOTES (Maintainer Only) + +**IMPORTANT**: `specs/RELEASE_NOTES_.md` is only generated when the user is the project maintainer (runkids). Contributors should skip this step. + +Check if running as maintainer: +```bash +git config user.name # Should match maintainer identity +``` + +If maintainer: +- Generate `specs/RELEASE_NOTES_${LATEST_TAG}.md` with detailed release notes +- Include migration guide if breaking changes exist + +If not maintainer: +- Skip RELEASE_NOTES generation +- Only update CHANGELOG.md + +## 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 +- **RELEASE_NOTES = maintainer only** — contributors only update CHANGELOG.md diff --git a/.skillshare/skills/cli-e2e-test/SKILL.md b/.skillshare/skills/cli-e2e-test/SKILL.md new file mode 100644 index 000000000..0deb94a84 --- /dev/null +++ b/.skillshare/skills/cli-e2e-test/SKILL.md @@ -0,0 +1,157 @@ +--- +name: skillshare-cli-e2e-test +description: Run isolated E2E tests in devcontainer from ai_docs/tests runbooks +argument-hint: "[runbook-name | new]" +targets: [claude, codex] +--- + +Run isolated E2E tests in devcontainer. $ARGUMENTS specifies runbook name or "new". + +## Flow + +### Phase 0: Environment Check + +1. Confirm devcontainer is running: + ```bash + docker compose -f .devcontainer/docker-compose.yml ps --format json + ``` + - If not running → prompt user: `docker compose -f .devcontainer/docker-compose.yml up -d` + - Wait until container is running + +2. Confirm Linux binary is available: + ```bash + docker exec skillshare_devcontainer-skillshare-devcontainer-1 bash -c \ + '/workspace/.devcontainer/ensure-skillshare-linux-binary.sh && ss version' + ``` + +### Phase 1: Detect Scope + +1. Read all `*_runbook.md` files under `ai_docs/tests/` to list available runbooks +2. Read `git diff HEAD~3 --stat` to identify recent code changes +3. Match changes to relevant runbooks (compare runbook Scope sections with changed file paths) + +### Phase 2: Select Tests + +Prompt user (via AskUserQuestion): + +- **Option A**: Run existing runbook (list all available + mark those related to recent changes) +- **Option B**: Auto-generate new test script based on recent changes +- **Option C**: If $ARGUMENTS specifies a runbook, skip to Phase 3 + +### Phase 3: Prepare & Execute + +#### Running existing runbook: + +1. Read the selected runbook `.md` file +2. Create isolated environment and execute step by step: + ```bash + # Container name + CONTAINER="skillshare_devcontainer-skillshare-devcontainer-1" + ENV_NAME="e2e-$(date +%Y%m%d-%H%M%S)" + + # Create isolated environment + docker exec $CONTAINER ssenv create "$ENV_NAME" + + # Isolated HOME has no target dirs by default — create them before init + docker exec $CONTAINER ssenv enter "$ENV_NAME" -- mkdir -p ~/.claude ~/.codex + + # Execute each step from runbook (ssenv enter isolates HOME) + docker exec $CONTAINER ssenv enter "$ENV_NAME" -- + ``` +3. After each step, verify conditions in the Expected block +4. Mark each step PASS / FAIL + +#### Generating new script: + +1. Read `git diff HEAD~3` to find changed files in `cmd/skillshare/` or `internal/` +2. Read changed files to understand new/modified functionality +3. Generate new runbook to `ai_docs/tests/_runbook.md`, following existing conventions: + - YAML-free, pure Markdown + - Has Scope, Environment, Steps (each with bash + Expected), Pass Criteria +4. Then execute the new runbook (same flow as above) + +### Phase 4: Cleanup & Report + +1. Clean up isolated environment: + ```bash + docker exec $CONTAINER ssenv delete "$ENV_NAME" --force + ``` + +2. Output summary: + ``` + ── E2E Test Report ── + + Runbook: {runbook name} + Env: {ENV_NAME} + Duration: {time} + + Step 1: {description} PASS + Step 2: {description} PASS + Step 3: {description} FAIL ← {error detail} + ... + + Result: {N}/{total} passed + ``` + +3. If any FAIL → analyze cause, provide fix suggestions + +## 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 +- **Verify every step** — never skip Expected checks +- **Don't abort on failure** — record FAIL, continue to next step, summarize at end +- **Always clean up** — Phase 4 must delete the ssenv environment +- **`ss` = `skillshare`** — same binary in runbooks +- **`~` = ssenv-isolated HOME** — `ssenv enter` auto-sets `HOME` +- **Create target dirs first** — isolated HOME has no `.claude`/`.codex` etc.; `mkdir -p` before `init` + +## ssenv Quick Reference + +| Command | Purpose | +|---------|---------| +| `sshelp` | Show shortcuts and usage | +| `ssls` | List isolated environments | +| `ssnew ` | Create + enter isolated shell (interactive) | +| `ssuse ` | Enter existing isolated shell (interactive) | +| `ssback` | Leave isolated context | +| `ssenv enter -- ` | Run single command in isolation (automation) | + +- For interactive debugging: `ssnew ` then `exit` when done +- For deterministic automation: prefer `ssenv enter -- ` one-liners + +## Test Command Policy + +When running Go tests inside devcontainer (not via runbook): + +```bash +go build -o bin/skillshare ./cmd/skillshare +SKILLSHARE_TEST_BINARY="$PWD/bin/skillshare" go test ./tests/integration -count=1 +go test ./... +``` + +Always run in devcontainer unless there is a documented exception. + +## Container Command Templates + +```bash +# Single command +docker exec $CONTAINER ssenv enter "$ENV_NAME" -- ss status + +# Multi-line compound command (use bash -c) +docker exec $CONTAINER ssenv enter "$ENV_NAME" -- bash -c ' + ss init --no-copy --all-targets --no-git --no-skill + ss status +' + +# Check files (HOME is set to isolated path by ssenv) +docker exec $CONTAINER ssenv enter "$ENV_NAME" -- bash -c ' + cat ~/.config/skillshare/config.yaml +' + +# With environment variables +docker exec $CONTAINER ssenv enter "$ENV_NAME" -- bash -c ' + TARGET=~/.claude/skills + ls -la "$TARGET" +' +``` diff --git a/.skillshare/skills/codebase-audit/SKILL.md b/.skillshare/skills/codebase-audit/SKILL.md new file mode 100644 index 000000000..4e9380f76 --- /dev/null +++ b/.skillshare/skills/codebase-audit/SKILL.md @@ -0,0 +1,110 @@ +--- +name: skillshare-codebase-audit +description: Cross-validate CLI flags, docs, tests, and targets for consistency across the codebase +targets: [claude, codex] +--- + +Read-only consistency audit across the skillshare codebase. $ARGUMENTS specifies focus area (e.g., "flags", "tests", "targets") or omit for full audit. + +**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. + +## 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`. + +```bash +# Find all flags in Go source +grep -rn 'flag\.\(String\|Bool\|Int\)' cmd/skillshare/ +grep -rn 'Args\|Usage' cmd/skillshare/ +``` + +Report: +- **UNDOCUMENTED**: Flag exists in code but not in docs +- **STALE**: Flag documented but not found in code +- **OK**: Flag matches between code and docs + +### 2. Spec vs Code + +For each spec in `specs/` marked as completed/done: +- Verify the described feature exists in source code +- Check that the spec's acceptance criteria are testable + +Report: +- **IMPLEMENTED**: Spec complete, code exists +- **MISMATCH**: Spec says done but code missing or partial +- **PENDING**: Spec not yet marked complete (informational) + +### 3. Test Coverage + +For each command handler in `cmd/skillshare/.go`: +- Check if `tests/integration/_test.go` exists +- Check if key behaviors have test cases + +```bash +# List all command handlers +ls cmd/skillshare/*.go | grep -v '_test.go\|main.go\|helpers.go\|mode.go' + +# List all integration tests +ls tests/integration/*_test.go +``` + +Report: +- **COVERED**: Command has integration test file with test cases +- **PARTIAL**: Test file exists but missing key scenarios +- **MISSING**: No integration test for this command + +### 4. Target Audit + +Verify `internal/config/targets.yaml` entries: +- Each target has both `global_path` and `project_path` +- Aliases are consistent +- No duplicate entries + +Report: +- **OK**: Target entry complete and valid +- **INCOMPLETE**: Missing required fields +- **DUPLICATE**: Name or alias collision + +## Output Format + +``` +== Skillshare Codebase Audit == + +### CLI Flags (N issues) +| Command | Flag | Status | +|-----------|-------------|--------------| +| install | --force | OK | +| install | --into | UNDOCUMENTED | + +### Specs (N issues) +| Spec File | Status | +|----------------------|-------------| +| copy-sync-mode.md | IMPLEMENTED | +| some-feature.md | MISMATCH | + +### Test Coverage (N issues) +| Command | Status | Notes | +|-----------|---------|--------------------| +| sync | COVERED | | +| audit | PARTIAL | missing edge cases | +| target | MISSING | | + +### Targets (N issues) +| Target | Status | Notes | +|-----------|------------|---------------| +| claude | OK | | +| newagent | INCOMPLETE | no project_path | + +== Summary: X OK / Y issues found == +``` + +## 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 diff --git a/.skillshare/skills/implement-feature/SKILL.md b/.skillshare/skills/implement-feature/SKILL.md new file mode 100644 index 000000000..d5288a19c --- /dev/null +++ b/.skillshare/skills/implement-feature/SKILL.md @@ -0,0 +1,166 @@ +--- +name: skillshare-implement-feature +description: Implement a feature from a spec file or description using TDD workflow +argument-hint: "[spec-file-path | feature description]" +targets: [claude, codex] +--- + +Implement a feature following TDD workflow. $ARGUMENTS is a spec file path (e.g., `specs/my-feature.md`) or a plain-text feature description. + +**Scope**: This skill writes Go code and tests. It does NOT update website docs (use `update-docs` after) or CHANGELOG (use `changelog` after). + +## Workflow + +### Step 1: Understand Requirements + +If $ARGUMENTS is a file path: +1. Read the spec file +2. Extract acceptance criteria and edge cases +3. Identify affected packages + +If $ARGUMENTS is a description: +1. Search existing code for related functionality +2. Identify the right package to extend +3. Confirm scope with user before proceeding + +### Step 2: Identify Affected Files + +List all files that will be created or modified: + +```bash +# Typical pattern for a new command +cmd/skillshare/.go # Command handler +cmd/skillshare/_project.go # Project-mode handler (if dual-mode) +internal//.go # Core logic +tests/integration/_test.go # Integration test +``` + +Display the file list and continue. If scope is unclear, ask the user. + +### Step 3: Write Failing Tests First (RED) + +Write integration tests using `testutil.Sandbox`: + +```go +func TestFeature_BasicCase(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + // Setup + sb.CreateSkill("test-skill", map[string]string{ + "SKILL.md": "---\nname: test-skill\n---\n# Content", + }) + + // Act + result := sb.RunCLI("command", "args...") + + // Assert + result.AssertSuccess() + result.AssertOutputContains("expected output") +} +``` + +Verify tests fail: +```bash +make test-int +# or run specific test: +go test ./tests/integration -run TestFeature_BasicCase +``` + +### Step 4: Implement (GREEN) + +Write minimal code to make tests pass: + +1. Follow existing patterns in `cmd/skillshare/` and `internal/` +2. Use `internal/ui` for terminal output (colors, spinners, boxes) +3. Add oplog instrumentation for mutating commands: + ```go + start := time.Now() + // ... do work ... + e := oplog.NewEntry("command-name", statusFromErr(err), time.Since(start)) + oplog.Write(configPath, oplog.OpsFile, e) + ``` +4. Register command in `main.go` commands map if new command + +Verify tests pass: +```bash +make test-int +``` + +### Step 5: Refactor and Verify + +1. Clean up code while keeping tests green +2. Run full quality check: + ```bash + make check # fmt-check + lint + test + ``` +3. Fix any formatting or lint issues + +### Step 6: E2E Runbook (Major Features Only) + +If the feature meets **any** of these criteria, generate an E2E runbook: +- New command or subcommand +- Changes to install/uninstall/sync flow +- Security-related (audit, hash verification, rollback) +- Multi-step user workflow (init → install → sync → verify) +- Edge cases that integration tests alone can't cover (Docker, network, file permissions) + +Generate `ai_docs/tests/_runbook.md` following the existing convention: + +```markdown +# CLI E2E Runbook: + +<One-line summary of what this validates.> + +**Origin**: <version> — <why this runbook exists> + +## Scope + +- <bullet list of behaviors being validated> + +## Environment + +Run inside devcontainer with `ssenv` isolation. + +## Steps + +### 1. Setup: <description> + +\```bash +<commands> +\``` + +**Expected**: <what should happen> + +### 2. <Action>: <description> +... + +## Pass Criteria + +- All steps marked PASS +- <additional criteria> +``` + +Key conventions: +- YAML-free, pure Markdown +- Each step has `bash` block + `Expected` block +- `ss` = `skillshare`, `~` = ssenv-isolated HOME +- Runbook can be executed by the `cli-e2e-test` skill + +If the feature does not meet the criteria above, skip this step. + +### Step 7: Stage and Report + +1. List all created/modified files +2. Confirm each acceptance criterion is met with test evidence +3. Remind user to run `update-docs` if the feature affects CLI flags or user-visible behavior + +## 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 diff --git a/.skillshare/skills/update-docs/SKILL.md b/.skillshare/skills/update-docs/SKILL.md new file mode 100644 index 000000000..5b8d31afc --- /dev/null +++ b/.skillshare/skills/update-docs/SKILL.md @@ -0,0 +1,100 @@ +--- +name: skillshare-update-docs +description: Update website docs to match recent code changes, cross-validating every flag against source +argument-hint: "[command-name | commit-range]" +targets: [claude, codex] +--- + +Sync website documentation with recent code changes. $ARGUMENTS specifies scope: a command name (e.g., `install`), commit range, or omit to auto-detect from `git diff HEAD~1`. + +**Scope**: This skill only updates `website/docs/`. It does NOT write Go code (use `implement-feature`) or CHANGELOG (use `changelog`). + +## Workflow + +### Step 1: Detect Changes + +```bash +# Auto-detect recently changed commands +git diff HEAD~1 --stat -- cmd/skillshare/ internal/ +``` + +Map changed files to affected documentation: +- `cmd/skillshare/install.go` → `website/docs/commands/install.md` +- `internal/audit/` → `website/docs/commands/audit.md` +- `internal/config/targets.yaml` → `website/docs/reference/supported-targets.md` + +### Step 2: Cross-Validate Flags + +For each affected command: + +1. Read the Go source to extract actual flags and behavior: + ```bash + grep -n 'flag\.\|Usage\|Args' cmd/skillshare/<cmd>.go + ``` + +2. Read the corresponding doc page: + ``` + website/docs/commands/<cmd>.md + ``` + +3. Compare and fix: + - **New flags** in code → add to docs with usage example + - **Removed flags** from code → remove from docs + - **Changed behavior** → update description + - **Every `--flag` in docs** must have a matching `grep` hit in source + +### Step 3: Update Documentation + +Apply changes following existing doc conventions: +- Match heading structure of neighboring doc pages +- Include CLI examples with expected output +- Keep flag tables consistent in format + +### Step 4: Check Built-in Skill + +If changes affect user-visible CLI behavior: + +1. Read `skills/skillshare/SKILL.md` +2. Check if the built-in skill description needs updating +3. Verify description stays under 1024 characters (CodeX limit) + +### Step 5: Check README + +Review `README.md` for sections that may need updates: +- Recent Updates section +- Feature list +- Usage examples + +### Step 6: Build Verification + +```bash +cd website && npm run build +``` + +Confirm no broken links or build errors. + +### Step 7: Report + +List all changes made with rationale: +``` +== Documentation Updates == + +Modified: + website/docs/commands/install.md + - Added --into flag documentation + - Updated install examples + + skills/skillshare/SKILL.md + - Added --into to feature list (desc: 987/1024 chars) + +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 diff --git a/ai_docs/tests/README.md b/ai_docs/tests/README.md deleted file mode 100644 index cd2d97419..000000000 --- a/ai_docs/tests/README.md +++ /dev/null @@ -1,67 +0,0 @@ -# AI Testing Guide (Devcontainer + ssenv) - -This guide is for AI agents running tests/verification in this repository. - -## Non-negotiable rules - -1. Always run tests inside devcontainer. -2. Always use an isolated `ssenv` environment for runtime verification. -3. Never rely on host `HOME` for CLI behavior checks. -4. End each run with explicit cleanup (`ssenv delete <name> --force`). - -## Required bootstrap - -From repository root: - -```bash -docker compose -f .devcontainer/docker-compose.yml up -d -docker exec -it skillshare_devcontainer-skillshare-devcontainer-1 bash -``` - -Inside container: - -```bash -/workspace/.devcontainer/ensure-skillshare-linux-binary.sh -sshelp -``` - -## Standard AI workflow - -Use this pattern for every verification run: - -```bash -ENV_NAME="ai-test-$(date +%Y%m%d-%H%M%S)" -ssenv create "$ENV_NAME" -ssenv enter "$ENV_NAME" -- ss init --no-copy --no-targets --no-git --no-skill -ssenv enter "$ENV_NAME" -- ss doctor -ssenv delete "$ENV_NAME" --force -``` - -Notes: - -- For interactive debugging, use `ssuse <env>` or `ssnew <env>`, then `exit` when done. -- For deterministic automation, prefer `ssenv enter <env> -- <command>` one-liners. -- If `ssenv delete <active-env> --force` is called from an eval-switched shell, it auto-returns to `/workspace`. - -## Test command policy - -Run in devcontainer unless there is a documented exception. - -```bash -go build -o bin/skillshare ./cmd/skillshare -SKILLSHARE_TEST_BINARY="$PWD/bin/skillshare" go test ./tests/integration -count=1 -go test ./... -``` - -## Quick commands reference - -- `sshelp`: show shortcuts and usage. -- `ssls`: list isolated environments. -- `ssnew <name>`: create + enter isolated shell. -- `ssuse <name>`: enter existing isolated shell. -- `ssback`: leave isolated context helper. -- `ssenv shortcuts`: print the same shortcuts reference. - -## Related runbook - -- `ai_docs/tests/first_use_cli_e2e_runbook.md`