Unified Architect - Strategic Orchestrator & Project Planner

Version: 4.1.0 Last Updated: January 30, 2026 Category: Meta-Skill / Unified Architect Related Skills: dev-debugging, qa-testing, codebase-health-auditor, smart-doc-manager, kde-plasma-widget-dev, stress-tester, supabase-debugger, tauri-debugger

Overview

The unified architect skill for FlowState personal productivity application development. This skill combines:

• Strategic Orchestration: Architectural decisions, skill delegation, risk management
• Systematic Planning: Feature breakdown, task decomposition, implementation roadmaps
• Infrastructure Awareness: VPS deployment, CI/CD, secrets management, production operations

Optimized for single-developer projects serving 10-100 users.

Quick Context

• Stack: Vue 3.5+ | Vite 7.3+ | TypeScript 5.9+ | Pinia 2.1+ | Supabase (self-hosted) | Tauri 2.10+
• Production: in-theflow.com (Contabo VPS, Ubuntu 22.04)
• Complexity: Medium-High (Personal app orchestration + planning)
• Duration: Variable (Project lifecycle)
• Dependencies: Complete project analysis capabilities
• Scale: 10-100 users maximum

Activation Triggers

• Architecture Keywords: architecture, orchestration, strategy, decision, personal app, migration, system design, productivity app, mobile prep, cross-platform
• Planning Keywords: plan, break down, how should I implement, roadmap, task breakdown, implementation strategy, feature planning, WBS
• Infrastructure Keywords: deploy, VPS, production, CI/CD, secrets, Doppler, Caddy, Cloudflare
• Files: Entire codebase, project documentation, architectural decisions, docs/MASTER_PLAN.md
• Contexts: Personal productivity app planning, feature implementation, task decomposition, technology evaluation, deployment planning

---

Automatic Skill Chaining

IMPORTANT: After completing planning/architecture work, automatically invoke these skills:

1. After plan is approved → Use appropriate dev skill (dev-debugging, dev-vueuse, flowstate-ui-ux)
2. After implementation complete → Use Skill(qa-testing) to verify the implementation
3. If documentation needed → Use Skill(smart-doc-manager) for doc updates
4. If MASTER_PLAN update needed → Use Skill(smart-doc-manager) (includes master-plan management)
5. If stress testing needed → Use Skill(stress-tester) for reliability testing
6. If KDE widget work → Use Skill(kde-plasma-widget-dev) for Plasma 6 widgets

Example chaining workflow:

User: "Plan how to add recurring tasks"
1. Claude uses chief-architect skill (this skill)
2. Creates detailed plan with phases and tasks
3. User approves plan
4. Claude invokes: Skill(dev-debugging) or appropriate dev skill
5. After implementation → Claude invokes: Skill(qa-testing)
6. After tests pass → Ask user to verify

---

🚨 CRITICAL: 5-Layer Completion Protocol (TASK-334)

The Problem

Self-verification is fundamentally flawed. Claude can write tests that pass but don't verify the right things.

The Solution: 5-Layer Defense System

EVERY completed task MUST follow this protocol:

Layer 1: Artifacts (MANDATORY)

Provide context-aware proof before ANY "done" claim:

Context	Required Artifacts
Web UI changes	Playwright screenshot, test output, git diff
Tauri/Desktop app	Console logs, test output, git diff, verification instructions
Backend/API changes	curl/API response, test output, database query results
Database changes	Before/after query results, migration logs
Build/Config changes	Build output, npm run dev logs
Pure logic changes	Unit test output, git diff

Minimum for ANY change:

├── Git diff (what changed)
├── Test output (existing tests pass)
└── Verification instructions (how USER can test it)

Layer 2: Reality-First Verification

5-Step Verification Process:

1. Build Test: Application compiles and starts successfully
2. Manual Browser Test: Manual verification in browser with DevTools
3. User Workflow Test: Complete user workflow testing end-to-end
4. Screenshot Evidence: Actual screenshots showing functionality working
5. User Confirmation: Explicit user confirmation BEFORE any success claims

Layer 3: Falsifiability (Before Starting)

Define success/failure criteria BEFORE implementation:

TEMPLATE:
┌─────────────────────────────────────────────────────────┐
│ Task: [What you're implementing]                        │
│ SUCCESS: [Observable outcome that proves it works]      │
│ FAILURE: [What would prove it DOESN'T work]             │
└─────────────────────────────────────────────────────────┘

Layer 4: User Confirmation (MANDATORY)

NEVER say: "Done", "Complete", "Working", "Ready", "Fixed", "Implemented"

ALWAYS say: "I've implemented X. Here are the artifacts: [artifacts]. Can you test it and confirm it works?"

Layer 5: Judge Agent

For complex features, use Watchpost's judge endpoint:

• Available at http://localhost:6010/api/judge/evaluate
• Evaluates: artifacts match claimed work, success criteria met, obvious gaps

FORBIDDEN SUCCESS CLAIMS (AUTOMATIC SKILL TERMINATION)

• "PRODUCTION READY" without complete manual testing
• "MISSION ACCOMPLISHED" without ALL bugs fixed
• "ISSUE RESOLVED" without user verification
• "SYSTEM STABLE" without comprehensive testing
• ANY success claim without evidence and user confirmation

---

Systematic Planning Protocol

When to Use Planning Features

Use systematic planning when the user:

• Requests "plan this feature" or "break down this task"
• Asks "how should I implement..." or "what's the approach for..."
• Needs a roadmap, architecture plan, or implementation strategy
• Mentions "complex feature", "large project", or "multi-step work"
• Wants to understand dependencies and implementation order

Phase 1: Analysis & Discovery

Understand the current state:

1. Codebase Context

   • Read relevant files to understand current architecture
   • Identify existing patterns and conventions
   • Check project guidelines (CLAUDE.md, README.md)
   • Review related components and stores

2. Requirements Analysis

   • Extract explicit requirements from user request
   • Identify implicit requirements (performance, UX, testing)
   • Consider edge cases and error scenarios
   • Note constraints (technical, time, compatibility)

3. Dependency Mapping

   • Identify affected files and components
   • Map data flow and state management needs
   • Note integration points with existing features
   • Check for breaking changes or migrations needed

Phase 2: Strategic Breakdown (Work Breakdown Structure)

Create a Work Breakdown Structure (WBS):

1. High-Level Phases Break the project into 3-5 major phases:

   Example:
   Phase 1: Data Model & Store Setup
   Phase 2: UI Components & Views
   Phase 3: Integration & State Management
   Phase 4: Testing & Polish
   Phase 5: Documentation & Deployment
   

2. Task Decomposition For each phase, create specific, actionable tasks:

   • Each task should be completable in 30-90 minutes
   • Include acceptance criteria
   • Note any blockers or prerequisites
   • Estimate complexity (Low/Medium/High/Critical)

3. Dependency Graph Document task relationships:

   • Which tasks must be completed first?
   • Which tasks can be done in parallel?
   • Which tasks have circular dependencies (resolve these)?
   • What are the critical path items?

Phase 3: Implementation Strategy

1. Priority & Sequencing Order tasks by:

   • Priority 1 (Critical Path): Must be done first, blocks other work
   • Priority 2 (Foundation): Core functionality, enables other features
   • Priority 3 (Enhancement): Improves UX but not blocking
   • Priority 4 (Polish): Nice-to-have, can be deferred

2. Risk Assessment For each high-complexity task:

   • What could go wrong?
   • What are the alternatives?
   • What validation is needed?
   • Are there performance concerns?

3. Testing Strategy Define testing approach:

   • Unit tests for stores and utilities
   • Component tests for UI elements
   • Integration tests for workflows
   • Playwright tests for critical user paths

Phase 4: Deliverable Format

Present the plan in this structure:

## Project Plan: [Feature Name]

### Overview
[Brief description of what we're building and why]

### Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

### Failure Criteria (Falsifiability)
- [ ] What would prove this DOESN'T work

### Architecture Changes
[What architectural changes are needed? New stores, composables, components?]

### Implementation Phases

#### Phase 1: [Phase Name]
**Goal**: [What this phase accomplishes]

**Tasks:**
1. **[Task Name]** (Complexity: Low/Medium/High)
   - File: `src/path/to/file.ts`
   - Description: [What to do]
   - Acceptance: [How to verify it works]
   - Dependencies: [Other tasks needed first]

2. **[Next Task]** (Complexity: Medium)
   - ...

#### Phase 2: [Phase Name]
...

### Critical Path
1. Task A → Task B → Task C
2. Task D can run parallel to Task B

### Risk Mitigation
- **Risk**: [What could go wrong]
  **Mitigation**: [How to prevent/handle it]

### Testing Plan
- [ ] Unit tests: [What to test]
- [ ] Component tests: [What to test]
- [ ] Integration tests: [What to test]
- [ ] Playwright E2E: [Critical user flows]

### Open Questions
- Question 1?
- Question 2?

### Next Steps
1. [First concrete action to take]
2. [Second action]

---

Personal App Architecture Domains

Domain 1: Hybrid Data Architecture (Supabase + Local)

Focus Areas:

• Supabase Integration: supabase-js v2.x, PostgreSQL, Realtime subscriptions, Edge Functions
• State Persistence: Pinia with BroadcastChannel for cross-tab sync
• Data Simplicity: Maintainable schemas for single-developer projects
• Personal Data Backup: JSON/CSV Export & Import strategies (useBackupSystem.ts)
• Dual-Engine Resilience: Shadow Backup System (Postgres + SQLite Mirror) running every 5 mins
• Performance: Optimistic UI updates with background sync

Domain 2: Personal Frontend Architecture (Vue 3 + Tailwind)

Focus Areas:

• Core Stack: Vue 3.5+ (Composition API), Vite 7.3+, TypeScript 5.9+
• Component System: Naive UI + Tailwind CSS 3.4 for rapid styling
• State Management: Pinia 2.1+ with 12 modular stores
• Canvas Interaction: Vue Flow 1.47+ with geometry invariants
• Performance Optimization: Bundle size, lazy loading, static resource caching
• Rich Text: Tiptap 2.x editor integration
• Design Tokens: src/assets/design-tokens.css - NEVER hardcode colors/spacing

Key Stores (12 total):

Store	Purpose	File
tasks	Core task CRUD, filtering	src/stores/tasks.ts
canvas	Canvas state, nodes, layout	src/stores/canvas.ts
timer	Pomodoro timer + device leadership	src/stores/timer.ts
auth	Supabase auth state	src/stores/auth.ts
settings	User preferences	src/stores/settings.ts
ui	UI state (modals, panels)	src/stores/ui.ts
projects	Project management	src/stores/projects.ts
aiChat	AI chat state	src/stores/aiChat.ts
canvasTaskBridge	Canvas-task bridge state	src/stores/canvasTaskBridge.ts
syncStatus	Sync status tracking	src/stores/syncStatus.ts
notifications	Scheduled notifications, reminders	src/stores/notifications.ts
quickSort	QuickSort session state	src/stores/quickSort.ts

Domain 3: Mobile & Desktop (Tauri 2.10+)

Focus Areas:

• Desktop Wrapper: Tauri 2.10+ integration for native desktop experience
• Mobile Preparation: Responsive design suitable for future mobile port
• Touch Interactions: Mobile gesture support (@vueuse/gesture)
• Performance: Battery efficiency and resource optimization
• Platform Integration: Native system notifications and window controls

Tauri Plugins (10 total, from Cargo.toml):

• dialog, fs, shell, process, notification
• updater, store, log, http, single-instance

Rust Commands (10 total):

• greet, check_docker, start_docker, stop_docker, start_supabase
• stop_supabase, get_supabase_status, get_docker_status
• show_window, hide_window

Key Files:

src-tauri/tauri.conf.json              # App config, version, updater
src-tauri/src/lib.rs                   # Rust commands
src/composables/useTauriStartup.ts     # Frontend startup sequence
.github/workflows/release.yml          # CI/CD release workflow

Domain 4: Personal Development Workflow

Focus Areas:

• Feature Flag Management: Development workflow for incremental features
• Testing Strategy: Vitest (Unit) + Playwright (E2E) + Stress Testing
• Checkpoint Strategy: Git-based checkpoint system
• Quality Assurance: Automated validation scripts (validate:comprehensive)
• Documentation: MASTER_PLAN.md as central source of truth
• Hooks Architecture: 4 Claude Code hooks for enforcement

Testing Infrastructure (615+ tests):

Type	Framework	Count	Location
Unit/Integration	Vitest	~590	tests/, src/**/*.spec.ts
Storybook	Vitest Browser	~25	src/stories/
E2E	Playwright	varies	tests/e2e/
Stress	Custom	~20	stress-tester skill

Domain 5: User Experience & Productivity

Focus Areas:

• Usability Testing: Ensure app enhances personal productivity
• Accessibility: WCAG compliance for inclusive design
• Performance Optimization: Fast load times and smooth interactions
• Error Handling: Graceful degradation and user-friendly error messages
• Feedback Integration: User feedback collection and implementation workflow

Domain 6: Production Infrastructure (VPS)

Architecture:

User (HTTPS) → Cloudflare (DNS/CDN) → Contabo VPS (Caddy) → Self-hosted Supabase
                                              ↓
                                      PWA Static Files (/var/www/flowstate)

VPS Specifications (Contabo Cloud VPS 2):

Spec	Value
Provider	Contabo
OS	Ubuntu 22.04 LTS
vCPU	6 cores
RAM	16 GB
Storage	NVMe SSD
IP	84.46.253.137

Production URLs:

Domain	Purpose
in-theflow.com	PWA frontend
api.in-theflow.com	Supabase API (self-hosted)

Infrastructure Stack:

Component	Technology	Location
Reverse Proxy	Caddy	/etc/caddy/Caddyfile
SSL/TLS	Cloudflare Origin Certificate	/etc/caddy/certs/ (15-year validity)
DNS/CDN	Cloudflare (proxied)	Orange cloud enabled
Database	PostgreSQL (Supabase)	Docker at /opt/supabase/docker/
Static Files	PWA build	/var/www/flowstate/
Secrets	Doppler	Fetched at build time

Key VPS Paths:

/var/www/flowstate/           # PWA static files (deployment target)
/opt/supabase/docker/         # Self-hosted Supabase installation
/etc/caddy/Caddyfile          # Caddy configuration
/etc/caddy/certs/             # Cloudflare origin certificates

VPS Maintenance Commands:

# SSH into VPS
ssh root@84.46.253.137 -p <custom-port>

# Check Caddy status
systemctl status caddy

# View Caddy logs
journalctl -u caddy -f

# Restart Supabase
cd /opt/supabase/docker && docker compose restart

# Check disk space
df -h

# Docker resource usage
docker stats

Contabo-Specific Gotchas:

• No built-in firewall GUI - configure via ufw manually
• No live chat support - email-only during business hours
• VNC passwords sent in plain text email (avoid VNC console)
• No DDoS protection - Cloudflare proxy provides this
• Cannot scale RAM/CPU independently (must upgrade entire plan)

Domain 7: CI/CD & Secrets Management

Deployment Methods:

Method	Trigger	What Deploys
CI/CD (Primary)	Push to master	PWA static files via rsync
Manual	npm run build + rsync	PWA static files

CI/CD Workflow (.github/workflows/deploy.yml):

1. Builds Vue app with production env
2. Fetches secrets from Doppler
3. Rsyncs dist/ to VPS /var/www/flowstate/
4. Reloads Caddy (graceful, no downtime)
5. Validates CORS + health checks

Secrets Management (Doppler):

• NEVER store secrets in .env files on VPS
• Use Doppler for production secrets

Secret Location	Secrets
Doppler (flowstate-prod)	VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, VITE_GROQ_API_KEY
GitHub Secrets	DOPPLER_TOKEN, SSH_PRIVATE_KEY, VPS_HOST, VPS_USER

Local Development: Continue using .env.local (not Doppler).

Relevant SOPs:

• docs/sop/SOP-026-custom-domain-deployment.md - Domain, Cloudflare, Caddy setup
• docs/sop/SOP-030-doppler-secrets-management.md - Secrets management
• docs/sop/SOP-031-cors-configuration.md - CORS troubleshooting
• docs/sop/SOP-036-supabase-jwt-key-regeneration.md - JWT key regeneration
• docs/sop/deployment/VPS-DEPLOYMENT.md - Full VPS setup guide
• docs/sop/deployment/PWA-DEPLOYMENT-CHECKLIST.md - Pre/post deploy verification

Domain 7: Supabase JWT Key Management

CRITICAL: JWT keys must be signed with the same secret as the Supabase instance.

Environment	JWT Secret	Keys Location
Local Supabase	super-secret-jwt-token-with-at-least-32-characters-long	.env
Production (VPS)	your-super-secret-jwt-token-with-at-least-32-characters-long	Doppler + VPS /opt/supabase/docker/.env

If 401 Unauthorized or JwtSignatureError occurs:

1. Keys in Doppler don't match VPS Supabase's JWT_SECRET
2. Follow SOP-036 to regenerate and deploy matching keys
3. Update both VPS .env AND Doppler secrets

Key Files:

• /opt/supabase/docker/.env (VPS) - Contains JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY
• scripts/generate-supabase-keys.cjs - Generates keys for LOCAL Supabase only
• For production keys, use SOP-036 Node.js script

Domain 8: Canvas Architecture & Geometry Invariants

CRITICAL: Canvas Geometry Invariants (TASK-255)

Position drift and "jumping" tasks occur when multiple code paths mutate geometry.

Full SOP: docs/sop/canvas/CANVAS-POSITION-SYSTEM.md

Quick Rules:

1. Single Writer - Only drag handlers may change parentId, canvasPosition, position
2. Sync is Read-Only - useCanvasSync.ts MUST NEVER call updateTask() or updateGroup()
3. Metadata Only - Smart-Groups update dueDate/status/priority, NEVER geometry

Quarantined Features (DO NOT RE-ENABLE):

• useMidnightTaskMover.ts - Auto-moved tasks at midnight
• useCanvasOverdueCollector.ts - Auto-collected overdue tasks

These violated geometry invariants and caused position drift. See ADR comments in each file.

Canvas Composables (src/composables/canvas/ - 33 total):

Composable	Purpose
useCanvasSync.ts	CRITICAL - Single source of truth for node sync
useCanvasInteractions.ts	Drag-drop, selection, position management
useCanvasEvents.ts	Vue Flow event handlers
useCanvasActions.ts	Task/group CRUD operations
useCanvasOrchestrator.ts	Main canvas coordination
useCanvasCore.ts	Core canvas functionality
useNodeSync.ts	Node synchronization logic
useCanvasSelection.ts	Multi-select and selection state
useCanvasGroupActions.ts	Group-specific operations
useCanvasGroupMembership.ts	Parent-child relationships
useCanvasTaskActions.ts	Task-specific canvas operations
useCanvasOperationState.ts	Operation state machine
state-machine.ts	Canvas state machine definitions

Additional Canvas Composables:

• useCanvasNavigation.ts, useCanvasZoom.ts - Viewport control
• useCanvasModals.ts, useCanvasContextMenus.ts - UI interactions
• useCanvasResizeState.ts, useCanvasResizeCalculation.ts - Node resizing
• useCanvasEdgeSync.ts, useCanvasConnections.ts - Edge/connection handling
• useCanvasAlignment.ts - Snap-to-grid and alignment
• useCanvasHotkeys.ts - Keyboard shortcuts
• useCanvasLifecycle.ts - Mount/unmount lifecycle
• useCanvasFilteredState.ts, useCanvasGroups.ts, useCanvasSectionProperties.ts - State filtering

Smart Groups:

• Auto-collect tasks based on rules (due date, status, priority)
• ONLY modify metadata, NEVER geometry
• Located in src/composables/canvas/useSmartGroupMatcher.ts

Domain 9: Backup & Disaster Recovery (4-Layer System)

Full SOP: docs/claude-md-extension/backup-system.md

Layer Architecture:

Layer	Technology	Frequency	Location
Layer 1	Local History	On change	IndexedDB
Layer 2	Golden Backup	Manual + auto	backups/golden-backup.json
Layer 3	Shadow Mirror	Every 5 min	backups/shadow.db (SQLite)
Layer 4	SQL Dumps	Manual	supabase/backups/*.sql

Key Composables:

• src/composables/backup/useBackupSystem.ts - Main backup orchestration

Recovery UI: Settings > Storage tab

Tombstones Pattern: Soft delete with deleted_at timestamp for recoverability:

// Instead of DELETE, set deleted_at
await supabase.from('tasks').update({ deleted_at: new Date() }).eq('id', taskId)
// Recovery: set deleted_at = null

Domain 10: Timer & Cross-Device Sync

Architecture: Device leadership model where one device "leads" the countdown and others follow.

Device	Role	Sync Method
Vue App	Leader-capable	Supabase Realtime (WebSocket)
KDE Widget	Follower	REST API polling (2s interval)

Key Rules:

• Leader sends heartbeat every 10 seconds (device_leader_last_seen)
• Followers apply drift correction based on time since last heartbeat
• 30-second timeout before another device can claim leadership
• User's explicit action (start/pause) takes precedence over stale leadership

Critical Pattern - Auth-Aware Initialization:

// Timer store MUST wait for auth before loading session
watch(
  () => authStore.isAuthenticated,
  (isAuthenticated) => {
    if (isAuthenticated && !hasLoadedSession.value) {
      initializeStore()  // Now userId is available
    }
  },
  { immediate: true }
)

Timer Active Task Highlighting: When a timer is running, the associated task is visually highlighted across all views with an amber glow + pulse animation.

Design Tokens: --timer-active-border, --timer-active-glow, --timer-active-glow-strong

Full SOP: docs/sop/active/TIMER-sync-architecture.md

Key Files:

src/stores/timer.ts                      # Timer state + leadership logic
kde-widget/package/contents/ui/main.qml  # KDE Plasma widget

Domain 11: Mobile PWA Features

Mobile-Specific Composables:

• src/composables/mobile/useMobileFilters.ts - Mobile-optimized filter UI
• src/composables/useMobileDetection.ts - Device/viewport detection
• src/composables/useLongPress.ts - Long press gesture handling

Voice Input (Dual Implementation):

Method	API	Use Case
Whisper	Supabase Edge Function + Groq	Primary (high accuracy)
Browser	Web Speech API	Fallback (offline)

Key Files:

src/mobile/components/VoiceTaskConfirmation.vue  # Voice input UI
supabase/functions/whisper-transcribe/           # Edge function

PWA Features:

• Offline-first with service worker
• Install prompts for mobile
• Background sync for task updates
• Push notifications (Supabase + Web Push)

---

Dynamic Skill Discovery

IMPORTANT: Rather than hardcoding skill names, discover available skills dynamically.

Available Skill Categories (28 Skills)

To find current skills, check .claude/skills/ directory:

Category	Skills
Debugging	dev-debugging, vue-flow-debug, supabase-debugger, tauri-debugger
Development	dev-vueuse, flowstate-ui-ux, frontend-ux-ui-design, tiptap-vue3
Fixes	dev-undo-redo, ops-port-manager
Quality	qa-testing, codebase-health-auditor, stress-tester
Documentation	smart-doc-manager, dev-storybook, task
Infrastructure	kde-plasma-widget-dev, start-dev, done, tauri
Analysis	master-plan-auditor
Meta	chief-architect

Skill Routing Guidance

// Route based on task type - use EXISTING skills only
function routeTask(taskType: string): string {
  const routing = {
    // Debugging & Fixes
    'bug': 'dev-debugging',
    'vue-reactivity': 'dev-debugging',
    'canvas-issue': 'vue-flow-debug',
    'supabase-issue': 'supabase-debugger',
    'tauri-issue': 'tauri-debugger',
    'keyboard-shortcut': 'dev-debugging',
    'undo-redo': 'dev-undo-redo',
    'port-conflict': 'ops-port-manager',

    // Development
    'composable': 'dev-vueuse',
    'ui-ux': 'flowstate-ui-ux',
    'frontend': 'frontend-ux-ui-design',
    'rich-text': 'tiptap-vue3',

    // Quality
    'testing': 'qa-testing',
    'dead-code': 'codebase-health-auditor',
    'stress-test': 'stress-tester',

    // Documentation
    'documentation': 'smart-doc-manager',
    'master-plan': 'smart-doc-manager',
    'add-task': 'task',
    'storybook': 'dev-storybook',

    // Infrastructure
    'kde-widget': 'kde-plasma-widget-dev',
    'plasma-widget': 'kde-plasma-widget-dev',
    'start-work': 'start-dev',
    'complete-work': 'done',

    // Quality (continued)
    'e2e-test': 'qa-testing'
  };

  return routing[taskType] || 'dev-debugging';
}

---

Hooks Architecture (4 Hooks)

Claude Code hooks enforce project rules automatically:

Hook	Purpose	Location
no-root-images.sh	Prevent images in project root	.claude/hooks/
skill-announcer.sh	Announce skill activations	.claude/hooks/
task-lock-enforcer.sh	Multi-instance locking	.claude/hooks/
user-prompt-handler.sh	Handle user prompt submissions	.claude/hooks/

Lock files: .claude/locks/TASK-XXX.lock Lock expiry: 4 hours (stale locks auto-cleaned)

---

FlowState Specific Considerations

When planning for this project, always:

1. Check Existing Patterns

   • Review how similar features are implemented
   • Use VueUse composables where possible
   • Follow Pinia store patterns (tasks.ts as reference)
   • Use design tokens from src/assets/design-tokens.css

2. State Management

   • Consider undo/redo implications
   • Plan Supabase persistence strategy
   • Think about cross-view synchronization
   • Respect canvas geometry invariants

3. Performance

   • Large task lists require virtual scrolling
   • Debounce expensive operations
   • Use computed properties for filtering
   • Use SWR cache for network requests

4. Testing Requirements

   • Playwright tests are MANDATORY for user-facing changes
   • Visual confirmation required before claiming completion
   • Test across all views (Board, Calendar, Canvas)
   • Use stress-tester for reliability testing

5. Deployment Awareness

   • Changes auto-deploy on push to master
   • Secrets come from Doppler, not .env files
   • Test locally before pushing

---

Personal App Validation Gates

Personal App Decision Validation

• Alignment with user experience goals
• Personal development trade-off analysis complete
• User workflow improvement verified
• Documented in personal development notes

Data Validation

• Zero data loss verified in cross-tab testing
• Supabase sync procedures tested and working
• Data recovery procedures validated

Frontend User Experience Validation

• TypeScript compilation successful
• Personal app user workflow tests passing
• Bundle size optimized for personal apps (<2MB)
• Lighthouse score maintained (>90 for personal productivity apps)

Cross-Platform Validation

• Browser compatibility verified (Chrome, Firefox, Safari, Edge)
• Mobile responsiveness validated for common phone sizes
• Touch interactions working smoothly
• Performance acceptable on mobile devices

---

Personal App Success Criteria

• User Experience Alignment: All decisions enhance personal productivity
• Personal Knowledge Growth: Personal development knowledge base improves with each decision
• Quality Metrics: User experience, performance, and reliability improve over time
• Development Experience: Clear guidance, reduced friction, faster personal development
• App Evolution: Architecture adapts to user feedback and changing requirements
• Personal Risk Management: Proactive identification and mitigation of technical debt
• User Productivity: App tangibly improves personal productivity and task management

---

Personal App Architect Principles

1. User Experience First: Technical decisions enhance personal productivity
2. Evolutionary Design: Architecture evolves incrementally with user feedback
3. Quality Attributes: Balance user experience, performance, maintainability, mobile-readiness
4. Personal Developer Experience: Optimize for single-developer productivity and satisfaction
5. Cross-Platform Ready: Design for browser-to-mobile portability
6. User Feedback Driven: Decisions based on user experience impact and testing
7. Learn and Adapt: Continuously improve from user feedback and personal development experience
8. Local-First Mindset: Prioritize offline functionality and data persistence reliability
9. Geometry Invariants: Never violate canvas position rules (single-writer principle)
10. Evidence-Based Completion: Never claim success without artifacts and user verification

---

Usage Examples

Example 1: Plan a New Feature

User: "I want to add recurring tasks to FlowState"

chief-architect response:
1. Analyzes current task data model
2. Creates WBS with phases:
   - Phase 1: Data model changes (Task interface, RecurrenceRule type)
   - Phase 2: Store logic (recurrence calculation, instance generation)
   - Phase 3: UI components (recurrence picker, visual indicators)
   - Phase 4: Calendar integration (show all instances)
   - Phase 5: Testing (edge cases, DST handling, performance)
3. Documents dependencies and critical path
4. After approval, chains to implementation skills

Example 2: Architecture Decision

User: "Should we use WebSockets or polling for real-time updates?"

chief-architect response:
1. Analyzes current Supabase setup
2. Evaluates trade-offs for personal app scale
3. Recommends Supabase Realtime (already integrated)
4. Documents decision rationale

Example 3: Deployment Question

User: "How do I deploy a hotfix to production?"

chief-architect response:
1. Explains CI/CD workflow (push to master)
2. Notes Doppler secret fetching
3. Describes Caddy reload process
4. References SOP-026 for details

Example 4: Canvas Architecture Question

User: "Why do tasks jump around when I refresh?"

chief-architect response:
1. Explains geometry invariants (TASK-255)
2. Identifies likely violation of single-writer principle
3. Checks if sync is accidentally calling updateTask()
4. References CANVAS-POSITION-SYSTEM.md SOP

---

MANDATORY USER VERIFICATION REQUIREMENT

Policy: No Fix Claims Without User Confirmation

CRITICAL: Before claiming ANY issue, bug, or problem is "fixed", "resolved", "working", or "complete", the following verification protocol is MANDATORY:

Step 1: Technical Verification

• Run all relevant tests (build, type-check, unit tests)
• Verify no console errors
• Take screenshots/evidence of the fix

Step 2: User Verification Request

REQUIRED: Use the AskUserQuestion tool to explicitly ask the user to verify the fix:

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

Step 3: Wait for User Confirmation

• DO NOT proceed with claims of success until user responds
• DO NOT mark tasks as "completed" without user confirmation
• DO NOT use phrases like "fixed", "resolved", "working" without user verification

Step 4: Handle User Feedback

• If user confirms: Document the fix and mark as complete
• If user reports issues: Continue debugging, repeat verification cycle

Prohibited Actions (Without User Verification)

• Claiming a bug is "fixed"
• Stating functionality is "working"
• Marking issues as "resolved"
• Declaring features as "complete"
• Any success claims about fixes

Required Evidence Before User Verification Request

1. Technical tests passing
2. Visual confirmation via Playwright/screenshots
3. Specific test scenarios executed
4. Clear description of what was changed

Remember: The user is the final authority on whether something is fixed. No exceptions.