Skip to content

CLAUDE.md

Latest commit

 

History

History
270 lines (201 loc) · 8.03 KB

CLAUDE.md

File metadata and controls

270 lines (201 loc) · 8.03 KB

IMPORTANT: USE CAS FOR TASK AND MEMORY MANAGEMENT

DO NOT USE BUILT-IN TOOLS (TodoWrite, EnterPlanMode) FOR TASK TRACKING.

Use CAS MCP tools instead:

  • mcp__cas__task with action: create - Create tasks (NOT TodoWrite)
  • mcp__cas__task with action: start/close - Manage task status
  • mcp__cas__task with action: ready - See ready tasks
  • mcp__cas__memory with action: remember - Store memories and learnings
  • mcp__cas__search with action: search - Search all context

CAS provides persistent context across sessions. Built-in tools are ephemeral.

CAS - Coding Agent System

Unified context system for AI agents: persistent memory, tasks, rules, and skills across sessions.

Design Philosophy: CAS is built for AI agents as the primary users. Humans are observers who review agent activity, provide feedback, and guide direction - but the tools and workflows are optimized for agent consumption and production.

Use CAS for Task & Memory Management

Agents use CAS MCP tools instead of built-in TodoWrite:

mcp__cas__task action=create     - Create/track tasks
mcp__cas__task action=start      - Start working on a task (sets status to in_progress)
mcp__cas__task action=notes      - Add progress notes (progress, blocker, decision, discovery)
mcp__cas__task action=close      - Complete tasks
mcp__cas__memory action=remember - Store learnings and context
mcp__cas__search action=search   - Find relevant context (filter with doc_type: entry/task/rule/skill)

Human CLI:

cas init           # Initialize CAS in a project
cas serve          # Start MCP server
cas config list    # View configuration
cas doctor         # Run diagnostics
cas update         # Self-update

Project Structure

cas-cli/           # Rust CLI & MCP server (primary)
crates/            # Workspace crates (cas-core, cas-store, cas-search, etc.)

cas-cli Architecture

Directory Purpose
src/types/ Core data: Entry, Task, Rule, Skill
src/store/ Storage abstraction (SqliteStore primary)
src/search/ Full-text search (BM25 via Tantivy)
src/cli/ Command handlers
src/hooks/ Claude Code integration

Key Patterns

Store Trait (cas-cli/src/store/mod.rs): All storage ops go through trait abstractions. SqliteStore is primary.

Rule Auto-Promotion: Use mcp__cas__rule action=helpful id=<id> to promote Draft/Stale rules to Proven, auto-syncs to .claude/rules/.

MCP Server: cas serve exposes all functionality as MCP tools for Claude Code integration.

Skill Frontmatter Fields (Claude Code 2.1.3+)

CAS skills sync to .claude/skills/ as SKILL.md files with YAML frontmatter.

Note: In Claude Code 2.1.3, skills and commands were unified into a single system.

The following fields are supported:

Required Fields

Field Type Description
name string Skill name (prefixed with cas-)
description string 1-2 line description

Optional Fields

Field Type Description Example
user-invocable bool Hide from slash menu (model can still invoke) false
argument-hint string Hint shown when invoked (must be quoted) "[query]"
context string Execution context mode fork
agent string Specialized agent to use Explore, code-reviewer
allowed-tools list Restrict tools the skill can use - Read
- Grep
disable-model-invocation bool Block model from invoking (command-only) true
hooks object Skill-scoped hooks (Claude Code 2.1.0+) See below

Note: user-invocable: false only hides the skill from the user's slash menu. The model can still invoke the skill unless disable-model-invocation: true is also set.

Hooks Structure (Claude Code 2.1.0+)

hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: cas hook PreToolUse
          timeout: 3000
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: cas hook PostToolUse
          timeout: 3000
  Stop:
    - hooks:
        - type: command
          command: cas hook Stop

Example SKILL.md

---
name: cas-deep-search
description: Comprehensive codebase search using forked context
argument-hint: "[query]"
context: fork
agent: Explore
allowed-tools:
  - Read
  - Grep
  - Glob
---

# Deep Search

Instructions for the skill...

Creating Skills

Via MCP (for agents):

mcp__cas__skill action=create name="My Skill" invokable=true argument_hint="[args]"

Via CLI (for humans):

cas skill create "My Skill" --invokable --argument-hint "[args]"

Skills are automatically synced to .claude/skills/ when enabled.

Hook Configuration (Claude Code 2.1.0+)

once: true Support

Claude Code 2.1.0 adds once: true for hooks that should only execute once per session (even on resume). CAS hooks intentionally do NOT use this because:

  • SessionStart: Should inject context on every start/resume
  • PostToolUse/Stop: Should run on every matching event

To add once: true to a specific hook, manually edit .claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "cas hook SessionStart",
        "timeout": 5000,
        "once": true
      }]
    }]
  }
}

Bash Wildcard Permissions

Claude Code 2.1.0 supports wildcard patterns for Bash permissions. Add to .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(cas :*)",
      "Bash(cas task:*)",
      "Bash(cas search:*)"
    ]
  }
}

Patterns:

  • Bash(cas :*) - Allow all CAS commands
  • Bash(cas task:*) - Allow task operations only
  • Bash(:* --help) - Allow help for any command

Code Search with ast-grep

Use ast-grep for syntax-aware structural matching instead of text-only tools like rg or grep. This is especially useful for finding code patterns, refactoring, and understanding structure.

# Rust: Find all function definitions
ast-grep --lang rust -p 'fn $NAME($$$) { $$$ }'

# Rust: Find impl blocks for a trait
ast-grep --lang rust -p 'impl $TRAIT for $TYPE { $$$ }'

# Rust: Find unwrap() calls (potential error handling issues)
ast-grep --lang rust -p '$EXPR.unwrap()'

# Elixir: Find function definitions
ast-grep --lang elixir -p 'def $NAME($$$) do $$$ end'

# Elixir: Find pipe chains
ast-grep --lang elixir -p '$EXPR |> $FUNC($$$)'

# TypeScript: Find React component definitions
ast-grep --lang typescript -p 'function $NAME($$$): JSX.Element { $$$ }'

# TypeScript: Find useState hooks
ast-grep --lang typescript -p 'const [$STATE, $SETTER] = useState($$$)'

Only fall back to rg or grep for plain-text searches (comments, strings, config files) or when explicitly requested.

Build & Test

# cas-cli (Rust)
cd cas-cli && cargo build --release
cargo test

Adding Features

New CLI command: Add to cas-cli/src/cli/mod.rs Commands enum, create handler file, add integration test in tests/cli_test.rs.

New MCP tool: Add handler in cas-cli/src/mcp/, register in tool list.

Schema Migrations

CAS uses a versioned migration system for database schema changes. See cas-cli/docs/MIGRATIONS.md for full documentation.

Quick Reference

Adding a new column:

  1. Add column to base schema in src/store/sqlite.rs or src/store/skill_store.rs
  2. Add migration in src/migration/migrations.rs with detection query
  3. Run cargo test migration

Migration ID ranges:

Subsystem Range Tables
Entries 1-50 entries, sessions
Rules 51-70 rules
Skills 71-90 skills
Agents 91-110 agents, task_leases

Human CLI commands:

cas update --check        # Check for pending migrations
cas update --dry-run      # Preview migrations
cas update --schema-only  # Apply migrations
cas doctor                # Shows schema version