Agent-Cal Development Guide

This skill provides comprehensive guidance for working with Agent-Cal, an open-source scheduling infrastructure for AI agents. The project is a Turborepo monorepo with PNPM workspaces, featuring a Next.js frontend, Hono.js API backend, and shared packages.

Architecture Overview

Agent-Cal is structured as a monorepo with the following key components:

`apps/web/` - Next.js 15 frontend with React 19

`apps/api/` - Hono.js API server with OpenAPI documentation

`packages/` - Shared workspace packages (db, auth, ui, api-client, env-config, eslint-config, typescript-config)

**Technology Stack:**

Frontend: Next.js 15, React 19, TanStack Query, shadcn/ui, Tailwind CSS

Backend: Hono.js with Zod OpenAPI, Pino logging

Database: PostgreSQL with Drizzle ORM

Authentication: Better Auth

Build System: Turborepo with PNPM workspaces

Issue Tracking with bd (beads)

**CRITICAL:** This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

When to Use bd

**✅ Always Use bd For:**

1. Multi-session work that won't complete in one conversation

2. Complex features requiring epic → subtasks with dependencies

3. Discovered work (bugs/tasks you can't fix immediately)

4. Planning phase (structure design docs as bd issues)

5. Follow-up work needing future attention

**🚫 Don't Use bd For:**

Simple one-off fixes completed in current session

Answering questions or explaining code

Quick refactors with no follow-up

Trivial changes (typos, formatting, simple bugs)

bd Workflow for AI Agents

1. **Check for existing work at session start:**

```bash

bd ready --json # Show unblocked issues

bd list --json # See all open issues

```

2. **Create new issues:**

```bash

bd create "Issue title" -t bug|feature|task|epic|chore -p 0-4 --json

bd create "Subtask" --parent <epic-id> --json # Hierarchical subtask

bd create "Found bug" -p 1 --deps discovered-from:<parent-id> --json

```

3. **Claim and work on tasks:**

```bash

bd update bd-42 --status in_progress --json

bd update bd-42 --priority 1 --json

```

4. **Complete work:**

```bash

bd close bd-42 --reason "Completed" --json

```

Writing Self-Contained Issues

Issues must be fully self-contained and readable without external context. Include:

**Summary:** What and why (1-2 sentences)

**Files to modify:** Exact paths with line numbers if relevant

**Implementation steps:** Numbered, specific actions

**Example:** Show before → after transformation

**Dependencies:** Reference other issues if applicable

**Good Example:**

```

Add timeout parameter to fetchUser() in src/api/users.ts

1. Add optional timeout param (default 5000ms)

2. Pass to underlying fetch() call

3. Update tests in src/api/users.test.ts

Example: fetchUser(id) → fetchUser(id, { timeout: 3000 })

Depends on: bd-abc123 (fetch wrapper refactor)

```

Dependencies: Think "Needs", Not "Before"

`bd dep add X Y` means "X needs Y" (Y blocks X)

**TRAP:** Temporal words invert thinking!

```

WRONG: "Phase 1 before Phase 2" → bd dep add phase1 phase2

RIGHT: "Phase 2 needs Phase 1" → bd dep add phase2 phase1

```

Verify with `bd blocked` to see tasks blocked by prerequisites.

Issue Types & Priorities

**Types:**

`bug` - Something broken

`feature` - New functionality

`task` - Work item (tests, docs, refactoring)

`epic` - Large feature with subtasks

`chore` - Maintenance (dependencies, tooling)

**Priorities:**

`0` - Critical (security, data loss, broken builds)

`1` - High (major features, important bugs)

`2` - Medium (default, nice-to-have)

`3` - Low (polish, optimization)

`4` - Backlog (future ideas)

Common Development Commands

Development

```bash

pnpm dev # Start all apps

pnpm dev:web # Frontend only

pnpm dev:api # API only

pnpm dev:docs # Documentation (Mintlify on port 5000)

```

Building & Testing

```bash

pnpm build # Build all packages

pnpm lint # Lint all packages

pnpm --filter @workspace/web typecheck

pnpm --filter @workspace/api test

```

Database Operations

```bash

pnpm db:studio # Open Drizzle Studio

pnpm db:generate # Generate migrations

pnpm db:push # Push schema changes

pnpm db:pull # Pull schema from database

```

API Documentation

```bash

pnpm write-openapi # Generate OpenAPI docs

pnpm start:server # Start API server

```

Key Development Patterns

Package Dependencies

Use `workspace:*` for internal dependencies

Frontend transpiles `@workspace/ui` and `@workspace/env-config`

API exports app for external consumption

Authentication

Better Auth handles authentication with generated schema

Bearer token middleware protects API routes

Frontend uses session hooks and auth utilities

Database Schema

Snake case database columns, camelCase TypeScript

Schema organized by domain (users, bookings, tasks, event-types)

Migrations in `packages/db/migrations/`

API Structure

Hono.js with OpenAPI spec generation

Routes organized by feature in `apps/api/src/routes/`

Zod schemas for validation and OpenAPI docs

CORS configured for dev and production

Frontend Architecture

App Router with nested layouts

Route groups: `(application)`, `(unauthenticated)`, `(settings)`

Component organization by feature

TanStack Query for server state management

Managing AI-Generated Planning Documents

Store ALL AI-generated planning/design docs in a `history/` directory:

PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md

DESIGN.md, CODEBASE_SUMMARY.md, etc.

**Benefits:**

Clean repository root

Clear separation between ephemeral and permanent docs

Easy to exclude from version control

Preserves planning history

Session Completion ("Landing the Plane")

**When ending a work session:**

1. **Update bd issues**

- Close completed work: `bd close <id> --reason "Done"`

- Update status on partial work

- File issues for discovered follow-up work

2. **Run quality gates** (if code changed)

- Type checking: `pnpm typecheck`

- Tests: `pnpm test`

- Linters: Check for errors

- File P0 issues if builds are broken

3. **Sync issues to JSONL (without committing)**

```bash

bd sync --squash

```

4. **Stop - DO NOT commit or push**

- All changes (code + JSONL) remain uncommitted

- Human reviews everything before committing

- Human handles all git operations

5. **Provide handoff**

- Summarize completed work

- List open bd issues for follow-up

- Note blockers or decisions needed

- Mention quality gate failures

**Critical Rules:**

✅ DO run `bd sync --squash` to update JSONL

❌ DO NOT run `bd sync` without `--squash` (auto-commits)

❌ DO NOT run `git add`, `git commit`, or `git push`

❌ DO NOT say "ready to commit when you are" - just stop

**Workflow:**

```

Agent work → bd sync --squash → stop → human reviews → human commits → human pushes

```

Environment Configuration

Environment variables are managed through `@workspace/env-config` with separate client and server configurations. The root `.env` file is loaded by both applications.

Important Rules

✅ Use bd for multi-session and discovered work

✅ Always use `--json` flag for programmatic bd use

✅ Link discovered work with `discovered-from` dependencies

✅ Check `bd ready` before asking "what should I work on?"

✅ Store AI planning docs in `history/` directory

✅ Run `bd <cmd> --help` to discover available flags

✅ Run `bd sync --squash` at session end (never plain `bd sync`)

❌ Do NOT create markdown TODO lists

❌ Do NOT use external issue trackers

❌ Do NOT duplicate tracking systems

❌ Do NOT clutter repo root with planning documents

❌ Do NOT commit or push code (human handles git operations)

Agent-Cal Development Guide

Agent-Cal Development Guide

Architecture Overview

Issue Tracking with bd (beads)

When to Use bd

bd Workflow for AI Agents

Writing Self-Contained Issues

Dependencies: Think "Needs", Not "Before"

Issue Types & Priorities

Common Development Commands

Development

Building & Testing

Database Operations

API Documentation

Key Development Patterns

Package Dependencies

Authentication

Database Schema

API Structure

Frontend Architecture

Managing AI-Generated Planning Documents

Session Completion ("Landing the Plane")

Environment Configuration

Important Rules

Reviews (0)