@boshu2/vibe-check 2.2.1 → 2.3.0

package/.agents/plans/2025-12-28-ai-safety-integration-plan.md

@@ -0,0 +1,326 @@
+---
+date: 2025-12-28
+type: Plan
+topic: "AI Safety Detection Module for vibe-check"
+research: ".agents/research/2025-12-28-ai-platform-security-integration.md"
+tags: [plan, ai-safety, llm-validation, security, vibe-check]
+status: READY_FOR_APPROVAL
+---
+
+# Plan: AI Safety Detection Module
+
+**Created:** 2025-12-28
+**Research:** `.agents/research/2025-12-28-ai-platform-security-integration.md`
+**Vibe Level:** L3 (Multiple files, following existing patterns)
+
+---
+
+## Overview
+
+Add a new `src/ai-safety/` module to vibe-check that detects LLM-specific antipatterns in commit history: **secret leakage**, **scope violations**, **contract drift**, and **token spirals**. This extends the existing inner-loop failure detection with patterns ported from ai-platform's production security stack.
+
+---
+
+## Approach
+
+Port security validation patterns from `ai-platform/tests/agents/test_agent_security.py` and adapt them for git-based analysis. Follow the existing `src/inner-loop/` module structure exactly.
+
+**Why this approach:**
+1. **Proven patterns:** ai-platform patterns are battle-tested for classified environments
+2. **Non-breaking:** Extends existing architecture without replacing anything
+3. **Familiar structure:** Same module organization as inner-loop
+4. **Zero new dependencies:** Pure TypeScript, uses existing git analysis
+
+---
+
+## Features
+
+### Feature 1: AI Safety Types and Orchestrator
+
+**Priority:** P0 (Foundation - must come first)
+**Type:** feature
+**Depends On:** None
+
+**Acceptance Criteria:**
+- [ ] `src/ai-safety/types.ts` defines all interfaces
+- [ ] `src/ai-safety/index.ts` exports orchestrator function
+- [ ] `AISafetyAnalysis` interface matches inner-loop pattern
+- [ ] Config supports enable/disable per detector
+- [ ] Compiles without errors
+
+**Files Affected:**
+- `src/ai-safety/types.ts` - New file: Type definitions
+- `src/ai-safety/index.ts` - New file: Orchestrator + exports
+
+**Test Strategy:** `npm run build` passes, types are importable
+
+---
+
+### Feature 2: Secret Leakage Detector
+
+**Priority:** P1 (Highest value, immediate utility)
+**Type:** feature
+**Depends On:** Feature 1
+
+**Acceptance Criteria:**
+- [ ] Detects OpenAI keys (`sk-[a-zA-Z0-9]{48}`)
+- [ ] Detects GitHub PATs (`ghp_[a-zA-Z0-9]{36}`)
+- [ ] Detects GitLab PATs (`glpat-[a-zA-Z0-9]{20}`)
+- [ ] Detects AWS keys (`AKIA[0-9A-Z]{16}`)
+- [ ] Detects Slack tokens (`xox[baprs]-*`)
+- [ ] Detects generic patterns (password=, secret=)
+- [ ] Reports file, line context, and pattern matched
+- [ ] Critical severity by default
+
+**Files Affected:**
+- `src/ai-safety/secret-leakage.ts` - New file: Secret detection logic
+- `src/ai-safety/index.ts` - Wire into orchestrator
+
+**Test Strategy:**
+1. Create test with fake secrets in commit diffs
+2. Verify detection of each pattern
+3. Verify no false positives on similar-looking strings
+
+---
+
+### Feature 3: Scope Violation Detector
+
+**Priority:** P2 (High value, needs config)
+**Type:** feature
+**Depends On:** Feature 1
+
+**Acceptance Criteria:**
+- [ ] Detects commits touching files outside declared scope
+- [ ] Scope defined via config file (`.vibe-check/scope.yaml`) or CLI
+- [ ] Supports glob patterns for scope definition
+- [ ] Reports which files violated scope
+- [ ] Warning severity by default
+
+**Files Affected:**
+- `src/ai-safety/scope-violation.ts` - New file: Scope check logic
+- `src/ai-safety/index.ts` - Wire into orchestrator
+- `src/types.ts` - Add AISafetyConfig to main types
+
+**Test Strategy:**
+1. Define scope as `src/feature/**`
+2. Create commit touching `src/other/file.ts`
+3. Verify scope violation detected
+
+---
+
+### Feature 4: Contract Drift Detector
+
+**Priority:** P2 (Medium value, pattern analysis)
+**Type:** feature
+**Depends On:** Feature 1
+
+**Acceptance Criteria:**
+- [ ] Tracks commit message format compliance over time
+- [ ] Detects degradation from conventional commits format
+- [ ] Tracks entropy (message quality declining)
+- [ ] Reports drift percentage and trend direction
+- [ ] Warning severity when >30% drift from baseline
+
+**Files Affected:**
+- `src/ai-safety/contract-drift.ts` - New file: Format drift logic
+- `src/ai-safety/index.ts` - Wire into orchestrator
+
+**Test Strategy:**
+1. Provide commits with good format then degrading format
+2. Verify drift percentage calculated
+3. Verify warning triggered at threshold
+
+---
+
+### Feature 5: Token Spiral Estimator
+
+**Priority:** P3 (Lower value, estimation-based)
+**Type:** feature
+**Depends On:** Feature 1
+
+**Acceptance Criteria:**
+- [ ] Estimates token usage from commit size
+- [ ] Uses heuristic: ~4 chars per token
+- [ ] Tracks cumulative session tokens
+- [ ] Detects explosion patterns (>2x baseline)
+- [ ] Info severity (advisory, not critical)
+
+**Files Affected:**
+- `src/ai-safety/token-spiral.ts` - New file: Token estimation logic
+- `src/ai-safety/index.ts` - Wire into orchestrator
+
+**Test Strategy:**
+1. Provide small commits then huge commit
+2. Verify explosion detected
+3. Verify reasonable token estimates
+
+---
+
+### Feature 6: Integration with Session End
+
+**Priority:** P1 (Makes feature visible to users)
+**Type:** feature
+**Depends On:** Features 1-2 (minimum)
+
+**Acceptance Criteria:**
+- [ ] `session end` JSON output includes `ai_safety` section
+- [ ] Terminal output shows AI safety warnings
+- [ ] Critical findings show in red
+- [ ] Recommendations generated for each finding
+
+**Files Affected:**
+- `src/commands/session.ts` - Add AI safety analysis call
+- `src/output/terminal.ts` - Format AI safety for terminal
+- `src/output/json.ts` - Format AI safety for JSON
+
+**Test Strategy:** `vibe-check session end --format json` includes ai_safety section
+
+---
+
+### Feature 7: Integration with Watch Command
+
+**Priority:** P2 (Real-time value)
+**Type:** feature
+**Depends On:** Feature 2 (secret detection)
+
+**Acceptance Criteria:**
+- [ ] Watch mode alerts on secret detection immediately
+- [ ] Uses red/bold for critical findings
+- [ ] Shows file and pattern matched
+- [ ] Rate-limited (don't spam alerts)
+
+**Files Affected:**
+- `src/commands/watch.ts` - Add secret detection to watch loop
+
+**Test Strategy:** Run watch, commit file with fake secret, see immediate alert
+
+---
+
+### Feature 8: Tests and Documentation
+
+**Priority:** P2 (Quality assurance)
+**Type:** task
+**Depends On:** Features 1-5
+
+**Acceptance Criteria:**
+- [ ] Unit tests for each detector
+- [ ] Integration test for orchestrator
+- [ ] CLAUDE.md updated with ai-safety commands
+- [ ] README.md mentions AI safety features
+
+**Files Affected:**
+- `tests/ai-safety.test.ts` - New file: Test suite
+- `CLAUDE.md` - Update documentation
+- `README.md` - Feature description
+
+**Test Strategy:** `npm test` passes with >80% coverage on new module
+
+---
+
+## Implementation Order
+
+| Step | Feature | Depends On | Validation |
+|------|---------|------------|------------|
+| 1 | Types and Orchestrator | - | `npm run build` passes |
+| 2 | Secret Leakage | Step 1 | Test with fake secrets |
+| 3 | Session Integration | Steps 1-2 | `session end` shows findings |
+| 4 | Scope Violation | Step 1 | Test with scope config |
+| 5 | Contract Drift | Step 1 | Test with degrading commits |
+| 6 | Token Spiral | Step 1 | Test with varying sizes |
+| 7 | Watch Integration | Step 2 | Real-time alert test |
+| 8 | Tests & Docs | Steps 1-6 | `npm test` passes |
+
+---
+
+## Beads Issues to Create
+
+After approval, these issues will be created:
+
+| ID | Title | Type | Priority | Depends On |
+|----|-------|------|----------|------------|
+| TBD | Epic: AI Safety Detection Module | epic | P1 | - |
+| TBD | AI Safety types and orchestrator | feature | P0 | Epic |
+| TBD | Secret leakage detector | feature | P1 | Types |
+| TBD | Session end AI safety integration | feature | P1 | Secret detector |
+| TBD | Scope violation detector | feature | P2 | Types |
+| TBD | Contract drift detector | feature | P2 | Types |
+| TBD | Token spiral estimator | feature | P3 | Types |
+| TBD | Watch command AI safety integration | feature | P2 | Secret detector |
+| TBD | Tests and documentation | task | P2 | All features |
+
+---
+
+## File Structure After Implementation
+
+```
+src/ai-safety/
+├── index.ts              # Orchestrator: analyzeAISafety()
+├── types.ts              # Interfaces: AISafetyAnalysis, configs
+├── secret-leakage.ts     # Regex-based secret detection
+├── scope-violation.ts    # Glob-based scope checking
+├── contract-drift.ts     # Commit format degradation
+└── token-spiral.ts       # Token usage estimation
+
+tests/ai-safety.test.ts   # Full test suite
+```
+
+---
+
+## Key Interfaces (Preview)
+
+```typescript
+// src/ai-safety/types.ts
+export interface AISafetyAnalysis {
+  secretLeakage: SecretLeakageResult;
+  scopeViolations: ScopeViolationResult;
+  contractDrift: ContractDriftResult;
+  tokenSpiral: TokenSpiralResult;
+  summary: {
+    totalIssues: number;
+    criticalIssues: number;
+    warningIssues: number;
+    overallHealth: 'healthy' | 'warning' | 'critical';
+  };
+  recommendations: string[];
+}
+
+export interface SecretLeakageResult {
+  detected: boolean;
+  findings: SecretFinding[];
+  message: string;
+}
+
+export interface SecretFinding {
+  commitHash: string;
+  file: string;
+  pattern: string;
+  lineContext: string;
+  severity: 'critical' | 'warning';
+}
+```
+
+---
+
+## Rollback Procedure
+
+If something goes wrong:
+
+1. **Module not loading:** Revert `src/ai-safety/` directory
+2. **Session command broken:** Revert `src/commands/session.ts` changes
+3. **Watch command broken:** Revert `src/commands/watch.ts` changes
+4. **Build fails:** Check `src/ai-safety/index.ts` exports
+
+All changes are additive - existing functionality is not modified, only extended.
+
+---
+
+## Next Steps
+
+1. **Review and approve this plan**
+2. **Create beads issues** (commands below)
+3. **`bd ready`** to see unblocked issues
+4. **`/implement`** to execute first issue
+
+---
+
+**Output:** .agents/plans/2025-12-28-ai-safety-integration-plan.md

package/.agents/research/2025-12-28-ai-platform-security-integration.md

@@ -0,0 +1,295 @@
+---
+date: 2025-12-28
+type: Research
+topic: "Integrating ai-platform security and LLM validation into vibe-check"
+tags: [research, security, llm-validation, integration, ai-platform, vibe-check]
+status: COMPLETE
+---
+
+# Research: Integrating AI-Platform Security & LLM Validation into Vibe-Check
+
+**Created:** 2025-12-28
+**Goal:** Understand how to integrate the security and LLM validation components from ai-platform into vibe-check for detecting AI agent misbehavior patterns.
+
+---
+
+## Executive Summary
+
+The **ai-platform** repository (`/Users/fullerbt/workspaces/work/ai-platform`) contains a comprehensive security and LLM validation stack built for production use in classified environments. Key components include: **RBAC access control**, **audit logging** (SIEM-ready), **agent execution tracking** (Prometheus metrics), **rate limiting with token budgets**, and **contract-driven agent testing**.
+
+**Recommendation:** Integrate these concepts into vibe-check as a new `ai-safety/` or `agent-validation/` module, extending the existing inner-loop failure pattern detection to include LLM-specific antipatterns like **prompt injection attempts**, **hallucination markers**, **scope violations**, and **contract drift**.
+
+---
+
+## Current State
+
+### What Exists in ai-platform
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| **Access Control** | `services/gateway/access_control.py` | RBAC for agents/tools via OIDC groups |
+| **Audit Logging** | `services/gateway/audit.py` | JSON request/response logging for SIEM |
+| **Agent Audit** | `services/gateway/agent_audit.py` | Agent execution tracking + Prometheus metrics |
+| **Rate Limiting** | `services/gateway/rate_limit.py` | Per-user rate limits + token budgets |
+| **Config Validator** | `services/etl/app/config_validator.py` | Startup config health checks |
+| **Security Tests** | `tests/agents/test_agent_security.py` | Boundary violation detection |
+| **Contract Tests** | `tests/agents/test_agent_contract_validation.py` | Output contract compliance |
+| **Platform Validator** | `services/etl/scripts/validate-platform.py` | End-to-end LLM platform checks |
+
+### Key Patterns Worth Porting to vibe-check
+
+1. **Agent Scope Boundary Detection** (`test_agent_security.py`)
+   - Detects when agents attempt actions outside their declared scope
+   - Pattern: Check if commit changes files/APIs not in the agent's domain
+
+2. **Hallucination Markers** (`test_agent_security.py:50-70`)
+   - Detects file path hallucination (made-up paths)
+   - Pattern: Commits referencing non-existent files or phantom dependencies
+
+3. **Secret Leakage Detection** (`test_agent_security.py:120-150`)
+   - Regex patterns for API keys, tokens, credentials
+   - Pattern: Commits accidentally exposing secrets
+
+4. **Contract Drift Detection** (`test_agent_contract_validation.py`)
+   - Validates agent responses match expected structure
+   - Pattern: Detect when AI outputs stop conforming to expected formats
+
+5. **Token Budget Tracking** (`rate_limit.py`)
+   - Tracks token consumption per user/session
+   - Pattern: Detect runaway token usage (context explosion)
+
+### Key Files
+
+| File | Purpose | Relevance to vibe-check |
+|------|---------|-------------------------|
+| `services/gateway/access_control.py` | RBAC via OIDC groups | Could map to commit author scope detection |
+| `services/gateway/audit.py` | JSON audit logging | Structure for storing AI interaction events |
+| `services/gateway/agent_audit.py` | Prometheus metrics + Langfuse traces | Pattern for tracking AI agent behavior over time |
+| `tests/agents/test_agent_security.py` | Security test patterns | Regex patterns and violation detection logic |
+| `services/gateway/rate_limit.py` | Token budget tracking | Pattern for detecting context window abuse |
+
+### Existing Patterns in vibe-check
+
+vibe-check already has:
+- **Inner-loop failure detection** (`src/inner-loop/`) with 4 detectors
+- **Spiral detection** with pattern regexes in `watch.ts`
+- **Session tracking** with baseline comparison
+- **NDJSON storage** for historical pattern analysis
+- **Prometheus-like metrics** (not exposed, but structured similarly)
+
+---
+
+## Findings
+
+### Finding 1: Security Validation Patterns Are Git-Analyzable
+
+**Evidence:** The ai-platform security tests detect violations by analyzing:
+- Commit messages for intent signals
+- File changes for scope violations
+- Code content for secret patterns
+
+**Implication:** These patterns can be adapted for vibe-check's commit-based analysis:
+```
+ai-platform pattern → vibe-check integration
+-------------------------------------------
+Scope violation test → Detect commits touching files outside declared domain
+Secret leakage test → Detect commits adding API keys/tokens
+Hallucination test → Detect commits referencing non-existent paths
+Contract drift test → Detect commits breaking expected output formats
+```
+
+### Finding 2: Agent Audit Structure Is Session-Compatible
+
+**Evidence:** `agent_audit.py` tracks events in a structure similar to vibe-check sessions:
+```python
+audit_record = {
+    "correlation_id": str,       # → session_id
+    "agent_name": str,           # → (new field)
+    "user_identity": str,        # → (already tracked)
+    "tokens_used": {             # → (new metric)
+        "input": int,
+        "output": int,
+        "total": int
+    },
+    "tool_invocations": [...],   # → (map to commit file changes)
+    "duration_ms": int           # → (session duration)
+}
+```
+
+**Implication:** Can extend `active-session.json` with agent/LLM metadata.
+
+### Finding 3: Rate Limiting = Token Spiral Detection
+
+**Evidence:** `rate_limit.py` implements token budget tracking:
+```python
+@dataclass
+class UserRateLimit:
+    max_tokens_per_minute: int = 100_000
+    max_tokens_per_hour: int = 1_000_000
+    max_tokens_per_day: int = 10_000_000
+```
+
+**Implication:** vibe-check could detect "token spirals" - sessions where token consumption explodes, indicating:
+- Context window abuse
+- Prompt stuffing
+- Repeated failed attempts (AI trying same thing repeatedly)
+
+### Finding 4: Secret Detection Regex Is Ready to Use
+
+**Evidence:** `test_agent_security.py:120-150`:
+```python
+SECRET_PATTERNS = [
+    r'sk-[a-zA-Z0-9]{48}',           # OpenAI
+    r'ghp_[a-zA-Z0-9]{36}',          # GitHub PAT
+    r'glpat-[a-zA-Z0-9]{20}',        # GitLab PAT
+    r'AKIA[0-9A-Z]{16}',             # AWS Access Key
+    r'xox[baprs]-[a-zA-Z0-9-]+',     # Slack tokens
+]
+```
+
+**Implication:** Can add a `secret-leakage.ts` detector to inner-loop.
+
+### Finding 5: Contract Validation Is Output-Pattern Detection
+
+**Evidence:** `test_agent_contract_validation.py` validates agent outputs against YAML-defined contracts:
+```yaml
+agents:
+  - name: code-review
+    output_contract:
+      required_sections: ["summary", "issues", "suggestions"]
+      max_length: 5000
+```
+
+**Implication:** vibe-check could detect "contract drift" - when AI commits start deviating from expected patterns:
+- Commit messages becoming less structured
+- PR descriptions missing required sections
+- Code comments becoming vague or absent
+
+---
+
+## Constraints
+
+| Constraint | Impact | Mitigation |
+|------------|--------|------------|
+| ai-platform is Python, vibe-check is TypeScript | Can't share code directly | Port patterns/logic, not code |
+| ai-platform runs in Kubernetes, vibe-check is CLI | Different runtime context | Adapt to git-based detection |
+| ai-platform has Prometheus/Langfuse dependencies | Heavy deps for CLI tool | Use file-based storage, optionally export |
+| Token tracking requires LLM API integration | vibe-check only sees git | Estimate tokens from commit size/complexity |
+
+---
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Over-engineering simple CLI tool | Medium | High | Start with 2-3 highest-value patterns |
+| False positives on secret detection | Medium | Medium | Require confidence threshold, allow suppression |
+| Token estimation inaccuracy | High | Low | Use as relative signal, not absolute |
+| Breaking existing inner-loop interface | Low | High | Extend, don't replace |
+
+---
+
+## Recommendation
+
+**Approach:** Add a new `src/ai-safety/` module to vibe-check with 4 new detectors:
+
+### Phase 1: High-Value Ports (Recommended First)
+
+1. **Secret Leakage Detector** (`src/ai-safety/secret-leakage.ts`)
+   - Port regex patterns from `test_agent_security.py`
+   - Scan commit diffs for exposed secrets
+   - Integrate into `session end` output
+
+2. **Scope Violation Detector** (`src/ai-safety/scope-violation.ts`)
+   - Detect commits touching files outside declared domain
+   - Requires domain configuration (similar to access_control.py mappings)
+   - Warning when agent strays from its lane
+
+### Phase 2: Medium-Value Ports
+
+3. **Contract Drift Detector** (`src/ai-safety/contract-drift.ts`)
+   - Detect when commit message patterns degrade
+   - Track deviation from conventional commit format
+   - Alert when AI stops following established patterns
+
+4. **Token Spiral Estimator** (`src/ai-safety/token-spiral.ts`)
+   - Estimate token usage from commit size/complexity
+   - Detect sessions with exploding context
+   - Use as relative metric (not absolute)
+
+### Integration Points
+
+```typescript
+// src/ai-safety/index.ts
+export interface AISafetyAnalysis {
+  secretsDetected: SecretLeakageResult;
+  scopeViolations: ScopeViolationResult;
+  contractDrift: ContractDriftResult;
+  tokenSpiral: TokenSpiralResult;
+  summary: {
+    totalIssues: number;
+    criticalIssues: number;
+    warningIssues: number;
+    overallHealth: 'healthy' | 'warning' | 'critical';
+  };
+  recommendations: string[];
+}
+
+export function analyzeAISafety(
+  commits: Commit[],
+  filesPerCommit: Map<string, string[]>,
+  config?: AISafetyConfig
+): AISafetyAnalysis;
+```
+
+**Integration into existing commands:**
+- `session end` → Add `ai_safety` section to JSON output
+- `watch` → Add real-time alerts for secret detection
+- `insights` → Add AI safety pattern history
+
+### Why This Approach
+
+1. **Non-breaking:** Extends existing architecture, doesn't replace
+2. **High-value first:** Secret leakage is immediately useful
+3. **Familiar patterns:** Same structure as existing inner-loop detectors
+4. **Low deps:** No new dependencies required (pure TypeScript)
+5. **Git-native:** Works with existing commit-based analysis
+
+---
+
+## Alternatives Considered
+
+1. **Import ai-platform as dependency** - Rejected: Different language, heavy deps
+2. **Create shared npm/pip packages** - Rejected: Over-engineering for 4 patterns
+3. **Keep validation in ai-platform only** - Rejected: vibe-check users need these patterns
+4. **Port entire audit system** - Rejected: Too complex, different runtime
+
+---
+
+## Next Steps
+
+1. Run `/plan` to create implementation plan from this research
+2. Plan will create beads issues for each detector
+3. Implement in priority order: secrets → scope → contract → token
+
+---
+
+## Appendix: Key Source File References
+
+### ai-platform Security Components
+- `/Users/fullerbt/workspaces/work/ai-platform/services/gateway/access_control.py` - RBAC implementation
+- `/Users/fullerbt/workspaces/work/ai-platform/services/gateway/audit.py` - Audit logging
+- `/Users/fullerbt/workspaces/work/ai-platform/services/gateway/agent_audit.py` - Agent execution tracking
+- `/Users/fullerbt/workspaces/work/ai-platform/services/gateway/rate_limit.py` - Rate limiting
+- `/Users/fullerbt/workspaces/work/ai-platform/tests/agents/test_agent_security.py` - Security tests
+- `/Users/fullerbt/workspaces/work/ai-platform/tests/agents/test_agent_contract_validation.py` - Contract tests
+
+### vibe-check Integration Points
+- `/Users/fullerbt/workspaces/personal/vibe-check/src/inner-loop/index.ts` - Existing detector orchestrator
+- `/Users/fullerbt/workspaces/personal/vibe-check/src/commands/session.ts` - Session end output
+- `/Users/fullerbt/workspaces/personal/vibe-check/src/commands/watch.ts` - Real-time monitoring
+- `/Users/fullerbt/workspaces/personal/vibe-check/src/types.ts` - Type definitions
+
+---
+
+**Output:** .agents/research/2025-12-28-ai-platform-security-integration.md

package/.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡