AH
Ali Hasan
← Back to Agentic AI Architecture
Consultant Agent System Design Role: System Architect

navigate-compass

Adaptive Engineering Scoping & Architecture Planning

$ invoke_subagent('navigate-compass')
Trigger Scenarios (When Needed)
  • ✓ When scoping a greenfield software project from scratch.
  • ✓ When planning a major redesign, architectural overhaul, or database migration.
  • ✓ When decomposing large, ambiguous engineering initiatives into actionable implementation roadmaps.
  • ✓ When defining clear technical architecture and dependency relationships before writing code.
Activation & Guardrails

Trigger: Activated when the user requests project planning, architectural design, roadmap scoping, or feature breakdowns.

Execution Rules:
• Must ask setup questions (project type, existing codebase to scan, one-sentence vision).
• Conducts an adaptive interview (Round 1 foundational questions, Round 2 drill-downs into data models, security, and edge cases).
• Produces three mandatory planning artifacts: plan.md, dependency-graph.md, and plan-graph.json.
• Never includes credentials, secrets, or internal server IPs in generated plans.
Example Prompt: "Plan a real-time collaborative whiteboarding system from scratch."
Technical Architecture & Data Contracts
Execution Pattern

Adaptive Socratic Interview & Tri-Artifact Graph Synthesis

Context Budget

Comprehensive planning context with adaptive multi-round conversation history.

State Management

Stores output artifacts in docs/plan/ (plan.md, dependency-graph.md, and plan-graph.json).

Input Contracts
User Vision & Requirements Technical & Hardware Constraints Existing Repository Files (Optional Pre-Flight Scan)
Output Contracts
docs/plan/plan.md (Comprehensive 11-Section Plan) docs/plan/dependency-graph.md (Mermaid Flowchart) docs/plan/plan-graph.json (Machine-Readable Adjacency List)
Bundled Scripts & Reference Resources

Reference Specifications (`references/`)

interview-questions.md Interview Protocol

Multi-round questioning strategy covering architecture, data modeling, concurrency, and security.

plan-template.md Document Template

Standardized 11-section markdown template ensuring comprehensive, audit-ready planning.

dependency-graph-template.md Graph Specification

Mermaid syntax rules and JSON adjacency list schema for automated downstream ingestion.

Executive Overview

Premature implementation is the most common reason software projects suffer from scope creep, architectural rework, and technical debt. navigate-compass solves this by forcing a rigorous, consultant-grade scoping process before a single line of application code is written.

Acting as a System Architect and Technical Consultant, navigate-compass runs an adaptive Socratic interview tailored to four distinct project scenarios:

  1. Greenfield Development: Defining tech stack, high-level topology, MVP boundaries, and database schemas.
  2. System Redesign: Analyzing pain points in legacy code and designing backwards-compatible transitions.
  3. Refactoring Initiatives: Isolating code smells, defining bounded contexts, and establishing characterization test suites.
  4. Feature Additions: Ensuring new capabilities integrate seamlessly with existing service contracts.

The Tri-Artifact Output System

Upon concluding the adaptive interview, navigate-compass synthesizes three distinct artifacts into docs/plan/:

1. docs/plan/plan.md (The Master Specification)

A comprehensive, 11-section engineering blueprint covering:

  • Executive Summary & Problem Statement
  • MVP Scope vs. Full Vision Roadmap
  • System Architecture & Component Diagram
  • Tech Stack Justification & Trade-off Analysis
  • Data Models, Schemas & Entity Relationships
  • API & Event Contracts
  • Error Handling & Resilience Strategy
  • Testing & Quality Assurance Strategy
  • Prioritized Task Breakdown Table
  • Security & Compliance Audit Checklist

2. docs/plan/dependency-graph.md (Mermaid Visualization)

A visual flowchart displaying task dependencies, execution paths, and critical blockers:

[Task 1: DB Migrations] --> [Task 2: Repository Layer] --> [Task 4: Controller]
                                       ↓
                            [Task 3: Unit Tests]

3. docs/plan/plan-graph.json (Graph-Prompting Adjacency List)

A machine-readable JSON structure designed specifically for downstream automated agent processing (split-plan and execute-issues):

{
  "project": "Geospatial Discovery Engine",
  "nodes": [
    { "id": "task-001", "title": "Setup MongoDB 2dsphere Index", "deps": [] },
    { "id": "task-002", "title": "Implement Snaps Gateway", "deps": ["task-001"] }
  ]
}

Adaptive Interview Methodology

Rather than asking static, rigid questionnaires, navigate-compass dynamically adapts based on developer responses:

  • If high concurrency is specified, it immediately drills into connection pooling, WebSocket gateways, and message broker backpressure.
  • If relational data is specified, it probes normalization, foreign keys, cascade behaviors, and indexing strategies.
  • If external API integrations are required, it challenges failure models, circuit breakers, and idempotency guarantees.