Kiro Company Brain

Kiro provides Sam with company memory, owner map, Slack-style decisions, Notion-style docs, onboarding rules, active project context, and guardrails.

# Codebase Onboarding for Sam ## Project Overview **crackstack** is a terse communication framework for AI coding assistants. It reduces token usage by ~46-75% while maintaining technical accuracy through "caveman mode" - a structured compression pattern that eliminates filler while preserving all technical substance. ## Core Conventions ### Communication Style **Source**: `skills/caveman/SKILL.md`, `rules/caveman-activate.md` The project uses "caveman mode" with multiple intensity levels: - **lite**: Drop articles, filler words. Keep structure readable. - **full**: Fragments OK. Short synonyms. Pattern: [thing] [action] [reason]. - **ultra**: Max compression. Single-word responses when possible. - **wenyan**: Classical Chinese style (文言文) - extreme terseness. **Pattern Example** (from `skills/compress/SKILL.md`): ``` Original: "You should always make sure to run the test suite before pushing..." Compressed: "Run tests before push to main. Catch bugs early, prevent broken prod deploys." ``` ### Commit Messages **Source**: `skills/caveman-commit/SKILL.md` Strict Conventional Commits format: - **Subject**: `<type>(<scope>): <imperative summary>` - 50 chars preferred, 72 hard cap - **Types**: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert` - **Imperative mood**: "add", "fix", "remove" (NOT "added", "adds", "adding") - **No trailing period** - **Body only when needed**: non-obvious why, breaking changes, migration notes - **What NEVER goes in**: "This commit does X", "I/we", AI attribution, emoji, restating file names ### Code Review Style **Source**: `skills/caveman-review/SKILL.md` One-line PR comments: `L42: bug: user null. Add guard.` **Auto-Clarity exceptions** - Drop terse mode for: - Security findings (CVE-class bugs need full explanation + reference) - Architectural disagreements (need rationale) - Onboarding contexts (new authors need the "why") ## File Structure & Ownership **Source**: `CLAUDE.original.md` ### Single Source of Truth Files (EDIT ONLY THESE): | File | Owns | |------|------| | `skills/caveman/SKILL.md` | Caveman behavior: intensity levels, rules, wenyan mode, auto-clarity, persistence | | `rules/caveman-activate.md` | Always-on auto-activation rule body (injected into agent configs by CI) | | `skills/caveman-commit/SKILL.md` | Commit message behavior (independent skill) | | `skills/caveman-review/SKILL.md` | Code review behavior (independent skill) | | `skills/compress/SKILL.md` | Compress sub-skill behavior | **DO NOT edit agent-specific copies** - they're generated from the source files above. ## Installation Architecture **Source**: `install.sh`, `tools/caveman-init.js` ### Supported Agents (30+ platforms): **Native**: Claude Code, Gemini CLI, Codex CLI **IDE/VS Code**: Cursor, Windsurf, Cline, Continue, Kilo, Roo, Augment **CLI agents**: Aider Desk, Sourcegraph Amp, IBM Bob, Crush, Devin, Droid, ForgeCode, Block Goose, iFlow, JetBrains Junie, Kiro, Mistral Vibe, OpenHands, opencode, Qwen Code, Qoder, Atlassian Rovo Dev, Tabnine, Trae, Warp, Replit, Google Antigravity **Per-repo rules**: GitHub Copilot (`.github/copilot-instructions.md`), AGENTS.md (Zed, etc.) ### Installation Modes: ```bash install.sh # default: plugin + hooks + MCP shrink install.sh --all # also drop per-repo rule files install.sh --minimal # plugin/extension only install.sh --only cursor # specific agent only ``` ## Key Skills/Tools **Source**: `skills/caveman-help/SKILL.md` | Skill | Trigger | Function | |-------|---------|----------| | **caveman-commit** | `/caveman-commit` | Terse commit messages. 50 char subject. | | **caveman-review** | `/caveman-review` | One-line PR comments | | **caveman-compress** | `/caveman:compress <file>` | Compress .md files. Saves ~46% tokens. | | **caveman-help** | `/caveman-help` | Skills reference card | ## Chaining Patterns for Development **Source**: `skills/cavecrew/SKILL.md` ### Locate → Fix → Verify (most common): 1. `cavecrew-investigator` returns site list 2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder` 3. `cavecrew-reviewer` audits the diff ### Parallel Scout (broad investigation): Spawn 2-3 `cavecrew-investigator` calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread. ### Single-shot Edit (known site): Skip investigator. Hand exact `path:line` to `cavecrew-builder` directly. ## Testing & PR Workflow **No explicit test files found in provided sources**, but conventions imply: - Run tests before push to main (from compression examples) - Reviews use `L<number>:` format for line-specific feedback - PRs should reference issues: `Closes #42`, `Refs #17` (from commit skill) ## Starter Tasks for Sam 1. **Read the source-of-truth files** (5 files listed above) - understand what NOT to edit 2. **Install locally**: Run `install.sh --dry-run --all` to see what would be installed 3. **Practice compression**: Take any verbose .md file, run `/caveman:compress` pattern manually 4. **Write a commit**: Follow the `skills/caveman-commit/SKILL.md` rules exactly 5. **Review code**: Practice one-line reviews using `L<num>: <issue>. <fix>.` format ## External URLs (for reference) **Source**: `install.sh` - Main repo: `https://github.com/JuliusBrussee/caveman` - Install script: `https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh` - Init tool: `https://raw.githubusercontent.com/JuliusBrussee/caveman/main/tools/caveman-init.js` ## Critical Rules for Sam 1. **Never edit generated files** - only edit the 5 source-of-truth files 2. **No AI attribution in commits** - "Generated with Claude Code" forbidden 3. **Auto-clarity override** - drop caveman for security/onboarding contexts 4. **Idempotent by design** - `caveman-init.js` safe to re-run (checks `SENTINEL`) 5. **Token budget**: 200,000 tokens available for context

Local fixture keeps the demo deterministic when sponsor APIs or WiFi are unavailable.