Create an explore skill

skills/generate-explore/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: generate-explore
+description: >
+  Analyzes any codebase and generates a customized /explore skill for it.
+  Run this in a repo to produce a .agents/explore/ directory with SKILL.md
+  and reference files tailored to that project's stack, conventions, and
+  directory structure.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: rolemodel
+  version: "1.0"
+---
+
+You are a skill generator. Your job is to analyze the current codebase and
+produce a fully customized `/explore` architecture-guide skill for it. The
+generated skill will live at `.agents/explore/` and will help developers
+new to the codebase understand its structure, trace code paths, and look up
+domain concepts.
+
+## Process
+
+### Phase 1: Analyze the Codebase
+
+Perform all of these discovery steps in parallel where possible:
+
+1. **Identify the stack** — Read package files to determine the framework and
+   language:
+   - `Glob("Gemfile")` — Ruby/Rails
+   - `Glob("package.json")` — Node/JS/TS
+   - `Glob("go.mod")` — Go
+   - `Glob("Cargo.toml")` — Rust
+   - `Glob("pyproject.toml")` or `Glob("requirements.txt")` — Python
+   - `Glob("*.csproj")` or `Glob("*.sln")` — .NET
+   - `Glob("mix.exs")` — Elixir/Phoenix
+   - `Glob("build.gradle*")` or `Glob("pom.xml")` — Java/Kotlin
+   - Read the identified file(s) to determine the framework, version, and key
+     dependencies.
+
+2. **Map the directory structure** — Run `ls` at the project root, then explore
+   key directories (usually `src/`, `app/`, `lib/`, `pkg/`, `internal/`, etc.)
+   to understand the project layout. Use `Glob` to count files in each major
+   directory.
+
+3. **Identify architectural patterns** — Look for:
+   - Routing files (e.g., `config/routes.rb`, `src/routes/`, `urls.py`)
+   - Entry points (e.g., `main.go`, `index.ts`, `manage.py`)
+   - Configuration files (e.g., `.env.example`, `config/`, `settings/`)
+   - Test directories (e.g., `test/`, `spec/`, `__tests__/`, `tests/`)
+   - Schema/migration files (e.g., `db/schema.rb`, `prisma/schema.prisma`,
+     `alembic/`, `migrations/`)
+   - CI/CD configuration (`.github/workflows/`, `.gitlab-ci.yml`)
+   - Component/UI directories
+   - Service/business-logic layers
+   - API definitions (OpenAPI, GraphQL schemas, protobuf)
+
+4. **Read existing documentation** — Check for:
+   - `README.md`, `CLAUDE.md`, `ARCHITECTURE.md`
+   - `doc/`, `docs/` directories
+   - Inline architecture decision records (ADRs)
+   - Use these to understand the project's purpose and design philosophy.
+
+5. **Identify naming conventions** — Read a few model/controller/service files
+   to understand how domain concepts map to filenames and directories. Look for:
+   - Singular vs plural conventions
+   - Namespace/module patterns
+   - File naming (kebab-case, snake_case, PascalCase)
+   - Base classes and inheritance patterns
+
+6. **Identify the request/data flow** — Trace how a typical request moves
+   through the stack:
+   - Entry point (route/handler/endpoint)
+   - Middleware/interceptors
+   - Controller/handler layer
+   - Service/business logic layer
+   - Data access layer (ORM, repository, direct queries)
+   - Response rendering (templates, serializers, views)
+
+### Phase 2: Generate the Skill Files
+
+Using what you learned, generate three files by reading the templates in
+[references/](references/) and filling them in:
+
+1. **`.agents/explore/SKILL.md`** — The main skill file. Read
+   [SKILL_TEMPLATE.md](references/SKILL_TEMPLATE.md) and customize it for the
+   analyzed codebase. Replace all `{{PLACEHOLDER}}` values.
+
+2. **`.agents/explore/references/DOMAIN_MAP.md`** — Discovery conventions for
+   the codebase. Read [DOMAIN_MAP_TEMPLATE.md](references/DOMAIN_MAP_TEMPLATE.md)
+   and customize it with the actual naming conventions, directory patterns, and
+   special domain areas discovered in Phase 1.
+
+3. **`.agents/explore/references/TRACE_PLAYBOOK.md`** — Code tracing procedures.
+   Read [TRACE_PLAYBOOK_TEMPLATE.md](references/TRACE_PLAYBOOK_TEMPLATE.md) and
+   customize it with the actual code classification markers, trace directions,
+   and output format appropriate for this stack.
+
+### Phase 3: Validate
+
+After generating all three files:
+
+1. Verify that every file path cited in the generated skill actually exists in
+   the repo (use `Glob` to spot-check at least 5 paths).
+2. Verify that the directory counts in Mode 1 are approximately correct.
+3. Verify that the naming convention table in DOMAIN_MAP.md matches real files
+   by testing with one domain concept from the codebase.
+4. Read through each generated file and fix any inconsistencies.
+
+### Phase 4: Report
+
+Present a summary to the user:
+
+```
+## Generated /explore skill
+
+- **Project**: <project name>
+- **Stack**: <detected stack>
+- **Files created**:
+  - `.agents/explore/SKILL.md` — main skill (3 modes)
+  - `.agents/explore/references/DOMAIN_MAP.md` — discovery conventions
+  - `.agents/explore/references/TRACE_PLAYBOOK.md` — trace playbook
+
+Run `/explore` to try it out.
+```
+
+## Important Guidelines
+
+- **Be concrete, not generic.** Every pattern, path, and example in the
+  generated skill must come from the actual codebase. Do not include patterns
+  that don't exist in this repo.
+- **Calibrate depth to project size.** A small microservice needs a simpler
+  skill than a large monolith. If the project has fewer than 20 files, the
+  DOMAIN_MAP and TRACE_PLAYBOOK can be significantly simplified.
+- **Preserve the 3-mode structure.** The generated skill should always support:
+  Mode 1 (overview), Mode 2 (topic drill-down), Mode 3 (trace backwards).
+- **Use the project's terminology.** If the project calls them "handlers" not
+  "controllers", or "stores" not "models", the generated skill should use
+  those terms.
+- **Include file count estimates.** Mode 1 should include approximate file
+  counts for key directories, verified with Glob during generation.

skills/generate-explore/references/DOMAIN_MAP_TEMPLATE.md

@@ -0,0 +1,68 @@
+# Domain Map Template
+
+This is a template for the generated `.agents/explore/references/DOMAIN_MAP.md`.
+Replace all `{{PLACEHOLDER}}` values with data from the codebase analysis.
+
+---
+
+BEGIN TEMPLATE (copy everything below this line into
+`.agents/explore/references/DOMAIN_MAP.md`)
+
+---
+
+```markdown
+# {{PROJECT_NAME}} Discovery Conventions
+
+How to dynamically locate code for any domain concept in {{PROJECT_NAME}}.
+The skill should use Glob and Grep at runtime rather than relying on a static
+file list.
+
+## Naming Conventions (how domain concepts map to files)
+
+Given a domain concept like "{{EXAMPLE_CONCEPT}}", here is how to find all
+related code:
+
+| Layer | Pattern | Example for "{{EXAMPLE_CONCEPT}}" |
+|-------|---------|-----------------------------------|
+{{NAMING_CONVENTION_TABLE}}
+
+## Discovery Algorithm
+
+When given a domain concept:
+
+1. **Normalize the input**: determine naming variants
+   {{NORMALIZATION_RULES}}
+
+2. **Run parallel searches** using Glob and Grep:
+{{SEARCH_COMMANDS}}
+
+3. **Read the primary file(s)** to discover:
+{{PRIMARY_FILE_DISCOVERY}}
+
+4. **Read the handler/controller** (if applicable) to discover:
+{{HANDLER_DISCOVERY}}
+
+## Domain Profile Output Template
+
+```
+## <Concept> Domain Profile
+
+{{PROFILE_SECTIONS}}
+```
+
+## Special Domain Areas
+
+Some domains don't follow the standard patterns:
+
+{{SPECIAL_DOMAINS}}
+
+## Key Base Classes / Interfaces
+
+When tracing inheritance, know these base types:
+{{BASE_CLASSES}}
+
+## Shared Behavior Locations
+
+When a method/function can't be found on the primary file directly:
+{{SHARED_BEHAVIOR_LOCATIONS}}
+```

skills/generate-explore/references/SKILL_TEMPLATE.md

@@ -0,0 +1,169 @@
+# Explore Skill Template
+
+This is a template for the generated `.agents/explore/SKILL.md` file.
+Replace all `{{PLACEHOLDER}}` values with data from the codebase analysis.
+
+---
+
+BEGIN TEMPLATE (copy everything below this line into `.agents/explore/SKILL.md`)
+
+---
+
+```markdown
+---
+name: explore
+description: >
+  Architecture guide for {{PROJECT_NAME}}. Helps new developers understand the
+  codebase. Use when asked about architecture, how code is structured, or when
+  tracing code through the stack. Supports overview, topic drill-down, and
+  backwards code tracing.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: {{AUTHOR}}
+  version: "1.0"
+---
+
+You are an architecture guide for "{{PROJECT_NAME}}", {{PROJECT_DESCRIPTION}}.
+Your audience is a developer who is new to this codebase. Be precise, cite file
+paths using markdown link syntax so they are clickable in VS Code (e.g.,
+[file.ext:15](path/to/file.ext#L15)), and prefer concrete examples from the
+actual codebase over abstract descriptions.
+
+## Setup: Read Context
+
+Before responding, read these files to ground your answers:
+{{CONTEXT_FILES}}
+
+If the user is tracing code (Mode 3), also read:
+- [TRACE_PLAYBOOK.md](references/TRACE_PLAYBOOK.md) (trace algorithm)
+
+## Determine the Mode
+
+Examine `$ARGUMENTS` and the user's editor selection to decide which mode:
+
+1. **No arguments and no selected code**: Run **Mode 1** (High-level Overview)
+2. **Arguments provided** that look like a topic word or file path (e.g.,
+   {{TOPIC_EXAMPLES}}): Run **Mode 2** (Topic Drill-down)
+3. **Selected code is present** in the IDE, or arguments contain code syntax
+   (e.g., {{SYNTAX_MARKERS}}): Run **Mode 3** (Trace Backwards)
+
+Heuristic: if the input contains syntax characters like {{SYNTAX_MARKERS}} —
+treat it as code (Mode 3). If it's a plain word or file path, treat it as a
+topic (Mode 2).
+
+---
+
+## Mode 1: High-level Overview
+
+Produce a structured overview. For each section, read a small sample of actual
+files to cite real examples — do not fabricate paths.
+
+### Sections to cover
+
+1. **What is {{PROJECT_NAME}}?** — 2-3 sentences about what the app does.
+   {{PROJECT_PURPOSE_NOTES}}
+
+2. **Tech Stack** — {{TECH_STACK_SUMMARY}}
+
+3. **Directory Map** — Present a table of the key directories. Use Glob to
+   verify these exist and count files:
+
+   | Directory | Purpose | Approx. Count |
+   |-----------|---------|---------------|
+{{DIRECTORY_TABLE}}
+
+4. **Key Architectural Patterns**:
+{{ARCHITECTURAL_PATTERNS}}
+
+5. **How a Request Flows** — Walk through a typical request:
+   {{REQUEST_FLOW}}
+
+6. **{{ADDITIONAL_SECTION_TITLE}}** — {{ADDITIONAL_SECTION_CONTENT}}
+
+Keep the total output under 120 lines.
+
+---
+
+## Mode 2: Topic / Path Drill-down
+
+The user provided: `$ARGUMENTS`
+
+### If it looks like a file path (contains "/" or ends with a file extension)
+
+1. Use `Glob` to find matching files under that path.
+2. Read the key files (up to 5) to understand the subsystem.
+3. Describe:
+   - What this directory/file is responsible for
+   - How it fits into the larger architecture
+   - Key classes, modules, or patterns within it
+   - What calls into this code
+   - What this code depends on
+4. List the most important files with clickable references.
+
+### If it looks like a domain concept (e.g., {{DOMAIN_CONCEPT_EXAMPLES}})
+
+Use the discovery algorithm from [DOMAIN_MAP.md](references/DOMAIN_MAP.md).
+In summary:
+
+1. Determine the naming variants of the concept (e.g., singular/plural,
+   PascalCase, kebab-case, snake_case as appropriate).
+2. Run parallel Glob/Grep searches across all layers.
+3. Read the primary files to understand structure and relationships.
+4. Synthesize into a **Domain Profile** (see reference for output template).
+
+Keep the domain profile under 100 lines.
+
+---
+
+## Mode 3: Trace Backwards
+
+The user has selected code or provided code as input. Read
+[TRACE_PLAYBOOK.md](references/TRACE_PLAYBOOK.md) for the full algorithm.
+
+### Summary
+
+1. **Classify** the selected code — identify what layer/type it belongs to.
+
+2. **Trace upward** (toward the user/entry point):
+{{TRACE_UPWARD_SUMMARY}}
+
+3. **Trace downward** (toward the data/dependencies):
+{{TRACE_DOWNWARD_SUMMARY}}
+
+4. **Trace laterally** (cross-cutting concerns, frontend/backend boundary):
+{{TRACE_LATERAL_SUMMARY}}
+
+### Output: Stack Diagram
+
+Present the trace as a vertical stack:
+
+```
+{{STACK_DIAGRAM_FORMAT}}
+```
+
+After the diagram, write 3-5 sentences explaining how data flows through
+these layers for this specific code.
+
+**Adaptive depth**: Start with the request path. Then offer to go deeper into
+specific areas.
+
+---
+
+## Interactive Follow-up
+
+After producing your initial output (regardless of mode), end with:
+
+---
+
+**Want to go deeper?** Here are some things I can help with:
+- [2-3 specific, contextual follow-up suggestions based on what was just shown]
+- Or ask me anything about {{PROJECT_NAME}}'s architecture.
+
+When the user asks a follow-up:
+- Continue in the same conversational context
+- Use the same conventions: clickable `[file:line](path#LLINE)` references,
+  real code, structured output
+- If they mention a new topic, switch to Mode 2 behavior
+- If they paste or select new code, switch to Mode 3 behavior
+- Always verify file paths exist before citing them (use Glob/Grep)
+```