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.9+
• 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

   ,

   dev-implement-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:

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 Dev-Maestro'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 +

  pinia-shared-state

  (Native 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
• SWR Cache Pattern: Stale-While-Revalidate with

  src/composables/useSWRCache.ts

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 3.0+ with 10 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 (10 total):

tasks

src/stores/tasks.ts

canvas

src/stores/canvas.ts

timer

src/stores/timer.ts

auth

src/stores/auth.ts

settings

src/stores/settings.ts

ui

src/stores/ui.ts

projects

src/stores/projects.ts

theme

src/stores/theme.ts

notifications

src/stores/notifications.ts

quickSort

src/stores/quickSort.ts

Domain 3: Mobile & Desktop (Tauri 2.9+)

Focus Areas:

• Desktop Wrapper: Tauri 2.9+ 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 (

  scripts/checkpoint-with-backup.sh

  )
• Quality Assurance: Automated validation scripts (

  validate:comprehensive

  )
• Documentation:

  MASTER_PLAN.md

  as central source of truth
• Hooks Architecture: 14 Claude Code hooks for enforcement

Testing Infrastructure (615+ tests):

tests/

src/**/*.spec.ts

src/stories/

tests/e2e/

stress-tester

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):

Production URLs:

in-theflow.com

api.in-theflow.com

Infrastructure Stack:

/etc/caddy/Caddyfile

/etc/caddy/certs/

/opt/supabase/docker/

/var/www/flowstate/

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:

npm run build

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

flowstate-prod

VITE_SUPABASE_URL

VITE_SUPABASE_ANON_KEY

VITE_GROQ_API_KEY

DOPPLER_TOKEN

SSH_PRIVATE_KEY

VPS_HOST

VPS_USER

Local Development: Continue using

.env.local

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.

super-secret-jwt-token-with-at-least-32-characters-long

.env

your-super-secret-jwt-token-with-at-least-32-characters-long

/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/

useCanvasSync.ts

useCanvasInteractions.ts

useCanvasEvents.ts

useCanvasActions.ts

useCanvasOrchestrator.ts

useCanvasCore.ts

useNodeSync.ts

useCanvasSelection.ts

useCanvasGroupActions.ts

useCanvasGroupMembership.ts

useCanvasTaskActions.ts

useCanvasOperationState.ts

state-machine.ts

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/useSmartGroups.ts

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

Full SOP:

docs/claude-md-extension/backup-system.md

Layer Architecture:

backups/golden-backup.json

backups/shadow.db

supabase/backups/*.sql

Key Composables:

• src/composables/useBackupSystem.ts

  - Main backup orchestration

• src/composables/useShadowBackup.ts

  - SQLite mirror logic

• src/composables/useLocalHistory.ts

  - IndexedDB history

Recovery UI: Settings > Storage tab

Tombstones Pattern: Soft delete with

deleted_at

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

SWR Cache Pattern (

src/composables/useSWRCache.ts

• Stale-While-Revalidate for optimal UX
• Returns cached data immediately, revalidates in background
• Automatic cache invalidation on mutations

Domain 10: Timer & Cross-Device Sync

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

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):

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/

dev-debugging

vue-flow-debug

supabase-debugger

tauri-debugger

dev-vueuse

dev-implement-ui-ux

frontend-design

tiptap-vue3

dev-undo-redo

ops-port-manager

qa-testing

codebase-health-auditor

stress-tester

smart-doc-manager

dev-storybook

task

kde-plasma-widget-dev

start-dev

done

master-plan-auditor

skill-creator-doctor

chief-architect

feature-creator

design-system-migrator

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': 'dev-implement-ui-ux',
    'frontend': 'frontend-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 (14 Hooks)

Claude Code hooks enforce project rules automatically:

destructive-command-blocker.sh

.claude/hooks/

task-lock-enforcer.sh

.claude/hooks/

completion-validator.sh

.claude/hooks/

atomic-task-enforcer.sh

.claude/hooks/

Lock files:

.claude/locks/TASK-XXX.lock

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

"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.