commit
This commit is contained in:
aruo
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user