tools-only TASK-18 Corrections: Plugin-First Approach
Date: 2025-10-23 Critical: Apply context engineering principles from Anthropic docs
🎯 Key Realizations from Context Engineering Images
Image 1: System Prompt Calibration
Spectrum: Too specific ← Just right → Too vague
"Just right" example (Claude's Bakery customer support):
- Framework, not rigid rules
- "Identify core issue → Gather context → Provide clear resolution"
- Guidelines, not exhaustive checklists
- Escalate to human when needed
Applied to Navigator:
- ❌ Too specific: "Run exactly these 15 steps in order"
- ✅ Just right: "Start session → Navigate to what you need → Load on-demand"
- ❌ Too vague: "Be helpful and efficient"
Image 2: Context Engineering for Agents
Core principle: Curation > Loading everything
Possible context (left) → Curated context (right)
- Many docs available → Load Doc1, Doc2 only
- Many tools available → Provide Tool1, Tool2 only
- Strategic selection based on task
This is literally Navigator's architecture.
🔧 Critical Corrections for TASK-18
1. Navigator is a Plugin (Not SaaS)
Reality:
- Users install on their machines
- Works with their projects (any codebase)
- No API keys required (unless they configure PM tools)
- No central server
- No user-specific data
Implications for TASK-18:
Philosophy Docs Must Be Portable ✅
# CONTEXT-EFFICIENCY.md
## The Problem I Kept Hitting
I was working on [any project]... ← NOT "Navigator's codebase"
I loaded all my docs... ← NOT "our docs"
Correct: Use "you/your" for user's project Wrong: Use "we/our" for Navigator's codebase
Case Studies Must Be Generic ✅
# FEATURE-IN-3-STEPS.md
Example: Adding authentication to e-commerce app
← NOT "Adding feature to Navigator"
Your project: 150k tokens if loaded upfront
Your usage: 12k tokens with Navigator
← NOT Navigator-specific metrics
Learning Content Must Apply to Any Codebase ✅
# CONTEXT-BUDGETS.md
Your project documentation:
├── README.md
├── docs/
└── .agent/ (Navigator adds this)
How to budget your 200k context:
- Your system: ~50k (docs, architecture)
- Your work: ~100k (code, changes)
- Navigator overhead: ~12k (guidance)
← Works for ANY project
Metrics Must Be User's Project ✅
"Show me my session statistics" output:
Your Project Efficiency
━━━━━━━━━━━━━━━━━━━━━━━━━━
Documentation in project: 150k tokens (baseline)
Loaded this session: 12k tokens
Tokens saved: 138k (92%)
← These are USER'S docs, not Navigator's
2. Automation Must Be Zero-Config
From Image 1 principle: "Just right" = helpful framework, not rigid process
Applied to Navigator:
✅ Auto-detect, Don't Ask
# GOOD: Auto-detect project type
if [ -f "package.json" ]; then
project_type="JavaScript"
elif [ -f "Cargo.toml" ]; then
project_type="Rust"
fi
# BAD: Ask user
echo "What type of project is this? (1) JS (2) Python (3) Rust"
✅ Smart Defaults, Override if Needed
# GOOD: Work without config
if [ -f ".agent/.nav-config.json" ]; then
load_config # User customized
else
use_defaults # Works immediately
fi
# BAD: Require configuration
if [ ! -f ".agent/.nav-config.json" ]; then
echo "ERROR: Please run setup first"
exit 1
fi
✅ Graceful Degradation
# GOOD: Optional enhancements
if command -v gh &> /dev/null; then
pm_tool="GitHub Issues (via gh CLI)"
else
pm_tool="Manual documentation" # Still works
fi
# BAD: Hard requirements
if ! command -v gh &> /dev/null; then
echo "ERROR: gh CLI required"
exit 1
fi
3. Instructions Must Be Clear & Minimal
From Image 1: Customer support prompt is ~400 words, not 4,000
Applied to Navigator:
Philosophy Docs: ~3-4k tokens each ✅
NOT: Comprehensive encyclopedia YES: Core insight + examples + when to use
Learning Guides: ~2-3k tokens each ✅
NOT: Academic textbook YES: Problem → Pattern → Proof → Practice
Commands: One-line invocation ✅
# GOOD
"Start my Navigator session"
# BAD
"Please initialize Navigator by loading the development readme
and checking for assigned tasks from the project management
system if configured, then display session statistics..."
4. Context Curation is THE Feature
From Image 2: Right side shows curated context window
Navigator's curation strategy:
Available in .agent/:
├── philosophy/ (3 files, ~10k tokens)
├── learning/ (4 files, ~10k tokens)
├── system/ (5 files, ~25k tokens)
├── tasks/ (10 files, ~30k tokens)
├── sops/ (8 files, ~20k tokens)
└── examples/ (3 files, ~8k tokens)
Total available: ~103k tokens
Loaded in typical session:
├── DEVELOPMENT-README.md (~2k)
├── Current task (~3k)
└── Relevant system doc (~5k)
Total loaded: ~10k tokens (90% savings)
This curation IS the product.
🎯 Corrections to Apply
TASK-18.1: Philosophy Documentation
Add section: "How Navigator Curates Context"
## Navigator's Curation Strategy
**Available**: All .agent/ documentation (~100k+ tokens)
**Loaded**: Navigator (2k) + Current task (3k) + System (if needed, 5k)
**Saved**: 90%+ of context window for your actual work
This is **context engineering**: Strategic selection over bulk loading.
Analogy: Library vs. Carrying Books
- Don't carry every book from the library
- Bring catalog (navigator)
- Check out what you need (on-demand)
- Return when done (compact)
TASK-18.2: Narrative Rewrite
Update voice: User's project, not Navigator's
Before (Navigator-centric):
Navigator reduces token usage by 92%
After (User-centric):
Your project docs: 150k tokens
With Navigator: 12k tokens loaded
You save: 92% of context for actual work
TASK-18.3: Metrics Enhancement
Ensure baseline is user's project:
# Calculate baseline from USER'S docs
calculate_baseline() {
local baseline=0
# User's docs (not Navigator's)
if [ -d ".agent" ]; then
baseline=$(find .agent -name "*.md" -type f -exec wc -c {} + | \
awk '{sum+=$1} END {print int(sum/4)}')
fi
# Project README
if [ -f "README.md" ]; then
baseline=$((baseline + $(wc -c < README.md) / 4))
fi
echo $baseline
}
TASK-18.5: Learning Content
Each guide must show curation in action:
# CONTEXT-BUDGETS.md
## Exercise: See Curation vs. Bulk Loading
### Without Navigator (Bulk Loading)
```bash
# Load everything at session start
cat .agent/**/*.md # 100k+ tokens
# Result: Context full, AI overwhelmed
With Navigator (Curation)
"Start Navigator session"
# Loads: Navigator (2k)
# Available: Everything else (on-demand)
# Result: 98k tokens available for work
This is context engineering: Curate, don't bulk load.
---
### TASK-18.7: Pattern Library
**Pattern Template must emphasize curation**:
```markdown
# Pattern: [Name]
## Context Engineering Principle
[Which curation strategy this uses]
- Lazy loading?
- Progressive refinement?
- Strategic selection?
## Problem
[What fails with bulk loading]
## Solution
[How curation fixes it]
## Proof
[Metrics: tokens saved, efficiency gained]
TASK-18.9: Manifesto
Lead with context engineering:
# The Context Efficiency Manifesto
## The Problem
AI tools load everything upfront. "Just in case."
Result: 70-90% of context wasted on irrelevant data.
## The Realization
**Context engineering beats bulk loading.**
From Anthropic's docs:
- Prompt engineering: One query, optimize prompt
- Context engineering: Multi-turn agent, curate context
Navigator implements context engineering for your codebase.
## The Principle
**Strategic curation > Bulk loading**
Not "load everything just in case"
Not "better safe than sorry"
Curate what's relevant. Load on-demand. Save context for work.
## The Proof
[User metrics, not Navigator's]
Your project: 150k tokens available
Navigator loaded: 12k tokens
Context saved for work: 138k (92%)
**Verified via OpenTelemetry, not estimates.**
🎯 Automation Checklist for TASK-18
Each deliverable must follow these principles:
Zero-Config ✅
- Works immediately after install
- Detects project type automatically
- Uses smart defaults
- Configuration is optional enhancement
Portable ✅
- No hardcoded paths
- No API keys required (unless user configures PM)
- Works on any codebase
- No Navigator-specific assumptions
Helpful Guidance ✅
- Clear next steps ("Do this next")
- Explains why, not just how
- Examples from user's perspective
- Escalation path when stuck
Graceful Degradation ✅
- Core features work without optional deps
- Missing integrations don't break workflow
- Clear messages when features unavailable
- Always has fallback
🎯 Updated Success Criteria
For Each Deliverable
Philosophy Docs (TASK-18.1):
- Uses "you/your project" (not "we/Navigator")
- Examples apply to any codebase
- Shows curation strategy explicitly
- References context engineering principles
Narrative Rewrite (TASK-18.2):
- User-centric ("your 150k tokens")
- No Navigator-specific jargon
- Clear for first-time installer
- Shows value in user's terms
Metrics (TASK-18.3):
- Calculates baseline from user's docs
- Shows user's token savings
- No Navigator-internal metrics
- Portable across projects
Learning Content (TASK-18.5):
- Exercises use user's codebase
- Shows curation in action
- Applies to any project type
- No setup required to understand
Pattern Library (TASK-18.7):
- Patterns are project-agnostic
- Shows which curation strategy
- Examples from various domains
- Clear when (not) to apply
Manifesto (TASK-18.9):
- Leads with context engineering
- References Anthropic principles
- User metrics, not Navigator's
- Shareable beyond Navigator users
🎯 Quality Gates
Before Marking Any Task Complete
Ask:
- Would this work for a Rust project? Python? JavaScript?
- Does it assume Navigator's codebase or user's?
- Can user install and use without configuration?
- Are instructions clear enough for non-experts?
- Does it show curation strategy explicitly?
- Would Anthropic's context engineering docs approve?
If any answer is no, revise before completing.
🎯 Key Takeaways for Implementation
1. Context Engineering is the Product ✅
Not: "Navigator has lazy loading feature" Is: "Navigator implements context engineering for your codebase"
From Anthropic docs: Curation > Bulk loading Navigator proves: 90%+ savings through strategic curation
2. "Just Right" Calibration ✅
Too specific: Rigid checklists, exhaustive rules Just right: Framework + examples + when to escalate Too vague: "Be efficient"
All TASK-18 deliverables must hit "just right"
3. Plugin Reality Check ✅
Every doc, command, and feature must work:
- ✅ On any machine (user's laptop)
- ✅ With any project (Rust, JS, Python, etc.)
- ✅ Without setup (or minimal setup)
- ✅ Without API keys (unless optional integrations)
- ✅ Offline (no network required for core features)
4. User-Centric Everything ✅
All metrics are user's:
- Your project: 150k tokens
- Your savings: 92%
- Your efficiency: 94/100
- Your time saved: 42 minutes
Not Navigator's metrics.
🚀 Implementation Order with Corrections
Week 1: Philosophy + Narrative (TASK-18.1, 18.2)
Focus: Establish context engineering as core principle Check: All examples use "your project," not Navigator's
Week 3: Metrics (TASK-18.3)
Focus: Show user's savings, not Navigator's overhead Check: Baseline calculated from user's docs
Week 5: Learning (TASK-18.5)
Focus: Teach curation through user's codebase Check: Exercises work on any project type
Week 7: Patterns (TASK-18.7)
Focus: Each pattern shows curation strategy Check: Patterns are project-agnostic
Week 9: Manifesto (TASK-18.9)
Focus: Lead with context engineering principles Check: References Anthropic docs, proves with user metrics
✅ Corrected and Ready
All TASK-18 deliverables will now:
- Apply context engineering principles (from images)
- Be portable (plugin for any project)
- Require zero/minimal config
- Use user-centric language
- Show curation strategy explicitly
- Hit "just right" calibration
These corrections ensure Navigator becomes THE context engineering framework for AI development.
Ready to start Week 1 with corrections applied.