@hailer/mcp 1.1.12 → 1.1.13

package/.claude/commands/plan-workspace.md

@@ -1,732 +0,0 @@
----
-description: Comprehensive workspace planning with thorough discovery
-argument-hint: <business/project description>
-allowed-tools: Task, Bash, Read, AskUserQuestion
----
-# Plan Workspace Command
-
-Deep discovery process for planning a complete Hailer workspace. Ask MANY questions before creating anything.
-
-## Philosophy
-
-**This is NOT a quick command.** This is a thorough discovery session that should feel like a proper requirements gathering meeting. Ask questions until you truly understand:
-- The business and its processes
-- Who uses the system and why
-- What data flows where
-- What automation saves time
-- What reporting matters
-
-**Rule: When in doubt, ask another question.**
-
----
-
-## Design Patterns (Reference for Planning)
-
-Keep these patterns in mind throughout discovery. They inform how to structure workflows.
-
-### Workflow Structure
-
-**Header + Rows (Two Workflows)**
-Any entity with line items needs two workflows:
-
-| Header | Rows | Links To |
-|--------|------|----------|
-| Sales Orders | Order Rows | Products, Services |
-| Purchase Orders | PO Rows | Products, Suppliers |
-| Invoices | Invoice Rows | (or linked Order Rows) |
-| Quotes | Quote Lines | Products, Services |
-| Projects | Tasks | - |
-
-**Why two workflows:**
-- Rows can have independent phases (partial delivery)
-- Row count unlimited
-- Aggregation via function fields (order total = sum of lines)
-- Cleaner reporting
-
-**Naming convention (Finnish):** Base + "rivit" suffix
-- Tilaukset → Tilausrivit
-- Myyntitilaukset → Myyntitilausrivit
-- Laskut → Laskurivit
-
-**Row Source Flexibility**
-Rows don't have to be one workflow. A Sales Order might link to:
-- Product Rows → Products catalog
-- Service Rows → Services catalog
-- Production Rows → Production items
-
-Use separate row workflows when types have different fields or processes.
-
----
-
-**Dataset vs Workflow**
-
-| Type | When to Use | Examples | Phase Behavior |
-|------|-------------|----------|----------------|
-| **Dataset** | Static/reference data | Products, Customers, Suppliers | Categories (activities don't transition) |
-| **Workflow** | Lifecycle/state data | Orders, Invoices, Tasks | Phases (activities progress through stages) |
-
-- **Dataset:** Activities are categorized but don't "move" - a Product stays in "Electronics" category
-- **Workflow:** Activities progress through phases - an Order moves from "Draft" → "Confirmed" → "Shipped"
-
-This affects phase design:
-- Datasets: phases = categories (no transitions expected)
-- Workflows: phases = lifecycle stages (transitions matter)
-
----
-
-**Master Data vs Transactional**
-
-| Type | enableUnlinkedMode | Examples |
-|------|-------------------|----------|
-| Master data | `true` (independent) | Customers, Products, Suppliers, Employees |
-| Transactional | `false` (requires context) | Orders, Invoices, Quotes, their Rows |
-
----
-
-**Domain Prefixes (Large Workspaces)**
-For 30+ workflows, use prefixes to organize:
-- `INV-` Invoicing (INV-Laskut, INV-Laskurivit)
-- `VH-` Warehouse (VH-Varastopaikat, VH-Nimikkeet)
-- `MYY-` Sales (MYY-Tilaukset, MYY-Tilausrivit)
-- `OST-` Purchasing (OST-Tilaukset, OST-Tilausrivit)
-
----
-
-**Phase-Specific Field Visibility**
-
-Different phases can show different fields. Plan this during design:
-
-**Workflow example (Orders):**
-| Phase | Fields Shown |
-|-------|--------------|
-| Draft | Customer, Items, Notes |
-| Confirmed | + Confirmed Date, Confirmed By |
-| Shipped | + Ship Date, Tracking Number |
-| Invoiced | + Invoice Number, Invoice Date |
-
-**Dataset example (Products):**
-| Category | Fields Shown |
-|----------|--------------|
-| Physical Products | Name, Price, + Dimensions, Weight, Stock |
-| Services | Name, Price, + Hourly Rate, Duration |
-| Both | Name, Description, Price (shared) |
-
-Document in PRD which fields appear in which phases.
-
----
-
-**Phase Rationalization for Apps**
-
-When building apps, document which phases to show per user role:
-
-```markdown
-## Data Access (in app PRD)
-
-| View | Phases Fetched | Rationale |
-|------|----------------|-----------|
-| Sales Dashboard | Active only | Hide internal WIP from sales team |
-| Manager View | Draft + Active | Managers need WIP visibility |
-| Admin Panel | All phases | Full access for admin |
-| Public Portal | Active only | No internal data exposed |
-| Insights/Reports | Active only | Accurate counts, no draft duplicates |
-```
-
-**Why this matters:**
-- Prevents exposing draft/internal data to wrong users
-- Ensures reports show accurate counts
-- Different roles need different visibility
-
----
-
-### Row Lifecycle Patterns
-
-**Pattern A: Rows progress through phases (simpler)**
-```
-Order Row → "Ordered" → "Shipped" → "Invoiced"
-```
-- Same activity, phase changes
-- Invoice workflow links to the rows
-- Works when 1:1 (ordered = shipped = invoiced)
-- Good for simple processes without integrations
-
-**Pattern B: Rows generate new activities (complex)**
-```
-Order Row → creates → Invoice Row
-           → creates → Delivery Row
-```
-- Separate workflows for each document type
-- Use when:
-  - Partial invoicing (invoice 3 of 5 rows now)
-  - Consolidated invoicing (multiple orders → one invoice)
-  - Accounting integration needs clean invoice data
-  - Different pricing (order price ≠ invoice price)
-
-**Decision Guide**
-
-| Scenario | Approach |
-|----------|----------|
-| Simple tracking, no integrations | Rows progress through phases |
-| 1:1 order-to-invoice | Rows progress through phases |
-| Partial deliveries/invoices | Separate row workflows |
-| Accounting integration (Netvisor, etc.) | Separate invoice rows |
-| Multiple orders → one invoice | Separate invoice rows |
-
----
-
-### Integration Patterns
-
-| Need | Solution |
-|------|----------|
-| Phase cascades (parent → children) | Activity Mover |
-| Simple notifications/external tasks | Zapier webhooks |
-| Complex automations, scheduled jobs | Project Monolith |
-| Accounting sync (Netvisor, Procountor) | Monolith integration |
-| No integration (manual export) | Export insight (CSV) |
-
-**Export insight fallback:** When no direct integration, create an insight that formats invoice data for CSV download. User imports manually to accounting.
-
----
-
-### Document Templates
-
-Used for: Invoices, Quotes, Order Confirmations, Delivery Notes, Reports
-
-Templates pull data from header workflow + linked rows. Typically PDF format with company branding.
-
----
-
-### Single Workflow Pattern
-
-Use only for:
-- Master data (Customers, Products, Suppliers)
-- Simple tracking without line items (Expenses, Notes, Logs)
-- Reference data (Categories, Types)
-
-## Instructions
-
-### Phase 1: Business Context (5-10 questions)
-
-Start by understanding the big picture. Use AskUserQuestion tool.
-
-**Questions to ask:**
-1. What's the business/organization? (company name, industry)
-2. What problem are we solving? (pain points, current process)
-3. Who are the main users? (roles - admin, sales, warehouse, customers)
-4. How many users approximately? (scale affects design)
-5. Is this replacing an existing system? (migration needs)
-6. Any compliance/regulatory requirements? (GDPR, industry-specific)
-7. What's the timeline expectation? (MVP vs complete)
-8. Any existing systems to integrate with? (ERP, accounting, etc.)
-9. What language for workflow/field names?
-   - Finnish: "Tilaukset", "Tilausrivit", "Asiakkaat"
-   - English: "Orders", "Order Lines", "Customers"
-   - Swedish: "Beställningar", "Beställningsrader"
-
-**Ask follow-ups based on answers.** If they mention "customers", ask what kind. If they mention "orders", ask about the order lifecycle.
-
----
-
-### Phase 2: Functional Areas (multiSelect + deep dive)
-
-Present functional areas as multiSelect:
-
-```
-Which business functions need to be covered?
-- [ ] Sales & CRM (customers, leads, opportunities, quotes)
-- [ ] Order Management (orders, order lines, fulfillment)
-- [ ] Purchasing (suppliers, purchase orders, receiving)
-- [ ] Inventory (products, stock levels, warehouses)
-- [ ] Projects & Tasks (projects, tasks, milestones)
-- [ ] Time & Expense (time tracking, expenses, billing)
-- [ ] HR & People (employees, onboarding, leave)
-- [ ] Finance (invoices, payments, accounts)
-- [ ] Assets & Equipment (equipment, maintenance, bookings)
-- [ ] Tickets & Support (tickets, SLA, knowledge base)
-- [ ] Custom (describe your specific needs)
-```
-
-**For EACH selected area, ask detailed questions:**
-
-#### If Sales & CRM selected:
-- What's your sales process? (stages/phases)
-- Do you track leads separately from customers?
-- Do you create quotes/proposals?
-- What customer info do you need? (contacts, addresses, segments)
-- How do you track sales activities? (calls, meetings, emails)
-- What makes a customer "won" vs "lost"?
-
-#### If Order Management selected:
-- What triggers an order? (quote approval, direct entry, portal)
-- What's the order lifecycle? (draft → confirmed → shipped → invoiced)
-- Do orders have line items? (products, quantities, prices)
-- Do you need delivery tracking?
-- How do you handle partial deliveries?
-- Any approval workflows needed?
-
-#### If Purchasing selected:
-- How do you decide what to purchase?
-- Do you need supplier comparison/approval?
-- What's the PO lifecycle?
-- Do you track goods receiving?
-- How do you match POs to invoices?
-
-#### If Inventory selected:
-- What do you track? (products, materials, equipment)
-- Multiple warehouses/locations?
-- Do you need stock alerts (min/max levels)?
-- Batch/serial number tracking?
-- How does stock relate to orders/purchasing?
-
-#### If Projects & Tasks selected:
-- What types of projects?
-- How do you track progress? (phases, milestones, % complete)
-- Do projects have budgets?
-- How are tasks assigned?
-- Do you need Gantt/timeline views?
-
-#### If Time & Expense selected:
-- Who tracks time? (employees, contractors)
-- Billable vs non-billable?
-- How do you approve time entries?
-- Expense categories needed?
-- How does this connect to invoicing?
-
-#### If HR & People selected:
-- What employee data do you track?
-- Onboarding checklists needed?
-- Leave/vacation tracking?
-- Performance reviews?
-- Training/certifications?
-
-#### If Finance selected:
-- Invoice from orders or standalone?
-- Payment tracking?
-- Multiple currencies?
-- Integration with accounting software?
-- Recurring invoices/subscriptions?
-
-#### If Assets & Equipment selected:
-- What assets do you track?
-- Maintenance schedules?
-- Booking/reservation system?
-- Depreciation tracking?
-
-#### If Tickets & Support selected:
-- What channels? (email, portal, phone)
-- SLA tracking needed?
-- Escalation rules?
-- Knowledge base?
-- Customer self-service?
-
----
-
-### Phase 3: Workflow Relationships (critical!)
-
-After functional areas, understand how they connect:
-
-**Questions:**
-1. When [X] happens, what should update in [Y]?
-2. Draw me through a typical transaction end-to-end
-3. What workflows need to link to each other?
-4. Are there parent-child relationships? (Order → Order Lines)
-5. What's the "master" data? (Customers used everywhere?)
-
-**Create a mental model:**
-```
-Customer → Orders → Order Lines
-              ↓
-         Deliveries → Invoices → Payments
-```
-
----
-
-### Phase 4: User Experience & Apps
-
-**Questions about apps/portals:**
-1. Do you need a customer-facing portal?
-   - What can customers see? (orders, invoices, tickets)
-   - Can they create things? (orders, tickets)
-   - Login required or public access?
-2. Do you need internal dashboards?
-   - What KPIs matter?
-   - Who sees what? (role-based views)
-3. Mobile needs?
-   - Which roles need mobile access?
-   - What actions on mobile?
-4. Any special UI needs?
-   - Kanban boards?
-   - Calendar views?
-   - Map views?
-
----
-
-### Phase 5: Reporting & Insights
-
-**Questions:**
-1. What reports do you need today? (existing reports to replicate)
-2. What questions do you want to answer?
-   - "How much did we sell this month?"
-   - "Which customers are overdue?"
-   - "What's our project profitability?"
-3. Who needs which reports?
-4. Export formats needed? (PDF, Excel)
-5. Any real-time dashboards?
-6. Public reports for customers?
-
----
-
-### Phase 6: Document Templates (PDF/CSV)
-
-**Questions:**
-1. What documents do you need to generate?
-   - Quotes/Proposals?
-   - Order confirmations?
-   - Invoices?
-   - Delivery notes/Packing slips?
-   - Purchase orders?
-   - Reports/Summaries?
-   - Certificates/Contracts?
-2. For each document type:
-   - What data needs to be on it? (fields, line items)
-   - Company branding? (logo, colors, footer)
-   - Multiple languages?
-   - Any legal text/terms & conditions?
-3. Do you have existing templates to match? (ask for examples)
-4. PDF vs CSV vs both?
-5. Who generates these? (automated or manual trigger)
-6. Any e-signature needs? (SignSpace integration)
-
----
-
-### Phase 6.5: Calculated Fields (Function Fields)
-
-**Discovery questions:**
-1. What values need to be calculated automatically?
-   - Totals? (quantity × price)
-   - Dates? (days until due, age in days)
-   - Status indicators? (overdue → 🔴)
-   - Counts? (how many line items per order?)
-
-2. For each workflow, ask:
-   - What derived data do users need to see?
-   - What would they otherwise calculate manually?
-   - Any fields that depend on other fields?
-
-**Common function field patterns:**
-
-| Type | Example | Formula Pattern |
-|------|---------|-----------------|
-| **Arithmetic** | Total = qty × price | `return qty * price;` |
-| **Date diff** | Days open = today - created | `Math.floor((Date.now() - created) / 86400000)` |
-| **Conditional** | Priority icon = 🔴/🟡/🟢 | `priority === 'high' ? '🔴' : '🟢'` |
-| **Backlink count** | Order count per customer | Count activities linking back |
-| **Aggregation** | Order total from line items | Sum child activity values |
-| **Status** | Overdue if due_date < today | `due_date < Date.now() ? 'Overdue' : 'OK'` |
-
-**Ask for each workflow:**
-- Any totals or sums needed?
-- Any date-based calculations? (days remaining, age)
-- Any conditional formatting or status indicators?
-- Any counts from linked activities?
-
-**Document as:**
-```
-Workflow: Orders
-- total_amount: function (sum of line item totals)
-- days_until_due: function (due_date - today)
-- overdue_indicator: function (🔴 if overdue, else empty)
-```
-
----
-
-### Phase 7: Automations & Integrations
-
-**Phase cascade / activity movers:**
-1. When [parent] moves to [phase], should [children] auto-move?
-   - Order "Shipped" → Order Lines "Shipped"?
-   - Project "Completed" → Tasks "Archived"?
-
-**Scheduled automations:**
-1. Any monthly/weekly jobs?
-   - Auto-invoice subscriptions?
-   - Reminder emails?
-   - Status updates?
-2. Any daily syncs needed?
-
-**External integrations:**
-1. Accounting system? (Netvisor, Procountor, other)
-2. ERP system?
-3. Email/calendar? (Outlook, Gmail)
-4. E-signatures? (SignSpace)
-5. Payment providers?
-6. Any APIs to connect to?
-
-**Notifications:**
-1. Who gets notified when?
-2. Email vs in-app vs both?
-
----
-
-### Phase 8: Summarize Understanding
-
-Before creating anything, summarize back to user:
-
-```
-## Here's what I understood:
-
-**Business:** [company] in [industry] solving [problem]
-**Users:** [roles and counts]
-**Timeline:** [MVP vs full]
-
-**Workflows planned:**
-1. Customers - [fields, phases, function fields]
-2. Orders - [fields, phases, function fields]
-3. ...
-
-**Relationships:**
-- Customers → Orders (one-to-many)
-- Orders → Order Lines (parent-child)
-- ...
-
-**Apps:**
-- Customer Portal (public, view orders/invoices)
-- Sales Dashboard (internal, KPIs)
-
-**Automations:**
-- Order shipped → Lines shipped (activity mover)
-- Monthly invoicing (scheduled)
-- Netvisor sync (integration)
-
-**Did I miss anything? Any corrections?**
-```
-
-**Ask for confirmation before proceeding.**
-
----
-
-### Phase 9: Generate Documentation
-
-Only after user confirms understanding:
-
-#### Create DEVELOPMENT.md
-
-```markdown
-# [Project Name] - Workspace Plan
-
-**Client:** [name]
-**Industry:** [industry]
-**Created:** YYYY-MM-DD
-**Status:** Planning
-
----
-
-## Overview
-[2-3 sentences about the business problem being solved]
-
----
-
-## Users & Roles
-
-| Role | Count | Access Level | Primary Functions |
-|------|-------|--------------|-------------------|
-| [role] | ~X | Admin/Editor/Viewer | [what they do] |
-
----
-
-## Data Model
-
-### Workflows
-
-| Workflow | Purpose | Key Fields | Phases |
-|----------|---------|------------|--------|
-| [name] | [what it stores] | [important fields] | [phase list] |
-
-### Relationships
-
-```
-[ASCII diagram of workflow relationships]
-```
-
----
-
-## Apps & Portals
-
-| App | Type | Users | Purpose |
-|-----|------|-------|---------|
-| [name] | Public/Internal | [roles] | [what it does] |
-
----
-
-## Insights & Reports
-
-| Report | Purpose | Data Source | Public? |
-|--------|---------|-------------|---------|
-| [name] | [what question it answers] | [workflows] | Yes/No |
-
----
-
-## Automations
-
-| Automation | Type | Trigger | Action |
-|------------|------|---------|--------|
-| [name] | Mover/Scheduled/Webhook | [when] | [what happens] |
-
----
-
-## Integrations
-
-| System | Direction | Data |
-|--------|-----------|------|
-| [name] | →/←/↔ Hailer | [what syncs] |
-
----
-
-## Document Templates
-
-| Template | Type | Workflow | Trigger |
-|----------|------|----------|---------|
-| [name] | PDF/CSV | [source workflow] | Manual/Auto |
-
----
-
-## Roadmap
-
-| # | Component | PRD | Priority | Status |
-|---|-----------|-----|----------|--------|
-| 1 | [Workflow: X] | [link] | Must have | Planned |
-| 2 | [Workflow: Y] | [link] | Must have | Planned |
-| 3 | [App: Z] | [link] | Should have | Planned |
-
----
-
-## Open Questions
-- [Any unresolved items from discovery]
-
----
-
-## Technical Decisions
-| Decision | Rationale | Date |
-|----------|-----------|------|
-```
-
-#### Create PRDs for each component
-
-Use the PRD templates from autoplan but with REAL DATA from the discovery:
-- `docs/prd-workflow-*.md` - With actual fields, phases, **function fields**, and nameFunction from answers
-- `docs/prd-app-*.md` - With actual screens, features from answers
-- `docs/prd-insight-*.md` - With actual queries from answers
-- `docs/prd-template-*.md` - For each document template (PDF/CSV)
-- `docs/prd-automation-*.md` - For each automation identified
-
-**Document Template PRD** (`docs/prd-template-[name].md`):
-```markdown
-# PRD: Template - [Name]
-
-**Status:** Planned
-**Created:** YYYY-MM-DD
-**Parent:** [DEVELOPMENT.md](../DEVELOPMENT.md)
-**Type:** PDF / CSV
-
----
-
-## Purpose
-[What document this generates and when it's used]
-
----
-
-## Source Workflow
-- **Workflow:** [which workflow this pulls data from]
-- **Trigger:** Manual / On phase change / Scheduled
-
----
-
-## Document Layout
-
-### Header
-- Company logo: [yes/no, position]
-- Company info: [address, phone, etc.]
-- Document title: [e.g., "Invoice", "Quote"]
-- Document number: [field]
-- Date: [field]
-
-### Recipient Section
-- Customer/Recipient info: [fields]
-
-### Body
-- Line items table: [columns needed]
-- [Any other sections]
-
-### Footer
-- Totals: [subtotal, tax, total fields]
-- Payment terms / Notes: [text]
-- Legal text: [if any]
-
----
-
-## Field Mapping
-
-| Document Field | Hailer Field | Format |
-|----------------|--------------|--------|
-| Invoice # | [field id] | prefix + number |
-| Date | [field id] | DD.MM.YYYY |
-| Customer | [linked field] | name |
-
----
-
-## Implementation Steps
-1. [ ] Create template in workspace/templates.ts
-2. [ ] Map all fields
-3. [ ] Add generation function
-4. [ ] Test with sample data
-5. [ ] Push and verify
-
----
-
-## Verification
-- [ ] PDF generates correctly
-- [ ] All fields populate
-- [ ] Layout matches requirements
-- [ ] Branding correct
-```
-
----
-
-### Phase 10: Report
-
-```
-## Workspace Plan Complete
-
-**Created:**
-- DEVELOPMENT.md (master plan)
-- X workflow PRDs
-- X app PRDs
-- X insight PRDs
-- X template PRDs (PDF/CSV)
-- X automation PRDs
-
-**Total components planned:** X
-
-**Recommended build order:**
-1. Core workflows (master data first) - Helga auto-spawns Alejandro for nameFunction
-2. Transactional workflows - Helga auto-spawns Alejandro for nameFunction + function fields
-3. Cross-workflow function fields (if needed separately)
-4. Insights for apps/reports
-5. Document templates (PDF/CSV)
-6. Apps
-7. Automations (last, need everything else first)
-
-**Next steps:**
-1. Review PRDs with stakeholder
-2. Start building from the first PRD
-```
-
----
-
-## Important Reminders
-
-- **Ask MORE questions than you think necessary**
-- **Never assume** - if unclear, ask
-- **Summarize and confirm** before creating files
-- **Real data** - PRDs should have actual field names, phases, not placeholders
-- **Think relationships** - how workflows connect is often more important than individual fields
-- **Consider scale** - 10 users vs 1000 users affects design