godpowers 0.15.7 → 0.15.9

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to Godpowers will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.15.9] - 2026-05-11
+
+Early design planning release. Lets UI and product-experience projects shape
+DESIGN.md before architecture.
+
+### Changed
+- `/god-init` now records UI and product-experience signals in
+  `.godpowers/prep/INITIAL-FINDINGS.md`.
+- `/god-prd`, `/god-next`, and `/god-mode` now route to `/god-design` after
+  PRD and before `/god-arch` when UI or product-experience signals are found.
+- `/god-design` now requires PRD, not stack, so DESIGN.md can inform
+  architecture, roadmap, and stack instead of arriving after them.
+- Architecture, roadmap, and stack routing and agents now read DESIGN.md and
+  PRODUCT.md when present.
+
+## [0.15.8] - 2026-05-11
+
+Init preparation release. Documents what Godpowers found before PRD, next-step
+routing, or the full autonomous arc starts.
+
+### Added
+- `/god-init` now always creates `.godpowers/prep/INITIAL-FINDINGS.md` with
+  codebase shape, framework and tooling signals, tests, CI, docs, AI-tool
+  instructions, detected methodology systems, risks, and the suggested next
+  command rationale.
+- `/god-prd`, `/god-next`, and `/god-mode` now read initial findings before
+  choosing or producing the next Godpowers artifact.
+- Architecture, roadmap, and stack agents now read initial findings alongside
+  imported planning context when present.
+
+### Documented
+- The full recent init preparation flow is now documented together:
+  automatic AI-tool context for explicit `god init`, quiet context writes,
+  GSD / Superpowers / BMAD import into `IMPORTED-CONTEXT.md`, and direct
+  Godpowers repo findings in `INITIAL-FINDINGS.md`.
+
 ## [0.15.7] - 2026-05-11
 
 Planning import release. Lets `/god-init` preserve useful context from nearby

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/aihxp/godpowers/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/godpowers/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.15.7-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.15.9-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/godpowers.svg)](https://www.npmjs.com/package/godpowers)
 
 **Ship fast. Ship right. Ship everything. Ship accountably.**
@@ -75,6 +75,12 @@ PRD complete: .godpowers/prd/PRD.md
 Suggested next: /god-arch (design the architecture)
 ```
 
+For UI or product-experience projects, PRD can route to design first:
+
+```
+Suggested next: /god-design (shape product experience)
+```
+
 You can also ask any time:
 
 ```
@@ -164,7 +170,7 @@ Skill updates:   PROGRESS.md
 | Tier | Sub-steps | Specialists |
 |------|-----------|-------------|
 | 0: Orchestration | mode detection, scale, progress | god-orchestrator |
-| 1: Planning | PRD, ARCH, ROADMAP, STACK | god-pm, god-architect, god-roadmapper, god-stack-selector |
+| 1: Planning | PRD, optional DESIGN, ARCH, ROADMAP, STACK | god-pm, god-designer, god-architect, god-roadmapper, god-stack-selector |
 | 2: Building | repo, plan, execute, review | god-repo-scaffolder, god-planner, god-executor, god-spec-reviewer, god-quality-reviewer |
 | 3: Shipping | deploy, observe, launch, harden | god-deploy-engineer, god-observability-engineer, god-launch-strategist, god-harden-auditor |
 

package/agents/god-architect.md

@@ -19,19 +19,35 @@ flip points.
 Before starting:
 - `.godpowers/prd/PRD.md` MUST exist
 - PRD MUST pass have-nots (run god-auditor first if uncertain)
+- Optional: `.godpowers/prep/INITIAL-FINDINGS.md` may exist as preparation
+  context.
 - Optional: `.godpowers/prep/IMPORTED-CONTEXT.md` may exist as preparation
   context.
+- Optional: `.godpowers/design/DESIGN.md` and
+  `.godpowers/design/PRODUCT.md` may exist as early product-experience
+  preparation.
 
 ## Imported Preparation Context
 
+If `.godpowers/prep/INITIAL-FINDINGS.md` exists, read it first for direct
+Godpowers observations about framework, tooling, deploy, tests, docs, and
+codebase risks.
+
 If `.godpowers/prep/IMPORTED-CONTEXT.md` exists, read its technical signals
 before drafting ARCH. Use imported architecture, integration, risk, and stack
 constraints as hypothesis-level input only.
 
+If `.godpowers/design/DESIGN.md` or `.godpowers/design/PRODUCT.md` exists,
+read them before drafting ARCH. Use early design to identify user-facing
+surfaces, routes, component boundaries, state flows, accessibility needs, and
+where architecture must preserve product experience.
+
 Rules:
 - Do not let imported context override PRD NFRs or Godpowers state.
 - Convert useful imported signals into ADR context, tradeoffs, or open
   questions.
+- Convert useful design signals into containers, ADR context, UI boundary
+  descriptions, or open questions.
 - If imported context conflicts with the PRD, the PRD wins and the conflict
   becomes an `[OPEN QUESTION]`.
 

package/agents/god-designer.md

@@ -4,7 +4,7 @@ description: |
   Lifecycle owner of DESIGN.md and PRODUCT.md. Detects impeccable; if
   installed, delegates to /impeccable teach (initial) or /impeccable
   document (refresh from code). If not installed, falls back to a
-  minimal builder using PRD/ARCH/STACK.
+  minimal builder using prep artifacts, PRD, and any available ARCH/STACK.
 
   Spawned by: /god-design, god-orchestrator (Tier 1, conditional on UI)
 tools: Read, Write, Edit, Bash, Grep, Glob
@@ -78,10 +78,18 @@ Cascade:
   - `references/design/UX-WRITING.md` (copy)
   - `references/design/DESIGN-ANTIPATTERNS.md` (what to avoid)
 
-  Use PRD.md (target users, register hints), ARCH.md (UI surface),
-  STACK.md (UI framework) to generate a starter DESIGN.md from the
-  template, applying the rules from the references above. The output
-  will be less polished than impeccable's, but it's not toothless: the
+  Read `.godpowers/prep/INITIAL-FINDINGS.md` and
+  `.godpowers/prep/IMPORTED-CONTEXT.md` when present, then use PRD.md
+  (target users, flows, register hints), plus ARCH.md and STACK.md only
+  when they already exist. Early mode runs after PRD and before
+  architecture, so do not require ARCH or STACK. In early mode, produce
+  an experience contract that architecture and stack can honor later:
+  screens, flows, component needs, interaction states, product voice,
+  constraints, anti-references, and visual token direction.
+
+  Generate a starter DESIGN.md from the template, applying the rules
+  from the references above. The output will be less polished than
+  impeccable's, but it's not toothless: the
   references encode our design opinions across all 7 domains
   (typography, color, spatial, motion, interaction, responsive,
   ux-writing) at shallower depth than impeccable's full skill set.
@@ -152,7 +160,8 @@ After done, return to god-orchestrator with:
 - DESIGN.md path
 - PRODUCT.md path (if produced)
 - Validation summary (errors, warnings)
-- Suggested next: `/god-repo` (proceed to scaffolding)
+- Suggested next: `/god-arch` when design ran early, or `/god-repo` when
+  architecture, roadmap, and stack are already complete
 
 ## Linkage hooks
 

package/agents/god-orchestrator.md

@@ -30,8 +30,9 @@ You and only you are responsible for:
 2. **Calling the play** - selecting the next specialist agent for each tier
    sub-step from `<runtimeRoot>/routing/<command>.yaml`.
 3. **Owning the playbook** - all writes to `state.json`, `PROGRESS.md`,
-   `intent.yaml`, `.godpowers/prep/IMPORTED-CONTEXT.md`, and `events.jsonl`
-   originate from you or agents you spawn.
+   `intent.yaml`, `.godpowers/prep/INITIAL-FINDINGS.md`,
+   `.godpowers/prep/IMPORTED-CONTEXT.md`, and `events.jsonl` originate from you
+   or agents you spawn.
 4. **Audibles** - handling pause checkpoints, the critical-finding gate, and
    the --yolo carve-out when the user has authorized auto-resolve.
 5. **Clock management** - mandatory final sync after Tier 3 (always, including
@@ -145,6 +146,20 @@ During `/god-init`, scan for adjacent methodology artifacts from GSD,
 Superpowers, BMAD, and similar systems. Treat them as preparation context,
 not as source of truth.
 
+Before or alongside that import, write `.godpowers/prep/INITIAL-FINDINGS.md`
+using `templates/INITIAL-FINDINGS.md`. This artifact records what Godpowers
+observed directly during init:
+- codebase shape, language, framework, package manager, tests, CI, deploy, and
+  documentation signals
+- AI-tool instruction files and methodology systems detected
+- risk signals and open questions raised by the scan
+- the suggested next command and why that command is the safest next step
+
+Downstream `/god-prd`, `/god-next`, and `/god-mode` flows must read
+`INITIAL-FINDINGS.md` when present. Use it as preparation context only. If it
+conflicts with user intent, state.json, PROGRESS.md, or completed Godpowers
+artifacts, the Godpowers artifact wins.
+
 Detection signals:
 - GSD: `.gsd/`, `.planning/`, `GSD.md`, `gsd*.md`
 - Superpowers: `.superpowers/`, `superpowers/`, `SUPERPOWERS.md`,
@@ -212,18 +227,23 @@ This is the third layer of decision support:
 
 ## Detection-Driven Tier 1 Routing
 
-After STACK done, branch on UI presence:
+After PRD and before ARCH, branch on UI or product-experience presence:
 
 1. Call `lib/design-detector.isUiProject(projectRoot)` to determine
    whether DESIGN tier is required.
 2. Call `lib/design-detector.isImpeccableInstalled(projectRoot)` to
    determine whether to delegate or fall back.
-3. Persist results to `state.json.project.detection-results`.
-4. If `requires-design: true`: spawn `god-designer` for DESIGN tier
-   (Tier 1 sub-step 5). god-designer delegates to impeccable's
+3. Read `.godpowers/prep/INITIAL-FINDINGS.md`,
+   `.godpowers/prep/IMPORTED-CONTEXT.md`, and `.godpowers/prd/PRD.md`
+   for UI, workflow, journey, component, brand, accessibility, and screen
+   signals.
+4. Persist results to `state.json.project.detection-results`.
+5. If `requires-design: true`: spawn `god-designer` for DESIGN tier before
+   architecture. god-designer delegates to impeccable's
    `/impeccable teach` if available, else falls back to a minimal builder.
-5. If `requires-design: false`: mark `tier-1.design.status = not-required`
-   and `tier-1.product.status = not-required`. Advance to Tier 2.
+   DESIGN.md and PRODUCT.md then inform architecture, roadmap, and stack.
+6. If `requires-design: false`: mark `tier-1.design.status = not-required`
+   and `tier-1.product.status = not-required`. Continue to architecture.
 
 ## Linkage and Reverse-Sync
 
@@ -308,9 +328,10 @@ For single-agent sub-steps:
 | Sub-step | Spawn Agent | Reads | Writes |
 |----------|-------------|-------|--------|
 | PRD | god-pm | user intent | .godpowers/prd/PRD.md |
-| Architecture | god-architect | PRD | .godpowers/arch/ARCH.md |
-| Roadmap | god-roadmapper | PRD, ARCH | .godpowers/roadmap/ROADMAP.md |
-| Stack | god-stack-selector | ARCH | .godpowers/stack/DECISION.md |
+| Design | god-designer | prep, PRD | .godpowers/design/DESIGN.md + .godpowers/design/PRODUCT.md |
+| Architecture | god-architect | PRD, optional DESIGN | .godpowers/arch/ARCH.md |
+| Roadmap | god-roadmapper | PRD, ARCH, optional DESIGN | .godpowers/roadmap/ROADMAP.md |
+| Stack | god-stack-selector | ARCH, optional DESIGN | .godpowers/stack/DECISION.md |
 | Repo | god-repo-scaffolder | DECISION | .godpowers/repo/AUDIT.md + repo files |
 | Deploy | god-deploy-engineer | ARCH, build | .godpowers/deploy/STATE.md |
 | Observe | god-observability-engineer | PRD, ARCH | .godpowers/observe/STATE.md |

package/agents/god-pm.md

@@ -31,6 +31,10 @@ required sections:
 
 ## Imported Preparation Context
 
+If `.godpowers/prep/INITIAL-FINDINGS.md` exists, read it first so the PRD
+reflects what Godpowers observed during init: codebase shape, tests, docs,
+risks, and methodology systems detected.
+
 If `.godpowers/prep/IMPORTED-CONTEXT.md` exists, read it before drafting the
 PRD. Use product signals from GSD, Superpowers, BMAD, or similar systems as
 hypothesis-level input only.

package/agents/god-roadmapper.md

@@ -16,15 +16,26 @@ Sequence the work.
 ## Gate Check
 
 `.godpowers/arch/ARCH.md` MUST exist and pass have-nots.
+Optional: `.godpowers/prep/INITIAL-FINDINGS.md` may exist as preparation
+context.
 Optional: `.godpowers/prep/IMPORTED-CONTEXT.md` may exist as preparation
 context.
+Optional: `.godpowers/design/DESIGN.md` and `.godpowers/design/PRODUCT.md`
+may exist as early product-experience preparation.
 
 ## Imported Preparation Context
 
+If `.godpowers/prep/INITIAL-FINDINGS.md` exists, read it first for repo risks,
+existing tests, docs, CI, deploy, and suggested sequencing implications.
+
 If `.godpowers/prep/IMPORTED-CONTEXT.md` exists, read its delivery signals
 before sequencing milestones. Use imported GSD, Superpowers, BMAD, or similar
 stories and plans as hypothesis-level input only.
 
+If DESIGN.md or PRODUCT.md exists, read them before sequencing milestones.
+Use screens, flows, components, accessibility obligations, and product voice to
+shape vertical slices and acceptance gates.
+
 Rules:
 - Do not add roadmap features that are not grounded in the PRD.
 - Use imported milestones, stories, and done-work signals to inform ordering,
@@ -32,6 +43,7 @@ Rules:
 - If imported context conflicts with PRD or ARCH, PRD and ARCH win.
 - Mark any imported sequencing assumption as `[HYPOTHESIS]` until confirmed by
   Godpowers artifacts or the user.
+- Keep design-derived milestones grounded in the PRD and ARCH.
 
 ## Process
 

package/agents/god-stack-selector.md

@@ -15,20 +15,33 @@ Pick the technology stack.
 ## Gate Check
 
 `.godpowers/arch/ARCH.md` MUST exist.
+Optional: `.godpowers/prep/INITIAL-FINDINGS.md` may exist as preparation
+context.
 Optional: `.godpowers/prep/IMPORTED-CONTEXT.md` may exist as preparation
 context.
+Optional: `.godpowers/design/DESIGN.md` and `.godpowers/design/PRODUCT.md`
+may exist as product-experience preparation.
 
 ## Imported Preparation Context
 
+If `.godpowers/prep/INITIAL-FINDINGS.md` exists, read it first for direct
+tooling, package manager, framework, runtime, CI, and deploy observations.
+
 If `.godpowers/prep/IMPORTED-CONTEXT.md` exists, read its technical and stack
 signals before scoring candidates. Use imported technology choices, constraints,
 and team familiarity as hypothesis-level input only.
 
+If DESIGN.md or PRODUCT.md exists, read them before scoring frontend,
+component, styling, accessibility, animation, and design-token tooling
+candidates.
+
 Rules:
 - Do not let imported stack preference override ARCH NFRs or ADRs.
 - Treat imported technology choices as candidate evidence, not decisions.
 - If imported context conflicts with ARCH, ARCH wins and the conflict becomes a
   stack open question.
+- If design intent conflicts with ARCH NFRs, ARCH wins and the conflict becomes
+  a stack or architecture open question.
 
 ## Process
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godpowers",
-  "version": "0.15.7",
+  "version": "0.15.9",
   "description": "AI-powered development system: 104 slash commands and 38 specialist agents that take a project from raw idea to hardened production. Runs inside Claude Code, Codex, Cursor, Windsurf, Gemini, and 10+ other AI coding tools.",
   "bin": {
     "godpowers": "./bin/install.js"

package/routing/god-arch.yaml

@@ -19,6 +19,9 @@ execution:
   context: fresh
   reads:
     - .godpowers/prd/PRD.md
+    - .godpowers/design/DESIGN.md
+    - .godpowers/design/PRODUCT.md
+    - .godpowers/prep/INITIAL-FINDINGS.md
     - .godpowers/prep/IMPORTED-CONTEXT.md
     - templates/ARCH.md
   writes:

package/routing/god-design.yaml

@@ -10,14 +10,18 @@ prerequisites:
     - check: file:.godpowers/PROGRESS.md
       reason: "/god-design needs an initialized project"
       auto-complete: /god-init
-    - check: file:.godpowers/stack/DECISION.md
-      reason: "Stack must be selected before design (UI framework drives token shape)"
-      auto-complete: /god-stack
-  optional:
     - check: file:.godpowers/prd/PRD.md
-      reason: "PRD informs target users and register"
+      reason: "Design needs PRD user, product, and register context"
+      auto-complete: /god-prd
+  optional:
+    - check: file:.godpowers/prep/INITIAL-FINDINGS.md
+      reason: "Initial findings can show UI and product-experience signals"
+    - check: file:.godpowers/prep/IMPORTED-CONTEXT.md
+      reason: "Imported GSD, Superpowers, or BMAD context can inform design hypotheses"
     - check: file:.godpowers/arch/ARCH.md
       reason: "ARCH names the UI surface that DESIGN applies to"
+    - check: file:.godpowers/stack/DECISION.md
+      reason: "STACK can refine framework-specific token shape when already selected"
 
 execution:
   spawns: [god-designer]
@@ -47,8 +51,11 @@ standards:
     - "cards in cards"        # impeccable anti-pattern
 
 success-path:
-  next-recommended: /god-repo
-  why: Design tokens stable; repo can scaffold with token references
+  next-recommended: /god-arch
+  why: Early product experience is defined; architecture can now respect the intended surfaces and flows
+  alternatives:
+    - command: /god-repo
+      when: architecture-roadmap-and-stack-already-done
 
 failure-path:
   on-error: /god-doctor

package/routing/god-init.yaml

@@ -19,6 +19,7 @@ execution:
     - .godpowers/PROGRESS.md
     - .godpowers/state.json
     - .godpowers/intent.yaml
+    - .godpowers/prep/INITIAL-FINDINGS.md
     - .godpowers/prep/IMPORTED-CONTEXT.md
 
 success-path:

package/routing/god-mode.yaml

@@ -14,7 +14,10 @@ prerequisites:
 execution:
   spawns: [god-orchestrator]
   context: fresh
-  secondary-spawns: [god-pm, god-architect, god-roadmapper, god-stack-selector, god-repo-scaffolder, god-planner, god-executor, god-spec-reviewer, god-quality-reviewer, god-deploy-engineer, god-observability-engineer, god-harden-auditor, god-launch-strategist]
+  reads:
+    - .godpowers/prep/INITIAL-FINDINGS.md
+    - .godpowers/prep/IMPORTED-CONTEXT.md
+  secondary-spawns: [god-pm, god-designer, god-architect, god-roadmapper, god-stack-selector, god-repo-scaffolder, god-planner, god-executor, god-spec-reviewer, god-quality-reviewer, god-deploy-engineer, god-observability-engineer, god-harden-auditor, god-launch-strategist]
   writes:
     []
 

package/routing/god-next.yaml

@@ -12,6 +12,9 @@ prerequisites:
 execution:
   spawns: [built-in]
   context: fresh
+  reads:
+    - .godpowers/prep/INITIAL-FINDINGS.md
+    - .godpowers/prep/IMPORTED-CONTEXT.md
   writes:
     []
 

package/routing/god-prd.yaml

@@ -21,6 +21,7 @@ execution:
   context: fresh
   reads:
     - .godpowers/intent.yaml
+    - .godpowers/prep/INITIAL-FINDINGS.md
     - .godpowers/prep/IMPORTED-CONTEXT.md
     - templates/PRD.md
   writes:
@@ -36,6 +37,13 @@ standards:
 
 success-path:
   next-recommended: /god-arch
+  conditional-next:
+    - condition: ui-detected
+      next: /god-design
+      reason: UI or product-experience signals found; write DESIGN.md before architecture
+    - condition: no-ui-detected
+      next: /god-arch
+      reason: No UI surface detected; architecture is the next planning gate
   alternatives:
     - command: /god-mode
       when: user-wants-autonomous-from-here

package/routing/god-roadmap.yaml

@@ -17,6 +17,9 @@ execution:
   reads:
     - .godpowers/prd/PRD.md
     - .godpowers/arch/ARCH.md
+    - .godpowers/design/DESIGN.md
+    - .godpowers/design/PRODUCT.md
+    - .godpowers/prep/INITIAL-FINDINGS.md
     - .godpowers/prep/IMPORTED-CONTEXT.md
     - templates/ROADMAP.md
   writes:

package/routing/god-stack.yaml

@@ -16,6 +16,9 @@ execution:
   context: fresh
   reads:
     - .godpowers/arch/ARCH.md
+    - .godpowers/design/DESIGN.md
+    - .godpowers/design/PRODUCT.md
+    - .godpowers/prep/INITIAL-FINDINGS.md
     - .godpowers/prep/IMPORTED-CONTEXT.md
   writes:
     - .godpowers/stack/DECISION.md

package/skills/god-arch.md

@@ -15,8 +15,11 @@ Spawn the **god-architect** agent in a fresh context via Task tool.
 
 1. Verify `.godpowers/prd/PRD.md` exists. If not, tell user to run `/god-prd` first.
 2. Spawn god-auditor briefly to verify PRD passes have-nots. If fails, report and stop.
-3. Spawn god-architect with the PRD path and full context window
-4. The agent writes `.godpowers/arch/ARCH.md` and ADRs to `.godpowers/arch/adr/`
+3. If `.godpowers/design/DESIGN.md` or `.godpowers/design/PRODUCT.md` exists,
+   include it as input. Design is optional, but when present it informs UI
+   containers, routes, flows, and tradeoffs.
+4. Spawn god-architect with the PRD path and full context window
+5. The agent writes `.godpowers/arch/ARCH.md` and ADRs to `.godpowers/arch/adr/`
 
 ## Verification
 

package/skills/god-init.md

@@ -30,6 +30,10 @@ needs to specify a mode.
    - Look for org-level context (current dir + parent dirs):
      - .godpowers/org-context.yaml
      - Workspace configs that share standards
+   - Write `.godpowers/prep/INITIAL-FINDINGS.md` summarizing what Godpowers
+     observed about the repo, tooling, docs, tests, risks, and suggested next
+     command. This happens before `/god-prd`, `/god-next`, or `/god-mode`
+     continues.
    - Look for adjacent planning-system context:
      - GSD: `.gsd/`, `.planning/`, `GSD.md`, `gsd*.md`
      - Superpowers: `.superpowers/`, `superpowers/`, `SUPERPOWERS.md`,
@@ -39,6 +43,17 @@ needs to specify a mode.
    - If any are detected, summarize useful signals into
      `.godpowers/prep/IMPORTED-CONTEXT.md` as preparation context.
      Do not treat external planning-system files as source of truth.
+   - Detect whether early design preparation is warranted:
+     - UI frameworks or app models: React, Next, Vue, Nuxt, Svelte,
+       SvelteKit, Astro, Remix, Angular, Solid, Flutter, Electron, Tauri
+     - UI surfaces: `src/components/`, `app/`, `pages/`, `routes/`,
+       `public/`, form-heavy flows, dashboards, editor surfaces, mobile
+       shells, marketing pages, or other user-facing product experience
+     - Imported GSD, Superpowers, or BMAD context that mentions UX, screens,
+       journeys, components, brand, interaction states, or visual design
+   - Record the result in `INITIAL-FINDINGS.md` so `/god-prd`, `/god-next`,
+     and `/god-mode` can place `/god-design` after PRD and before
+     `/god-arch` when the project needs early product-experience shape.
 
 3. **Announce findings in plain English** (no jargon):
    - Empty dir + no org context: "Detected: empty directory. Starting fresh."
@@ -57,6 +72,7 @@ needs to specify a mode.
    The orchestrator will:
    - Run Mode Detection (announced in plain English; stored as A/B/C/E internally)
    - Run Scale Detection (trivial/small/medium/large/enterprise)
+   - Write `.godpowers/prep/INITIAL-FINDINGS.md`
    - Run planning-system context detection for GSD, Superpowers, and BMAD
    - Write `.godpowers/prep/IMPORTED-CONTEXT.md` when useful context exists
    - For brownfield: schedule archaeology + reconstruction as preflight
@@ -77,6 +93,7 @@ needs to specify a mode.
    .godpowers/
      PROGRESS.md
      prep/
+       INITIAL-FINDINGS.md
        IMPORTED-CONTEXT.md   # only when GSD / Superpowers / BMAD context exists
      prd/
      arch/
@@ -112,6 +129,12 @@ needs to specify a mode.
 
 `.godpowers/PROGRESS.md` created with initial state.
 
+Always create `.godpowers/prep/INITIAL-FINDINGS.md`. This is Godpowers'
+durable answer to "what did init find in this codebase?" It captures codebase
+shape, framework and tooling signals, tests, CI, docs, AI-tool files, detected
+methodology systems, UI or product-experience signals, risk signals, and the
+reasoning behind the suggested next command.
+
 If GSD, Superpowers, BMAD, or similar planning context is detected, create
 `.godpowers/prep/IMPORTED-CONTEXT.md`. This artifact is preparation context,
 not source of truth. It feeds PRD, architecture, roadmap, and stack decisions

package/skills/god-mode.md

@@ -47,6 +47,12 @@ You are receiving a /god-mode invocation. Your job is to spawn the
    - The detected mode (A/B/C/E)
    - The active flags
    - Instruction to read `.godpowers/PROGRESS.md` from disk if it exists
+   - Instruction to read `.godpowers/prep/INITIAL-FINDINGS.md` and
+     `.godpowers/prep/IMPORTED-CONTEXT.md` if present before choosing the
+     first planning or build step
+   - Instruction to run `/god-design` after `/god-prd` and before `/god-arch`
+     when initial findings, imported planning context, the PRD, or the
+     codebase show UI or product-experience signals
 
 6. Orchestrator runs the appropriate workflow:
    - Greenfield -> full-arc

package/skills/god-next.md

@@ -39,6 +39,17 @@ if any are missing.
 User just ran /god-next. Auto-detects current project phase and suggests
 the next logical command.
 
+Before suggesting, read `.godpowers/prep/INITIAL-FINDINGS.md` and
+`.godpowers/prep/IMPORTED-CONTEXT.md` if present. Use them to explain why the
+next step is safe or why a migration-aware step such as `/god-prd`,
+`/god-map-codebase`, or `/god-mode` is better. Prep artifacts are context only;
+state.json and completed Godpowers artifacts remain authoritative.
+
+If PRD is complete, DESIGN is missing, and initial findings, imported context,
+the PRD, or the codebase show UI or product-experience signals, suggest
+`/god-design` before `/god-arch`. DESIGN.md is early preparation for visible
+workflows, not a replacement for architecture.
+
 ## Process for Mode 1 (post-completion)
 
 ```
@@ -51,7 +62,8 @@ Skill calls: /god-next --after=/god-prd
 Read <runtimeRoot>/routing/god-prd.yaml
    |
    v
-Get success-path.next-recommended (e.g., "/god-arch")
+Get success-path.next-recommended (e.g., "/god-arch"), then apply any
+conditional-next rule such as UI-detected -> "/god-design"
    |
    v
 Display: "PRD complete: .godpowers/prd/PRD.md

package/skills/god-prd.md

@@ -14,10 +14,16 @@ Spawn the **god-pm** agent in a fresh context via Task tool.
 ## Setup
 
 1. If `.godpowers/PROGRESS.md` does not exist: tell the user to run `/god-init` first
-2. Otherwise: spawn god-pm with the user's project description from PROGRESS.md
-3. The agent writes `.godpowers/prd/PRD.md`
-4. The agent runs have-nots checks before declaring done
-5. If god-pm pauses for a human question: relay to user using pause format
+2. Read `.godpowers/prep/INITIAL-FINDINGS.md` if present.
+3. Read `.godpowers/prep/IMPORTED-CONTEXT.md` if present.
+4. Spawn god-pm with the user's project description from PROGRESS.md plus any
+   prep artifacts. Prep artifacts are context, not source of truth.
+5. The agent writes `.godpowers/prd/PRD.md`
+6. The agent runs have-nots checks before declaring done
+7. If god-pm pauses for a human question: relay to user using pause format
+8. If prep artifacts or the PRD show UI or product-experience signals, route
+   to `/god-design` next so DESIGN.md can shape architecture. Otherwise route
+   to `/god-arch`.
 
 ## Verification
 
@@ -44,7 +50,7 @@ After PRD is written and have-nots pass, print:
 ```
 PRD complete: .godpowers/prd/PRD.md
 
-Suggested next: /god-arch (design the architecture)
+Suggested next: /god-design (shape product experience) if UI/product experience is detected, otherwise /god-arch (design the architecture)
 ```
 
 

package/templates/INITIAL-FINDINGS.md

@@ -0,0 +1,54 @@
+# Initial Findings
+
+> This artifact records what Godpowers observed during `/god-init`. It is
+> preparation documentation for planning, routing, and migration. Godpowers
+> state and completed artifacts remain authoritative after they exist.
+
+## Codebase Shape
+
+- [HYPOTHESIS] Project type: [greenfield / brownfield / bluefield / audit].
+- [HYPOTHESIS] Scale: [trivial / small / medium / large / enterprise].
+- [HYPOTHESIS] Primary language or runtime: [detected value].
+- [HYPOTHESIS] Framework or app model: [detected value].
+- [HYPOTHESIS] Package manager or build tool: [detected value].
+
+## Repo Signals
+
+- [HYPOTHESIS] Source directories found: [paths].
+- [HYPOTHESIS] Test signals found: [paths or "none detected"].
+- [HYPOTHESIS] CI or release signals found: [paths or "none detected"].
+- [HYPOTHESIS] Deployment signals found: [paths or "none detected"].
+- [HYPOTHESIS] Documentation signals found: [paths or "none detected"].
+- [HYPOTHESIS] UI or product-experience signals found: [frameworks, routes, components, workflows, design docs, or "none detected"].
+
+## Methodology And AI Tool Signals
+
+- [HYPOTHESIS] AI instruction files found: [paths or "none detected"].
+- [HYPOTHESIS] GSD context found: [paths or "none detected"].
+- [HYPOTHESIS] Superpowers context found: [paths or "none detected"].
+- [HYPOTHESIS] BMAD context found: [paths or "none detected"].
+- [HYPOTHESIS] Imported context artifact: [.godpowers/prep/IMPORTED-CONTEXT.md or "not created"].
+
+## Planning Implications
+
+- [HYPOTHESIS] PRD should pay attention to: [product or user signal].
+- [HYPOTHESIS] Design should pay attention to: [early UX, workflow, brand, component, or interaction signal].
+- [HYPOTHESIS] Architecture should pay attention to: [technical or risk signal].
+- [HYPOTHESIS] Roadmap should pay attention to: [delivery or dependency signal].
+- [HYPOTHESIS] Stack should pay attention to: [tooling or constraint signal].
+
+## Risks And Unknowns
+
+- [OPEN QUESTION] [Question raised by repo scan] -- Owner: user -- Due: before the relevant planning step.
+- [HYPOTHESIS] Risk signal: [missing tests / unclear deploy path / stale docs / conflicting planning systems].
+
+## Suggested Next
+
+- [DECISION] Suggested next command: [/god-prd / /god-map-codebase / /god-mode / /god-next].
+- [DECISION] Reason: [why this command is the safest next step based on findings].
+
+## Use Rules
+
+- [DECISION] Downstream agents may use this artifact as preparation context only.
+- [DECISION] If this artifact conflicts with `.godpowers/intent.yaml`, `.godpowers/state.json`, `PROGRESS.md`, or a completed Godpowers artifact, the Godpowers artifact wins.
+- [DECISION] Imported GSD, Superpowers, and BMAD signals must be converted into Godpowers-native artifacts, not preserved as parallel state.