Project Context Navigator

Project Context Navigator

Purpose

This Skill provides instant orientation for developers using Spec Kit + CCGC integration pipelines. It replaces the need to manually check multiple files (active_context.md, tasks_plan.md, git status) by displaying a unified dashboard showing:

• Current feature and phase in the pipeline (7-phase workflow)
• Task progress and next immediate action
• Memory system health (file staleness, completeness)
• Architecture and technical standards compliance
• Recommended next steps based on current state

Key Problem Solved: Eliminates the "where am I?" disorientation that occurs in CLI-based development without persistent visual cues.

When to Use This Skill

User Initiates (explicit triggers):

• "Where am I in the project?"
• "What's my current status?"
• "What phase is this feature in?"
• "Project status"
• "What should I be working on?"
• Switching between projects: "What's the state of [other-project]?"

Auto-Activate (contextual triggers):

• Session start (after CLI boots)
• After returning from long idle period (context may have changed)
• Context confusion: "I'm not sure what..."
• State mismatch questions: "Why is branch X but memory says feature Y?"

Multi-Project Scenarios:

• Developer maintains 3+ codebases with same Spec Kit + CCGC structure
• Quick switch between projects: Instantly see which feature and phase each is in
• No context loss: Dashboard shows per-project state

How It Works

Step 1: Gather Current State (Using Native Prompt Caching)

Performance Optimization: Leverage Claude 4.5 native prompt caching with cache_control blocks:

SYSTEM PROMPT (with caching):
[Context about GCSK project and skills]
<cache_control type="ephemeral">

[Load all 7 memory files - auto-cached by Claude API]
- active_context.md
- tasks_plan.md  
- architecture.md
- technical.md
- product_requirement_docs.md
- decisions.md
- glossary.md

[Constitution and specifications]
- constitution.md
- README.md

</cache_control>

Cache benefits:
- 5-minute TTL (auto-refreshes on use)
- 90% cost reduction on cache hits
- No custom cache management needed
- Invalidates automatically when files change

Read these files to understand the complete picture:

Primary State Files (project root /memory/):

• active_context.md - Current feature, phase, last activity
• tasks_plan.md - Task breakdown, completion status, current focus
• Git status: Current branch, commits since last sync

Secondary State Files (.specify/):

• constitution.md - Project principles, quality gates
• README.md - Project overview

Diagnostic Info:

• Git: git rev-parse --show-toplevel (detect project)
• Git: git branch --show-current (current branch)
• Git: `git log -1 --format=%h (recent commit for context)
• File timestamps: When each memory file was last updated

Note: The load_memory_parallel function loads all 7 core memory files simultaneously, cached results are reused within 5-minute TTL.

Step 2: Detect Current Phase (7-Phase Pipeline)

Determine which phase by checking file existence and content:

No spec.md (phase 0)
    ↓
spec.md exists (phase 1 - Specification)
    ↓
spec.md + plan.md (phase 2 - Planning)
    ↓
spec.md + plan.md + tasks.md (phase 3 - Task Breakdown)
    ↓
Tasks marked as in-progress/complete (phase 4 - Implementation)
    ↓
All tests passing (phase 5 - Validation)
    ↓
Memory synced (phase 6 - Learning & Completion)
    ↓
New feature ready (back to phase 0/1)

Step 3: Calculate Health Metrics

Memory Health:

• Check if all 7 core files exist
• Check timestamps: Which files are stale (>2 hours, >24 hours)?
• Calculate: health_percentage = (files_exist + files_fresh) / 7 * 100

Task Progress:

• Count completed tasks (marked [x] in tasks_plan.md)
• Count total tasks
• Calculate: completion = completed / total * 100
• Identify next unchecked task

Context Freshness:

• Compare: active_context.md timestamp vs current time
• Compare: git branch vs recorded branch (mismatch detection)
• Compare: git log vs recorded last activity

Constitutional Compliance (NEW v2.0.0):

• Check if .specify/memory/constitution.md exists
• If exists: Parse principle count and names
• Check for cached validation results in .claude/cache/validator-results/
• Read recent audit logs from .claude/audit/YYYY-MM-DD.json
• Determine compliance status per principle
• Calculate overall compliance rate

Plugin System Status (NEW v2.0.0):

• Check if .claude/commands/plugins/ directory exists
• Scan for plugin.json manifests
• Read cached plugin registry from .claude/cache/plugins.json
• Count loaded plugin packs and their provides (commands, validators)
• Calculate total available commands (core + plugins)

Validator Results (NEW v2.0.0):

• Check for core validators in .claude/validators/core/
• Check for plugin validators in .claude/validators/plugins/
• Read recent validator execution results from cache
• Parse exit codes to determine status (0=pass, 1=critical, 2=high, 3=medium, 4=low)
• Aggregate by severity and recency

Step 4: Display Dashboard

Format output as a visual dashboard with sections:

🎯 PROJECT CONTEXT DASHBOARD
════════════════════════════════════════════════════════════════

📦 PROJECT IDENTIFICATION
   Project: [Project Name from git root or CLAUDE.md]
   Directory: [Absolute path]
   Repo: [URL from git remote]

🌿 GIT STATE
   Branch: [current branch]
   Commit: [recent hash + message]
   Status: [working tree clean/dirty + changes count]

📍 PIPELINE PHASE
   Current Phase: [Phase N of 7]: [Phase Name]
   Status: [IN PROGRESS / READY FOR NEXT / COMPLETE]
   Prerequisites: [✅ All met / ❌ Missing X files]

🎪 ACTIVE FEATURE (if applicable)
   Feature ID: [Feature number]
   Name: [Feature name]
   Priority: [P0 CRITICAL / P1 HIGH / etc]
   Status: [Specification / Planning / Implementation / Testing / Complete]

📋 TASK PROGRESS (if in implementation phase)
   Total Tasks: [N tasks]
   Completed: [N tasks]
   In Progress: [N tasks]
   Next Task: [Task ID: Task description (Est. time)]
   Parallel Opportunities: [N tasks marked with [P]]
   Estimated Time to Complete: [Total hours]

📊 MEMORY SYSTEM HEALTH
   Core Files: [M/7 files exist]
   Freshness: [N% fresh, X stale, Y very stale]
   Last Sync: [N hours ago / N days ago]
   Issues: [if any]

⚖️  CONSTITUTIONAL COMPLIANCE (NEW v2.0.0)
   Constitution: [✅ Found / ❌ Not ratified]
   Principles: [N total principles defined]
   Compliance Status:
   ├─ Principle I:   [✅ PASS / ⚠️ WARN / ❌ FAIL] ([last check time])
   ├─ Principle II:  [✅ PASS / ⚠️ WARN / ❌ FAIL] ([last check time])
   ├─ [Additional principles...]
   └─ Overall: [N]/[M] principles compliant ([%] compliance rate)

   Recent Violations: [if any]
   Quality Gates: [N passed / M total]

🔍 VALIDATION RESULTS (NEW v2.0.0)
   Core Validators:
   ├─ memory-consistency:    [✅ PASS / ⚠️ WARN / ❌ FAIL] ([last run])
   ├─ phase-transition:      [✅ PASS / ⚠️ WARN / ❌ FAIL] ([last run])
   └─ architectural-boundaries: [✅ PASS / ⚠️ WARN / ❌ FAIL] ([last run])

   Project Validators: [if plugins exist]
   ├─ [validator-name]:      [✅ PASS / ⚠️ WARN / ❌ FAIL] ([last run])
   └─ [Additional validators...]

   Summary: [N passed, X warnings, Y failures]

🔌 PLUGINS (NEW v2.0.0)
   Status: [✅ Loaded / ⚠️ Partially loaded / ❌ None]
   Loaded Packs: [N plugin packs]
   ├─ [plugin-pack-name] v[X.Y.Z] ([N commands, M validators])
   └─ [Additional plugin packs...]
   Commands Available: [X core + Y plugin = Z total]
   Validators Active: [A core + B plugin = C total]

⚠️  DETECTED ISSUES (if any)
   [List any state mismatches, stale context, missing files, violations, etc.]

🎯 RECOMMENDED NEXT ACTIONS
   1. [Specific action based on phase and compliance status]
   2. [Next step after that]
   3. [Alternative if stuck or blocked by violations]

💡 QUICK COMMANDS
   /memory-read         [Load all memory]
   /memory-sync         [Update stale files]
   /constitution-check  [Run constitutional validation] (NEW v2.0.0)
   /plugin-list         [Show loaded plugins] (NEW v2.0.0)
   /implement           [Start/continue implementation]
   @agent-implementer   [Execute next task]

════════════════════════════════════════════════════════════════

Step 5: Provide Intelligent Recommendations

Based on current phase, suggest specific next actions:

If Phase 0 (No Spec):

→ Next: Create feature specification
  Run: /specify "Your feature description"
  Or ask: "I want to build X"

If Phase 1 (Spec Exists):

→ Next: Create implementation plan
  Run: /plan
  Or ask: "How should we build this?"

If Phase 2-3 (Planning Complete, Tasks Ready):

→ Next: Load context and start coding
  Run: "ready to code" → quick-start Skill
  Or ask: "start coding"

If Phase 4 (Implementation In Progress):

→ Next: Continue with next task
  Current Task: [T001: Description]
  Run: @agent-implementer
  Or ask: "implement next task"

If Phase 5 (Tests Passing):

→ Next: Capture learnings
  Run: /memory-sync
  Or ask: "sync memory"

Examples

Example 1: Session Start (Orientation)

User Action: Opens Claude Code CLI at start of day

Skill Activation: Automatic (session start context needed)

Skill Output:

🎯 PROJECT CONTEXT DASHBOARD - IECPN Dashboard
════════════════════════════════════════════════════════════════

📦 PROJECT: IECPN Healthcare Dashboard

🌿 GIT STATE
   Branch: 006-feature-006-logging ✓ (matches active feature)
   Commit: 217b377 "feat: implement Phase 5 E2E testing"
   Status: Clean (no uncommitted changes)

📍 PHASE: 4 / 7 - IMPLEMENTATION (Active)
   Feature: #006 - PHI Logging Cleanup
   Status: IN PROGRESS ✓
   Prerequisites: ✅ All met

🎪 ACTIVE FEATURE
   ID: 006
   Name: PHI Logging Cleanup and Automated Redaction
   Priority: P0 CRITICAL
   Compliance Impact: LGPD Art. 46, HIPAA §164.312
   Tasks: 26 total
   ├─ Completed: 0
   ├─ In Progress: 0
   └─ Next: T001 - Create migration (10 min, [P] parallel)

📊 MEMORY HEALTH
   Files: 7/7 complete ✓
   Freshness: 2 fresh, 1 stale (>2h), 4 current
   Last Sync: 11 hours ago ⚠️
   Recommendation: Run /memory-sync to refresh context

⚠️  CONTEXT ISSUE DETECTED
   active_context.md is 11 hours stale
   Recommend: /memory-sync to update before starting

🎯 NEXT ACTIONS
   1. Refresh context: /memory-sync
   2. Load full context: "ready to code"
   3. Begin implementation: @agent-implementer

💡 QUICK ACTIONS
   Type: "sync memory" → Auto-run /memory-sync
   Type: "ready to code" → Load context + validate
   Type: "start 006" → Begin Feature 006 implementation
════════════════════════════════════════════════════════════════

Example 2: Multi-Project Context Switch

User Action: "Where am I?" (after switching between 3 projects)

Skill Activation: Automatic (context confusion)

Skill Output:

🎯 MULTI-PROJECT STATUS
════════════════════════════════════════════════════════════════

🔍 DETECTED: You switched projects

📍 CURRENT PROJECT: /Users/dev/personal/dev_IECPN
   Branch: 006-feature-006-logging
   Phase: 4 - IMPLEMENTATION (26 tasks, 0% complete)
   Feature: PHI Logging Cleanup (P0 CRITICAL)
   Memory: Stale (11 hours)
   Next: @agent-implementer

📍 OTHER PROJECTS (in recent git history):
   /Users/dev/work/api-refactor
   Branch: 012-api-gateway
   Phase: 2 - PLANNING (plan.md created, no tasks yet)
   Memory: Current (1 hour old)
   Next: /tasks to generate task breakdown

   /Users/dev/personal/ml-pipeline
   Branch: master
   Phase: 1 - SPECIFICATION (no plan.md yet)
   Memory: Very stale (3 days old)
   Next: /memory-sync, then /plan for design

════════════════════════════════════════════════════════════════

Example 3: Detecting State Mismatch

User Action: "Project status"

State Detected:

• Branch: mvp-nuclear-reset
• active_context.md says: Feature 006 in progress
• Git log shows: Phase 6 work completed
• No 006 branch checkout

Skill Output:

🎯 PROJECT STATUS - State Mismatch Detected
════════════════════════════════════════════════════════════════

⚠️  BRANCH-CONTEXT MISMATCH

Current State:
├─ Git Branch: mvp-nuclear-reset (not a feature branch)
├─ Memory Says: Feature 006 in progress
└─ Conflict: These don't match!

Recent History:
└─ Latest commit: Phase 6 complete (7b82d09)

Analysis:
Most likely: You completed Phase 6, need to start Feature 006
├─ Option 1: Checkout 006 branch to start Feature 006
├─ Option 2: Sync memory to update context to completed state

🎯 RECOMMENDED:
1. Run: /memory-sync
   (Update active_context.md with current state)

2. Then: Choose next action
   - Start Feature 006: git checkout 006-feature-006-logging
   - Start new feature: /specify "description"
   - Review Phase 6 completion: "summary of phase 6"

💡 QUICK FIX
   Type: "sync context" → Auto-run /memory-sync
   Type: "start 006" → Checkout 006 branch + sync
════════════════════════════════════════════════════════════════

Technical Implementation Details

File Locations to Check

Project Root:

/memory/
├── active_context.md     (1) Current feature, phase, activity
├── tasks_plan.md         (2) Task breakdown and progress
├── architecture.md       (3) System design (reference only)
├── technical.md          (4) Tech standards (reference only)
├── product_requirement_docs.md  (5) Feature scope
├── lessons-learned.md    (6) Implementation insights
└── error-documentation.md (7) Known issues

CLAUDE.md                  → Runtime guidance + project name

Spec Kit:

.specify/
├── memory/constitution.md → Principles, quality gates
└── README.md              → Project overview

Constitutional System (NEW v2.0.0):

.claude/cache/
├── principle-registry.json       → Parsed constitution principles
├── plugins.json                  → Loaded plugin registry
└── validator-results/            → Recent validator execution results
    ├── architectural-boundaries-[hash].json
    └── memory-consistency-[hash].json

.claude/audit/
└── YYYY-MM-DD.json              → Daily audit log with validation history

Plugin System (NEW v2.0.0):

.claude/commands/plugins/
└── [plugin-pack-name]/
    ├── plugin.json              → Plugin manifest
    └── [command-name]/          → Plugin commands

.claude/validators/plugins/
└── [plugin-pack-name]/
    ├── plugin.json              → Validator manifest
    └── [validator-name].sh      → Validator scripts

Git Info:

$(git rev-parse --show-toplevel)  → Project root
$(git branch --show-current)      → Current branch
$(git log -1 --format=%h)         → Recent commit
$(git status --porcelain)         → Working tree state

Staleness Indicators

Freshness Categories:

• Current: Modified within 1 hour
• Stale: 1-24 hours old (⚠️)
• Very Stale: >24 hours old (🔴)
• Missing: File doesn't exist (❌)

Phase Detection Logic

# Pseudocode for phase detection
if [ ! -f spec.md ]; then
    phase=0  # No specification
elif [ ! -f plan.md ]; then
    phase=1  # Specification exists, planning needed
elif [ ! -f tasks.md ]; then
    phase=2  # Planning complete, tasks needed
elif grep -q "^\- \[ \]" tasks.md; then
    phase=3  # Tasks exist, implementation needed
elif grep -q "all tests passing\|✅ validation complete" active_context.md; then
    phase=5  # Tests passing, learning phase
else
    phase=4  # Implementation in progress
fi

Integration with Other Skills

Relationship to quick-start Skill:

• context-navigator: Shows status (read-only)
• quick-start: Loads full context (write-capable)
• User flow: context-navigator → quick-start → coding

Relationship to phase-guide Skill:

• context-navigator: Current phase snapshot
• phase-guide: Detailed phase-by-phase navigation
• User flow: context-navigator detects phase, phase-guide guides transitions

Relationship to memory-keeper Skill:

• context-navigator: Detects stale context
• memory-keeper: Proactively maintains freshness
• User flow: context-navigator warns staleness, memory-keeper auto-fixes

Troubleshooting

Issue: Dashboard shows but recommendations seem wrong

Diagnosis: Check if active_context.md accurately reflects current state

Fix: Run /memory-sync to update memory files

Issue: Can't determine current phase

Diagnosis: Check for spec.md, plan.md, tasks.md existence

Fix: Ensure .specify/ and memory/ directories exist

Performance Notes

This Skill performs these fast, read-only operations:

1. File reads (active_context.md, tasks_plan.md, constitution.md)
2. Git status checks
3. File timestamp comparison
4. Cache file reads (plugins.json, principle-registry.json) (NEW v2.0.0)
5. Recent audit log parsing (optional) (NEW v2.0.0)

Expected execution time: <500ms No side effects: Pure read-only diagnostic Skill

Graceful Degradation (NEW v2.0.0)

This skill is backward compatible and works in all configurations:

Without Constitution (v1.0.0 compatibility):

• Constitutional Compliance section shows: "Constitution: Not ratified"
• All other sections work normally
• No errors or failures

Without Plugins (core-only mode):

• Plugins section shows: "Status: None (core commands only)"
• Commands Available shows only core count (8 commands)
• Validators shows only core validators (3 validators)

Without Cache Files (fresh installation):

• Reads directly from source files instead of cache
• Slightly slower (<100ms additional overhead)
• No functional differences

Partial Plugin Failure (some plugins broken):

• Shows which plugins loaded successfully
• Lists broken plugins with error messages
• Core functionality unaffected

Missing v2.0.0 Directories:

No .claude/cache/ → "Cache not initialized (run session-start hook)"
No .claude/audit/ → "Audit logging not enabled"
No .claude/validators/plugins/ → "No project validators installed"

This ensures developers can:

1. Use v2.0.0 features incrementally
2. Migrate from v1.0.0 without breaking changes
3. Work in minimal environments (core only)
4. Debug plugin issues without losing core functionality