{
  "id": "2026-04-25-platform-methodology-2efb803830",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-25-platform-methodology.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.673Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Platform Methodology — AI-First Project Execution",
  "summary": "Platform Methodology — AI First Project Execution Philosophy Most AI platforms automate existing workflows. This system asks a different question: what does project execution look like when AI is the default worker and humans are the decision layer? The answer: decisions are the only scarce resource. Research, specs, architecture, design, code, tests — agent...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Philosophy",
      "level": 2,
      "body": "Most AI platforms automate existing workflows. This system asks a different question: what does project execution look like when AI is the default worker and humans are the decision layer?\n\nThe answer: **decisions are the only scarce resource.** Research, specs, architecture, design, code, tests — agents produce these at near-zero marginal cost. The only thing that cannot be automated is judgment about what to build and whether it's right.\n\nThe system is optimized to make decisions fast, preserve them permanently (HCS), and propagate them to every downstream agent without loss.\n\n**The core principle:** front-load intelligence, back-end autonomy. By the time Build starts, every agent has enough context to execute without a human. The exec gates are in Design and Plan — not in Build.\n\n---"
    },
    {
      "title": "1. Design",
      "level": 3,
      "body": "*What are we building and how, in general, are we building it?*\n\nNo build work starts until Design is locked. Every downstream agent — Priya, Zara, Vikram, Quinn — must be able to execute with zero ambiguity from Design's output.\n\n**Deliverables:**\n\n| Artifact | Owner | Contains |\n|---|---|---|\n| PRD | Priya | Problem, users, user flows, features in/out, success criteria, constraints |\n| UX Spec | Zara | User flows, component specs, interaction patterns, design system decisions |\n| Architecture | Vikram | Data model, service boundaries, API design, tech stack decisions, security model, external integrations |\n| Decision Log | Mindy | Every significant decision made during Design — what was considered, what was chosen, why |\n| Constraints Doc | Mindy | Things Quinn cannot deviate from. Patterns to follow. Patterns to avoid. |\n\n**Design flow:**\n```\nPriya → PRD\n  ↓\nZara + Vikram in parallel (both informed by PRD)\n  ↓\nCoherence review — do UX and Architecture align?\n  ↓\nExec gate — Justin approves Design\n  ↓\nDesign locked\n```\n\n**Test for \"Design is done\":** Could you hand these documents to any agent and have them execute with zero blocked? If any product or architecture decision is unresolved, Design is not done.\n\n---"
    },
    {
      "title": "2. Plan",
      "level": 3,
      "body": "*What are the phases, what are the tasks, what are the specs, what are the dependencies?*\n\nPlan takes Design's decisions and translates them into an executable task graph. By the end of Plan, every Quinn task is fully contracted. Build starts with zero ambiguity.\n\n**Structure:**\n```\nPhase 1 — [name, goal, scope]\n  Task 1.1 — [full spec: schema, API contract, acceptance criteria, branch, constraints, scope boundary]\n  Task 1.2 — [full spec]\n  depends_on: []\n\nPhase 2 — [name, goal, scope]  \n  Task 2.1 — [full spec]\n  depends_on: []  ← default: parallel\n\nPhase 3 — [name, goal, scope]\n  Task 3.1 — [full spec]\n  depends_on: [phase_2]  ← only when genuinely coupled\n```\n\n**Default is parallel.** Phase specs do not depend on each other unless there is genuine coupling. The Architecture doc is the shared dependency — all Priyas read the same Vikram output.\n\n**Plan flow:**\n```\nMindy creates all phase spec tasks (depends_on: [] by default)\n  ↓\nMultiple Priyas spec all phases in parallel\n  ↓\nCoherence review — do all specs fit together?\n  - Interface contracts connect?\n  - No gaps in PRD coverage?\n  - No conflicting schema ownership?\n  ↓\nExec gate — Justin approves Plan\n  ↓\nMindy creates full task graph on HCS (all phases + tasks with depends_on)\nPlan locked → Build starts\n```\n\n---"
    },
    {
      "title": "3. Build",
      "level": 3,
      "body": "*Execute the plan. Autonomous.*\n\nOnce the Plan is approved, Build runs without exec gates unless something breaks the approved plan. Mindy manages. Engine dispatches. Agents execute.\n\n**Build flow:**\n```\nEngine — sees tasks with satisfied depends_on → dispatches to role queues\nQuinn × N — builds in parallel across independent phases\nLuna — verifies Quinn's output against acceptance criteria (tests in prod)\nVikram — code review on completed phases\nMindy — reads outputs, updates project context, handles blocks, adjusts plan if needed\n  → Exec gate only if plan needs to change\n```\n\n**Mindy's authority in Build:**\n- Adjust task briefs before Quinn starts\n- Re-dispatch blocked tasks with revised spec\n- Split a phase into two if needed\n- Cancel and replace tasks\n- Insert new tasks if gaps are discovered\n- Escalate to exec only when a change exceeds the approved plan\n\n---"
    },
    {
      "title": "Mindy — Product Manager",
      "level": 3,
      "body": "The intelligence layer above Engine. Owns the project from Claire handoff through Build completion. The only agent with a persistent relationship to a project over its lifetime.\n\n**Input:** Project from Claire (post exec approval of project definition)  \n**Output:** Completed project — all phases built, tested, reviewed\n\n**Responsibilities:**\n- Maintains the living project context document\n- Creates and adjusts the task graph\n- Dispatches agents (during Design and Plan phases)\n- Monitors Build autonomously\n- Escalates to exec only when the plan needs to change\n- Reads BezelBrain at session start, writes learnings at session end\n\n**Memory:**\n- *Project memory* — living context doc: decisions, constraints, interface contracts, deferred items\n- *Cross-project memory* — BezelBrain: learnings from prior projects injected at session start\n\n**Always knows:**\n- What stage the project is in\n- Who is working on what right now\n- What comes next (dependency graph)\n- What is blocked and why\n\n---"
    },
    {
      "title": "Claire — Coordinator",
      "level": 3,
      "body": "Company-level intake. Routes projects to Mindy. Never goes deep on a single project.\n\n**Input:** Project brief from Justin  \n**Output:** Project + Intake stage created, exec gate for project definition approval, then PM task dispatched to Mindy\n\n---"
    },
    {
      "title": "Priya — Business Analyst",
      "level": 3,
      "body": "Writes the PRD during Design. Writes all phase specs during Plan.\n\n**Input:** Project brief + Architecture (Vikram) + UX Spec (Zara) + phase scope from Mindy  \n**Output (Design):** PRD — problem, users, flows, features, success criteria  \n**Output (Plan):** Phase spec — schema, API contract, acceptance criteria, scope boundary, constraints, branch name, dependencies\n\n**Contract:** Every spec must have all seven elements before Mindy will dispatch it to Quinn. Incomplete specs go back to Priya.\n\n---"
    },
    {
      "title": "Zara — UX Designer",
      "level": 3,
      "body": "Designs the user experience during Design phase. Parallel with Vikram.\n\n**Input:** PRD from Priya  \n**Output:** UX Spec — user flows, component hierarchy, interaction patterns, design system decisions, component specs\n\n**Contract:** Every component Quinn builds must have a corresponding Zara spec. If a spec is missing, Quinn posts blocked.\n\n---"
    },
    {
      "title": "Vikram — Architect / Reviewer",
      "level": 3,
      "body": "Designs the technical architecture during Design. Reviews code during Build.\n\n**Input (Design):** PRD from Priya  \n**Output (Design):** Architecture — data model, API design, service boundaries, tech decisions, patterns, security model\n\n**Input (Review):** Quinn's completed branch + Priya's acceptance criteria  \n**Output (Review):** Pass or fail with specific line references. No vague feedback.\n\n---"
    },
    {
      "title": "Quinn — Developer",
      "level": 3,
      "body": "Implements exactly what the spec says. Never improvises. Posts blocked immediately if spec has a gap.\n\n**Input:** Priya's phase spec (complete) + Vikram's architecture + Zara's component spec + branch name  \n**Output:** Code on branch + summary of what was built + any deviations from spec\n\n**Task sizing:** One vertical slice — one feature or component, completable in one session, ~100–500 LOC, testable in isolation.\n\n**Contract:** If any of the seven spec elements are missing, post blocked immediately. Do not guess.\n\n---"
    },
    {
      "title": "Luna — QA",
      "level": 3,
      "body": "Verifies Quinn's work against acceptance criteria. Tests in prod.\n\n**Input:** Quinn's completed branch + Priya's acceptance criteria  \n**Output:** Pass or fail per criterion. If fail: exact what broke and why.\n\n**Contract:** If Luna fails a phase, it does not advance. Goes back to Quinn with Luna's specific failure report.\n\n---"
    },
    {
      "title": "Engine — State Machine",
      "level": 3,
      "body": "Walks the dependency graph. Dispatches tasks with satisfied dependencies. No intelligence, no opinion.\n\n**Rule:** If depends_on are all complete → post task.available to role queue. That's it.\n\nMindy modifies the graph. Engine executes it.\n\n---"
    },
    {
      "title": "The Task Spec Contract",
      "level": 2,
      "body": "Every task dispatched to Quinn must contain all seven elements:\n\n| Element | Description |\n|---|---|\n| **Scope** | Exactly what to build. Exactly what NOT to touch. |\n| **Schema** | Exact table names, column names, types. No interpretation. |\n| **API contract** | Method, path, request shape, response shape (if applicable) |\n| **Branch name** | Where the work goes |\n| **Acceptance criteria** | Specific, testable conditions. Luna verifies these. |\n| **Dependencies** | What prior work this builds on and where it lives |\n| **Constraints** | Patterns to follow. Patterns to avoid. From Vikram's architecture. |\n\nMissing any element → task goes back to Priya before Quinn sees it. Mindy gates this.\n\n---"
    },
    {
      "title": "Entity Model",
      "level": 2,
      "body": "```\nProject (HCS topic)\n  └── Stage: Intake\n  └── Stage: Design\n        └── Phase: Discovery (Priya)\n        └── Phase: UX Design (Zara)\n        └── Phase: Architecture (Vikram)\n  └── Stage: Plan\n        └── Phase: Spec Phase 1 (Priya)\n        └── Phase: Spec Phase 2 (Priya)\n        └── Phase: Coherence Review (Vikram)\n  └── Stage: Build\n        └── Phase 1\n              └── Task 1.1 (Quinn)\n              └── Task 1.2 (Quinn)\n        └── Phase 2\n              └── Task 2.1 (Quinn)\n  └── Stage: Launch\n```\n\nEvery entity is an HCS topic. The topic ID is the entity ID everywhere — Supabase PK, depends_on references, audit trail. Decisions are permanent and verifiable.\n\n---"
    },
    {
      "title": "The Goal",
      "level": 2,
      "body": "One exec approval unlocks an entire Build stage. Design and Plan are where Justin is deeply involved — reviewing decisions, not code. Build runs autonomously under Mindy's management. \n\nThe system's output isn't just software — it's a complete record of every decision made, on-chain, tamper-proof, from first brief to shipped product."
    }
  ],
  "html_path": "artifacts/2026-04-25-platform-methodology-2efb803830.html",
  "json_path": "artifacts/2026-04-25-platform-methodology-2efb803830.json"
}