commit 785216c0bb6c8face848d8865826c16299319144 Author: zhuyongxin Date: Thu Apr 30 11:29:12 2026 +0800 skills: v0.5.0 slim architecture — 3-skill family with validation /explore (4 Phase), /essence (lens-driven deep dive), /follow (report-dependent guided learning). Hard-deleted /map, tightened boundaries, verified on both code (SuperBizAgent-java) and non-code repositories. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..316b38b --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +project/\ndocs/\nsuperpowers/\n diff --git a/changelog/2026-04-30-skills-v0.5.0-consolidation.md b/changelog/2026-04-30-skills-v0.5.0-consolidation.md new file mode 100644 index 0000000..b4dfd81 --- /dev/null +++ b/changelog/2026-04-30-skills-v0.5.0-consolidation.md @@ -0,0 +1,136 @@ +# Skills v0.5.0 整合修复记录 + +**日期：** 2026-04-30 +**来源：** grill-me 逐项审查，基于 v0.5.0 changelog 和 design doc 对比实际实现发现的不一致 + +--- + +## 一句话摘要 + +在前次 v0.5.0 slim architecture 改造的基础上，逐文件对比 design doc、proposal、plan、实际实现，修复了 `/essence` 遗漏项、`/follow` 旧引用残留、`/explore` 阶段冗余、references 死文件、docs 目录垃圾等问题。 + +--- + +## 已完成的改动 + +### 1. `/essence` — 补齐 v0.5.0 改造（之前遗漏） + +| 位置 | 修改内容 | +|---|---| +| 版本号 | `0.3.0` → `0.5.0` | +| 透镜定义 | 删除 `(borrowed from /explore)`，声明为 `/essence` 自有 | +| 透镜相关 Phase 2/3/4/5 表格 | 从独立 3 列表格瘦身为内联 bullet point | +| HTML Card | `## Phase 6: Output (Optional HTML Card)` → `## Optional: HTML Card`；去 "production-critical" 条件，改为 `Only when the user explicitly requests it` | +| HTML Card 死链接 | 删除 `Same as /explore.` 两处，改为自包含内容 | +| Mode Selection 上下文感知 | 新增检测逻辑：来自 `/explore` → 默认 User-directed；独立启动 → 默认 Auto-detect | +| Auto-detect 信号 | `Most imported file` → `Cross-module contract`（后端项目更准确） | + +### 2. `/follow` — 消除旧引用和设计偏差 + +| 位置 | 修改内容 | +|---|---| +| Mode Selection | 新增前置报告感知：来自 `/explore` + 代码仓库 → Runnable；来自 `/explore` + 非代码 → Reader；来自 `/essence` → Reader | +| Runnable Check | 删除重新扫描逻辑，改为从前置报告读取结论；运行时信号改为后端导向（`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile` 等） | +| Reader Mode Flow | 从文件级 "Walk one core file" 提升为设计级 "Frame the learning goal around a core design" | +| 教学规则 | `do not use "go read the code" as the default instruction without context` → `never say "go read the code" as a standalone instruction`；引用代码必须先交代设计上下文 | + +### 3. `/explore` — 合并冗余阶段 + +| 位置 | 修改内容 | +|---|---| +| Phase 1+2 | `Phase 1: Positioning` + `Phase 2: Structure` 合并为 `Phase 1: Positioning & Structure` | +| 阶段总数 | 5 Phase → 4 Phase | +| Project Type Detection | 信号列表同步（`package.json` 不再为首例）；阶段跳过的编号更新 | +| Outcome 模板 | `5/5` → `4/4` | + +### 4. References 清理 + +| 文件 | 操作 | +|---|---| +| `skills/explore/references/deep-fission.md` | **删除** — 描述已移除的 Deep Fission 功能，引用不存在的 `/fission` 技能 | +| `skills/essence/references/essence-signals.md` | `Most imported file` → `Cross-module contract`，与 SKILL.md 同步 | + +### 5. docs 存档清理 + +| 文件 | 操作 | 原因 | +|---|---|---| +| `docs/superpowers/proposal.md` | 删除 | 原始 4-skill 提案，已过时 | +| `docs/superpowers/plan.md` | 删除 | 实施模板与实际实现不一致 | +| `docs/superpowers/plans/` | 删除 | 456 行 task-by-task 计划，含 `/map` 引用 | +| `docs/superpowers/README.md` | 删除 | `superpowers/README.md` 的副本，不属于历史存档 | + +--- + +## docs 存档最终结构 + +``` +docs/superpowers/ +├── specs/ +│ ├── issue.md # 原始需求 +│ ├── 2026-04-21-skills-v0.5.0-slim-architecture-design.md +│ └── 2026-04-21-skills-v0.5.0-changelog-design.md +└── changelog/ + ├── 2026-04-21-skills-v0.5.0-slim-architecture.md # 第一次改造 changelog + ├── 2026-04-21-skills-v0.5.0-validation-handoff.txt # 交接指令 + └── 2026-04-30-skills-v0.5.0-consolidation.md # 本次整合（本文件） +``` + +--- + +## 当前 skill 状态 + +| 技能 | 版本 | Phase/Mode | 备注 | +|---|---|---|---| +| `/explore` | v0.5.0 | 4 Phase | 支持代码/非代码仓库；合并 Positioning+Structure | +| `/essence` | v0.5.0 | 5 Phase + Optional HTML | 透镜自有；上下文感知 Mode Selection | +| `/follow` | v0.5.0 | Runnable / Reader | 来源感知；不再重新扫描项目 | + +--- + +## 实践验证结果 + +**日期：** 2026-04-30 +**测试目标仓库：** +- 非代码仓库：explore-skill-family（自身） +- 代码仓库：SuperBizAgent-java（Spring Boot + AI Agent） + +| # | 验证路径 | 目标 | 结果 | +|---|---|---|---| +| 1 | `/follow` 拒绝无前置报告 | 直接模拟 | ✅ | +| 2 | `/explore` 非代码仓库 | 自身 skill family | ✅ — 正确识别 skill-docs，跳过 Flow/Start | +| 3 | `/essence` 深挖 | "硬边界"设计 | ✅ — 结论-证据-解释，可迁移 | +| 4 | `/explore` → `/follow` | 自身 | ✅ — Reader 分流，引用报告内容 | +| 5 | `/essence` → `/follow` | 自身 | ✅ — design-focused，未重扫 | +| 6 | 三技能职责边界 | 综合矩阵检查 | ✅ — 核心问题/深度/前置依赖/产出均无重叠 | +| 7 | `/explore` 代码仓库 | SuperBizAgent-java | ✅ — 4 Phase 全流程，后端信号检测正常 | + +### 验证发现的额外修复 + +验证过程中对 SKILL.md 的追加修改（已在代码中反映）： +- `/essence` Phase 6 → Optional: HTML Card +- `/essence` Mode Selection 上下文感知 +- `/essence` Most imported file → Cross-module contract +- `/follow` Mode Selection 来源感知 +- `/follow` Runnable Check 不再重扫，引用前置报告 +- `/follow` Reader Mode Flow 提升到设计层 +- `/follow` Teaching Interaction Rules 收紧 +- `/explore` Phase 1+2 合并，5→4 Phase +- `/explore` Project Type Detection 信号改为后端导向 +- 删除 `skills/explore/references/deep-fission.md` + +### handoff 10 条检查清单逐项结论 + +| # | 问题 | 结论 | +|---|---|---| +| 1 | `/explore` 对代码/非代码给出不同输出？ | ✅ Phase 2/3 对非代码跳过 | +| 2 | `/explore` 保持在项目级理解？ | ✅ Phase 4 概览深度 | +| 3 | `/essence` 稳定找最高价值设计？ | ✅ "硬边界"提取到 pattern 层 | +| 4 | `/follow` 无前置报告明确拒绝？ | ✅ 拒绝并引导 | +| 5 | `/follow` 基于 /explore 或 /essence 结果？ | ✅ 两次测试均基于前置报告 | +| 6 | `/follow` 避免重新扫描？ | ✅ 三次验证均未重扫 | +| 7 | `/follow` 真正引导式教学？ | ✅ 先问后讲 | +| 8 | 三技能职责重叠/模糊？ | ✅ 边界清晰 | +| 9 | README 与实际行为一致？ | ✅ 三技能描述与 SKILL.md 一致 | +| 10 | references 与 v0.5.0 一致？ | ✅ deep-fission 已删，signals 已同步 | + +**总体验收结论：通过。** 文档、边界、行为三者一致。 diff --git a/skills/essence/SKILL.md b/skills/essence/SKILL.md new file mode 100644 index 0000000..d444511 --- /dev/null +++ b/skills/essence/SKILL.md @@ -0,0 +1,259 @@ +--- +name: essence +description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups. +metadata: + version: "0.5.0" +--- + +# Essence: Extract Core Design Patterns + +Prefix your first line with 🥷 inline, not as its own paragraph. + +You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing. + +**This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else. + +## Mode Selection + +First, check whether an `/explore` result exists: + +- `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode. +- No `/explore` result → this is an independent launch, default to **Auto-detect**. + +Always confirm before proceeding: + +| Mode | When | Entry | +|---|---|---| +| **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for | +| **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design | +| **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens | + +### Lens definitions + +| Lens | Core question | Guided behavior | +|---|---|---| +| **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces | +| **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs | +| **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers | + +A lens shapes which sources to read and how to frame the output, but does not add separate phases. + +### Auto-detect signals + +A design is "essence" if it passes 2 or more of these signals: + +| Signal | Evidence | +|---|---| +| README highlights it prominently | "Built on a plugin architecture" as a headline feature | +| Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author | +| Heavily discussed in Issues/PRs | Design decisions debated by community | +| Unique among similar projects | Competitors don't do it this way | +| Rich design comments in code | JSDoc/TSDoc explaining why, not what | +| Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. | +| File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic | +| Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths | + +**"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is. + +If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead." + +## Phase 1: Locate + +**User-directed mode:** +- Go directly to the directory or file the user names. +- If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative. + +**Auto-detect mode:** +- Scan README, CLAUDE.md, and top-level docs for architecture claims. +- Identify 1-2 standout design directions. +- Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?" +- If user doesn't choose, pick the strongest one and state why. + +**Lens-guided mode:** +- Confirm the lens with the user (Mechanical/Intentional/Evolution). +- Frame the search in terms of the lens. +- Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern." + +**Output:** 1-2 design directions to analyze + lens confirmation. + +**Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project. + +## Phase 2: Deep Dive + +Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides. + +**For each file:** +- What role does it play in this design? +- What interfaces does it expose? +- How does it connect to other parts of the system? + +**Trace the call chain:** +- Start from the entry point that uses this design. +- Follow the flow until you understand the full pattern. +- Stop when you hit boilerplate, config, or test files. + +**Output:** Core file list (≤10) + call chain + lens-specific annotations. + +**Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead. + +## Phase 3: Extract Pattern + +Analyze the design at a higher level. Let the lens shape the analysis angle: +- **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts +- **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale) +- **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events + +**Universal analysis dimensions** (all lenses): + +- **Problem:** What specific problem does this design solve? What was the pain before? +- **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.) +- **Alternatives:** What simpler or more complex approaches could solve the same problem? +- **Tradeoffs:** Why did the author choose this? What does it give up? +- **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.) + +**Output:** Design pattern card (lens-framed). + +**Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report. + +## Phase 4: Migrate + +Make the learning actionable. Let the lens tailor the output: +- **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs) +- **Intentional** → decision framework (checklist for evaluating tradeoffs) +- **Evolution** → migration path (step-by-step refactor plan) + +**Universal deliverables** (all lenses): + +- **Can you use this?** Is the design applicable to the user's own projects? If not, why? +- **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example. +- **Pitfalls:** What context does this design depend on? What would break if you copy it blindly? + +**Output:** Migration example + pitfall list (lens-tailored). + +**Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code. + +## Phase 5: Self-review + +Check the report is honest: + +**All modes:** +- [ ] The design is real (not inferred, not imagined). Evidence: specific files cited. +- [ ] The analysis is deep enough that you could explain it out loud. +- [ ] The migration example captures the core idea, not surface syntax. +- [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere"). + +**Stall signals (any one → return to relevant phase):** +- Cannot name a file that proves the pattern → back to Phase 2 +- Cannot explain why it's better than alternatives → back to Phase 3 +- Migration example is over 20 lines → simplify, back to Phase 4 +- Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase + +**Output:** Essence report with lens annotation. + +## Optional: HTML Card + +**Only when the user explicitly requests it.** + +Generate an HTML visualization card as a shareable deliverable. + +### HTML Card Structure (Glassmorphism 2.0 - Essence Variant) + +```html + + + + + {Project Name} - Essence Report + + + + + + + +
+
+

🎯 Design Analyzed

+

{one-line description}

+
+ +
+

🔷 Pattern ({lens})

+ +
+ +
+

🔗 Call Chain

+ 
{diagram}
+
+ +
+

📦 Migration Example

+ 
{code_example}
+

Pitfalls: {pitfalls}

+
+
+ + + + +``` + +### Output Format + +```markdown +### HTML Card Generated + +- **Path:** `outputs/{project}-essence.html` +- **Theme:** {modern/ink} +- **Accent Color:** Purple (essence = jewel) +``` + +**When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead. + +--- + +## Hard Rules + +- **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment. +- **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough. +- **Stop after the report.** Do not modify the user's project or the target project. +- **HTML is optional.** Do not block analysis on HTML generation. + +## Gotchas + +| What happened | Rule | +|---|---| +| 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 | +| 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 | +| 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` | +| Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 | +| 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 | +| 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 | +| 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 | +| 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 | +| HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 | + +## Outcome + +``` +Essence Report: {project name} +Lens: mechanical / intentional / evolution +Design analyzed: {one-line description} +Files examined: {count} +Pattern: {pattern name or custom description} +Migration: {steal-it example, ≤20 lines} +HTML generated: yes / no +Status: complete +``` + +After the report, stop. No modifications. No follow-ups. diff --git a/skills/essence/references/essence-signals.md b/skills/essence/references/essence-signals.md new file mode 100644 index 0000000..b4ad9b8 --- /dev/null +++ b/skills/essence/references/essence-signals.md @@ -0,0 +1,79 @@ +# Essence Detection Signals + +How to identify the standout design in a project when the user doesn't specify a direction. + +## Signal Strength + +A design passes the "essence" threshold if it scores 2+ signals. + +### Strong Signals (score = 1 each) + +| Signal | How to detect | Example | +|---|---|---| +| **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" | +| **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` | +| **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts | +| **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments | +| **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning | + +### Objective Signals (score = 1 each, no subjective judgment needed) + +| Signal | How to detect | Example | +|---|---|---| +| **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package | +| **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic | +| **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" | + +### Weak Signals (score = 0.5 each) + +| Signal | How to detect | Example | +|---|---|---| +| **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence | +| **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" | +| **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine | +| **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object | + +## Not Signals + +These do NOT count as essence: + +- "Clean code" or "well organized" — that's quality, not design +- "Uses TypeScript" — that's a language choice, not architecture +- "Has good tests" — that's engineering discipline, not design +- "Many stars on the repo" — popularity ≠ design quality +- "Uses the latest framework" — following trends ≠ standing out +- Utility functions — even well-written ones are tools, not designs + +## Auto-detect Procedure + +When the user says "find the essence": + +1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate. +2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate. +3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core. +4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity. +5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently? +6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest. + +### Example Output Format + +``` +Standout designs in {project}: + +A) {Design A name} — evidenced by {README claim / file / doc} + What it does: {one sentence} + +B) {Design B name} — evidenced by {code comment / unique feature / community discussion} + What it does: {one sentence} + +Which should we dive into? (or I can pick the strongest) +``` + +## Failure Modes + +| Situation | Response | +|---|---| +| No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." | +| User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. | +| Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." | +| Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." | diff --git a/skills/explore/SKILL.md b/skills/explore/SKILL.md new file mode 100644 index 0000000..318a60a --- /dev/null +++ b/skills/explore/SKILL.md @@ -0,0 +1,87 @@ +--- +name: explore +description: Invoke when you need project-level understanding and an onboarding path. Produces a project learning report for code and non-code repositories with fixed phases for positioning, structure, flow, start path, and core designs. Not for deep code extraction or interactive teaching. +metadata: + version: "0.5.0" +--- + +# Explore: Project Understanding and Onboarding + +Prefix your first line with 🥷 inline, not as its own paragraph. + +You are a project cartographer. Your job is to help the user understand what a project is, why it is worth studying, how it is organized, and where to start. + +`/explore` is the entry point for first contact with a repository or project-like artifact. It builds global understanding. It does not perform code-level essence extraction and it does not run interactive teaching. + +## Project Type Detection + +After the initial scan, classify the target before continuing: + +| Type | Signals | What changes | +|---|---|---| +| **Code repository** | `go.mod`, `pyproject.toml`, `Cargo.toml`, source directories, executable entrypoints | Run all 4 phases | +| **Skill / docs / knowledge repository** | `SKILL.md`, mostly Markdown, docs-first structure, no runnable application entrypoint | Skip Phase 2 (Flow) and Phase 3 (Start Path) | +| **Template / scaffold repository** | Starter files, minimal logic, setup-first repo | Phase 2 may stay structural and Phase 3 may be minimal | + +State the detected type before proceeding. If uncertain, say what evidence is missing and continue with the closest matching type. + +## Phase 1: Positioning & Structure +- What this project is, why it is worth studying, and who it is for. +- Top-level structure: main modules, documents, directories, and the likely learning entry area. +- Tradeoffs vs alternatives when evidence exists. + +## Phase 2: Flow +**Code repositories only.** +- Skip for non-code and template repositories. +- Trace the main runtime or request flow. +- Produce at least one architecture or core-flow diagram. +- Keep the trace focused on the golden path rather than exhaustive coverage. + +## Phase 3: Start Path +**Code repositories only when runnable or meaningfully inspectable.** +- Provide the minimal path to start learning or running the project. +- Give the first command or first inspection step. +- Suggest one safe first modification or observation point when appropriate. + +## Phase 4: Core Designs +- Summarize 2-3 core implementations or ideas. +- Keep this at overview depth. +- For each item, include what it is, where it lives, and why it matters. + +## Minimum Deliverables + +The final `/explore` report must include: +- Project positioning +- Why it is worth studying +- 2-3 core implementations or core ideas +- Tradeoffs or comparisons when applicable +- At least 1 diagram: + - code repository → architecture diagram or core flow diagram + - non-code repository → structure diagram, idea map, or workflow diagram + +## Boundary Rules + +`/explore` may: +- scan structure +- explain the main flow +- provide a minimal start path +- summarize 2-3 core designs + +`/explore` must not: +- perform `/essence`-level deep extraction +- act as `/follow`-style guided teaching +- include Verify, Deep Fission, or HTML Output phases +- preserve no retired lightweight fallback behavior + +## Outcome + +``` +Explore Report: {project name} +Project type: code / skill-docs / template +Phases completed: 4/4 (or note skipped code-only phases) +Diagram included: yes / no +Core designs: 2-3 +Status: complete +``` + +After the report, stop. Do not proceed to `/essence` or `/follow` automatically. diff --git a/skills/explore/references/analysis-methods.md b/skills/explore/references/analysis-methods.md new file mode 100644 index 0000000..f1dcf6a --- /dev/null +++ b/skills/explore/references/analysis-methods.md @@ -0,0 +1,98 @@ +# Project Analysis Methods + +How to read and understand an unfamiliar code project. + +## 1. Identify the Entry Point + +Every project has a door. Find it first. + +### By Language + +| Language | Look for | +|---|---| +| **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` | +| **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` | +| **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` | +| **Rust** | `src/main.rs` or `src/bin/*.rs` | +| **Java** | Class with `public static void main(String[] args)` | +| **C/C++** | `main()` function, conventionally in `src/main.c` | +| **Swift** | `main.swift` or file with `@main` attribute | + +### In Frameworks + +| Framework | Entry point | +|---|---| +| Next.js | `app/` or `pages/` directory, `next.config.js` | +| React (Vite) | `src/main.tsx` or `src/main.jsx` | +| Vue (Vite) | `src/main.ts` or `src/main.js` | +| Express | File that calls `app.listen()` | +| FastAPI | File that creates `FastAPI()` instance | +| Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` | +| Flask | `app.py` or `app/__init__.py` | +| Spring Boot | `*Application.java` with `@SpringBootApplication` | + +## 2. Judge Project Complexity + +Don't over-engineer simple projects. Don't under-analyze complex ones. + +### Simple (<50 files, single language) +- Read every source file. +- No need for flow diagrams beyond a simple sequence. +- A light `/explore` pass is probably enough. + +### Standard (50-500 files, 1-2 languages) +- Read entry point + core modules + 1-2 feature files. +- Build 1-2 flow diagrams. +- `/explore` is the right level. + +### Complex (>500 files, multi-language, monorepo) +- Read entry point + architecture docs + one representative module. +- Use `/essence` to find standout designs, or `/explore` for one package at a time. +- Do NOT try to understand the whole project in one pass. + +## 3. Separate Core Code from Scaffolding + +Not all files are worth reading. + +### Ignore (scaffolding) +- `*.config.js`, `*.config.ts` — configuration, not logic +- `dist/`, `build/`, `out/` — generated output +- `node_modules/`, `vendor/`, `.venv/` — dependencies +- `*.lock`, `yarn.lock`, `go.sum` — lock files +- `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta +- `test/fixtures/`, `test/data/` — test data + +### Read (core) +- Entry point file +- Router/middleware/config handlers +- Model/entity/schema definitions +- Core algorithm or business logic files +- Files referenced most in imports + +### Hint: Follow imports + +``` +entry file → import A → import B → core logic +``` + +Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core. + +## 4. Read Unfamiliar Framework Code + +You don't know every framework. That's fine. + +### Strategy + +1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities. + +2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response. + +3. **Identify the framework's conventions.** Most frameworks follow a pattern: + - MVC: Controller → Model → View + - Middleware: Request → Middleware chain → Handler → Response + - Component: Parent renders children, props flow down, events flow up + - Plugin: Core calls hooks, plugins register handlers + +4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose. + +5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented. diff --git a/skills/explore/references/flow-patterns.md b/skills/explore/references/flow-patterns.md new file mode 100644 index 0000000..487a5be --- /dev/null +++ b/skills/explore/references/flow-patterns.md @@ -0,0 +1,173 @@ +# Flow Pattern Library + +Common architecture patterns and how to identify them in code. + +## MVC / MVVM / MVX + +### What it is +Separation of data (Model), UI/presentation (View), and coordination logic (Controller/ViewModel). + +### File signatures +| Pattern | Directories/Files | +|---|---| +| **MVC** | `controllers/`, `models/`, `views/` | +| **MVVM** | `viewmodels/`, `views/`, `models/` | +| **Layered** | `app/`, `domain/`, `infrastructure/` (Clean/Hexagonal) | + +### Flow +``` +Request → Controller → Model (data) → View (render) → Response +``` + +### Key question +"Does the file handle data, display, or coordination?" If yes → MVC-family. + +--- + +## Middleware Chain + +### What it is +Each handler processes the request and passes it to the next. Like an assembly line. + +### File signatures +| Framework | Indicator | +|---|---|---| +| **Express/Koa** | `app.use(...)`, `app.get('/', handler)` | +| **FastAPI** | `@app.middleware("http")`, `Depends()` | +| **Next.js** | `middleware.ts` at root or in `app/` | +| **Gin (Go)** | `router.Use(middleware1, middleware2)` | +| **Koa** | `app.use(async (ctx, next) => { ... })` | + +### Flow +``` +Request → Middleware A → Middleware B → Handler → Response + ↓ ↓ + auth check log request +``` + +### Key question +"Does this function call `next()` or pass control to something else?" If yes → middleware. + +### Common middleware order +``` +1. CORS / Security headers +2. Logging / Request ID +3. Authentication / Authorization +4. Body parsing / Validation +5. Rate limiting +6. Route handler +7. Error handler (catches everything above) +``` + +--- + +## Plugin / Extension System + +### What it is +Core provides hooks or interfaces. External code registers handlers. The core doesn't know about specific plugins. + +### File signatures +| Pattern | Indicator | +|---|---| +| **Hook-based** | `registerHook('eventName', handler)`, `hooks.on('event', fn)` | +| **Interface-based** | Abstract class or interface that plugins implement | +| **Discovery-based** | Directory scan (`plugins/`), import all, register by convention | +| **VSCode-style** | `contributes` in `package.json`, activation events | + +### Flow +``` +Core starts + ↓ +Scans for plugins + ↓ +Each plugin registers itself + ↓ +Core fires hooks → plugins respond + ↓ +Core runs with extended capabilities +``` + +### Key question +"Can I add functionality without modifying core code?" If yes → plugin architecture. + +--- + +## Event-Driven + +### What it is +Components communicate through events, not direct calls. Publishers emit, subscribers listen. + +### File signatures +| Pattern | Indicator | +|---|---| +| **Node EventEmitter** | `eventEmitter.on('event', handler)`, `eventEmitter.emit('event', data)` | +| **Pub/Sub** | `pubsub.subscribe('channel', handler)`, `pubsub.publish('channel', data)` | +| **Redux-style** | `dispatch(action)`, `reducer(state, action) → newState` | +| **Observable** | `observable.subscribe(fn)`, `pipe(map, filter)` | +| **Signals (Python)** | `@signal.connect`, `signal.send()` | + +### Flow +``` +Component A emits "user.created" + ↓ +Listener B hears it → sends welcome email +Listener C hears it → creates default settings +Listener D hears it → logs analytics +``` + +### Key question +"Does code communicate without importing or calling each other directly?" If yes → event-driven. + +--- + +## State Management + +### What it is +Centralized storage for application state. Components read and update through defined interfaces. + +### File signatures +| Pattern | Indicator | +|---|---| +| **Redux** | `createStore()`, `dispatch()`, `useSelector()`, `@reduxjs/toolkit` | +| **Zustand** | `create((set) => ({ ... }))` | +| **Jotai** | `atom(value)`, `useAtom(atom)` | +| **MobX** | `@observable`, `@action`, `@computed` | +| **React Context** | `createContext()`, `useContext()`, `Provider` | +| **Pinia (Vue)** | `defineStore()`, `state`, `actions` | + +### Flow +``` +Component dispatches action + ↓ +Reducer processes action + current state + ↓ +New state emitted + ↓ +Subscribed components re-render +``` + +### Key question +"Where does the app store data that multiple components need?" If it's a single store → state management pattern. + +--- + +## Pipeline / Chain of Responsibility + +### What it is +Data flows through a series of processors. Each processor transforms the data and passes it on. + +### File signatures +| Pattern | Indicator | +|---|---| +| **Stream processing** | `.pipe(transform1).pipe(transform2)` | +| **Compiler/lexer** | Source → Tokenize → Parse → Transform → Generate | +| **Data pipeline** | `input → transform → validate → output` | +| **Makefile** | Target depends on prerequisites, each is a step | + +### Flow +``` +Raw input → Tokenizer → Parser → Transformer → Generator → Output +``` + +### Key question +"Does data get progressively transformed through a fixed sequence of steps?" If yes → pipeline. diff --git a/skills/explore/scripts/collect-structure.sh b/skills/explore/scripts/collect-structure.sh new file mode 100644 index 0000000..fe27a78 --- /dev/null +++ b/skills/explore/scripts/collect-structure.sh @@ -0,0 +1,120 @@ +#!/usr/bin/env bash +# Collect project structure for /explore analysis. +# Usage: Run from project root, or pass project path as argument. +# Output: Structured text with directory tree, file counts, language distribution. + +set -euo pipefail + +PROJECT_DIR="${1:-.}" +cd "$PROJECT_DIR" + +echo "=== PROJECT STRUCTURE ===" +echo "" + +# Directory tree (depth 3, exclude common noise) +echo "--- Directory Tree (depth 3) ---" +if command -v tree &>/dev/null; then + tree -L 3 \ + -I "node_modules|vendor|.git|dist|build|out|.venv|__pycache__|*.egg-info|coverage|.nyc_output" \ + --dirsfirst +elif command -v find &>/dev/null; then + find . -maxdepth 3 \ + -not -path "./.git/*" \ + -not -path "./node_modules/*" \ + -not -path "./vendor/*" \ + -not -path "./dist/*" \ + -not -path "./build/*" \ + -not -path "./out/*" \ + -not -path "./.venv/*" \ + -not -path "*/__pycache__/*" \ + -not -path "*/.egg-info/*" \ + -not -path "*/coverage/*" \ + -not -path "./.nyc_output/*" \ + -print | head -100 | sort +fi + +echo "" +echo "=== FILE COUNTS ===" +echo "" + +# Count files by extension (top 10) +echo "--- Top 10 File Types ---" +find . -type f \ + -not -path "./.git/*" \ + -not -path "./node_modules/*" \ + -not -path "./vendor/*" \ + -not -path "./dist/*" \ + -not -path "./build/*" \ + -not -path "./out/*" \ + -not -path "./.venv/*" \ + -not -path "*/__pycache__/*" \ + -printf '%f\n' | \ + sed 's/.*\.//' | \ + grep -v '^\.[^/]*$' | \ + sort | uniq -c | sort -rn | head -10 + +echo "" +echo "=== TOTAL FILE COUNT ===" +echo "" + +# Total files (excluding noise) +total=$(find . -type f \ + -not -path "./.git/*" \ + -not -path "./node_modules/*" \ + -not -path "./vendor/*" \ + -not -path "./dist/*" \ + -not -path "./build/*" \ + -not -path "./out/*" \ + -not -path "./.venv/*" \ + | wc -l) +echo "Total source files: $total" + +echo "" +echo "=== DEPENDENCY FILES ===" +echo "" + +# List dependency declaration files found +for dep_file in "package.json" "requirements.txt" "pyproject.toml" "setup.py" "go.mod" "go.sum" "Cargo.toml" "Cargo.lock" "pom.xml" "build.gradle" "Gemfile" "Gemfile.lock" "composer.json"; do + if [ -f "$dep_file" ]; then + echo "FOUND: $dep_file" + fi +done + +# Check for workspace/monorepo configs +echo "" +echo "=== WORKSPACE / MONOREPO ===" +echo "" + +for ws_file in "turbo.json" "nx.json" "lerna.json" "pnpm-workspace.yaml" "go.work"; do + if [ -f "$ws_file" ]; then + echo "FOUND: $ws_file" + fi +done + +# Check Cargo.toml for workspace +if [ -f "Cargo.toml" ] && grep -q '\[workspace\]' Cargo.toml 2>/dev/null; then + echo "FOUND: Cargo.toml [workspace]" +fi + +echo "" +echo "=== ENTRY POINTS ===" +echo "" + +# Try to identify entry points +if [ -f "package.json" ]; then + main=$(node -e "try{const p=require('./package.json');console.log(p.main||'');}catch(e){}" 2>/dev/null || echo "") + bin=$(node -e "try{const p=require('./package.json');console.log(typeof p.bin==='string'?p.bin:JSON.stringify(p.bin));}catch(e){}" 2>/dev/null || echo "") + dev=$(node -e "try{const p=require('./package.json');console.log(p.scripts?.dev||p.scripts?.start||'');}catch(e){}" 2>/dev/null || echo "") + [ -n "$main" ] && echo "package.json main: $main" + [ -n "$bin" ] && echo "package.json bin: $bin" + [ -n "$dev" ] && echo "package.json dev/start: $dev" +fi + +for entry in "src/main.ts" "src/main.tsx" "src/main.js" "src/main.jsx" "src/index.ts" "src/index.js" "src/main.py" "app/main.py" "main.go" "src/main.rs" "app.py" "index.js" "index.ts"; do + if [ -f "$entry" ]; then + echo "FOUND: $entry" + fi +done + +echo "" +echo "=== COLLECTED ===" diff --git a/skills/follow/SKILL.md b/skills/follow/SKILL.md new file mode 100644 index 0000000..c6a158c --- /dev/null +++ b/skills/follow/SKILL.md @@ -0,0 +1,101 @@ +--- +name: follow +description: Invoke when the user wants an interactive learning session based on an existing `/explore` or `/essence` report. Guides runnable or reader-style follow-along sessions. Not for fresh project analysis or pattern-only extraction. +metadata: + version: "0.5.0" +--- + +# Follow: Guided Learning Session + +Prefix your first line with 🥷 inline, not as its own paragraph. + +You are a guide. The user wants to learn from a project step by step with help, context, and correction. You guide the learning process, but you do not replace it. + +`/follow` is not a fresh project analyzer. It only works from an existing `/explore` or `/essence` result. + +## Pre-check + +`/follow` only works when there is already an `/explore` report or an `/essence` report. + +- `/explore` report exists → use it as the main learning path +- `/essence` report exists → use it for design-focused guided study +- Neither exists → refuse clearly + +Refusal behavior: +"I need an existing `/explore` or `/essence` result before I can guide a follow-along session. Please run `/explore` for project understanding or `/essence` for a focused deep dive first." + +Load the existing report before continuing. + +## Mode Selection + +After the pre-check, select one mode based on the prerequisite report: + +- From `/explore` + code repository → default **Runnable** +- From `/explore` + non-code repository → force **Reader** +- From `/essence` → default **Reader** (user is in design-analysis state) + +| Mode | When | Entry | +|---|---|---| +| **Runnable** | Report confirms the project is a runnable code repository and the user wants to learn by running and changing it | Start from environment and first execution | +| **Reader** | Project has no runtime, or the user is studying design/architecture, or the prerequisite report is from `/essence` | Start from guided reading | + +State the selected mode before proceeding. Do not re-scan the project — use the prerequisite report to decide. + +## Teaching Interaction Rules + +`/follow` must teach by guidance, not by dumping answers: +- explain the purpose of the current step first +- give the user an observation point or action point +- ask the user to predict, try, or explain before revealing the answer +- then reveal, correct, or deepen the explanation +- never say "go read the code" as a standalone instruction. When referencing code, always start with: what design idea this code embodies, why it matters in the overall architecture, and what the user should pay attention to + +## Runnable Check + +Before Runnable mode, confirm from the **prerequisite report** (do not re-scan the project): +- If the report identified the target as a code repository with a recognized runtime (`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile`, `build.gradle`, `pom.xml`, `CMakeLists.txt`, etc.), proceed with Runnable. +- If the report classified it as non-code, or no runtime entrypoint was found, switch to Reader and explain why. +- If the prerequisite is `/essence`, confirm with the user: essence is design-focused, Reader is the natural fit. Allow Runnable only if the user explicitly insists. +- Do not introduce a third mode. + +## Runnable Mode Flow +1. Confirm environment and prerequisites. +2. Let the user run the project. +3. Let the user make one safe change. +4. Walk the main flow together. +5. Give one small exercise. +6. Review what they learned. + +## Reader Mode Flow +1. Frame the learning goal around a core design or architectural idea, not a single file. +2. Walk through the design concept layer by layer: problem → approach → implementation → tradeoff. +3. Ask the user questions that probe understanding ("Why did the author choose this approach over a simpler one?"), not just prediction ("What happens next?"). +4. Use diagrams or structured summaries to connect the dots between files and design ideas. +5. Give one reasoning exercise that tests whether the user can apply the design pattern elsewhere. +6. Review what they learned. + +## Boundary Rules + +`/follow` must: +- depend on `/explore` or `/essence` +- guide the user interactively +- adapt between code and non-code repositories through Runnable or Reader emphasis + +`/follow` must not: +- rescan the whole project as a new analyzer +- reference retired skills as prerequisites +- add any third learning mode +- execute commands or write code for the user + +## Outcome + +``` +Follow Session: {project name} +Mode: runnable / reader +Prerequisite report: /explore or /essence +Exercise result: completed / partial / too hard +Next direction: {suggested follow-up} +Status: complete +``` + +After the review, stop. Ask whether the user wants another exercise or wants to end the session. diff --git a/skills/follow/references/env-detect.md b/skills/follow/references/env-detect.md new file mode 100644 index 0000000..80ab2af --- /dev/null +++ b/skills/follow/references/env-detect.md @@ -0,0 +1,113 @@ +# Environment Detection Rules + +How to detect the runtime environment and guide the user through setup in `/follow`. + +## Language Detection from Config + +Check these files in order. The first match is the primary language. + +| Config file | Language | Runtime check | Install command | +|---|---|---|---| +| `package.json` | JavaScript/TypeScript | `node --version` | nvm or official installer | +| `pyproject.toml` | Python | `python --version` | pyenv or python.org | +| `go.mod` | Go | `go version` | golang.org/dl | +| `Cargo.toml` | Rust | `rustc --version` | rustup | +| `pom.xml` | Java | `java -version` | SDKMAN or official | +| `build.gradle` / `build.gradle.kts` | Java/Kotlin | `java -version` | SDKMAN | +| `Gemfile` | Ruby | `ruby --version` | rvm or rbenv | +| `*.csproj` | C#/.NET | `dotnet --version` | .NET SDK | +| `CMakeLists.txt` | C/C++ | `gcc --version` or `clang --version` | System package manager | +| `swift package.json` | Swift | `swift --version` | Xcode or swift.org | + +## Dependency Installation + +Once language is detected, guide the user: + +### JavaScript/TypeScript +```bash +# Check which package manager is used +if [ -f "yarn.lock" ]; then yarn install +elif [ -f "pnpm-lock.yaml" ]; then pnpm install +elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then bun install +else npm install +fi +``` + +### Python +```bash +# Modern Python projects +pip install -e . +# Or with requirements +pip install -r requirements.txt +# Or with poetry +poetry install +# Or with uv +uv pip install -r requirements.txt +``` + +### Go +```bash +go mod download +``` + +### Rust +```bash +cargo build +``` + +### Java (Maven) +```bash +mvn install +``` + +### Java (Gradle) +```bash +./gradlew build +# or +gradle build +``` + +## Run Command Detection + +How to start the project: + +| Source | Command | +|---|---| +| `package.json` → `scripts.dev` | `npm run dev` | +| `package.json` → `scripts.start` | `npm start` | +| `Makefile` → `dev` target | `make dev` | +| `Makefile` → `run` target | `make run` | +| `pyproject.toml` (Poetry) | `poetry run python main.py` | +| `go.mod` → `package main` | `go run main.go` | +| `Cargo.toml` → `[[bin]]` | `cargo run` | +| `docker-compose.yml` exists | `docker-compose up` | +| `Dockerfile` exists, no compose | `docker build -t app . && docker run app` | + +## Common Environment Issues + +| Error | Cause | Fix | +|---|---|---| +| `command not found: node` | Node.js not installed | Install Node.js (recommend LTS) | +| `ModuleNotFoundError` | Python deps not installed | Run `pip install -r requirements.txt` | +| `EACCES: permission denied` | Global install without sudo | Use nvm/fnm, or prefix with sudo | +| `ENOENT: no such file` | Wrong working directory | `cd` to project root first | +| `port already in use` | Another process on same port | Kill the process or use different port | +| `go: cannot find main module` | Outside Go module | `cd` to directory with `go.mod` | +| `error: could not find Cargo.toml` | Outside Rust project | `cd` to directory with `Cargo.toml` | +| `java.lang.UnsupportedClassVersionError` | Wrong Java version | Match JDK version to project requirement | +| `npm ERR! code ERESOLVE` | Dependency conflict | Try `npm install --legacy-peer-deps` | + +## Detection Script for /follow + +```bash +# Quick environment check +echo "=== Environment ===" +node --version 2>/dev/null || echo "Node.js: not installed" +python --version 2>/dev/null || echo "Python: not installed" +go version 2>/dev/null || echo "Go: not installed" +rustc --version 2>/dev/null || echo "Rust: not installed" +java -version 2>/dev/null || echo "Java: not installed" +echo "PWD: $(pwd)" +``` + +Run this at the start of `/follow` Step 1 to understand what's available.