@brunosps00/dev-workflow 1.0.1 → 1.0.4

package/scaffold/en/commands/dw-install-aws-skills.md

@@ -0,0 +1,166 @@
+<system_instructions>
+You install opt-in AWS agent skills from `aws/agent-toolkit-for-aws` (Apache 2.0) into `.agents/skills/aws/` and register the unified AWS MCP Server (stdio via `uvx mcp-proxy-for-aws`, requires AWS credentials) in `.claude/settings.json`. Same outcome as `npx @brunosps00/dev-workflow install-aws-skills` — different interface.
+
+## When to Use
+- Use when the user asks to "install AWS skills", "setup AWS MCP", "add AWS expertise", "I'm going to work on AWS", or similar.
+- Use when an existing project starts a new feature that touches AWS (Lambda, S3, Bedrock, EC2, etc.) and there is no `.agents/skills/aws/` yet.
+- Do NOT use for Azure, GCP, or non-AWS clouds — those have their own commands or aren't supported.
+- Do NOT use to install dev-workflow's own skills — those ship with `init`/`update`.
+
+## Pipeline Position
+**Predecessor:** (user explicit request) | **Successor:** any AWS-shaped feature work (typically `/dw-plan` or `/dw-autopilot`).
+
+## Prerequisites
+
+<critical>This command needs:
+1. `git` available on PATH.
+2. `uv` (Python tool runner) — provides `uvx` which invokes `mcp-proxy-for-aws`.
+3. `aws cli` ≥ 2.32.0.
+4. Valid AWS credentials — verify with `aws sts get-caller-identity`.
+
+If ANY of these is missing or invalid, STOP and tell the user how to install/configure it. Do NOT clone or copy anything if prerequisites are not met — partial install is worse than no install.</critical>
+
+## Categories (upstream-native)
+
+| Category | Upstream paths |
+|---|---|
+| **All** | `skills/core-skills/*` + `skills/specialized-skills/*/*` |
+| **Core** | `skills/core-skills/*` — 13 horizontal skills: amazon-bedrock, aws-amplify, aws-billing-and-cost-management, aws-cdk, aws-cloudformation, aws-containers, aws-iam, aws-messaging-and-streaming, aws-observability, aws-sdk-js-v3-usage, aws-sdk-python-usage, aws-sdk-swift-usage, aws-serverless |
+| **Analytics** | `skills/specialized-skills/analytics-skills/*` |
+| **Database** | `skills/specialized-skills/database-skills/*` |
+| **EC2 / Compute** | `skills/specialized-skills/ec2-skills/*` |
+| **Migration & Modernization** | `skills/specialized-skills/migration-and-modernization-skills/*` |
+| **Networking & Content Delivery** | `skills/specialized-skills/networking-and-content-delivery-skills/*` |
+| **Operations** | `skills/specialized-skills/operations-skills/*` |
+| **Security & Identity** | `skills/specialized-skills/security-and-identity-skills/*` |
+| **Serverless** | `skills/specialized-skills/serverless-skills/*` |
+| **Storage** | `skills/specialized-skills/storage-skills/*` |
+
+## Workflow
+
+### 1. Verify prerequisites
+
+Run each in turn via Bash. On any failure, STOP and print the matching instruction block:
+
+| Check | If missing |
+|---|---|
+| `git --version` | `git is required. Install via brew/apt/git-scm.com.` |
+| `uv --version` | `uv is required. Install: curl -LsSf https://astral.sh/uv/install.sh \| sh` (macOS/Linux) or PowerShell equivalent on Windows. |
+| `aws --version` | `aws cli ≥ 2.32.0 is required. Install via brew install awscli, winget install Amazon.AWSCLI, or follow AWS docs.` |
+| `aws sts get-caller-identity` | `AWS credentials are missing/expired. Easiest: aws login (rotates every 15 min, valid 12h). SSO: aws configure sso. Keys: aws configure.` |
+
+Do NOT proceed to step 2 if any check fails.
+
+### 2. Pick region
+
+Ask the user which AWS region to use. The MCP server is regional — currently supported endpoints:
+
+- `us-east-1` → `https://aws-mcp.us-east-1.api.aws/mcp`
+- `eu-central-1` → `https://aws-mcp.eu-central-1.api.aws/mcp`
+
+Default to `us-east-1` if the user has no preference. The agent can override per-query (e.g., "list EC2 instances in eu-west-1") — the endpoint region is just the default operating region.
+
+### 3. Ask which categories to install
+
+Use AskUserQuestion (multi-select if supported; otherwise loop). Present the 11 categories above. Default suggestion when undecided: ask "what part of AWS are you about to work on?" and map to a category.
+
+### 4. Shallow clone the upstream repo
+
+```bash
+TMP=$(mktemp -d -t dw-aws-skills-XXXXXX)
+git clone --depth=1 https://github.com/aws/agent-toolkit-for-aws.git "$TMP"
+```
+
+If the clone fails, STOP and report the error verbatim.
+
+### 5. Filter and copy
+
+For each selected category, glob the corresponding upstream path and collect all skill directories. Examples:
+
+- "Core" → every subdirectory of `$TMP/skills/core-skills/`
+- "Database" → every subdirectory of `$TMP/skills/specialized-skills/database-skills/`
+- "All" → every subdirectory of `$TMP/skills/core-skills/` AND every subdirectory of `$TMP/skills/specialized-skills/*/`
+
+Before copying, **clear** `.agents/skills/aws/` for a clean refresh (re-runs replace previous selections).
+
+Skip any skill whose root contains executable scripts (`.sh`, `.py`, `.js`, `.ts`, `.ps1`, `.bat`) — dev-workflow only installs pure-markdown skills. Report the skipped count.
+
+Copy each matched directory recursively to `.agents/skills/aws/<skill-name>/`. **Flatten** the upstream hierarchy — the destination has no `core-skills/` vs `specialized-skills/` split. Just the skill slug as the directory name.
+
+### 6. Register the AWS MCP Server
+
+Read `.claude/settings.json`. Parse the JSON. Upsert into `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "aws-mcp": {
+      "command": "uvx",
+      "args": [
+        "mcp-proxy-for-aws@latest",
+        "https://aws-mcp.us-east-1.api.aws/mcp",
+        "--metadata",
+        "AWS_REGION=us-east-1"
+      ],
+      "transport": "stdio",
+      "timeout": 100000
+    }
+  }
+}
+```
+
+Substitute the endpoint and `AWS_REGION` value with the region picked in step 2.
+
+If `mcpServers.aws-mcp` already exists, leave it untouched — never overwrite. Tell the user to edit `.claude/settings.json` directly (or remove the entry and re-run) to change the region. Other entries in `mcpServers` (context7, playwright, microsoft-learn, etc.) MUST be preserved.
+
+### 7. Write `.dw/references/aws-mcp-instructions.md`
+
+Create (overwrite if present) with the canonical agent-facing guidance — the 5 MCP tools (`aws___search_documentation`, `aws___read_documentation`, `aws___retrieve_skill`, `aws___call_aws`, `aws___run_script`), the destructive-operations protocol (confirm before any `create*`/`update*`/`delete*`/`modify*`/IAM/billing call), region behavior, source-grounding discipline, refresh/uninstall.
+
+The CLI version of this command (`npx @brunosps00/dev-workflow install-aws-skills`) ships the canonical text. If running as a slash command, replicate the same content from `lib/install-aws-skills.js` `AWS_MCP_INSTRUCTIONS` constant.
+
+### 8. Cleanup
+
+Remove `$TMP`. Always — even if earlier steps failed.
+
+### 9. Report
+
+```
+## AWS skills installed
+
+Categories: [list]
+Region: us-east-1 (or chosen)
+Skills copied: N (skipped M with executable scripts)
+MCP registered: aws-mcp (or "already present, left unchanged")
+Agent instructions: .dw/references/aws-mcp-instructions.md
+
+## Next steps
+
+1. Restart Claude Code (or Codex / Copilot / OpenCode) so the MCP loads.
+2. Validate with an AWS question, e.g. "What's the Lambda concurrent execution limit?"
+3. The agent can now call AWS APIs via aws___call_aws — review
+   .dw/references/aws-mcp-instructions.md for destructive-op protocol.
+4. To refresh from upstream, re-run /dw-install-aws-skills.
+5. To uninstall: rm -rf .agents/skills/aws/ and remove the "aws-mcp"
+   entry from .claude/settings.json mcpServers.
+```
+
+## Required Behavior
+
+<critical>NEVER add `aws-mcp` MCP outside of this command. It is opt-in. `init` and `update` MUST NOT touch it.</critical>
+
+<critical>NEVER register the deprecated AWS Knowledge MCP (`https://knowledge-mcp.global.api.aws`). AWS officially superseded it with the unified AWS MCP Server; registering both causes tool conflicts that confuse agents.</critical>
+
+<critical>NEVER auto-install `uv` or `aws cli`. Print the instruction block and let the user choose their install path. This avoids breaking the user's environment with package managers we don't own.</critical>
+
+<critical>NEVER skip the credentials check. A clean install with no working `aws sts get-caller-identity` produces a broken MCP that fails on every tool call. Better to stop and instruct.</critical>
+
+<critical>NEVER copy upstream LICENSE/README/CONTRIBUTING into `.agents/skills/aws/` — those belong to AWS and pollute skill discovery. Copy only per-skill `SKILL.md` + auxiliary content (references/, assets/).</critical>
+
+<critical>NEVER copy skills with executable scripts. The dev-workflow scope is markdown-only. If a skill needs scripts, the user should install it directly from the upstream repo, not through this command.</critical>
+
+## Attribution
+
+Skills come from [`aws/agent-toolkit-for-aws`](https://github.com/aws/agent-toolkit-for-aws) (Apache 2.0, by AWS). The MCP server is documented at [docs.aws.amazon.com/aws-mcp/](https://docs.aws.amazon.com/aws-mcp/). The proxy is [`aws/mcp-proxy-for-aws`](https://github.com/aws/mcp-proxy-for-aws). dev-workflow only orchestrates the install.
+
+</system_instructions>

package/scaffold/en/commands/dw-install-azure-skills.md

@@ -0,0 +1,138 @@
+<system_instructions>
+You install opt-in Azure agent skills from `MicrosoftDocs/Agent-Skills` (CC-BY-4.0) into `.agents/skills/azure/` and register the Microsoft Learn MCP Server (HTTP, no-auth) in `.claude/settings.json`. Same outcome as `npx @brunosps00/dev-workflow install-azure-skills` — different interface.
+
+## When to Use
+- Use when the user asks to "install Azure skills", "setup Microsoft docs MCP", "add Azure expertise", "I'm going to work on Azure", or similar.
+- Use when an existing project starts a new feature that touches Azure (Container Apps, OpenAI, AKS, etc.) and there is no `.agents/skills/azure/` yet.
+- Do NOT use for AWS, GCP, or any non-Microsoft cloud — those are not in the upstream repo.
+- Do NOT use to install dev-workflow's own skills — those ship with `init`/`update`.
+
+## Pipeline Position
+**Predecessor:** (user explicit request) | **Successor:** any Azure-shaped feature work (typically `/dw-plan` or `/dw-autopilot`).
+
+## Prerequisites
+
+<critical>This command needs `git` available on PATH. If `git --version` fails, STOP and tell the user to install git first.</critical>
+
+## Categories (curated)
+
+| Category | What it covers |
+|---|---|
+| All | Every skill in the upstream `skills/` directory. |
+| Compute | AKS, App Service, Container Apps/Instances/Registry, Functions, VMs, Batch, Spring Apps. |
+| Data & Storage | Blob, Cosmos DB, SQL, MySQL, PostgreSQL, Cache for Redis, Data Lake, Files, Table/Queue Storage, Managed Disks. |
+| AI & ML | OpenAI, AI Foundry, AI Vision, AI Search, AI Services, Machine Learning, Anomaly Detector, Bot Service, Cognitive Services. |
+| Networking | Application Gateway, Front Door, Load Balancer, VPN Gateway, ExpressRoute, Bastion, DNS, CDN, Virtual Network, Virtual WAN, Private Link, Network Watcher, Firewall, Traffic Manager. |
+| Identity & Security | Entra ID (Active Directory), Key Vault, Attestation, Defender, Sentinel, Security Center, Artifact Signing. |
+| DevOps | Boards, Pipelines, Artifacts, Repos, Azure DevOps Server, Test Plans. |
+| Observability | Monitor, Application Insights, Log Analytics. |
+| Integration | Logic Apps, Service Bus, Event Grid, Event Hubs, API Management, API Center, Business Process Tracking. |
+| Architecture | Architecture guidance, Advisor, Blueprints, Well-Architected, Policy, Resource Graph, Resource Manager. |
+
+## Workflow
+
+### 1. Verify `git`
+
+Run `git --version` via Bash. On failure, STOP with: `git is required to install Azure skills. Install git and re-run.`
+
+### 2. Ask the user which categories to install
+
+Use AskUserQuestion (multi-select if your interface supports it; otherwise loop). Present the 10 categories with their one-line descriptions. Default suggestion when the user is undecided: ask "what part of Azure are you about to work on?" and map their answer to a category.
+
+### 3. Shallow clone the upstream repo
+
+```bash
+TMP=$(mktemp -d -t dw-azure-skills-XXXXXX)
+git clone --depth=1 https://github.com/MicrosoftDocs/Agent-Skills.git "$TMP"
+```
+
+If the clone fails (network, GitHub rate limit, etc.), STOP and report the error verbatim. Do not partially install.
+
+### 4. Filter and copy
+
+For each subdirectory of `$TMP/skills/`, decide whether it matches the selected categories. The match is **prefix-based** — a directory name like `azure-aks-edge-essentials` matches the prefix `azure-aks`.
+
+**Prefix table (canonical — keep in sync with `lib/azure-categories.js` in the dev-workflow repo):**
+
+| Category | Prefixes |
+|---|---|
+| **All** | (every directory under `$TMP/skills/`) |
+| **Compute** | `azure-aks`, `azure-app-service`, `azure-container-apps`, `azure-container-instances`, `azure-container-registry`, `azure-functions`, `azure-virtual-machines`, `azure-vmware-solution`, `azure-batch`, `azure-spring-apps` |
+| **Data & Storage** | `azure-blob-storage`, `azure-cosmos-db`, `azure-sql`, `azure-database-for-mysql`, `azure-database-for-postgresql`, `azure-cache-redis`, `azure-data-lake`, `azure-files`, `azure-storage`, `azure-table-storage`, `azure-queue-storage`, `azure-managed-disk` |
+| **AI & ML** | `azure-openai`, `azure-ai-foundry`, `azure-ai-vision`, `azure-ai-search`, `azure-ai-services`, `azure-machine-learning`, `azure-anomaly-detector`, `azure-bot-service`, `azure-cognitive` |
+| **Networking** | `azure-application-gateway`, `azure-front-door`, `azure-load-balancer`, `azure-vpn-gateway`, `azure-expressroute`, `azure-bastion`, `azure-dns`, `azure-cdn`, `azure-virtual-network`, `azure-virtual-wan`, `azure-private-link`, `azure-network-watcher`, `azure-firewall`, `azure-traffic-manager` |
+| **Identity & Security** | `azure-active-directory`, `azure-entra`, `azure-key-vault`, `azure-attestation`, `azure-defender`, `azure-sentinel`, `azure-security-center`, `azure-artifact-signing` |
+| **DevOps** | `azure-boards`, `azure-pipelines`, `azure-artifacts`, `azure-repos`, `azure-devops`, `azure-test-plans` |
+| **Observability** | `azure-monitor`, `azure-application-insights`, `azure-log-analytics` |
+| **Integration** | `azure-logic-apps`, `azure-service-bus`, `azure-event-grid`, `azure-event-hubs`, `azure-api-management`, `azure-api-center`, `azure-business-process-tracking` |
+| **Architecture** | `azure-architecture`, `azure-advisor`, `azure-blueprints`, `azure-well-architected`, `azure-policy`, `azure-resource-graph`, `azure-resource-manager` |
+
+A directory matches a category if its name equals one of the prefixes OR starts with `<prefix>-`.
+
+Before copying, **clear** `.agents/skills/azure/` to ensure a clean refresh (re-runs replace previous selections; this is intentional).
+
+Skip any skill whose root contains executable scripts (`.sh`, `.py`, `.js`, `.ts`, `.ps1`, `.bat`) — dev-workflow only installs pure markdown skills. Report the skipped count.
+
+Copy each matched directory recursively to `.agents/skills/azure/<skill-name>/`. Preserve subdirectories (`references/`, `assets/`).
+
+### 5. Register the Microsoft Learn MCP server
+
+Read `.claude/settings.json` (create the directory if missing). Parse the JSON. Upsert into `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "microsoft-learn": {
+      "type": "http",
+      "url": "https://learn.microsoft.com/api/mcp"
+    }
+  }
+}
+```
+
+If `mcpServers.microsoft-learn` already exists, leave it untouched — never overwrite user config. Other entries in `mcpServers` (context7, playwright, etc.) MUST be preserved.
+
+### 6. Write `.dw/references/azure-mcp-instructions.md`
+
+Create this file (overwrite if present) with the agent-facing guidance — when to call which MCP tool (`microsoft_docs_search`, `microsoft_docs_fetch`, `microsoft_code_sample_search`), how to cite sources per `dw-source-grounding`, and how to refresh or uninstall.
+
+The CLI version of this command (`npx @brunosps00/dev-workflow install-azure-skills`) ships the canonical text of this file — if you are running as a slash command, replicate the same content from `lib/install-azure-skills.js` `AZURE_MCP_INSTRUCTIONS` constant.
+
+### 7. Cleanup
+
+Remove `$TMP`. Always — even if earlier steps failed.
+
+### 8. Report
+
+```
+## Azure skills installed
+
+Categories: [list]
+Skills copied: N (skipped M with executable scripts)
+MCP registered: microsoft-learn (or "already present, left unchanged")
+Agent instructions: .dw/references/azure-mcp-instructions.md
+
+## Next steps
+
+1. Restart Claude Code (or Codex / Copilot / OpenCode) so the MCP loads.
+2. Validate with an Azure question, e.g. "How do I deploy to Azure Container Apps?"
+3. To refresh from upstream, re-run /dw-install-azure-skills.
+4. To uninstall: rm -rf .agents/skills/azure/ and remove the "microsoft-learn"
+   entry from .claude/settings.json mcpServers.
+```
+
+## Required Behavior
+
+<critical>NEVER add `microsoft-learn` MCP outside of this command. It is opt-in. `init` and `update` MUST NOT touch it.</critical>
+
+<critical>NEVER copy skills with executable scripts. The dev-workflow scope is markdown-only. If a skill needs scripts, the user should install it directly from the upstream repo, not through this command.</critical>
+
+<critical>NEVER fabricate the upstream URL or the MCP URL. The repo is `https://github.com/MicrosoftDocs/Agent-Skills.git` and the MCP endpoint is `https://learn.microsoft.com/api/mcp`. These are first-party Microsoft endpoints with CC-BY-4.0 attribution required.</critical>
+
+<critical>NEVER copy upstream LICENSE/README files into `.agents/skills/azure/` — those belong to Microsoft and pollute the agent's skill discovery. Copy only `SKILL.md` + per-skill auxiliary content (references/, assets/).</critical>
+
+## Attribution
+
+Skills come from [`MicrosoftDocs/Agent-Skills`](https://github.com/MicrosoftDocs/Agent-Skills) (CC-BY-4.0, by Microsoft). The MCP server is documented at [Microsoft Learn](https://learn.microsoft.com/en-us/training/support/mcp-get-started). dev-workflow only orchestrates the install — no upstream content is modified beyond directory placement.
+
+</system_instructions>

package/scaffold/en/commands/dw-intel.md

@@ -38,9 +38,10 @@ You are the codebase intelligence assistant. Two modes: query the existing index
 
 ## File Locations
 
-- Machine-readable intel (queried first): `.dw/intel/{stack,files,apis,deps}.json` + `.dw/intel/arch.md`
+- Machine-readable intel (queried first): `.dw/intel/{stack,files,apis,deps,bugfixes}.json` + `.dw/intel/arch.md`
 - Refresh metadata: `.dw/intel/.last-refresh.json`
-- Human-readable rules (queried second): `.dw/rules/{index,<module>,integrations}.md`
+- Human-readable rules (queried second): `.dw/rules/{index,<module>,integrations,concerns}.md`
+- Bugfix history source: `.dw/bugfixes/*/SUMMARY.md`
 - Direct grep fallback (queried last): the project source files
 
 ## Required Behavior
@@ -67,6 +68,8 @@ Classify the user's `{{QUERY}}` into one of the shapes documented in `.agents/sk
 - **api-list** — primary: `apis.json`
 - **find-export** — primary: `files.json` (search `exports` arrays)
 - **convention** — primary: `arch.md`, secondary: `.dw/rules/`
+- **bugfix-history** — primary: `bugfixes.json`, secondary: `.dw/rules/concerns.md` (triggers: "bugs in <module>", "recent fixes", "what broke in X", "fix history for Y")
+- **risk-area** — primary: `.dw/rules/concerns.md`, secondary: `bugfixes.json` (triggers: "is X risky", "what's fragile", "hot spots", "tech debt")
 
 ### 3. Search execution
 
@@ -143,7 +146,31 @@ When invoked with `--build`, the command produces or refreshes the queryable int
 5. **API extraction.** Routes, RPC handlers, GraphQL resolvers, public CLI surface. Output to `.dw/intel/apis.json`. Budget ≤1.5K tokens.
 6. **Dependency map.** Internal cross-module imports + external packages with `used_by` arrays. Output to `.dw/intel/deps.json`. Budget ≤1K tokens.
 7. **Architecture summary.** Prose document describing the project's shape, key patterns, request flows, deployment topology. Output to `.dw/intel/arch.md`. Budget ≤1.5K tokens.
-8. **Refresh metadata.** Write `.dw/intel/.last-refresh.json` with `updated_at`, `version`, `mode` (full or incremental), files-scanned count.
+8. **Bugfix history.** If `.dw/bugfixes/` exists and is non-empty, scan every `SUMMARY.md` and build `.dw/intel/bugfixes.json` (budget ≤1K tokens). Schema:
+   ```json
+   {
+     "schema_version": "1.0",
+     "fixes": [
+       {
+         "slug": "001-login-not-working",
+         "date": "YYYY-MM-DD",
+         "status": "Fixed",
+         "severity": "Medium",
+         "symptom_one_line": "...",
+         "root_cause_one_line": "...",
+         "modules_touched": ["src/auth/", "src/api/login/"],
+         "files_touched": ["src/auth/session.ts", "src/auth/session.test.ts"],
+         "related_concerns": ["src/auth/session.ts"],
+         "path": ".dw/bugfixes/001-login-not-working/"
+       }
+     ],
+     "by_module": {
+       "src/auth/": ["001-login-not-working", "007-refresh-token-leak"]
+     }
+   }
+   ```
+   Skip if `.dw/bugfixes/` does not exist. Reject SUMMARY.md files that fail frontmatter validation; log them in the build report. **Escalated bugfixes** (those with `escalated.md` but no `SUMMARY.md` because the fix lives under `.dw/spec/prd-bugfix-<slug>/`) are skipped from `bugfixes.json` until the spec ships a fix — they re-enter the index when their SUMMARY.md is eventually written. The escalated `TASK.md` remains queryable by direct grep; the index only tracks completed fixes.
+9. **Refresh metadata.** Write `.dw/intel/.last-refresh.json` with `updated_at`, `version`, `mode` (full or incremental), files-scanned count, and `bugfixes_indexed` count.
 
 ### Complementary skill for build mode
 

package/scaffold/en/commands/dw-pause.md

@@ -0,0 +1,92 @@
+<system_instructions>
+You are a session-handoff agent. Your job is to consolidate the current session's mental state into `.dw/STATE.md` so the next session (yours or a teammate's) can resume without losing context.
+
+## When to Use
+- Use when the user says "pause work", "end session", "I need to stop for now", "save what we're doing"
+- Use proactively before a long break, before switching projects, or before a context window is about to be compacted
+- Do NOT use mid-task when nothing has been decided or learned (nothing to consolidate)
+- Do NOT use as a substitute for `/dw-commit` — STATE.md is mental state, not code changes
+
+## Pipeline Position
+**Predecessor:** any working session | **Successor:** `/dw-resume` (in a future session)
+
+## What this command does NOT do
+- It does NOT commit code (use `/dw-commit`)
+- It does NOT replace per-PRD `MEMORY.md` (workflow memory for a single feature lives there; `dw-memory` skill manages it)
+- It does NOT promote anything to ADRs (use `/dw-adr` for durable architectural decisions)
+
+## File Location
+- Single artifact: `.dw/STATE.md` (project-level, not per-PRD)
+- Template: `.dw/templates/state-template.md` (used only on first creation)
+
+## Workflow
+
+### 1. Ensure STATE.md exists
+- If `.dw/STATE.md` is missing, copy `.dw/templates/state-template.md` to `.dw/STATE.md`. Notify in chat: "STATE.md not found — initialized from template."
+- If `.dw/templates/state-template.md` is also missing (very old project), create a minimal STATE.md with the required sections (Open Loops, Decisions, Blockers, Todos, Deferred Ideas, Lessons, Preferences, Notes).
+
+### 2. Survey the session
+Read the conversation context and identify, **without inventing**:
+
+- **Open loops**: tasks/work started but not finished (e.g. "PRD `prd-foo` is at TechSpec stage, awaiting user approval"; "Task 3 of `prd-bar` failing on lint")
+- **Decisions made**: choices the user and agent agreed on during the session that affect future work
+- **Blockers encountered**: things that stopped forward motion (waiting on input, broken tooling, knowledge gap)
+- **Todos** mentioned in passing that don't yet have a PRD or task file
+- **Ideas explored and parked** (with the reason for parking)
+- **Lessons learned** — small operational lessons worth recording
+- **Preferences expressed** — conventions the user wants applied going forward
+
+### 3. Merge into STATE.md
+
+<critical>NEVER overwrite STATE.md blindly. Read the existing file, parse the sections, and merge: append new items, do not delete old ones unless the user explicitly asked you to.</critical>
+
+Rules:
+- Each new entry gets a date prefix `YYYY-MM-DD` (use today's date).
+- Use bullet lists. Keep each item to one line where possible; two lines if context is essential.
+- If a section ends up with `_none_` placeholder and you have nothing to add, keep `_none_`.
+- Update the `last_paused` frontmatter field to today's date (YYYY-MM-DD).
+
+### 4. Compaction pass (when STATE.md is large)
+
+If after merging STATE.md exceeds **~6KB** or any single section exceeds **20 items**, compact:
+
+- **Open Loops resolved during the session**: remove them.
+- **Todos completed during the session**: remove them.
+- **Decisions older than 30 days that have been formalized into ADRs or constitution**: remove (the ADR is the durable record).
+- **Lessons older than 60 days**: keep only those still relevant; drop dated tactical advice.
+- **Deferred Ideas older than 90 days with no revisit trigger**: ask the user before dropping.
+
+If compaction removes more than 5 items, list them in chat so the user can veto.
+
+### 5. Report
+
+Present a brief summary to the user:
+
+```
+## Session Paused
+
+Updated `.dw/STATE.md`:
+- Open Loops: +N (now: X total)
+- Decisions: +N
+- Blockers: +N (Y unresolved)
+- Todos: +N (Z total)
+- Deferred: +N
+
+[If compaction ran: lines removed and why]
+
+Resume with `/dw-resume` next session.
+```
+
+## Required Behavior
+
+<critical>NEVER fabricate state. If you don't see evidence of a blocker or decision in the conversation, don't add it. Empty sections are fine.</critical>
+
+<critical>NEVER touch per-PRD memory files (`.dw/spec/*/MEMORY.md`, `.dw/spec/*/tasks/*_memory.md`). Those are managed by `dw-memory` skill and are PRD-local.</critical>
+
+<critical>NEVER drop user content silently. If you compact, you list what you removed.</critical>
+
+## Inspired by
+
+This command adapts the session-handoff pattern from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). Adaptations: `.dw/STATE.md` location instead of `.specs/project/STATE.md`, explicit compaction protocol, frontmatter with `last_paused` / `last_resumed` for ordering signals, complementarity with the existing `dw-memory` skill.
+
+</system_instructions>

package/scaffold/en/commands/dw-qa.md

@@ -19,6 +19,8 @@ You are the QA orchestrator. Two modes: run QA against the implementation (UI or
 | `/dw-qa --fix` | QA pass followed by an iterative fix+retest loop. Each detected bug → root-cause → fix → retest with evidence → mark resolved. Continues until all bugs marked Closed or user accepts a deferred list. |
 | `/dw-qa --api` | Forces API-only mode (skips UI even when frontend dependencies are present). Useful for backend-only sub-features in fullstack repos. |
 | `/dw-qa --ai` | Adds AI feature evaluation against the reference dataset at `.dw/eval/datasets/<feature>/`. Computes precision@k / faithfulness / outcome accuracy per the feature type. Logs JSONL to `QA/logs/ai/`. |
+| `/dw-qa --uat` | **Interactive UAT walkthrough.** The agent walks the user through the feature step-by-step, asking targeted questions ("does this match expectation?", "what's the expected behavior in case X?"). No Playwright auto-driving, no AI eval. Output: `QA/uat-report.md`. Used after `--fix` (or instead of `/dw-qa` for primarily-judgment-bound features). |
+| `/dw-qa --bugfix <NNN-slug>` | Targets a bugfix at `.dw/bugfixes/NNN-slug/` instead of a PRD. Runs the standard QA flow scoped to the files touched by the fix; output written to `.dw/bugfixes/NNN-slug/QA/`. Combines with `--fix`/`--api`/`--ai`/`--uat`. |
 
 ## Mode auto-detection
 
@@ -32,8 +34,17 @@ The default `/dw-qa` inspects the project to choose UI vs API:
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{PRD_PATH}}` | Path to PRD directory containing tasks (auto-detect from active branch if omitted) | `.dw/spec/prd-invoice-export` |
-| `{{MODE}}` | `--fix` / `--api` / `--ai` (optional; default = auto-detect) | — |
+| `{{PRD_PATH}}` | Path to PRD directory containing tasks (auto-detect from active branch if omitted; ignored when `--bugfix` is used) | `.dw/spec/prd-invoice-export` |
+| `{{BUGFIX_SLUG}}` | Bugfix slug when `--bugfix` flag is used | `001-login-not-working` |
+| `{{MODE}}` | `--fix` / `--api` / `--ai` / `--uat` / `--bugfix <slug>` (optional; default = auto-detect, target = PRD) | — |
+
+## Target Resolution
+
+Compute `<target>` ONCE at the start; substitute it wherever you see `<target>` below.
+
+1. **PRD target (default):** `<target>` = `{{PRD_PATH}}`. Artifacts read: `prd.md` (FRs), `techspec.md`, `tasks.md`, per-task files. Output written to `<target>/QA/`.
+
+2. **Bugfix target (`--bugfix <slug>`):** `<target>` = `.dw/bugfixes/<slug>/`. Artifacts read: `TASK.md` (numbered tasks + files touched), `fix-report.md` (verify evidence + reproduction trace), `SUMMARY.md`. QA is scoped to the files in the `Files Touched` table and the adjacent surfaces those files expose. Output written to `<target>/QA/`. The `qa-report.md` produced here is shorter — there are at most 5 tasks and a single root-cause to validate, not a full FR matrix.
 
 ## Complementary Skills
 
@@ -50,19 +61,20 @@ When available under `./.agents/skills/`, these are invoked operationally:
 ## Output Structure
 
 ```
-.dw/spec/<prd>/QA/
-├── qa-report.md                  # Test plan + execution summary
-├── bugs.md                       # Bug catalog with status
+<target>/QA/                          # <target> = .dw/spec/<prd>/ OR .dw/bugfixes/<NNN-slug>/
+├── qa-report.md                      # Test plan + execution summary
+├── bugs.md                           # Bug catalog with status
+├── uat-report.md                     # (--uat mode only) Walkthrough log + user observations
 ├── scripts/
-│   ├── ui/<RF>-<slug>.spec.ts    # Playwright scripts (UI mode)
-│   ├── api/<RF>-<slug>.http      # API test files
-│   └── ai/<feature>-eval.ts      # AI eval scripts (--ai mode)
+│   ├── ui/<RF>-<slug>.spec.ts        # Playwright scripts (UI mode)
+│   ├── api/<RF>-<slug>.http          # API test files
+│   └── ai/<feature>-eval.ts          # AI eval scripts (--ai mode)
 ├── evidence/
-│   ├── ui/                       # Screenshots per RF + retests
+│   ├── ui/                           # Screenshots per RF + retests
 │   └── ...
 └── logs/
-    ├── api/<RF>-<slug>.log       # JSONL request/response per call
-    └── ai/<feature>-<date>.jsonl # AI eval results
+    ├── api/<RF>-<slug>.log           # JSONL request/response per call
+    └── ai/<feature>-<date>.jsonl     # AI eval results
 ```
 
 ## Mode 1: Default (`/dw-qa`)
@@ -105,6 +117,70 @@ When available under `./.agents/skills/`, these are invoked operationally:
 4. Compare to prior run's JSONL — alert on >10% regression in any metric.
 5. Append AI-mode section to `qa-report.md`.
 
+## Mode 1.5: Interactive UAT (`/dw-qa --uat`)
+
+The UAT mode is a **human-in-the-loop walkthrough**. There is no Playwright auto-driving and no AI eval. The agent is the navigator; the user is the verifier. Use this when behavior is judgment-bound — a redesign, a content-heavy flow, a new flow whose acceptance criteria are partly aesthetic, or a bugfix whose user-facing manifestation needs a human eye to confirm.
+
+### Pre-flight
+
+1. **Bugfix target:** read `<target>/SUMMARY.md` → Symptom + Resolution. The walkthrough is the reproduction trace from `fix-report.md` (before → after), now confirmed live.
+2. **PRD target:** read `<target>/prd.md` → for each FR, draft a one-line "what should you see when X happens?" question.
+3. Start the project's dev server (or instruct the user to start it if it needs interactive credentials).
+
+### Walkthrough loop
+
+For each FR (PRD target) or each numbered task in `TASK.md` (bugfix target):
+
+1. **Agent describes the next step in plain words.** Example: "Open `/invoices/export` while logged in as a viewer. The export button should be disabled and a tooltip should explain why."
+2. **User performs the step in their browser/app** and reports what they observed.
+3. **Agent asks one targeted follow-up** matched to the FR/task — never more than one open question at a time:
+   - "Does the disabled state visually communicate why? (text, icon, contrast — your call)"
+   - "If you tab to the button, does the tooltip become accessible via keyboard?"
+   - "What happened in the network panel?" (only if a backend behavior is relevant)
+4. **Agent records the answer verbatim** in `uat-report.md` under that FR/task's section. No interpretation, no rephrasing.
+5. **Agent flags a finding** when the user reports unexpected behavior. The finding goes into `bugs.md` with `source: uat` and `severity: <user's choice>`.
+6. **Repeat until all FRs / numbered tasks have been walked.**
+
+### Output
+
+Save to `<target>/QA/uat-report.md`:
+
+```markdown
+# UAT Walkthrough — <target>
+
+Date: YYYY-MM-DD
+Walked by: <user identifier or "user">
+Browser/env: <as reported>
+
+## FR-1.1 (or Task 1) — <one-line scope>
+
+- Step: <what agent asked>
+- User observation: <verbatim>
+- Verdict: PASS / FAIL / NEEDS-DESIGN-INPUT
+- Notes: <any follow-up>
+
+## FR-1.2 (or Task 2) — ...
+...
+
+## Summary
+
+- Walked: N FRs / tasks
+- PASS: N
+- FAIL: N (cross-ref bugs.md entries with source:uat)
+- NEEDS-DESIGN-INPUT: N (no bug; the spec was under-defined here)
+```
+
+### Required behavior
+
+<critical>
+- NEVER auto-drive the browser in `--uat` mode. The user navigates; you observe.
+- NEVER paraphrase the user's observation. Quote verbatim under each FR/task.
+- NEVER mark a finding as a bug without the user's explicit "yes, that's a bug" — UAT findings can also surface unclear specs (NEEDS-DESIGN-INPUT), which are not bugs.
+- Cap each FR's section at one open question per turn. UAT is interactive, not interrogation.
+</critical>
+
+UAT composes with `--bugfix <slug>` (walks the regression test path with the user instead of FRs) and with `--fix` (after a fix lands, UAT is the human green-light before commit).
+
 ## Mode 2: Fix loop (`/dw-qa --fix`)
 
 ### Behavior