# Proxym Example: TypeScript TODO App

End-to-end demonstration of automatic project generation using proxym AI tool
orchestration. This example creates a real TypeScript CLI application on your
disk, entirely driven by proxym tickets and AI tools.

## What This Example Does

```
┌─────────────────────────────────────────────────────────────────┐
│                        run.sh                                   │
│                                                                 │
│  Phase 1 · Create project scaffold on disk                      │
│      ↓        ~/projects/todo-app-ts/                           │
│      ↓        package.json, tsconfig.json, src/ stubs           │
│                                                                 │
│  Phase 2 · Register in proxym                                   │
│      ↓        Environment (local_path → project dir)            │
│      ↓        Project (todo-app-ts, default tool, etc.)         │
│                                                                 │
│  Phase 3 · Create sprint & tickets                              │
│      ↓        Sprint "TODO App MVP"                             │
│      ↓        7 tickets (store, format, commands, CLI, tests)   │
│                                                                 │
│  Phase 4 · Dispatch to AI tools                                 │
│      ↓        Each ticket → aider/claude-code → runs in dir     │
│      ↓        Waits for completion, creates human ticket on fail│
│                                                                 │
│  Phase 5 · Build & Verify                                       │
│      ↓        npm install → tsc --noEmit → npm run build        │
│      ↓        npm test → smoke test (add/list/stats)            │
│                                                                 │
│  Phase 6 · Save report                                          │
│             .proxym/report.md, tickets.manifest, run.log        │
└─────────────────────────────────────────────────────────────────┘
```

## Quick Start

```bash
# 1. Make sure proxym server is running
proxym serve &

# 2. Run the example (default: ~/projects/todo-app-ts, tool: aider)
bash examples/todo-app-ts/run.sh

# 3. Inspect the generated project
cd ~/projects/todo-app-ts
npm install && npm run build
node dist/index.js add "Hello world" --priority high
node dist/index.js list
```

## Options

```bash
bash examples/todo-app-ts/run.sh [OPTIONS]

Options:
  --project-dir PATH   Where to create the project (default: ~/projects/todo-app-ts)
  --tool NAME          AI tool to use: aider, claude-code (default: aider)
  --model NAME         LLM model override (default: tool's default)
  --proxy URL          Proxym server URL (default: http://localhost:4000)
  --dry-run            Show plan without executing anything
  --skip-dispatch      Create project & tickets but don't dispatch to AI tools
  -h, --help           Show help
```

## Examples

```bash
# Dry run — see what would happen without doing anything
bash examples/todo-app-ts/run.sh --dry-run

# Use claude-code instead of aider
bash examples/todo-app-ts/run.sh --tool claude-code

# Custom project directory
bash examples/todo-app-ts/run.sh --project-dir /tmp/my-todo-app

# Custom proxym server
bash examples/todo-app-ts/run.sh --proxy http://10.0.0.5:4000

# Setup only — create project and tickets, dispatch manually later
bash examples/todo-app-ts/run.sh --skip-dispatch
```

## What Gets Created on Disk

The generated project at `~/projects/todo-app-ts/` is a **real, standalone
Node.js project** that works independently of proxym:

```
~/projects/todo-app-ts/
├── package.json              # Node.js project config
├── tsconfig.json             # TypeScript config
├── vitest.config.ts          # Test runner config
├── spec.md                   # Project specification (input for AI)
├── README.md                 # Generated README
├── .gitignore
├── .git/                     # Git history of changes
├── src/
│   ├── types.ts              # Todo interface, enums
│   ├── store.ts              # JSON file storage (AI-generated)
│   ├── format.ts             # Output formatters (AI-generated)
│   ├── commands.ts           # CLI command handlers (AI-generated)
│   └── index.ts              # CLI entry point (AI-generated)
├── tests/
│   ├── store.test.ts         # Store unit tests (AI-generated)
│   └── commands.test.ts      # Command tests (AI-generated)
├── dist/                     # Compiled JS (after build)
├── node_modules/             # Dependencies (after npm install)
└── .proxym/                  # Proxym metadata
    ├── metadata.json         # Project & environment IDs
    ├── tickets.manifest      # Ticket ID → title mapping
    ├── report.md             # Full run report
    └── run.log               # Timestamped execution log
```

## How It Works Step by Step

### Phase 1: Scaffold

The script creates the project directory with:
- `package.json` with TypeScript, Vitest, and Commander.js
- `tsconfig.json` with strict mode
- `src/types.ts` with the complete `Todo` data model
- Stub files (`store.ts`, `commands.ts`, `format.ts`, `index.ts`) with detailed
  JSDoc comments describing what the AI should implement
- Stub test files with `it.todo()` placeholders
- Git repository initialized with initial commit

### Phase 2: Register

The script registers everything in proxym via the REST API:
1. **Environment** — a `local_path` environment pointing to the project dir
2. **Tool assignment** — the chosen AI tool is assigned to that environment
3. **Project** — registered with name, description, default tool, and
   environment link

### Phase 3: Tickets

A sprint "TODO App MVP" is created, then 7 tickets:

| # | Ticket | Type | Priority | Tool |
|---|--------|------|----------|------|
| 1 | Implement TodoStore (store.ts) | feature | high | aider |
| 2 | Implement formatters (format.ts) | feature | medium | aider |
| 3 | Implement commands (commands.ts) | feature | high | aider |
| 4 | Implement CLI entry (index.ts) | feature | high | aider |
| 5 | Write store unit tests | test | high | aider |
| 6 | Write integration tests | test | medium | aider |
| 7 | Build & verify (npm) | task | critical | none |

Each ticket has a detailed description with exact requirements, file paths,
and a reference to `spec.md`.

### Phase 4: Dispatch

Tickets are dispatched sequentially. For each ticket:
1. `POST /dashboard/tools/dispatch` sends it to the AI tool
2. The tool (aider/claude-code) runs as a subprocess in the project directory
3. The script polls the job status every 5 seconds
4. On **success**: ticket moves to `in_review`
5. On **failure**: a `human` ticket is automatically created with:
   - The error details from the job
   - The project directory path
   - Instructions for manual fix

### Phase 5: Verify

After all dispatches complete:
1. `npm install` — install dependencies
2. `tsc --noEmit` — check for TypeScript errors
3. `npm run build` — compile to JavaScript
4. `npm test` — run Vitest
5. Smoke test — `add`, `list`, `stats` commands

Any failure creates a human ticket with the error output.

### Phase 6: Report

A Markdown report is saved to `.proxym/report.md` containing:
- Run configuration
- All ticket IDs and statuses
- Commands to inspect the project without proxym
- Command to reproduce the run

## Inspecting Results Without Proxym

The project is a regular Node.js project on disk. Even if proxym is stopped:

```bash
# The code is all there:
cd ~/projects/todo-app-ts
cat src/store.ts
cat src/commands.ts

# Build and use it:
npm install
npm run build
node dist/index.js add "Task 1"
node dist/index.js add "Task 2" --priority high
node dist/index.js list
node dist/index.js stats

# Check proxym metadata:
cat .proxym/metadata.json      # project ID, environment ID
cat .proxym/tickets.manifest   # ticket ID → title
cat .proxym/run.log            # timestamped log
cat .proxym/report.md          # full Markdown report
```

## Inspecting Results With Proxym

```bash
# Board view — see ticket statuses
proxym ticket board

# List all tickets for the project
proxym ticket list

# Check job queue and results
proxym tools jobs
proxym tools queue

# Show a specific ticket's details
proxym ticket show TKT-XXXXXX

# Show a specific job's output
proxym tools job <job-id>
```

## Troubleshooting

### "Proxym server not reachable"

```bash
proxym serve &
# or start on a specific port:
proxym serve --port 4000
```

### "Tool 'aider' not found"

The tool will fall back to LLM mode (generates text but doesn't write files).
For full functionality, install the tool:

```bash
pip install aider-chat       # for aider
npm install -g @anthropic/claude-code  # for claude-code
```

### "TypeScript errors after generation"

This is expected — AI-generated code sometimes has issues. Check the human
tickets:

```bash
proxym ticket list --status todo
# Fix the issues manually, then:
proxym ticket update TKT-XXXXXX --status done
```

### "Tests fail"

Review the test output and fix:

```bash
cd ~/projects/todo-app-ts
npm test 2>&1 | head -50
# Fix, then re-run
```

## Project Specification

See [spec.md](spec.md) for the full TypeScript TODO app specification that
drives the AI ticket generation.

## Files in This Example

| File | Purpose |
|------|---------|
| `run.sh` | Main orchestration script (all 6 phases) |
| `spec.md` | Project specification (input for AI tickets) |
| `verify.sh` | Standalone verification script |
| `README.md` | This file |