warp-os 1.1.2 → 1.2.1

package/dist/warp-plan-brainstorm/SKILL.md

@@ -133,6 +133,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -154,9 +156,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---
@@ -313,7 +321,15 @@ Product stage determines which forcing questions to ask (see Phase 2).
    ```
    If prior brainstorms exist, surface them: "Prior brainstorm found at `.warp/reports/planning/brainstorm.md`. Want to build on it or start fresh?"
 
-4. Output: "Here's what I understand about this project and the problem area you want to explore: [1-2 paragraph synthesis]." State what is known and what is unclear.
+4. **Related Design Discovery:** Search `.warp/reports/` for any existing artifacts with keyword overlap to the stated problem:
+   ```bash
+   grep -rl "[key terms from user's problem description]" .warp/reports/ 2>/dev/null
+   ```
+   If related work exists, present it via AskUserQuestion: "Found existing artifacts that may be relevant: [list with brief description of each]. Want to build on these or start fresh?"
+
+   This prevents duplicate brainstorming and surfaces prior thinking the user may have forgotten about. Skip this step only if `.warp/reports/` does not exist.
+
+5. Output: "Here's what I understand about this project and the problem area you want to explore: [1-2 paragraph synthesis]." State what is known and what is unclear.
 
 ---
 
@@ -448,6 +464,45 @@ If the framing is imprecise, reframe constructively: "Let me try restating what
 
 ---
 
+## PHASE 2.5: Landscape Awareness (Both Modes)
+
+**Goal:** Ground the brainstorm in what actually exists in the market. Conventional wisdom is often wrong — search for evidence before synthesizing.
+
+### Privacy Gate
+
+Before any web search, ask via AskUserQuestion:
+
+> "I'd like to search for [specific query] to understand the competitive landscape. This will send a web search query. OK to proceed? [Y/n]"
+
+Only proceed with the search if the user approves. If declined, skip to Phase 3 and note in the brainstorm artifact that landscape analysis was skipped by user choice.
+
+### Search Strategy
+
+Search for:
+- `[product category] + "alternatives"` — what direct competitors exist
+- `[problem domain] + "solutions"` — how people solve this problem today
+- `[user type] + [pain point]` — how the target user describes their problem
+
+Use WebSearch for each approved query. Limit to 2-3 searches to avoid over-researching.
+
+### Landscape Synthesis
+
+Produce:
+
+```
+LANDSCAPE SYNTHESIS:
+  Conventional wisdom: [what everyone assumes the solution looks like]
+  Search findings: [what competitors actually do — 3-5 with URLs]
+  First-principles view: [what the data suggests that contradicts conventional wisdom]
+  Eureka moments: [any insight that changes the problem framing]
+```
+
+**Integration:** Feed the landscape synthesis directly into Phase 3 (User Needs Mapping) and Phase 6 (Synthesis). The "Key Insight" in Phase 6 should reference landscape findings when they reveal a non-obvious opportunity.
+
+**Smart-skip:** If the user already provided detailed competitive analysis or the product is in a space with no direct competitors (novel research, internal tool), skip the search but still produce the synthesis from what the user shared.
+
+---
+
 ## PHASE 2B: Builder Mode Questions
 
 Use this phase when the user is building for fun, learning, hacking, at a hackathon, or doing research.
@@ -677,6 +732,33 @@ Present via AskUserQuestion. Do NOT proceed without user approval.
 
 **Goal:** Write the output artifact with all session findings.
 
+### Design Doc Lineage
+
+Before writing, check if a previous `brainstorm.md` exists:
+
+```bash
+if [ -f .warp/reports/planning/brainstorm.md ]; then
+  # Get the date from the existing file's pipeline header
+  existing_date=$(grep -oP '\d{4}-\d{2}-\d{2}' .warp/reports/planning/brainstorm.md | head -1)
+  # Count existing versions in archive
+  mkdir -p .warp/reports/planning/archive
+  version=$(ls .warp/reports/planning/archive/brainstorm-v*.md 2>/dev/null | wc -l)
+  next_version=$((version + 1))
+  # Archive the previous version
+  cp .warp/reports/planning/brainstorm.md ".warp/reports/planning/archive/brainstorm-v${next_version}.md"
+fi
+```
+
+If a previous version was archived, add a `Supersedes:` comment at the top of the new brainstorm.md:
+
+```markdown
+<!-- Supersedes: brainstorm-v[N].md ([date]) — [brief reason for new version, e.g., "scope expanded after competitive analysis"] -->
+```
+
+This creates an audit trail of how the product thinking evolved. The archive is in `.warp/reports/planning/archive/` and is never deleted.
+
+### Write the Artifact
+
 Create `.warp/reports/planning/brainstorm.md`:
 
 ```markdown
@@ -717,12 +799,21 @@ Create `.warp/reports/planning/brainstorm.md`:
 ### Approach C: {name — if applicable}
 {from Phase 7}
 
+## Landscape Analysis
+{from Phase 2.5 — conventional wisdom, search findings, first-principles view, eureka moments}
+{If skipped by user choice, note: "Landscape analysis skipped at user request."}
+
 ## Recommended Direction
 {from Phase 6 synthesis}
 
 ## What to Build First
 {the narrowest wedge}
 
+## Distribution Plan
+How users get this: {app store / npm / direct download / SaaS / browser extension / etc.}
+CI/CD pipeline needed: {yes — describe / no — manual / existing pipeline covers it}
+Update mechanism: {auto-update / manual / package manager / N/A for SaaS}
+
 ## Open Questions
 {unresolved uncertainties that the next skill should address}
 

package/dist/warp-plan-design/SKILL.md

@@ -134,6 +134,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -155,9 +157,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---
@@ -435,7 +443,44 @@ SCREEN: [name]
 - Never use technical language in user-facing copy: "Something went wrong" not "Error 500"
 - Loading copy uses present participle with ellipsis character: "Loading flights..." uses `…` not `...`
 
-### 2E. Accessibility Strategy
+### 2E. Interaction State Coverage
+
+For every feature or screen identified in the user flows, map which interaction states have been designed. This ensures no screen ships with only the happy path.
+
+```
+INTERACTION STATE COVERAGE:
+  ┌──────────────┬─────────┬───────┬───────┬─────────┬─────────┐
+  │ Feature       │ Loading │ Empty │ Error │ Success │ Partial │
+  ├──────────────┼─────────┼───────┼───────┼─────────┼─────────┤
+  │ [feature]     │ ✓/✗     │ ✓/✗   │ ✓/✗   │ ✓/✗     │ ✓/✗     │
+  └──────────────┴─────────┴───────┴───────┴─────────┴─────────┘
+Every ✗ must be designed before the design phase completes.
+```
+
+Produce this table for every screen from Phase 2A. If a state does not apply to a given feature (e.g., a static "About" page has no loading state), mark it N/A with a brief reason. All other gaps are design debt that must be resolved before Phase 3.
+
+### 2F. User Journey & Emotional Arc
+
+For the primary user flow (and any secondary flow that involves emotional stakes), produce a storyboard mapping what the user does, what they feel, and whether the design addresses that feeling.
+
+```
+USER JOURNEY:
+  ┌──────┬──────────────────┬──────────────────┬───────────────────┐
+  │ Step │ User Does         │ User Feels        │ Design Specifies?  │
+  ├──────┼──────────────────┼──────────────────┼───────────────────┤
+  │ 1    │ [action]          │ [emotion]         │ [yes/no + what]    │
+  │ 2    │ [action]          │ [emotion]         │ [yes/no + what]    │
+  └──────┴──────────────────┴──────────────────┴───────────────────┘
+Any step where "Design Specifies?" = no is a gap to fill.
+```
+
+Rules:
+- Include negative emotions (confusion, anxiety, frustration) — these are where design matters most
+- The "Design Specifies?" column must reference a concrete design element: a loading skeleton, a success animation, an error message with recovery instructions, a reassuring empty state
+- If a step has no design specification, create one before proceeding to Phase 3
+- For Builder mode projects, the emotional arc should include at least one "delight" moment where the user says "whoa"
+
+### 2G. Accessibility Strategy
 
 Define accessibility requirements at the strategy level:
 
@@ -462,7 +507,7 @@ REDUCED MOTION:
   [how animations degrade — typically to opacity fade only]
 ```
 
-### 2F. Figma Setup (if available)
+### 2H. Figma Setup (if available)
 
 If Figma MCP is configured (check `.warp/warp-tools.json` → `mcp_servers.figma.status`):
 
@@ -743,7 +788,55 @@ ANTI-SLOP VERIFICATION:
 
 If ANY item fails the slop scan, go back and fix it before proceeding.
 
-**HARD GATE: Visual System complete. Present color palette, typography, spacing, and key component wireframes to user for approval before proceeding to Implementation.**
+**HARD GATE: Visual System complete. Present color palette, typography, spacing, and key component wireframes to user for approval before proceeding to Design Rating.**
+
+---
+
+## PHASE 3.5: Design Dimension Rating
+
+**Goal:** Rate the design across seven critical dimensions, identify gaps, and fix them before implementation begins. This is the quality gate that prevents mediocre designs from reaching the build phase.
+
+### Rating Method
+
+Score each dimension 0-10. For each, describe what a perfect 10 looks like for THIS specific product. Be concrete — "good typography" is not a 10 description; "type scale with 5 levels, mathematical 1.25 ratio, monospace for all data, system fonts for performance, tested at 200% zoom" is.
+
+```
+DESIGN DIMENSION RATING:
+  ┌────────────────────────────┬───────┬──────────────────────────────────┐
+  │ Dimension                   │ Score │ What 10 looks like                │
+  ├────────────────────────────┼───────┼──────────────────────────────────┤
+  │ Information Architecture    │ [0-10]│ [specific description]            │
+  │ Interaction State Coverage  │ [0-10]│ [specific description]            │
+  │ User Journey & Emotional Arc│ [0-10]│ [specific description]            │
+  │ Design System Alignment     │ [0-10]│ [specific description]            │
+  │ Responsive & Accessibility  │ [0-10]│ [specific description]            │
+  │ Content Strategy            │ [0-10]│ [specific description]            │
+  │ Delight & Differentiation   │ [0-10]│ [specific description]            │
+  └────────────────────────────┴───────┴──────────────────────────────────┘
+```
+
+### Fix Loop
+
+For any dimension scoring below 8:
+
+1. **Explain the gap** — what specifically is missing or weak, with concrete examples from the current design
+2. **Propose a fix** — what specific change would close the gap
+3. **Apply the fix** — update the relevant Phase 2 or Phase 3 output
+4. **Re-rate** — score the dimension again after the fix
+
+Loop until all dimensions score 8 or higher, or the user says "move on."
+
+### Dimension Definitions
+
+- **Information Architecture:** Is every screen's priority hierarchy clear? Can a user answer their primary question in under 1 second? Is navigation depth ≤ 3?
+- **Interaction State Coverage:** Does every feature have loading, empty, error, success, and partial states designed? (Cross-reference with the Phase 2E table.)
+- **User Journey & Emotional Arc:** Does every step in the primary flow have a designed emotional response? Are negative emotions (anxiety, confusion) explicitly addressed?
+- **Design System Alignment:** Are all colors, typography, spacing, and components using tokens? Zero raw values? Consistent across every screen?
+- **Responsive & Accessibility:** WCAG AA verified for all pairs? Touch targets ≥ 44px? Dynamic type tested? Reduced motion specified? Platform conventions honored?
+- **Content Strategy:** Real copy on every screen, every state? Buttons are verb + object? Error messages include recovery? Empty states suggest next action?
+- **Delight & Differentiation:** Would a human designer guess "AI made this"? Does the design have at least one moment that makes the user say "whoa"? Are all three anti-slop commitments honored?
+
+**HARD GATE: All dimensions must score ≥ 8, or the user must explicitly approve moving forward with lower scores. Present the rating table to user for approval before proceeding to Implementation.**
 
 ---
 

package/dist/warp-plan-onboarding/SKILL.md

@@ -129,6 +129,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -150,9 +152,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---

package/dist/warp-plan-optimize/SKILL.md

@@ -129,6 +129,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -150,9 +152,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---

package/dist/warp-plan-scope/SKILL.md

@@ -133,6 +133,8 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 
 ## AskUserQuestion
 
+**Flow: analysis first, then decision tool.** Present your full reasoning, trade-offs, and recommendations as conversational text — the user wants to read your thinking. Then cap it with AskUserQuestion to formalize the decision. **If you're composing a message with multiple options or "which approach?" language, you MUST end it with AskUserQuestion.** Never present options in prose without the tool.
+
 **Contract:**
 1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
 2. **Simplify:** Plain English a smart 16-year-old could follow.
@@ -154,9 +156,15 @@ Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`)
 Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
 Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
 
+**Pre-call checklist (verify before every AskUserQuestion invocation):**
+- ☐ Completeness scores in every option label
+- ☐ Recommended option listed first
+- ☐ One decision per question (split if multiple)
+- ☐ Analysis/reasoning already presented in message text above
+
 **Formatting:**
 - *Italics* for emphasis, not **bold** (bold for headers only).
-- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- After each answer: `✔ Decision {N} recorded`
 - Previews under 8 lines. Full mockups go in conversation text before the question.
 
 ---
@@ -342,6 +350,25 @@ LEVERAGE INVENTORY:
 
 **[SYSTEM scale only]:** If this is a greenfield project with no existing code, note that and proceed.
 
+### Taste Calibration
+
+Before scoping new work, calibrate to the project's actual quality bar. Identify 2-3 well-designed files in the existing codebase and 1-2 anti-patterns. This ensures the scope targets the right level of quality — not aspirational, not lowest-common-denominator, but calibrated to the project's own best work.
+
+```
+TASTE CALIBRATION:
+  Well-designed (match this quality):
+    - [file path] — [why it's good: clear names, good structure, etc.]
+    - [file path] — [why it's good]
+  Anti-patterns (avoid this):
+    - [file path] — [what's wrong: unclear, coupled, etc.]
+```
+
+Rules:
+- "Well-designed" means: clear naming, clean separation of concerns, readable without comments, testable in isolation. Not "clever" — clear.
+- "Anti-pattern" means: unclear responsibility, tight coupling, implicit state, hard to test, confusing to a new reader.
+- If the project is greenfield with no existing code, skip this section.
+- The taste calibration informs the scope: new work should match the quality of the best existing work, not the worst. If the scope would require work at a quality level below the project's best, flag it.
+
 ---
 
 ## PHASE 2: Dream State Mapping
@@ -580,6 +607,41 @@ RISK: [name]
 
 ---
 
+## PHASE 6.5: Implementation Alternatives (Mandatory)
+
+**Goal:** Before committing to a single approach, require 2-3 distinct implementation strategies with explicit trade-offs. This prevents tunnel vision and gives the architect phase real options instead of a predetermined path.
+
+For the scoped work, produce:
+
+```
+IMPLEMENTATION ALTERNATIVES:
+  A) [approach name]
+     Effort: [low/medium/high]  Risk: [low/medium/high]
+     Pros: [list]  Cons: [list]
+  B) [approach name]
+     Effort: [low/medium/high]  Risk: [low/medium/high]
+     Pros: [list]  Cons: [list]
+  C) [approach name] (if applicable)
+     Effort: [low/medium/high]  Risk: [low/medium/high]
+     Pros: [list]  Cons: [list]
+```
+
+Rules:
+- **Minimum two alternatives.** If you can only think of one way to build this, you have not thought hard enough. Even "build from scratch" vs. "use existing library" vs. "fork and customize" counts.
+- **Alternatives must be genuinely different.** Not "React" vs. "React with different state management." Different means different architecture, different trade-offs, different failure modes. Examples: monolith vs. services, server-rendered vs. SPA, build vs. buy, single-table vs. normalized.
+- **Effort and risk must be calibrated to this team.** "Low effort" for a team with React experience is different from "low effort" for a team learning React. Use the taste calibration and leverage inventory to ground estimates.
+- **Do not pre-decide.** Present alternatives neutrally. The user (or the architect phase) chooses. If you have a strong recommendation, state it separately after the alternatives — not embedded in the pros/cons.
+- **Include the "boring" option.** One alternative should always be the simplest, most conventional approach. If the boring option has no real downsides, it is probably the right choice.
+
+Present via AskUserQuestion. User may select one, ask for more detail, or request additional alternatives. Record the selected approach (or "deferred to architect") in scope.md.
+
+**Mode effects:**
+- **Expansion / Selective Expansion:** Full analysis with 3 alternatives minimum.
+- **Hold Scope:** 2 alternatives minimum — the current approach and one meaningful variation.
+- **Reduction:** 2 alternatives — the minimum viable approach and the slightly-less-minimum approach. Focus on what can be cut from the implementation, not just from the feature list.
+
+---
+
 ## PHASE 7: Write scope.md
 
 **Goal:** Write the scope artifact that architect, design, spec, and build all depend on.
@@ -639,6 +701,10 @@ Create `.warp/reports/planning/scope.md`:
 
 {Top risks from Phase 6}
 
+## Implementation Alternatives
+
+{2-3 approaches with effort/risk/pros/cons from Phase 6.5. Selected approach marked.}
+
 ## Temporal Decisions
 
 {What must be decided now vs. deferred}