specweave 1.0.342 → 1.0.344

package/plugins/specweave/skills/architect/SKILL.md

@@ -48,6 +48,62 @@ When a service exposes 50+ API endpoints to AI agents, avoid exposing each as a
 
 **Reference**: ADR-0140 (Code Execution Over Direct MCP Tool Calls) in `.specweave/docs/internal/architecture/adr/`
 
+## Markdown Preview Guidelines
+
+When presenting **2+ architectural approaches** for the user to choose between, use `AskUserQuestion` with the `markdown` preview field to show ASCII diagrams. This lets the user visually compare structural trade-offs in a side-by-side panel.
+
+**When to use**: Any decision point with 2+ options that have structural differences (service layout, schema design, component boundaries, data flow).
+
+**When NOT to use**: Simple yes/no questions, single-option confirmations, or text-only trade-offs without structural implications.
+
+### Example 1: Service Architecture Decision (Box Diagrams)
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Which service architecture should we use for the payment system?",
+    header: "Architecture",
+    multiSelect: false,
+    options: [
+      {
+        label: "Gateway Pattern (Recommended)",
+        description: "Single API gateway routes to microservices. Centralized auth, rate limiting.",
+        markdown: "┌─────────────┐     ┌─────────────┐\n│  Frontend   │────►│ API Gateway │\n│  (Next.js)  │     │  (Workers)  │\n└─────────────┘     └──────┬──────┘\n                      ┌────┴────┐\n                ┌─────▼───┐ ┌───▼───────┐\n                │ Payment │ │  Billing  │\n                │ Service │ │  Service  │\n                └─────────┘ └───────────┘"
+      },
+      {
+        label: "Direct Service Mesh",
+        description: "Services communicate directly via mesh. More resilient but complex.",
+        markdown: "┌─────────────┐     ┌───────────┐\n│  Frontend   │────►│  Payment  │\n│  (Next.js)  │  ┌─►│  Service  │\n└──────┬──────┘  │  └─────┬─────┘\n       │         │        │\n       │    ┌────┴────┐   │\n       └───►│ Billing │◄──┘\n            │ Service │\n            └─────────┘"
+      }
+    ]
+  }]
+})
+```
+
+### Example 2: Database Schema Decision (ASCII Tables)
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Which schema design should we use for user sessions?",
+    header: "Schema",
+    multiSelect: false,
+    options: [
+      {
+        label: "Normalized (Recommended)",
+        description: "Separate tables with foreign keys. Strict integrity, standard JOINs.",
+        markdown: "users                sessions\n────────────────     ────────────────────\nid     UUID PK       id       UUID PK\nemail  TEXT UNIQUE    user_id  UUID FK ──► users.id\nname   TEXT           token    TEXT UNIQUE\n                     expires  TIMESTAMP\n\nIndexes: users(email), sessions(token, user_id)"
+      },
+      {
+        label: "Denormalized",
+        description: "Single table with embedded session data. Faster reads, no JOINs.",
+        markdown: "user_sessions\n──────────────────────────────\nid            UUID PK\nemail         TEXT UNIQUE\nname          TEXT\nsession_token TEXT UNIQUE\nsession_exp   TIMESTAMP\nmetadata      JSONB\n\nIndexes: user_sessions(email, session_token)"
+      }
+    ]
+  }]
+})
+```
+
 ## Delegation
 
 After architecture is ready, delegate to domain skills:

package/plugins/specweave/skills/increment/SKILL.md

@@ -381,6 +381,62 @@ Tasks: [N] | Domains: [M] | Complexity: [Low/Medium/High]
 
 See CLAUDE.md Execution Strategy section for the full decision matrix.
 
+## Markdown Preview Guidelines
+
+When presenting **scope or structure decisions** that have 2+ meaningful options, use `AskUserQuestion` with the `markdown` preview field to show tree diagrams (folder structures) or tables (AC coverage). This helps the user visually compare what each approach delivers.
+
+**When to use**: Choosing between increment scopes (MVP vs full), folder structures, or comparing AC coverage across approaches.
+
+**When NOT to use**: Simple type classification (feature vs bug), single-option confirmations, or questions without structural implications.
+
+### Example 1: Scope Decision with AC Coverage Table
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Which scope should this increment cover?",
+    header: "Scope",
+    multiSelect: false,
+    options: [
+      {
+        label: "MVP (Recommended)",
+        description: "Core auth flow only. Ship fast, iterate in next increment.",
+        markdown: "Task        AC Coverage      Stories\n──────────  ───────────────  ───────\nDB Schema   AC-US1-01        US-001\nJWT Utils   AC-US1-02        US-001\nLogin API   AC-US1-01,03     US-001\nAuth MW     AC-US2-01        US-002\n\nTotal: 4 tasks | 2 stories | 4 ACs covered"
+      },
+      {
+        label: "Full Feature",
+        description: "Auth + password reset + OAuth. More complete but 3x the work.",
+        markdown: "Task          AC Coverage        Stories\n────────────  ─────────────────  ───────\nDB Schema     AC-US1-01          US-001\nJWT Utils     AC-US1-02          US-001\nLogin API     AC-US1-01,03       US-001\nAuth MW       AC-US2-01          US-002\nPwd Reset     AC-US3-01,02       US-003\nOAuth Flow    AC-US4-01,02,03    US-004\nE2E Tests     AC-US1-01..US4-03  All\n\nTotal: 7 tasks | 4 stories | 10 ACs covered"
+      }
+    ]
+  }]
+})
+```
+
+### Example 2: Structure Decision with Tree Preview
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Which folder structure should we use for this feature?",
+    header: "Structure",
+    multiSelect: false,
+    options: [
+      {
+        label: "By Domain (Recommended)",
+        description: "Group files by business domain. Better for feature isolation.",
+        markdown: "src/\n├── auth/\n│   ├── api/\n│   │   ├── login.ts\n│   │   └── register.ts\n│   ├── middleware.ts\n│   └── jwt-utils.ts\n├── billing/\n│   ├── api/\n│   └── stripe-client.ts\n└── shared/\n    └── db.ts"
+      },
+      {
+        label: "By Layer",
+        description: "Group by technical layer. Familiar MVC-style structure.",
+        markdown: "src/\n├── api/\n│   ├── auth.ts\n│   └── billing.ts\n├── middleware/\n│   └── auth.ts\n├── services/\n│   ├── jwt-utils.ts\n│   └── stripe-client.ts\n└── db/\n    └── client.ts"
+      }
+    ]
+  }]
+})
+```
+
 ## Output
 
 ```

package/plugins/specweave/skills/plan/SKILL.md

@@ -235,6 +235,38 @@ Planning for framework features requires different considerations than user apps
 - ACTIVE → ACTIVE (regenerate plan/tasks)
 - BACKLOG → (no change - spec.md already exists)
 
+## Markdown Preview Guidelines
+
+When the execution strategy analysis (Step 6) identifies **2+ viable execution approaches** or when task dependency ordering has meaningful alternatives, use `AskUserQuestion` with the `markdown` preview field to show DAG diagrams of task dependencies.
+
+**When to use**: Presenting execution strategy options where the task dependency graph helps visualize parallelism, critical path, or execution order trade-offs.
+
+**When NOT to use**: When there's only one viable strategy, or when the choice is purely about tooling (e.g., `/sw:do` vs `/sw:auto`) without structural implications.
+
+### Example: Task Execution Strategy with DAG Preview
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Which execution strategy should we use for this increment?",
+    header: "Strategy",
+    multiSelect: false,
+    options: [
+      {
+        label: "Parallel (Recommended)",
+        description: "Frontend and backend in parallel, merge at integration. 2 parallel lanes.",
+        markdown: "T-001 [DB Schema]  ──► T-003 [API Routes] ──┐\n                                             ├──► T-006 [E2E Tests]\nT-002 [JWT Utils]  ──► T-004 [Middleware] ──┘\n                   └──► T-005 [Frontend]  ──► T-007 [Docs]\n\nCritical path: T-001 → T-003 → T-006\nParallel lanes: 2  |  Tasks: 7"
+      },
+      {
+        label: "Sequential",
+        description: "All tasks in order. Simpler but slower, no parallelism.",
+        markdown: "T-001 [DB Schema] ──► T-002 [JWT Utils] ──► T-003 [API Routes]\n    ──► T-004 [Middleware] ──► T-005 [Frontend]\n    ──► T-006 [E2E Tests] ──► T-007 [Docs]\n\nCritical path: T-001 → T-002 → ... → T-007 (all)\nParallel lanes: 0  |  Tasks: 7"
+      }
+    ]
+  }]
+})
+```
+
 ## Related Commands
 
 - `/sw:increment` - Create new increment (generates spec.md)

package/plugins/specweave-github/lib/github-client-v2.js

@@ -336,6 +336,9 @@ ${body}`;
     const issue = JSON.parse(result.stdout);
     return {
       ...issue,
+      // gh CLI returns state as UPPERCASE ("OPEN"/"CLOSED"), normalize to lowercase
+      // for consistency with GitHub REST API which uses lowercase
+      state: issue.state?.toLowerCase() ?? issue.state,
       html_url: issue.url,
       labels: issue.labels?.map((l) => l.name) || []
     };

package/plugins/specweave-github/lib/github-client-v2.ts

@@ -445,6 +445,9 @@ export class GitHubClientV2 {
     const issue = JSON.parse(result.stdout);
     return {
       ...issue,
+      // gh CLI returns state as UPPERCASE ("OPEN"/"CLOSED"), normalize to lowercase
+      // for consistency with GitHub REST API which uses lowercase
+      state: issue.state?.toLowerCase() ?? issue.state,
       html_url: issue.url,
       labels: issue.labels?.map((l: any) => l.name) || [],
     };