Dagger-App Development

Development guide for working on Dagger-App, a local web application for generating Daggerheart TTRPG adventures using Claude Code via MCP (Model Context Protocol).

What This Skill Provides

This skill guides you through developing Dagger-App, including:

Project Architecture

```

┌─────────────────┐ HTTP/WS ┌─────────────────┐ MCP ┌─────────────────┐

│ React Frontend │ ◄──────────────► │ MCP Bridge │ ◄──────────► │ Claude Code │

│ (Vite + TS) │ │ Server (Node) │ │ (Your sub) │

└────────┬────────┘ └────────┬────────┘ └─────────────────┘

│ │

│ │

▼ ▼

┌─────────────────┐ ┌─────────────────┐

│ Local Browser │ │ Supabase JMK │

│ │ │ (12 content │

└─────────────────┘ │ tables) │

└─────────────────┘

```

Data Flow

1. User → Frontend: Chat messages, dial adjustments, content requests

2. Frontend → Bridge: HTTP REST + WebSocket for real-time updates

3. Bridge → Claude: MCP tool invocations for AI generation

4. Bridge → Supabase: Queries for Daggerheart content (frames, adversaries, items, etc.)

5. Bridge → Frontend: Streaming responses, draft content, phase updates

Project Structure

```

dagger-app/

├── apps/

│ ├── web/ # React frontend (port 5173)

│ │ ├── src/

│ │ │ ├── components/ # UI components

│ │ │ ├── stores/ # Zustand stores

│ │ │ ├── hooks/ # Custom hooks

│ │ │ ├── services/ # API clients

│ │ │ └── styles/ # Global CSS with Tailwind

│ │ ├── vite.config.ts

│ │ └── tailwind.config.ts # Fantasy theme colors

│ │

│ └── mcp-bridge/ # Node.js bridge server (port 3001)

│ ├── src/

│ │ ├── index.ts # Express + WebSocket entry point

│ │ ├── config.ts # Environment configuration

│ │ ├── routes/ # REST endpoints

│ │ ├── middleware/ # cors.ts, logger.ts

│ │ ├── websocket/ # WebSocket handler

│ │ └── services/ # supabase.ts, daggerheart-queries.ts

│ └── .env.example

│

├── packages/

│ └── shared-types/ # TypeScript types shared between apps

│ └── src/

│ ├── index.ts # API types

│ └── database.ts # Supabase schema types (14 tables)

│

└── documentation/

└── PLAN.md # Full project plan and phase breakdown

```

Development Instructions

1. Setting Up Development Environment

When starting work on Dagger-App:

1. Verify Node.js 20+ and pnpm 9+ are installed

2. Check for `.env` file in `apps/mcp-bridge/` with required environment variables:

- `PORT=3001`

- `NODE_ENV=development`

- `ALLOWED_ORIGINS=http://localhost:5173`

- `SUPABASE_URL` and `SUPABASE_ANON_KEY`

3. Start development servers with `pnpm dev` (runs both frontend and bridge)

4. Verify health check: `curl http://localhost:3001/health`

2. Creating New Features

When implementing new features:

1. **Identify the scope**: Frontend component, backend route, MCP tool, or full-stack integration

2. **Use shared types**: Import types from `@dagger-app/shared-types` for consistency

3. **Follow the fantasy theme**: Use Tailwind classes with fantasy palette (`parchment`, `ink`, `gold`, `blood`, `shadow`)

4. **Apply TDD for bugs/enhancements**: Write failing tests first for `bug` and `enhancement` labels

5. **Maintain coverage for refactors**: Use Coverage Guard approach for `refactor` label

3. Working with Shared Types

Always use shared types from `packages/shared-types`:

```typescript

import { DaggerheartFrame, DaggerheartAdversary } from '@dagger-app/shared-types';

```

When adding new types:

1. Add to `packages/shared-types/src/database.ts` for database schemas

2. Add to `packages/shared-types/src/index.ts` for API contracts

3. Rebuild shared-types package: `pnpm --filter shared-types build`

4. Implementing MCP Tools

When creating new MCP tools:

1. Follow the pattern in existing tools

2. Include input validation using Zod schemas

3. Add comprehensive error handling

4. Write unit tests covering success and error cases

5. Register tool in tool registry

6. Document tool purpose and parameters

Consider invoking the `mcp-tool-developer` agent for complex tools.

5. Working with Supabase Content

When querying Daggerheart content:

1. Use the singleton Supabase client: `import { getSupabase } from './services/supabase.js';`

2. Reference the 14 content tables:

- `daggerheart_frames` (adventure frameworks)

- `daggerheart_adversaries` (enemy stat blocks)

- `daggerheart_items`, `daggerheart_consumables`, `daggerheart_weapons`, `daggerheart_armor`

- `daggerheart_environments`, `daggerheart_ancestries`, `daggerheart_classes`

- `daggerheart_subclasses`, `daggerheart_domains`, `daggerheart_abilities`

- `daggerheart_communities`, `daggerheart_adventures`

3. Filter by tier/difficulty when appropriate

4. Check Supabase health with `checkSupabaseHealth()` for diagnostics

Consider invoking the `daggerheart-content-expert` agent for content recommendations.

6. Implementing WebSocket Communication

When adding real-time features:

1. Use planned WebSocket events:

- `chat:assistant_message` for streaming AI responses

- `content:draft_ready` for generated content notifications

- `phase:changed` for workflow progression updates

2. Handle connection lifecycle (connect, disconnect, reconnect)

3. Implement error recovery and timeout handling

4. Test with frontend connection states

7. Adventure Generation Workflow

Respect the 10-phase adventure generation workflow:

1. **Setup** - Adventure name, folder creation

2. **Dial Tuning** - Conversational configuration of 14 parameters (CRITICAL)

3. **Frame** - Select/create adventure framework from Supabase

4. **Outline** - Generate 3-6 scene briefs with feedback loop

5. **Scenes** - Draft-feedback-revise cycle per scene

6. **NPCs** - Compile and enrich NPCs from scenes

7. **Adversaries** - Pull full stat blocks from Supabase

8. **Items** - Generate tier-appropriate rewards

9. **Echoes** - Create GM creativity tools (5 categories)

10. **Complete** - Export to filesystem

Each phase should maintain state and allow backward navigation.

8. Git Workflow

Follow the branch strategy:

1. Create feature branch: `git checkout -b gh-<issue-number>-<short-description>`

2. Make atomic commits referencing the issue number

3. Run validations before pushing: `pnpm build && pnpm lint`

4. Create PR: `gh pr create`

5. Reference related issues in PR description

9. Testing Strategy

Apply testing based on issue label:

Run tests with:

```bash

pnpm test # All tests

pnpm --filter web test # Frontend only

pnpm --filter mcp-bridge test # Bridge only

```

10. Using Project Agents

Invoke specialized agents for complex tasks:

- Example: "Use the daggerheart-content-expert agent to recommend adversaries for tier 2"

- Example: "Use the adventure-validator to check if the outline matches the dials"

- Example: "Use the mcp-tool-developer to create a new tool for echo generation"

- Example: "Use the integration-test-writer to add tests for the NPC compilation workflow"

Key Patterns and Conventions

Fantasy Theme Colors

Use Tailwind classes with fantasy palette:

```typescript

className="bg-parchment text-ink border-gold"

className="bg-shadow text-parchment-100"

className="text-blood-700 shadow-gold-glow"

```

Available colors: `parchment`, `ink`, `gold`, `blood`, `shadow` (each with 50-950 shades)

Supabase Singleton Pattern

```typescript

import { getSupabase, checkSupabaseHealth } from './services/supabase.js';

const supabase = getSupabase();

const frames = await supabase.from('daggerheart_frames').select('*');

```

Error Handling

Always provide detailed error context:

```typescript

throw new Error(`Failed to fetch adversaries for tier ${tier}: ${error.message}`);

```

Common Commands

```bash

Development

pnpm dev # Start both apps

pnpm --filter web dev # Frontend only (port 5173)

pnpm --filter mcp-bridge dev # Bridge only (port 3001)

Build & Quality

pnpm build # Build all packages

pnpm typecheck # Type checking

pnpm lint # Linting

pnpm clean # Clean build artifacts

Testing

pnpm test # Run all tests

pnpm --filter <package> test # Run tests for specific package

```

Critical Constraints

1. **Dial Tuning Must Be Conversational**: Phase 2 dial configuration should feel like a natural conversation, not a form

2. **Tier-Appropriate Content**: Always filter Supabase content by tier/difficulty

3. **Maintain Coverage**: Refactors must maintain or improve test coverage baseline

4. **Type Safety**: Use shared types from `@dagger-app/shared-types` package

5. **Fantasy Theme Consistency**: Apply fantasy color palette throughout UI

Technology Stack

Additional Resources