Plan Review Archive
Human-review HTML for design plans and specs. Markdown in
docs/superpowers/specs remains the source of truth.
- 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