Initial commit
This commit is contained in:
Zhongwei Li
456
skills/plugin-slash-command/examples/medium-command-example.md
Normal file
456
skills/plugin-slash-command/examples/medium-command-example.md
Normal file
@@ -0,0 +1,456 @@
|
||||
---
|
||||
description: Smart context compact - preserve essential Navigator markers and documentation context
|
||||
---
|
||||
|
||||
# Navigator Smart Compact
|
||||
|
||||
You are performing a context-optimized compact operation that preserves essential Navigator documentation markers.
|
||||
|
||||
## What This Does
|
||||
|
||||
**Regular `/compact`**: Clears all conversation history, loses context
|
||||
|
||||
**Navigator `/nav:compact`**:
|
||||
- Generates a **context marker** (snapshot of where you are)
|
||||
- Saves marker to `.agent/.context-markers/`
|
||||
- Shows you exactly how to resume
|
||||
- Clears conversation history
|
||||
- You restore context in your next session by reading the marker
|
||||
|
||||
**The Magic**: Context markers compress your entire session (50+ messages, 130k tokens) into a focused summary (3k tokens) that captures only what matters: current task, decisions made, next steps.
|
||||
|
||||
## How Context Markers Work
|
||||
|
||||
Think of it like save points in a video game:
|
||||
|
||||
```
|
||||
Before Compact:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
You: "Help me implement auth"
|
||||
Claude: [50 messages of implementation]
|
||||
You: "Now add OAuth"
|
||||
Claude: [20 messages of OAuth work]
|
||||
Total: 130k tokens, approaching limit
|
||||
|
||||
After /nav:compact:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
✅ Marker saved: .agent/.context-markers/2025-10-12.md
|
||||
|
||||
Contains:
|
||||
- Task: TASK-45 (auth + OAuth)
|
||||
- Status: OAuth integrated, needs testing
|
||||
- Decisions: Using passport.js, JWT tokens
|
||||
- Next: Write tests for OAuth flow
|
||||
- 3k tokens
|
||||
|
||||
Next session:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
You: Read @.agent/.context-markers/2025-10-12.md
|
||||
Claude: *knows exactly where you left off*
|
||||
You: "Write the OAuth tests"
|
||||
Claude: *continues seamlessly*
|
||||
```
|
||||
|
||||
**You never lose progress. The knowledge is preserved, just compressed.**
|
||||
|
||||
## When to Use
|
||||
|
||||
### ✅ Good Times to Compact
|
||||
|
||||
**After isolated sub-tasks**:
|
||||
- Just finished documentation update
|
||||
- Created SOP for solved issue
|
||||
- Archived feature implementation plan
|
||||
- Completed debugging session
|
||||
|
||||
**Before context switches**:
|
||||
- Switching from feature A to feature B
|
||||
- Moving from debugging to new feature
|
||||
- Starting new sprint/milestone
|
||||
- After research phase, before implementation
|
||||
|
||||
**Token optimization**:
|
||||
- Approaching 70% token usage
|
||||
- Long conversation with repeated info
|
||||
- After multiple /nav:update-doc operations
|
||||
|
||||
### ❌ Bad Times to Compact
|
||||
|
||||
**In middle of work**:
|
||||
- Feature half-implemented
|
||||
- Debugging complex issue
|
||||
- Multiple related sub-tasks pending
|
||||
|
||||
**Context still needed**:
|
||||
- Next sub-task depends on current conversation
|
||||
- Need to reference recent decisions
|
||||
- Team discussion ongoing
|
||||
|
||||
## Compact Process
|
||||
|
||||
### Step 1: Identify Essential Context
|
||||
|
||||
Scan conversation for:
|
||||
|
||||
**Must preserve**:
|
||||
- Current task ID (TASK-XX)
|
||||
- Active feature/epic name
|
||||
- Key technical decisions made
|
||||
- Unresolved blockers/questions
|
||||
- Next steps planned
|
||||
|
||||
**Can clear**:
|
||||
- Completed sub-tasks details
|
||||
- Resolved debugging sessions
|
||||
- Documentation already written
|
||||
- Exploratory research (if documented)
|
||||
|
||||
### Step 2: Generate Context Marker
|
||||
|
||||
Create compact marker to preserve essentials:
|
||||
|
||||
```markdown
|
||||
# Navigator Context Marker (Post-Compact)
|
||||
|
||||
**Session**: [Date/Time]
|
||||
**Navigator**: .agent/DEVELOPMENT-README.md
|
||||
|
||||
## Active Work
|
||||
- **Task**: TASK-XX - [Feature Name]
|
||||
- **Status**: [Phase/Progress]
|
||||
- **Location**: [File/component being worked on]
|
||||
|
||||
## Recent Decisions
|
||||
- [Decision 1]
|
||||
- [Decision 2]
|
||||
|
||||
## Documentation State
|
||||
- **Task docs**: [List updated docs]
|
||||
- **System docs**: [List updated docs]
|
||||
- **SOPs**: [List created SOPs]
|
||||
|
||||
## Next Steps
|
||||
1. [Next action]
|
||||
2. [Following action]
|
||||
|
||||
## Blockers
|
||||
- [Blocker 1 if any]
|
||||
|
||||
## Don't Load Again (Already Documented)
|
||||
- [Doc 1] - Already in .agent/
|
||||
- [Doc 2] - Already in .agent/
|
||||
|
||||
---
|
||||
Load this context marker after compacting to resume efficiently.
|
||||
```
|
||||
|
||||
### Step 3: Save Context Marker
|
||||
|
||||
**IMPORTANT**: You MUST save the marker where the user can access it after compact.
|
||||
|
||||
**Recommended**: Save to `.agent/.context-markers/` directory
|
||||
|
||||
```bash
|
||||
# Create directory if doesn't exist
|
||||
mkdir -p .agent/.context-markers
|
||||
|
||||
# Save with timestamp
|
||||
Write(
|
||||
file_path: ".agent/.context-markers/2025-10-12-143022-compact.md"
|
||||
content: [context marker from Step 2]
|
||||
)
|
||||
```
|
||||
|
||||
### Step 3.5: Mark as Active Marker
|
||||
|
||||
**NEW**: Create `.active` file to enable automatic resume
|
||||
|
||||
```bash
|
||||
# Create .active file pointing to this marker
|
||||
echo "2025-10-12-143022-compact.md" > .agent/.context-markers/.active
|
||||
```
|
||||
|
||||
**This enables**: `/nav:start` will auto-detect and load this marker
|
||||
|
||||
**Show user the saved location**:
|
||||
```
|
||||
✅ Context marker saved and marked as active:
|
||||
.agent/.context-markers/2025-10-12-143022-compact.md
|
||||
|
||||
This marker will be auto-loaded on next session start.
|
||||
```
|
||||
|
||||
**Alternative locations**:
|
||||
|
||||
**Option 2**: Append to current task doc (if task exists)
|
||||
```
|
||||
Append to: .agent/tasks/TASK-XX-feature.md
|
||||
|
||||
## Session Notes
|
||||
### Compact Point - [Date]
|
||||
[Context marker content]
|
||||
|
||||
After compact: Read @.agent/tasks/TASK-XX-feature.md
|
||||
```
|
||||
|
||||
**Option 3**: User clipboard (if no task doc yet)
|
||||
```
|
||||
⚠️ No task doc exists yet.
|
||||
|
||||
Copy this marker and paste it in your next session:
|
||||
|
||||
[Show marker content]
|
||||
|
||||
Or save it manually before compacting.
|
||||
```
|
||||
|
||||
### Step 4: Show Resume Instructions
|
||||
|
||||
**CRITICAL**: Tell the user exactly how to resume.
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════╗
|
||||
║ ║
|
||||
║ 🔄 Ready to Compact ║
|
||||
║ ║
|
||||
╚══════════════════════════════════════════════════════╝
|
||||
|
||||
✅ Context marker created and marked as active:
|
||||
.agent/.context-markers/2025-10-12-143022-compact.md
|
||||
|
||||
TO RESUME AFTER COMPACT:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Simply run: /nav:start
|
||||
|
||||
This will automatically:
|
||||
• Load navigator (.agent/DEVELOPMENT-README.md)
|
||||
• Detect active marker
|
||||
• Restore your context (~3k tokens)
|
||||
• Load current task (if applicable)
|
||||
|
||||
All in one command. No manual steps needed.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Proceed with compact? Type 'yes' to continue.
|
||||
```
|
||||
|
||||
**Wait for confirmation before compacting**.
|
||||
|
||||
### Step 5: Perform Compact
|
||||
|
||||
**Only after user confirms**, execute Claude Code's `/compact` command.
|
||||
|
||||
### Step 6: Post-Compact Resume (For User's Next Session)
|
||||
|
||||
**Immediately after compact**:
|
||||
|
||||
1. **Load navigator** (always):
|
||||
```
|
||||
Read .agent/DEVELOPMENT-README.md (~2k tokens)
|
||||
```
|
||||
|
||||
2. **Load context marker**:
|
||||
```
|
||||
Read context marker from Step 2
|
||||
```
|
||||
|
||||
3. **Load active task doc** (if exists):
|
||||
```
|
||||
Read .agent/tasks/TASK-XX-feature.md (~3k tokens)
|
||||
```
|
||||
|
||||
4. **Resume work**: Continue where left off
|
||||
|
||||
**Total tokens loaded**: ~7k (vs 60k+ if keeping full conversation)
|
||||
|
||||
## Compact Strategies
|
||||
|
||||
### Aggressive (Compact Often)
|
||||
|
||||
**When**: Token-constrained, switching tasks frequently
|
||||
|
||||
**Trigger**:
|
||||
- After every sub-task
|
||||
- Before every new task
|
||||
- Every 50% token usage
|
||||
|
||||
**Trade-off**: More compacts, less context continuity
|
||||
|
||||
**Best for**: Multiple short tasks, exploratory work
|
||||
|
||||
### Conservative (Compact Rarely)
|
||||
|
||||
**When**: Deep work on single feature, need context continuity
|
||||
|
||||
**Trigger**:
|
||||
- After major milestones only
|
||||
- When reaching 70%+ tokens
|
||||
- Between unrelated epics
|
||||
|
||||
**Trade-off**: Fewer compacts, more token usage
|
||||
|
||||
**Best for**: Complex features, long debugging sessions
|
||||
|
||||
### Manual (User Decides)
|
||||
|
||||
**When**: User knows when to compact
|
||||
|
||||
**Trigger**: User runs `/nav:compact` explicitly
|
||||
|
||||
**Trade-off**: Full control, requires judgment
|
||||
|
||||
**Best for**: Experienced users, custom workflows
|
||||
|
||||
## Configuration
|
||||
|
||||
Set in `.agent/.nav-config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"compact_strategy": "conservative",
|
||||
"compact_trigger_percent": 70,
|
||||
"save_context_markers": true,
|
||||
"context_marker_location": ".agent/.context-markers/"
|
||||
}
|
||||
```
|
||||
|
||||
## Example Compact Scenarios
|
||||
|
||||
### Scenario 1: Feature Complete
|
||||
|
||||
```
|
||||
Before Compact:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Tokens: 65% (130k used)
|
||||
Conversation: 50+ messages
|
||||
Feature TASK-123 complete
|
||||
Docs updated
|
||||
Tests passing
|
||||
|
||||
Action: /nav:compact
|
||||
Reason: Feature done, docs archived, ready for next task
|
||||
|
||||
After Compact:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Tokens: 5% (10k used)
|
||||
- Navigator loaded (2k)
|
||||
- Context marker (3k)
|
||||
- Ready for TASK-124
|
||||
|
||||
Savings: 120k tokens freed (60% of budget)
|
||||
```
|
||||
|
||||
### Scenario 2: Research → Implementation
|
||||
|
||||
```
|
||||
Before Compact:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Tokens: 45% (90k used)
|
||||
Research: Explored 5 different approaches
|
||||
Decision: Chose approach #3
|
||||
Key findings: Documented in SOP
|
||||
|
||||
Action: /nav:compact
|
||||
Reason: Research done, documented, time to implement
|
||||
|
||||
After Compact:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Tokens: 7% (14k used)
|
||||
- Navigator (2k)
|
||||
- Task doc with decision (3k)
|
||||
- Relevant SOP (2k)
|
||||
- Implementation ready
|
||||
|
||||
Savings: 76k tokens freed
|
||||
```
|
||||
|
||||
### Scenario 3: Multi-Task Day
|
||||
|
||||
```
|
||||
Morning:
|
||||
- TASK-101: Bug fix (15k tokens)
|
||||
- /nav:compact
|
||||
- TASK-102: New feature (25k tokens)
|
||||
- /nav:compact
|
||||
|
||||
Afternoon:
|
||||
- TASK-103: Integration (20k tokens)
|
||||
- /nav:compact
|
||||
- TASK-104: Documentation (10k tokens)
|
||||
|
||||
Total work: 4 tasks
|
||||
Peak usage: 25k tokens (12.5%)
|
||||
Without compact: Would hit 70k+ (35%), slower responses
|
||||
|
||||
Benefit: Maintained fast responses all day
|
||||
```
|
||||
|
||||
## Compact Checklist
|
||||
|
||||
Before running `/nav:compact`:
|
||||
|
||||
- [ ] Current task completed or at good stopping point
|
||||
- [ ] Important decisions documented (task doc or SOP)
|
||||
- [ ] No unresolved blockers requiring conversation context
|
||||
- [ ] Ready to switch tasks or take break
|
||||
- [ ] Context marker generated (if needed)
|
||||
|
||||
After running `/nav:compact`:
|
||||
|
||||
- [ ] Load navigator (.agent/DEVELOPMENT-README.md)
|
||||
- [ ] Load context marker (if saved)
|
||||
- [ ] Load active task doc (if continuing work)
|
||||
- [ ] Verify ready to continue
|
||||
|
||||
## Advanced: Auto-Compact
|
||||
|
||||
**Future enhancement**: Automatically compact based on triggers
|
||||
|
||||
```json
|
||||
{
|
||||
"auto_compact": {
|
||||
"enabled": false,
|
||||
"triggers": {
|
||||
"token_percent": 70,
|
||||
"after_update_doc": true,
|
||||
"between_tasks": true
|
||||
},
|
||||
"require_confirmation": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When trigger hit:
|
||||
```
|
||||
⚠️ Navigator Auto-Compact Suggested
|
||||
|
||||
Reason: Token usage at 71%
|
||||
Action: Run /nav:compact to free 60k+ tokens
|
||||
|
||||
Compact now? [Y/n]:
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
Track compact efficiency:
|
||||
|
||||
**Before Compact**:
|
||||
- Tokens used: 130k (65%)
|
||||
- Message count: 50+
|
||||
- Time: 2 hours
|
||||
|
||||
**After Compact**:
|
||||
- Tokens used: 10k (5%)
|
||||
- Context preserved: Task doc + decision markers
|
||||
- Ready for: Next task immediately
|
||||
|
||||
**Savings**:
|
||||
- 120k tokens freed
|
||||
- 60% of budget reclaimed
|
||||
- Fast responses restored
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Navigator compact preserves what matters (documented knowledge) and clears what doesn't (conversation history). This keeps your context lean and your sessions productive.
|
||||
642
skills/plugin-slash-command/examples/simple-command-example.md
Normal file
642
skills/plugin-slash-command/examples/simple-command-example.md
Normal file
@@ -0,0 +1,642 @@
|
||||
---
|
||||
description: Create context markers on-demand - save your progress anytime
|
||||
---
|
||||
|
||||
# Navigator Marker - Save Points for Your Conversation
|
||||
|
||||
Create context markers during work to capture your current state. Think of it as **git commits for your AI conversation**.
|
||||
|
||||
---
|
||||
|
||||
## What This Does
|
||||
|
||||
Creates a snapshot of your current work state that you can restore later.
|
||||
|
||||
**Traditional approach**: Work until compact, lose intermediate context
|
||||
|
||||
**With markers**:
|
||||
- Save progress anytime
|
||||
- Multiple markers per session
|
||||
- Resume from any point
|
||||
- Safety nets before risky changes
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
### ✅ Perfect Times for Markers
|
||||
|
||||
**Before taking breaks**:
|
||||
```
|
||||
You: "Implemented auth flow, going to lunch"
|
||||
You: /nav:marker lunch-break
|
||||
Result: Resume perfectly after lunch
|
||||
```
|
||||
|
||||
**Before exploring approaches**:
|
||||
```
|
||||
You: /nav:marker before-refactor
|
||||
You: "Let's try refactoring X"
|
||||
*doesn't work*
|
||||
You: Read @.agent/.context-markers/before-refactor.md
|
||||
Result: Back to known good state
|
||||
```
|
||||
|
||||
**During long features**:
|
||||
```
|
||||
Day 1: Core implementation → /nav:marker day1-core
|
||||
Day 2: Add integrations → /nav:marker day2-integrations
|
||||
Day 3: Tests & polish → /nav:marker day3-complete
|
||||
Result: Checkpoints throughout multi-day work
|
||||
```
|
||||
|
||||
**Before risky changes**:
|
||||
```
|
||||
You: "About to refactor entire routing system"
|
||||
You: /nav:marker pre-routing-refactor
|
||||
Result: Safety net if things go wrong
|
||||
```
|
||||
|
||||
**End of day**:
|
||||
```
|
||||
You: /nav:marker eod-2025-10-12
|
||||
Result: Tomorrow starts with perfect context
|
||||
```
|
||||
|
||||
**After important decisions**:
|
||||
```
|
||||
You: "We decided to use PostgreSQL instead of MongoDB"
|
||||
You: /nav:marker architecture-decision
|
||||
Result: Decision captured with full context
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
/nav:marker
|
||||
```
|
||||
|
||||
Creates marker with auto-generated name: `marker-2025-10-12-143022.md`
|
||||
|
||||
### Named Markers
|
||||
|
||||
```bash
|
||||
/nav:marker before-refactor
|
||||
/nav:marker lunch-break
|
||||
/nav:marker pre-deployment
|
||||
/nav:marker day1-complete
|
||||
```
|
||||
|
||||
Creates marker with your name: `before-refactor-2025-10-12-143022.md`
|
||||
|
||||
### With Description
|
||||
|
||||
```bash
|
||||
/nav:marker oauth-working "OAuth flow implemented and tested"
|
||||
```
|
||||
|
||||
Adds description to marker content.
|
||||
|
||||
---
|
||||
|
||||
## Marker Creation Process
|
||||
|
||||
### Step 1: Analyze Current State
|
||||
|
||||
Scan conversation for:
|
||||
|
||||
**Active work**:
|
||||
- Current task/feature
|
||||
- Files being modified
|
||||
- What's implemented
|
||||
- What's remaining
|
||||
|
||||
**Recent context**:
|
||||
- Technical decisions made
|
||||
- Approaches tried (successful and failed)
|
||||
- Dependencies added
|
||||
- Blockers encountered
|
||||
|
||||
**Next steps**:
|
||||
- What you planned to do next
|
||||
- Open questions
|
||||
- Ideas to explore
|
||||
|
||||
### Step 2: Generate Marker Content
|
||||
|
||||
Create comprehensive marker:
|
||||
|
||||
```markdown
|
||||
# Navigator Context Marker: [Name]
|
||||
|
||||
**Created**: 2025-10-12 14:30:22
|
||||
**Type**: On-demand marker
|
||||
**Navigator**: .agent/DEVELOPMENT-README.md
|
||||
|
||||
---
|
||||
|
||||
## 📍 Current Location
|
||||
|
||||
**Task**: TASK-123 - Implement OAuth authentication
|
||||
**Phase**: Integration complete, testing pending
|
||||
**Files**:
|
||||
- src/auth/oauth.ts (implemented)
|
||||
- src/routes/auth.ts (updated)
|
||||
- tests/auth.test.ts (needs work)
|
||||
|
||||
**Progress**: 70% complete
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What's Done
|
||||
|
||||
- ✅ OAuth flow implemented with passport.js
|
||||
- ✅ JWT token generation working
|
||||
- ✅ Login/logout endpoints created
|
||||
- ✅ Session management configured
|
||||
- ✅ Google OAuth provider integrated
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Technical Decisions
|
||||
|
||||
**OAuth Library**: Chose passport.js over next-auth
|
||||
- Reason: More control over flow, simpler for our use case
|
||||
- Trade-off: More manual config, but cleaner integration
|
||||
|
||||
**Token Strategy**: JWT in httpOnly cookies
|
||||
- Reason: XSS protection, no localStorage needed
|
||||
- Expiration: 7 days, refresh token pattern
|
||||
|
||||
**Session Store**: Redis
|
||||
- Reason: Fast, scalable, easy invalidation
|
||||
- Config: TTL matches JWT expiration
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Challenges & Solutions
|
||||
|
||||
**Challenge**: CORS issues with OAuth callback
|
||||
**Solution**: Added credentials: 'include' and proper CORS headers
|
||||
**File**: src/middleware/cors.ts
|
||||
|
||||
**Challenge**: Token not persisting across requests
|
||||
**Solution**: Missing httpOnly flag in cookie options
|
||||
**File**: src/auth/tokens.ts:45
|
||||
|
||||
---
|
||||
|
||||
## 📝 Next Steps
|
||||
|
||||
1. Write comprehensive tests for OAuth flow
|
||||
- Happy path: successful login
|
||||
- Error cases: invalid tokens, expired sessions
|
||||
- Edge cases: concurrent logins, token refresh
|
||||
|
||||
2. Add error handling for failed OAuth
|
||||
- Network errors
|
||||
- Provider downtime
|
||||
- Invalid credentials
|
||||
|
||||
3. Document OAuth setup in README
|
||||
- Environment variables needed
|
||||
- Provider setup instructions
|
||||
- Local development flow
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Documentation
|
||||
|
||||
**Already documented**:
|
||||
- .agent/system/auth-architecture.md - Auth system design
|
||||
- .agent/sops/integrations/oauth-setup.md - OAuth provider config
|
||||
|
||||
**Needs documentation**:
|
||||
- Testing strategy for OAuth
|
||||
- Production deployment checklist
|
||||
|
||||
---
|
||||
|
||||
## 💡 Ideas to Explore
|
||||
|
||||
- Add more OAuth providers (GitHub, Twitter)
|
||||
- Implement OAuth scope management
|
||||
- Add "Sign in with" UI component library
|
||||
- Consider magic link as alternative auth method
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Don't Load Again
|
||||
|
||||
These are already documented, don't reload:
|
||||
- .agent/tasks/TASK-123-oauth-auth.md
|
||||
- .agent/system/auth-architecture.md
|
||||
- Previous markers (if any)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Restore Instructions
|
||||
|
||||
To resume from this marker:
|
||||
|
||||
1. Read this marker:
|
||||
```
|
||||
Read @.agent/.context-markers/oauth-working-2025-10-12-143022.md
|
||||
```
|
||||
|
||||
2. Continue with: "Write tests for OAuth flow"
|
||||
|
||||
**Context restored in ~3k tokens instead of replaying 130k token conversation.**
|
||||
|
||||
---
|
||||
|
||||
Generated by: /nav:marker oauth-working
|
||||
```
|
||||
|
||||
### Step 3: Save Marker
|
||||
|
||||
**Create directory if needed**:
|
||||
```bash
|
||||
mkdir -p .agent/.context-markers
|
||||
```
|
||||
|
||||
**Save with naming convention**:
|
||||
```
|
||||
Format: [user-name]-YYYY-MM-DD-HHMMSS.md
|
||||
Example: oauth-working-2025-10-12-143022.md
|
||||
```
|
||||
|
||||
**Write marker**:
|
||||
```
|
||||
Write(
|
||||
file_path: ".agent/.context-markers/oauth-working-2025-10-12-143022.md"
|
||||
content: [marker content from Step 2]
|
||||
)
|
||||
```
|
||||
|
||||
### Step 4: Confirm to User
|
||||
|
||||
Show clear confirmation:
|
||||
|
||||
```
|
||||
✅ Marker saved!
|
||||
|
||||
📍 Location: .agent/.context-markers/oauth-working-2025-10-12-143022.md
|
||||
|
||||
🔄 To restore this state later:
|
||||
Read @.agent/.context-markers/oauth-working-2025-10-12-143022.md
|
||||
|
||||
💾 Marker size: ~3k tokens
|
||||
📊 Current session: ~85k tokens
|
||||
|
||||
Tip: You can continue working or use /nav:compact to free up space.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### List All Markers
|
||||
|
||||
```bash
|
||||
/nav:marker list
|
||||
```
|
||||
|
||||
Shows all available markers:
|
||||
|
||||
```
|
||||
📍 Available Context Markers
|
||||
|
||||
Recent markers (last 7 days):
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
1. oauth-working-2025-10-12-143022.md
|
||||
Created: 2 hours ago
|
||||
Task: TASK-123 - OAuth authentication
|
||||
Size: 3.2k tokens
|
||||
|
||||
2. before-refactor-2025-10-12-091500.md
|
||||
Created: 7 hours ago
|
||||
Task: TASK-122 - Routing refactor
|
||||
Size: 2.8k tokens
|
||||
|
||||
3. day1-complete-2025-10-11-170000.md
|
||||
Created: yesterday
|
||||
Task: TASK-121 - User dashboard
|
||||
Size: 3.5k tokens
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Total: 3 markers | Combined size: 9.5k tokens
|
||||
|
||||
To restore: Read @.agent/.context-markers/[filename]
|
||||
To clean up: /nav:marker clean
|
||||
```
|
||||
|
||||
### Clean Old Markers
|
||||
|
||||
```bash
|
||||
/nav:marker clean
|
||||
```
|
||||
|
||||
Interactive cleanup:
|
||||
|
||||
```
|
||||
🧹 Marker Cleanup
|
||||
|
||||
Found 15 markers older than 7 days:
|
||||
- [list with dates and sizes]
|
||||
|
||||
Keep only:
|
||||
1. Last 7 days (recommended)
|
||||
2. Last 30 days
|
||||
3. Keep all, just show me
|
||||
4. Custom selection
|
||||
|
||||
Choice [1-4]:
|
||||
```
|
||||
|
||||
### Compare Markers
|
||||
|
||||
```bash
|
||||
/nav:marker diff oauth-working before-refactor
|
||||
```
|
||||
|
||||
Shows what changed between two markers:
|
||||
|
||||
```
|
||||
📊 Marker Comparison
|
||||
|
||||
From: before-refactor (7 hours ago)
|
||||
To: oauth-working (2 hours ago)
|
||||
|
||||
Changes:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Tasks:
|
||||
- Completed: TASK-122 (routing refactor)
|
||||
+ Started: TASK-123 (OAuth auth)
|
||||
|
||||
Files Modified:
|
||||
+ src/auth/oauth.ts (new)
|
||||
+ src/auth/tokens.ts (new)
|
||||
~ src/routes/auth.ts (modified)
|
||||
|
||||
Decisions Made:
|
||||
+ Using passport.js for OAuth
|
||||
+ JWT in httpOnly cookies
|
||||
+ Redis for session storage
|
||||
|
||||
Progress: 30% → 70% (task)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Marker Strategies
|
||||
|
||||
### Checkpoint Strategy
|
||||
|
||||
Create markers at natural checkpoints:
|
||||
|
||||
```
|
||||
Feature Planning:
|
||||
/nav:marker planning-complete
|
||||
|
||||
Core Implementation:
|
||||
/nav:marker core-working
|
||||
|
||||
Integration:
|
||||
/nav:marker integration-done
|
||||
|
||||
Testing:
|
||||
/nav:marker tests-passing
|
||||
|
||||
Ready for Review:
|
||||
/nav:marker ready-for-pr
|
||||
```
|
||||
|
||||
**Benefit**: Clear progression, easy to resume at any stage
|
||||
|
||||
### Daily Markers
|
||||
|
||||
End each day with a marker:
|
||||
|
||||
```bash
|
||||
/nav:marker eod-2025-10-12 "Finished OAuth, need tests tomorrow"
|
||||
```
|
||||
|
||||
**Benefit**: Perfect context on Monday for Friday's work
|
||||
|
||||
### Experiment Markers
|
||||
|
||||
Before trying new approaches:
|
||||
|
||||
```bash
|
||||
/nav:marker before-experiment
|
||||
# Try risky refactor
|
||||
# Doesn't work?
|
||||
# Restore from marker, try different approach
|
||||
```
|
||||
|
||||
**Benefit**: Safe exploration, easy rollback
|
||||
|
||||
### Decision Markers
|
||||
|
||||
After important decisions:
|
||||
|
||||
```bash
|
||||
/nav:marker architecture-decision "Chose PostgreSQL over MongoDB"
|
||||
```
|
||||
|
||||
**Benefit**: Capture why decisions were made with full context
|
||||
|
||||
---
|
||||
|
||||
## Marker Best Practices
|
||||
|
||||
### ✅ Do
|
||||
|
||||
- Create markers before breaks (lunch, end of day)
|
||||
- Name markers descriptively (`oauth-working` not `marker-1`)
|
||||
- Add descriptions for important markers
|
||||
- Clean up old markers monthly
|
||||
- Use markers as conversation save points
|
||||
|
||||
### ❌ Don't
|
||||
|
||||
- Don't create markers every 5 minutes (too granular)
|
||||
- Don't use generic names (`test`, `stuff`, `work`)
|
||||
- Don't forget to clean up (markers accumulate)
|
||||
- Don't rely solely on markers (still commit code!)
|
||||
|
||||
---
|
||||
|
||||
## Integration with Navigator Workflow
|
||||
|
||||
### Markers + Compact
|
||||
|
||||
```
|
||||
Work on feature → /nav:marker feature-done
|
||||
Continue to polish → Token usage high
|
||||
/nav:compact
|
||||
Result: Marker preserved, conversation cleared
|
||||
```
|
||||
|
||||
**Benefit**: Markers survive compacts
|
||||
|
||||
### Markers + Tasks
|
||||
|
||||
```
|
||||
Start task → Load task doc
|
||||
Make progress → /nav:marker progress-update
|
||||
Complete → /nav:update-doc feature TASK-XX
|
||||
```
|
||||
|
||||
**Benefit**: Markers complement task documentation
|
||||
|
||||
### Markers + SOPs
|
||||
|
||||
```
|
||||
Hit bug → Debug → Solve
|
||||
/nav:marker bug-solved "Fixed CORS issue with OAuth"
|
||||
/nav:update-doc sop debugging cors-oauth-fix
|
||||
```
|
||||
|
||||
**Benefit**: Markers capture point-in-time, SOPs capture solution
|
||||
|
||||
---
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Marker Storage
|
||||
|
||||
```
|
||||
.agent/.context-markers/
|
||||
├── oauth-working-2025-10-12-143022.md
|
||||
├── before-refactor-2025-10-12-091500.md
|
||||
├── day1-complete-2025-10-11-170000.md
|
||||
└── .gitkeep
|
||||
```
|
||||
|
||||
**Naming**: `[name]-YYYY-MM-DD-HHMMSS.md`
|
||||
|
||||
**Size**: ~3k tokens each
|
||||
|
||||
**Git**: Ignored by default (in .gitignore)
|
||||
|
||||
### Marker Format
|
||||
|
||||
**Required sections**:
|
||||
- Current Location (task, files, progress)
|
||||
- What's Done (achievements)
|
||||
- Technical Decisions (with rationale)
|
||||
- Next Steps (what's remaining)
|
||||
- Restore Instructions (how to resume)
|
||||
|
||||
**Optional sections**:
|
||||
- Challenges & Solutions
|
||||
- Ideas to Explore
|
||||
- Related Documentation
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: End of Day Marker
|
||||
|
||||
```bash
|
||||
You: "Finished implementing user settings page, need to add tests tomorrow"
|
||||
You: /nav:marker eod-settings-done
|
||||
|
||||
Result:
|
||||
✅ Marker saved: .agent/.context-markers/eod-settings-done-2025-10-12-170000.md
|
||||
|
||||
Tomorrow: Read @.agent/.context-markers/eod-settings-done-2025-10-12-170000.md
|
||||
```
|
||||
|
||||
### Example 2: Before Risky Change
|
||||
|
||||
```bash
|
||||
You: "Current routing works. About to refactor to use new router"
|
||||
You: /nav:marker before-routing-refactor
|
||||
You: "Refactor the routing system to use express-router"
|
||||
|
||||
*After testing...*
|
||||
|
||||
You: "The refactor broke auth. Let me restore"
|
||||
You: Read @.agent/.context-markers/before-routing-refactor.md
|
||||
You: "Take different approach - migrate gradually"
|
||||
```
|
||||
|
||||
### Example 3: Multi-Day Feature
|
||||
|
||||
```bash
|
||||
Monday:
|
||||
You: /nav:marker day1-foundation "Built database models and API structure"
|
||||
|
||||
Tuesday:
|
||||
You: Read @.agent/.context-markers/day1-foundation.md
|
||||
You: *continues work*
|
||||
You: /nav:marker day2-integration "Integrated with frontend, working on auth"
|
||||
|
||||
Wednesday:
|
||||
You: Read @.agent/.context-markers/day2-integration.md
|
||||
You: *continues work*
|
||||
You: /nav:marker day3-complete "Feature complete, tests passing"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
**Without markers**:
|
||||
- Resume after break: 5-10 min re-explaining context
|
||||
- Session restart: Lose all context
|
||||
- Risky changes: No safety net
|
||||
- Multi-day work: Fragmented understanding
|
||||
|
||||
**With markers**:
|
||||
- Resume after break: 30 seconds (read marker)
|
||||
- Session restart: Full context restored
|
||||
- Risky changes: Rollback point available
|
||||
- Multi-day work: Continuous context thread
|
||||
|
||||
**Token efficiency**:
|
||||
- Marker: 3k tokens to restore full context
|
||||
- Re-explaining: 20-30k tokens of back-and-forth
|
||||
- **Savings**: 85-90% fewer tokens to resume
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
**Auto-markers**:
|
||||
```json
|
||||
{
|
||||
"auto_marker": {
|
||||
"on_task_complete": true,
|
||||
"on_break_detected": true,
|
||||
"every_n_hours": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Marker search**:
|
||||
```bash
|
||||
/nav:marker search "OAuth"
|
||||
# Returns all markers mentioning OAuth
|
||||
```
|
||||
|
||||
**Marker merge**:
|
||||
```bash
|
||||
/nav:marker merge day1 day2 day3 → feature-complete
|
||||
# Combines multiple markers into one
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Markers transform your AI workflow from stateless to stateful. Never lose context again.** 🎯
|
||||
Reference in New Issue
Block a user