@boshu2/vibe-check 1.8.1 → 2.2.0

package/.agents/research/2025-12-27-vibe-check-evolution.md

@@ -0,0 +1,352 @@
+---
+date: 2025-12-27
+type: Research
+topic: "Vibe-Check Evolution: Features and Improvements Roadmap"
+tags: [research, vibe-check, vibe-coding, roadmap, improvements]
+status: COMPLETE
+---
+
+# Research: Vibe-Check Evolution
+
+**Created:** 2025-12-27
+**Goal:** Understand the current state of vibe-check and identify opportunities for improvement based on the broader vibe-coding ecosystem
+
+---
+
+## Executive Summary
+
+vibe-check is a **production-ready** CLI tool (v2.1.0) that detects the 4 inner loop failure patterns from Gene Kim & Steve Yegge's *Vibe Coding* methodology. The tool has evolved from a simple metrics analyzer to a comprehensive coaching system with gamification, real-time monitoring, and session integration.
+
+**Key findings:**
+1. **Core metrics are solid** - 5 semantic-free metrics work well across any codebase
+2. **Inner loop detection is complete** - All 4 inner loop disasters are detected
+3. **Enhancement Plan exists** - Documented but unimplemented improvements for investigation gaps, tracer tracking, and domain cohesion
+4. **Agent integration opportunity** - Concept for "Vibe Validator" agent that verifies completion claims
+5. **Middle/Outer loop gaps** - 8 additional failure patterns not yet detected
+
+**Recommendation:** Implement the Enhancement Plan (tracer bullets, investigation gaps) and explore agent integration for autonomous development validation.
+
+---
+
+## Current State
+
+### What Exists (v2.1.0)
+
+| Component | Status | Description |
+|-----------|--------|-------------|
+| **5 Core Metrics** | Complete | Velocity, Rework, Trust, Spirals, Flow |
+| **4 Semantic-Free Metrics** | Complete | File Churn, Time Spiral, Velocity Anomaly, Code Stability |
+| **Inner Loop Detection** | Complete | Tests Lie, Amnesia, Drift, Debug Spiral |
+| **Gamification** | Complete | XP, Levels, Streaks, 18 Achievements |
+| **Session Tracking** | Complete | Baseline comparison, failure pattern detection |
+| **Watch Mode** | Complete | Real-time spiral detection |
+| **Dashboard** | Complete | Visual charts and metrics |
+| **Forensics** | Complete | Deep pattern analysis |
+| **Audit** | Complete | Static code mess detection |
+| **Modularity Analysis** | Complete | Pattern-aware module structure |
+
+### Architecture Strengths
+
+1. **Clean separation** - CLI → Analysis → Data → Output layers
+2. **100% TypeScript** - Full type coverage, no `any` in public APIs
+3. **Extensible patterns** - Easy to add new detectors
+4. **Atomic persistence** - Safe file operations with schema versioning
+5. **Comprehensive tests** - 114 tests, all passing
+6. **Personalized coaching** - Spiral history enables context-aware advice
+
+### Key Files
+
+| File | Purpose | Lines |
+|------|---------|-------|
+| `src/metrics/index.ts` | Metrics orchestration | 150 |
+| `src/inner-loop/index.ts` | Inner loop aggregator | 97 |
+| `src/gamification/xp.ts` | XP calculation | 85 |
+| `src/commands/session.ts` | Session management | 250 |
+| `src/commands/watch.ts` | Real-time monitoring | 180 |
+
+---
+
+## Existing Enhancement Plan
+
+From `docs/ENHANCEMENT-PLAN.md` (dated 2025-12-11), these improvements are documented but not implemented:
+
+### P1: Investigation Gap Detection
+**Problem:** Long gaps between commits indicate hidden debugging time.
+
+```typescript
+interface InvestigationGap {
+  startCommit: string
+  endCommit: string
+  gapMinutes: number
+  followedByFix: boolean
+  component: string
+}
+```
+
+**Rating:** >30min gap followed by fix = investigation time
+**Impact:** Surfaces the hidden cost of debugging
+
+### P2: Tracer Bullet Tracking
+**Problem:** No visibility into whether assumptions were validated before building.
+
+```typescript
+// Convention: commits starting with "tracer:" or "tb:"
+interface TracerMetrics {
+  tracerCount: number
+  tracerBeforeFeature: number
+  tracerBeforeFix: number  // too late!
+  tracerRatio: number
+}
+```
+
+**Rating:** ELITE >20% | HIGH >10% | MEDIUM >5% | LOW <5%
+**Impact:** Encourages proactive validation
+
+### P3: Domain Cohesion Score
+**Problem:** Scattered changes indicate coupling.
+
+```typescript
+interface CohesionMetrics {
+  avgDomainsPerCommit: number
+  scatteredCommits: number  // 3+ domains
+  cohesiveCommits: number   // 1 domain
+  cohesionScore: number     // 0-100%
+}
+```
+
+**Rating:** ELITE >80% | HIGH >60% | MEDIUM >40% | LOW <40%
+**Impact:** Architectural feedback
+
+### P4: Session Markers (Wall-Clock)
+**Problem:** Git timestamps don't capture actual session duration.
+
+```typescript
+interface Session {
+  wallClockMinutes: number
+  commitMinutes: number
+  investigationMinutes: number  // wallClock - commitMinutes
+  efficiency: number
+}
+```
+
+**Impact:** Accurate time tracking for coaching
+
+---
+
+## Vibe Validator Concept
+
+From `.agents/research/2025-12-10-vibe-check-agent-concept.md`:
+
+### The Problem
+
+Autonomous agents (like Gusto) **trust** completion claims. When an agent outputs `<promise>COMPLETE</promise>`, the system believes it.
+
+### The Solution
+
+A "Vibe Validator" that **verifies** before allowing exit:
+
+1. **Tests Lie Detector** - Actually run `npm test`
+2. **Build Verification** - Actually run `npm run build`
+3. **Fake Data Detector** - Pattern match for suspicious test code
+4. **Smoke Tests** - Run tracer tests if configured
+
+### Implementation Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│              Vibe-Check Agent (Observer)            │
+│                                                     │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
+│  │ Inner Loop  │  │ Middle Loop │  │ Outer Loop  │ │
+│  │  Detector   │  │  Detector   │  │  Detector   │ │
+│  │  (4 patterns)│  │  (4 patterns)│  │  (4 patterns)│ │
+│  └─────────────┘  └─────────────┘  └─────────────┘ │
+│                          │                         │
+│              ┌───────────────────────┐             │
+│              │   Intervention Engine │             │
+│              │   (Stop/Warn/Log)     │             │
+│              └───────────────────────┘             │
+└─────────────────────────────────────────────────────┘
+```
+
+### Integration Options
+
+1. **Hook-Based** - Use Claude Code hooks to intercept agent actions
+2. **Side-Car** - Separate process monitors output file
+3. **Integrated Agent** - Claude agent runs via Task tool as observer
+
+---
+
+## Middle/Outer Loop Gaps
+
+vibe-check currently focuses on inner loop. These patterns are documented but not detected:
+
+### Middle Loop (Hours-Days)
+
+| Pattern | Detection Strategy | Effort |
+|---------|-------------------|--------|
+| **Eldritch Horror** | Static analysis (function line count) | Medium |
+| **Agent Collision** | File lock detection | Medium |
+| **Memory Decay** | Bundle/progress file checks | Low |
+| **Deadlock** | Process state monitoring | High |
+
+### Outer Loop (Weeks-Months)
+
+| Pattern | Detection Strategy | Effort |
+|---------|-------------------|--------|
+| **Bridge Torch** | API diff analysis | High |
+| **Deletion** | Git diff pre-commit | Medium |
+| **Gridlock** | GitHub API / queue analysis | Medium |
+| **Stewnami** | feature-list.json analysis | Low |
+
+---
+
+## The Vibe Ecosystem
+
+vibe-check is one layer in a three-layer system:
+
+```
+BUILD → WORK → RUN
+
+12-Factor Agents  → Vibe Coding → 12-Factor AgentOps
+(HumanLayer)        (Gene & Steve)    (Operations)
+```
+
+**Vibe Coding is the DevOps movement for AI.**
+**12-Factor AgentOps is the SRE to their DevOps.**
+
+### Related Projects
+
+| Project | Purpose | Integration |
+|---------|---------|-------------|
+| **12-Factor AgentOps** | Operational principles | Documents patterns vibe-check detects |
+| **Beads** | Git-backed issue tracker | `/research → /plan → /implement` workflow |
+| **Houston** | Agent harness | Uses vibe-check for session metrics |
+| **Gusto** | Autonomous loop | Completion checking pattern |
+
+---
+
+## Improvement Opportunities
+
+### High Priority
+
+| Feature | Value | Effort | Source |
+|---------|-------|--------|--------|
+| **Tracer Bullet Tracking** | Encourages proactive validation | 2h | Enhancement Plan |
+| **Investigation Gap Detection** | Surfaces hidden debugging | 2-3h | Enhancement Plan |
+| **Middle Loop: Eldritch Horror** | Function length analysis | 3h | Agent Concept |
+| **Middle Loop: Stewnami** | WIP limit detection | 2h | Agent Concept |
+
+### Medium Priority
+
+| Feature | Value | Effort | Source |
+|---------|-------|--------|--------|
+| **Domain Cohesion Score** | Architectural feedback | 3-4h | Enhancement Plan |
+| **Agent Collision Detector** | Multi-agent safety | 4h | Agent Concept |
+| **VS Code Extension** | Status bar, live alerts | 8-10h | VIBE-ECOSYSTEM.md |
+| **Claude Code Plugin** | Native integration | 6h | Agent Concept |
+
+### Low Priority
+
+| Feature | Value | Effort | Source |
+|---------|-------|--------|--------|
+| **Pre-Commit Verification** | Hook-based test tracking | 2-3h | Enhancement Plan |
+| **Wall-Clock Sessions** | Explicit start/end tracking | 4-5h | Enhancement Plan |
+| **Bridge Torch Detection** | API diff analysis | 8h | Agent Concept |
+| **GitHub Action v2** | PR blocking on patterns | 4h | Existing |
+
+---
+
+## Constraints
+
+| Constraint | Impact | Mitigation |
+|------------|--------|------------|
+| **Conventional commits required** | Full accuracy needs `type(scope): message` | Semantic-free metrics work without |
+| **Git-only analysis** | Can't see wall-clock time | Session markers (proposed) |
+| **Single-repo focus** | No cross-repo analysis | Future enhancement |
+| **Node.js 20+ required** | ESM-only package | Document in README |
+
+---
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| **False positives in detection** | Medium | Medium | Calibration thresholds, user feedback |
+| **Performance on large repos** | Low | Medium | Caching, incremental analysis |
+| **User adoption** | Medium | High | Documentation, gamification |
+| **Scope creep** | Medium | Medium | Stick to inner loop focus |
+
+---
+
+## Recommendation
+
+**Approach:** Implement Enhancement Plan P1-P2, then explore agent integration
+
+**Phases:**
+
+1. **Phase 1: Tracer Bullets + Investigation Gaps** (4-5h)
+   - Implement `src/metrics/tracers.ts`
+   - Implement `src/metrics/investigation.ts`
+   - Add to analyze output
+   - Update documentation
+
+2. **Phase 2: Middle Loop Basics** (5-6h)
+   - Implement Eldritch Horror detector (function line count)
+   - Implement Stewnami detector (WIP analysis)
+   - Add to audit command
+
+3. **Phase 3: Agent Integration** (6-8h)
+   - Create Claude Code plugin structure
+   - Implement Stop hook for validation
+   - Test with Gusto workflow
+
+4. **Phase 4: VS Code Extension** (8-10h)
+   - Status bar metrics
+   - Real-time spiral alerts
+   - Session controls
+
+**Why:**
+- Enhancement Plan is documented and ready
+- Tracer bullets align with vibe-coding methodology
+- Agent integration enables autonomous development validation
+- VS Code extension increases adoption
+
+**Alternatives Considered:**
+1. **Start with VS Code** - Rejected: Higher effort, lower immediate value
+2. **Full middle/outer loop** - Rejected: Scope creep, inner loop is the focus
+3. **Rebuild as Claude plugin only** - Rejected: CLI value should be preserved
+
+---
+
+## Next Steps
+
+1. Run `/plan` to create implementation plan for Phase 1
+2. Plan will create beads issues from this research
+3. Implement tracer bullet tracking first (highest value:effort ratio)
+
+---
+
+## Sources
+
+### Vault Documents
+- `docs/ENHANCEMENT-PLAN.md` - Documented improvements (Dec 11)
+- `docs/VIBE-ECOSYSTEM.md` - Ecosystem overview
+- `.agents/research/2025-12-10-vibe-check-agent-concept.md` - Agent integration concept
+
+### Workspace Documents
+- `work/houston/.agents/research/2025-12-10-vibe-coding-inner-loop.md` - Inner loop patterns
+- `work/research/2025-12-09-vibe-check-algorithms.md` - Algorithm details
+- `personal/12-factor-agentops/docs/explanation/vibe-coding-integration.md` - Ecosystem integration
+- `work/gitops/docs/methodology/vibe-ecosystem/vibe-coding/README.md` - Methodology docs
+
+### External
+- *Vibe Coding* (Gene Kim & Steve Yegge, IT Revolution Press, 2025)
+- 12-Factor AgentOps framework
+- Beads workflow system
+
+---
+
+**Output:** .agents/research/2025-12-27-vibe-check-evolution.md
+
+**Next:** /plan .agents/research/2025-12-27-vibe-check-evolution.md

package/.claude/settings.local.json

@@ -1,7 +1,13 @@
 {
-  "includeCoAuthoredBy": true,
+  "includeCoAuthoredBy": false,
+  "permissions": {
+    "allow": [
+      "mcp__smart-connections-work__lookup",
+      "mcp__smart-connections-personal__lookup"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
   "enabledMcpjsonServers": [
     "context7"
-  ],
-  "enableAllProjectMcpServers": true
+  ]
 }

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2025-12-27
+
+### Added
+
+- **Enhanced Metrics** - Three new metrics for deeper insights into development habits
+  - **Tracer Bullet Ratio** - Measures proactive validation via `tracer:` or `tb:` commits
+    - Tracers before features = proactive validation (good!)
+    - Tracers before fixes = reactive debugging (too late!)
+    - Rating: ELITE >20% | HIGH >10% | MEDIUM >5% | LOW <5%
+  - **Investigation Gap Detection** - Surfaces hidden debugging time
+    - Detects gaps >15min followed by fix commits
+    - Shows total investigation time and longest gap
+    - Rating: ELITE 0min | HIGH <30min | MEDIUM <60min | LOW >60min
+  - **Domain Cohesion Score** - Measures how focused changes are
+    - Cohesive commits touch 1 domain
+    - Scattered commits touch 3+ domains
+    - Rating: ELITE >80% | HIGH >60% | MEDIUM >40% | LOW <40%
+
+- **Eldritch Horror Detector** - Detects oversized functions in the `audit` command
+  - Functions >200 lines = warning
+  - Functions >500 lines = critical
+  - Supports TypeScript, JavaScript, Python, Go
+
+- **Tracer Commit Type** - New `tracer` commit type recognized
+  - Use `tracer:` or `tb:` prefix for tracer bullet commits
+  - Example: `tracer(auth): validate OAuth token refresh flow`
+  - Tracers are counted separately from features/fixes
+
+### Changed
+
+- Enhanced metrics are calculated when using `--score` flag
+- Audit command now includes function-level analysis
+
+## [2.0.0] - 2025-12-15
+
+### Added
+- **Audit Command** - `vibe-check audit` for static analysis of code messes (monoliths, test gaps, TODOs)
+
+### Changed
+- **ESM Migration** - Package is now pure ESM (`type: module`). Requires Node.js 20+.
+- **Dependencies** - Updated all dependencies to December 2025 latest versions.
+- **Chalk v5** - Updated to `chalk` v5 (ESM only).
+
 ## [1.8.0] - 2025-12-05
 
 ### Added

package/CLAUDE.md

@@ -1,29 +1,5 @@
 # vibe-check Development Guide
 
-## Opus 4.5 Behavioral Standards
-
-<default_to_action>
-By default, implement changes rather than only suggesting them. If the user's intent is unclear, infer the most useful likely action and proceed, using tools to discover any missing details instead of guessing.
-</default_to_action>
-
-<use_parallel_tool_calls>
-When performing multiple independent operations (reading multiple files, running multiple checks), execute them in parallel rather than sequentially. Only sequence operations when one depends on another's output.
-</use_parallel_tool_calls>
-
-<investigate_before_answering>
-Before proposing code changes, read and understand the relevant files. Do not speculate about code you have not opened. Give grounded, hallucination-free answers based on actual code inspection.
-</investigate_before_answering>
-
-<avoid_overengineering>
-Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused. Do not add features, refactor code, or make "improvements" beyond what was asked. Do not create helpers or abstractions for one-time operations.
-</avoid_overengineering>
-
-<communication_style>
-After completing tasks involving tool use, provide a brief summary of work done. When making significant changes, explain what was changed and why. Keep summaries concise but informative.
-</communication_style>
-
----
-
 ## npm Publishing Standards
 
 ### When to Publish
@@ -161,7 +137,10 @@ src/
 │   ├── file-churn.ts   # File churn patterns
 │   ├── time-spiral.ts  # Time-based spirals
 │   ├── velocity-anomaly.ts # Velocity anomaly detection
-│   └── code-stability.ts   # Code stability metrics
+│   ├── code-stability.ts   # Code stability metrics
+│   ├── tracers.ts      # Tracer bullet ratio (v2.2.0)
+│   ├── investigation.ts # Investigation gap detection (v2.2.0)
+│   └── cohesion.ts     # Domain cohesion score (v2.2.0)
 ├── gamification/
 │   ├── index.ts        # Gamification exports
 │   ├── types.ts        # XP, levels, achievements types
@@ -190,6 +169,11 @@ src/
 │   ├── context-amnesia.ts      # Context Amnesia detector
 │   ├── instruction-drift.ts    # Instruction Drift detector
 │   └── logging-only.ts         # Debug Loop Spiral detector
+├── analyzers/
+│   ├── audit.ts           # Codebase audit (monoliths, test gaps, TODOs)
+│   ├── eldritch.ts        # Eldritch horror detector (oversized functions)
+│   ├── modularity.ts      # Module structure analysis
+│   └── patterns.ts        # Pattern analysis
 └── output/
     ├── index.ts        # Output format router
     ├── terminal.ts     # Colored terminal output
@@ -271,6 +255,24 @@ Shows your spiral history, patterns by frequency, what resolutions worked, and p
 | Debug Spiral Duration | Avg time in fix chains | <15m = Elite |
 | Flow Efficiency | % time building vs debugging | >90% = Elite |
 
+## Enhanced Metrics (v2.2.0)
+
+Three additional metrics for deeper insight into development habits:
+
+| Metric | Measures | Threshold |
+|--------|----------|-----------|
+| Tracer Bullet Ratio | % of tracer: commits | >20% = Elite |
+| Investigation Time | Hidden debugging time (gaps before fixes) | 0min = Elite |
+| Domain Cohesion | % single-domain commits | >80% = Elite |
+
+**Tracer Bullets:** Use `tracer:` or `tb:` prefix for validation commits:
+```
+tracer(auth): validate OAuth token refresh
+tb(api): test streaming endpoint response
+```
+
+Tracers before features = proactive. Tracers before fixes = reactive (too late!).
+
 ## Debug Spiral Detection
 
 A "debug spiral" is detected when 3+ consecutive fix commits target the same component. Patterns are categorized:
@@ -331,6 +333,179 @@ src/inner-loop/
 When critical inner loop failures are detected:
 
 ```
-🚨 EMERGENCY PROTOCOL: Multiple inner loop failures detected.
+EMERGENCY PROTOCOL: Multiple inner loop failures detected.
 STOP → git status → backup → start simple
 ```
+
+---
+
+# Vibe-Coding Methodology
+
+---
+
+## The One Rule
+
+> Reality does not match your model? **Update the model.**
+
+Not the code. Not the tests. Not the plan. **The model in your head.**
+
+---
+
+## Opus 4.5 Behavioral Standards
+
+<default_to_action>
+When uncertain, act rather than asking for clarification. Make reasonable assumptions, implement, and verify. If wrong, adjust.
+</default_to_action>
+
+<use_parallel_tool_calls>
+When multiple operations are independent (file reads, searches, API calls), batch them in a single response. Don't serialize what can parallelize.
+</use_parallel_tool_calls>
+
+<investigate_before_answering>
+When you don't know something, investigate using available tools before saying you can't help. Read files, search code, check documentation.
+</investigate_before_answering>
+
+---
+
+## Explicit Reasoning Protocol (L1-L3 Only)
+
+For uncertain work, externalize predictions:
+
+```
+DOING: [current action]
+EXPECT: [predicted outcome]
+IF WRONG: [planned adjustment]
+
+RESULT: [actual outcome]
+MATCHES: [yes/no]
+THEREFORE: [continue/stop/pivot]
+```
+
+---
+
+## On Failure
+
+When something fails, surface it immediately. Don't hide errors or pretend success:
+- Show the actual error
+- State what you expected
+- Suggest the most likely cause
+- Propose a fix or investigation path
+
+---
+
+## Vibe Levels (Trust Calibration)
+
+| Level | Trust | Verify | Use For | Example |
+|-------|-------|--------|---------|---------|
+| **5** | 95% | Final only | Format, lint | Fix typo |
+| **4** | 80% | Spot check | Boilerplate | Add CRUD endpoint |
+| **3** | 60% | Key outputs | CRUD, tests | New feature |
+| **2** | 40% | Every change | Features | Integration |
+| **1** | 20% | Every line | Architecture | New system |
+| **0** | 0% | N/A | Research | Exploration |
+
+---
+
+## The 5 Core Metrics
+
+| Metric | Question | Target | Red Flag |
+|--------|----------|--------|----------|
+| **Iteration Velocity** | How tight are feedback loops? | >3/hour | <1/hour |
+| **Rework Ratio** | Building or debugging? | <50% | >70% |
+| **Trust Pass Rate** | Does code stick? | >80% | <60% |
+| **Debug Spiral Duration** | How long stuck? | <30min | >60min |
+| **Flow Efficiency** | What % productive? | >75% | <50% |
+
+---
+
+## The 12 Failure Patterns
+
+### Inner Loop (Seconds-Minutes)
+1. **Tests Passing Lie** - Tests pass but don't validate
+2. **Premature Abstraction** - Solving problems you don't have
+3. **Debug Loop Spiral** - Same fix failing repeatedly
+
+### Middle Loop (Hours-Days)
+4. **Plan-Reality Gap** - Plan doesn't match implementation
+5. **Scope Creep** - Features growing beyond plan
+6. **Bridge Torching** - Breaking backwards compatibility
+7. **Eldritch Horror Merge** - Massive PRs nobody can review
+
+### Outer Loop (Days-Weeks)
+8. **Context Amnesia** - Forgetting session insights
+9. **Instruction Drift** - Wandering from user intent
+10. **Memory Tattoo Decay** - Knowledge not persisted
+11. **Trust Erosion** - Repeated failures lower trust
+12. **Requirement Telephone** - Requirements mutating through layers
+
+---
+
+## The 10 Laws of an Agent
+
+1. **Reality First** - Reality != model? Update model.
+2. **Explicit Predictions** - State expected outcomes before acting.
+3. **Git Discipline** - Add files individually, semantic commits.
+4. **TDD with Tracers** - Validate assumptions before building.
+5. **Guide with Workflows** - Use /research, /plan, /implement.
+6. **Classify Vibe Level** - L0-L5 before each task.
+7. **Measure and Calibrate** - Track 5 metrics, adjust.
+8. **Session Protocol** - One feature focus per session.
+9. **Protect Feature Definitions** - Features are contracts.
+10. **Explicit Reasoning** - For L1-L3, externalize thinking.
+
+---
+
+## Autonomy Boundaries
+
+**Proceed autonomously:**
+- Implementing approved plans
+- Running tests and fixing failures
+- Reading files to understand context
+- Making git commits with proper messages
+
+**Punt to user:**
+- Deleting user data
+- Pushing to main/master
+- Changing architectural decisions
+- Spending money (API calls, services)
+- Security-sensitive changes
+
+---
+
+## Context Window Discipline
+
+**The 40% Rule:** Start planning handoff at 40% context usage.
+
+| Context % | Action |
+|-----------|--------|
+| 0-20% | Deep work mode |
+| 20-40% | Normal operation |
+| 40-60% | Plan handoff, save state |
+| 60-80% | Emergency save only |
+| 80%+ | Stop, save, new session |
+
+---
+
+## Slash Commands (Reference)
+
+| Command | Purpose | Token Budget |
+|---------|---------|--------------|
+| `/research` | Deep exploration | 40-60k |
+| `/plan` | Precise specifications | 40-60k |
+| `/implement` | Execute approved plan | 60-80k |
+| `/bundle-save` | Compress findings | 500-1k output |
+| `/bundle-load` | Resume context | Load bundle |
+| `/retro` | Session retrospective | 5-10k |
+| `/learn` | Extract patterns | 5-10k |
+
+---
+
+## Communication Standards
+
+- **Direct:** State facts, skip hedging
+- **Objective:** Focus on technical accuracy
+- **Brief:** Context is expensive
+
+---
+
+**Last Updated:** 2025-12-17