From da813d48a092eb67a68bdf7b0c360e7328e130f7 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Sun, 5 Apr 2026 15:42:58 -0700 Subject: [PATCH] feat: add code tour workflow --- AGENTS.md | 4 +- README.md | 6 +- README.zh-CN.md | 2 +- WORKING-CONTEXT.md | 4 +- docs/zh-CN/AGENTS.md | 4 +- docs/zh-CN/README.md | 6 +- manifests/install-modules.json | 1 + skills/code-tour/SKILL.md | 236 +++++++++++++++++++++++++++++++++ 8 files changed, 251 insertions(+), 12 deletions(-) create mode 100644 skills/code-tour/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index e8d15b1b..c172b577 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Everything Claude Code (ECC) — Agent Instructions -This is a **production-ready AI coding plugin** providing 38 specialized agents, 161 skills, 72 commands, and automated hook workflows for software development. +This is a **production-ready AI coding plugin** providing 38 specialized agents, 162 skills, 72 commands, and automated hook workflows for software development. **Version:** 1.10.0 @@ -146,7 +146,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat ``` agents/ — 38 specialized subagents -skills/ — 161 workflow skills and domain knowledge +skills/ — 162 workflow skills and domain knowledge commands/ — 72 slash commands hooks/ — Trigger-based automations rules/ — Always-follow guidelines (common + per-language) diff --git a/README.md b/README.md index b06507ce..e54808e6 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,7 @@ For manual install instructions see the README in the `rules/` folder. When copy /plugin list ecc@ecc ``` -**That's it!** You now have access to 38 agents, 161 skills, and 72 legacy command shims. +**That's it!** You now have access to 38 agents, 162 skills, and 72 legacy command shims. ### Multi-model commands require additional setup @@ -1154,7 +1154,7 @@ The configuration is automatically detected from `.opencode/opencode.json`. |---------|-------------|----------|--------| | Agents | PASS: 38 agents | PASS: 12 agents | **Claude Code leads** | | Commands | PASS: 72 commands | PASS: 31 commands | **Claude Code leads** | -| Skills | PASS: 161 skills | PASS: 37 skills | **Claude Code leads** | +| Skills | PASS: 162 skills | PASS: 37 skills | **Claude Code leads** | | Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** | | Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** | | MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** | @@ -1263,7 +1263,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e |---------|------------|------------|-----------|----------| | **Agents** | 38 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 | | **Commands** | 72 | Shared | Instruction-based | 31 | -| **Skills** | 161 | Shared | 10 (native format) | 37 | +| **Skills** | 162 | Shared | 10 (native format) | 37 | | **Hook Events** | 8 types | 15 types | None yet | 11 types | | **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks | | **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions | diff --git a/README.zh-CN.md b/README.zh-CN.md index fee6048f..fdf84f8f 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -106,7 +106,7 @@ cp -r everything-claude-code/rules/perl ~/.claude/rules/ /plugin list ecc@ecc ``` -**完成！** 你现在可以使用 38 个代理、161 个技能和 72 个命令。 +**完成！** 你现在可以使用 38 个代理、162 个技能和 72 个命令。 ### multi-* 命令需要额外配置 diff --git a/WORKING-CONTEXT.md b/WORKING-CONTEXT.md index 9d117454..607808ca 100644 --- a/WORKING-CONTEXT.md +++ b/WORKING-CONTEXT.md @@ -10,7 +10,7 @@ Public ECC plugin repo for agents, skills, commands, hooks, rules, install surfa - Default branch: `main` - Public release surface is aligned at `v1.10.0` -- Public catalog truth is `38` agents, `72` commands, and `160` skills +- Public catalog truth is `38` agents, `72` commands, and `162` skills - Public plugin slug is now `ecc`; legacy `everything-claude-code` install paths remain supported for compatibility - Release discussion: `#1272` - ECC 2.0 exists in-tree and builds, but it is still alpha rather than GA @@ -138,6 +138,8 @@ Keep this file detailed for only the current sprint, blockers, and next actions. - 2026-04-05: Shipped `846ffb7` (`chore: ship v1.10.0 release surface refresh`). This updated README/plugin metadata/package versions, synced the explicit plugin agent inventory, bumped stale star/fork/contributor counts, created `docs/releases/1.10.0/*`, tagged and released `v1.10.0`, and posted the announcement discussion at `#1272`. - 2026-04-05: Salvaged the reusable Hermes-branch operator skills in `6eba30f` without replaying the full branch. Added `skills/github-ops`, `skills/knowledge-ops`, and `skills/hookify-rules`, wired them into install modules, and re-synced the repo to `159` skills. `knowledge-ops` was explicitly adapted to the current workspace model: live code in cloned repos, active truth in GitHub/Linear, broader non-code context in the KB/archive layers. - 2026-04-05: Fixed the remaining OpenCode npm-publish gap in `db6d52e`. The root package now builds `.opencode/dist` during `prepack`, includes the compiled OpenCode plugin assets in the published tarball, and carries a dedicated regression test (`tests/scripts/build-opencode.test.js`) so the package no longer ships only raw TypeScript source for that surface. +- 2026-04-05: Added `skills/council`, direct-ported the safe `code-tour` lane from `#1193`, and re-synced the repo to `162` skills. `code-tour` stays self-contained and only produces `.tours/*.tour` artifacts with real file/line anchors; no external runtime or extension install is assumed inside the skill. +- 2026-04-05: Closed the latest auto-generated ECC bundle PR wave (`#1275`-`#1281`) after deploying `ECC-Tools/main` fix `f615905`, which now blocks repo-level issue-comment `/analyze` requests from opening repeated bundle PRs while still allowing PR-thread retry analysis to run against immutable head SHAs. - 2026-04-05: Fixed the stale-row bug in `.github/workflows/monthly-metrics.yml` with `bf5961e`. The workflow now refreshes the current month row in issue `#1087` instead of early-returning when the month already exists, and the dispatched run updated the April snapshot to the current star/fork/release counts. - 2026-04-05: Recovered the useful cost-control workflow from the divergent Hermes branch as a small ECC-native operator skill instead of replaying the branch. `skills/ecc-tools-cost-audit/SKILL.md` is now wired into `operator-workflows` and focused on webhook -> queue -> worker tracing, burn containment, quota bypass, premium-model leakage, and retry fanout in the sibling `ECC-Tools` repo. - 2026-04-05: Added `skills/council/SKILL.md` in `753da37` as an ECC-native four-voice decision workflow. The useful protocol from PR `#1254` was retained, but the shadow `~/.claude/notes` write path was explicitly removed in favor of `knowledge-ops`, `/save-session`, or direct GitHub/Linear updates when a decision delta matters. diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md index 4f43f80c..a2a68075 100644 --- a/docs/zh-CN/AGENTS.md +++ b/docs/zh-CN/AGENTS.md @@ -1,6 +1,6 @@ # Everything Claude Code (ECC) — 智能体指令 -这是一个**生产就绪的 AI 编码插件**，提供 38 个专业代理、161 项技能、72 条命令以及自动化钩子工作流，用于软件开发。 +这是一个**生产就绪的 AI 编码插件**，提供 38 个专业代理、162 项技能、72 条命令以及自动化钩子工作流，用于软件开发。 **版本:** 1.10.0 @@ -147,7 +147,7 @@ ``` agents/ — 38 个专业子代理 -skills/ — 161 个工作流技能和领域知识 +skills/ — 162 个工作流技能和领域知识 commands/ — 72 个斜杠命令 hooks/ — 基于触发的自动化 rules/ — 始终遵循的指导方针（通用 + 每种语言） diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index c0d42b37..a856e3e1 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -209,7 +209,7 @@ npx ecc-install typescript /plugin list ecc@ecc ``` -**搞定！** 你现在可以使用 38 个智能体、161 项技能和 72 个命令了。 +**搞定！** 你现在可以使用 38 个智能体、162 项技能和 72 个命令了。 *** @@ -1096,7 +1096,7 @@ opencode |---------|-------------|----------|--------| | 智能体 | PASS: 38 个 | PASS: 12 个 | **Claude Code 领先** | | 命令 | PASS: 72 个 | PASS: 31 个 | **Claude Code 领先** | -| 技能 | PASS: 161 项 | PASS: 37 项 | **Claude Code 领先** | +| 技能 | PASS: 162 项 | PASS: 37 项 | **Claude Code 领先** | | 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多！** | | 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** | | MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** | @@ -1208,7 +1208,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以 |---------|------------|------------|-----------|----------| | **智能体** | 38 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 | | **命令** | 72 | 共享 | 基于指令 | 31 | -| **技能** | 161 | 共享 | 10 (原生格式) | 37 | +| **技能** | 162 | 共享 | 10 (原生格式) | 37 | | **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 | | **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 | | **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 | diff --git a/manifests/install-modules.json b/manifests/install-modules.json index f7a8cfa9..2d98d872 100644 --- a/manifests/install-modules.json +++ b/manifests/install-modules.json @@ -200,6 +200,7 @@ "paths": [ "skills/ai-regression-testing", "skills/configure-ecc", + "skills/code-tour", "skills/continuous-learning", "skills/continuous-learning-v2", "skills/council", diff --git a/skills/code-tour/SKILL.md b/skills/code-tour/SKILL.md new file mode 100644 index 00000000..6038675a --- /dev/null +++ b/skills/code-tour/SKILL.md @@ -0,0 +1,236 @@ +--- +name: code-tour +description: Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests. +origin: ECC +--- + +# Code Tour + +Create **CodeTour** `.tour` files for codebase walkthroughs that open directly to real files and line ranges. Tours live in `.tours/` and are meant for the CodeTour format, not ad hoc Markdown notes. + +A good tour is a narrative for a specific reader: +- what they are looking at +- why it matters +- what path they should follow next + +Only create `.tour` JSON files. Do not modify source code as part of this skill. + +## When to Use + +Use this skill when: +- the user asks for a code tour, onboarding tour, architecture walkthrough, or PR tour +- the user says "explain how X works" and wants a reusable guided artifact +- the user wants a ramp-up path for a new engineer or reviewer +- the task is better served by a guided sequence than a flat summary + +Examples: +- onboarding a new maintainer +- architecture tour for one service or package +- PR-review walk-through anchored to changed files +- RCA tour showing the failure path +- security review tour of trust boundaries and key checks + +## When NOT to Use + +| Instead of code-tour | Use | +| --- | --- | +| A one-off explanation in chat is enough | answer directly | +| The user wants prose docs, not a `.tour` artifact | `documentation-lookup` or repo docs editing | +| The task is implementation or refactoring | do the implementation work | +| The task is broad codebase onboarding without a tour artifact | `codebase-onboarding` | + +## Workflow + +### 1. Discover + +Explore the repo before writing anything: +- README and package/app entry points +- folder structure +- relevant config files +- the changed files if the tour is PR-focused + +Do not start writing steps before you understand the shape of the code. + +### 2. Infer the reader + +Decide the persona and depth from the request. + +| Request shape | Persona | Suggested depth | +| --- | --- | --- | +| "onboarding", "new joiner" | `new-joiner` | 9-13 steps | +| "quick tour", "vibe check" | `vibecoder` | 5-8 steps | +| "architecture" | `architect` | 14-18 steps | +| "tour this PR" | `pr-reviewer` | 7-11 steps | +| "why did this break" | `rca-investigator` | 7-11 steps | +| "security review" | `security-reviewer` | 7-11 steps | +| "explain how this feature works" | `feature-explainer` | 7-11 steps | +| "debug this path" | `bug-fixer` | 7-11 steps | + +### 3. Read and verify anchors + +Every file path and line anchor must be real: +- confirm the file exists +- confirm the line numbers are in range +- if using a selection, verify the exact block +- if the file is volatile, prefer a pattern-based anchor + +Never guess line numbers. + +### 4. Write the `.tour` + +Write to: + +```text +.tours/-.tour +``` + +Keep the path deterministic and readable. + +### 5. Validate + +Before finishing: +- every referenced path exists +- every line or selection is valid +- the first step is anchored to a real file or directory +- the tour tells a coherent story rather than listing files + +## Step Types + +### Content + +Use sparingly, usually only for a closing step: + +```json +{ "title": "Next Steps", "description": "You can now trace the request path end to end." } +``` + +Do not make the first step content-only. + +### Directory + +Use to orient the reader to a module: + +```json +{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." } +``` + +### File + line + +This is the default step type: + +```json +{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." } +``` + +### Selection + +Use when one code block matters more than the whole file: + +```json +{ + "file": "src/core/pipeline.ts", + "selection": { + "start": { "line": 15, "character": 0 }, + "end": { "line": 34, "character": 0 } + }, + "title": "Request Pipeline", + "description": "This block wires validation, auth, and downstream execution." +} +``` + +### Pattern + +Use when exact lines may drift: + +```json +{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" } +``` + +### URI + +Use for PRs, issues, or docs when helpful: + +```json +{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" } +``` + +## Writing Rule: SMIG + +Each description should answer: +- **Situation**: what the reader is looking at +- **Mechanism**: how it works +- **Implication**: why it matters for this persona +- **Gotcha**: what a smart reader might miss + +Keep descriptions compact, specific, and grounded in the actual code. + +## Narrative Shape + +Use this arc unless the task clearly needs something different: +1. orientation +2. module map +3. core execution path +4. edge case or gotcha +5. closing / next move + +The tour should feel like a path, not an inventory. + +## Example + +```json +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "API Service Tour", + "description": "Walkthrough of the request path for the payments service.", + "ref": "main", + "steps": [ + { + "directory": "src", + "title": "Source Root", + "description": "All runtime code for the service starts here." + }, + { + "file": "src/server.ts", + "line": 12, + "title": "Entry Point", + "description": "The server boots here and wires middleware before any route is reached." + }, + { + "file": "src/routes/payments.ts", + "line": 8, + "title": "Payment Routes", + "description": "Every payments request enters through this router before hitting service logic." + }, + { + "title": "Next Steps", + "description": "You can now follow any payment request end to end with the main anchors in place." + } + ] +} +``` + +## Anti-Patterns + +| Anti-pattern | Fix | +| --- | --- | +| Flat file listing | Tell a story with dependency between steps | +| Generic descriptions | Name the concrete code path or pattern | +| Guessed anchors | Verify every file and line first | +| Too many steps for a quick tour | Cut aggressively | +| First step is content-only | Anchor the first step to a real file or directory | +| Persona mismatch | Write for the actual reader, not a generic engineer | + +## Best Practices + +- keep step count proportional to repo size and persona depth +- use directory steps for orientation, file steps for substance +- for PR tours, cover changed files first +- for monorepos, scope to the relevant packages instead of touring everything +- close with what the reader can now do, not a recap + +## Related Skills + +- `codebase-onboarding` +- `coding-standards` +- `council` +- official upstream format: `microsoft/codetour`