Build Dashclaw

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/.repository.js (all SQL here)
3. Lib module — Create app/lib/.js (business logic)
4. Route handler — Create app/api//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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ucsandman
• Source: ucsandman/dashclaw-skills
• License: MIT

Install and usage instructions live in the source repository linked above.