Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (67 loc) · 4.32 KB

CLAUDE.md

File metadata and controls

87 lines (67 loc) · 4.32 KB

Core Rules

  • Production-ready only; no temporary solutions. Blocked? Open a GitHub issue
  • Honor docs/ specifications; reconcile inconsistencies
  • Before destructive ops (rm, git reset), inspect repo state first
  • No process/status documents; only architecture docs
  • No estimates or project management info in technical docs
  • No placeholder implementations; avoid fallbacks unless truly required (fallbacks add redundancy and can hide issues)
  • NEVER create documentation unless explicitly requested, conflicts with existing docs, or absolutely critical

Pre-Implementation Checks

  • Search first: Before implementing any new code, search the repo by keywords to find related or similar code
  • Deduplicate: Reuse existing logic or refactor to remove duplication when possible
  • Evaluate open-source components before building from scratch
  • Check for deprecated/unused code
  • Assess refactoring needs and clean first if required
  • Implement incrementally (one logical section at a time)

Implementation Cycle (per section)

  1. Implement a feature section
  2. Write comprehensive tests for that section
  3. Run tests and verify all pass
  4. Fix any issues
  5. Commit code

Completion Notes

  • Before ending a task, summarize current implementation status, with focus on:
    • Any implemented functionality not wired into the execution path/integrations
    • Conflicts or overlaps with existing functionality
    • Testing status and whether coverage is sufficient
    • Need for refactors/adjustments
    • Potential better implementation approaches
    • A list of next steps

Planning & Discussion Rules

  • No documentation generation during planning
  • No extensive code examples (brief pseudocode only if needed)
  • Keep options concise; include pros/cons, recommendation, and next steps

Git Hooks & Restrictions

  • Files: no temp scripts, test data dirs, hardcoded secrets, LICENSE text in code
  • Docs: no status/progress/log docs, no PM terms (Author, Phase 1, Sprint, est.)
  • Commits: <emoji> <type>(<scope>): <subject> (<=100 chars, <=4 lines), no PM terms, no Co-Authored-By
  • When hooks fail: follow <system-reminder> and "-> Next:" guidance

Key Patterns

  • Error handling: Rust thiserror with typed error enums; use .context() for error chaining
  • Testing: #[cfg(test)] modules; E2E tests in web/e2e/ (Playwright)
  • Database: SQLite via rusqlite; migrations in migrations/ (Refinery, V0XX__name.sql naming)
  • Serialization: serde + schemars for JSON schema generation
  • Async: Tokio runtime; async-trait for trait async methods

Key Entry Paths

  • crates/oversight-server/ - Axum HTTP server, API routes, Scheduler, WorkerPool, embedded Worker
  • crates/oversight-worker/ - CLI agent Worker node: AcpClient, adapters (Claude/Codex/OpenClaw), WebSocket session, transport
  • crates/oversight-models/ - Data models (tasks, documents, workflows, agents, cycles, permissions)
  • crates/oversight-store/ - SQLite persistence layer (repo_*.rs pattern, including agent skills)
  • crates/oversight-agents/ - Agent composition, registry, catalog (AgentLocality), prompts
  • crates/oversight-tools/ - 40+ agent tools (document, task, workflow, git, shell)
  • web/ - React + TypeScript frontend (Vite, Tailwind CSS)
  • web/src/lib/api.ts - Frontend API client (type-safe REST endpoints)

Architecture Notes

  • Awaken framework: awaken 0.2.0 from crates.io (awaken-agent, awaken-contract, awaken-runtime, awaken-server, awaken-stores)
  • Server runs on port 7878 (configurable via OVERSIGHT_PORT)
  • API routes: /api (REST), /v1/ai-sdk (AI SDK v6), /v1/ag-ui (AG-UI), /v1/a2a (A2A)
  • Database: .oversight/oversight.db (configurable via OVERSIGHT_DATA_DIR)
  • Frontend build served from web/dist/ (configurable via OVERSIGHT_STATIC_DIR)
  • CLI agents (Claude Code, Codex, OpenClaw) communicate via unified ACP (Agent Client Protocol)
  • Worker mode: OVERSIGHT_WORKER_MODE=embedded (default, in-process) or remote (distributed WebSocket)
  • Agent locality: Local (in-process), Remote (A2A), Distributed (Scheduler → Worker)

Documentation Rules

  • Update docs for API/schema/env var/tech debt changes only
  • ADRs only when 2+ modules, new infra, or major architecture shift
  • Never create docs for routine impls, refactors, optimizations, or planning

Note: Git hooks (lefthook.yml) enforce all restrictions automatically.