Plan Review Archive
Human-review HTML for design plans and specs. Markdown in
docs/superpowers/specs remains the source of truth.
- Approved 中文版
FieldForce Mobile App Design
FieldForce is the first Flutter app in the Gremlin mobile workspace: an offline-first field-worker client that syncs directly with the existing Go/Postgres/NATS backend via PowerSync — no separate mobile backend. The MVP proves offline-first work cycles, realtime updates when connected, and feature-flagged shift-scoped background location, inside a melos monorepo built for multiple apps from day one.
- Flutter + PowerSync in a melos monorepo with Clean Architecture is selected over React Native, Capacitor, and native Kotlin/Swift; ecosystem cohesion and PowerSync collapsing offline+realtime+migration outweigh losing TS type-sharing (ADR-0037, ADR-0038, ADR-0039).
- PowerSync keeps a local SQLite DB in sync with the existing Postgres; the Go backend stays the single source of truth and write authority, so there is no separate mobile backend and no hand-built WebSocket realtime (ADR-0040).
- Heterogeneous data paths: interactive entities flow through PowerSync buckets, but high-volume append-only background location telemetry routes around PowerSync to a dedicated Go endpoint via the engine's own queue.
- Draft
FieldForce Mobile App Design
FieldForce becomes a real offline-first Flutter mobile app backed by PowerSync, with the Go backend retaining all identity, write authority, conflict resolution, feature flags, and business rules. The grill pass tightened the design around Task as the canonical sync entity, mobile JWT/session source, Phase 1 Shift backend work, PowerSync Cloud Free for development, explicit uploadData endpoint mapping, rejected Task upload UX, and Crashlytics debug context.
- Build FieldForce as a Flutter app with a Melos monorepo and layered core packages matching the backend's hexagonal boundaries.
- Use PowerSync for interactive offline entities; route background location telemetry through flutter_background_geolocation's own queue to a dedicated Go endpoint.
- Keep Go as the write authority: uploadData() is a Flutter-side bridge to existing or entity-specific Go API endpoints, not a generic backend write endpoint.
- Approved 中文版
Digital Worker Phase 1.5 — Self-Service Identity Verification Design
A Phase 1.5 self-service identity verification flow: a verified Gremlin user binds their own external chat identity by DMing a short-lived, single-use code to the worker on Telegram or WhatsApp, and the inbound webhook supplies the authoritative external_user_id so no one copies an opaque platform ID. It replaces admin-by-hand ID sourcing while producing the same verified dw_external_identities row, leaving the Phase 1 security gate unchanged.
- Self-service DM-code challenge replaces admin ID-sourcing; the webhook envelope's external_user_id is the authoritative binding key (ADR-0035).
- v1 self-service is Telegram + WhatsApp only (shared webhook path); Discord self-service is deferred (Gateway-only ingest) and stays admin-assert.
- Codes persist a single code_lookup = HMAC-SHA256(token, server pepper); the raw token is never stored or logged (the second hash column was dropped).
- Approved
Digital Worker Phase 3 — Progress & Risk Digest Design
Phase 3 turns what the Digital Worker already observes into a scheduled Progress & Risk Digest: a per-channel-binding summary of progress, blockers, stale commitments, and follow-ups, delivered via the in-app notifications module and read in the SolidStart panel. It is the lowest-risk next step, composed almost entirely of Phase 1/2 primitives, with no new external-posting surface.
- Phase 3 ships a per-channel-binding Progress & Risk Digest delivered on a configurable schedule plus on-demand, via the in-app notifications module and the SolidStart panel — no posting to external chat channels.
- The digest is computed hybrid: Commitment health (overdue + unclear ownership) comes from structured extracted data with no AI, while Progress, Blockers, and Suggested follow-ups come from one bounded, gated LLM pass.
- Generation mirrors the Fieldforce briefings engine — a system_cron loop plus a new dw_digests store, with one GenerateChannelDigest use case shared by the scheduled and on-demand triggers.
- Approved
Morning Routine Dashboard — Design
Persists the agent-generated daily Morning Routine briefing to Postgres and renders it on a frosted-glass dashboard in the SolidStart panel, with a service-token ingest API, per-user card preferences, a browsable date rail, and a 2-tier feature flag. Telegram is reduced to a 3-line teaser deep-linking to the dashboard.
- The agent keeps generating the report and POSTs structured JSON to a service-token ingest endpoint; a new Go morningroutine module stores and serves it per user.
- One mr_reports row per (user_id, report_date) with JSONB section arrays; re-POSTing the same date is a full replace, never a partial merge.
- Card preferences are a pure display filter — the report always carries full top_stats and the UI shows the enabled subset, with unknown keys appended at the end for discoverability.
- Approved
Digital Worker Phase 2 — Role-Agent Memory And Skill Learning Design
Phase 2 gives each Digital Worker role-agent durable, cross-channel memory and approved, versioned skills, governed by a Learning Inbox and per-agent approval. A 2026-06-06 grilling session trimmed scope to memory + skills + a tone-only Agent Soul, deferring Constructive-Critic critique and KPI signals to Phase 3, and reconciled the design with the shipped Phase-1 schema.
- Phase 2 ships memory + approved skills + Learning Inbox + Agent Soul as a tone/posture knob only; Constructive-Critic critique, process-improvement proposals, and KPI-signal capture move to a Phase 3 spec.
- Memory is owned by the role-agent keyed on (org_id, role_agent_id), shared cross-channel, with policy-over-learning precedence: admin-authored org memory outranks machine-learned role-agent memory (ADR-0032).
- dw_role_agents is an ALTER not a CREATE: keep the shipped name/persona columns and status CHECK('active','disabled'); add soul_id (FK ON DELETE SET NULL), auto_memory_enabled, auto_memory_require_verified, skill_learning_enabled.
- Approved
Digital Worker Team Chat Observer Design
Phase 1 of the Digital Worker product: a Team Chat Observer that integrates directly with WhatsApp, Telegram, and Discord to answer @-mentions in-channel and draft follow-up tasks from observed commitments into a review inbox. It enforces verified identity, per-channel capability policy, a two-tier LLM (local triage then gated remote), and human approval only for consequential actions — with Fieldforce as the sole task-promotion target.
- Direct integration with the WhatsApp, Telegram, and Discord bot APIs — no OpenClaw/Hermes middleware and no Bun bridge; the Go core owns one adapter per provider (ADR-0031).
- Mention-response is a direct, ungated, in-channel reply; only consequential actions (creating/assigning Fieldforce tasks, posting unsolicited messages, scheduling) are human-gated — a safe-executable vs consequential action model (ADR-0029).
- Proactive extraction is two-tier: a local Ollama triage model is an unbilled pre-gate filter, and only a positive hit calls the frontier model through AccessGate (digital_worker:chat_task_extract) — ADR-0028.
- Approved
Fieldforce Phase 5 — AI Risk Intervention Inbox Design
Phase 5 ships a manager-facing AI Risk Intervention Inbox that turns risk detection into actionable draft interventions — assignee nudges, supervisor escalations, or reassignment recommendations. A daily cron pipeline deterministically scores open tasks, persists ranked recommendation rows, and calls the LLM once per org to draft text; page loads serve stored rows only and never trigger LLM calls.
- Risk Intervention Inbox selected over briefing follow-up drafts and task-detail copilot — a proactive, filterable command-center surface backed by persisted ff_risk_interventions rows, not dependent on the Phase 4 morning briefing.
- Deterministic risk scoring (7 rule keys with additive weights: overdue 40, escalated_no_progress 30, repeated_rejection 25, approaching_due 20, no_activity 20, high_priority_idle 15, stalled_checklist 10) ranks candidates; the LLM drafts text only and never re-ranks.
- generation_mode follows ADR-0023 lease-then-LLM: INSERT starts as pending, finalizes to llm or heuristic_only; all reads must filter WHERE generation_mode <> 'pending'.
- Approved
Plan HTML Review App Design
Defines a manual workflow that converts canonical markdown specs into clean HTML review pages via an agentic LLM CLI, served by a dedicated Astro app at apps/plans. The generated HTML is a fast-comprehension layer over the source markdown — not a second source of truth.
- Generation is LLM-driven via a pluggable agentic CLI (claude|codex|gemini); the agent writes JSON + HTML files directly into a temp dir which the script validates and atomically promotes.
- Output shape is a metadata JSON file plus a sibling HTML body fragment; the Astro shell wraps the fragment with chrome (hero, TOC, footer).
- Component vocabulary is closed: body_html may only use classes declared in COMPONENT_CATALOG.md; undeclared classes trigger a suggestion entry in JSON, not a lint pass.
- Approved
Fieldforce Phase 4 — Daily AI Briefings + At-Risk Delays Design
Phase 4 ships a daily AI-generated briefing per org, persisted as ff_briefings records and surfaced as a panel dashboard widget for managers and supervisors. A hybrid pipeline (deterministic heuristics shortlist → single LLM call ranks and reasons) keeps costs at one call per org per day, with full heuristic-only fallback when the AI gate denies or the LLM fails. A new ai_prompt_templates table lets platform admins tune LLM prompts in the DB without code PRs.
- Approach A selected: one org-scope LLM briefing per day with supervisor team-filtered at-risk view — 1 LLM call per org per day, avoiding cost-scaling per-team calls.
- ff_briefings UNIQUE(org_id, briefing_date) provides lease-based idempotency — the losing replica on a UNIQUE conflict skips the org with no LLM spend.
- team_ids denormalized onto ff_briefing_at_risk at generation time for cheap supervisor read filtering with correct snapshot semantics (team membership at generation time).
- Approved
Phase 2 Grill Session — Decisions & Clarifications
Grill session between Wayne and Claude resolving eight open design questions for Fieldforce Phase 2 across Go backend, Astro mobile, and SolidStart panel. Decisions lock in atomic attachment linking, immutable ticked checklist items, upload-on-select for both platforms, and role-only approval access control.
- Activity creation and attachment linking are atomic: if any attachment ID is invalid or already-used, the entire transaction rolls back with 422.
- Ticked checklist items (done: true) are immutable — Go returns 422 if client attempts to modify done/ticked_at/ticked_by.
- Client sends full checklist item objects including existing ticked_at/ticked_by; Go stores as-is with no server-side matching.
- Approved
Fieldforce Phase 3 — Task Creation AI + BYOK Foundation
Phase 3 delivers the first user-facing AI feature in Fieldforce — natural-language task creation on the SolidStart Panel — plus the platform-wide AccessGate that all future AI calls must pass through, covering trial/platform/BYOK/disabled modes, plan caps, AES-GCM encrypted BYOK key management, and a global AI kill-switch. Three deferred Phase 2 AI features (NL task parsing, auto-categorization, AI checklist generation) are delivered as one user action via a single combined-schema LLM call.
- Single combined-schema LLM call per parse-task request replaces two sequential calls, halving latency and aligning token debit with user-visible Generate actions.
- AccessGate.Authorize must run before any prompt construction; every AI call routes through the gate before provider interaction.
- Trial rows are lazy-provisioned on first AI call via INSERT ON CONFLICT DO NOTHING; no org-creation hook couples core org creation to AI module availability.
- Approved +1 variant
Fieldforce Management — Design Spec
Fieldforce Management is a multi-tenant SaaS module for dispatching tasks to field teams, tracking execution, and verifying completion with AI — supporting service, sales, and logistics verticals. Two surfaces (Panel desktop + Mobile Web) share one org-scoped backend, with ClawUI routing all AI calls across Anthropic, OpenAI, Google, and Azure providers with per-org cost tracking and audit logging.
- Two surfaces (Panel desktop + Mobile Web) share one backend; role controls WHAT you see, surface controls HOW you see it — both route through /api/organizations/:org_id/fieldforce/*.
- All AI calls route through ClawUI middleware for cost tracking, audit logging, and multi-provider failover — Anthropic, OpenAI, Google, and Azure OpenAI supported.
- Storage abstraction layer (FieldforceStorageAdapter interface) is defined in Phase 1 so components never call IndexedDB directly — Electric SQL swap in Phase 4 is a single implementation change with zero component changes.
- Approved +1 variant
grm CLI — Auth MVP Design
Design for the grm CLI's authentication commands (login, logout, whoami) using OAuth 2.0 Device Authorization Flow with Better Auth's deviceAuthorization and apiKey plugins. The CLI stores a long-lived API key locally after browser-based sign-in.
- OAuth 2.0 Device Authorization Flow chosen for login — enables both human and AI agent authentication without exposing credentials in the terminal
- Long-lived API key stored locally after device flow completes — agents authenticate once and reuse the key for all subsequent operations
- Thin Cobra abstraction layer (CommandDef/FlagDef/Context/Build) eliminates framework boilerplate while preserving completions and man pages