/nav-marker

name: nav-marker
description: Create context save points to preserve conversation state before breaks, risky changes, or compaction. Use when user says "save my progress", "create checkpoint", "mark this point", or before clearing context.
allowed-tools: Read, Write, Bash
version: 1.0.0

Navigator Marker Skill

Create context markers - save points that preserve conversation state so you can resume work later without re-explaining everything.

When to Invoke

Invoke this skill when the user:

• Says "save my progress", "create checkpoint", "mark this"
• Says "before I take a break", "save before lunch"
• Mentions "risky refactor ahead", "experiment with new approach"
• Says "end of day", "stopping for today"
• Before compacting context

**DO NOT invoke** if:

• User is asking about existing markers (use listing, not creation)
• Context is fresh (< 5 messages exchanged)

Execution Steps

Step 1: Check Navigator Structure

Verify `.agent/.context-markers/` directory exists:

mkdir -p .agent/.context-markers

Step 2: Determine Marker Name

**If user provided name**:

• Use their name (sanitize: lowercase, hyphens for spaces)
• Example: "Before Big Refactor" → "before-big-refactor"

**If no name provided**:

• Auto-generate with timestamp: `marker-{YYYY-MM-DD}-{HHmm}`
• Example: `marker-2025-10-16-1430`

**Ask user for optional note**:

Creating marker: [name]

Add a note? (optional - helps remember context later)
Example: "OAuth working, need to add tests"

Note:

Step 3: Generate Marker Content [EXECUTE]

**IMPORTANT**: You MUST actively capture ToM sections (User Intent, Corrections, Belief State).

Create marker document with this structure:

# Context Marker: [name]

**Created**: [YYYY-MM-DD HH:MM]
**Note**: [user's note or "No note provided"]

---

## Conversation Summary

[Summarize last 10-15 messages:
- What user was working on
- Key decisions made
- Problems solved
- Current progress state
]

## Documentation Loaded

[List docs that were Read during session:
- Navigator: ✅ .agent/DEVELOPMENT-README.md
- Task: TASK-XX-feature.md
- System: project-architecture.md
- SOPs: [if any]
]

## Files Modified

[List files with Write/Edit calls:
- src/auth/login.ts (implemented OAuth)
- src/routes/auth.ts (added endpoints)
- tests/auth.test.ts (created tests)
]

## Current Focus

[What user is working on right now:
- Feature: Authentication with OAuth
- Phase: Integration complete, testing pending
- Blockers: [if any]
]

## Technical Decisions

[Key architectural choices:
- Using passport.js over next-auth (better control)
- JWT tokens in httpOnly cookies (XSS protection)
- Redis for session storage (scalability)
]

## Next Steps

[What to do after restore:
1. Finish writing tests for OAuth flow
2. Add error handling for failed logins
3. Document setup in README
]

## User Intent & Goals (ToM) [CAPTURE ACTIVELY]

[Theory of Mind section - captures user's mental state for better restoration]

**⚠️ CRITICAL: Analyze conversation to extract these - do not leave empty!**

**Primary goal this session**:
[What the user was ultimately trying to accomplish - not just the surface task]
- Review conversation for "I want to...", "The goal is...", "We need to..."
- Infer from task context if not explicitly stated

**Stated preferences**:
[Any preferences expressed during session:
- Communication style (concise/detailed)
- Code patterns preferred
- Confirmation behavior wanted
]
- Look for "I prefer...", "Don't do...", "Always use..."

**Corrections made**:
[Important corrections that should persist:
- "Should be /users not /user (plural convention)"
- "Prefer functional components over class"
- "Always use TypeScript strict mode"
]
- Look for "No, I meant...", "Actually...", "Not X, use Y"
- These MUST be captured to avoid repeating mistakes

## Belief State [CAPTURE ACTIVELY]

[Captures mutual understanding state for accurate restoration]

**⚠️ CRITICAL: Infer from conversation - do not leave empty!**

**What user knows**:
[User's demonstrated knowledge level:
- Familiar with Express, new to Passport
- Knows about JWT, unfamiliar with refresh tokens
- Senior developer, skip basics
]

**Assumptions I made**:
[Key assumptions during session:
- Using Redis for sessions (confirmed by user)
- Auth endpoints follow /api/auth/* pattern
- Testing with Jest + React Testing Library
]

**Uncertainty areas**:
[Questions that weren't fully resolved:
- Not sure if user wants social logins beyond Google
- Rate limiting requirements unclear
- Error message format preferences unknown
]

## Loop State (if in loop mode)

[Capture loop mode state for resumption - skip if not in loop mode]

**Iteration**: [N]/[MAX] (e.g., 3/5)
**Phase**: [INIT|RESEARCH|IMPL|VERIFY|COMPLETE]
**State Hash**: [6-char hash for continuity]
**Completion Indicators**:
- [ ] Code committed
- [ ] Tests passing
- [ ] Documentation updated
- [ ] Ticket closed
- [ ] Marker created

**EXIT_SIGNAL**: [true/false]
**Stagnation Count**: [N]/[THRESHOLD]

## Knowledge Graph State (v6.0.0+)

[Capture graph state for restoration - skip if no knowledge graph]

**Check if graph exists**:
```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
if [ -f ".agent/knowledge/graph.json" ]; then
  python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" --action stats --graph-path .agent/knowledge/graph.json
fi

**Memories surfaced this session**: [List memories that were queried or created:

• mem-001: "Auth changes break session tests" (surfaced)
• mem-002: "Use plural REST endpoints" (created from correction)

]

**Concepts active**: [Concepts relevant to current work:

• authentication
• testing
• api

]

**Graph queries made**: [Knowledge graph queries from this session:

• "What do we know about auth?" → 3 tasks, 1