Add Claude Code plugin marketplace

.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"
+    }
+  ]
+}

.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"
+  }
+}

AGENTIC_NAVIGATION_GUIDE.md

@@ -1,21 +1,44 @@
 <agentic-navigation-guide>
 - 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.
 </agentic-navigation-guide>

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!"

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
+<agentic-navigation-guide>
+- 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
+</agentic-navigation-guide>
+```
+
+### 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
+<agentic-navigation-guide>
+- 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.
+</agentic-navigation-guide>
+```
+
+## 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?