diff --git a/.skillshare/skills/skillshare-codebase-audit/SKILL.md b/.skillshare/skills/skillshare-codebase-audit/SKILL.md deleted file mode 100644 index 4f3e52a1d..000000000 --- a/.skillshare/skills/skillshare-codebase-audit/SKILL.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -name: skillshare-codebase-audit -description: >- - Cross-validate CLI flags, docs, tests, and targets for consistency across the - codebase. Use this skill whenever the user asks to: audit the codebase, check - for consistency issues, find undocumented flags, verify test coverage, validate - targets.yaml, check handler split conventions, or verify oplog instrumentation. - This is a read-only audit — it reports issues but never modifies files. Use - after large refactors, before releases, or whenever you suspect docs/code/tests - have drifted out of sync. -metadata: - targets: [claude, universal] ---- - -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. - -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 every dimension below 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/reference/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. 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 - -### 3. Target Audit - -Verify `internal/config/targets.yaml` entries: -- Each target has `skills.global` and `skills.project` -- Aliases are consistent -- No duplicate entries - -Report: -- **OK**: Target entry complete and valid -- **INCOMPLETE**: Missing required fields -- **DUPLICATE**: Name or alias collision - -### 4. Handler Split Audit - -For commands with >300 lines in `cmd/skillshare/.go`, verify the handler split convention is followed: - -```bash -# Find large command files -wc -l cmd/skillshare/*.go | sort -rn | head -20 -``` - -Check that large commands are properly split: - -| Suffix | Expected for large commands | -|--------|---------------------------| -| `_handlers.go` | Core logic extracted | -| `_render.go` | Output rendering separated | -| `_tui.go` | TUI components isolated | - -Report: -- **SPLIT**: Large command properly follows handler split convention -- **MONOLITH**: >300 lines without split (should be refactored) -- **N/A**: Small command, no split needed - -### 5. Oplog Coverage - -Verify all mutating commands have oplog instrumentation: - -```bash -# Find commands that modify state -grep -rn 'func handle\|func cmd' cmd/skillshare/*.go - -# Check for oplog.Write calls -grep -rn 'oplog.Write' cmd/skillshare/ -``` - -Mutating commands (install, uninstall, sync, update, init, collect, backup, restore, trash) should all write to oplog. Read-only commands (list, status, check, search, audit, log, version) should not. - -Report: -- **INSTRUMENTED**: Mutating command has oplog.Write -- **MISSING**: Mutating command lacks oplog instrumentation -- **N/A**: Read-only command (no oplog expected) - -### 6. Web API Consistency - -Verify `internal/server/handler_*.go` routes match CLI commands: - -```bash -# List all handler files -ls internal/server/handler_*.go | grep -v _test.go - -# Check route registration in server.go -grep -n 'HandleFunc\|Handle(' internal/server/server.go -``` - -Report: -- **SYNCED**: CLI command has corresponding API handler -- **CLI-ONLY**: Command exists in CLI but not in Web API (may be intentional) -- **API-ONLY**: API handler without CLI counterpart (unusual) - -## Output Format - -``` -== Skillshare Codebase Audit == - -### CLI Flags (N issues) -| Command | Flag | Status | -|-----------|-------------|--------------| -| install | --force | OK | -| install | --into | UNDOCUMENTED | - -### 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 skills.project | - -### Handler Split (N issues) -| Command | Lines | Status | Notes | -|-----------|-------|-----------|--------------------| -| install | 450 | SPLIT | 6 sub-files | -| audit | 320 | MONOLITH | should split render | -| status | 80 | N/A | | - -### Oplog (N issues) -| Command | Mutating? | Status | -|-----------|-----------|---------------| -| install | Yes | INSTRUMENTED | -| trash | Yes | MISSING | -| list | No | N/A | - -### Web API (N issues) -| Command | CLI | API | Status | -|-----------|-----|-----|----------| -| install | Yes | Yes | SYNCED | -| diff | Yes | No | CLI-ONLY | - -== Summary: X OK / Y issues found == -``` - -## Rules - -Apply the `audit` topic and keep this workflow read-only. diff --git a/website/docs/learn/with-ai-coding-agents.md b/website/docs/learn/with-ai-coding-agents.md index a39ce9366..8f6ae8c04 100644 --- a/website/docs/learn/with-ai-coding-agents.md +++ b/website/docs/learn/with-ai-coding-agents.md @@ -25,19 +25,19 @@ Your AI agent now has access to specialized skills for working on this codebase. | Skill | What it does | |-------|-------------| -| `implement-feature` | Implement a feature from a spec file or description using TDD workflow | -| `update-docs` | Update website docs to match recent code changes, cross-validating every flag against source | -| `codebase-audit` | Cross-validate CLI flags, docs, tests, and targets for consistency across the codebase | -| `cli-e2e-test` | Run isolated E2E tests in devcontainer from runbooks | -| `changelog` | Generate a CHANGELOG.md entry from recent commits in conventional format | +| `skillshare-implement-feature` | Implement a feature from a spec file or description using TDD workflow | +| `skillshare-update-docs` | Update website docs to match recent code changes, cross-validating every flag against source | +| `skillshare-code-review` | Review a change in parallel passes (correctness, repo rules, spec, consumers, cleanup) and verify each finding | +| `skillshare-cli-e2e-test` | Run isolated E2E tests in devcontainer from runbooks | +| `skillshare-changelog` | Generate a CHANGELOG.md entry from recent commits in conventional format | ## Typical Workflow -1. **Start a feature** — ask your agent to use `implement-feature` with a spec -2. **Update docs** — after code changes, invoke `update-docs` to sync website docs -3. **Audit consistency** — run `codebase-audit` to catch flag/doc mismatches -4. **Run E2E tests** — use `cli-e2e-test` to verify in a sandbox -5. **Write changelog** — invoke `changelog` before release +1. **Start a feature** — ask your agent to use `skillshare-implement-feature` with a spec +2. **Update docs** — after code changes, invoke `skillshare-update-docs` to sync website docs +3. **Review the change** — run `skillshare-code-review` before committing or opening a PR +4. **Run E2E tests** — use `skillshare-cli-e2e-test` to verify in a sandbox +5. **Write changelog** — invoke `skillshare-changelog` before release ## What's Next? diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md index 0c319ee95..95175e426 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md @@ -26,19 +26,19 @@ skillshare sync -p | Skill | 何をするか | |-------|-------------| -| `implement-feature` | TDD ワークフローを使い、spec ファイルまたは説明から機能を実装する | -| `update-docs` | すべてのフラグを Source と照合しながら、Web サイトのドキュメントを最近のコード変更に合わせて更新する | -| `codebase-audit` | CLI フラグ、ドキュメント、テスト、Target をコードベース全体で相互検証する | -| `cli-e2e-test` | runbook から devcontainer 内で隔離された E2E テストを実行する | -| `changelog` | 最近のコミットから conventional な形式で CHANGELOG.md のエントリを生成する | +| `skillshare-implement-feature` | TDD ワークフローを使い、spec ファイルまたは説明から機能を実装する | +| `skillshare-update-docs` | すべてのフラグを Source と照合しながら、Web サイトのドキュメントを最近のコード変更に合わせて更新する | +| `skillshare-code-review` | 変更を並列パス(正確性、リポジトリのルール、仕様、利用箇所、クリーンアップ)でレビューし、各指摘を検証する | +| `skillshare-cli-e2e-test` | runbook から devcontainer 内で隔離された E2E テストを実行する | +| `skillshare-changelog` | 最近のコミットから conventional な形式で CHANGELOG.md のエントリを生成する | ## 典型的なワークフロー -1. **機能を始める** — Agent に spec を使って `implement-feature` を使うよう依頼する -2. **ドキュメントを更新する** — コード変更後、`update-docs` を呼び出して Web サイトのドキュメントを Sync する -3. **一貫性を監査する** — フラグ/ドキュメントの不一致を捕捉するために `codebase-audit` を実行する -4. **E2E テストを実行する** — サンドボックスで検証するために `cli-e2e-test` を使う -5. **changelog を書く** — リリース前に `changelog` を呼び出す +1. **機能を始める** — Agent に spec を使って `skillshare-implement-feature` を使うよう依頼する +2. **ドキュメントを更新する** — コード変更後、`skillshare-update-docs` を呼び出して Web サイトのドキュメントを Sync する +3. **変更をレビューする** — コミットや PR の前に `skillshare-code-review` を実行する +4. **E2E テストを実行する** — サンドボックスで検証するために `skillshare-cli-e2e-test` を使う +5. **changelog を書く** — リリース前に `skillshare-changelog` を呼び出す ## 次のステップ diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md index 03185cf01..903f76444 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md @@ -24,19 +24,19 @@ skillshare sync -p | Skill | 하는 일 | |-------|-------------| -| `implement-feature` | TDD 워크플로를 사용해 spec 파일이나 설명으로부터 기능을 구현합니다 | -| `update-docs` | 모든 플래그를 소스와 교차 검증하며 최근 코드 변경 사항에 맞춰 웹사이트 문서를 업데이트합니다 | -| `codebase-audit` | 코드베이스 전반에서 CLI 플래그, 문서, 테스트, Target의 일관성을 교차 검증합니다 | -| `cli-e2e-test` | Runbook을 기반으로 devcontainer에서 격리된 E2E 테스트를 실행합니다 | -| `changelog` | 최근 커밋으로부터 conventional 형식의 CHANGELOG.md 항목을 생성합니다 | +| `skillshare-implement-feature` | TDD 워크플로를 사용해 spec 파일이나 설명으로부터 기능을 구현합니다 | +| `skillshare-update-docs` | 모든 플래그를 소스와 교차 검증하며 최근 코드 변경 사항에 맞춰 웹사이트 문서를 업데이트합니다 | +| `skillshare-code-review` | 변경 사항을 병렬 패스(정확성, 저장소 규칙, 사양, 사용처, 정리)로 리뷰하고 각 지적을 검증합니다 | +| `skillshare-cli-e2e-test` | Runbook을 기반으로 devcontainer에서 격리된 E2E 테스트를 실행합니다 | +| `skillshare-changelog` | 최근 커밋으로부터 conventional 형식의 CHANGELOG.md 항목을 생성합니다 | ## 일반적인 워크플로 -1. **기능 시작** — agent에게 spec과 함께 `implement-feature`를 사용하도록 요청하세요 -2. **문서 업데이트** — 코드 변경 후 `update-docs`를 호출해 웹사이트 문서를 동기화하세요 -3. **일관성 감사** — `codebase-audit`를 실행해 플래그/문서 불일치를 잡아내세요 -4. **E2E 테스트 실행** — `cli-e2e-test`를 사용해 샌드박스에서 검증하세요 -5. **Changelog 작성** — 릴리스 전에 `changelog`를 호출하세요 +1. **기능 시작** — agent에게 spec과 함께 `skillshare-implement-feature`를 사용하도록 요청하세요 +2. **문서 업데이트** — 코드 변경 후 `skillshare-update-docs`를 호출해 웹사이트 문서를 동기화하세요 +3. **변경 사항 리뷰** — 커밋하거나 PR을 열기 전에 `skillshare-code-review`를 실행하세요 +4. **E2E 테스트 실행** — `skillshare-cli-e2e-test`를 사용해 샌드박스에서 검증하세요 +5. **Changelog 작성** — 릴리스 전에 `skillshare-changelog`를 호출하세요 ## 다음 단계는? diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md index 7a71de614..24cc087b0 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md @@ -25,19 +25,19 @@ skillshare sync -p | Skill | 作用 | |-------|-------------| -| `implement-feature` | 使用 TDD 工作流,根据 spec 文件或描述实现功能 | -| `update-docs` | 更新网站文档以匹配最近的代码变更,并将每个 flag 与源码交叉验证 | -| `codebase-audit` | 交叉验证 CLI flags、文档、测试与 targets,检查整个代码库的一致性 | -| `cli-e2e-test` | 依据 runbooks,在 devcontainer 中运行隔离的 E2E 测试 | -| `changelog` | 以约定式格式,根据最近的提交生成 CHANGELOG.md 条目 | +| `skillshare-implement-feature` | 使用 TDD 工作流,根据 spec 文件或描述实现功能 | +| `skillshare-update-docs` | 更新网站文档以匹配最近的代码变更,并将每个 flag 与源码交叉验证 | +| `skillshare-code-review` | 以并行检查(正确性、仓库规则、规格、使用处、清理)审查变更,并逐条验证发现的问题 | +| `skillshare-cli-e2e-test` | 依据 runbooks,在 devcontainer 中运行隔离的 E2E 测试 | +| `skillshare-changelog` | 以约定式格式,根据最近的提交生成 CHANGELOG.md 条目 | ## 典型工作流 -1. **开始一个功能** — 让你的 agent 使用 `implement-feature` 搭配一份 spec -2. **更新文档** — 代码变更后,调用 `update-docs` 来同步网站文档 -3. **审计一致性** — 运行 `codebase-audit` 以捕捉 flag 与文档不一致的地方 -4. **运行 E2E 测试** — 使用 `cli-e2e-test` 在沙盒中进行验证 -5. **撰写 changelog** — 发布前调用 `changelog` +1. **开始一个功能** — 让你的 agent 使用 `skillshare-implement-feature` 搭配一份 spec +2. **更新文档** — 代码变更后,调用 `skillshare-update-docs` 来同步网站文档 +3. **审查变更** — 提交或开 PR 前运行 `skillshare-code-review` +4. **运行 E2E 测试** — 使用 `skillshare-cli-e2e-test` 在沙盒中进行验证 +5. **撰写 changelog** — 发布前调用 `skillshare-changelog` ## 接下来? diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md index f7d67bfaa..d7f951a76 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/learn/with-ai-coding-agents.md @@ -25,19 +25,19 @@ skillshare sync -p | Skill | 功能 | |-------|-------------| -| `implement-feature` | 使用 TDD 工作流程,根據 spec 檔案或描述實作功能 | -| `update-docs` | 更新網站文件以符合最新的程式碼變更,並交叉驗證每個 flag 是否與原始碼一致 | -| `codebase-audit` | 交叉驗證 CLI flags、文件、測試與 targets 在整個程式碼庫中的一致性 | -| `cli-e2e-test` | 根據 runbook 在 devcontainer 中執行隔離的 E2E 測試 | -| `changelog` | 以 conventional commit 格式,根據最近的 commits 產生 CHANGELOG.md 項目 | +| `skillshare-implement-feature` | 使用 TDD 工作流程,根據 spec 檔案或描述實作功能 | +| `skillshare-update-docs` | 更新網站文件以符合最新的程式碼變更,並交叉驗證每個 flag 是否與原始碼一致 | +| `skillshare-code-review` | 以平行檢查(正確性、儲存庫規則、規格、使用處、清理)審查變更,並逐條驗證發現的問題 | +| `skillshare-cli-e2e-test` | 根據 runbook 在 devcontainer 中執行隔離的 E2E 測試 | +| `skillshare-changelog` | 以 conventional commit 格式,根據最近的 commits 產生 CHANGELOG.md 項目 | ## 典型工作流程 -1. **開始一項功能** — 請你的 agent 搭配 spec 使用 `implement-feature` -2. **更新文件** — 程式碼變更後,呼叫 `update-docs` 以同步網站文件 -3. **稽核一致性** — 執行 `codebase-audit` 以抓出 flag 與文件不一致之處 -4. **執行 E2E 測試** — 使用 `cli-e2e-test` 在 sandbox 中驗證 -5. **撰寫 changelog** — 發布前呼叫 `changelog` +1. **開始一項功能** — 請你的 agent 搭配 spec 使用 `skillshare-implement-feature` +2. **更新文件** — 程式碼變更後,呼叫 `skillshare-update-docs` 以同步網站文件 +3. **審查變更** — 提交或開 PR 前執行 `skillshare-code-review` +4. **執行 E2E 測試** — 使用 `skillshare-cli-e2e-test` 在 sandbox 中驗證 +5. **撰寫 changelog** — 發布前呼叫 `skillshare-changelog` ## 接下來呢?