Setup

Context intelligence activates automatically when Pilot detects a .agent/ directory in your project. Since v0.33.16, Pilot auto-initializes the .agent/ directory on first task execution — no manual setup required.

Prerequisites

• Pilot installed and configured (pilot doctor passes)
• Claude Code (or Qwen Code / OpenCode) installed
• A project repository with at least one commit

Auto-Initialization (Default)

When Pilot executes its first task in a project, it automatically creates the .agent/ directory with a default DEVELOPMENT-README.md. This is sufficient for most projects.

# Just run a task — .agent/ is created automatically
pilot task "Add health check endpoint"

The auto-generated index includes your project structure, detected framework, and component status.

What Gets Created

Auto-init creates the full Navigator directory structure:

.agent/
├── DEVELOPMENT-README.md     # Project-specific navigator guide
├── .nav-config.json          # Navigator configuration
├── .gitignore                # Excludes session-specific files
├── tasks/                    # Implementation plans
├── system/                   # Architecture docs
└── sops/                     # Standard operating procedures
    ├── integrations/
    ├── debugging/
    ├── development/
    └── deployment/

Tech Stack Detection

Pilot auto-detects your technology stack from project files:

Template Variables

Templates use these placeholders, automatically replaced during initialization:

Auto-Init Configuration

Configure auto-initialization in your Pilot config:

# ~/.pilot/config.yaml
executor:
  navigator:
    auto_init: true                # Enable auto-init (default: true)
    templates_path: "/custom/path" # Override template location (optional)

Custom Templates

If templates_path is set, Pilot uses templates from that directory instead of built-in ones. This is useful for organizations that want standardized Navigator setup across all projects.

Custom Setup

For projects that need a tailored context structure, initialize manually:

mkdir -p .agent/system .agent/tasks .agent/memories .agent/sops .agent/.context-markers

.agent/
├── DEVELOPMENT-README.md     # Index document (loaded every session)
├── system/                    # Architecture and system docs
│   ├── ARCHITECTURE.md        # System design, data flow
│   ├── FEATURE-MATRIX.md      # What's implemented vs planned
│   └── PR-CHECKLIST.md        # Pre-merge verification
├── tasks/                     # Task implementation plans
│   └── archive/               # Completed task docs
├── memories/                  # Knowledge graph entries
├── sops/                      # Standard Operating Procedures
└── .context-markers/          # Session save points

# Project Name — Development Context
 
## Quick Navigation
 
| Document | When to Read |
|----------|-------------|
| This file | Every session (auto-loaded) |
| `system/ARCHITECTURE.md` | System design, data flow |
| `system/FEATURE-MATRIX.md` | What's implemented vs not |
| `tasks/TASK-XX.md` | Active task details |
 
## Current State
 
**Version:** v1.0.0
 
### Key Components
 
| Component | Status | Notes |
|-----------|--------|-------|
| API Server | Working | Express + TypeScript |
| Database | Working | PostgreSQL + Prisma |
| Auth | In Progress | JWT-based |
 
## Project Structure
 
\`\`\`
project/
├── src/
│   ├── api/          # Route handlers
│   ├── services/     # Business logic
│   └── models/       # Database models
├── tests/
└── .agent/           # Context docs
\`\`\`
 
## Active Work
 
_See GitHub Issues with `pilot` label for current queue._

## Context Intelligence
 
This project uses structured context management.
Documentation lives in `.agent/`.
 
### Quick Commands
- `/nav-start` — Start or resume context session
- `/nav-task "description"` — Plan a new task
- `/nav-compact` — Clear context when done with a task

pilot task --dry-run "Test context detection"

🧭 Context: ✓ detected (.agent/ exists)

Directory Reference

DEVELOPMENT-README.md (Required)

The index document. Loaded every session. Contains:

• Quick navigation table linking to other docs
• Current project state and version
• Key component status
• Project structure overview
• Active work references

Target size: Under 500 words (~2,000 tokens).

system/ (Recommended)

Architecture and system-level documentation:

These are loaded on demand when tasks touch architecture.

tasks/ (Recommended)

Task implementation plans created by /nav-task. Each task gets a markdown file with:

• Requirements analysis
• Implementation steps
• Affected files
• Test plan
• Post-completion archive with learnings

Completed tasks move to tasks/archive/.

memories/ (Optional)

Knowledge graph entries — decisions, patterns, and pitfalls captured during development. The context engine creates and queries these automatically.

sops/ (Optional)

Standard Operating Procedures for recurring workflows:

• Release process
• Integration testing
• Deployment steps

.context-markers/ (Auto-managed)

Session save points created by the context engine. Do not manually edit these files. Format: YYYY-MM-DD-HHMM_description.md

.nav-config.json (Optional)

Context engine configuration overrides:

{
  "version": "6.1.0",
  "features": {
    "knowledge_graph": true,
    "user_profile": true,
    "loop_mode": true
  }
}

.user-profile.json (Auto-managed)

User preferences learned by the bilateral modeling system:

{
  "verbosity": "concise",
  "confirmation_threshold": "low",
  "framework_preferences": ["Go", "TypeScript"],
  "correction_patterns": []
}

Configuration in config.yaml

Enable context intelligence per project in your Pilot configuration:

# ~/.pilot/config.yaml
projects:
  - name: "my-project"
    path: "/path/to/project"
    navigator: true    # Pilot checks for .agent/ before each task

When navigator: true, Pilot will activate context intelligence if .agent/ exists in the project path.

Troubleshooting