antigravity-claudekit/skills/ck-session-guard/SKILL.md

name, description

name	description
ck-session-guard	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:

{
  "hooks": {
    "session-init": true,
    "subagent-init": true,
    "session-end": true,
    "usage-context-awareness": true
  },
  "codingLevel": 5,
  "plan": {
    "namingFormat": "{date}-{slug}",
    "reportsDir": "plans/reports"
  }
}