# Build Dashclaw

> Contribute to the DashClaw codebase — architecture, scaffolding, tests, CI

- **Type:** Skill
- **Install:** `agentstack add skill-ucsandman-dashclaw-skills-build-dashclaw`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ucsandman](https://agentstack.voostack.com/s/ucsandman)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ucsandman](https://github.com/ucsandman)
- **Source:** https://github.com/ucsandman/dashclaw-skills/tree/main/skills/build-dashclaw

## Install

```sh
agentstack add skill-ucsandman-dashclaw-skills-build-dashclaw
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:
```javascript
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

```bash
# 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:

```bash
# 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](https://github.com/ucsandman)
- **Source:** [ucsandman/dashclaw-skills](https://github.com/ucsandman/dashclaw-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ucsandman-dashclaw-skills-build-dashclaw
- Seller: https://agentstack.voostack.com/s/ucsandman
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.