@hailer/mcp 1.1.13 → 1.1.15

package/.claude/commands/autoplan.md

@@ -0,0 +1,563 @@
+---
+description: Create project plan with workspace structure and PRDs
+argument-hint: <project description>
+---
+# Autoplan Command
+
+Create a complete project plan: workspace structure, DEVELOPMENT.md (big picture), and PRDs (feature details).
+
+## Usage
+```
+/autoplan "Build a booking system with customer portal and admin dashboard"
+```
+
+## Instructions
+
+### Phase 1: Understand the Project
+
+1. **Parse the prompt** - Identify:
+   - Project name/purpose
+   - Individual features/apps mentioned
+   - Any technical requirements mentioned
+
+2. **Detect project state:**
+
+   | Indicator | State | Action |
+   |-----------|-------|--------|
+   | Has `workspace/` with workflows | Existing Hailer | Audit first, then plan additions |
+   | Has `workspace/` empty/minimal | New Hailer | Plan from scratch |
+   | Has `DEVELOPMENT.md` | Existing project | Read it, plan additions |
+   | Nothing | New project | Plan from scratch |
+
+3. **For EXISTING Hailer projects — audit first:**
+
+   ```bash
+   # Read what already exists
+   ls workspace/           # List workflows
+   ls apps/ 2>/dev/null    # List apps (if any)
+   ls docs/prd-*.md 2>/dev/null  # List existing PRDs
+   ```
+
+   Use Kenji agent to read:
+   - Existing workflows and their fields/phases
+   - Existing insights
+   - Existing apps and their purpose
+
+   **Then ask:**
+   - What do you want to ADD to this project?
+   - Any existing features need changes?
+
+4. **For NEW Hailer projects:**
+   - What workflows/data do you need?
+   - Need custom apps? (or just use built-in UI)
+   - If apps: Public or authenticated?
+
+5. **For standard projects:**
+   - Tech stack preferences?
+   - Any existing codebase to integrate with?
+
+6. **Apply design patterns** (see below) when structuring workflows.
+
+---
+
+## Design Patterns (Quick Reference)
+
+### Workflow Structure
+
+**Header + Rows (Two Workflows)**
+Any entity with line items needs two workflows:
+- Sales Orders → Order Rows (link to Products, Services)
+- Purchase Orders → PO Rows
+- Invoices → Invoice Rows (or link to existing Order Rows)
+- Quotes → Quote Lines
+
+**Row Source Flexibility:** Order rows can link to multiple catalogs (Products, Services, Materials) - use separate row workflows when types differ significantly.
+
+**Dataset vs Workflow**
+- **Dataset:** Static/reference data (Products, Customers) - phases are categories, activities don't transition
+- **Workflow:** Lifecycle data (Orders, Invoices) - phases are stages, activities progress through them
+
+**Master Data vs Transactional**
+- Master data: `enableUnlinkedMode: true` - Customers, Products, Suppliers
+- Transactional: `enableUnlinkedMode: false` - Orders, Invoices, Rows
+
+**Phase-Specific Field Visibility**
+Different phases can show different fields:
+- Workflow: Draft (basic fields) → Confirmed (+ date, by) → Shipped (+ tracking)
+- Dataset: Products (dimensions, weight) vs Services (hourly rate, duration)
+
+**Domain Prefixes (30+ workflows):** Use `INV-`, `MYY-`, `OST-`, `VH-` prefixes to organize.
+
+---
+
+### Row Lifecycle
+
+**Pattern A: Rows progress through phases**
+```
+Order Row → "Ordered" → "Shipped" → "Invoiced"
+```
+Use when: Simple 1:1 process, no integrations
+
+**Pattern B: Rows generate new activities**
+```
+Order Row → creates → Invoice Row
+```
+Use when: Partial invoicing, consolidated invoicing, accounting integration, different pricing
+
+---
+
+### Integration Patterns
+
+| Need | Solution |
+|------|----------|
+| Phase cascades | Activity Mover |
+| Simple notifications | Zapier webhooks |
+| Complex automations | Project Monolith |
+| No integration | Export insight (CSV) |
+
+---
+
+### Document Templates
+
+For invoices, quotes, order confirmations - pull header + linked rows into PDF.
+
+### Phase 2: Create Project Structure
+
+**For Hailer projects:**
+
+Note: `workspace/` is created by the Hailer SDK, not manually. It starts with one workflow.
+
+```bash
+# Only create if custom apps are needed
+mkdir -p apps
+mkdir -p docs
+
+# Copy Hailer agents/skills/hooks if not present
+# (suggest running /setup-hailer)
+```
+
+**For standard projects:**
+```bash
+mkdir -p docs
+mkdir -p apps  # Only if multiple apps mentioned
+```
+
+### Phase 3: Create/Update DEVELOPMENT.md
+
+**For EXISTING projects:**
+- If DEVELOPMENT.md exists → READ it first, then UPDATE (don't overwrite)
+- Add new features to existing Roadmap table
+- Document existing workflows/apps if not already documented
+- Preserve existing Technical Decisions
+
+**For NEW projects:** Create from scratch using templates below.
+
+---
+
+**For Hailer projects:**
+
+```markdown
+# [Project Name]
+
+**Type:** Hailer SDK Project
+**Workspace:** [workspace name in Hailer]
+**Run:** `npm run dev` (if apps)
+
+---
+
+## What This Project Does
+[2-3 sentences from the prompt]
+
+---
+
+## Data Model (Workflows)
+
+| Workflow | Purpose | Key Fields |
+|----------|---------|------------|
+| [Workflow 1] | [What it stores] | [Important fields] |
+| [Workflow 2] | [What it stores] | [Important fields] |
+
+---
+
+## Apps
+
+| App | Type | Description |
+|-----|------|-------------|
+| [app-name] | Public / Authenticated | [What it does] |
+
+**Public apps** use public insights (no login required)
+**Authenticated apps** use Hailer user management
+
+---
+
+## Architecture
+
+```
+project/
+├── workspace/           # Data model (SDK-managed)
+│   └── [Workflow]_id/   # Fields, phases, functions
+├── apps/                # Custom frontends (if needed)
+│   └── [app-name]/
+└── docs/
+    └── prd-*.md
+```
+
+---
+
+## Roadmap
+
+| Feature | PRD | Status |
+|---------|-----|--------|
+| [Workflow: Name] | [docs/prd-workflow-name.md](docs/prd-workflow-name.md) | Planned |
+| [App: Name] | [docs/prd-app-name.md](docs/prd-app-name.md) | Planned |
+| [Insight: Name] | [docs/prd-insight-name.md](docs/prd-insight-name.md) | Planned |
+
+---
+
+## Current Status
+**Active:** Planning phase
+**Blocked:** None
+
+---
+
+## Known Issues
+- [ ] None yet
+
+---
+
+## Technical Decisions
+| Decision | Rationale | Date |
+|----------|-----------|------|
+```
+
+**For standard projects:**
+
+```markdown
+# [Project Name]
+
+**Stack:** [Detected or asked]
+**Entry:** [Main entry point]
+**Run:** [Dev command]
+
+---
+
+## What This Project Does
+[2-3 sentences from the prompt]
+
+---
+
+## Architecture
+
+```
+project/
+├── apps/
+│   └── [app-name]/
+├── docs/
+│   └── prd-*.md
+└── [other relevant dirs]
+```
+
+---
+
+## Roadmap
+
+| Feature | PRD | Status |
+|---------|-----|--------|
+| [Feature 1] | [docs/prd-feature-1.md](docs/prd-feature-1.md) | Planned |
+
+---
+
+## Current Status
+**Active:** Planning phase
+**Blocked:** None
+
+---
+
+## Known Issues
+- [ ] None yet
+
+---
+
+## Technical Decisions
+| Decision | Rationale | Date |
+|----------|-----------|------|
+```
+
+### Phase 4: Create PRDs for New Features
+
+**For EXISTING projects:**
+- Check `docs/prd-*.md` for existing PRDs
+- Only create PRDs for NEW features being added
+- Don't duplicate existing documentation
+- If existing feature needs changes → update existing PRD or create a new one with `-v2` suffix
+
+**For Hailer projects, create PRDs by type:**
+
+**Workflow PRD** (`docs/prd-workflow-[name].md`):
+```markdown
+# PRD: Workflow - [Name]
+
+**Status:** Planned
+**Created:** YYYY-MM-DD
+**Parent:** [DEVELOPMENT.md](../DEVELOPMENT.md)
+
+---
+
+## Purpose
+[What data this workflow stores and why]
+
+---
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| [name] | text/date/dropdown/link/etc | Yes/No | [purpose] |
+
+---
+
+## Phases
+
+| Phase | Description | Visible Fields |
+|-------|-------------|----------------|
+| [phase] | [when activity is in this state] | [which fields show] |
+
+---
+
+## Function Fields (calculated values)
+
+| Field | Type | Formula/Logic | Variables |
+|-------|------|---------------|-----------|
+| [total] | function | qty × price | qty, price |
+| [days_open] | function | today - created_date | created_date |
+| [status_text] | function | if priority=high → "🔴" | priority |
+
+**Common patterns:**
+- Arithmetic: `qty * price`, `subtotal + tax`
+- Date diff: `Math.floor((new Date() - created) / 86400000)`
+- Conditional: `priority === 'high' ? '🔴 Urgent' : '🟢 Normal'`
+- Backlink count: Count linked activities from another workflow
+
+---
+
+## Name Function
+
+**Pattern:** `[prefix]-[number] [distinctive field]`
+**Example:** `ORD-001 Acme Corp`
+**Key field:** [which field makes activities identifiable]
+
+---
+
+## Implementation Steps
+1. [ ] Add workflow via SDK
+2. [ ] Define fields in fields.ts
+3. [ ] Define phases in phases.ts
+4. [ ] Push and pull (get IDs) - Helga auto-spawns Alejandro for nameFunction + function fields (if any)
+5. [ ] Verify in Hailer
+
+---
+
+## Verification
+- [ ] Workflow appears in Hailer
+- [ ] All fields work correctly
+- [ ] Phase transitions work
+```
+
+**App PRD** (`docs/prd-app-[name].md`):
+```markdown
+# PRD: App - [Name]
+
+**Status:** Planned
+**Created:** YYYY-MM-DD
+**Parent:** [DEVELOPMENT.md](../DEVELOPMENT.md)
+**Type:** Public / Authenticated
+
+---
+
+## Purpose
+[What this app does for users]
+
+---
+
+## Data Sources
+- **Workflow:** [which workflow(s) it reads/writes]
+- **Insight:** [which insight(s) power the views]
+- **Public insight?** [Yes = public app possible, No = requires auth]
+
+---
+
+## Data Access (Phase Rationalization)
+
+| View | Phases Fetched | Rationale |
+|------|----------------|-----------|
+| [Main list] | [which phases] | [why these phases for this user] |
+| [Dashboard] | [which phases] | [why] |
+
+---
+
+## User Stories
+- As a [user type], I want to [action] so that [benefit]
+
+---
+
+## Screens/Views
+1. [Screen name] - [what it shows]
+2. [Screen name] - [what it shows]
+
+---
+
+## Implementation Steps
+1. [ ] Create insight for data (if needed)
+2. [ ] Scaffold app with MCP tool
+3. [ ] Build components
+4. [ ] Connect to Hailer data
+5. [ ] Test and deploy
+
+---
+
+## Verification
+- [ ] App loads correctly
+- [ ] Data displays from Hailer
+- [ ] User actions work (if authenticated)
+```
+
+**Insight PRD** (`docs/prd-insight-[name].md`):
+```markdown
+# PRD: Insight - [Name]
+
+**Status:** Planned
+**Created:** YYYY-MM-DD
+**Parent:** [DEVELOPMENT.md](../DEVELOPMENT.md)
+**Public:** Yes / No
+
+---
+
+## Purpose
+[What data this insight provides and for what use]
+
+---
+
+## Query Design
+- **Source workflow(s):** [which workflows]
+- **Joins:** [if linking workflows]
+- **Filters:** [default filters]
+- **Grouping:** [if aggregating]
+
+---
+
+## Output Fields
+| Field | Source | Description |
+|-------|--------|-------------|
+| [name] | [workflow.field] | [purpose] |
+
+---
+
+## Implementation Steps
+1. [ ] Create insight via Viktor agent
+2. [ ] Test query results
+3. [ ] Set public flag (if needed for public app)
+
+---
+
+## Verification
+- [ ] Insight returns correct data
+- [ ] Performance is acceptable
+```
+
+**For standard projects:**
+
+```markdown
+# PRD: [Feature Name]
+
+**Status:** Planned
+**Created:** YYYY-MM-DD
+**Parent:** [DEVELOPMENT.md](../DEVELOPMENT.md)
+
+---
+
+## Overview
+[What this feature does, 2-3 sentences]
+
+---
+
+## User Stories
+- As a [user type], I want to [action] so that [benefit]
+
+---
+
+## Requirements
+
+### Must Have
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+### Nice to Have
+- [ ] Optional requirement
+
+---
+
+## Technical Approach
+[How to implement - key files, patterns, integrations]
+
+**Files to create/modify:**
+- `path/to/file` - [purpose]
+
+---
+
+## Implementation Steps
+1. [ ] Step 1 with file references
+2. [ ] Step 2 with file references
+
+---
+
+## Verification
+- [ ] How to test this feature works
+
+---
+
+## Open Questions
+- [Any unresolved decisions]
+```
+
+### Phase 5: Report
+
+**For NEW projects:**
+```
+## Project Planned: [Name]
+
+**Created:**
+- DEVELOPMENT.md (big picture)
+- docs/prd-feature-1.md
+- docs/prd-feature-2.md
+- Directory structure
+
+**Next steps:**
+1. Review PRDs and refine requirements
+2. Start building from a PRD: review requirements, then implement
+```
+
+**For EXISTING projects:**
+```
+## Project Updated: [Name]
+
+**Existing (documented):**
+- [X workflows already in place]
+- [X apps already built]
+- [X existing PRDs]
+
+**Added:**
+- Updated DEVELOPMENT.md with current state
+- docs/prd-new-feature.md
+
+**Next steps:**
+1. Review new PRDs
+2. Start implementing from the PRD
+```
+
+## Important
+
+- **Big picture → DEVELOPMENT.md** (architecture, roadmap, status)
+- **Feature details → PRDs** (requirements, steps, verification)
+- PRDs are linked from DEVELOPMENT.md roadmap table
+- Each PRD is self-contained but references parent DEVELOPMENT.md
+- Don't start implementing - only plan

package/.claude/commands/cleanup-squad.md

@@ -0,0 +1,98 @@
+---
+description: Clean up codebase with Bjorn, Code Simplifier, and Lars
+argument-hint: [files, directory, or blank for recent changes]
+allowed-tools: Task, Bash
+---
+# Cleanup Squad
+
+Run parallel codebase cleanup using three agents simultaneously.
+
+**Agents:**
+- **Bjorn** - Configuration audit (verify CLAUDE.md, hooks, workspace structure)
+- **Code Simplifier** - Refactor (improve code clarity and maintainability)
+- **Lars** - Dead code detection (find unused imports, dead code, type errors)
+
+**Target:** $ARGUMENTS (if blank, use recent git changes)
+
+**Changed files (auto-injected):**
+!git diff --name-only HEAD
+
+## Protocol
+
+### Step 1: Determine Target
+
+If `$ARGUMENTS` has specific files/directories, use those.
+Otherwise, use the changed files list above as the target.
+
+If `$ARGUMENTS` contains `--skip-config`:
+- Remove flag from target
+- Skip Bjorn in Step 2
+
+If `$ARGUMENTS` contains `--skip-dead-code`:
+- Remove flag from target
+- Skip Lars in Step 2
+
+### Step 2: Launch Agents in Parallel
+
+Spawn all agents simultaneously using multiple Task tool calls in a single message:
+
+**Bjorn:**
+```
+Task(subagent_type="agent-bjorn-config-audit", prompt="Audit codebase configuration for: [TARGET]. Check:\n- CLAUDE.md accuracy and completeness\n- Hook configurations\n- Workspace structure\n- Agent definitions\n\nReturn list of issues found with severity levels.")
+```
+
+**Code Simplifier:**
+```
+Task(subagent_type="agent-code-simplifier", prompt="Refactor these files for clarity and maintainability: [TARGET]. Focus on:\n- Variable naming\n- Function complexity\n- Comment clarity\n- Code organization\n\nReturn refactoring suggestions with before/after examples.")
+```
+
+**Lars:**
+```
+Task(subagent_type="agent-lars-code-inspector", prompt="Inspect these files for dead code: [TARGET]. Find:\n- Unused imports\n- Unreachable code\n- Unused variables\n- Type errors\n\nUse LSP if available. Return detailed list grouped by file.")
+```
+
+### Step 3: Aggregate Results
+
+Compile a unified cleanup report:
+
+```markdown
+## Cleanup Squad Report
+
+### Bjorn (Config Audit)
+- Issues found: X
+- Critical: X
+- Warnings: X
+- [Issues grouped by category]
+
+### Code Simplifier (Refactoring)
+- Files analyzed: X
+- Refactoring suggestions: X
+- [Suggestions grouped by file]
+
+### Lars (Dead Code)
+- Unused imports: X
+- Dead code blocks: X
+- Type errors: X
+- [Details grouped by file]
+
+### Summary
+[Overall assessment of codebase health]
+[Prioritized action items]
+
+### Recommended Order
+1. [Fix critical config issues first]
+2. [Remove dead code]
+3. [Apply refactoring suggestions]
+```
+
+If any agent fails or times out, report partial results from successful agents, note which failed, and offer to re-run individually.
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| `--skip-config` | Skip Bjorn (faster, no config validation) |
+| `--skip-dead-code` | Skip Lars (when LSP not configured) |
+| `--bg` | Run all agents in background mode |
+
+If `--bg` is present, launch all agents with `run_in_background: true` and tell the user they'll be notified when complete.