/nav-init

name: nav-init
description: Initialize Navigator documentation structure in a project. Auto-invokes when user says "Initialize Navigator", "Set up Navigator", "Create Navigator structure", or "Bootstrap Navigator".
allowed-tools: Write, Bash, Read, Glob
version: 1.0.0
triggers:
  - "initialize navigator"
  - "init navigator"
  - "set up navigator"
  - "setup navigator"
  - "create navigator structure"
  - "bootstrap navigator"
  - "start navigator project"

Navigator Initialization Skill

Purpose

Creates the Navigator documentation structure (`.agent/`) in a new project, copies templates, and sets up initial configuration.

When This Skill Auto-Invokes

• "Initialize Navigator in this project"
• "Set up Navigator documentation structure"
• "Create .agent folder for Navigator"
• "Bootstrap Navigator for my project"

What This Skill Does

1. **Checks if already initialized**: Prevents overwriting existing structure 2. **Creates `.agent/` directory structure**:

   .agent/
   ├── DEVELOPMENT-README.md
   ├── .nav-config.json
   ├── tasks/
   ├── system/
   ├── sops/
   │   ├── integrations/
   │   ├── debugging/
   │   ├── development/
   │   └── deployment/
   └── grafana/
       ├── docker-compose.yml
       ├── otel-collector-config.yml
       ├── prometheus.yml
       ├── grafana-datasource.yml
       ├── grafana-dashboards.yml
       ├── navigator-dashboard.json
       └── README.md

3. **Copies templates**: DEVELOPMENT-README.md, config, Grafana setup 5. **Auto-detects project info**: Name, tech stack (from package.json if available) 6. **Updates CLAUDE.md**: Adds Navigator-specific instructions to project 7. **Creates .gitignore entries**: Excludes temporary Navigator files

Execution Steps

1. Check if Already Initialized

if [ -d ".agent" ]; then
    echo "✅ Navigator already initialized in this project"
    echo ""
    echo "To start a session: 'Start my Navigator session'"
    echo "To view documentation: Read .agent/DEVELOPMENT-README.md"
    exit 0
fi

2. Detect Project Information

Read `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, or similar to extract:

• Project name
• Tech stack
• Dependencies

**Fallback**: Use current directory name if no config found.

3. Create Directory Structure

Use Write tool to create:

.agent/
.agent/tasks/
.agent/system/
.agent/sops/integrations/
.agent/sops/debugging/
.agent/sops/development/
.agent/sops/deployment/
.agent/grafana/

4. Copy Templates

Copy from plugin's `templates/` directory to `.agent/`:

**DEVELOPMENT-README.md**:

• Replace `${PROJECT_NAME}` with detected project name
• Replace `${TECH_STACK}` with detected stack
• Replace `${DATE}` with current date

**`.nav-config.json`**:

{
  "version": "5.5.0",
  "project_name": "${PROJECT_NAME}",
  "tech_stack": "${TECH_STACK}",
  "project_management": "none",
  "task_prefix": "TASK",
  "task_id_source": "local",
  "team_chat": "none",
  "auto_load_navigator": true,
  "compact_strategy": "conservative",
  "auto_update": {
    "enabled": true,
    "check_interval_hours": 1,
    "curl_fallback": false
  },
  "task_doc_guard_hook": {
    "enabled": true,
    "strict_block": true
  }
}

**Grafana Setup**: Copy all Grafana dashboard files to enable metrics visualization:

# Find plugin installation directory
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

# Copy Grafana files if plugin has them
if [ -d "${PLUGIN_DIR}/.agent/grafana" ]; then
  cp -r "${PLUGIN_DIR}/.agent/grafana/"* .agent/grafana/
  echo "✓ Grafana dashboard installed"
else
  echo "⚠️  Grafana files not found in plugin"
fi

Files copied:

• docker-compose.yml (OpenTelemetry Collector + Prometheus + Grafana stack)
• otel-collector-config.yml (OTLP in from every Claude Code session, scrape endpoint out)
• prometheus.yml (scrapes the collector; legacy direct exporter job on :9464)
• grafana-datasource.yml (Prometheus datasource config)
• grafana-dashboards.yml (dashboard provider config)
• navigator-dashboard.json (13-panel Navigator metrics dashboard)
• README.md (setup instructions, incl. the `~/.claude/settings.json` env block)

5. Update Project CLAUDE.md

If `CLAUDE.md` exists:

• Append Navigator-specific sections
• Keep existing project customizations

If `CLAUDE.md` doesn't exist:

• Copy `templates/CLAUDE.md` to project root
• Customize with project info

6. Claude Code Hooks (Plugin Manifest)

**Navigator's lifecycle hooks ship with the plugin manifest** (`.claude-plugin/plugin.json`'s top-level `hooks` field) starting v6.13.0+. They are *not* merged into the project's `.claude/settings.json` — Claude Code only substitutes `${CLAUDE_PLUGIN_ROOT}` for hooks declared in a plugin manifest, so merging them into user settings (the prior approach) produced broken commands like `/hooks/X.py`.

The plugin registers the following hooks automatically when the plugin is installed:

1. **SessionStart** — injects Navigator context (navigator + active marker + config + graph + profile) into the session, eliminating ~6 Read tool calls at start (v6.9.0+) 2. **PreCompact** — writes a context marker before manual or silent auto-compact (v6.10.0+) 3. **PostCompact** — appends Claude Code's compact summary to the marker (v6.10.0+) 4. **Stop** — silent workflow-state writer; records whether WORKFLOW CHECK / NAVIGATOR_STATUS appeared (v6.11.0+) 5. **UserPromptSubmit** — prompt_gate + prompt_brief ops (Loop/Task mode trigger detection + optional strict_block gate; intent-brief injection) 6. **PreToolUse(Read)** — read_guard op (bulk-read circuit breaker) 6b. **PreToolUse(Write|Edit|Bash|Skill)** — task_doc_guard op (blocks a hand-written `.agent/tasks/TASK-*.md` unless `/nav-task` ran this session; GH-40) 7. **PostToolUse(Edit|Write|Bash)** — t