Initial commit: antigravity-claudekit

skills/ck-session-guard/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: ck-session-guard
+description: Session lifecycle management — initializes environment context, injects project info into subagents, tracks usage limits, cleans up on session end. Activates automatically at session start, subagent start, and session end.
+---
+
+# ck-session-guard
+
+Manages session lifecycle: environment detection at startup, context injection into subagents, usage limit tracking, and clean teardown. This guard runs automatically — it is not manually invoked.
+
+## When Active
+
+- **Session Start**: Fires once per session (startup, resume, `/clear`, compact)
+- **Subagent Start**: Fires when any agent is dispatched
+- **Session End**: Fires when session ends (clear, compact, user exit)
+- **Usage Tracking**: Fires on each user prompt and periodically on tool use
+
+## Don't Use When
+
+- This is a background guard — never invoke manually
+- If session context appears stale, use `/clear` to reset
+
+---
+
+## Session Start Behavior
+
+Detects and injects into the session environment:
+
+**Project Detection:**
+- Project type (Node.js, Python, Go, etc.)
+- Package manager (npm, yarn, pnpm, bun)
+- Framework (Next.js, NestJS, FastAPI, etc.)
+- Git branch, remote URL, and root directory
+
+**Plan Resolution:**
+- Active plan: explicitly set via session state — used for report paths
+- Suggested plan: branch-matched hint — shown to user, NOT auto-activated
+- No plan: create new using `## Naming` pattern
+
+**Environment Variables set:**
+- `CK_SESSION_ID`, `CK_ACTIVE_PLAN`, `CK_SUGGESTED_PLAN`
+- `CK_REPORTS_PATH`, `CK_PLANS_PATH`, `CK_DOCS_PATH`
+- `CK_GIT_BRANCH`, `CK_GIT_ROOT`, `CK_PROJECT_TYPE`
+- `CK_NAME_PATTERN` — computed naming pattern for reports/plans
+
+**Coding Level Guidelines:** If configured (levels 0–5), injects response format guidelines for output depth and style.
+
+**User Assertions:** If configured, injects custom user rules into session context.
+
+**Post-Compact Warning:** When session was compacted, injects a reminder:
+> "Context was compacted. If you were waiting for user approval via an interactive question (e.g., a review gate), you MUST re-confirm with the user before proceeding. Do NOT assume approval was given."
+
+---
+
+## Subagent Start Behavior
+
+Injects a compact context block (~200 tokens) into every dispatched agent:
+
+```
+## Subagent: {agent-type}
+ID: {id} | CWD: {cwd}
+
+## Context
+- Plan: {active-plan or none}
+- Reports: {reports-path}
+- Paths: {plans-path}/ | {docs-path}/
+
+## Rules
+- Reports → {reports-path}
+- YAGNI / KISS / DRY
+- Concise, list unresolved Qs at end
+- Python scripts in .claude/skills/: Use `{venv-path}`
+- Never use global pip install
+
+## Naming
+- Report: {reports-path}/{agent-type}-{name-pattern}.md
+- Plan dir: {plans-path}/{name-pattern}/
+```
+
+**Monorepo support:** Uses the subagent's own CWD (not process CWD) for path resolution, enabling subdirectory workflows.
+
+---
+
+## Session End Behavior
+
+On `/clear`: Deletes the compact marker file to reset the context baseline for the next session. Ensures a clean slate without stale state from the previous session.
+
+---
+
+## Usage Tracking Behavior
+
+Fetches Claude usage limits from the Anthropic OAuth API and writes to a local cache file (`/tmp/ck-usage-limits-cache.json`).
+
+- Throttled: 1-minute intervals on user prompts; 5-minute intervals on tool use
+- Cross-platform credential retrieval: macOS Keychain, or file-based at `~/.claude/.credentials.json`
+- Cache TTL: 60 seconds
+- Fails silently — never blocks the session
+
+---
+
+## Skill Dedup (Reference Only)
+
+Originally designed to prevent local project skills from shadowing global versions. **Disabled** due to race conditions with parallel sessions. Any orphaned `.claude/skills/.shadowed/` directories are automatically restored at session start.
+
+---
+
+## Configuration
+
+All behavior configurable in `$HOME/.claude/.ck.json`:
+
+```json
+{
+  "hooks": {
+    "session-init": true,
+    "subagent-init": true,
+    "session-end": true,
+    "usage-context-awareness": true
+  },
+  "codingLevel": 5,
+  "plan": {
+    "namingFormat": "{date}-{slug}",
+    "reportsDir": "plans/reports"
+  }
+}
+```