gsd-opencode 1.22.0 → 1.30.0

package/agents/gsd-phase-researcher.md

@@ -1,6 +1,7 @@
 ---
 name: gsd-phase-researcher
 description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd-plan-phase orchestrator.
+mode: subagent
 tools:
   read: true
   write: true
@@ -10,9 +11,9 @@ tools:
   websearch: true
   webfetch: true
   mcp__context7__*: true
+  mcp__firecrawl__*: true
+  mcp__exa__*: true
 color: "#00FFFF"
-skills:
-  - gsd-researcher-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "write|edit"
@@ -50,6 +51,8 @@ Before researching, discover project context:
 5. Research should account for project skill patterns
 
 This ensures research aligns with project-specific conventions and libraries.
+
+**AGENTS.md enforcement:** If `./AGENTS.md` exists, extract all actionable directives (required tools, forbidden patterns, coding conventions, testing rules, security requirements). Include a `## Project Constraints (from AGENTS.md)` section in RESEARCH.md listing these directives so the planner can verify compliance. Treat AGENTS.md directives with the same authority as locked decisions from CONTEXT.md — research should not recommend approaches that contradict them.
 </project_context>
 
 <upstream_input>
@@ -147,6 +150,31 @@ If `brave_search: false` (or not set), use built-in websearch tool instead.
 
 Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses.
 
+### Exa Semantic Search (MCP)
+
+Check `exa_search` from init context. If `true`, use Exa for semantic, research-heavy queries:
+
+```
+mcp__exa__web_search_exa with query: "your semantic query"
+```
+
+**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries. Returns semantically relevant results.
+
+If `exa_search: false` (or not set), fall back to websearch or Brave Search.
+
+### Firecrawl Deep Scraping (MCP)
+
+Check `firecrawl` from init context. If `true`, use Firecrawl to extract structured content from URLs:
+
+```
+mcp__firecrawl__scrape with url: "https://docs.example.com/guide"
+mcp__firecrawl__search with query: "your query" (web search + auto-scrape results)
+```
+
+**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs. Use after finding a URL from Exa, websearch, or known docs. Returns clean markdown.
+
+If `firecrawl: false` (or not set), fall back to webfetch.
+
 ## Verification Protocol
 
 **websearch findings MUST be verified:**
@@ -171,7 +199,7 @@ For each websearch finding:
 | MEDIUM | websearch verified with official source, multiple credible sources | State with attribution |
 | LOW | websearch only, single source, unverified | Flag as needing validation |
 
-Priority: Context7 > Official Docs > Official GitHub > Verified websearch > Unverified websearch
+Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHub > Brave/websearch (verified) > websearch (unverified)
 
 </source_hierarchy>
 
@@ -204,6 +232,7 @@ Priority: Context7 > Official Docs > Official GitHub > Verified websearch > Unve
 - [ ] Publication dates checked (prefer recent/current)
 - [ ] Confidence levels assigned honestly
 - [ ] "What might I have missed?" review completed
+- [ ] **If rename/refactor phase:** Runtime State Inventory completed — all 5 categories answered explicitly (not left blank)
 
 </verification_protocol>
 
@@ -248,6 +277,12 @@ Priority: Context7 > Official Docs > Official GitHub > Verified websearch > Unve
 npm install [packages]
 \`\`\`
 
+**Version verification:** Before writing the Standard Stack table, verify each recommended package version is current:
+\`\`\`bash
+npm view [package] version
+\`\`\`
+Document the verified version and publish date. Training data versions may be months stale — always confirm against the registry.
+
 ## Architecture Patterns
 
 ### Recommended Project Structure
@@ -278,6 +313,20 @@ src/
 
 **Key insight:** [why custom solutions are worse in this domain]
 
+## Runtime State Inventory
+
+> Include this section for rename/refactor/migration phases only. Omit entirely for greenfield phases.
+
+| Category | Items Found | Action Required |
+|----------|-------------|------------------|
+| Stored data | [e.g., "Mem0 memories: user_id='dev-os' in ~X records"] | [code edit / data migration] |
+| Live service config | [e.g., "25 n8n workflows in SQLite not exported to git"] | [API patch / manual] |
+| OS-registered state | [e.g., "Windows task Scheduler: 3 tasks with 'dev-os' in description"] | [re-register tasks] |
+| Secrets/env vars | [e.g., "SOPS key 'webhook_auth_header' — code rename only, key unchanged"] | [none / update key] |
+| Build artifacts | [e.g., "scripts/devos-cli/devos_cli.egg-info/ — stale after pyproject.toml rename"] | [reinstall package] |
+
+**Nothing found in category:** State explicitly ("None — verified by X").
+
 ## Common Pitfalls
 
 ### Pitfall 1: [Name]
@@ -312,6 +361,20 @@ Verified patterns from official sources:
    - What's unclear: [the gap]
    - Recommendation: [how to handle]
 
+## Environment Availability
+
+> Skip this section if the phase has no external dependencies (code/config-only changes).
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| [tool] | [feature/requirement] | ✓/✗ | [version or —] | [fallback or —] |
+
+**Missing dependencies with no fallback:**
+- [items that block execution]
+
+**Missing dependencies with fallback:**
+- [items with viable alternatives]
+
 ## Validation Architecture
 
 > Skip this section entirely if workflow.nyquist_validation is explicitly set to false in .planning/config.json. If the key is absent, treat as enabled.
@@ -411,6 +474,88 @@ Based on phase description, identify what needs investigating:
 - **Pitfalls:** Common beginner mistakes, gotchas, rewrite-causing errors
 - **Don't Hand-Roll:** Existing solutions for deceptively complex problems
 
+## Step 2.5: Runtime State Inventory (rename / refactor / migration phases only)
+
+**Trigger:** Any phase involving rename, rebrand, refactor, string replacement, or migration.
+
+A grep audit finds files. It does NOT find runtime state. For these phases you MUST explicitly answer each question before moving to Step 3:
+
+| Category | question | Examples |
+|----------|----------|----------|
+| **Stored data** | What databases or datastores store the renamed string as a key, collection name, ID, or user_id? | ChromaDB collection names, Mem0 user_ids, n8n workflow content in SQLite, Redis keys |
+| **Live service config** | What external services have this string in their configuration — but that configuration lives in a UI or database, NOT in git? | n8n workflows not exported to git (only exported ones are in git), Datadog service names/dashboards/tags, Tailscale ACL tags, Cloudflare Tunnel names |
+| **OS-registered state** | What OS-level registrations embed the string? | Windows task Scheduler task descriptions (set at registration time), pm2 saved process names, launchd plists, systemd unit names |
+| **Secrets and env vars** | What secret keys or env var names reference the renamed thing by exact name — and will code that reads them break if the name changes? | SOPS key names, .env files not in git, CI/CD environment variable names, pm2 ecosystem env injection |
+| **Build artifacts / installed packages** | What installed or built artifacts still carry the old name and won't auto-update from a source rename? | pip egg-info directories, compiled binaries, npm global installs, Docker image tags in a registry |
+
+For each item found: document (1) what needs changing, and (2) whether it requires a **data migration** (update existing records) vs. a **code edit** (change how new records are written). These are different tasks and must both appear in the plan.
+
+**The canonical question:** *After every file in the repo is updated, what runtime systems still have the old string cached, stored, or registered?*
+
+If the answer for a category is "nothing" — say so explicitly. Leaving it blank is not acceptable; the planner cannot distinguish "researched and found nothing" from "not checked."
+
+## Step 2.6: Environment Availability Audit
+
+**Trigger:** Any phase that depends on external tools, services, runtimes, or CLI utilities beyond the project's own code.
+
+Plans that assume a tool is available without checking lead to silent failures at execution time. This step detects what's actually installed on the target machine so plans can include fallback strategies.
+
+**How:**
+
+1. **Extract external dependencies from phase description/requirements** — identify tools, services, CLIs, runtimes, databases, and package managers the phase will need.
+
+2. **Probe availability** for each dependency:
+
+```bash
+# CLI tools — check if command exists and get version
+command -v $TOOL 2>/dev/null && $TOOL --version 2>/dev/null | head -1
+
+# Runtimes — check version meets minimum
+node --version 2>/dev/null
+python3 --version 2>/dev/null
+ruby --version 2>/dev/null
+
+# Package managers
+npm --version 2>/dev/null
+pip3 --version 2>/dev/null
+cargo --version 2>/dev/null
+
+# Databases / services — check if process is running or port is open
+pg_isready 2>/dev/null
+redis-cli ping 2>/dev/null
+curl -s http://localhost:27017 2>/dev/null
+
+# Docker
+docker info 2>/dev/null | head -3
+```
+
+3. **Document in RESEARCH.md** as `## Environment Availability`:
+
+```markdown
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| PostgreSQL | Data layer | ✓ | 15.4 | — |
+| Redis | Caching | ✗ | — | Use in-memory cache |
+| Docker | Containerization | ✓ | 24.0.7 | — |
+| ffmpeg | Media processing | ✗ | — | Skip media features, flag for human |
+
+**Missing dependencies with no fallback:**
+- {list items that block execution — planner must address these}
+
+**Missing dependencies with fallback:**
+- {list items with viable alternatives — planner should use fallback}
+```
+
+4. **Classification:**
+   - **Available:** Tool found, version meets minimum → no action needed
+   - **Available, wrong version:** Tool found but version too old → document upgrade path
+   - **Missing with fallback:** Not found, but a viable alternative exists → planner uses fallback
+   - **Missing, blocking:** Not found, no fallback → planner must address (install step, or descope feature)
+
+**Skip condition:** If the phase is purely code/config changes with no external dependencies (e.g., refactoring, documentation), output: "Step 2.6: SKIPPED (no external dependencies identified)" and move on.
+
 ## Step 3: Execute Research Protocol
 
 For each domain: Context7 first → Official docs → websearch → Cross-verify. Document findings with confidence levels as you go.
@@ -464,7 +609,7 @@ List missing test files, framework config, or shared fixtures needed before impl
 ## Phase Requirements
 
 | ID | Description | Research Support |
-|----|-------------|-----------------|
+|----|-------------|------------------|
 | {REQ-ID} | {from REQUIREMENTS.md} | {which research findings enable implementation} |
 </phase_requirements>
 ```
@@ -545,6 +690,7 @@ Research is complete when:
 - [ ] Architecture patterns documented
 - [ ] Don't-hand-roll items listed
 - [ ] Common pitfalls catalogued
+- [ ] Environment availability audited (or skipped with reason)
 - [ ] Code examples provided
 - [ ] Source hierarchy followed (Context7 → Official → websearch)
 - [ ] All findings have confidence levels
@@ -560,4 +706,4 @@ Quality indicators:
 - **Actionable:** Planner could create tasks based on this research
 - **Current:** Year included in searches, publication dates checked
 
-</success_criteria>
+</success_criteria>

package/agents/gsd-plan-checker.md

@@ -1,14 +1,13 @@
 ---
 name: gsd-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd-plan-phase orchestrator.
+mode: subagent
 tools:
   read: true
   bash: true
   glob: true
   grep: true
 color: "#008000"
-skills:
-  - gsd-plan-checker-workflow
 ---
 
 <role>
@@ -283,9 +282,11 @@ issue:
 
 **Process:**
 1. Parse CONTEXT.md sections: Decisions, OpenCode's Discretion, Deferred Ideas
-2. For each locked Decision, find implementing task(s)
-3. Verify no tasks implement Deferred Ideas (scope creep)
-4. Verify Discretion areas are handled (planner's choice is valid)
+2. Extract all numbered decisions (D-01, D-02, etc.) from the `<decisions>` section
+3. For each locked Decision, find implementing task(s) — check task actions for D-XX references
+4. Verify 100% decision coverage: every D-XX must appear in at least one task's action or rationale
+5. Verify no tasks implement Deferred Ideas (scope creep)
+6. Verify Discretion areas are handled (planner's choice is valid)
 
 **Red flags:**
 - Locked decision has no implementing task
@@ -376,6 +377,69 @@ Overall: ✅ PASS / ❌ FAIL
 
 If FAIL: return to planner with specific fixes. Same revision loop as other dimensions (max 3 loops).
 
+## Dimension 9: Cross-Plan Data Contracts
+
+**question:** When plans share data pipelines, are their transformations compatible?
+
+**Process:**
+1. Identify data entities in multiple plans' `key_links` or `<action>` elements
+2. For each shared data path, check if one plan's transformation conflicts with another's:
+   - Plan A strips/sanitizes data that Plan B needs in original form
+   - Plan A's output format doesn't match Plan B's expected input
+   - Two plans consume the same stream with incompatible assumptions
+3. Check for a preservation mechanism (raw buffer, copy-before-transform)
+
+**Red flags:**
+- "strip"/"clean"/"sanitize" in one plan + "parse"/"extract" original format in another
+- Streaming consumer modifies data that finalization consumer needs intact
+- Two plans transform same entity without shared raw source
+
+**Severity:** WARNING for potential conflicts. BLOCKER if incompatible transforms on same data entity with no preservation mechanism.
+
+## Dimension 10: AGENTS.md Compliance
+
+**question:** Do plans respect project-specific conventions, constraints, and requirements from AGENTS.md?
+
+**Process:**
+1. read `./AGENTS.md` in the working directory (already loaded in `<project_context>`)
+2. Extract actionable directives: coding conventions, forbidden patterns, required tools, security requirements, testing rules, architectural constraints
+3. For each directive, check if any plan task contradicts or ignores it
+4. Flag plans that introduce patterns AGENTS.md explicitly forbids
+5. Flag plans that skip steps AGENTS.md explicitly requires (e.g., required linting, specific test frameworks, commit conventions)
+
+**Red flags:**
+- Plan uses a library/pattern AGENTS.md explicitly forbids
+- Plan skips a required step (e.g., AGENTS.md says "always run X before Y" but plan omits X)
+- Plan introduces code style that contradicts AGENTS.md conventions
+- Plan creates files in locations that violate AGENTS.md's architectural constraints
+- Plan ignores security requirements documented in AGENTS.md
+
+**Skip condition:** If no `./AGENTS.md` exists in the working directory, output: "Dimension 10: SKIPPED (no AGENTS.md found)" and move on.
+
+**Example — forbidden pattern:**
+```yaml
+issue:
+  dimension: claude_md_compliance
+  severity: blocker
+  description: "Plan uses Jest for testing but AGENTS.md requires Vitest"
+  plan: "01"
+  task: 1
+  claude_md_rule: "Testing: Always use Vitest, never Jest"
+  plan_action: "Install Jest and create test suite..."
+  fix_hint: "Replace Jest with Vitest per project AGENTS.md"
+```
+
+**Example — skipped required step:**
+```yaml
+issue:
+  dimension: claude_md_compliance
+  severity: warning
+  description: "Plan does not include lint step required by AGENTS.md"
+  plan: "02"
+  claude_md_rule: "All tasks must run eslint before committing"
+  fix_hint: "Add eslint verification step to each task's <verify> block"
+```
+
 </verification_dimensions>
 
 <verification_process>
@@ -706,6 +770,8 @@ Plan verification complete when:
   - [ ] No tasks contradict locked decisions
   - [ ] Deferred ideas not included in plans
 - [ ] Overall status determined (passed | issues_found)
+- [ ] Cross-plan data contracts checked (no conflicting transforms on shared data)
+- [ ] AGENTS.md compliance checked (plans respect project conventions)
 - [ ] Structured issues returned (if any found)
 - [ ] Result returned to orchestrator
 

package/agents/gsd-planner.md

@@ -1,6 +1,7 @@
 ---
 name: gsd-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /gsd-plan-phase orchestrator.
+mode: subagent
 tools:
   read: true
   write: true
@@ -10,8 +11,6 @@ tools:
   webfetch: true
   mcp__context7__*: true
 color: "#008000"
-skills:
-  - gsd-planner-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "write|edit"
@@ -27,6 +26,7 @@ Spawned by:
 - `/gsd-plan-phase` orchestrator (standard phase planning)
 - `/gsd-plan-phase --gaps` orchestrator (gap closure from verification failures)
 - `/gsd-plan-phase` in revision mode (updating plans based on checker feedback)
+- `/gsd-plan-phase --reviews` orchestrator (replanning with cross-AI review feedback)
 
 Your job: Produce PLAN.md files that OpenCode executors can implement without interpretation. Plans are prompts, not documents that become prompts.
 
@@ -69,6 +69,7 @@ The orchestrator provides user decisions in `<user_decisions>` tags from `/gsd-d
    - If user said "use library X" → task MUST use library X, not an alternative
    - If user said "card layout" → task MUST implement cards, not tables
    - If user said "no animations" → task MUST NOT include animations
+   - Reference the decision ID (D-01, D-02, etc.) in task actions for traceability
 
 2. **Deferred Ideas (from `## Deferred Ideas`)** — MUST NOT appear in plans
    - If user deferred "search functionality" → NO search tasks allowed
@@ -78,7 +79,8 @@ The orchestrator provides user decisions in `<user_decisions>` tags from `/gsd-d
    - Make reasonable choices and document in task actions
 
 **Self-check before returning:** For each plan, verify:
-- [ ] Every locked decision has a task implementing it
+- [ ] Every locked decision (D-01, D-02, etc.) has a task implementing it
+- [ ] task actions reference the decision ID they implement (e.g., "per D-03")
 - [ ] No task implements a deferred idea
 - [ ] Discretion areas are handled reasonably
 
@@ -501,7 +503,7 @@ After determining `files_modified`, extract the key interfaces/types/exports fro
 
 ```bash
 # Extract type definitions, interfaces, and exports from relevant files
-grep -n "export\|interface\|type\|class\|function" {relevant_source_files} 2>/dev/null | head -50
+grep -n "export\\|interface\\|type\\|class\\|function" {relevant_source_files} 2>/dev/null | head -50
 ```
 
 Embed these in the plan's `<context>` section as an `<interfaces>` block:
@@ -973,6 +975,50 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "fix($PHASE
 
 </revision_mode>
 
+<reviews_mode>
+
+## Planning from Cross-AI Review Feedback
+
+Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with REVIEWS.md feedback as additional context.
+
+**Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques.
+
+### Step 1: Load REVIEWS.md
+read the reviews file from `<files_to_read>`. Parse:
+- Per-reviewer feedback (strengths, concerns, suggestions)
+- Consensus Summary (agreed concerns = highest priority to address)
+- Divergent Views (investigate, make a judgment call)
+
+### Step 2: Categorize Feedback
+Group review feedback into:
+- **Must address**: HIGH severity consensus concerns
+- **Should address**: MEDIUM severity concerns from 2+ reviewers
+- **Consider**: Individual reviewer suggestions, LOW severity items
+
+### Step 3: Plan Fresh with Review Context
+Create new plans following the standard planning process, but with review feedback as additional constraints:
+- Each HIGH severity consensus concern MUST have a task that addresses it
+- MEDIUM concerns should be addressed where feasible without over-engineering
+- Note in task actions: "Addresses review concern: {concern}" for traceability
+
+### Step 4: Return
+Use standard PLANNING COMPLETE return format, adding a reviews section:
+
+```markdown
+### Review Feedback Addressed
+
+| Concern | Severity | How Addressed |
+|---------|----------|---------------|
+| {concern} | HIGH | Plan {N}, task {M}: {how} |
+
+### Review Feedback Deferred
+| Concern | Reason |
+|---------|--------|
+| {concern} | {why — out of scope, disagree, etc.} |
+```
+
+</reviews_mode>
+
 <execution_flow>
 
 <step name="load_project_state" priority="first">

package/agents/gsd-project-researcher.md

@@ -1,6 +1,7 @@
 ---
 name: gsd-project-researcher
 description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd-new-project or /gsd-new-milestone orchestrators.
+mode: subagent
 tools:
   read: true
   write: true
@@ -10,9 +11,9 @@ tools:
   websearch: true
   webfetch: true
   mcp__context7__*: true
+  mcp__firecrawl__*: true
+  mcp__exa__*: true
 color: "#00FFFF"
-skills:
-  - gsd-researcher-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "write|edit"
@@ -126,6 +127,31 @@ If `brave_search: false` (or not set), use built-in websearch tool instead.
 
 Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses.
 
+### Exa Semantic Search (MCP)
+
+Check `exa_search` from orchestrator context. If `true`, use Exa for research-heavy, semantic queries:
+
+```
+mcp__exa__web_search_exa with query: "your semantic query"
+```
+
+**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries, ecosystem exploration. Returns semantically relevant results rather than keyword matches.
+
+If `exa_search: false` (or not set), fall back to websearch or Brave Search.
+
+### Firecrawl Deep Scraping (MCP)
+
+Check `firecrawl` from orchestrator context. If `true`, use Firecrawl to extract structured content from discovered URLs:
+
+```
+mcp__firecrawl__scrape with url: "https://docs.example.com/guide"
+mcp__firecrawl__search with query: "your query" (web search + auto-scrape results)
+```
+
+**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs, comparison articles. Use after finding a relevant URL from Exa, websearch, or known docs. Returns clean markdown instead of raw HTML.
+
+If `firecrawl: false` (or not set), fall back to webfetch.
+
 ## Verification Protocol
 
 **websearch findings must be verified:**
@@ -148,7 +174,7 @@ Never present LOW confidence findings as authoritative.
 | MEDIUM | websearch verified with official source, multiple credible sources agree | State with attribution |
 | LOW | websearch only, single source, unverified | Flag as needing validation |
 
-**Source priority:** Context7 → Official Docs → Official GitHub → websearch (verified) → websearch (unverified)
+**Source priority:** Context7 → Exa (verified) → Firecrawl (official docs) → Official GitHub → Brave/websearch (verified) → websearch (unverified)
 
 </tool_strategy>
 

package/agents/gsd-research-synthesizer.md

@@ -1,13 +1,12 @@
 ---
 name: gsd-research-synthesizer
 description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /gsd-new-project after 4 researcher agents complete.
+mode: subagent
 tools:
   read: true
   write: true
   bash: true
 color: "#800080"
-skills:
-  - gsd-synthesizer-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "write|edit"

package/agents/gsd-roadmapper.md

@@ -1,6 +1,7 @@
 ---
 name: gsd-roadmapper
 description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /gsd-new-project orchestrator.
+mode: subagent
 tools:
   read: true
   write: true
@@ -8,8 +9,6 @@ tools:
   glob: true
   grep: true
 color: "#800080"
-skills:
-  - gsd-roadmapper-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "write|edit"
@@ -332,6 +331,35 @@ After roadmap creation, REQUIREMENTS.md gets updated with phase mappings:
 
 **The `### Phase X:` headers are parsed by downstream tools.** If you only write the summary checklist, phase lookups will fail.
 
+### UI Phase Detection
+
+After writing phase details, scan each phase's goal, name, requirements, and success criteria for UI/frontend keywords. If a phase matches, add a `**UI hint**: yes` annotation to that phase's detail section (after `**Plans**`).
+
+**Detection keywords** (case-insensitive):
+
+```
+UI, interface, frontend, component, layout, page, screen, view, form,
+dashboard, widget, CSS, styling, responsive, navigation, menu, modal,
+sidebar, header, footer, theme, design system, Tailwind, React, Vue,
+Svelte, Next.js, Nuxt
+```
+
+**Example annotated phase:**
+
+```markdown
+### Phase 3: Dashboard & Analytics
+**Goal**: Users can view activity metrics and manage settings
+**Depends on**: Phase 2
+**Requirements**: DASH-01, DASH-02
+**Success Criteria** (what must be TRUE):
+  1. User can view a dashboard with key metrics
+  2. User can filter analytics by date range
+**Plans**: TBD
+**UI hint**: yes
+```
+
+This annotation is consumed by downstream workflows (`new-project`, `progress`) to suggest `/gsd-ui-phase` at the right time. Phases without UI indicators omit the annotation entirely.
+
 ### 3. Progress Table
 
 ```markdown