feat: /meditate — proactive repo consciousness

[sevastyanovio]

Author: Roman Sevast, co-founder of Awesomic (YC S21). Inspired by Vipassana meditation practice — built this after using gstack on our codebase.

Summary

Inspired by Vipassana body-scanning meditation — systematic observation that builds awareness without judgment.

• New /meditate skill — scans repo structure, git history, and past AI conversations (Claude Code, Codex CLI, Gemini CLI) to produce .gstack/context.md. Every other skill reads this file and becomes smarter: /qa knows which flows to hammer, /review focuses on high-risk files, /cso already knows the attack surface.
• Scanner binary (bin/gstack-meditate.ts) — deterministic data collection with zero LLM cost. Compiled via bun build --compile. Runs in <1s on this repo.
• Multi-AI conversation mining — discovers sessions from Claude Code, Codex CLI, and Gemini CLI. Extracts file references, error patterns, workflow habits across tools. Privacy-first: only patterns in 3+ sessions included, never raw prose.
• Six-section context file — Architecture Map, Hotspots, Conventions, User Taste, Recurring Problems, Watch These Next. Capped at 1024 lines.
• Preamble integration — all skills now check .gstack/context.md freshness.
• Template-based --background mode — produces basic context.md without LLM tokens.

Why This Matters

The Missing Layer in AI Coding

Today's AI coding has three context mechanisms: static docs (CLAUDE.md), reactive memory (auto-memories), and search/indexing (Greptile, Sourcegraph). What's missing is proactive awareness — a system that systematically observes the repo and your behavior, builds understanding over time, and feeds it to every tool. Not search. Consciousness.

Why gstack Needs This to Reach L8

The L0-L8 AI development maturity levels put gstack at L7 — 10+ agents managed through a skill orchestration layer. To reach L8 ("Build your own orchestrator"), agents need to be self-aware. An orchestrator without repo consciousness is just a dispatcher. An orchestrator with consciousness can make autonomous decisions — what to scan harder, what to skip, what to flag — because it has priors.

/meditate is the infrastructure that makes L8 possible. Without it, each skill starts blind. With it, each skill inherits accumulated awareness.

The Vipassana Insight: Awareness vs. Search

The industry's instinct is better search when context is lacking. But awareness is not search:

• Search = "I can find any file in 100ms" — reactive, starts from nothing
• Awareness = "I know what matters and why, without being asked" — proactive, cumulative

Every tool builds search. /meditate builds awareness. Fundamentally different paradigm.

Test Coverage

10/10 unit tests passing. 567 tests across full suite, 0 failures from this branch.

[★★★ TESTED] deriveSlug, scanRepoStructure, detectLanguages, scanTodos,
             extractDocs, templateSynthesize (format + 1024 limit),
             templateSynthesize (minimal input), full scanner run (JSON + multi-AI)
[★★  TESTED] CLI --help

Test plan

• 10 scanner unit tests pass
• 567 tests pass across full suite (0 failures from our changes)
• Scanner produces valid JSON (609ms on gstack repo)
• --background produces .gstack/context.md (85 lines, under 1024 limit)
• All 6 context sections present
• Multi-AI: detected 6 Claude Code sessions correctly
• No path leaks in Codex-generated SKILL.md

🤖 Generated with Claude Code

[garrytan]

Thanks for the creative work! Closing — a meditation/Vipassana skill for repos is outside the scope of what gstack is trying to be. We're focused on practical developer workflow tools. Appreciate the imaginative approach though!