/build-dashclaw

name: build-dashclaw
description: Contribute to the DashClaw codebase — architecture, scaffolding, tests, CI
license: MIT
metadata:
  author: ucsandman
  version: "1.0.0"
  category: development

Build DashClaw

Guide for contributing to the DashClaw codebase. Covers architecture, adding new capabilities, testing, and CI.

Architecture Overview

DashClaw is organized into 3 tiers:

Tier 1: Core Runtime (`app/api/`)

7 mandatory endpoints that define DashClaw's governance category:

| Route | Method | Purpose | |-------|--------|---------| | `/api/guard` | POST | Policy evaluation — "can I do this?" | | `/api/actions` | POST, PATCH, GET | Action lifecycle recording | | `/api/approvals` | POST | Human approval decisions | | `/api/assumptions` | POST, GET | Reasoning integrity tracking | | `/api/signals` | GET | Real-time anomaly detection | | `/api/policies` | GET, POST | Guard policy management | | `/api/health` | GET | System readiness |

**The 7-route boundary is CI-enforced.** Adding a new core route requires justification.

Tier 2: Extensions (`app/(extensions)/`)

Modular operational intelligence:

• Compliance, Drift, Evaluations, Scoring, Prompts, Webhooks, Learning

Tier 3: Archived (`app/api/_archive/`)

Legacy features from the "Agent Platform" era. Physically isolated.

Tech Stack

| Layer | Technology | |-------|------------| | Runtime | Node.js 20+ | | Framework | Next.js 16 (App Router) | | Database | Postgres (Neon recommended) | | ORM | Drizzle ORM | | Auth | NextAuth.js v4 | | UI | React 18, Tailwind CSS 3 | | Testing | Vitest + jsdom | | Package Manager | npm |

Key Conventions

TEXT Primary Keys

All IDs are TEXT with crypto-random prefixed values:

import { randomBytes } from 'crypto';
const id = `act_${randomBytes(16).toString('hex')}`;

ID prefixes: `ar_` (actions), `oc_live_`/`oc_test_` (API keys), `sp_` (scoring profiles), `pt_` (prompt templates), etc.

Repository Pattern

**No direct SQL in route handlers.** All data access goes through repository modules:

app/lib/repositories/*.repository.js

Route handlers import from repositories, never inline SQL.

Auth Chain

Request → Strip client org headers → Rate limit → Route matching
  → Public routes: pass through
  → Protected routes: x-api-key (fast path: timing-safe compare)
    → Inject org context from resolved key

12-Step Scaffold for New Capabilities

When adding a new feature to DashClaw:

1. **Migration** — Add table with TEXT PKs and crypto-random IDs 2. **Repository** — Create `app/lib/repositories/<name>.repository.js` (all SQL here) 3. **Lib module** — Create `app/lib/<name>.js` (business logic) 4. **Route handler** — Create `app/api/<name>/route.js` (imports from repository) 5. **Demo fixtures** — Add fixture data if the feature needs demo mode support 6. **Demo middleware** — Wire fixtures into demo mode if needed 7. **Node SDK method** — Add to `sdk/dashclaw.js` (camelCase) 8. **Python SDK method** — Add to `sdk-python/dashclaw/client.py` (snake_case) 9. **Docs page** — Create dashboard page or update existing docs 10. **Node README** — Add method to SDK README 11. **Python README** — Add method to Python SDK README 12. **Parity matrix** — Update `docs/sdk-parity.md` with new method counts

Legacy SDK Promotion

The v1 SDK has 187 methods across 31 categories. When promoting to v2:

**High priority (core governance):**

• `registerOpenLoop()` + `resolveOpenLoop()` — Decision integrity
• `events()` — Real-time SSE events
• `heartbeat()` + `startHeartbeat()` — Agent telemetry

**Medium priority (analytics):**

• `getRecommendations()` + `recommendAction()` — Adaptive learning
• `getLearningVelocity()` + `getLearningCurves()` — Learning analytics
• `getSignals()` — Decision integrity signals

See `knowledge/legacy-sdk-reference.md` for the full inventory with all method signatures.

Testing

# Run all tests (watch mode)
npm run test

# Run tests once (CI mode)
npm run test -- --run

# Run specific test file
npx vitest run app/lib/__tests__/guard.test.js

Tests live alongside their modules or in `__tests__/` directories.

CI Checks

Three mandatory CI checks:

# 1. Governance boundary — enforces 7-route API limit
npm run governance:boundary:check

# 2. OpenAPI contract — detects API drift
npm run openapi:check

# 3. Tests
npm run test -- --run

All three must pass before merge.

Key Files for Contributors

| File | What to Read | |------|-------------| | `PROJECT_DETAILS.md` | Canonical system map (source of truth) | | `CLAUDE.md` | Contributing conventions | | `app/lib/guard.js` | Risk scoring engine | | `app/lib/signals.js` | Anomaly detection logic | | `sdk/dashclaw.js` | V2 SDK implementation | | `sdk/legacy/dashclaw-v1.js` | V1 SDK (187 methods) | | `schema/schema.js` | Database schema (Drizzle) | | `middleware.js` | Auth chain | | `docs/sdk-parity.md` | SDK method parity matrix |

Contributing Workflow

1. Read `PROJECT_DETAILS.md` and `CLAUDE.md` 2. Understand the 3-tier boundary (core vs extension vs archived) 3. Follow the 12-step scaffold if adding a new capability 4. Match existing patterns (repository pattern, TEXT PKs, etc.) 5. Run all three CI checks locally before committing 6. Keep SDK parity: if you add a Node method, add the Python equivalent