← Nav Continuity Layer → Agent Platform Phase 0 · Prompt Deck · Pictures
Nav Continuity Layer Spec
How do we think slowly so the agent starts fast and the context never breaks?
Intent Contract
Agent autonomy boundary. Not parsed by engineering — governance instrument for humans and agents.
| Dimension | Statement |
|---|---|
| Objective | Eliminate manual re-briefing at session start — the system carries the cognitive load of context transfer between sessions. |
| Outcomes | 1. nav-briefing.md generates without manual CLI commands on startup. 2. Median session start to productive interaction <30 seconds. 3. Zero copy-paste re-briefing over 10 sessions. |
| Health Metrics | Script execution <5s. Injected context <2000 tokens. No hallucinated context (100% accuracy). |
| Constraints | Hard: Token budget enforced — context bloat breaks LLM window. Steering: Bash over TypeScript for IDE-agnostic execution. |
| Autonomy | Allowed: Briefing format, aggregation logic, file layout. Escalate: Memory schema changes, new data sources. Never: Modify user working memory without explicit trigger. |
| Stop Rules | Complete when: 10 consecutive sessions start productive in <30s. Halt when: compiler takes >10s or injects >2000 tokens. |
Build Contract
The deliverable. Engineering builds from this. Commissioning reads this. Every row has an acceptance test.
Job: Seamless Session Start
| # | Function | Artifact | Verification | Value | State |
|---|---|---|---|---|---|
| 1 | Gather latest plans, receipts, issues at session start | Briefing compiler script (team-activation.sh) | nav-briefing.md contains current plan, open blockers, last 3 receipts | Pre-compiled context, no manual gathering | Live |
| 2 | Read/write persistent context between sessions | Memory ledger (WM-NAV.md + working-memory.json) | State persists across sessions; next session reads previous state correctly | Institutional memory survives session end | Live |
| 3 | Trigger context injection at session start | Boot hook (.claude/hooks/ SessionStart) | Hook fires on terminal/session open, briefing visible before first user input | Zero-click execution | Live |
Principles
What truths constrain the design?
The Job
| Element | Detail |
|---|---|
| Situation | Every build session starts cold — 5 minutes of re-briefing, pasting changelogs, explaining what happened. |
| Intention | Agent greets with a pre-compiled briefing summarizing the plan, issues, and recent receipts. |
| Obstacle | No persistent, agent-readable memory layer injecting context automatically. |
| Hardest Thing | Context bloat — too much context is worse than none. The token budget is the design constraint. |
Why Now
Inside a session, the interaction is formidable. Between sessions, the institutional memory evaporates. This is the single highest-leverage improvement available to the human-AI collaboration layer right now. Every other PRD benefits from faster session starts.
Design Constraints
| Constraint | Rationale |
|---|---|
| Token budget <2000 | Context bloat breaks the LLM window and degrades response quality |
| Bash, not TypeScript | IDE-agnostic — works in any terminal, no build step |
| Graceful degradation | If Convex is unreachable, hook degrades to "Comms: unavailable" |
| No hallucinated context | Briefing must be 100% accurate — wrong context worse than no context |
Performance
How do we know it's working?
Priority Score
PRIORITY = Pain x Demand x Edge x Trend x Conversion
| Dimension | Score (1-5) | Evidence |
|---|---|---|
| Pain | 5 | Manual re-briefing takes ~5m per session, repetitive chore. |
| Demand | 5 | Nav explicitly raised this via the Tight Five command as maximum appetite. |
| Edge | 4 | Utilizing local immutable KB ecosystem over waiting for IDE vendor features. |
| Trend | 4 | All AI engineering agents are moving towards state persistence. |
| Conversion | 5 | Drastically increases throughput of all subsequent venture PRD builds. |
| Composite | 2000 | 5 x 5 x 4 x 4 x 5 — Strong Build Now |
Quality Targets
| Signal | Measurement | Target |
|---|---|---|
| Telemetry | Re-briefing copy-paste occurrences | Zero over next 10 sessions |
| Quality | Accuracy of nav-briefing.md | 100% (no hallucinated context) |
| Performance | Script execution time | Under 5 seconds |
Kill signal: If the compiler script takes over 10 seconds to run or injects over 2000 tokens of context, pare down the scope.
Platform
What do we control?
Current State
| Component | Built | Wired | Working | Notes |
|---|---|---|---|---|
team-activation.sh | Yes | Yes | Yes | SessionStart hook, branch + plan loading |
session-bootstrap-context.sh | Yes | Yes | Yes | Decisions, handoffs, blockers |
WM-NAV.md | Yes | Yes | Yes | Navigation working memory |
working-memory.json | Yes | Yes | Yes | Orchestrator cognitive workspace |
agent-comms.ts | Yes | Yes | Partial | Convex comms — degrades gracefully |
Build Ratio
~90% composition (existing hooks, memory files, Convex client), ~10% new (aggregation logic, token budget enforcement).
Protocols
How do we coordinate?
Architecture
Hook fires on terminal/session initiation
|
v
Reader accesses plan.json, recent .ai/receipts/, issues
|
v
Synthesizer writes active state to nav-briefing.md
|
v
Context Injector loads briefing via team-activation.sh
|
v
Persists state to WM-NAV.md + working-memory.json
Build Order
| Sprint | Features | What | Effort | Acceptance |
|---|---|---|---|---|
| S1 | #2 | Standardize WM-NAV.md + working-memory.json schema | 2d | Schema documented, receipt aggregation working |
| S2 | #1 | Build nav-briefing.md layout engine | 2d | Briefing includes plan, blockers, last 3 receipts |
| S3 | #3 | Attach to IDE/CLI session boot hook | 1d | Zero-click: open terminal, briefing visible |
Commissioning
| # | Feature | Install | Test | Operational | Optimize |
|---|---|---|---|---|---|
| 1 | Briefing Compiler | Pass | Pass | Pass | -- |
| 2 | Memory Ledger | Pass | Pass | Pass | -- |
| 3 | Boot Hook | Pass | Pass | Pass | -- |
All 3 features at L2 (functional, not yet independently verified at L3).
Agent-Facing Spec
Commands:
bash .claude/hooks/team-activation.sh # Manual trigger
cat .ai/nav-briefing.md # Read current briefing
Boundaries: Always: read memory files, generate briefing. Ask first: change memory schema. Never: overwrite user working memory without trigger.
Players
Who creates harmony?
Demand-Side Jobs
Job 1: Seamless Session Start
Situation: Opening IDE/Chat CLI to start a build session.
| Element | Detail |
|---|---|
| Struggling moment | Finding the current active plan, last receipts, explaining context to AI |
| Current workaround | Manually paste changelogs and context into the chat at start |
| What progress looks like | Agent greets with pre-compiled briefing. Productive work in <30s. |
| Hidden objection | "The briefing will be wrong and I'll spend more time correcting it" |
| Switch trigger | Third session in a row where you paste the same context block |
Features that serve this job: #1, #2, #3
Role Definitions
| Role | Access | Permissions |
|---|---|---|
| Nav (agent) | Full read of memory files | Generate briefing, update WM-NAV.md |
| User | Read briefing output | Adjust working memory, override briefing |
Relationship to Other PRDs
| PRD | Relationship | Data Flow |
|---|---|---|
| Agent Platform | Parent | Nav Continuity = Phase 3 (Comms) + Phase 4.5 (Receipts) |
| Agent Receipts | Input | Receipts feed the briefing compiler |
Context
- PRD Index — Nav Continuity Layer → Agent Platform Phase 0
- Prompt Deck — 5-card pitch
- Pictures — Pre-flight maps