duck-dag GitHub Copilot Instructions

Development workflow and architectural guidance for the duck-dag project, a WASM-powered data pipeline builder.

Project Overview

duck-dag is an in-browser data pipeline builder leveraging:

Critical: Dev Server Behavior

**All AI agents must understand:** Development servers display informational messages that are NOT interactive prompts.

Server Ready Indicators

When you see these patterns, the server is running and ready:

```

➜ Local: http://localhost:5173/

➜ Network: use --host to expose

➜ press h + enter to show help

```

**These messages mean:**

Detection Patterns

Server is ready when output contains:

Correct Implementation

```typescript

// ✅ CORRECT: Start server in background

run_in_terminal({

command: "npm run dev",

isBackground: true // Returns immediately, process continues

})

// Poll output to confirm ready state

get_terminal_output(terminalId)

// Look for "Local: http://localhost:XXXX/"

// Server is ready - no further input needed

```

```typescript

// ❌ WRONG: Don't send keyboard input to dev servers

run_in_terminal({

command: "h\n", // Server doesn't need this!

})

```

Development Commands

Starting Development Server

```bash

cd duck-dag-ui

npm run dev # Starts Vite dev server (background-friendly)

```

Running Tests

```bash

cd duck-dag-ui

npm test # Vitest in watch mode

npm test -- --run # Single run (CI-friendly)

```

Building for Production

```bash

cd duck-dag-ui

npm run build # Production build

```

BMad Method Workflow

This project follows the BMad Method for structured development:

1. **Story-Driven**: All features tied to stories in `_bmad-output/implementation-artifacts/`

2. **Dev Agent Workflow**:

- Check for existing story files first

- Create story with acceptance criteria

- Implement changes

- Test against acceptance criteria

- Review and iterate

3. **Story Locations**: `_bmad-output/implementation-artifacts/`

Before Implementing Features

Always check for existing story files that define:

Architecture Reference

For complete system design, consult:

Key architectural components:

Usage Examples

Starting a Feature

1. Check for story file in `_bmad-output/implementation-artifacts/`

2. Start dev server: `cd duck-dag-ui && npm run dev`

3. Wait for "Local: http://localhost:XXXX/" message

4. Begin implementation against acceptance criteria

5. Run tests: `npm test -- --run`

Testing Changes

```bash

Run tests in watch mode during development

npm test

Run once for CI/verification

npm test -- --run

```

Important Constraints