diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..ee34c5b --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,13 @@ +{ + "name": "agentic-navigation-guide-marketplace", + "owner": { + "name": "agentic-navigation-guide contributors" + }, + "plugins": [ + { + "name": "agentic-navigation-guide", + "source": ".", + "description": "Full suite: skills, agents, commands, and hooks for navigation guide management" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..5f5b56e --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "agentic-navigation-guide", + "description": "Create, validate, and maintain navigation guides for AI coding assistants. Provides skills for authoring guides, agents for automated guide management, and hooks for continuous validation.", + "version": "0.2.0", + "author": { + "name": "agentic-navigation-guide contributors" + } +} diff --git a/AGENTIC_NAVIGATION_GUIDE.md b/AGENTIC_NAVIGATION_GUIDE.md index 485f2e8..1d6fb14 100644 --- a/AGENTIC_NAVIGATION_GUIDE.md +++ b/AGENTIC_NAVIGATION_GUIDE.md @@ -1,21 +1,44 @@ - src/ - - main.rs # Main entry point - - lib.rs # Core logic goes here + - main.rs # CLI entry point + - lib.rs # Core library exports - types.rs # Core data types - - errors.rs # Error handling - - parser.rs # logic for parsing guide from markdown - - validator.rs # logic for validating syntax of guide - - verifier.rs # logic for verifying guide against file system - - dumper.rs # file-system-hierarchy "dumping" logic + - errors.rs # Error types and messages + - parser.rs # Parse guides from markdown + - validator.rs # Validate guide syntax + - verifier.rs # Verify guide against filesystem + - dumper.rs # Generate guides from filesystem + - recursive.rs # Monorepo recursive verification - cli/ - - mod.rs + - mod.rs # CLI module root - check.rs # check subcommand - dump.rs # dump subcommand - init.rs # init subcommand - verify.rs # verify subcommand +- .claude-plugin/ + - plugin.json # Plugin metadata + - marketplace.json # Marketplace definition +- skills/ + - authoring-guide.md # Creating new guides + - summarizing-items.md # Writing good comments + - revising-guide.md # Updating existing guides + - configuring-hooks.md # Hook setup documentation +- agents/ + - summarize-item.md # Summarize single file/directory + - create-guide.md # Create guide from scratch + - refresh-guide.md # Update existing guide +- commands/ + - setup-guide.md # Setup repository with guide + - update-guide.md # Update existing guide + - check-guide.md # Check guide syntax + - verify-guide.md # Verify guide accuracy +- hooks/ + - hooks.json # PostToolUse hook config +- scripts/ + - pre-commit # Git pre-commit hook script - Cargo.toml +- Makefile # Development commands - README.md -- Specification.md # original project specification document -- ... # Additional project files (tests, examples, etc.) +- Specification.md # Format specification +- ... # Tests, CI configs, etc. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..ea9fa86 --- /dev/null +++ b/Makefile @@ -0,0 +1,59 @@ +# Makefile for agentic-navigation-guide development + +.PHONY: all build check test lint fmt clippy verify clean install-hooks + +# Default target +all: check + +# Build the project +build: + cargo build + +# Quick check without building +check: + cargo check + +# Run all tests +test: + cargo test + +# Run all linting checks (same as pre-commit hook) +lint: fmt-check clippy + +# Check formatting +fmt-check: + cargo fmt -- --check + +# Format code +fmt: + cargo fmt + +# Run clippy with warnings as errors +clippy: + cargo clippy -- -D warnings + +# Verify navigation guide +verify: + cargo run -- verify + +# Clean build artifacts +clean: + cargo clean + +# Install pre-commit hook +install-hooks: + @echo "Installing pre-commit hook..." + @cp scripts/pre-commit .git/hooks/pre-commit 2>/dev/null || \ + (gitdir=$$(cat .git 2>/dev/null | sed 's/gitdir: //'); \ + if [ -n "$$gitdir" ]; then \ + cp scripts/pre-commit "$$gitdir/hooks/pre-commit"; \ + else \ + echo "Could not find git hooks directory"; \ + exit 1; \ + fi) + @chmod +x .git/hooks/pre-commit 2>/dev/null || true + @echo "Pre-commit hook installed!" + +# Run all CI checks locally +ci: lint test verify + @echo "All CI checks passed!" diff --git a/agents/create-guide.md b/agents/create-guide.md new file mode 100644 index 0000000..8726431 --- /dev/null +++ b/agents/create-guide.md @@ -0,0 +1,143 @@ +--- +name: create-guide +description: Create a complete navigation guide for a repository from scratch. Use when setting up a new project with no existing guide. +--- + +# Create Guide Agent + +This agent creates a comprehensive navigation guide for a repository by analyzing its structure and generating meaningful comments. + +## Process + +### Step 1: Generate Initial Structure + +Run the dump command to get the directory structure: + +```bash +agentic-navigation-guide dump --depth 3 --exclude target --exclude node_modules --exclude .git --exclude __pycache__ --exclude .venv --exclude dist --exclude build +``` + +This provides the raw structure to work from. + +### Step 2: Identify Key Files + +Focus on files that are most important for navigation: + +**High priority (always include with comments):** +- Entry points (`main.rs`, `index.ts`, `app.py`, `main.go`) +- Library roots (`lib.rs`, `mod.rs`, `__init__.py`) +- Configuration (`Cargo.toml`, `package.json`, `pyproject.toml`) +- Core business logic files +- API definitions + +**Medium priority (include, comment if non-obvious):** +- Module directories +- Test directories (top-level) +- Documentation files + +**Low priority (use placeholders or omit):** +- Individual test files +- Generated files +- Build configuration details +- IDE settings + +### Step 3: Analyze and Comment + +For each important file/directory: + +1. Read the file or examine directory contents +2. Identify primary purpose +3. Generate 5-10 word comment +4. Use project-specific terminology + +### Step 4: Structure the Guide + +Build the guide with: +- Proper indentation (2 spaces) +- Directories ending with `/` +- Comments after `#` +- Placeholders (`...`) for less important areas + +### Step 5: Write the Guide + +Create `AGENTIC_NAVIGATION_GUIDE.md`: + +```markdown + +- src/ + - main.rs # Entry point comment + - lib.rs # Library root comment + - module/ + - mod.rs # Module entry + - ... # Module internals +- tests/ + - ... # Test files +- Cargo.toml +- README.md + +``` + +### Step 6: Verify + +Run verification to catch any errors: + +```bash +agentic-navigation-guide verify +``` + +Fix any issues reported. + +### Step 7: Integrate with CLAUDE.md + +Check if `CLAUDE.md` exists: +- If yes, suggest adding `@AGENTIC_NAVIGATION_GUIDE.md` to include the guide +- If no, offer to create a minimal CLAUDE.md with the reference + +## Output + +The agent produces: +1. `AGENTIC_NAVIGATION_GUIDE.md` - The navigation guide file +2. Verification that the guide is valid +3. Suggestion for CLAUDE.md integration + +## Example Output + +For a typical Rust project: + +```markdown + +- src/ + - main.rs # CLI entry point, argument parsing + - lib.rs # Public API exports + - config.rs # Configuration loading from env/files + - db/ + - mod.rs # Database module root + - connection.rs # PostgreSQL connection pool + - migrations.rs # Schema migration runner + - ... # Query implementations + - api/ + - mod.rs # API module root + - routes.rs # HTTP route definitions + - handlers.rs # Request handlers + - middleware.rs # Auth and logging middleware + - models/ + - mod.rs # Domain models + - ... # Individual model definitions +- tests/ + - integration/ + - ... # Integration tests +- migrations/ + - ... # SQL migration files +- Cargo.toml # Project manifest +- README.md +- ... # Config files, CI, etc. + +``` + +## Guidelines + +1. **Don't over-document** - Focus on navigation value, not completeness +2. **Use placeholders liberally** - Better than listing every file +3. **Match project conventions** - Use terminology from the codebase +4. **Verify before delivering** - Always run verification +5. **Consider the audience** - What would help an AI assistant navigate? diff --git a/agents/refresh-guide.md b/agents/refresh-guide.md new file mode 100644 index 0000000..2f53749 --- /dev/null +++ b/agents/refresh-guide.md @@ -0,0 +1,199 @@ +--- +name: refresh-guide +description: Update an existing navigation guide to match the current filesystem state. Use when verification fails or after significant codebase changes. +--- + +# Refresh Guide Agent + +This agent updates an existing navigation guide to reflect filesystem changes while preserving existing comments and style. + +## Process + +### Step 1: Run Verification + +Check current state: + +```bash +agentic-navigation-guide verify +``` + +If verification passes, the guide is already up to date. Report success and exit. + +### Step 2: Parse Verification Errors + +Common error types to handle: + +| Error | Meaning | Action | +|-------|---------|--------| +| `path does not exist` | File/dir was deleted | Remove entry | +| `expected directory, found file` | Type changed | Update entry (remove `/`) | +| `expected file, found directory` | Type changed | Update entry (add `/`) | +| `placeholder has no unlisted items` | All items now listed | Remove placeholder or add comment | + +### Step 3: Get Current Filesystem State + +Generate fresh structure: + +```bash +agentic-navigation-guide dump --depth 3 --exclude target --exclude node_modules --exclude .git +``` + +Compare with existing guide to identify: +- New files/directories not in guide +- Structural changes (moves, renames) + +### Step 4: Read Existing Guide + +Read `AGENTIC_NAVIGATION_GUIDE.md` and note: +- Existing comment style (terse vs. detailed) +- Ordering convention (alphabetical, by importance, etc.) +- Which items have comments vs. which don't +- Placeholder usage patterns + +### Step 5: Make Updates + +**For each verification error:** + +1. **Deleted items**: Remove the entry from the guide +2. **Type changes**: Update the path (add/remove trailing `/`) +3. **Stale placeholders**: Either remove or add a comment + +**For new files/directories:** + +1. Determine if important enough to add (entry points, core modules) +2. Generate comment matching existing style +3. Insert in appropriate location maintaining order + +**For moved/renamed items:** + +1. Find the old entry +2. Update path to new location +3. Preserve the existing comment if still accurate +4. Adjust indentation if hierarchy changed + +### Step 6: Preserve Style + +Match the existing guide's conventions: + +```markdown +# If existing comments are short: +- new_file.rs # Token validation + +# If existing comments are descriptive: +- new_file.rs # Validates JWT tokens and checks expiry dates +``` + +### Step 7: Verify Again + +```bash +agentic-navigation-guide verify +``` + +Repeat steps 4-6 until verification passes. + +### Step 8: Report Changes + +Summarize what was updated: +- Files/directories removed +- Files/directories added +- Paths updated +- Comments modified + +## Example Refresh + +### Before (with errors) + +Guide: +```markdown + +- src/ + - main.rs # Entry point + - old_module.rs # Old module + - utils/ + - helpers.rs + +``` + +Errors: +``` +line 4: path 'src/old_module.rs' does not exist +line 6: path 'src/utils/helpers.rs' does not exist +``` + +Current filesystem: +``` +src/ + main.rs + new_module.rs + lib/ + helpers.rs +``` + +### After (fixed) + +```markdown + +- src/ + - main.rs # Entry point + - new_module.rs # Replaces old_module + - lib/ + - helpers.rs # Moved from utils/ + +``` + +Changes made: +- Removed `old_module.rs` (deleted) +- Added `new_module.rs` (new file) +- Renamed `utils/` to `lib/` (directory renamed) +- Moved `helpers.rs` under `lib/` (file moved) + +## Handling Edge Cases + +### Large-Scale Restructuring + +If many files changed, consider: +1. Running `agentic-navigation-guide dump` for complete new structure +2. Manually merging comments from old guide to new structure +3. This is faster than updating entry by entry + +### New Subdirectory with Many Files + +Instead of listing all files: +```markdown +- new_feature/ + - mod.rs # Feature module root + - ... # Implementation files +``` + +### Entire Directory Deleted + +Remove the directory entry AND all its children from the guide. + +### File Became Directory (or vice versa) + +This usually indicates significant restructuring. Check if the purpose changed: +```markdown +# Before: single file +- auth.rs # Authentication logic + +# After: became a module directory +- auth/ + - mod.rs # Auth module root + - oauth.rs # OAuth2 implementation + - jwt.rs # JWT handling +``` + +## Output + +The agent produces: +1. Updated `AGENTIC_NAVIGATION_GUIDE.md` +2. Successful verification +3. Summary of changes made + +## Guidelines + +1. **Preserve comments** - Existing comments represent human knowledge +2. **Match style** - New entries should look like existing ones +3. **Don't over-add** - Only add entries that help navigation +4. **Verify iteratively** - Fix one category of errors at a time +5. **Report clearly** - Tell the user exactly what changed diff --git a/agents/summarize-item.md b/agents/summarize-item.md new file mode 100644 index 0000000..377a05d --- /dev/null +++ b/agents/summarize-item.md @@ -0,0 +1,101 @@ +--- +name: summarize-item +description: Generate a navigation guide comment for a single file or directory. Use when you need to add or improve a comment for a specific item. +--- + +# Summarize Item Agent + +This agent analyzes a file or directory and generates a concise navigation guide comment. + +## Input + +Provide the path to a file or directory you want to summarize. + +## Process + +1. **Determine item type** + - If path ends with `/` or is a directory, treat as directory + - Otherwise, treat as file + +2. **For files:** + - Read the file content + - Identify the primary purpose/responsibility + - Note key functionality (entry point, exports, handlers, etc.) + - Look for doc comments or module-level documentation + +3. **For directories:** + - List contents to understand scope + - Identify the common theme or subsystem + - Read any `mod.rs`, `index.ts`, `__init__.py`, or similar entry points + +4. **Generate comment:** + - Keep to 5-10 words + - Focus on PURPOSE, not implementation + - Use active voice when possible + - Match project terminology + +## Output Format + +For files: +``` +filename.ext # Your generated comment +``` + +For directories: +``` +dirname/ # Your generated comment +``` + +## Examples + +### Example 1: Rust Entry Point + +Input: `src/main.rs` + +Analysis: File contains `fn main()`, argument parsing with clap, and signal handlers. + +Output: +``` +main.rs # CLI entry point, arg parsing, signal handling +``` + +### Example 2: Module Directory + +Input: `src/auth/` + +Analysis: Directory contains `mod.rs`, `oauth.rs`, `jwt.rs`, `session.rs`. + +Output: +``` +auth/ # Authentication: OAuth2, JWT, sessions +``` + +### Example 3: Configuration File + +Input: `config/settings.json` + +Analysis: JSON file with database URLs, feature flags, and API keys placeholder. + +Output: +``` +settings.json # Runtime config: DB, features, API keys +``` + +### Example 4: Test File + +Input: `tests/integration/api_test.rs` + +Analysis: Contains `#[test]` functions testing REST endpoints. + +Output: +``` +api_test.rs # Integration tests for REST API endpoints +``` + +## Guidelines + +1. **Read before summarizing** - Always examine actual content +2. **Be specific** - "OAuth2 token refresh" not "auth stuff" +3. **Match tone** - If existing comments are terse, be terse +4. **Skip obvious** - Don't comment `README.md` unless unusual +5. **Note entry points** - Highlight files that are starting points for exploration diff --git a/commands/check-guide.md b/commands/check-guide.md new file mode 100644 index 0000000..d17ab05 --- /dev/null +++ b/commands/check-guide.md @@ -0,0 +1,34 @@ +--- +description: Check navigation guide syntax without filesystem verification +--- + +# Check Navigation Guide Syntax + +Run `agentic-navigation-guide check` to validate the syntax and formatting of a navigation guide without checking against the filesystem. + +This command will: +- Parse the navigation guide from the markdown file +- Check for proper formatting (directories end with `/`, files don't) +- Verify consistent indentation (2 spaces per level) +- Check for valid path formats (no `.`, `..`, `./`, `../`) +- Validate placeholder (`...`) usage rules +- Report any syntax errors with line numbers + +This is useful when: +- You're editing a guide and want quick feedback on formatting +- You're working on a guide for a directory structure that doesn't exist yet +- You want to validate guide syntax in a CI pipeline before filesystem checks + +## Difference from `/verify-guide` + +- **`/check-guide`**: Only validates syntax and formatting rules +- **`/verify-guide`**: Validates syntax AND checks that paths exist in the filesystem + +## Options + +```bash +# Check a specific guide file +agentic-navigation-guide check --guide path/to/guide.md +``` + + diff --git a/commands/setup-guide.md b/commands/setup-guide.md new file mode 100644 index 0000000..4f2cb55 --- /dev/null +++ b/commands/setup-guide.md @@ -0,0 +1,55 @@ +--- +description: Set up a repository with a navigation guide, including initialization, customization, and CLAUDE.md integration +--- + +# Setup Navigation Guide + +Set up a complete navigation guide for this repository. + +## What This Command Does + +1. **Checks for existing guide** + - If `AGENTIC_NAVIGATION_GUIDE.md` exists, offers to update or replace it + +2. **Generates initial structure** + - Runs `agentic-navigation-guide init` with sensible defaults + - Excludes common build artifacts (`target/`, `node_modules/`, `.git/`, etc.) + +3. **Adds meaningful comments** + - Analyzes key files to generate helpful navigation comments + - Focuses on entry points, core modules, and configuration + +4. **Verifies the guide** + - Runs `agentic-navigation-guide verify` to ensure accuracy + +5. **Integrates with CLAUDE.md** + - If CLAUDE.md exists, suggests adding `@AGENTIC_NAVIGATION_GUIDE.md` + - If not, offers to create a minimal CLAUDE.md with the reference + +## Usage + +Simply run: +``` +/setup-guide +``` + +## Options + +You may be asked: +- Whether to overwrite an existing guide +- Which files deserve detailed comments +- Whether to create/update CLAUDE.md + +## After Setup + +Once complete, you should: +1. Review the generated comments and adjust as needed +2. Remove any entries that shouldn't be tracked +3. Add comments to important files that were missed +4. Run `/verify-guide` to confirm everything is correct + +## See Also + +- `/verify-guide` - Verify guide accuracy +- `/update-guide` - Update an existing guide +- `/check-guide` - Check guide syntax only diff --git a/commands/update-guide.md b/commands/update-guide.md new file mode 100644 index 0000000..87a5af5 --- /dev/null +++ b/commands/update-guide.md @@ -0,0 +1,68 @@ +--- +description: Update an existing navigation guide to match current filesystem state +--- + +# Update Navigation Guide + +Update the navigation guide to reflect recent changes to the codebase. + +## What This Command Does + +1. **Verifies current state** + - Runs `agentic-navigation-guide verify` to check for mismatches + +2. **If guide is valid** + - Reports "Navigation guide is up to date" + - No changes needed + +3. **If errors found** + - Identifies what changed (deleted files, new files, renames) + - Makes targeted updates to fix mismatches + - Preserves existing comments and style + - Adds comments for significant new files + +4. **Re-verifies** + - Confirms all issues are resolved + +5. **Reports changes** + - Summarizes what was added, removed, or modified + +## Usage + +Simply run: +``` +/update-guide +``` + +## When to Use + +Run this command after: +- Adding new files or directories +- Deleting files or directories +- Renaming or moving files +- Restructuring modules +- The post-tool-use hook reports guide issues + +## What Gets Updated + +| Change Type | Action | +|-------------|--------| +| Deleted file | Entry removed | +| New file | Entry added (with comment if important) | +| Renamed file | Path updated, comment preserved | +| Moved file | Path and indentation updated | +| Type change | Updated (file to dir or vice versa) | + +## Preserving Your Work + +The command preserves: +- Existing comments (won't overwrite your descriptions) +- Comment style (terse vs. detailed) +- Ordering conventions +- Placeholder patterns + +## See Also + +- `/verify-guide` - Check guide without making changes +- `/setup-guide` - Create a new guide from scratch +- `/check-guide` - Check syntax only diff --git a/commands/verify-guide.md b/commands/verify-guide.md new file mode 100644 index 0000000..15efd49 --- /dev/null +++ b/commands/verify-guide.md @@ -0,0 +1,34 @@ +--- +description: Verify navigation guide accuracy against current filesystem +--- + +# Verify Navigation Guide + +Run `agentic-navigation-guide verify` to check that the navigation guide in `AGENTIC_NAVIGATION_GUIDE.md` (or specified guide file) matches the current state of the filesystem. + +This command will: +- Parse the navigation guide from the markdown file +- Check for syntax errors (proper formatting, indentation, path conventions) +- Verify that all referenced paths exist in the filesystem +- Ensure directories end with `/` and files don't +- Report any mismatches or errors with line numbers + +## Options + +You can customize the verification by running the command with additional flags: + +```bash +# Verify a specific guide file +agentic-navigation-guide verify --guide path/to/guide.md + +# Verify relative to a specific root directory +agentic-navigation-guide verify --root /path/to/root + +# Recursively verify all guides in a monorepo +agentic-navigation-guide verify --recursive + +# Use custom guide name for recursive verification +agentic-navigation-guide verify --recursive --guide-name GUIDE.md +``` + + diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..a9a0747 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,13 @@ +{ + "PostToolUse": [ + { + "matcher": "Write|Edit|Bash", + "hooks": [ + { + "type": "command", + "command": "agentic-navigation-guide verify --post-tool-use-hook" + } + ] + } + ] +} diff --git a/scripts/pre-commit b/scripts/pre-commit new file mode 100755 index 0000000..8fe21b2 --- /dev/null +++ b/scripts/pre-commit @@ -0,0 +1,45 @@ +#!/bin/sh +# Pre-commit hook for agentic-navigation-guide +# Runs formatting and linting checks before allowing a commit +# +# To install this hook, run from the repository root: +# cp scripts/pre-commit .git/hooks/pre-commit +# chmod +x .git/hooks/pre-commit +# +# Or create a symlink: +# ln -sf ../../scripts/pre-commit .git/hooks/pre-commit + +set -e + +echo "Running pre-commit checks..." + +# Check formatting +echo "Checking formatting with rustfmt..." +if ! cargo fmt -- --check; then + echo "" + echo "ERROR: Code is not formatted correctly." + echo "Run 'cargo fmt' to fix formatting issues." + exit 1 +fi + +# Run clippy +echo "Running clippy linter..." +if ! cargo clippy -- -D warnings; then + echo "" + echo "ERROR: Clippy found issues." + echo "Fix the issues above before committing." + exit 1 +fi + +# Verify navigation guide (if the tool is built) +if command -v agentic-navigation-guide >/dev/null 2>&1; then + echo "Verifying navigation guide..." + if ! agentic-navigation-guide verify --pre-commit-hook; then + echo "" + echo "ERROR: Navigation guide verification failed." + echo "Update AGENTIC_NAVIGATION_GUIDE.md to match the filesystem." + exit 1 + fi +fi + +echo "All pre-commit checks passed!" diff --git a/skills/authoring-guide.md b/skills/authoring-guide.md new file mode 100644 index 0000000..246167c --- /dev/null +++ b/skills/authoring-guide.md @@ -0,0 +1,203 @@ +--- +name: authoring-guide +description: Create a new navigation guide from scratch. Use when setting up a guide for a repository that doesn't have one yet. +--- + +# Authoring a Navigation Guide + +This skill teaches you how to create an effective navigation guide from scratch. + +## File Format Basics + +A navigation guide is embedded in markdown using XML-like sentinel tags: + +```markdown + +- src/ + - main.rs # Entry point + - lib.rs # Core library +- Cargo.toml +- README.md + +``` + +### Core Syntax Rules + +1. **Directories** must end with `/`: + - `- src/` (correct) + - `- src` (incorrect - will be treated as a file) + +2. **Files** do NOT end with `/`: + - `- main.rs` (correct) + - `- main.rs/` (incorrect - will be treated as a directory) + +3. **Indentation** shows hierarchy: + - Use consistent spacing (2 spaces recommended) + - Children are indented one level deeper than their parent + - The first indented item sets the indent size for the entire guide + +4. **Comments** come after `#`: + - `- main.rs # Entry point for the application` + - Whitespace between path and `#` is optional + +5. **No blank lines** inside the guide block + +6. **No special directories**: `.`, `..`, `./`, `../` are forbidden + +## What to Include + +**DO include:** +- Source code directories (`src/`, `lib/`, `app/`) +- Configuration files (`Cargo.toml`, `package.json`, `pyproject.toml`) +- Documentation (`README.md`, `docs/`) +- Key entry points and core modules +- Test directories if they have complex structure + +**DO NOT include:** +- Build artifacts (`target/`, `dist/`, `build/`, `out/`) +- Dependency directories (`node_modules/`, `vendor/`, `.venv/`) +- Cache directories (`.cache/`, `__pycache__/`) +- IDE/editor directories (`.idea/`, `.vscode/` unless project-specific) +- Generated files (`.d.ts` from TypeScript, etc.) +- Git internals (`.git/`) + +## Writing Good Comments + +Comments should explain **purpose**, not repeat the filename. + +**Good comments:** +```markdown +- src/ + - auth/ + - oauth.rs # OAuth2 flow with token refresh + - jwt.rs # JWT creation and validation + - api/ + - handlers.rs # HTTP request handlers for REST endpoints + - middleware.rs # Request logging and auth middleware +``` + +**Bad comments:** +```markdown +- src/ + - auth/ + - oauth.rs # OAuth file + - jwt.rs # JWT code + - api/ + - handlers.rs # Handler functions + - middleware.rs # Middleware +``` + +Guidelines for comments: +- Keep to 5-10 words +- Use active voice ("Handles X" not "X handling") +- Focus on what an agent needs to know to navigate +- Use project-specific terminology + +## Advanced Features + +### Placeholders (`...`) + +Use `...` to indicate there are additional items not listed: + +```markdown + +- src/ + - main.rs # Entry point + - ... # Other source files +- tests/ + - integration/ + - auth_test.rs + - ... # Additional integration tests + +``` + +**Two types of placeholders:** + +1. **Without comment** - Must represent actual unlisted items: + ```markdown + - src/ + - main.rs + - ... # There MUST be other files in src/ not listed + ``` + +2. **With comment** - Can be used anywhere, even if all items are listed: + ```markdown + - plans/ + - phase-01.md # Completed + - ... # Future phases will appear here + ``` + +Rules: +- Placeholders cannot have children +- Cannot have two adjacent placeholders + +### Choice Expansion (`[option1, option2]`) + +Group related files on a single line: + +```markdown +- FooCoordinator[.h, .cpp] # Coordinates foo operations +``` + +Expands to: +```markdown +- FooCoordinator.h # Coordinates foo operations +- FooCoordinator.cpp # Coordinates foo operations +``` + +More examples: +```markdown +- Config[, .local].json # Config.json and Config.local.json +- src[/main, /lib].rs # src/main.rs and src/lib.rs +``` + +Rules: +- At most one `[...]` block per line +- Whitespace inside brackets is trimmed +- Use quotes for values with spaces/commas: `["with , comma"]` +- Escape special chars: `\,` `\"` `\\` `\[` `\]` + +### Ignoring Guides (`ignore=true`) + +Mark guides to skip verification (useful for documentation examples): + +```markdown + +- example/ + - fictional-file.rs + +``` + +## Complete Example + +Here's a well-structured guide for a Rust project: + +```markdown + +- src/ + - main.rs # CLI entry point, argument parsing + - lib.rs # Public API and module exports + - types.rs # Core domain types and structs + - errors.rs # Error types and conversion impls + - parser.rs # Config file parsing logic + - cli/ + - mod.rs # CLI module root + - commands.rs # Subcommand implementations + - ... # Additional CLI utilities +- tests/ + - integration/ + - ... # Integration test files +- Cargo.toml # Project manifest and dependencies +- README.md # Project documentation +- ... # License, CI configs, etc. + +``` + +## Workflow + +1. Run `agentic-navigation-guide init` to generate a starting point +2. Edit to add meaningful comments +3. Remove entries for build artifacts and generated files +4. Add placeholders where appropriate +5. Run `agentic-navigation-guide verify` to validate +6. Include in your CLAUDE.md: `@AGENTIC_NAVIGATION_GUIDE.md` diff --git a/skills/configuring-hooks.md b/skills/configuring-hooks.md new file mode 100644 index 0000000..b64921d --- /dev/null +++ b/skills/configuring-hooks.md @@ -0,0 +1,313 @@ +--- +name: configuring-hooks +description: Set up automated navigation guide verification with Claude Code hooks, GitHub Actions, or pre-commit hooks. +--- + +# Configuring Hooks for Navigation Guide Verification + +This skill teaches you how to set up automated verification of navigation guides using various hook systems. + +## Prerequisites + +Install the CLI tool: + +```bash +cargo install agentic-navigation-guide +``` + +Verify installation: + +```bash +agentic-navigation-guide --version +``` + +## Claude Code PostToolUse Hook + +The PostToolUse hook automatically verifies your guide after file system changes. + +### Using the Plugin (Recommended) + +Install the plugin and hooks are configured automatically: + +``` +/plugin marketplace add https://github.com/plx/agentic-navigation-guide +/plugin install agentic-navigation-guide@agentic-navigation-guide-marketplace +``` + +### Manual Configuration + +Create or edit `hooks/hooks.json` in your project: + +```json +{ + "PostToolUse": [ + { + "matcher": "Write|Edit|Bash", + "hooks": [ + { + "type": "command", + "command": "agentic-navigation-guide verify --post-tool-use-hook" + } + ] + } + ] +} +``` + +Or add to your `~/.claude/settings.json` for global use: + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit|Bash", + "hooks": [ + { + "type": "command", + "command": "agentic-navigation-guide verify --post-tool-use-hook" + } + ] + } + ] + } +} +``` + +### How It Works + +- **Matcher**: `Write|Edit|Bash` triggers on file writes, edits, and bash commands +- **Exit code 2**: The `--post-tool-use-hook` flag causes exit code 2 on failure (Claude Code's hook failure code) +- **Output**: Shows verification result; errors include line numbers + +## GitHub Actions + +Add a workflow to verify guides on every push and pull request. + +### Basic Workflow + +Create `.github/workflows/verify-guide.yml`: + +```yaml +name: Verify Navigation Guide + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + verify: + name: Verify Navigation Guide + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions-rust-lang/setup-rust-toolchain@v1 + + - name: Install agentic-navigation-guide + run: cargo install agentic-navigation-guide + + - name: Verify navigation guide + run: agentic-navigation-guide verify --github-actions-check +``` + +### Monorepo Workflow (Recursive) + +For projects with multiple guides: + +```yaml +name: Verify Navigation Guides + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + verify: + name: Verify All Navigation Guides + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions-rust-lang/setup-rust-toolchain@v1 + + - name: Install agentic-navigation-guide + run: cargo install agentic-navigation-guide + + - name: Verify all guides recursively + run: | + agentic-navigation-guide verify \ + --recursive \ + --exclude target \ + --exclude node_modules \ + --github-actions-check +``` + +### Using Environment Variable + +Alternative to `--github-actions-check`: + +```yaml +- name: Verify navigation guide + run: agentic-navigation-guide verify + env: + AGENTIC_NAVIGATION_GUIDE_EXECUTION_MODE: github-actions +``` + +### GitHub Actions Output + +On success: +``` +Navigation guide verified +``` + +On failure: +``` +AGENTIC_NAVIGATION_GUIDE.md:15: error: path 'src/deleted.rs' does not exist +``` + +The `file:line` format integrates with GitHub's annotation system. + +## hk (Lefthook) + +[hk](https://github.com/evilmartians/lefthook) is a fast Git hooks manager. + +### Installation + +```bash +# macOS +brew install lefthook + +# npm +npm install -g lefthook +``` + +### Configuration + +Create `lefthook.yml` in your project root: + +```yaml +pre-commit: + commands: + verify-navigation-guide: + run: agentic-navigation-guide verify --pre-commit-hook + fail_text: "Navigation guide verification failed" +``` + +### Enable Hooks + +```bash +lefthook install +``` + +### Pre-push Alternative + +To verify only before pushing: + +```yaml +pre-push: + commands: + verify-navigation-guide: + run: agentic-navigation-guide verify --pre-commit-hook +``` + +## Generic Pre-commit Hook + +For simple Git hooks without a framework. + +### Shell Script + +Create `.git/hooks/pre-commit`: + +```bash +#!/bin/sh + +# Verify navigation guide before commit +if ! agentic-navigation-guide verify --pre-commit-hook; then + echo "" + echo "Navigation guide verification failed." + echo "Please update AGENTIC_NAVIGATION_GUIDE.md to match filesystem." + echo "" + echo "Run 'agentic-navigation-guide verify' for details." + exit 1 +fi +``` + +Make it executable: + +```bash +chmod +x .git/hooks/pre-commit +``` + +### With pre-commit Framework + +If using [pre-commit](https://pre-commit.com/), add to `.pre-commit-config.yaml`: + +```yaml +repos: + - repo: local + hooks: + - id: verify-navigation-guide + name: Verify Navigation Guide + entry: agentic-navigation-guide verify --pre-commit-hook + language: system + pass_filenames: false + always_run: true +``` + +Then install: + +```bash +pre-commit install +``` + +## Execution Modes Comparison + +| Flag | Exit Code on Failure | Best For | +|------|---------------------|----------| +| (none) | 1 | Manual CLI use | +| `--post-tool-use-hook` | 2 | Claude Code hooks | +| `--pre-commit-hook` | 1 | Git pre-commit hooks | +| `--github-actions-check` | 1 | CI/CD pipelines | + +## Environment Variables + +Configure defaults via environment: + +| Variable | Values | Purpose | +|----------|--------|---------| +| `AGENTIC_NAVIGATION_GUIDE_EXECUTION_MODE` | `default`, `post-tool-use`, `pre-commit-hook`, `github-actions` | Set execution mode | +| `AGENTIC_NAVIGATION_GUIDE_LOG_MODE` | `quiet`, `default`, `verbose` | Control output verbosity | +| `AGENTIC_NAVIGATION_GUIDE_PATH` | Path | Default guide file path | +| `AGENTIC_NAVIGATION_GUIDE_ROOT` | Path | Default root directory | + +## Troubleshooting + +### Hook Not Running + +- **hk/lefthook**: Run `lefthook install` after changing config +- **Git hooks**: Check file is executable (`chmod +x`) +- **pre-commit**: Run `pre-commit install` after config changes + +### Command Not Found + +Ensure `agentic-navigation-guide` is in PATH: + +```bash +# Check installation +which agentic-navigation-guide + +# If using cargo install, ensure ~/.cargo/bin is in PATH +export PATH="$HOME/.cargo/bin:$PATH" +``` + +### False Positives in CI + +If CI fails but local passes: +- Check for OS-specific path issues (Windows vs Unix) +- Ensure `.gitignore` patterns match exclude patterns +- Verify the checkout includes all expected files diff --git a/skills/revising-guide.md b/skills/revising-guide.md new file mode 100644 index 0000000..6e267ec --- /dev/null +++ b/skills/revising-guide.md @@ -0,0 +1,269 @@ +--- +name: revising-guide +description: Update an existing navigation guide when the codebase changes. Use when files have been added, removed, renamed, or restructured. +--- + +# Revising an Existing Navigation Guide + +This skill teaches you how to update a navigation guide to keep it in sync with filesystem changes. + +## When to Update + +Update the guide after: +- **Adding** new files or directories +- **Deleting** files or directories +- **Renaming** or moving files +- **Restructuring** the codebase (e.g., reorganizing modules) +- **Changing file purposes** (update comments) + +## Update Process + +### Step 1: Identify Issues + +Run verification to see what's wrong: + +```bash +agentic-navigation-guide verify +``` + +Common errors: +- `path does not exist` - File was deleted or moved +- `expected directory, found file` - Type mismatch +- `expected file, found directory` - Type mismatch +- `placeholder has no unlisted items` - All items now listed + +### Step 2: Gather Current State + +See what actually exists: + +```bash +agentic-navigation-guide dump --depth 3 +``` + +Compare this output with your guide to identify: +- New files not in the guide +- Guide entries with no matching files +- Structural changes + +### Step 3: Make Updates + +**For deleted files:** Remove the entry from the guide. + +**For renamed files:** Update the path, keep the comment if still accurate. + +**For moved files:** Update the path to new location, adjust indentation. + +**For new files:** Add entries in the appropriate location with comments. + +**For restructured directories:** May need to reorganize multiple entries. + +### Step 4: Verify Again + +```bash +agentic-navigation-guide verify +``` + +Repeat until no errors remain. + +## Maintaining Consistency + +### Match Existing Style + +If existing comments use a pattern, follow it: + +```markdown +# If existing comments are terse: +- new-file.rs # Token validation + +# If existing comments are more detailed: +- new-file.rs # Validates JWT tokens and checks expiration +``` + +### Preserve Comment Tone + +```markdown +# If existing uses active voice: +- auth.rs # Handles OAuth2 flow +- new.rs # Validates user input # <-- match this style + +# If existing uses nouns: +- auth.rs # OAuth2 authentication +- new.rs # Input validation # <-- match this style +``` + +### Keep Ordering Conventions + +Some guides order entries: +- Alphabetically +- By importance +- Directories first, then files +- By module dependency + +Maintain whatever convention exists. + +## Handling Different Scenarios + +### Scenario: File Renamed + +Before: +```markdown +- src/ + - old_name.rs # Does something +``` + +After: +```markdown +- src/ + - new_name.rs # Does something +``` + +### Scenario: File Moved to New Directory + +Before: +```markdown +- src/ + - utils.rs # String helpers +``` + +After: +```markdown +- src/ + - helpers/ + - utils.rs # String helpers +``` + +### Scenario: New Module Added + +Before: +```markdown +- src/ + - main.rs + - lib.rs +``` + +After: +```markdown +- src/ + - main.rs + - lib.rs + - auth/ + - mod.rs # Auth module root + - oauth.rs # OAuth2 implementation + - jwt.rs # JWT handling +``` + +### Scenario: Directory Flattened + +Before: +```markdown +- src/ + - handlers/ + - api.rs + - web.rs +``` + +After: +```markdown +- src/ + - api_handlers.rs # Combined API handlers + - web_handlers.rs # Combined web handlers +``` + +### Scenario: Using Placeholders for Partial Updates + +When you don't want to enumerate everything: + +```markdown +- src/ + - main.rs # Entry point + - core/ + - important.rs # Key module - document this + - ... # Other core modules + - utils/ + - ... # Utility modules +``` + +## Dealing with Large Changes + +For major restructuring: + +1. **Option A: Incremental updates** + - Fix errors one at a time + - Verify after each change + - Slower but safer + +2. **Option B: Regenerate and merge** + - Run `agentic-navigation-guide dump` for new structure + - Manually merge comments from old guide + - Faster but requires care to preserve comments + +3. **Option C: Start fresh** + - Run `agentic-navigation-guide init` + - Re-add comments (may be needed for major rewrites) + +## Common Mistakes to Avoid + +### 1. Forgetting to update comments + +When a file's purpose changes, update the comment: + +```markdown +# Wrong - file now does more +- auth.rs # Basic auth # (but now also does OAuth) + +# Right +- auth.rs # Basic auth and OAuth2 +``` + +### 2. Leaving stale placeholders + +If you listed everything, remove the placeholder: + +```markdown +# Wrong - no other files exist +- src/ + - main.rs + - lib.rs + - ... # ERROR: no unlisted items + +# Right +- src/ + - main.rs + - lib.rs +``` + +Or add a comment to make it valid: +```markdown +- src/ + - main.rs + - lib.rs + - ... # Future modules +``` + +### 3. Inconsistent indentation + +All children must be indented the same amount: + +```markdown +# Wrong +- src/ + - main.rs + - lib.rs # <-- different indent + +# Right +- src/ + - main.rs + - lib.rs +``` + +## Quick Reference + +| Change | Action | +|--------|--------| +| File deleted | Remove entry | +| File added | Add entry with comment | +| File renamed | Update path | +| File moved | Update path and indentation | +| Directory deleted | Remove directory and all children | +| Directory added | Add directory and children | +| Purpose changed | Update comment | diff --git a/skills/summarizing-items.md b/skills/summarizing-items.md new file mode 100644 index 0000000..e235e42 --- /dev/null +++ b/skills/summarizing-items.md @@ -0,0 +1,177 @@ +--- +name: summarizing-items +description: Write concise, helpful comments for files and directories in a navigation guide. Use when adding or improving comments. +--- + +# Summarizing Files and Directories + +This skill teaches you how to write effective comments for navigation guide entries. + +## Comment Structure + +Comments appear after the `#` separator: + +```markdown +- path/to/file.rs # Your comment here +- directory/ # Description of what's inside +``` + +Whitespace between the path and `#` is flexible - use what looks clean. + +## Writing Effective Comments + +### Focus on Purpose, Not Name + +**Ask:** "Why would an agent need to look here?" + +| Bad (repeats name) | Good (explains purpose) | +|-------------------|-------------------------| +| `main.rs # main file` | `main.rs # CLI entry point, arg parsing` | +| `utils.rs # utilities` | `utils.rs # String manipulation helpers` | +| `auth/ # authentication` | `auth/ # OAuth2 and JWT token handling` | + +### Use Active Voice + +| Passive/Noun | Active | +|--------------|--------| +| `# Authentication handling` | `# Handles OAuth2 authentication` | +| `# Database connection` | `# Connects to PostgreSQL` | +| `# Error definitions` | `# Defines app-wide error types` | + +### Be Specific + +| Vague | Specific | +|-------|----------| +| `# Config stuff` | `# Runtime config from env vars` | +| `# API code` | `# REST handlers for /users endpoint` | +| `# Tests` | `# Unit tests for parser module` | + +### Keep It Short + +Aim for 5-10 words. If you need more, the file might be doing too much. + +| Too Long | Better | +|----------|--------| +| `# This file handles all the authentication logic including OAuth2 flows and JWT token validation` | `# OAuth2 and JWT authentication` | + +## Directory vs File Comments + +**Directories** describe the category or subsystem: +```markdown +- api/ # HTTP REST API layer +- db/ # Database access and migrations +- auth/ # Authentication and authorization +``` + +**Files** describe specific responsibilities: +```markdown +- api/ + - handlers.rs # Request handlers for all endpoints + - middleware.rs # Logging and auth middleware + - routes.rs # URL routing configuration +``` + +## Use Project Terminology + +Match the vocabulary used in the codebase: + +```markdown +# If the project calls them "coordinators" +- FooCoordinator.rs # Coordinates foo lifecycle + +# If the project uses "manager" +- SessionManager.rs # Manages user sessions + +# If the project has domain terms +- ledger.rs # Double-entry transaction ledger +``` + +## Anti-Patterns to Avoid + +### 1. Repeating the filename +```markdown +# BAD +- parser.rs # parser +- config.json # configuration file + +# GOOD +- parser.rs # Converts markdown to AST +- config.json # Build settings and feature flags +``` + +### 2. Being too vague +```markdown +# BAD +- utils.rs # utility functions +- helpers/ # helper code + +# GOOD +- utils.rs # Date formatting and string helpers +- helpers/ # Shared test fixtures and mocks +``` + +### 3. Multi-sentence comments +```markdown +# BAD +- auth.rs # This handles authentication. It supports both OAuth2 and basic auth. + +# GOOD +- auth.rs # OAuth2 and basic auth support +``` + +### 4. Implementation details +```markdown +# BAD +- cache.rs # Uses HashMap with LRU eviction + +# GOOD +- cache.rs # In-memory response caching +``` + +## Examples of Good Comments + +### Rust/Systems Project +```markdown +- src/ + - main.rs # CLI entry, signal handlers + - lib.rs # Public API exports + - parser/ + - mod.rs # Parser module root + - lexer.rs # Tokenizes input stream + - ast.rs # Abstract syntax tree types + - codegen/ + - mod.rs # Code generation module + - emit.rs # Emits target assembly +``` + +### Web Application +```markdown +- src/ + - app/ + - routes/ # URL route definitions + - controllers/ # Request handlers + - models/ # Database models (Prisma) + - services/ # Business logic layer + - lib/ + - auth.ts # JWT and session handling + - db.ts # Database connection pool +``` + +### Python Package +```markdown +- src/ + - mypackage/ + - __init__.py # Package exports + - core.py # Main algorithm implementation + - io.py # File reading and writing + - cli.py # Click command definitions +``` + +## When to Skip Comments + +Some entries are self-explanatory: +- `Cargo.toml` - obvious for Rust projects +- `package.json` - obvious for JS projects +- `README.md` - universal + +You can omit comments for these, or add them for consistency. diff --git a/src/types.rs b/src/types.rs index 44a45e1..49eda70 100644 --- a/src/types.rs +++ b/src/types.rs @@ -128,9 +128,10 @@ impl Default for NavigationGuide { } /// Execution mode for the CLI tool -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] pub enum ExecutionMode { /// Default execution mode + #[default] Default, /// Running as a post-tool-use hook PostToolUse, @@ -140,29 +141,18 @@ pub enum ExecutionMode { GitHubActions, } -impl Default for ExecutionMode { - fn default() -> Self { - Self::Default - } -} - /// Log level for output verbosity -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] pub enum LogLevel { /// Minimal output Quiet, /// Normal output + #[default] Default, /// Verbose output Verbose, } -impl Default for LogLevel { - fn default() -> Self { - Self::Default - } -} - /// Configuration for the CLI tool #[derive(Debug, Clone, Serialize, Deserialize, Default)] pub struct Config {