diff --git a/changelog/2026-04-30-skills-v0.5.0-consolidation.md b/changelog/2026-04-30-skills-v0.5.0-consolidation.md deleted file mode 100644 index b4dfd81..0000000 --- a/changelog/2026-04-30-skills-v0.5.0-consolidation.md +++ /dev/null @@ -1,136 +0,0 @@ -# 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/openspec/changes/archive/2026-05-19-add-clear-filters/design.md b/openspec/archive/2026-05-19-add-clear-filters/design.md similarity index 100% rename from openspec/changes/archive/2026-05-19-add-clear-filters/design.md rename to openspec/archive/2026-05-19-add-clear-filters/design.md diff --git a/openspec/changes/archive/2026-05-19-add-clear-filters/proposal.md b/openspec/archive/2026-05-19-add-clear-filters/proposal.md similarity index 100% rename from openspec/changes/archive/2026-05-19-add-clear-filters/proposal.md rename to openspec/archive/2026-05-19-add-clear-filters/proposal.md diff --git a/openspec/changes/archive/2026-05-19-add-clear-filters/specs/knowledge-filtering/spec.md b/openspec/archive/2026-05-19-add-clear-filters/specs/knowledge-filtering/spec.md similarity index 100% rename from openspec/changes/archive/2026-05-19-add-clear-filters/specs/knowledge-filtering/spec.md rename to openspec/archive/2026-05-19-add-clear-filters/specs/knowledge-filtering/spec.md diff --git a/openspec/changes/archive/2026-05-19-add-clear-filters/tasks.md b/openspec/archive/2026-05-19-add-clear-filters/tasks.md similarity index 100% rename from openspec/changes/archive/2026-05-19-add-clear-filters/tasks.md rename to openspec/archive/2026-05-19-add-clear-filters/tasks.md diff --git a/skills/essence/SKILL.md b/skills/essence/SKILL.md deleted file mode 100644 index d444511..0000000 --- a/skills/essence/SKILL.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -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 deleted file mode 100644 index b4ad9b8..0000000 --- a/skills/essence/references/essence-signals.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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 deleted file mode 100644 index 318a60a..0000000 --- a/skills/explore/SKILL.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -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 deleted file mode 100644 index f1dcf6a..0000000 --- a/skills/explore/references/analysis-methods.md +++ /dev/null @@ -1,98 +0,0 @@ -# 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 deleted file mode 100644 index 487a5be..0000000 --- a/skills/explore/references/flow-patterns.md +++ /dev/null @@ -1,173 +0,0 @@ -# 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 deleted file mode 100644 index fe27a78..0000000 --- a/skills/explore/scripts/collect-structure.sh +++ /dev/null @@ -1,120 +0,0 @@ -#!/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 deleted file mode 100644 index c6a158c..0000000 --- a/skills/follow/SKILL.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -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 deleted file mode 100644 index 80ab2af..0000000 --- a/skills/follow/references/env-detect.md +++ /dev/null @@ -1,113 +0,0 @@ -# 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.