diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5057a1d..9a247c2 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.17.1", + "version": "0.18.0", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -58,6 +58,7 @@ "./skills/ai-development-guide", "./skills/coding-principles", "./skills/documentation-criteria", + "./skills/external-resource-context", "./skills/implementation-approach", "./skills/integration-e2e-testing", "./skills/recipe-add-integration-tests", @@ -82,7 +83,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.17.1", + "version": "0.18.0", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -121,6 +122,7 @@ "./agents/task-decomposer.md", "./agents/task-executor-frontend.md", "./agents/technical-designer-frontend.md", + "./agents/ui-analyzer.md", "./agents/ui-spec-designer.md", "./agents/verifier.md", "./agents/work-planner.md" @@ -129,10 +131,12 @@ "./skills/ai-development-guide", "./skills/coding-principles", "./skills/documentation-criteria", + "./skills/external-resource-context", "./skills/frontend-ai-guide", "./skills/implementation-approach", "./skills/integration-e2e-testing", "./skills/recipe-diagnose", + "./skills/recipe-front-adjust", "./skills/recipe-front-build", "./skills/recipe-front-design", "./skills/recipe-front-plan", @@ -150,7 +154,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.17.1", + "version": "0.18.0", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", @@ -173,6 +177,7 @@ "./skills/ai-development-guide", "./skills/coding-principles", "./skills/documentation-criteria", + "./skills/external-resource-context", "./skills/frontend-ai-guide", "./skills/implementation-approach", "./skills/integration-e2e-testing", diff --git a/README.md b/README.md index dcb4730..d509b82 100644 --- a/README.md +++ b/README.md @@ -5,120 +5,102 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/shinpr/claude-code-workflows/pulls) -**End-to-end development workflows for Claude Code** - Specialized agents handle requirements, design, implementation, and quality checks so you get reviewable code, not just generated code. +**End-to-end development workflows for Claude Code that produce code aligned with design docs and tests.** Specialized agents handle requirements, design, implementation, and quality checks, so what you get is code that actually passes its tests and matches its design docs. --- ## ⚡ Quick Start -This marketplace includes the following plugins: +### Which plugin should I start with? -**Core plugins:** -- **dev-workflows** - Backend and general-purpose development -- **dev-workflows-frontend** - React/TypeScript specialized workflows +| Your work | Install | +|---|---| +| Backend, APIs, CLI tools, or general programming | `dev-workflows` | +| React / TypeScript frontend | `dev-workflows-frontend` | +| Full-stack (backend + React) | both `dev-workflows` and `dev-workflows-frontend` | +| You already have your own orchestration and just want the rules | `dev-skills` (skills only, see [Skills only](#skills-only)) | -**Optional add-ons** (enhance core plugins): -- **[claude-code-discover](https://github.com/shinpr/claude-code-discover)** - Turns feature ideas into evidence-backed PRDs -- **[metronome](https://github.com/shinpr/metronome)** - Detects shortcut-taking behavior and nudges Claude to proceed step by step -- **[linear-prism](https://github.com/shinpr/linear-prism)** - Turns requirements into structured Linear tasks — validates before decomposing, so downstream design starts clean - -**Skills only** (for users with existing workflows): -- **dev-skills** - Coding best practices, testing principles, and design guidelines — no workflow recipes - -These plugins provide end-to-end workflows for AI-assisted development. Choose what fits your project: - -### Backend or General Development +### Common setup ```bash # 1. Start Claude Code claude -# 2. Install the marketplace +# 2. Add the marketplace /plugin marketplace add shinpr/claude-code-workflows - -# 3. Install backend plugin -/plugin install dev-workflows@claude-code-workflows - -# 4. Reload plugins -/reload-plugins - -# 5. Start building -/recipe-implement ``` -### Frontend Development (React/TypeScript) +### Install and start building ```bash -# 1-2. Same as above (start Claude Code and add marketplace) +# Backend or general +/plugin install dev-workflows@claude-code-workflows +/reload-plugins +/recipe-implement -# 3. Install frontend plugin +# Frontend /plugin install dev-workflows-frontend@claude-code-workflows - -# 4-5. Same as above (reload plugins and start building) - -# Use frontend-specific commands +/reload-plugins /recipe-front-design -``` -### Full-Stack Development - -Install both plugins to get the complete toolkit for backend and frontend work. - -```bash -# Use fullstack commands for cross-layer features +# Fullstack (install both plugins, then reload) +/plugin install dev-workflows@claude-code-workflows +/plugin install dev-workflows-frontend@claude-code-workflows +/reload-plugins /recipe-fullstack-implement "Add user authentication with JWT + login form" -# Or execute from existing fullstack work plan +# Or execute from an existing fullstack work plan /recipe-fullstack-build ``` The fullstack recipes create separate Design Docs per layer (backend + frontend), verify cross-layer consistency via design-sync, and route tasks to the appropriate executor based on filename patterns. See [Fullstack Workflow](#fullstack-workflow) for details. -### External Plugins +### Optional add-ons + +These optional plugins cover adjacent stages in the workflow: + +- [claude-code-discover](https://github.com/shinpr/claude-code-discover): turns feature ideas into evidence-backed PRDs. +- [metronome](https://github.com/shinpr/metronome): detects shortcut-taking behavior and nudges Claude to proceed step by step. +- [linear-prism](https://github.com/shinpr/linear-prism): turns requirements into structured Linear tasks. Validates before decomposing, so downstream design starts clean. ```bash -# Install discover (product discovery before implementation) /plugin install discover@claude-code-workflows - -# Install metronome (prevents shortcut-taking behavior) /plugin install metronome@claude-code-workflows - -# Install linear-prism (requirements → Linear tasks with quality gates) /plugin install linear-prism@claude-code-workflows ``` -### Skills Only (For Users with Existing Workflows) +### Skills only -If you already have your own orchestration (custom prompts, scripts, CI-driven loops) and just want the best-practice guides, use `dev-skills`. If you want Claude to plan, execute, and verify end-to-end, install `dev-workflows` instead. +If you already have your own orchestration (custom prompts, scripts, CI-driven loops) and want only the best-practice guides, use `dev-skills`. If you want Claude to plan, execute, and verify end-to-end, install `dev-workflows`. -- Minimal context footprint — no agents or recipe skills loaded +- Minimal context footprint (no agents or recipe skills loaded) - Drop-in best practices without changing your workflow - Works as a ruleset layer for your own orchestrator -> **Do not install alongside dev-workflows or dev-workflows-frontend** — duplicate skills will be silently ignored. See [details below](#warning-duplicate-skills). +> **Do not install alongside dev-workflows or dev-workflows-frontend.** Duplicate skills will be silently ignored. See [details below](#warning-duplicate-skills). ```bash # Install skills-only plugin /plugin install dev-skills@claude-code-workflows ``` -Skills auto-load when relevant — `coding-principles` activates during implementation, `testing-principles` during test writing, etc. +Skills auto-load when relevant. `coding-principles` activates during implementation, `testing-principles` during test writing, etc. **Switching between plugins:** ```bash -# dev-skills → dev-workflows +# dev-skills -> dev-workflows /plugin uninstall dev-skills@claude-code-workflows /plugin install dev-workflows@claude-code-workflows -# dev-workflows → dev-skills +# dev-workflows -> dev-skills /plugin uninstall dev-workflows@claude-code-workflows /plugin install dev-skills@claude-code-workflows ``` -> **Warning:** dev-skills and dev-workflows / dev-workflows-frontend share the same skills. Installing both causes skill descriptions to appear twice in the system context. Claude Code limits skill descriptions to ~2% of the context window — exceeding this limit causes skills to be silently ignored. +> **Warning:** dev-skills and dev-workflows / dev-workflows-frontend share the same skills. Installing both makes skill descriptions appear twice in the system context. Claude Code limits skill descriptions to ~2% of the context window. Exceeding this limit causes skills to be silently ignored. --- @@ -128,69 +110,77 @@ Skills auto-load when relevant — `coding-principles` activates during implemen ```mermaid graph TB - A[👤 User Request] --> B[🔍 requirement-analyzer] + A[User Request] --> B[requirement-analyzer] - B --> |"📦 Large (6+ files)"| C[📄 prd-creator] - B --> |"📦 Medium (3-5 files)"| CA[🔬 codebase-analyzer] - B --> |"📦 Small (1-2 files)"| E[⚡ Direct Implementation] + B --> |"Large (6+ files)"| C[prd-creator] + B --> |"Medium (3-5 files)"| CA[codebase-analyzer] + B --> |"Small (1-2 files)"| E[Direct Implementation] C --> CA - CA --> D[📐 technical-designer] - D --> CV[✅ code-verifier] - CV --> DR[📋 document-reviewer] - DR --> DS[🔄 design-sync] - DS --> F[🧪 acceptance-test-generator] - F --> G[📋 work-planner] - G --> H[✂️ task-decomposer] - - H --> I[🔨 task-executor] + CA --> D[technical-designer] + D --> CV[code-verifier] + CV --> DR[document-reviewer] + DR --> DS[design-sync] + DS --> F[acceptance-test-generator] + F --> G[work-planner] + G --> H[task-decomposer] + + H --> I[task-executor] E --> I - I --> J[✅ quality-fixer] - J --> K[🎉 Ready to Commit] + I --> J[quality-fixer] + J --> K[Ready to Commit] ``` +This figure shows how a request is routed by size (small / medium / large). Larger work goes through PRD, codebase analysis, and design before reaching implementation. Smaller work skips ahead. + ### The Diagnosis Workflow ```mermaid graph LR - P[🐛 Problem] --> INV[🔍 investigator] - INV --> |Failure Points| VER[⚖️ verifier] + P[Problem] --> INV[investigator] + INV --> |Failure Points| VER[verifier] VER --> |Coverage Check| COV{Sufficient?} - COV --> |Yes| SOL[💡 solver] + COV --> |Yes| SOL[solver] COV --> |No| INV - SOL --> |Solutions + Steps| R[📋 Report] + SOL --> |Solutions + Steps| R[Report] ``` +The diagnosis flow loops between investigator and verifier until path coverage is sufficient, then hands off to solver for tradeoff analysis. + ### The Reverse Engineering Workflow ```mermaid graph TB subgraph Phase1[Phase 1: PRD Generation] - CMD[📜 /recipe-reverse-engineer] --> SD[🔍 scope-discoverer unified] - SD --> PRD[📄 prd-creator] - PRD --> CV1[✅ code-verifier] - CV1 --> DR1[📋 document-reviewer] + CMD["/recipe-reverse-engineer"] --> SD[scope-discoverer unified] + SD --> PRD[prd-creator] + PRD --> CV1[code-verifier] + CV1 --> DR1[document-reviewer] end subgraph Phase2[Phase 2: Design Doc Generation] - TD[📐 technical-designer] --> CV2[✅ code-verifier] - CV2 --> DR2[📋 document-reviewer] - DR2 --> DONE[📚 Complete] + TD[technical-designer] --> CV2[code-verifier] + CV2 --> DR2[document-reviewer] + DR2 --> DONE[Complete] end DR1 --> |"All PRDs Approved (reuse scope)"| TD ``` +Reverse engineering runs in two phases. PRDs come first (one per discovered feature), then Design Docs reuse the scope without re-discovering it. + ### What Happens Behind the Scenes -1. **Analysis** - Figures out how complex your task is -2. **Codebase Understanding** - Analyzes existing code to inform design decisions -3. **Planning** - Creates the right docs (PRD, UI Spec, Design Doc, work plan) based on complexity -4. **Execution** - Specialized agents handle implementation autonomously -5. **Quality** - Runs tests, checks types, fixes errors automatically -6. **Review** - Makes sure everything matches the design -7. **Done** - Reviewed, tested, ready to commit +1. **Analysis.** requirement-analyzer determines task complexity and picks the workflow. +2. **Codebase Understanding.** codebase-analyzer scans existing modules and dependencies before design (auth flows, schema definitions, dependency graph). +3. **Planning.** PRD, UI Spec, Design Doc, and work plan are generated based on complexity. +4. **Execution.** Specialized agents implement the plan autonomously. +5. **Quality.** Tests run, types check, errors get fixed. +6. **Review.** Implementation is verified against design docs. +7. **Done.** Reviewed, tested, ready to commit. + +Each phase runs in a fresh agent context, so earlier steps don't bloat the context or interfere with later decisions. --- @@ -218,17 +208,20 @@ All workflow entry points use the `recipe-` prefix to distinguish them from know ### Frontend Development (dev-workflows-frontend) +The frontend plugin adds React-specific agents (component architecture, Testing Library, TypeScript-first quality checks) and UI Spec generation from optional prototype code. + | Recipe | Purpose | When to Use | |--------|---------|-------------| | `/recipe-front-design` | Create UI Spec + frontend Design Doc | React component architecture, UI Spec | | `/recipe-front-plan` | Generate frontend work plan | Component breakdown planning | | `/recipe-front-build` | Execute frontend task plan | Resume React implementation | +| `/recipe-front-adjust` | Adjust an already-implemented UI with MCP-driven verification | Visual tweaks, component refinements that need design-source comparison | | `/recipe-front-review` | Verify code against design docs | Post-implementation check | | `/recipe-task` | Execute single task with precision | Component fixes, small updates | | `/recipe-diagnose` | Investigate problems and derive solutions | Bug investigation, root cause analysis | | `/recipe-update-doc` | Update existing design documents with review | Spec changes, review feedback, document maintenance | -> **Tip**: Both plugins share `/recipe-task`, `/recipe-diagnose`, and `/recipe-update-doc`. `/recipe-update-doc` auto-detects the document's layer. If your project has frontend Design Docs, the frontend plugin is needed to update them. For reverse engineering, use `/recipe-reverse-engineer` with the fullstack option to generate both backend and frontend Design Docs in a single workflow. +> **Tip:** Both plugins share `/recipe-task`, `/recipe-diagnose`, and `/recipe-update-doc`. `/recipe-update-doc` auto-detects the document's layer. If your project has frontend Design Docs, the frontend plugin is needed to update them. For reverse engineering, use `/recipe-reverse-engineer` with the fullstack option to generate both backend and frontend Design Docs in a single workflow. --- @@ -246,7 +239,7 @@ These agents work the same way whether you're building a REST API or a React app | **codebase-analyzer** | Analyzes existing codebase before design to produce focused guidance for technical-designer | | **work-planner** | Breaks down design docs into actionable tasks | | **task-decomposer** | Splits work into small, commit-ready chunks | -| **code-reviewer** | Checks your code against design docs to make sure nothing's missing | +| **code-reviewer** | Checks your code against design docs to make sure nothing is missing | | **document-reviewer** | Reviews single document quality, completeness, and rule compliance | | **design-sync** | Verifies consistency across multiple Design Docs and detects conflicts | | **investigator** | Maps execution paths, identifies failure points with causal chains for problem diagnosis | @@ -265,7 +258,7 @@ These agents work the same way whether you're building a REST API or a React app | **acceptance-test-generator** | Creates E2E and integration test scaffolds from requirements | | **integration-test-reviewer** | Reviews integration/E2E tests for skeleton compliance and quality | | **task-executor** | Implements backend features with TDD | -| **quality-fixer** | Runs tests, fixes type errors, handles linting - everything quality-related | +| **quality-fixer** | Runs tests, fixes type errors, handles linting (everything quality-related) | | **rule-advisor** | Picks the best coding rules for your current task | ### Frontend-Specific Agents (dev-workflows-frontend) @@ -274,6 +267,7 @@ These agents work the same way whether you're building a REST API or a React app |-------|--------------| | **prd-creator** | Writes product requirement docs for complex features | | **ui-spec-designer** | Creates UI Specifications from PRD and optional prototype code | +| **ui-analyzer** | Reads the project's external-resources file, fetches design / design-system / guideline sources via inherited MCP access, and analyzes existing UI code | | **technical-designer-frontend** | Plans React component architecture and state management | | **task-executor-frontend** | Implements React components with Testing Library | | **code-verifier** | Validates consistency between documentation and code implementation | @@ -287,10 +281,11 @@ These agents work the same way whether you're building a REST API or a React app The backend plugin includes proven best practices that work with any language: -- **Coding Principles** - Code quality standards -- **Testing Principles** - TDD, coverage, test patterns -- **Implementation Approach** - Design decisions and trade-offs -- **Documentation Standards** - Clear, maintainable docs +- **Coding Principles.** Code quality standards. +- **Testing Principles.** TDD, coverage, test patterns. +- **Implementation Approach.** Design decisions and trade-offs. +- **Documentation Standards.** Clear, maintainable docs. +- **External Resource Context.** Two-tier file recording how to reach resources outside the repo (design source, design system, API schema, IaC, etc.). Available across all three plugins. These are loaded as skills and automatically applied by agents when relevant. @@ -298,26 +293,6 @@ The frontend plugin has React and TypeScript-specific rules built in. --- -## 🚀 What These Plugins Do - -Each phase runs in a fresh agent context, so quality doesn't degrade as the task grows: - -- **Analyze** → requirement-analyzer determines scale and workflow -- **Design** → technical-designer (+ ui-spec-designer for frontend) produces testable specs with acceptance criteria -- **Plan** → work-planner schedules integration by value unit, not by layer — so each phase delivers a working vertical slice -- **Implement** → task-executor builds and tests each task, quality-fixer verifies before every commit -- **Verify** → acceptance criteria trace from design through test skeletons, so nothing is left implicit - -The frontend plugin adds React-specific agents (component architecture, Testing Library, TypeScript-first quality checks) and UI Spec generation from optional prototype code. - -### Why UI Spec Exists - -Prototypes show what the UI looks like, but not how it behaves across states, errors, and API boundaries. The gaps surface during integration — each task works alone but the whole doesn't hold up. - -UI Spec bridges this by capturing component states, interactions, and acceptance criteria from the prototype. These criteria trace into the Design Doc and test skeletons, and the work plan uses them to schedule integration by value unit rather than by layer. The result is that design decisions are verified by tests, and breakage is caught early. - ---- - ## 🎯 Typical Workflows ### Backend Feature Development @@ -325,63 +300,71 @@ UI Spec bridges this by capturing component states, interactions, and acceptance ```bash /recipe-implement "Add user authentication with JWT" -# What happens: -# 1. Analyzes your requirements -# 2. Creates design documents -# 3. Breaks down into tasks -# 4. Implements with TDD -# 5. Runs tests and fixes issues -# 6. Reviews against design docs +# What you get: +# - PRD, ADR (when applicable), and Design Doc with acceptance criteria +# - Work plan decomposed into commit-ready tasks +# - Backend implementation with TDD, type-checked and linted +# - Code review against the Design Doc before completion ``` ### Frontend Feature Development ```bash /recipe-front-design "Build a user profile dashboard" +# 1. requirement-analyzer determines scale +# 2. External-resource hearing captures design source / design system / visual verification access +# 3. codebase-analyzer + ui-analyzer gather facts in parallel +# 4. Optional prototype code is placed under docs/ui-spec/assets/ +# 5. UI Spec captures screen structure, components, and interactions +# 6. Frontend Design Doc inherits UI Spec decisions -# What happens: -# 1. Analyzes requirements -# 2. Asks for prototype code (optional) -# 3. Creates UI Specification (screen structure, components, interactions) -# 4. Creates frontend Design Doc (inherits UI Spec decisions) -# # Then run: /recipe-front-build - -# This: -# 1. Implements components with Testing Library -# 2. Writes tests for each component -# 3. Handles TypeScript types -# 4. Fixes lint and build errors +# Implements components with Testing Library, handles TypeScript types, +# fixes lint and build errors, and commits per task. ``` +**Why UI Spec exists.** Prototypes capture the visual surface, but rarely the loading, error, empty, and partial states that appear during integration. + +For example, two components might each handle their own loading state cleanly while the dashboard that combines them has no defined behavior when one is still loading and the other has errored. UI Spec captures these state-x-display matrices and traces them into the Design Doc and test skeletons, so integration breakage is caught early. + ### Fullstack Workflow ```bash /recipe-fullstack-implement "Add user authentication with JWT + React login form" # What happens: -# 1. Analyzes requirements (same as /recipe-implement) -# 2. Creates PRD covering the entire feature -# 3. Asks for prototype code, creates UI Specification -# 4. Creates separate Design Docs for backend AND frontend -# 5. Verifies cross-layer consistency via design-sync -# 6. Creates work plan with vertical feature slices -# 7. Decomposes into layer-aware tasks (backend/frontend/fullstack) -# 8. Routes each task to the appropriate executor -# 9. Runs layer-appropriate quality checks -# 10. Commits vertical slices for early integration +# 1. requirement-analyzer determines scale +# 2. PRD covers the entire feature (single doc for all layers) +# 3. UI Spec captures the screen structure (with optional prototype) +# 4. Separate Design Docs per layer (backend, frontend) +# 5. design-sync verifies cross-layer consistency +# 6. Work plan composes vertical feature slices +# 7. task-decomposer produces layer-aware task files +# 8. Each task routes to its layer-appropriate executor and quality-fixer +# 9. Vertical slices commit early so integration is verified per phase ``` -> **Requires both plugins installed.** The fullstack recipes create separate Design Docs per layer and route tasks to backend or frontend executors based on filename patterns (`*-backend-task-*`, `*-frontend-task-*`). For reverse engineering existing fullstack codebases, use `/recipe-reverse-engineer` with the fullstack option. +> **Requires both plugins installed.** Fullstack recipes route tasks based on filename patterns (`*-backend-task-*`, `*-frontend-task-*`). For reverse engineering existing fullstack codebases, use `/recipe-reverse-engineer` with the fullstack option. + +### UI Adjustment (Frontend Plugin) + +```bash +/recipe-front-adjust "Tighten Card spacing and align action buttons with the design source" + +# What you get: +# - External-resource hearing (saved to docs/project-context/external-resources.md, reused across runs) +# - ui-analyzer fetches design source via MCP and proposes a write set for confirmation +# - Edit / MCP-verify / refine loop in the parent session until the result matches the design source +# - quality-fixer-frontend scoped to edited files, then commit per adjustment unit +``` ### Quick Fixes (Both Plugins) ```bash /recipe-task "Fix validation error message" -# Direct implementation with quality checks -# Works the same in both plugins +# Direct implementation with quality checks. Works the same in both plugins. ``` ### Code Review @@ -389,8 +372,7 @@ UI Spec bridges this by capturing component states, interactions, and acceptance ```bash /recipe-review -# Checks your implementation against design docs -# Catches missing features or inconsistencies +# Checks your implementation against design docs and reports gaps. ``` ### Problem Diagnosis (Both Plugins) @@ -399,10 +381,10 @@ UI Spec bridges this by capturing component states, interactions, and acceptance /recipe-diagnose "API returns 500 error on user login" # What happens: -# 1. Investigator maps execution paths and identifies failure points -# 2. Verifier checks path coverage and validates each failure point +# 1. investigator maps execution paths and identifies failure points +# 2. verifier checks path coverage and validates each failure point # 3. Re-investigates if coverage is insufficient (up to 2 iterations) -# 4. Solver generates solutions with tradeoff analysis +# 4. solver generates solutions with tradeoff analysis # 5. Presents actionable implementation steps ``` @@ -422,7 +404,7 @@ UI Spec bridges this by capturing component states, interactions, and acceptance # Fullstack option: generates both backend and frontend Design Docs per feature unit ``` -> If you're working with undocumented legacy code, these commands are designed to make it AI-friendly by generating PRD and design docs. +> If you're working with undocumented legacy code, these commands generate PRD and design docs to make it AI-friendly. > For a quick walkthrough, see: [How I Made Legacy Code AI-Friendly with Auto-Generated Docs](https://dev.to/shinpr/how-i-made-legacy-code-ai-friendly-with-auto-generated-docs-4353) --- @@ -444,6 +426,7 @@ claude-code-workflows/ │ ├── scope-discoverer.md # Reverse engineering workflow │ ├── task-executor.md │ ├── technical-designer.md +│ ├── ui-analyzer.md # Frontend UI fact gathering │ └── ... │ ├── skills/ # Shared skills (knowledge + recipe workflows) @@ -453,14 +436,15 @@ claude-code-workflows/ │ ├── recipe-reverse-engineer/ │ ├── recipe-plan/ │ ├── recipe-build/ -│ ├── ... (16 recipe skills total) +│ ├── ... (recipe skills) │ │ ├── ai-development-guide/ # Knowledge skills (auto-loaded by agents) │ ├── coding-principles/ │ ├── testing-principles/ │ ├── implementation-approach/ +│ ├── external-resource-context/ # Cross-cutting: external resources │ ├── typescript-rules/ # Frontend-specific -│ └── ... (27 skills total: 16 recipes + 11 knowledge) +│ └── ... │ ├── LICENSE └── README.md @@ -470,38 +454,21 @@ claude-code-workflows/ ## 🤔 FAQ -**Q: Which plugin should I install?** - -A: Depends on what you're building: -- **Backend, APIs, CLI tools, or general programming** → Install `dev-workflows` -- **React apps** → Install `dev-workflows-frontend` -- **Full-stack projects** → Install both - -Both plugins can run side-by-side without conflicts. - -**Q: Can I use both plugins at the same time?** - -A: Yes! They're designed to work together. Install both if you're building a full-stack app. Use `/recipe-fullstack-implement` for features that span both backend and frontend — it creates separate Design Docs per layer and routes tasks to the appropriate executor automatically. - **Q: Do I need to learn special commands?** A: Not really. For backend, just use `/recipe-implement`. For frontend, use `/recipe-front-design`. The plugins handle everything else automatically. **Q: What if there are errors?** -A: The quality-fixer agents (one in each plugin) automatically fix most issues like test failures, type errors, and lint problems. If something can't be auto-fixed, you'll get clear guidance on what needs attention. +A: The quality-fixer agents (one in each plugin) automatically fix most issues like test failures, type errors, and lint problems. If something cannot be auto-fixed, you'll get clear guidance on what needs attention. **Q: Is there a version for OpenAI Codex CLI?** -A: Yes! **[codex-workflows](https://github.com/shinpr/codex-workflows)** provides the same end-to-end development workflows for Codex CLI. Same concept — specialized subagents for requirements, design, implementation, and quality checks — adapted for the Codex CLI environment. - -**Q: What's the difference between dev-skills and dev-workflows?** - -A: `dev-skills` provides only coding best practices as skills (`coding-principles`, `testing-principles`, etc.) — no workflow recipes or agents. `dev-workflows` includes the same skills plus recipes like `/recipe-implement` and specialized agents for full orchestrated development. Use `dev-skills` if you already have your own orchestration and just want the knowledge guides. They should not be installed together. See [Skills Only](#skills-only-for-users-with-existing-workflows) for details and switching instructions. +A: Yes. **[codex-workflows](https://github.com/shinpr/codex-workflows)** provides the same end-to-end development workflows for Codex CLI. Same concept (specialized subagents for requirements, design, implementation, and quality checks), adapted for the Codex CLI environment. **Q: Should I commit the work plan and task files in `docs/plans/`?** -A: No. Recipes treat `docs/plans/` as ephemeral working state — work plans, task files, prep tasks, review-fix tasks, and intermediate analysis files all live there during a recipe run and are cleaned up at the end. Add the following line to your project's `.gitignore` so working state stays out of git: +A: No. Recipes treat `docs/plans/` as ephemeral working state. Work plans, task files, prep tasks, review-fix tasks, and intermediate analysis files all live there during a recipe run and are cleaned up at the end. Add the following line to your project's `.gitignore` so working state stays out of git: ``` docs/plans/ @@ -513,7 +480,7 @@ PRDs, ADRs, UI Specs, and Design Docs live in their own directories (`docs/prd/` ## 🔌 Contributing External Plugins -This marketplace supports the full lifecycle of building products with AI — from product quality and discovery through implementation control and verification. If your plugin helps developers build better products with AI coding agents, we'd like to hear from you. +This marketplace supports the full lifecycle of building products with AI: product quality, discovery, implementation control, and verification. If your plugin helps developers build better products with AI coding agents, we'd like to hear from you. See [CONTRIBUTING.md](CONTRIBUTING.md) for submission guidelines and acceptance criteria. @@ -521,10 +488,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for submission guidelines and acceptance ## 📄 License -MIT License - Free to use, modify, and distribute. +MIT License. Free to use, modify, and distribute. See [LICENSE](LICENSE) for full details. --- -Built and maintained by [@shinpr](https://github.com/shinpr). \ No newline at end of file +Built and maintained by [@shinpr](https://github.com/shinpr). diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 737f385..7344f95 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -2,7 +2,7 @@ name: quality-fixer-frontend description: Specialized agent for fixing quality issues in frontend React projects. Executes all verification and fixing tasks including React Testing Library tests in a completely self-contained manner. Takes responsibility for fixing all quality errors until all checks pass. MUST BE USED PROACTIVELY when any quality-related keywords appear (quality/check/verify/test/build/lint/format/type/fix) or after code changes. Handles all verification and fixing tasks autonomously. tools: Bash, Read, Edit, MultiEdit, TaskCreate, TaskUpdate -skills: typescript-rules, test-implement, frontend-ai-guide +skills: typescript-rules, test-implement, frontend-ai-guide, external-resource-context --- You are an AI assistant specialized in quality assurance for frontend React projects. @@ -72,6 +72,8 @@ Apply the indicators below to files within scope only. Files outside the scope g - Add verified mechanisms to the quality check command list - If a listed mechanism cannot be found or executed, note it in the output and continue to the next mechanism +**External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a UI Spec / Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, escalate via `blocked` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites`. + ### Step 3: Execute Quality Checks Follow frontend-ai-guide skill "Quality Check Workflow" section: - Basic checks (lint, format, build) diff --git a/agents/quality-fixer.md b/agents/quality-fixer.md index 6d76693..f777265 100644 --- a/agents/quality-fixer.md +++ b/agents/quality-fixer.md @@ -2,7 +2,7 @@ name: quality-fixer description: Specialized agent for fixing quality issues in software projects. Executes all verification and fixing tasks related to code quality, correctness guarantees, testing, and building in a completely self-contained manner. Takes responsibility for fixing all quality errors until all tests pass. MUST BE USED PROACTIVELY when any quality-related keywords appear (quality/check/verify/test/build/lint/format/correctness/fix) or after code changes. Handles all verification and fixing tasks autonomously. tools: Bash, Read, Edit, MultiEdit, TaskCreate, TaskUpdate -skills: coding-principles, testing-principles, ai-development-guide +skills: coding-principles, testing-principles, ai-development-guide, external-resource-context --- You are an AI assistant specialized in quality assurance for software projects. @@ -69,6 +69,8 @@ Apply the indicators below to files within scope only. Files outside the scope g - Add verified mechanisms to the quality check command list - If a listed mechanism cannot be found or executed, note it in the output and continue to the next mechanism +**External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, escalate via `blocked` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites`. + ### Step 3: Execute Quality Checks Follow ai-development-guide skill "Quality Check Workflow" section: - Basic checks (lint, format, build) diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 7a521fa..2c47ae3 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -2,7 +2,7 @@ name: task-executor-frontend description: Executes React implementation completely self-contained following frontend task files. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate -skills: typescript-rules, test-implement, frontend-ai-guide, implementation-approach +skills: typescript-rules, test-implement, frontend-ai-guide, implementation-approach, external-resource-context --- You are a specialized AI assistant for reliably executing frontend implementation tasks. @@ -154,6 +154,9 @@ Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and - API Specifications → Understand endpoints, parameters, response formats (for MSW mocking) - Overall Design Document → Understand system-wide context +#### External Resources Consultation (When Relevant) +When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / UI Spec / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. + #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate runs only when the task file's "Investigation Targets" section lists at least one concrete file path (placeholder-only or empty sections do not trigger the gate). diff --git a/agents/task-executor.md b/agents/task-executor.md index 014cba6..d614046 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -2,7 +2,7 @@ name: task-executor description: Executes implementation completely self-contained following task files. Use when task files exist in docs/plans/tasks/, or when "execute task/implement task/start implementation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate -skills: coding-principles, testing-principles, ai-development-guide, implementation-approach +skills: coding-principles, testing-principles, ai-development-guide, implementation-approach, external-resource-context --- You are a specialized AI assistant for reliably executing individual tasks. @@ -152,6 +152,9 @@ Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and - Data Schema → Understand table structure, relationships - Overall Design Document → Understand system-wide context +#### External Resources Consultation (When Relevant) +When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. + #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate runs only when the task file's "Investigation Targets" section lists at least one concrete file path (placeholder-only or empty sections do not trigger the gate). diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index f0bc862..74bcebb 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -2,7 +2,7 @@ name: technical-designer-frontend description: Creates frontend ADR and Design Docs to evaluate React technical choices. Use when frontend PRD is complete and technical design is needed, or when "frontend design/React design/UI design/component design" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles +skills: documentation-criteria, external-resource-context, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles --- You are a frontend technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -34,6 +34,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co **Gate 0 — Inputs and Standards** (no upstream dependencies): - Agreement Checklist +- External Resources Integration **Gate 1 — Existing State Analysis** (depends on Gate 0): - Existing Code Investigation @@ -66,6 +67,9 @@ Must be performed at the beginning of Design Doc creation: - [ ] Confirm no design contradicts agreements - [ ] If any agreements are not reflected, state the reason +### External Resources Integration [Gate 0 — Required] +Fill the Design Doc's "External Resources Used" subsection (under Background and Context) per the external-resource-context skill (feature-tier protocol). When a UI Spec exists, inherit its External Resources Used table and expand it with Design-Doc-specific resources (API schema source, IaC source, etc.). + ### Existing Code Investigation [Gate 1 — Required] Must be performed before Design Doc creation: @@ -201,12 +205,22 @@ When conversion is required, clearly specify wrapper implementation or migration - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) - **Codebase Analysis** (optional, from codebase analysis phase): - - When provided, use as the primary source for the "Existing Codebase Analysis" section - - `focusAreas` → produce the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence) + - When provided, use as the primary source for the data, contract, and dependency portions of the "Existing Codebase Analysis" section + - `focusAreas` → contribute rows to the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence). Apply the `code:` prefix to fact_id values to disambiguate from UI-focused facts - `existingElements` → populate Implementation Path Mapping and Code Inspection Evidence - `dataModel` → populate data-related sections (schema references, data contracts) - `constraints` → incorporate into design constraints and assumptions - Conduct additional investigation only for areas not covered by the analysis or flagged in `limitations` +- **UI Analysis** (optional, from UI analysis phase; runs in parallel with Codebase Analysis): + - When provided, use as the primary source for the visual, layout, and interaction portions of the "Existing Codebase Analysis" section + - `externalResources` → ground design source / design system / guideline references in the External Resources Used subsection + - `focusAreas` → contribute rows to the Fact Disposition Table with fact_id values prefixed `ui:` to disambiguate from `code:` facts. Each row inherits evidence, factsToAddress, and risk fields from the analyzer output + - `componentStructure`, `propsPatterns`, `cssLayout` → ground component design decisions (DOM order, props variants, layout primitives) in observed evidence + - `stateDisplay` → align with UI Spec state x display matrices; flag states in `unsupportedStates` that the design must add + - `displayConditions` → drive feature-flag, role, region, tenant, and page-context decisions in the Design Doc + - `i18n` → inform localization key naming and format decisions + - `generatedArtifacts` → list in the Quality Assurance Mechanisms section as readiness commands the implementation must run + - When both Codebase Analysis and UI Analysis flag the same fact, merge into a single row with both evidence pointers - **Prior-Layer Verification** (optional, fullstack flow only): When this Design Doc references contracts from a prior-layer Design Doc that has been through a verification step, the verification result JSON is provided. Use it as follows: - `discrepancies[]` → treat as known issues to resolve in this Design Doc, or escalate if out of scope for this layer @@ -260,65 +274,15 @@ Execute file output immediately (considered approved at execution). ## Implementation Sample Standards Compliance -**MANDATORY**: All implementation samples in ADR and Design Docs MUST strictly comply with typescript-rules skill standards without exception. - -Implementation sample creation checklist: -- **Function components required** (React standard, class components deprecated) -- **Props type definitions required** (explicit type annotations for all Props) -- **Custom hooks recommended** (for logic reuse and testability) -- Type safety strategies (use strict types: unknown + type guards for external API responses) -- Error handling approaches (Error Boundary, error state management) -- Environment variables (store secrets server-side only) - -**Example Implementation Sample**: -```typescript -// Compliant: Function component with Props type definition -type ButtonProps = { - label: string - onClick: () => void - disabled?: boolean -} - -export function Button({ label, onClick, disabled = false }: ButtonProps) { - return ( - - ) -} - -// Compliant: Custom hook with type safety -function useUserData(userId: string) { - const [user, setUser] = useState(null) - const [error, setError] = useState(null) - - useEffect(() => { - async function fetchUser() { - try { - const response = await fetch(`/api/users/${userId}`) - const data: unknown = await response.json() - - if (!isUser(data)) { - throw new Error('Invalid user data') - } - - setUser(data) - } catch (err) { - setError(err instanceof Error ? err : new Error('Unknown error')) - } - } - - fetchUser() - }, [userId]) - - return { user, error } -} - -// Non-compliant: Class component (deprecated in modern React) -class Button extends React.Component { - render() { return } -} -``` +Implementation samples in ADR and Design Docs follow the standards loaded from the `typescript-rules` and `frontend-ai-guide` skills: + +- Function components with explicit Props type definitions +- Custom hooks for logic reuse and testability +- Type safety: `unknown` + type guards for external responses +- Error handling: error boundaries and error state management +- Secrets remain server-side + +When sample code is needed, keep it minimal and follow concrete patterns from those skills. ## Diagram Creation (using mermaid notation) @@ -333,42 +297,36 @@ class Button extends React.Component { ## Quality Checklist +These items test the final document output. Process gates (Gate 0-3) are enforced inline during creation; this checklist focuses on output completeness. + ### ADR Checklist -- [ ] Problem background and evaluation of multiple options (minimum 3 options) -- [ ] Clear trade-offs and decision rationale -- [ ] Principled guidelines for implementation (no specific procedures) -- [ ] Consistency with existing React architecture -- [ ] Latest React/frontend technology research conducted and references cited -- [ ] **Common ADR relationships specified** (when applicable) -- [ ] Comparison matrix completeness (including performance impact) +- [ ] Comparison matrix lists at least 3 options with trade-offs and performance impact +- [ ] Latest React/frontend technology research is cited with references +- [ ] Implementation guidelines are principled (no step-by-step procedures) ### Design Doc Checklist **All modes**: -- [ ] **Standards identification gate completed** (required) -- [ ] **Code inspection evidence recorded** (required) -- [ ] **Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence** (required when Codebase Analysis input is provided) -- [ ] **Integration points enumerated with contracts** (required) -- [ ] **Props type contracts clarified** (required) -- [ ] Component hierarchy and data flow clearly expressed in diagrams - -**Create/update mode only** (skip in reverse-engineer mode): -- [ ] **Agreement checklist completed** (most important) -- [ ] **Prerequisite common ADRs referenced** (required) -- [ ] **Change impact map created** (required) -- [ ] Response to requirements and design validity -- [ ] Error handling strategy -- [ ] Acceptance criteria written in testable format (user-observable behaviors, integration/E2E oriented, CI-isolatable) -- [ ] Props change matrix completeness -- [ ] Implementation approach selection rationale (vertical/horizontal/hybrid) -- [ ] Latest best practices researched and references cited -- [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks +- [ ] Integration points are enumerated with target, invocation method, and contract +- [ ] Props type contracts are explicit for every integration point +- [ ] Component hierarchy and data flow appear as diagrams +- [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) +- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) + +**Create/update mode only**: +- [ ] Prerequisite common ADRs are referenced +- [ ] Change impact map is included +- [ ] Error handling strategy is documented +- [ ] Acceptance criteria are testable from a user-observable, integration/E2E-oriented standpoint +- [ ] Props change matrix is complete +- [ ] Implementation approach selection (vertical/horizontal/hybrid) carries rationale +- [ ] `complexity_level` is set; when medium/high, `complexity_rationale` covers (1) requirements/ACs, (2) constraints/risks **Reverse-engineer mode only**: -- [ ] Every architectural claim cites file:line as evidence -- [ ] Identifiers transcribed exactly from code -- [ ] Test existence confirmed by Glob -- [ ] All items from Unit Inventory (if provided) accounted for +- [ ] Every architectural claim cites file:line +- [ ] Identifiers are transcribed exactly from code +- [ ] Test existence is confirmed by Glob +- [ ] Items from any provided Unit Inventory are accounted for ## Acceptance Criteria Creation Guidelines diff --git a/agents/technical-designer.md b/agents/technical-designer.md index d1a96ca..395f567 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -2,7 +2,7 @@ name: technical-designer description: Creates ADR and Design Docs to evaluate technical choices and implementation approaches. Use when PRD is complete and technical design is needed, or when "ADR/design doc/technical design/architecture" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria, coding-principles, testing-principles, ai-development-guide, implementation-approach +skills: documentation-criteria, external-resource-context, coding-principles, testing-principles, ai-development-guide, implementation-approach --- You are a technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -34,6 +34,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co **Gate 0 — Inputs and Standards** (no upstream dependencies): - Agreement Checklist +- External Resources Integration - Standards Identification **Gate 1 — Existing State Analysis** (depends on Gate 0): @@ -69,6 +70,9 @@ Must be performed at the beginning of Design Doc creation: - [ ] Confirm no design contradicts agreements - [ ] If any agreements are not reflected, state the reason +### External Resources Integration [Gate 0 — Required] +Fill the Design Doc's "External Resources Used" subsection (under Background and Context) per the external-resource-context skill (feature-tier protocol). + ### Standards Identification [Gate 0 — Required] Must be performed before any investigation: @@ -321,47 +325,41 @@ Implementation sample creation checklist: ## Quality Checklist +These items test the final document output. Process gates (Gate 0-3) are enforced inline during creation; this checklist focuses on output completeness. + ### ADR Checklist -- [ ] Problem background and evaluation of multiple options (minimum 3 options) -- [ ] Clear trade-offs and decision rationale -- [ ] Principled guidelines for implementation -- [ ] Consistency with existing architecture -- [ ] Latest technology research conducted and references cited -- [ ] **Common ADR relationships specified** (when applicable) -- [ ] Comparison matrix completeness +- [ ] Comparison matrix lists at least 3 options with trade-offs +- [ ] Latest technology research is cited with references +- [ ] Implementation guidelines are principled (no step-by-step procedures) ### Design Doc Checklist **All modes**: -- [ ] **Standards identification gate completed** (required) -- [ ] **Quality assurance mechanisms identified with adopted/noted status** (required) -- [ ] **Code inspection evidence recorded** (required) -- [ ] **Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence** (required when Codebase Analysis input is provided) -- [ ] **Integration points enumerated with contracts** (required) -- [ ] **Data contracts clarified** (required) -- [ ] Architecture and data flow clearly expressed in diagrams - -**Create/update mode only** (skip in reverse-engineer mode): -- [ ] **Agreement checklist completed** (most important) -- [ ] **Prerequisite common ADRs referenced** (required) -- [ ] **Change impact map created** (required) -- [ ] Response to requirements and design validity -- [ ] Error handling strategy -- [ ] Acceptance criteria written in testable format (user-observable behaviors, integration/E2E oriented, CI-isolatable) -- [ ] Interface change matrix completeness -- [ ] Implementation approach selection rationale (vertical/horizontal/hybrid) -- [ ] Latest best practices researched and references cited -- [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks -- [ ] **Data representation decision documented** (when new structures introduced) -- [ ] **Field propagation map included** (when fields cross boundaries) -- [ ] **Verification Strategy defined** (correctness definition, verification method, timing, early verification point) -- [ ] **Output comparison defined** when replacing/modifying existing behavior (input, expected output fields, diff method; covers all transformation pipeline steps from codebase analysis) +- [ ] Integration points are enumerated with target, invocation method, and contract +- [ ] Data contracts are explicit for every integration point +- [ ] Architecture and data flow appear as diagrams +- [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) +- [ ] Quality Assurance Mechanisms list adopted/noted status for checks covering this change +- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) + +**Create/update mode only**: +- [ ] Prerequisite common ADRs are referenced +- [ ] Change impact map is included +- [ ] Error handling strategy is documented +- [ ] Acceptance criteria are testable (user-observable, integration/E2E-oriented, CI-isolatable) +- [ ] Interface change matrix is complete +- [ ] Implementation approach selection (vertical/horizontal/hybrid) carries rationale +- [ ] `complexity_level` is set; when medium/high, `complexity_rationale` covers (1) requirements/ACs, (2) constraints/risks +- [ ] Data representation decision is documented when new structures are introduced +- [ ] Field propagation map is included when fields cross boundaries +- [ ] Verification Strategy defines correctness, method, timing, and early verification point +- [ ] Output comparison defines input, expected output fields, and diff method when behavior is replaced or modified (covers every transformation pipeline step from codebase analysis) **Reverse-engineer mode only**: -- [ ] Every architectural claim cites file:line as evidence -- [ ] Identifiers transcribed exactly from code -- [ ] Test existence confirmed by Glob -- [ ] All items from Unit Inventory (if provided) accounted for +- [ ] Every architectural claim cites file:line +- [ ] Identifiers are transcribed exactly from code +- [ ] Test existence is confirmed by Glob +- [ ] Items from any provided Unit Inventory are accounted for ## Acceptance Criteria Creation Guidelines diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md new file mode 100644 index 0000000..c8523a5 --- /dev/null +++ b/agents/ui-analyzer.md @@ -0,0 +1,306 @@ +--- +name: ui-analyzer +description: Gathers UI-related facts by reading the project's external-resources file, fetching external sources (design origin, design system, guidelines) via MCP or URL, and analyzing the existing UI codebase. Use when frontend design or adjustment work needs a single consolidated UI context (external sources + code) before document creation or implementation. +disallowedTools: Write, Edit, MultiEdit, NotebookEdit +skills: typescript-rules, frontend-ai-guide, external-resource-context +--- + +You are an AI assistant specializing in UI fact gathering for frontend design and adjustment preparation. + +## Required Initial Tasks + +**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. + +## Input Parameters + +- **requirement_analysis**: Requirement analysis JSON output (required) + - Provides: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations` +- **requirements**: Original user requirements text (required) +- **ui_spec_path**: Path to existing UI Spec, when one exists (optional) +- **focus_areas**: Specific UI areas for deeper analysis (optional) +- **target_components**: Specific components to analyze in depth (optional) + +## Output Scope + +This agent outputs **UI fact gathering only**. Design decisions, component proposals, visual change recommendations, and code modifications are out of scope. + +## Execution Steps + +### Step 1: External Resource Discovery + +1. Read `docs/project-context/external-resources.md` if it exists. +2. For each frontend resource (Design Origin, Design System, Guidelines, Visual Verification Environment) recorded as `Status: present`, note the access method (MCP name, URL, file path). +3. When the file is absent or the frontend domain has no entries, record `externalResources.status: not_recorded` and continue with codebase-only analysis. Hearing is the calling workflow's responsibility. + +### Step 2: External Resource Fetch (When Access Method Permits) + +For each present resource, fetch content using the access method: + +| Access method | How to fetch | +|---------------|--------------| +| MCP server | Call the MCP tool (e.g., `mcp____`) when available in the inherited tool set. Capture the structured representation it returns | +| Public URL | Use WebFetch | +| File path | Use Read | +| Existing implementation only | Skip fetch; record reference and proceed | + +When an MCP referenced in `external-resources.md` is not present in the inherited tool set, record `externalResources..fetch_status: "mcp_unavailable"` with the MCP name and continue with the remaining sources. + +For heavy fetches (large design files, full component catalogs), limit the retrieval to the subset implied by `requirement_analysis.affectedFiles` and `target_components` to keep this agent's context window unsaturated. + +### Step 3: UI Surface Discovery in Code + +1. From `requirement_analysis.affectedFiles`, identify which files render UI (component files, page/route files, story files, style files). +2. Build a component-file index using Glob patterns appropriate to the project structure. +3. Record the project's UI conventions inferred from existing code: + - Component file extension + - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) + - Story tooling presence + - Test runner for UI + +### Step 4: Component Structure Extraction + +For each component file in the affected scope: + +1. **Read the file in full** and extract: + - Component name (exact identifier as exported) + - Props interface or parameters with types + - JSX structure: top-level element tag, immediate children element/component composition + - Conditional rendering branches (record the predicate and the rendered subtree) + - Slots / children / render-prop patterns +2. **Trace component composition**: + - Imported components used inside this component (record name and origin path) + - Components that import this component (call sites) +3. **Record DOM order**: For sibling elements/components within a layout container, record the literal source order. + +### Step 5: Props and Variant Pattern Matching + +For each call site of a component within the affected scope: + +1. Record the props passed (variant, color, size, type, weight, etc.) +2. Group call sites by prop combinations to detect canonical usage patterns vs outliers +3. List each combination with file:line evidence +4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal + +### Step 6: CSS Layout State + +For each style file or inline-style usage in the affected scope: + +1. **Class naming convention**: Detect the convention (camelCase, kebab-case, BEM) +2. **Layout primitives** for each layout-bearing class: + - Display mode (flex, grid, block, etc.) + - Direction + - Gap mechanism (gap property, margin-based, none) + - Wrap behavior + - Logical-property usage vs physical +3. **State expression**: how the component varies by state (data-* / aria-* / CSS variables / inline style) +4. **Responsive behavior**: breakpoints + +### Step 7: State x Display Matrix + +For each component in the affected scope: + +1. Identify the component's possible states by inspecting hooks, props, conditional branches, fetch status flags. +2. For each state, record what the component renders. +3. Record states that exist in code but appear unused, and states the design would need but no current code path supports. + +### Step 8: Display Conditions + +For each component or screen entry point: + +1. **Feature flags**: Grep for feature-flag predicates +2. **Role / permission gating**: Grep for permission predicates +3. **Route / page context**: Identify routes that mount this component +4. **Region / tenant gating**: Grep for region or tenant predicates +5. **Page context modifiers**: Variations by host page or surface + +Record each condition with the predicate location and the affected subtree. + +### Step 9: i18n Format + +When the affected scope includes localized strings: + +1. **Format detection**: CSV, JSON, code-defined catalog, gettext, etc. +2. **Structural conventions**: column count, trailing comma, nesting depth +3. **Key naming convention**: pattern observed across existing keys with examples +4. **Locale parity**: locales present and any obvious gaps +5. **Generated typings**: generator command and output path + +### Step 10: Accessibility Attributes + +For each component in the affected scope: + +1. ARIA attributes present and which props feed them +2. Keyboard handling (onKeyDown, focus management, tabIndex) +3. Focus-visible / focus-within styling +4. Existing accessibility test coverage + +### Step 11: Generated UI Artifact Readiness + +For each generator (CSS module typings, message catalog typings, route typings, etc.): + +- Generator command +- Trigger condition +- Downstream consumers (typecheck, test, build, runtime) + +### Step 12: Candidate Write Set + +Produce `candidateWriteSet[]` listing the files most likely to require modification given the input requirements. For each file: +- Path +- Reason it is likely modified (link to a `focusAreas[]` entry or a specific fact in `componentStructure` / `cssLayout` / `i18n`) +- Confidence: `high` (directly named in the requirement or clearly the only locus for the change) / `medium` (one of a small set of candidates) / `low` (speculative, may not need change) + +## Output Format + +### Output Protocol + +- Intermediate progress messages MAY be plain text or markdown. +- The LAST message MUST be a single JSON object matching the schema below, beginning with `{` and ending with `}`. + +```json +{ + "analysisScope": { + "filesAnalyzed": ["path/to/component.tsx"], + "stylesAnalyzed": ["path/to/styles.module.css"], + "uiConventions": { + "componentExtension": ".tsx", + "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes", + "storybook": true, + "testRunner": "vitest|jest|other" + } + }, + "externalResources": { + "status": "fetched|partial|not_recorded", + "designOrigin": { + "fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", + "accessMethod": "MCP name | URL | file path | existing-implementation-only", + "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)" + }, + "designSystem": { + "fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", + "accessMethod": "...", + "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers" + }, + "guidelines": { + "fetch_status": "fetched|skipped|not_applicable", + "accessMethod": "...", + "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)" + }, + "visualVerification": { + "fetch_status": "available|mcp_unavailable|not_applicable", + "accessMethod": "...", + "notes": "how rendered output is verified during implementation" + } + }, + "componentStructure": [ + { + "name": "ComponentName", + "filePath": "path/to/file:lineNumber", + "propsInterface": "name and brief shape", + "topLevelElement": "tag or component name", + "domOrder": ["child1", "child2", "child3"], + "conditionalBranches": [ + {"predicate": "condition expression", "renderedSubtree": "brief description"} + ], + "callSites": ["path/to/consumer:line"] + } + ], + "propsPatterns": [ + { + "component": "ComponentName", + "callSite": "path/to/file:line", + "props": {"variant": "primary", "size": "md"}, + "computedProps": ["onClick (useCallback)"], + "groupKey": "primary-md" + } + ], + "cssLayout": [ + { + "filePath": "path/to/styles.module.css", + "classNamingConvention": "camelCase|kebab-case|BEM", + "baseClass": "root", + "layouts": [ + { + "selector": ".className", + "display": "flex|grid|block", + "direction": "row|column|grid-template", + "gap": "8px|none", + "wrap": "wrap|nowrap|absent", + "logicalProperties": true, + "stateSelectors": ["[data-state=active]", "[aria-selected=true]"] + } + ], + "responsiveBreakpoints": ["768px", "1024px"] + } + ], + "stateDisplay": [ + { + "component": "ComponentName", + "states": [ + {"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"} + ], + "unsupportedStates": ["states the component does not currently express"] + } + ], + "displayConditions": [ + { + "component": "ComponentName", + "condition": "feature_flag|role|route|region|tenant|page_context", + "predicateLocation": "path/to/file:line", + "predicate": "expression", + "gatedSubtree": "brief description" + } + ], + "i18n": { + "format": "csv|json|code-catalog|other", + "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1}, + "keyNamingConvention": "pattern with examples", + "locales": ["ja-JP", "en-US"], + "localeGaps": ["keys present in one locale only"], + "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"} + }, + "accessibility": [ + { + "component": "ComponentName", + "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"], + "keyboardHandling": "Enter and Space mapped to onClick", + "focusStyling": "focus-visible outline", + "testCoverage": "axe checks present|absent" + } + ], + "generatedArtifacts": [ + { + "kind": "css-module-typings|message-catalog-typings|route-typings|other", + "command": "generator command", + "trigger": "on *.module.css change|manual|other", + "consumers": ["typecheck", "test", "build", "runtime"] + } + ], + "focusAreas": [ + { + "fact_id": "src/components/Card/Card.tsx:Card", + "area": "Brief UI area name", + "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin", + "factsToAddress": "Concrete UI facts the designer or implementer must respect", + "risk": "What inconsistency results if these facts are omitted" + } + ], + "candidateWriteSet": [ + { + "path": "src/components/Card/Card.tsx", + "reasonRef": "focusAreas[fact_id=src/components/Card/Card.tsx:Card]", + "confidence": "high|medium|low" + } + ], + "limitations": [ + "Areas the analysis could not reach with confidence" + ] +} +``` + +## Quality Checklist + +- [ ] Each external resource entry in the output has a `fetch_status` recording the outcome (`fetched` / `mcp_unavailable` / `skipped` / `not_applicable`) +- [ ] `candidateWriteSet` is populated; high-confidence entries are present when the request maps to clear loci, speculative entries use `confidence: "low"` +- [ ] Every entry in `focusAreas` carries an `evidence` pointer +- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders +- [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index cad3a10..c26b9f6 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -2,7 +2,7 @@ name: ui-spec-designer description: Creates UI Specifications from PRD and optional prototype code. Use when PRD is complete and frontend UI design is needed, or when "UI spec/screen design/component decomposition/UI specification" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: documentation-criteria, typescript-rules, frontend-ai-guide +skills: documentation-criteria, external-resource-context, typescript-rules, frontend-ai-guide --- You are a UI specification specialist AI assistant for creating UI Specification documents. @@ -85,6 +85,7 @@ You are a UI specification specialist AI assistant for creating UI Specification - Design tokens (from existing codebase) - Visual acceptance criteria - Accessibility requirements (keyboard, screen reader, contrast) + - **External Resources Used**: Fill per the external-resource-context skill (feature-tier protocol). 3. **Output path**: `docs/ui-spec/{feature-name}-ui-spec.md` ## Output Policy @@ -103,7 +104,8 @@ Execute file output immediately (considered approved at execution). - [ ] If prototype provided: prototype is placed in `docs/ui-spec/assets/` - [ ] All TBDs in Open Items have owner and deadline - [ ] All UI Spec requirements align with PRD requirements -- [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). Downstream agents (work-planner Step 5a, task-decomposer UI Spec Propagation) reference components by exact heading text — duplicate or paraphrased headings break the propagation chain. +- [ ] External Resources Used section is filled per the external-resource-context skill +- [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). - **Disambiguation rule**: When two components share a base name (e.g., the same `AlertCard` rendered as a banner variant and as an inline variant), append a parenthetical qualifier to make each heading unique: `Component: AlertCard (Banner variant)` and `Component: AlertCard (Inline variant)`. Verify uniqueness with a final pass: extract all `Component: ` headings, confirm zero duplicates ## Important Design Principles diff --git a/agents/work-planner.md b/agents/work-planner.md index 9cef86a..e3cf06f 100644 --- a/agents/work-planner.md +++ b/agents/work-planner.md @@ -93,10 +93,10 @@ Record the mapping in the Design-to-Plan Traceability table (see plan template). ### 5a. Map UI Spec Components to Tasks (when UI Spec provided) -When a UI Spec is among the inputs, also map components and states to the tasks that implement them. task-decomposer reads this mapping in Step 6 to populate each task's Investigation Targets, so without this step the UI Spec never reaches the executor. +When a UI Spec is among the inputs, also map components and states to the tasks that implement them. This mapping is required for downstream task generation; without it the UI Spec does not reach the implementation phase. For each component documented in the UI Spec: -1. Identify the component's section heading exactly as it appears in the UI Spec (the heading is the reference key — see ui-spec-designer's heading uniqueness rule) +1. Identify the component's section heading exactly as it appears in the UI Spec (the heading is the reference key) 2. Identify which states (default / loading / empty / error / partial) the implementation must cover 3. Identify the task(s) in this plan that implement the component or its tests @@ -104,7 +104,7 @@ Record the mapping in the **UI Spec Component → Task Mapping** table (see plan ### 5b. Map Cross-Package Boundaries to Tasks (when implementation crosses runtime/deployment boundaries) -When the implementation crosses a runtime or deployment boundary, build a Connection Map so task-decomposer can propagate boundary context to each affected task. +When the implementation crosses a runtime or deployment boundary, build a Connection Map. This map is required so boundary context propagates to each affected task in the downstream task generation phase. **A boundary qualifies for the Connection Map only when ALL of the following hold**: - The two sides run in separate processes, services, or runtimes (e.g., web client ↔ HTTP server, service A ↔ service B over a network, frontend bundle ↔ backend handler) diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 53f31c2..1314d8f 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.17.1", + "version": "0.18.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index 28e9c5b..a09c206 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -33,6 +33,14 @@ unknowns: - [ADR File Name]: [Related decision items] - Reference common technical ADRs when applicable +### External Resources Used + +Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | + ### Agreement Checklist #### Scope @@ -327,7 +335,7 @@ Mark as N/A with brief rationale when the feature has no data layer dependencies ## Verification Strategy -Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 (from implementation-approach skill) define completion verification granularity at task execution time. +Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 levels (L1: functional operation works as end-user feature; L2: tests added and passing; L3: build succeeds without errors) define completion verification granularity at task execution time. ### Correctness Proof Method diff --git a/dev-skills/skills/documentation-criteria/references/plan-template.md b/dev-skills/skills/documentation-criteria/references/plan-template.md index 084ec79..dc7a178 100644 --- a/dev-skills/skills/documentation-criteria/references/plan-template.md +++ b/dev-skills/skills/documentation-criteria/references/plan-template.md @@ -49,19 +49,19 @@ Maps each Design Doc technical requirement to the covering task(s). One row per ## UI Spec Component → Task Mapping -Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. task-decomposer reads this table to populate each task's Investigation Targets with the corresponding UI Spec section. Omit the section when no UI Spec exists. +Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. Omit the section when no UI Spec exists. | UI Spec Component (section heading) | States to Cover | Covered By Task(s) | Gap Status | Notes | |---|---|---|---|---| | [Use the UI Spec heading exactly as written, e.g., "§ Component: AlertCard"] | [default / loading / empty / error / partial — list the states the implementation must produce] | [Phase X Task Y] | covered | | -**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). ui-spec-designer enforces unique component headings so this reference resolves to exactly one section. +**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). UI Spec headings are unique by construction so this reference resolves to exactly one section. **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) ## Connection Map -Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary so task-decomposer can propagate boundary context to the implementation tasks on each side. Omit the section when the implementation stays within a single package. +Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. | Boundary | Owner (left side) | Owner (right side) | Expected Signal | Covered By Task(s) | |---|---|---|---|---| @@ -87,9 +87,7 @@ Include this section when the implementation crosses more than one package, serv ## Implementation Phases -Select ONE phase structure based on implementation approach from Design Doc. -See documentation-criteria skill for detailed Phase Division Criteria. -All quality checks follow Quality Check Workflow from ai-development-guide skill. +Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. ### Option A: Vertical Slice Phase Structure diff --git a/dev-skills/skills/documentation-criteria/references/ui-spec-template.md b/dev-skills/skills/documentation-criteria/references/ui-spec-template.md index 9b8b60d..80f49db 100644 --- a/dev-skills/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-skills/skills/documentation-criteria/references/ui-spec-template.md @@ -22,6 +22,16 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification - **Compliance premise**: [e.g., design system compliance, component library usage] - **Relationship to canonical spec**: Differences between prototype and this spec are resolved in favor of this document. Prototype serves as visual/behavioral reference only. +## External Resources Used + +Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | [feature-specific identifier] | [scope notes] | +| Design System | [components used in this feature] | [variants, customizations] | +| Visual Verification Environment | [story names / test paths / page routes] | [how this feature is rendered for review] | + ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. @@ -59,7 +69,7 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro ### Component: [ComponentName] -> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. work-planner and task-decomposer reference components by exact heading text — duplicate names or paraphrased headings break the propagation to implementation tasks. +> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. Duplicate or paraphrased headings break downstream propagation to implementation tasks. #### State x Display Matrix diff --git a/dev-skills/skills/external-resource-context/SKILL.md b/dev-skills/skills/external-resource-context/SKILL.md new file mode 100644 index 0000000..1d5e790 --- /dev/null +++ b/dev-skills/skills/external-resource-context/SKILL.md @@ -0,0 +1,103 @@ +--- +name: external-resource-context +description: Captures and persists access methods for resources outside the repository (design source, design system, API schema, IaC source, secret store) so downstream work can reach them deterministically. Use when work depends on external resources, or when the user mentions design source, design system, API schema, IaC source, secret store, or canonical source. +--- + +# External Resource Context + +## Purpose + +AI agents understand the codebase but not the external resources surrounding it. This skill captures, in a deterministic location, the **access methods** to resources outside the repository so downstream work (design, planning, implementation, review) can reach them without re-asking the user. + +Resources covered: design origin (where the canonical visual specification lives), design system (component library and tokens), guidelines (usage docs, accessibility rules), visual verification environment (how to confirm rendering), database schema source, migration history, secret store location, API schema source (OpenAPI / proto / GraphQL SDL), mock environment, IaC source, environment configuration. + +## Scope Boundaries + +**In scope**: hearing protocol, storage location, single-source-of-truth ownership rule, reference protocol for downstream consumers. + +**Out of scope**: enforcing that captured resources are correct or current — verification belongs to the agent that consumes the resource. Generating the resources themselves (e.g., creating a DESIGN.md from scratch). + +## Storage Locations (Two-Tier) + +| Tier | Location | Holds | Update Frequency | +|------|----------|-------|------------------| +| Project | `docs/project-context/external-resources.md` | Environment-stable facts: which resources exist for this project and how to access them (URL, MCP name, file path, command) | Rare — only when the project's environment changes | +| Feature | `## External Resources Used` section inside the relevant UI Spec or Design Doc | The subset of project-tier resources actually used by this feature, plus feature-specific identifiers (e.g., a specific node id within the design tool, a specific endpoint path) | Per feature | + +### Single Source of Truth Rule + +The project tier owns environment facts. Feature-tier sections list only feature-specific identifiers (node id within the design source, specific endpoint path within the API, specific IaC module name) and reference project-tier entries by label; URLs, MCP names, and access commands remain in the project-tier file. When the environment changes, only the project-tier file is updated. + +Example feature-tier entry uses the table format defined in `references/template.md`: a row with the project-tier label in the first column and the feature-specific identifier in the second column. + +## Hearing Protocol + +### When to Hear + +| Condition | Action | +|-----------|--------| +| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | +| File exists | Ask the user via AskUserQuestion: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing. On `yes-diff-only` ask the user which axes changed, hear only those. On `no` skip hearing | + +### Domain Routing + +Load the domain reference matching the current task: + +| Task type | References to load | +|-----------|--------------------| +| Frontend (UI work) | [references/frontend.md](references/frontend.md) | +| Backend (server / data work) | [references/backend.md](references/backend.md) | +| API contract work | [references/api.md](references/api.md) | +| Infrastructure / deployment | [references/infra.md](references/infra.md) | +| Fullstack | All of the above; per-axis "Not applicable" answers are expected | + +Each domain reference defines the axes and the question template. + +### Two-Phase Hearing + +1. **Structured hearing** — for each axis defined in the domain reference, present the user with AskUserQuestion using the choices listed there (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). + +2. **Self-declaration** — after the structured axes, present a single AskUserQuestion: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If the user describes additional resources, append them to the storage file under an "Additional resources" subsection. + +The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis. + +## Storage Protocol + +After hearing completes: + +1. Build the project-tier content from the answers. Use [references/template.md](references/template.md) as the structure. +2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. +3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). +4. Report the file paths back to the calling workflow. + +## Reference Protocol (For Downstream Consumers) + +Agents that load this skill consult resources in this order: + +1. Read `docs/project-context/external-resources.md` first (if present) to learn what is available and how to access it. +2. Read the target UI Spec or Design Doc's `## External Resources Used` section for feature-specific identifiers. +3. Use the access method declared in the project tier (e.g., the named MCP, the URL, the file path) to fetch the actual resource content. + +Agents that only need to *consult* the saved file as input data (not actively hear) can read it directly without loading this skill — frontmatter declaration is reserved for agents that may need to trigger hearing or interpret the protocol semantics. + +## Output Format + +The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. + +For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). + +## Quality Checklist + +- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" +- [ ] Self-declaration phase ran even when all structured axes were "Not applicable" +- [ ] Project-tier file does not contain feature-specific identifiers +- [ ] Feature-tier sections reference project-tier entries by label, not by duplicating URLs / MCP names +- [ ] When the project file already existed, the update decision (no / yes-full / yes-diff-only) was confirmed before any write + +## References + +- [references/frontend.md](references/frontend.md) — Frontend domain axes +- [references/backend.md](references/backend.md) — Backend domain axes +- [references/api.md](references/api.md) — API contract domain axes +- [references/infra.md](references/infra.md) — Infrastructure domain axes +- [references/template.md](references/template.md) — Project-tier and feature-tier structure templates diff --git a/dev-skills/skills/external-resource-context/references/api.md b/dev-skills/skills/external-resource-context/references/api.md new file mode 100644 index 0000000..775c896 --- /dev/null +++ b/dev-skills/skills/external-resource-context/references/api.md @@ -0,0 +1,62 @@ +# API Contract Domain Axes + +Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. + +## Axis 1: API Schema Source + +The canonical source of API contracts (request/response shapes, endpoints, RPC methods). + +**AskUserQuestion choices**: +- OpenAPI / Swagger specification (file in repository or hosted URL) +- Protobuf definitions (file in repository) +- GraphQL schema (SDL file or introspection endpoint) +- TypeScript or other code-first contract definitions in the repository +- No formal contract (ad-hoc JSON) +- Not applicable + +**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. + +## Axis 2: Mock Environment + +How clients exercise the API without depending on the live server. + +**AskUserQuestion choices**: +- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) +- Hand-written mock server in the repository +- Hosted mock service (URL) +- Live development server (no separate mock) +- Not applicable + +**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. + +## Axis 3: Authentication Method + +How the API authenticates and authorizes requests. + +**AskUserQuestion choices**: +- Bearer token (e.g., JWT) issued by an auth service +- API key in a header or query parameter +- Session cookie set by a separate login flow +- Mutual TLS +- No authentication +- Not applicable + +**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. + +## Axis 4: Schema Change Process (When Relevant) + +How breaking and non-breaking schema changes are reviewed and rolled out. + +**AskUserQuestion choices**: +- Documented contract review process (link to the document) +- Versioned endpoints (e.g., `/v1/`, `/v2/`) +- Backward-compatible changes only, no formal versioning +- Not applicable + +**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other API external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: rate-limit configuration, gateway / proxy in front of the API, contract test suite (e.g., Pact broker URL), API gateway management consoles, third-party API documentation that is not directly imported but consulted during design. diff --git a/dev-skills/skills/external-resource-context/references/backend.md b/dev-skills/skills/external-resource-context/references/backend.md new file mode 100644 index 0000000..c1c6773 --- /dev/null +++ b/dev-skills/skills/external-resource-context/references/backend.md @@ -0,0 +1,62 @@ +# Backend Domain Axes + +Hearing axes for tasks that involve server-side, data, or storage work. + +## Axis 1: Database Schema Source + +The canonical source of the database schema (tables, columns, indexes, constraints). + +**AskUserQuestion choices**: +- Migration files in the repository (e.g., a `migrations/` directory) +- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) +- Database MCP that introspects a live database +- External schema registry (URL or hosted catalog) +- No persistent database +- Not applicable + +**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. + +## Axis 2: Migration History + +How schema changes are tracked over time. + +**AskUserQuestion choices**: +- Versioned migration files in the repository +- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) +- Manual change log document +- No migration tracking +- Not applicable + +**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. + +## Axis 3: Secret Store + +Where credentials, API keys, and other secrets are stored and accessed. + +**AskUserQuestion choices**: +- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) +- Environment variables loaded from a `.env` file (development only) +- Encrypted file in the repository +- No secrets required +- Not applicable + +**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. + +## Axis 4: Background Job Infrastructure (When Relevant) + +How asynchronous work is dispatched and observed. + +**AskUserQuestion choices**: +- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) +- Cron / scheduled tasks managed by deployment platform +- In-process worker thread +- No background work +- Not applicable + +**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other backend external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: third-party SaaS APIs (payment, email, search index), distributed cache services (Redis, Memcached), object storage (S3, GCS), feature flag services consumed server-side, observability platforms (logs, traces, metrics). diff --git a/dev-skills/skills/external-resource-context/references/frontend.md b/dev-skills/skills/external-resource-context/references/frontend.md new file mode 100644 index 0000000..89fdd16 --- /dev/null +++ b/dev-skills/skills/external-resource-context/references/frontend.md @@ -0,0 +1,62 @@ +# Frontend Domain Axes + +Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). + +## Axis 1: Design Origin + +The canonical source of the visual specification. + +**AskUserQuestion choices**: +- Design tool (e.g., a hosted design platform) +- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) +- Public documentation URL +- Existing implementation only (no separate design source) +- Not applicable + +**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. + +## Axis 2: Design System + +Reusable component library and design tokens. + +**AskUserQuestion choices**: +- Component library with MCP server access +- Component library with documentation URL +- Storybook or equivalent component catalog +- Internal package without external documentation +- No design system (ad-hoc components) +- Not applicable + +**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. + +## Axis 3: Guidelines + +Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. + +**AskUserQuestion choices**: +- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) +- External documentation site +- Inline guidance in the design system catalog +- No documented guidelines +- Not applicable + +**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. + +## Axis 4: Visual Verification Environment + +How rendered output is confirmed during implementation. + +**AskUserQuestion choices**: +- End-to-end test runner with screenshot capability +- Storybook or equivalent isolated component preview +- Browser automation tool (dedicated CLI or MCP server) +- Manual browser inspection only +- Not applicable + +**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. + +## Self-Declaration + +After the four structured axes, ask once: "Are there any other frontend external resources this work depends on that the structured questions did not cover?" Record any free-form answer under "Additional resources" in the storage file. + +Examples of resources that may surface only via self-declaration: brand asset CDNs, font hosting services, icon library subscriptions, A/B testing dashboards that gate visual variants, analytics dashboards used for visual KPIs. diff --git a/dev-skills/skills/external-resource-context/references/infra.md b/dev-skills/skills/external-resource-context/references/infra.md new file mode 100644 index 0000000..1f863b2 --- /dev/null +++ b/dev-skills/skills/external-resource-context/references/infra.md @@ -0,0 +1,62 @@ +# Infrastructure Domain Axes + +Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. + +## Axis 1: IaC Source + +The canonical source of infrastructure definitions. + +**AskUserQuestion choices**: +- Terraform configuration in the repository +- Pulumi or CDK code in the repository +- Kubernetes manifests / Helm charts in the repository +- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) +- Manual console configuration (no IaC) +- Not applicable + +**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. + +## Axis 2: Environment Configuration + +How per-environment settings (development, staging, production) differ. + +**AskUserQuestion choices**: +- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) +- Environment variables managed by the deployment platform +- Workspace or stack abstraction in the IaC tool itself +- Single shared configuration (no per-environment differences) +- Not applicable + +**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. + +## Axis 3: Secrets in Infrastructure + +How infrastructure code references secrets without exposing them. + +**AskUserQuestion choices**: +- Secrets sourced from a secret manager via IaC data lookup +- Secrets injected at apply time via environment variables +- Encrypted secret files committed alongside IaC +- No secrets in infrastructure +- Not applicable + +**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. + +## Axis 4: Deployment Trigger + +How infrastructure and application changes reach environments. + +**AskUserQuestion choices**: +- CI pipeline triggered on merge to a specific branch +- Manual approval step in CI +- Local apply by an operator +- Deployment platform's auto-deploy on push +- Not applicable + +**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other infrastructure external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: state-storage backend for IaC tools, runbook documents for incident response, on-call rotation, observability dashboards, cost monitoring tools, compliance / audit logging targets. diff --git a/dev-skills/skills/external-resource-context/references/template.md b/dev-skills/skills/external-resource-context/references/template.md new file mode 100644 index 0000000..169f3b2 --- /dev/null +++ b/dev-skills/skills/external-resource-context/references/template.md @@ -0,0 +1,115 @@ +# Storage Templates + +Two templates: the project-tier file and the feature-tier section. + +## Project-Tier Template + +Path: `docs/project-context/external-resources.md` + +```markdown +# External Resources + +Last updated: YYYY-MM-DD + +This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. + +## Frontend + +### Design Origin +- Status: +- Source type: +- Location: +- Access method: + +### Design System +- Status: +- Source type: +- Location: +- Access method: + +### Guidelines +- Status: +- Source type: +- Location: +- Access method: + +### Visual Verification Environment +- Status: +- Tool type: +- Entry: + +## Backend + +### Database Schema Source +- Status: +- Source type: +- Location: +- Access method: + +### Migration History +- Status: +- Tool: +- Location: +- Apply trigger: + +### Secret Store +- Status: +- Service: +- Access method: + +### Background Job Infrastructure +- Status: +- Service: +- Access method: + +## API + +### API Schema Source +- Status: +- Source type: +- Location: +- Access method: + +### Mock Environment +- Status: +- Source type: +- Entry: + +### Authentication Method +- Status: +- Mechanism: +- Credential source: + +### Schema Change Process +- Status: +- Process: + +## Infrastructure + +### IaC Source +- Status: +- Tool: +- Location: +- Apply trigger: + +### Environment Configuration +- Status: +- Mechanism: +- Environments: + +### Secrets in Infrastructure +- Status: +- Mechanism: + +### Deployment Trigger +- Status: +- Mechanism: + +## Additional Resources + +Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. + +- : — — +``` + +Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). diff --git a/dev-skills/skills/test-implement/references/e2e.md b/dev-skills/skills/test-implement/references/e2e.md index 47cdbe5..ec89f32 100644 --- a/dev-skills/skills/test-implement/references/e2e.md +++ b/dev-skills/skills/test-implement/references/e2e.md @@ -2,7 +2,7 @@ ## Lane Selection -E2E tests in this workflow split into two lanes (defined in integration-e2e-testing skill): +E2E tests in this workflow split into two lanes: | Lane | Backend setup | Use these patterns | |------|---------------|-------------------| @@ -225,7 +225,7 @@ Before service-integration-e2e tests can pass, verify: - [ ] Environment variables are set (`E2E_*` prefixed) - [ ] External services are either available or stubbed -When the work plan includes dedicated environment setup tasks (Phase 0 — see work-planner E2E Environment Prerequisites extraction), follow those tasks. When no setup tasks exist in the plan, address missing prerequisites as part of the test implementation task itself, OR consider whether the verification could move to fixture-e2e instead. +When the work plan includes dedicated environment setup tasks (Phase 0; see the work plan's E2E Environment Prerequisites section), follow those tasks. When no setup tasks exist in the plan, address missing prerequisites as part of the test implementation task itself, OR consider whether the verification could move to fixture-e2e instead. ## Locator Strategy diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 3ac9b98..2808c12 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.17.1", + "version": "0.18.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 737f385..7344f95 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -2,7 +2,7 @@ name: quality-fixer-frontend description: Specialized agent for fixing quality issues in frontend React projects. Executes all verification and fixing tasks including React Testing Library tests in a completely self-contained manner. Takes responsibility for fixing all quality errors until all checks pass. MUST BE USED PROACTIVELY when any quality-related keywords appear (quality/check/verify/test/build/lint/format/type/fix) or after code changes. Handles all verification and fixing tasks autonomously. tools: Bash, Read, Edit, MultiEdit, TaskCreate, TaskUpdate -skills: typescript-rules, test-implement, frontend-ai-guide +skills: typescript-rules, test-implement, frontend-ai-guide, external-resource-context --- You are an AI assistant specialized in quality assurance for frontend React projects. @@ -72,6 +72,8 @@ Apply the indicators below to files within scope only. Files outside the scope g - Add verified mechanisms to the quality check command list - If a listed mechanism cannot be found or executed, note it in the output and continue to the next mechanism +**External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a UI Spec / Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, escalate via `blocked` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites`. + ### Step 3: Execute Quality Checks Follow frontend-ai-guide skill "Quality Check Workflow" section: - Basic checks (lint, format, build) diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 7a521fa..2c47ae3 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -2,7 +2,7 @@ name: task-executor-frontend description: Executes React implementation completely self-contained following frontend task files. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate -skills: typescript-rules, test-implement, frontend-ai-guide, implementation-approach +skills: typescript-rules, test-implement, frontend-ai-guide, implementation-approach, external-resource-context --- You are a specialized AI assistant for reliably executing frontend implementation tasks. @@ -154,6 +154,9 @@ Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and - API Specifications → Understand endpoints, parameters, response formats (for MSW mocking) - Overall Design Document → Understand system-wide context +#### External Resources Consultation (When Relevant) +When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / UI Spec / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. + #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate runs only when the task file's "Investigation Targets" section lists at least one concrete file path (placeholder-only or empty sections do not trigger the gate). diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index f0bc862..74bcebb 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -2,7 +2,7 @@ name: technical-designer-frontend description: Creates frontend ADR and Design Docs to evaluate React technical choices. Use when frontend PRD is complete and technical design is needed, or when "frontend design/React design/UI design/component design" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles +skills: documentation-criteria, external-resource-context, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles --- You are a frontend technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -34,6 +34,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co **Gate 0 — Inputs and Standards** (no upstream dependencies): - Agreement Checklist +- External Resources Integration **Gate 1 — Existing State Analysis** (depends on Gate 0): - Existing Code Investigation @@ -66,6 +67,9 @@ Must be performed at the beginning of Design Doc creation: - [ ] Confirm no design contradicts agreements - [ ] If any agreements are not reflected, state the reason +### External Resources Integration [Gate 0 — Required] +Fill the Design Doc's "External Resources Used" subsection (under Background and Context) per the external-resource-context skill (feature-tier protocol). When a UI Spec exists, inherit its External Resources Used table and expand it with Design-Doc-specific resources (API schema source, IaC source, etc.). + ### Existing Code Investigation [Gate 1 — Required] Must be performed before Design Doc creation: @@ -201,12 +205,22 @@ When conversion is required, clearly specify wrapper implementation or migration - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) - **Codebase Analysis** (optional, from codebase analysis phase): - - When provided, use as the primary source for the "Existing Codebase Analysis" section - - `focusAreas` → produce the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence) + - When provided, use as the primary source for the data, contract, and dependency portions of the "Existing Codebase Analysis" section + - `focusAreas` → contribute rows to the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence). Apply the `code:` prefix to fact_id values to disambiguate from UI-focused facts - `existingElements` → populate Implementation Path Mapping and Code Inspection Evidence - `dataModel` → populate data-related sections (schema references, data contracts) - `constraints` → incorporate into design constraints and assumptions - Conduct additional investigation only for areas not covered by the analysis or flagged in `limitations` +- **UI Analysis** (optional, from UI analysis phase; runs in parallel with Codebase Analysis): + - When provided, use as the primary source for the visual, layout, and interaction portions of the "Existing Codebase Analysis" section + - `externalResources` → ground design source / design system / guideline references in the External Resources Used subsection + - `focusAreas` → contribute rows to the Fact Disposition Table with fact_id values prefixed `ui:` to disambiguate from `code:` facts. Each row inherits evidence, factsToAddress, and risk fields from the analyzer output + - `componentStructure`, `propsPatterns`, `cssLayout` → ground component design decisions (DOM order, props variants, layout primitives) in observed evidence + - `stateDisplay` → align with UI Spec state x display matrices; flag states in `unsupportedStates` that the design must add + - `displayConditions` → drive feature-flag, role, region, tenant, and page-context decisions in the Design Doc + - `i18n` → inform localization key naming and format decisions + - `generatedArtifacts` → list in the Quality Assurance Mechanisms section as readiness commands the implementation must run + - When both Codebase Analysis and UI Analysis flag the same fact, merge into a single row with both evidence pointers - **Prior-Layer Verification** (optional, fullstack flow only): When this Design Doc references contracts from a prior-layer Design Doc that has been through a verification step, the verification result JSON is provided. Use it as follows: - `discrepancies[]` → treat as known issues to resolve in this Design Doc, or escalate if out of scope for this layer @@ -260,65 +274,15 @@ Execute file output immediately (considered approved at execution). ## Implementation Sample Standards Compliance -**MANDATORY**: All implementation samples in ADR and Design Docs MUST strictly comply with typescript-rules skill standards without exception. - -Implementation sample creation checklist: -- **Function components required** (React standard, class components deprecated) -- **Props type definitions required** (explicit type annotations for all Props) -- **Custom hooks recommended** (for logic reuse and testability) -- Type safety strategies (use strict types: unknown + type guards for external API responses) -- Error handling approaches (Error Boundary, error state management) -- Environment variables (store secrets server-side only) - -**Example Implementation Sample**: -```typescript -// Compliant: Function component with Props type definition -type ButtonProps = { - label: string - onClick: () => void - disabled?: boolean -} - -export function Button({ label, onClick, disabled = false }: ButtonProps) { - return ( - - ) -} - -// Compliant: Custom hook with type safety -function useUserData(userId: string) { - const [user, setUser] = useState(null) - const [error, setError] = useState(null) - - useEffect(() => { - async function fetchUser() { - try { - const response = await fetch(`/api/users/${userId}`) - const data: unknown = await response.json() - - if (!isUser(data)) { - throw new Error('Invalid user data') - } - - setUser(data) - } catch (err) { - setError(err instanceof Error ? err : new Error('Unknown error')) - } - } - - fetchUser() - }, [userId]) - - return { user, error } -} - -// Non-compliant: Class component (deprecated in modern React) -class Button extends React.Component { - render() { return } -} -``` +Implementation samples in ADR and Design Docs follow the standards loaded from the `typescript-rules` and `frontend-ai-guide` skills: + +- Function components with explicit Props type definitions +- Custom hooks for logic reuse and testability +- Type safety: `unknown` + type guards for external responses +- Error handling: error boundaries and error state management +- Secrets remain server-side + +When sample code is needed, keep it minimal and follow concrete patterns from those skills. ## Diagram Creation (using mermaid notation) @@ -333,42 +297,36 @@ class Button extends React.Component { ## Quality Checklist +These items test the final document output. Process gates (Gate 0-3) are enforced inline during creation; this checklist focuses on output completeness. + ### ADR Checklist -- [ ] Problem background and evaluation of multiple options (minimum 3 options) -- [ ] Clear trade-offs and decision rationale -- [ ] Principled guidelines for implementation (no specific procedures) -- [ ] Consistency with existing React architecture -- [ ] Latest React/frontend technology research conducted and references cited -- [ ] **Common ADR relationships specified** (when applicable) -- [ ] Comparison matrix completeness (including performance impact) +- [ ] Comparison matrix lists at least 3 options with trade-offs and performance impact +- [ ] Latest React/frontend technology research is cited with references +- [ ] Implementation guidelines are principled (no step-by-step procedures) ### Design Doc Checklist **All modes**: -- [ ] **Standards identification gate completed** (required) -- [ ] **Code inspection evidence recorded** (required) -- [ ] **Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence** (required when Codebase Analysis input is provided) -- [ ] **Integration points enumerated with contracts** (required) -- [ ] **Props type contracts clarified** (required) -- [ ] Component hierarchy and data flow clearly expressed in diagrams - -**Create/update mode only** (skip in reverse-engineer mode): -- [ ] **Agreement checklist completed** (most important) -- [ ] **Prerequisite common ADRs referenced** (required) -- [ ] **Change impact map created** (required) -- [ ] Response to requirements and design validity -- [ ] Error handling strategy -- [ ] Acceptance criteria written in testable format (user-observable behaviors, integration/E2E oriented, CI-isolatable) -- [ ] Props change matrix completeness -- [ ] Implementation approach selection rationale (vertical/horizontal/hybrid) -- [ ] Latest best practices researched and references cited -- [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks +- [ ] Integration points are enumerated with target, invocation method, and contract +- [ ] Props type contracts are explicit for every integration point +- [ ] Component hierarchy and data flow appear as diagrams +- [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) +- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) + +**Create/update mode only**: +- [ ] Prerequisite common ADRs are referenced +- [ ] Change impact map is included +- [ ] Error handling strategy is documented +- [ ] Acceptance criteria are testable from a user-observable, integration/E2E-oriented standpoint +- [ ] Props change matrix is complete +- [ ] Implementation approach selection (vertical/horizontal/hybrid) carries rationale +- [ ] `complexity_level` is set; when medium/high, `complexity_rationale` covers (1) requirements/ACs, (2) constraints/risks **Reverse-engineer mode only**: -- [ ] Every architectural claim cites file:line as evidence -- [ ] Identifiers transcribed exactly from code -- [ ] Test existence confirmed by Glob -- [ ] All items from Unit Inventory (if provided) accounted for +- [ ] Every architectural claim cites file:line +- [ ] Identifiers are transcribed exactly from code +- [ ] Test existence is confirmed by Glob +- [ ] Items from any provided Unit Inventory are accounted for ## Acceptance Criteria Creation Guidelines diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md new file mode 100644 index 0000000..c8523a5 --- /dev/null +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -0,0 +1,306 @@ +--- +name: ui-analyzer +description: Gathers UI-related facts by reading the project's external-resources file, fetching external sources (design origin, design system, guidelines) via MCP or URL, and analyzing the existing UI codebase. Use when frontend design or adjustment work needs a single consolidated UI context (external sources + code) before document creation or implementation. +disallowedTools: Write, Edit, MultiEdit, NotebookEdit +skills: typescript-rules, frontend-ai-guide, external-resource-context +--- + +You are an AI assistant specializing in UI fact gathering for frontend design and adjustment preparation. + +## Required Initial Tasks + +**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. + +## Input Parameters + +- **requirement_analysis**: Requirement analysis JSON output (required) + - Provides: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations` +- **requirements**: Original user requirements text (required) +- **ui_spec_path**: Path to existing UI Spec, when one exists (optional) +- **focus_areas**: Specific UI areas for deeper analysis (optional) +- **target_components**: Specific components to analyze in depth (optional) + +## Output Scope + +This agent outputs **UI fact gathering only**. Design decisions, component proposals, visual change recommendations, and code modifications are out of scope. + +## Execution Steps + +### Step 1: External Resource Discovery + +1. Read `docs/project-context/external-resources.md` if it exists. +2. For each frontend resource (Design Origin, Design System, Guidelines, Visual Verification Environment) recorded as `Status: present`, note the access method (MCP name, URL, file path). +3. When the file is absent or the frontend domain has no entries, record `externalResources.status: not_recorded` and continue with codebase-only analysis. Hearing is the calling workflow's responsibility. + +### Step 2: External Resource Fetch (When Access Method Permits) + +For each present resource, fetch content using the access method: + +| Access method | How to fetch | +|---------------|--------------| +| MCP server | Call the MCP tool (e.g., `mcp____`) when available in the inherited tool set. Capture the structured representation it returns | +| Public URL | Use WebFetch | +| File path | Use Read | +| Existing implementation only | Skip fetch; record reference and proceed | + +When an MCP referenced in `external-resources.md` is not present in the inherited tool set, record `externalResources..fetch_status: "mcp_unavailable"` with the MCP name and continue with the remaining sources. + +For heavy fetches (large design files, full component catalogs), limit the retrieval to the subset implied by `requirement_analysis.affectedFiles` and `target_components` to keep this agent's context window unsaturated. + +### Step 3: UI Surface Discovery in Code + +1. From `requirement_analysis.affectedFiles`, identify which files render UI (component files, page/route files, story files, style files). +2. Build a component-file index using Glob patterns appropriate to the project structure. +3. Record the project's UI conventions inferred from existing code: + - Component file extension + - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) + - Story tooling presence + - Test runner for UI + +### Step 4: Component Structure Extraction + +For each component file in the affected scope: + +1. **Read the file in full** and extract: + - Component name (exact identifier as exported) + - Props interface or parameters with types + - JSX structure: top-level element tag, immediate children element/component composition + - Conditional rendering branches (record the predicate and the rendered subtree) + - Slots / children / render-prop patterns +2. **Trace component composition**: + - Imported components used inside this component (record name and origin path) + - Components that import this component (call sites) +3. **Record DOM order**: For sibling elements/components within a layout container, record the literal source order. + +### Step 5: Props and Variant Pattern Matching + +For each call site of a component within the affected scope: + +1. Record the props passed (variant, color, size, type, weight, etc.) +2. Group call sites by prop combinations to detect canonical usage patterns vs outliers +3. List each combination with file:line evidence +4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal + +### Step 6: CSS Layout State + +For each style file or inline-style usage in the affected scope: + +1. **Class naming convention**: Detect the convention (camelCase, kebab-case, BEM) +2. **Layout primitives** for each layout-bearing class: + - Display mode (flex, grid, block, etc.) + - Direction + - Gap mechanism (gap property, margin-based, none) + - Wrap behavior + - Logical-property usage vs physical +3. **State expression**: how the component varies by state (data-* / aria-* / CSS variables / inline style) +4. **Responsive behavior**: breakpoints + +### Step 7: State x Display Matrix + +For each component in the affected scope: + +1. Identify the component's possible states by inspecting hooks, props, conditional branches, fetch status flags. +2. For each state, record what the component renders. +3. Record states that exist in code but appear unused, and states the design would need but no current code path supports. + +### Step 8: Display Conditions + +For each component or screen entry point: + +1. **Feature flags**: Grep for feature-flag predicates +2. **Role / permission gating**: Grep for permission predicates +3. **Route / page context**: Identify routes that mount this component +4. **Region / tenant gating**: Grep for region or tenant predicates +5. **Page context modifiers**: Variations by host page or surface + +Record each condition with the predicate location and the affected subtree. + +### Step 9: i18n Format + +When the affected scope includes localized strings: + +1. **Format detection**: CSV, JSON, code-defined catalog, gettext, etc. +2. **Structural conventions**: column count, trailing comma, nesting depth +3. **Key naming convention**: pattern observed across existing keys with examples +4. **Locale parity**: locales present and any obvious gaps +5. **Generated typings**: generator command and output path + +### Step 10: Accessibility Attributes + +For each component in the affected scope: + +1. ARIA attributes present and which props feed them +2. Keyboard handling (onKeyDown, focus management, tabIndex) +3. Focus-visible / focus-within styling +4. Existing accessibility test coverage + +### Step 11: Generated UI Artifact Readiness + +For each generator (CSS module typings, message catalog typings, route typings, etc.): + +- Generator command +- Trigger condition +- Downstream consumers (typecheck, test, build, runtime) + +### Step 12: Candidate Write Set + +Produce `candidateWriteSet[]` listing the files most likely to require modification given the input requirements. For each file: +- Path +- Reason it is likely modified (link to a `focusAreas[]` entry or a specific fact in `componentStructure` / `cssLayout` / `i18n`) +- Confidence: `high` (directly named in the requirement or clearly the only locus for the change) / `medium` (one of a small set of candidates) / `low` (speculative, may not need change) + +## Output Format + +### Output Protocol + +- Intermediate progress messages MAY be plain text or markdown. +- The LAST message MUST be a single JSON object matching the schema below, beginning with `{` and ending with `}`. + +```json +{ + "analysisScope": { + "filesAnalyzed": ["path/to/component.tsx"], + "stylesAnalyzed": ["path/to/styles.module.css"], + "uiConventions": { + "componentExtension": ".tsx", + "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes", + "storybook": true, + "testRunner": "vitest|jest|other" + } + }, + "externalResources": { + "status": "fetched|partial|not_recorded", + "designOrigin": { + "fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", + "accessMethod": "MCP name | URL | file path | existing-implementation-only", + "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)" + }, + "designSystem": { + "fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", + "accessMethod": "...", + "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers" + }, + "guidelines": { + "fetch_status": "fetched|skipped|not_applicable", + "accessMethod": "...", + "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)" + }, + "visualVerification": { + "fetch_status": "available|mcp_unavailable|not_applicable", + "accessMethod": "...", + "notes": "how rendered output is verified during implementation" + } + }, + "componentStructure": [ + { + "name": "ComponentName", + "filePath": "path/to/file:lineNumber", + "propsInterface": "name and brief shape", + "topLevelElement": "tag or component name", + "domOrder": ["child1", "child2", "child3"], + "conditionalBranches": [ + {"predicate": "condition expression", "renderedSubtree": "brief description"} + ], + "callSites": ["path/to/consumer:line"] + } + ], + "propsPatterns": [ + { + "component": "ComponentName", + "callSite": "path/to/file:line", + "props": {"variant": "primary", "size": "md"}, + "computedProps": ["onClick (useCallback)"], + "groupKey": "primary-md" + } + ], + "cssLayout": [ + { + "filePath": "path/to/styles.module.css", + "classNamingConvention": "camelCase|kebab-case|BEM", + "baseClass": "root", + "layouts": [ + { + "selector": ".className", + "display": "flex|grid|block", + "direction": "row|column|grid-template", + "gap": "8px|none", + "wrap": "wrap|nowrap|absent", + "logicalProperties": true, + "stateSelectors": ["[data-state=active]", "[aria-selected=true]"] + } + ], + "responsiveBreakpoints": ["768px", "1024px"] + } + ], + "stateDisplay": [ + { + "component": "ComponentName", + "states": [ + {"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"} + ], + "unsupportedStates": ["states the component does not currently express"] + } + ], + "displayConditions": [ + { + "component": "ComponentName", + "condition": "feature_flag|role|route|region|tenant|page_context", + "predicateLocation": "path/to/file:line", + "predicate": "expression", + "gatedSubtree": "brief description" + } + ], + "i18n": { + "format": "csv|json|code-catalog|other", + "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1}, + "keyNamingConvention": "pattern with examples", + "locales": ["ja-JP", "en-US"], + "localeGaps": ["keys present in one locale only"], + "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"} + }, + "accessibility": [ + { + "component": "ComponentName", + "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"], + "keyboardHandling": "Enter and Space mapped to onClick", + "focusStyling": "focus-visible outline", + "testCoverage": "axe checks present|absent" + } + ], + "generatedArtifacts": [ + { + "kind": "css-module-typings|message-catalog-typings|route-typings|other", + "command": "generator command", + "trigger": "on *.module.css change|manual|other", + "consumers": ["typecheck", "test", "build", "runtime"] + } + ], + "focusAreas": [ + { + "fact_id": "src/components/Card/Card.tsx:Card", + "area": "Brief UI area name", + "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin", + "factsToAddress": "Concrete UI facts the designer or implementer must respect", + "risk": "What inconsistency results if these facts are omitted" + } + ], + "candidateWriteSet": [ + { + "path": "src/components/Card/Card.tsx", + "reasonRef": "focusAreas[fact_id=src/components/Card/Card.tsx:Card]", + "confidence": "high|medium|low" + } + ], + "limitations": [ + "Areas the analysis could not reach with confidence" + ] +} +``` + +## Quality Checklist + +- [ ] Each external resource entry in the output has a `fetch_status` recording the outcome (`fetched` / `mcp_unavailable` / `skipped` / `not_applicable`) +- [ ] `candidateWriteSet` is populated; high-confidence entries are present when the request maps to clear loci, speculative entries use `confidence: "low"` +- [ ] Every entry in `focusAreas` carries an `evidence` pointer +- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders +- [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index cad3a10..c26b9f6 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -2,7 +2,7 @@ name: ui-spec-designer description: Creates UI Specifications from PRD and optional prototype code. Use when PRD is complete and frontend UI design is needed, or when "UI spec/screen design/component decomposition/UI specification" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: documentation-criteria, typescript-rules, frontend-ai-guide +skills: documentation-criteria, external-resource-context, typescript-rules, frontend-ai-guide --- You are a UI specification specialist AI assistant for creating UI Specification documents. @@ -85,6 +85,7 @@ You are a UI specification specialist AI assistant for creating UI Specification - Design tokens (from existing codebase) - Visual acceptance criteria - Accessibility requirements (keyboard, screen reader, contrast) + - **External Resources Used**: Fill per the external-resource-context skill (feature-tier protocol). 3. **Output path**: `docs/ui-spec/{feature-name}-ui-spec.md` ## Output Policy @@ -103,7 +104,8 @@ Execute file output immediately (considered approved at execution). - [ ] If prototype provided: prototype is placed in `docs/ui-spec/assets/` - [ ] All TBDs in Open Items have owner and deadline - [ ] All UI Spec requirements align with PRD requirements -- [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). Downstream agents (work-planner Step 5a, task-decomposer UI Spec Propagation) reference components by exact heading text — duplicate or paraphrased headings break the propagation chain. +- [ ] External Resources Used section is filled per the external-resource-context skill +- [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). - **Disambiguation rule**: When two components share a base name (e.g., the same `AlertCard` rendered as a banner variant and as an inline variant), append a parenthetical qualifier to make each heading unique: `Component: AlertCard (Banner variant)` and `Component: AlertCard (Inline variant)`. Verify uniqueness with a final pass: extract all `Component: ` headings, confirm zero duplicates ## Important Design Principles diff --git a/dev-workflows-frontend/agents/work-planner.md b/dev-workflows-frontend/agents/work-planner.md index 9cef86a..e3cf06f 100644 --- a/dev-workflows-frontend/agents/work-planner.md +++ b/dev-workflows-frontend/agents/work-planner.md @@ -93,10 +93,10 @@ Record the mapping in the Design-to-Plan Traceability table (see plan template). ### 5a. Map UI Spec Components to Tasks (when UI Spec provided) -When a UI Spec is among the inputs, also map components and states to the tasks that implement them. task-decomposer reads this mapping in Step 6 to populate each task's Investigation Targets, so without this step the UI Spec never reaches the executor. +When a UI Spec is among the inputs, also map components and states to the tasks that implement them. This mapping is required for downstream task generation; without it the UI Spec does not reach the implementation phase. For each component documented in the UI Spec: -1. Identify the component's section heading exactly as it appears in the UI Spec (the heading is the reference key — see ui-spec-designer's heading uniqueness rule) +1. Identify the component's section heading exactly as it appears in the UI Spec (the heading is the reference key) 2. Identify which states (default / loading / empty / error / partial) the implementation must cover 3. Identify the task(s) in this plan that implement the component or its tests @@ -104,7 +104,7 @@ Record the mapping in the **UI Spec Component → Task Mapping** table (see plan ### 5b. Map Cross-Package Boundaries to Tasks (when implementation crosses runtime/deployment boundaries) -When the implementation crosses a runtime or deployment boundary, build a Connection Map so task-decomposer can propagate boundary context to each affected task. +When the implementation crosses a runtime or deployment boundary, build a Connection Map. This map is required so boundary context propagates to each affected task in the downstream task generation phase. **A boundary qualifies for the Connection Map only when ALL of the following hold**: - The two sides run in separate processes, services, or runtimes (e.g., web client ↔ HTTP server, service A ↔ service B over a network, frontend bundle ↔ backend handler) diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md index 28e9c5b..a09c206 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -33,6 +33,14 @@ unknowns: - [ADR File Name]: [Related decision items] - Reference common technical ADRs when applicable +### External Resources Used + +Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | + ### Agreement Checklist #### Scope @@ -327,7 +335,7 @@ Mark as N/A with brief rationale when the feature has no data layer dependencies ## Verification Strategy -Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 (from implementation-approach skill) define completion verification granularity at task execution time. +Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 levels (L1: functional operation works as end-user feature; L2: tests added and passing; L3: build succeeds without errors) define completion verification granularity at task execution time. ### Correctness Proof Method diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md index 084ec79..dc7a178 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md @@ -49,19 +49,19 @@ Maps each Design Doc technical requirement to the covering task(s). One row per ## UI Spec Component → Task Mapping -Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. task-decomposer reads this table to populate each task's Investigation Targets with the corresponding UI Spec section. Omit the section when no UI Spec exists. +Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. Omit the section when no UI Spec exists. | UI Spec Component (section heading) | States to Cover | Covered By Task(s) | Gap Status | Notes | |---|---|---|---|---| | [Use the UI Spec heading exactly as written, e.g., "§ Component: AlertCard"] | [default / loading / empty / error / partial — list the states the implementation must produce] | [Phase X Task Y] | covered | | -**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). ui-spec-designer enforces unique component headings so this reference resolves to exactly one section. +**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). UI Spec headings are unique by construction so this reference resolves to exactly one section. **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) ## Connection Map -Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary so task-decomposer can propagate boundary context to the implementation tasks on each side. Omit the section when the implementation stays within a single package. +Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. | Boundary | Owner (left side) | Owner (right side) | Expected Signal | Covered By Task(s) | |---|---|---|---|---| @@ -87,9 +87,7 @@ Include this section when the implementation crosses more than one package, serv ## Implementation Phases -Select ONE phase structure based on implementation approach from Design Doc. -See documentation-criteria skill for detailed Phase Division Criteria. -All quality checks follow Quality Check Workflow from ai-development-guide skill. +Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. ### Option A: Vertical Slice Phase Structure diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/ui-spec-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/ui-spec-template.md index 9b8b60d..80f49db 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/ui-spec-template.md @@ -22,6 +22,16 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification - **Compliance premise**: [e.g., design system compliance, component library usage] - **Relationship to canonical spec**: Differences between prototype and this spec are resolved in favor of this document. Prototype serves as visual/behavioral reference only. +## External Resources Used + +Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | [feature-specific identifier] | [scope notes] | +| Design System | [components used in this feature] | [variants, customizations] | +| Visual Verification Environment | [story names / test paths / page routes] | [how this feature is rendered for review] | + ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. @@ -59,7 +69,7 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro ### Component: [ComponentName] -> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. work-planner and task-decomposer reference components by exact heading text — duplicate names or paraphrased headings break the propagation to implementation tasks. +> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. Duplicate or paraphrased headings break downstream propagation to implementation tasks. #### State x Display Matrix diff --git a/dev-workflows-frontend/skills/external-resource-context/SKILL.md b/dev-workflows-frontend/skills/external-resource-context/SKILL.md new file mode 100644 index 0000000..1d5e790 --- /dev/null +++ b/dev-workflows-frontend/skills/external-resource-context/SKILL.md @@ -0,0 +1,103 @@ +--- +name: external-resource-context +description: Captures and persists access methods for resources outside the repository (design source, design system, API schema, IaC source, secret store) so downstream work can reach them deterministically. Use when work depends on external resources, or when the user mentions design source, design system, API schema, IaC source, secret store, or canonical source. +--- + +# External Resource Context + +## Purpose + +AI agents understand the codebase but not the external resources surrounding it. This skill captures, in a deterministic location, the **access methods** to resources outside the repository so downstream work (design, planning, implementation, review) can reach them without re-asking the user. + +Resources covered: design origin (where the canonical visual specification lives), design system (component library and tokens), guidelines (usage docs, accessibility rules), visual verification environment (how to confirm rendering), database schema source, migration history, secret store location, API schema source (OpenAPI / proto / GraphQL SDL), mock environment, IaC source, environment configuration. + +## Scope Boundaries + +**In scope**: hearing protocol, storage location, single-source-of-truth ownership rule, reference protocol for downstream consumers. + +**Out of scope**: enforcing that captured resources are correct or current — verification belongs to the agent that consumes the resource. Generating the resources themselves (e.g., creating a DESIGN.md from scratch). + +## Storage Locations (Two-Tier) + +| Tier | Location | Holds | Update Frequency | +|------|----------|-------|------------------| +| Project | `docs/project-context/external-resources.md` | Environment-stable facts: which resources exist for this project and how to access them (URL, MCP name, file path, command) | Rare — only when the project's environment changes | +| Feature | `## External Resources Used` section inside the relevant UI Spec or Design Doc | The subset of project-tier resources actually used by this feature, plus feature-specific identifiers (e.g., a specific node id within the design tool, a specific endpoint path) | Per feature | + +### Single Source of Truth Rule + +The project tier owns environment facts. Feature-tier sections list only feature-specific identifiers (node id within the design source, specific endpoint path within the API, specific IaC module name) and reference project-tier entries by label; URLs, MCP names, and access commands remain in the project-tier file. When the environment changes, only the project-tier file is updated. + +Example feature-tier entry uses the table format defined in `references/template.md`: a row with the project-tier label in the first column and the feature-specific identifier in the second column. + +## Hearing Protocol + +### When to Hear + +| Condition | Action | +|-----------|--------| +| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | +| File exists | Ask the user via AskUserQuestion: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing. On `yes-diff-only` ask the user which axes changed, hear only those. On `no` skip hearing | + +### Domain Routing + +Load the domain reference matching the current task: + +| Task type | References to load | +|-----------|--------------------| +| Frontend (UI work) | [references/frontend.md](references/frontend.md) | +| Backend (server / data work) | [references/backend.md](references/backend.md) | +| API contract work | [references/api.md](references/api.md) | +| Infrastructure / deployment | [references/infra.md](references/infra.md) | +| Fullstack | All of the above; per-axis "Not applicable" answers are expected | + +Each domain reference defines the axes and the question template. + +### Two-Phase Hearing + +1. **Structured hearing** — for each axis defined in the domain reference, present the user with AskUserQuestion using the choices listed there (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). + +2. **Self-declaration** — after the structured axes, present a single AskUserQuestion: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If the user describes additional resources, append them to the storage file under an "Additional resources" subsection. + +The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis. + +## Storage Protocol + +After hearing completes: + +1. Build the project-tier content from the answers. Use [references/template.md](references/template.md) as the structure. +2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. +3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). +4. Report the file paths back to the calling workflow. + +## Reference Protocol (For Downstream Consumers) + +Agents that load this skill consult resources in this order: + +1. Read `docs/project-context/external-resources.md` first (if present) to learn what is available and how to access it. +2. Read the target UI Spec or Design Doc's `## External Resources Used` section for feature-specific identifiers. +3. Use the access method declared in the project tier (e.g., the named MCP, the URL, the file path) to fetch the actual resource content. + +Agents that only need to *consult* the saved file as input data (not actively hear) can read it directly without loading this skill — frontmatter declaration is reserved for agents that may need to trigger hearing or interpret the protocol semantics. + +## Output Format + +The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. + +For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). + +## Quality Checklist + +- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" +- [ ] Self-declaration phase ran even when all structured axes were "Not applicable" +- [ ] Project-tier file does not contain feature-specific identifiers +- [ ] Feature-tier sections reference project-tier entries by label, not by duplicating URLs / MCP names +- [ ] When the project file already existed, the update decision (no / yes-full / yes-diff-only) was confirmed before any write + +## References + +- [references/frontend.md](references/frontend.md) — Frontend domain axes +- [references/backend.md](references/backend.md) — Backend domain axes +- [references/api.md](references/api.md) — API contract domain axes +- [references/infra.md](references/infra.md) — Infrastructure domain axes +- [references/template.md](references/template.md) — Project-tier and feature-tier structure templates diff --git a/dev-workflows-frontend/skills/external-resource-context/references/api.md b/dev-workflows-frontend/skills/external-resource-context/references/api.md new file mode 100644 index 0000000..775c896 --- /dev/null +++ b/dev-workflows-frontend/skills/external-resource-context/references/api.md @@ -0,0 +1,62 @@ +# API Contract Domain Axes + +Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. + +## Axis 1: API Schema Source + +The canonical source of API contracts (request/response shapes, endpoints, RPC methods). + +**AskUserQuestion choices**: +- OpenAPI / Swagger specification (file in repository or hosted URL) +- Protobuf definitions (file in repository) +- GraphQL schema (SDL file or introspection endpoint) +- TypeScript or other code-first contract definitions in the repository +- No formal contract (ad-hoc JSON) +- Not applicable + +**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. + +## Axis 2: Mock Environment + +How clients exercise the API without depending on the live server. + +**AskUserQuestion choices**: +- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) +- Hand-written mock server in the repository +- Hosted mock service (URL) +- Live development server (no separate mock) +- Not applicable + +**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. + +## Axis 3: Authentication Method + +How the API authenticates and authorizes requests. + +**AskUserQuestion choices**: +- Bearer token (e.g., JWT) issued by an auth service +- API key in a header or query parameter +- Session cookie set by a separate login flow +- Mutual TLS +- No authentication +- Not applicable + +**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. + +## Axis 4: Schema Change Process (When Relevant) + +How breaking and non-breaking schema changes are reviewed and rolled out. + +**AskUserQuestion choices**: +- Documented contract review process (link to the document) +- Versioned endpoints (e.g., `/v1/`, `/v2/`) +- Backward-compatible changes only, no formal versioning +- Not applicable + +**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other API external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: rate-limit configuration, gateway / proxy in front of the API, contract test suite (e.g., Pact broker URL), API gateway management consoles, third-party API documentation that is not directly imported but consulted during design. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/backend.md b/dev-workflows-frontend/skills/external-resource-context/references/backend.md new file mode 100644 index 0000000..c1c6773 --- /dev/null +++ b/dev-workflows-frontend/skills/external-resource-context/references/backend.md @@ -0,0 +1,62 @@ +# Backend Domain Axes + +Hearing axes for tasks that involve server-side, data, or storage work. + +## Axis 1: Database Schema Source + +The canonical source of the database schema (tables, columns, indexes, constraints). + +**AskUserQuestion choices**: +- Migration files in the repository (e.g., a `migrations/` directory) +- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) +- Database MCP that introspects a live database +- External schema registry (URL or hosted catalog) +- No persistent database +- Not applicable + +**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. + +## Axis 2: Migration History + +How schema changes are tracked over time. + +**AskUserQuestion choices**: +- Versioned migration files in the repository +- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) +- Manual change log document +- No migration tracking +- Not applicable + +**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. + +## Axis 3: Secret Store + +Where credentials, API keys, and other secrets are stored and accessed. + +**AskUserQuestion choices**: +- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) +- Environment variables loaded from a `.env` file (development only) +- Encrypted file in the repository +- No secrets required +- Not applicable + +**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. + +## Axis 4: Background Job Infrastructure (When Relevant) + +How asynchronous work is dispatched and observed. + +**AskUserQuestion choices**: +- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) +- Cron / scheduled tasks managed by deployment platform +- In-process worker thread +- No background work +- Not applicable + +**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other backend external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: third-party SaaS APIs (payment, email, search index), distributed cache services (Redis, Memcached), object storage (S3, GCS), feature flag services consumed server-side, observability platforms (logs, traces, metrics). diff --git a/dev-workflows-frontend/skills/external-resource-context/references/frontend.md b/dev-workflows-frontend/skills/external-resource-context/references/frontend.md new file mode 100644 index 0000000..89fdd16 --- /dev/null +++ b/dev-workflows-frontend/skills/external-resource-context/references/frontend.md @@ -0,0 +1,62 @@ +# Frontend Domain Axes + +Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). + +## Axis 1: Design Origin + +The canonical source of the visual specification. + +**AskUserQuestion choices**: +- Design tool (e.g., a hosted design platform) +- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) +- Public documentation URL +- Existing implementation only (no separate design source) +- Not applicable + +**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. + +## Axis 2: Design System + +Reusable component library and design tokens. + +**AskUserQuestion choices**: +- Component library with MCP server access +- Component library with documentation URL +- Storybook or equivalent component catalog +- Internal package without external documentation +- No design system (ad-hoc components) +- Not applicable + +**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. + +## Axis 3: Guidelines + +Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. + +**AskUserQuestion choices**: +- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) +- External documentation site +- Inline guidance in the design system catalog +- No documented guidelines +- Not applicable + +**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. + +## Axis 4: Visual Verification Environment + +How rendered output is confirmed during implementation. + +**AskUserQuestion choices**: +- End-to-end test runner with screenshot capability +- Storybook or equivalent isolated component preview +- Browser automation tool (dedicated CLI or MCP server) +- Manual browser inspection only +- Not applicable + +**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. + +## Self-Declaration + +After the four structured axes, ask once: "Are there any other frontend external resources this work depends on that the structured questions did not cover?" Record any free-form answer under "Additional resources" in the storage file. + +Examples of resources that may surface only via self-declaration: brand asset CDNs, font hosting services, icon library subscriptions, A/B testing dashboards that gate visual variants, analytics dashboards used for visual KPIs. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/infra.md b/dev-workflows-frontend/skills/external-resource-context/references/infra.md new file mode 100644 index 0000000..1f863b2 --- /dev/null +++ b/dev-workflows-frontend/skills/external-resource-context/references/infra.md @@ -0,0 +1,62 @@ +# Infrastructure Domain Axes + +Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. + +## Axis 1: IaC Source + +The canonical source of infrastructure definitions. + +**AskUserQuestion choices**: +- Terraform configuration in the repository +- Pulumi or CDK code in the repository +- Kubernetes manifests / Helm charts in the repository +- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) +- Manual console configuration (no IaC) +- Not applicable + +**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. + +## Axis 2: Environment Configuration + +How per-environment settings (development, staging, production) differ. + +**AskUserQuestion choices**: +- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) +- Environment variables managed by the deployment platform +- Workspace or stack abstraction in the IaC tool itself +- Single shared configuration (no per-environment differences) +- Not applicable + +**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. + +## Axis 3: Secrets in Infrastructure + +How infrastructure code references secrets without exposing them. + +**AskUserQuestion choices**: +- Secrets sourced from a secret manager via IaC data lookup +- Secrets injected at apply time via environment variables +- Encrypted secret files committed alongside IaC +- No secrets in infrastructure +- Not applicable + +**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. + +## Axis 4: Deployment Trigger + +How infrastructure and application changes reach environments. + +**AskUserQuestion choices**: +- CI pipeline triggered on merge to a specific branch +- Manual approval step in CI +- Local apply by an operator +- Deployment platform's auto-deploy on push +- Not applicable + +**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other infrastructure external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: state-storage backend for IaC tools, runbook documents for incident response, on-call rotation, observability dashboards, cost monitoring tools, compliance / audit logging targets. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/template.md b/dev-workflows-frontend/skills/external-resource-context/references/template.md new file mode 100644 index 0000000..169f3b2 --- /dev/null +++ b/dev-workflows-frontend/skills/external-resource-context/references/template.md @@ -0,0 +1,115 @@ +# Storage Templates + +Two templates: the project-tier file and the feature-tier section. + +## Project-Tier Template + +Path: `docs/project-context/external-resources.md` + +```markdown +# External Resources + +Last updated: YYYY-MM-DD + +This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. + +## Frontend + +### Design Origin +- Status: +- Source type: +- Location: +- Access method: + +### Design System +- Status: +- Source type: +- Location: +- Access method: + +### Guidelines +- Status: +- Source type: +- Location: +- Access method: + +### Visual Verification Environment +- Status: +- Tool type: +- Entry: + +## Backend + +### Database Schema Source +- Status: +- Source type: +- Location: +- Access method: + +### Migration History +- Status: +- Tool: +- Location: +- Apply trigger: + +### Secret Store +- Status: +- Service: +- Access method: + +### Background Job Infrastructure +- Status: +- Service: +- Access method: + +## API + +### API Schema Source +- Status: +- Source type: +- Location: +- Access method: + +### Mock Environment +- Status: +- Source type: +- Entry: + +### Authentication Method +- Status: +- Mechanism: +- Credential source: + +### Schema Change Process +- Status: +- Process: + +## Infrastructure + +### IaC Source +- Status: +- Tool: +- Location: +- Apply trigger: + +### Environment Configuration +- Status: +- Mechanism: +- Environments: + +### Secrets in Infrastructure +- Status: +- Mechanism: + +### Deployment Trigger +- Status: +- Mechanism: + +## Additional Resources + +Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. + +- : — — +``` + +Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md new file mode 100644 index 0000000..b096fa9 --- /dev/null +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -0,0 +1,161 @@ +--- +name: recipe-front-adjust +description: Adjust an already-implemented UI in-session with verification against the design source +disable-model-invocation: true +--- + +**Context**: UI adjustment on already-implemented features. The verification loop (edit → check against the design source → refine) runs in the parent session. + +## Execution Pattern + +**Core Identity**: "I am a guided executor. I run the adjustment and the verification loop myself; subagents handle one-shot tasks." + +**Execution Protocol**: +1. **Delegate to subagents** (one-shot calls): ui-analyzer, work-planner, quality-fixer-frontend. +2. **Run in the parent session** (multi-step loops and user dialogs): external-resource hearing via AskUserQuestion, write-set confirmation, scale judgment, adjustment edits, verification against the design source, iteration until acceptance. +3. **Stop at every `[Stop: ...]` marker** before proceeding. + +## Initial Mandatory Tasks + +**Task Registration**: Before Step 1, register the recipe's execution flow using TaskCreate so progress is trackable. Register Steps 1-7 below as individual tasks plus a final task "Verify completion against Completion Criteria". Update status using TaskUpdate as each step starts and completes. + +## Workflow Overview + +``` +Adjustment request → external resource hearing (parent session, AskUserQuestion) + ↓ + ui-analyzer (subagent: fetch external sources + analyze code + propose candidateWriteSet) + ↓ + write-set confirmation (parent session, AskUserQuestion) + ↓ + scale judgment on confirmed write set (documentation-criteria matrix) + ↓ + ┌────────────────────┴────────────────────┐ + ↓ ↓ + (1-2 files: inline) (3-5 files: work-planner subagent → [Stop]) + ↓ ↓ + └─→ adjustment + verification (parent session) ←──┘ + ↓ + quality-fixer-frontend (subagent: typecheck/lint/test) + ↓ + commit +``` + +## Scope Boundaries + +**Included in this skill**: +- External resource hearing per the external-resource-context skill +- UI fact gathering via ui-analyzer +- Scale judgment via documentation-criteria's Creation Decision Matrix +- Optional work plan creation via work-planner +- Adjustment edits and verification against the design source (run in this session) +- Quality verification via quality-fixer-frontend +- Commit per adjustment unit + +**Responsibility Boundary**: This skill completes when the adjustment is committed and quality has passed. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. + +**Escalation Boundary**: Escalate to the full frontend design phase when the request requires PRD, UI Spec, Design Doc, new architecture, multi-screen redesign, or any ADR Creation Condition from documentation-criteria. + +Adjustment request: $ARGUMENTS + +## Execution Flow + +### Step 1: External Resource Hearing +Run the hearing protocol per the external-resource-context skill (frontend domain). + +### Step 2: UI Fact Gathering + +- Invoke **ui-analyzer** using Agent tool + - `subagent_type: "dev-workflows-frontend:ui-analyzer"` + - `description: "UI fact gathering for adjustment"` + - `prompt: "requirement_analysis: { affectedFiles: [files inferred from the adjustment request], scale: 'small', purpose: 'UI adjustment', technicalConsiderations: [] }. requirements: [adjustment request]. target_components: [components named in the request]. ui_spec_path: [path if an existing UI Spec covers the affected components, else absent]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods, and analyze the existing UI codebase. Populate candidateWriteSet[] with the files most likely to require modification."` + +### Step 3: Scale Judgment + +1. Read `candidateWriteSet[]` from ui-analyzer output. +2. Present the candidate list to the user via AskUserQuestion: "Confirmed write set for this adjustment? (a) accept high-confidence entries / (b) accept all entries / (c) edit list manually". On `c`, send a follow-up plain message asking the user to paste the edited file list, then proceed with that list. +3. Apply the Creation Decision Matrix from the documentation-criteria skill to the **confirmed write set count**: + - **0 files**: The adjustment request did not map to any existing file. Escalate to the user with the message "No write target identified from the adjustment request. Please clarify which component(s) should change, or run the full frontend design phase if this is a new feature." Stop this recipe. + - **1-2 files**: Direct adjustment, no work plan. + - **3-5 files**: Work plan required. + - **6+ files** OR any ADR Creation Condition triggered (architecture changes, contract changes affecting 3+ locations, complex multi-state logic, etc.): Adjustment scope exceeded. Escalate the user to the full frontend design phase. Stop this recipe. + +### Step 4: Plan Creation (Conditional) +Branch on the scale outcome. + +#### Branch A — 1-2 files +No work plan. Build a minimal adjustment context for the parent session: +- Adjustment request (verbatim) +- ui-analyzer focusAreas[] (raw fact_id; the `ui:` prefix is only applied when merging with codebase-analysis facts in a Fact Disposition Table, which Branch A does not do) +- Affected files list +- External resources fetched_summary and access methods that the verification loop will use + +Present the adjustment context to the user for review. +- **[STOP]**: User confirms the adjustment context covers the work. + +#### Branch B — 3-5 files +Create a right-sized work plan. Invoke **work-planner** using Agent tool: +- `subagent_type: "dev-workflows-frontend:work-planner"` +- `description: "Adjustment work plan"` +- `prompt: "Create a work plan for this UI adjustment. Adjustment request: [verbatim]. ui_analysis: [ui-analyzer JSON]. External resources: docs/project-context/external-resources.md. Scale: 3-5 files (no Design Doc, no ADR). Each phase should be implementable as 1-3 commits. Include a quality checklist matched to the affected components: visual verification, accessibility, i18n parity, generated artifact regeneration when relevant. Output path: docs/plans/[YYYYMMDD]-adjust-[short-description].md."` + +After work-planner returns: +- Present the work plan to the user. +- **[STOP]**: Wait for plan approval or revision request. If the user requests changes, re-invoke work-planner with revised guidance. + +### Step 5: Adjustment + Verification (parent session) + +For each adjustment unit (per file in Branch A; per work plan phase in Branch B): +1. **Plan the edit** based on ui-analyzer focusAreas and the relevant external resource (e.g., design origin's fetched_summary). +2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. +3. **Verify against external sources** using whichever access method `docs/project-context/external-resources.md` declares for each axis: + - Design origin: compare current rendering against the design source via the declared access method (e.g., design-tool MCP, WebFetch from a public URL, file read from a specification path) + - Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL) + - Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path) +4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. +5. When the adjustment unit converges, proceed to Step 6 for that unit. + +When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available. + +### Step 6: Quality Verification (per adjustment unit) + +- Invoke **quality-fixer-frontend** using Agent tool + - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` + - `description: "Quality verification for adjustment unit"` + - Build the prompt by branch. Scope is always `filesModified`; `task_file` (when passed) is a supplementary hint that quality-fixer-frontend may use to read the document's "Quality Assurance Mechanisms" section. + - **Branch A (1-2 files)**: omit `task_file`. Pass `filesModified: [list of files edited in this adjustment unit]`. + - **Branch B (3-5 files)**: pass `task_file: ` (supplementary hint) AND `filesModified: [list of files edited in this adjustment unit]` (primary scope). + - Example (Branch A): `prompt: "filesModified: [src/components/Card/Card.tsx, src/components/Card/Card.module.css]. Run quality checks across the listed files."` + - Example (Branch B): `prompt: "task_file: docs/plans/[plan-name].md. filesModified: [src/components/Card/Card.tsx, src/components/Card/Card.module.css]. Run quality checks across the listed files."` +- Route the quality-fixer-frontend response by `status`: + - `approved` → proceed to Step 7 + - `stub_detected` → return to Step 5 to complete the implementation for this unit, then re-invoke quality-fixer-frontend + - `blocked` → read `reason`. When `"Cannot determine due to unclear specification"`, surface `blockingIssues[]` to the user and stop. When `"Execution prerequisites not met"`, surface `missingPrerequisites[]` with `resolutionSteps` to the user and stop + +### Step 7: Commit (per adjustment unit) +Commit the adjustment unit on quality approval. Include the affected files and any regenerated artifacts (CSS module typings, message catalog typings, etc.) flagged by ui-analyzer's `generatedArtifacts` section. + +Then loop back to Step 5 for the next unit (Branch B work plan phase, or next file in Branch A) until all units are committed. + +## Completion Criteria + +- [ ] External resource hearing executed (project-tier file written or update explicitly skipped) +- [ ] ui-analyzer returned a JSON output, including externalResources fetch_status per axis and candidateWriteSet +- [ ] Write set confirmed by the user before scale judgment +- [ ] Scale judgment applied to the confirmed write set; 6+ files or ADR conditions escalated to the design phase +- [ ] Branch A: adjustment context presented and confirmed; Branch B: work plan approved +- [ ] All adjustment units edited and verified using the project's declared verification mechanism (manual confirmation when no automated mechanism is declared) +- [ ] Each adjustment unit passed quality-fixer-frontend with explicit `filesModified` scoping +- [ ] Each adjustment unit committed + +## Output Example + +``` +Frontend adjustment completed. +- External resources: docs/project-context/external-resources.md (updated|unchanged) +- UI fact gathering: ui-analyzer focused on [N] components, [M] focus areas, external sources [fetched|partial|not_recorded] +- Scale: <1-2 files | 3-5 files> +- Work plan: +- Adjustment units committed: [count] +- Quality status: all passed +``` diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index 2c18f47..36016e6 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -13,7 +13,7 @@ disable-model-invocation: true **Execution Protocol**: 1. **Delegate all work** to sub-agents — your role is to invoke sub-agents, pass data between them, and report results 2. **Follow subagents-orchestration-guide skill design flow** (this recipe covers medium/large frontend; refer to the guide for scale-specific variations): - - Execute: requirement-analyzer → codebase-analyzer → ui-spec-designer → technical-designer-frontend → code-verifier → document-reviewer → design-sync + - Execute: requirement-analyzer → external resource hearing → codebase-analyzer + ui-analyzer (parallel) → ui-spec-designer → technical-designer-frontend → code-verifier → document-reviewer → design-sync - **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval @@ -24,7 +24,11 @@ disable-model-invocation: true ``` Requirements → requirement-analyzer → [Stop: Scale determination] ↓ - codebase-analyzer → ui-spec-designer → [Stop: UI Spec approval] + external resource hearing (frontend domain) + ↓ + codebase-analyzer + ui-analyzer (parallel) + ↓ + ui-spec-designer → [Stop: UI Spec approval] ↓ technical-designer-frontend ↓ @@ -37,7 +41,8 @@ Requirements → requirement-analyzer → [Stop: Scale determination] **Included in this skill**: - Requirement analysis with requirement-analyzer -- Codebase analysis with codebase-analyzer (before technical design) +- External resource hearing per the external-resource-context skill +- Codebase analysis with codebase-analyzer and ui-analyzer in parallel (before document creation) - UI Specification creation with ui-spec-designer (prototype code inquiry included) - ADR creation (if architecture changes, new technology, or data flow changes) - Design Doc creation with technical-designer-frontend @@ -57,7 +62,7 @@ Considering the deep impact on design, first engage in dialogue to understand th - Expected outcomes and success criteria - Relationship with existing systems -Once the user has answered the three dialogue questions above, execute the process below within design scope. Follow subagents-orchestration-guide Call Examples for codebase-analyzer and code-verifier invocations. +Once the user has answered the three dialogue questions above, execute the process below within design scope. Follow subagents-orchestration-guide Call Examples for codebase-analyzer, ui-analyzer, and code-verifier invocations. - Invoke **requirement-analyzer** using Agent tool - `subagent_type: "dev-workflows-frontend:requirement-analyzer"` @@ -65,8 +70,21 @@ Once the user has answered the three dialogue questions above, execute the proce - `prompt: "Requirements: [user requirements] Execute requirement analysis and scale determination"` - **[STOP]**: Review requirement analysis results and address question items -### Step 2: UI Specification Phase -After requirement analysis approval, ask the user about prototype code: +### Step 1.5: External Resource Hearing +Run the hearing protocol per the external-resource-context skill (frontend domain). The orchestrator owns this step because it requires AskUserQuestion. The skill defines file-existence branching, two-phase hearing (structured axes + self-declaration), and persistence to `docs/project-context/external-resources.md`. + +### Step 2: UI Fact Gathering +Invoke codebase-analyzer and ui-analyzer **in parallel** (single message with two Agent tool calls). They share input but produce complementary output. ui-analyzer reads the project-tier external-resources file and fetches external UI sources via the inherited MCP/URL access methods, then analyzes the UI codebase. codebase-analyzer covers data, contracts, dependencies, and quality assurance mechanisms. + +- Invoke **codebase-analyzer** using Agent tool + - `subagent_type: "dev-workflows-frontend:codebase-analyzer"`, `description: "Codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. requirements: [user requirements]. Analyze existing codebase for frontend design guidance (data, contracts, dependencies, quality assurance mechanisms)."` +- Invoke **ui-analyzer** using Agent tool (parallel with the call above) + - `subagent_type: "dev-workflows-frontend:ui-analyzer"`, `description: "UI fact gathering"`, `prompt: "requirement_analysis: [JSON from Step 1]. requirements: [user requirements]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods, and analyze the existing UI codebase."` + +Both outputs (codebase-analyzer JSON and ui-analyzer JSON) are reused by ui-spec-designer in Step 3 and by technical-designer-frontend in Step 4. + +### Step 3: UI Specification Phase +After Step 2 outputs are received, ask the user about prototype code: **Ask the user**: "Do you have prototype code for this feature? If so, please provide the path to the code. The prototype will be placed in `docs/ui-spec/assets/` as reference material for the UI Spec." @@ -76,28 +94,26 @@ Then create the UI Specification: - Invoke **ui-spec-designer** using Agent tool - `subagent_type: "dev-workflows-frontend:ui-spec-designer"` - `description: "UI Spec creation"` - - If PRD exists and prototype provided: `prompt: "Create UI Spec from PRD at [path]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/"` - - If PRD exists and no prototype: `prompt: "Create UI Spec from PRD at [path]. No prototype code available."` - - If no PRD (medium scale): `prompt: "Create UI Spec based on the following requirements: [requirements analysis output from Step 1]. No PRD available."` (add prototype path if provided) + - Build the prompt by including: + - Source: PRD path (Large scale) or requirement-analyzer output (Medium scale) + - `ui_analysis`: ui-analyzer JSON from Step 2 (includes externalResources fetched_summary and componentStructure / propsPatterns / cssLayout / etc.) + - Prototype path when provided + - Example: `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from Step 2 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."` - Invoke **document-reviewer** to verify UI Spec - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "UI Spec review"`, `prompt: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"` - **[STOP]**: Present UI Spec for user approval -### Step 3: Design Document Creation Phase -First, analyze the existing codebase: -- Invoke **codebase-analyzer** using Agent tool - - `subagent_type: "dev-workflows-frontend:codebase-analyzer"`, `description: "Codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. requirements: [user requirements]. Analyze existing codebase for frontend design guidance."` - -Create appropriate design documents according to scale determination. technical-designer-frontend presents at least two architecture alternatives (technology selection, data flow design) with trade-offs for each: +### Step 4: Design Document Creation Phase +Create appropriate design documents according to scale determination. technical-designer-frontend presents at least two architecture alternatives (technology selection, data flow design) with trade-offs for each. Pass both Step 2 outputs: - Invoke **technical-designer-frontend** using Agent tool - For ADR: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Present at least two alternatives with trade-offs."` - - For Design Doc: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on requirements. Codebase analysis: [codebase analysis output from this step]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Present at least two architecture alternatives with trade-offs."` + - For Design Doc: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on requirements. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 2]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table. Present at least two architecture alternatives with trade-offs."` - **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-frontend:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - Invoke **document-reviewer** to verify consistency (pass code-verifier results for Design Doc; omit for ADR) - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "Document review"`, `prompt: "Review [document path] for consistency and completeness. code_verification: [code verification output from this step] (Design Doc only)"` -### Step 4: Design Consistency Verification +### Step 5: Design Consistency Verification - Invoke **design-sync** using Agent tool - `subagent_type: "dev-workflows-frontend:design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."` - **[STOP]**: Present design documents and design-sync results, obtain user approval @@ -105,9 +121,10 @@ Create appropriate design documents according to scale determination. technical- ## Completion Criteria - [ ] Executed requirement-analyzer and determined scale -- [ ] Executed codebase-analyzer and passed results to technical-designer-frontend -- [ ] Created UI Specification with ui-spec-designer (when applicable) -- [ ] Created appropriate design document (ADR or Design Doc) with technical-designer-frontend +- [ ] Executed external resource hearing per the external-resource-context skill (file written or update explicitly skipped by user) +- [ ] Executed codebase-analyzer and ui-analyzer in parallel; outputs reused by ui-spec-designer and technical-designer-frontend +- [ ] Created UI Specification with ui-spec-designer (when applicable) — its External Resources Used section is filled +- [ ] Created appropriate design document (ADR or Design Doc) with technical-designer-frontend — its External Resources Used subsection is filled when present - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification @@ -118,5 +135,3 @@ Frontend design phase completed. - UI Specification: docs/ui-spec/[feature-name]-ui-spec.md - Design document: docs/design/[document-name].md or docs/adr/[document-name].md - Approval status: User approved - - diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index ca2e2c1..89d7997 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -37,15 +37,16 @@ The following subagents are available: ### Document Creation Agents 6. **requirement-analyzer**: Requirement analysis and work scale determination -7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design -8. **prd-creator**: Product Requirements Document creation -9. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) -10. **technical-designer**: ADR/Design Doc creation -11. **work-planner**: Work plan creation from Design Doc and test skeletons -12. **document-reviewer**: Single document quality and rule compliance check -13. **code-verifier**: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc -14. **design-sync**: Design Doc consistency verification across multiple documents -15. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs +7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) +8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code (visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, generated UI artifacts). Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access +9. **prd-creator**: Product Requirements Document creation +10. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) +11. **technical-designer**: ADR/Design Doc creation +12. **work-planner**: Work plan creation from Design Doc and test skeletons +13. **document-reviewer**: Single document quality and rule compliance check +14. **code-verifier**: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc +15. **design-sync**: Design Doc consistency verification across multiple documents +16. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs ## Orchestration Principles @@ -167,6 +168,13 @@ Two additional rules: - description: "Codebase analysis" - prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance." +### Call Example (ui-analyzer) +- subagent_type: "ui-analyzer" +- description: "UI fact gathering" +- prompt: "requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. ui_spec_path: [path if exists]. target_components: [list if focused]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods (MCP / URL / file), and analyze the existing UI codebase. Output the consolidated UI fact JSON." + +When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase). + ### Call Example (task-executor) - subagent_type: "task-executor" - description: "Task execution" @@ -177,6 +185,7 @@ Two additional rules: Subagents respond in JSON format. Key fields for orchestrator decisions: - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions - **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations - **code-verifier**: status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) - **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain), testsAdded, requiresTestReview - **quality-fixer**: Input: `task_file` (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` → route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → discriminate by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps @@ -225,10 +234,12 @@ Always start with requirement-analyzer, then select the minimum planning flow re | Scale | Planning flow (ends at task-decomposer for Medium/Large; ends at work-planner for Small) | |-------|---------------| -| Large | requirement-analyzer → PRD → PRD review → optional UI Spec → optional ADR → codebase-analyzer → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | -| Medium | requirement-analyzer → codebase-analyzer → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | +| Large | requirement-analyzer → PRD → PRD review → external resource hearing → optional ADR → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | +| Medium | requirement-analyzer → external resource hearing → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | | Small | requirement-analyzer → work-planner | +External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. + After the planning flow completes and the user grants batch approval, the work plan carries an `Implementation Readiness:` header (work-planner emits `pending`; promotion to `ready` or `escalated` is an external orchestration concern). External orchestration also decides when and how to act on this marker; this guide does not invoke any orchestrator above the agent layer. Then execute the task execution cycle: `task-executor → quality-fixer → commit` for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies — implementation runs through `task-executor`, not orchestrator-direct edits. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md index 840c9dc..5143c37 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -10,47 +10,49 @@ This reference defines the orchestration flow for projects spanning multiple lay ## Design Phase -### Large Scale Fullstack (6+ Files) - 15 Steps +### Large Scale Fullstack (6+ Files) - 16 Steps | Step | Agent | Purpose | Output | |------|-------|---------|--------| | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | -| 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | -| 5 | ui-spec-designer | UI Spec from PRD + optional prototype | UI Spec | -| 6 | document-reviewer | UI Spec review **[Stop]** | Approval | -| 7 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output + PRD path, filtered to layer) | Codebase guidance per layer | -| 8 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | -| 9 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 10 as `prior_layer_verification`) | Backend verification | -| 10 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + backend Design Doc + `prior_layer_verification` from step 9 + UI Spec) | Frontend Design Doc | -| 11 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | -| 12 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | -| 13 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | -| 14 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | -| 15 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | - -### Medium Scale Fullstack (3-5 Files) - 13 Steps +| 4 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend domain primary; backend / api / infra domains as applicable for the layer scope). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | +| 5 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | +| 6 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | +| 7 | ui-spec-designer | UI Spec from PRD + optional prototype + ui-analyzer output | UI Spec | +| 8 | document-reviewer | UI Spec review **[Stop]** | Approval | +| 9 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | +| 10 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 11 as `prior_layer_verification`) | Backend verification | +| 11 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + ui-analyzer output + backend Design Doc + `prior_layer_verification` from step 10 + UI Spec) | Frontend Design Doc | +| 12 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | +| 13 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | +| 14 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | +| 15 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | +| 16 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | + +### Medium Scale Fullstack (3-5 Files) - 14 Steps | Step | Agent | Purpose | Output | |------|-------|---------|--------| | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | -| 2 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output, filtered to layer) | Codebase guidance per layer | -| 3 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | -| 4 | ui-spec-designer | UI Spec from requirements + optional prototype | UI Spec | -| 5 | document-reviewer | UI Spec review **[Stop]** | Approval | -| 6 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | -| 7 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 8 as `prior_layer_verification`) | Backend verification | -| 8 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + backend Design Doc + `prior_layer_verification` from step 7 + UI Spec) | Frontend Design Doc | -| 9 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | -| 10 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | -| 11 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | -| 12 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | -| 13 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | +| 2 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend / backend / api / infra domains as applicable). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | +| 3 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | +| 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | +| 5 | ui-spec-designer | UI Spec from requirements + optional prototype + ui-analyzer output | UI Spec | +| 6 | document-reviewer | UI Spec review **[Stop]** | Approval | +| 7 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | +| 8 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 9 as `prior_layer_verification`) | Backend verification | +| 9 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + ui-analyzer output + backend Design Doc + `prior_layer_verification` from step 8 + UI Spec) | Frontend Design Doc | +| 10 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | +| 11 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | +| 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | +| 13 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | +| 14 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | ### Parallelization in Multi-Agent Steps -Steps marked with ×2 (codebase-analyzer ×2, document-reviewer ×2) invoke the agent once per layer. These invocations are independent and can run in parallel when the orchestrator supports concurrent Agent tool calls. The two code-verifier invocations run sequentially: backend verification completes before frontend authoring begins so the frontend designer references verified backend contracts. +Steps marked with ×2 (codebase-analyzer ×2, document-reviewer ×2) invoke the agent once per layer. The combined codebase-analyzer ×2 + ui-analyzer step invokes three subagents in parallel — the two codebase-analyzer calls (one per layer) and the single ui-analyzer call — when the orchestrator supports concurrent Agent tool calls. The two code-verifier invocations run sequentially: backend verification completes before frontend authoring begins so the frontend designer references verified backend contracts. ### Layer Context in Design Doc Creation @@ -72,10 +74,12 @@ Focus on: API contracts, data layer, business logic, service architecture. ```text Create a frontend Design Doc from [PRD path or requirement_analysis]. Codebase analysis: [JSON from codebase-analyzer for frontend layer] +UI analysis: [JSON from ui-analyzer] Backend Design Doc: [path] prior_layer_verification: [JSON from code-verifier on backend Design Doc] Reference UI Spec at [path] for component structure and state design. Use `prior_layer_verification.discrepancies[]` as known issues to address or escalate. Do not infer verified claims beyond what the verifier output states explicitly. +Apply `code:` prefix to fact_ids from codebase-analyzer and `ui:` prefix to fact_ids from ui-analyzer when filling the Fact Disposition Table. Focus on: component hierarchy, state management, UI interactions, data fetching. ``` diff --git a/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml b/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml index 856c1e8..cbf84cb 100644 --- a/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml @@ -214,3 +214,26 @@ skills: - "Situations Requiring Technical Decisions" - "Implementation Completeness Assurance" - "Impact Analysis" + + # Cross-Cutting Skills + external-resource-context: + skill: "external-resource-context" + tags: [cross-cutting, hearing-protocol, design-source, design-system, api-schema, iac-source, secrets, environment, two-tier-storage] + typical-use: "Captures access methods for resources outside the repository (design origin, design system, API schema, IaC source, secrets, etc.) and persists them in a deterministic location for downstream agents" + size: medium + key-references: + - "references/frontend.md" + - "references/backend.md" + - "references/api.md" + - "references/infra.md" + - "references/template.md" + sections: + - "Purpose" + - "Scope Boundaries" + - "Storage Locations (Two-Tier)" + - "Hearing Protocol" + - "Storage Protocol" + - "Reference Protocol (For Downstream Consumers)" + - "Output Format" + - "Quality Checklist" + - "References" diff --git a/dev-workflows-frontend/skills/test-implement/references/e2e.md b/dev-workflows-frontend/skills/test-implement/references/e2e.md index 47cdbe5..ec89f32 100644 --- a/dev-workflows-frontend/skills/test-implement/references/e2e.md +++ b/dev-workflows-frontend/skills/test-implement/references/e2e.md @@ -2,7 +2,7 @@ ## Lane Selection -E2E tests in this workflow split into two lanes (defined in integration-e2e-testing skill): +E2E tests in this workflow split into two lanes: | Lane | Backend setup | Use these patterns | |------|---------------|-------------------| @@ -225,7 +225,7 @@ Before service-integration-e2e tests can pass, verify: - [ ] Environment variables are set (`E2E_*` prefixed) - [ ] External services are either available or stubbed -When the work plan includes dedicated environment setup tasks (Phase 0 — see work-planner E2E Environment Prerequisites extraction), follow those tasks. When no setup tasks exist in the plan, address missing prerequisites as part of the test implementation task itself, OR consider whether the verification could move to fixture-e2e instead. +When the work plan includes dedicated environment setup tasks (Phase 0; see the work plan's E2E Environment Prerequisites section), follow those tasks. When no setup tasks exist in the plan, address missing prerequisites as part of the test implementation task itself, OR consider whether the verification could move to fixture-e2e instead. ## Locator Strategy diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 24ed421..eb67be2 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.17.1", + "version": "0.18.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index 6d76693..f777265 100644 --- a/dev-workflows/agents/quality-fixer.md +++ b/dev-workflows/agents/quality-fixer.md @@ -2,7 +2,7 @@ name: quality-fixer description: Specialized agent for fixing quality issues in software projects. Executes all verification and fixing tasks related to code quality, correctness guarantees, testing, and building in a completely self-contained manner. Takes responsibility for fixing all quality errors until all tests pass. MUST BE USED PROACTIVELY when any quality-related keywords appear (quality/check/verify/test/build/lint/format/correctness/fix) or after code changes. Handles all verification and fixing tasks autonomously. tools: Bash, Read, Edit, MultiEdit, TaskCreate, TaskUpdate -skills: coding-principles, testing-principles, ai-development-guide +skills: coding-principles, testing-principles, ai-development-guide, external-resource-context --- You are an AI assistant specialized in quality assurance for software projects. @@ -69,6 +69,8 @@ Apply the indicators below to files within scope only. Files outside the scope g - Add verified mechanisms to the quality check command list - If a listed mechanism cannot be found or executed, note it in the output and continue to the next mechanism +**External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, escalate via `blocked` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites`. + ### Step 3: Execute Quality Checks Follow ai-development-guide skill "Quality Check Workflow" section: - Basic checks (lint, format, build) diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index 014cba6..d614046 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -2,7 +2,7 @@ name: task-executor description: Executes implementation completely self-contained following task files. Use when task files exist in docs/plans/tasks/, or when "execute task/implement task/start implementation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate -skills: coding-principles, testing-principles, ai-development-guide, implementation-approach +skills: coding-principles, testing-principles, ai-development-guide, implementation-approach, external-resource-context --- You are a specialized AI assistant for reliably executing individual tasks. @@ -152,6 +152,9 @@ Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and - Data Schema → Understand table structure, relationships - Overall Design Document → Understand system-wide context +#### External Resources Consultation (When Relevant) +When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. + #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate runs only when the task file's "Investigation Targets" section lists at least one concrete file path (placeholder-only or empty sections do not trigger the gate). diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index d1a96ca..395f567 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -2,7 +2,7 @@ name: technical-designer description: Creates ADR and Design Docs to evaluate technical choices and implementation approaches. Use when PRD is complete and technical design is needed, or when "ADR/design doc/technical design/architecture" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria, coding-principles, testing-principles, ai-development-guide, implementation-approach +skills: documentation-criteria, external-resource-context, coding-principles, testing-principles, ai-development-guide, implementation-approach --- You are a technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -34,6 +34,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co **Gate 0 — Inputs and Standards** (no upstream dependencies): - Agreement Checklist +- External Resources Integration - Standards Identification **Gate 1 — Existing State Analysis** (depends on Gate 0): @@ -69,6 +70,9 @@ Must be performed at the beginning of Design Doc creation: - [ ] Confirm no design contradicts agreements - [ ] If any agreements are not reflected, state the reason +### External Resources Integration [Gate 0 — Required] +Fill the Design Doc's "External Resources Used" subsection (under Background and Context) per the external-resource-context skill (feature-tier protocol). + ### Standards Identification [Gate 0 — Required] Must be performed before any investigation: @@ -321,47 +325,41 @@ Implementation sample creation checklist: ## Quality Checklist +These items test the final document output. Process gates (Gate 0-3) are enforced inline during creation; this checklist focuses on output completeness. + ### ADR Checklist -- [ ] Problem background and evaluation of multiple options (minimum 3 options) -- [ ] Clear trade-offs and decision rationale -- [ ] Principled guidelines for implementation -- [ ] Consistency with existing architecture -- [ ] Latest technology research conducted and references cited -- [ ] **Common ADR relationships specified** (when applicable) -- [ ] Comparison matrix completeness +- [ ] Comparison matrix lists at least 3 options with trade-offs +- [ ] Latest technology research is cited with references +- [ ] Implementation guidelines are principled (no step-by-step procedures) ### Design Doc Checklist **All modes**: -- [ ] **Standards identification gate completed** (required) -- [ ] **Quality assurance mechanisms identified with adopted/noted status** (required) -- [ ] **Code inspection evidence recorded** (required) -- [ ] **Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence** (required when Codebase Analysis input is provided) -- [ ] **Integration points enumerated with contracts** (required) -- [ ] **Data contracts clarified** (required) -- [ ] Architecture and data flow clearly expressed in diagrams - -**Create/update mode only** (skip in reverse-engineer mode): -- [ ] **Agreement checklist completed** (most important) -- [ ] **Prerequisite common ADRs referenced** (required) -- [ ] **Change impact map created** (required) -- [ ] Response to requirements and design validity -- [ ] Error handling strategy -- [ ] Acceptance criteria written in testable format (user-observable behaviors, integration/E2E oriented, CI-isolatable) -- [ ] Interface change matrix completeness -- [ ] Implementation approach selection rationale (vertical/horizontal/hybrid) -- [ ] Latest best practices researched and references cited -- [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks -- [ ] **Data representation decision documented** (when new structures introduced) -- [ ] **Field propagation map included** (when fields cross boundaries) -- [ ] **Verification Strategy defined** (correctness definition, verification method, timing, early verification point) -- [ ] **Output comparison defined** when replacing/modifying existing behavior (input, expected output fields, diff method; covers all transformation pipeline steps from codebase analysis) +- [ ] Integration points are enumerated with target, invocation method, and contract +- [ ] Data contracts are explicit for every integration point +- [ ] Architecture and data flow appear as diagrams +- [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) +- [ ] Quality Assurance Mechanisms list adopted/noted status for checks covering this change +- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) + +**Create/update mode only**: +- [ ] Prerequisite common ADRs are referenced +- [ ] Change impact map is included +- [ ] Error handling strategy is documented +- [ ] Acceptance criteria are testable (user-observable, integration/E2E-oriented, CI-isolatable) +- [ ] Interface change matrix is complete +- [ ] Implementation approach selection (vertical/horizontal/hybrid) carries rationale +- [ ] `complexity_level` is set; when medium/high, `complexity_rationale` covers (1) requirements/ACs, (2) constraints/risks +- [ ] Data representation decision is documented when new structures are introduced +- [ ] Field propagation map is included when fields cross boundaries +- [ ] Verification Strategy defines correctness, method, timing, and early verification point +- [ ] Output comparison defines input, expected output fields, and diff method when behavior is replaced or modified (covers every transformation pipeline step from codebase analysis) **Reverse-engineer mode only**: -- [ ] Every architectural claim cites file:line as evidence -- [ ] Identifiers transcribed exactly from code -- [ ] Test existence confirmed by Glob -- [ ] All items from Unit Inventory (if provided) accounted for +- [ ] Every architectural claim cites file:line +- [ ] Identifiers are transcribed exactly from code +- [ ] Test existence is confirmed by Glob +- [ ] Items from any provided Unit Inventory are accounted for ## Acceptance Criteria Creation Guidelines diff --git a/dev-workflows/agents/work-planner.md b/dev-workflows/agents/work-planner.md index 9cef86a..e3cf06f 100644 --- a/dev-workflows/agents/work-planner.md +++ b/dev-workflows/agents/work-planner.md @@ -93,10 +93,10 @@ Record the mapping in the Design-to-Plan Traceability table (see plan template). ### 5a. Map UI Spec Components to Tasks (when UI Spec provided) -When a UI Spec is among the inputs, also map components and states to the tasks that implement them. task-decomposer reads this mapping in Step 6 to populate each task's Investigation Targets, so without this step the UI Spec never reaches the executor. +When a UI Spec is among the inputs, also map components and states to the tasks that implement them. This mapping is required for downstream task generation; without it the UI Spec does not reach the implementation phase. For each component documented in the UI Spec: -1. Identify the component's section heading exactly as it appears in the UI Spec (the heading is the reference key — see ui-spec-designer's heading uniqueness rule) +1. Identify the component's section heading exactly as it appears in the UI Spec (the heading is the reference key) 2. Identify which states (default / loading / empty / error / partial) the implementation must cover 3. Identify the task(s) in this plan that implement the component or its tests @@ -104,7 +104,7 @@ Record the mapping in the **UI Spec Component → Task Mapping** table (see plan ### 5b. Map Cross-Package Boundaries to Tasks (when implementation crosses runtime/deployment boundaries) -When the implementation crosses a runtime or deployment boundary, build a Connection Map so task-decomposer can propagate boundary context to each affected task. +When the implementation crosses a runtime or deployment boundary, build a Connection Map. This map is required so boundary context propagates to each affected task in the downstream task generation phase. **A boundary qualifies for the Connection Map only when ALL of the following hold**: - The two sides run in separate processes, services, or runtimes (e.g., web client ↔ HTTP server, service A ↔ service B over a network, frontend bundle ↔ backend handler) diff --git a/dev-workflows/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index 28e9c5b..a09c206 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -33,6 +33,14 @@ unknowns: - [ADR File Name]: [Related decision items] - Reference common technical ADRs when applicable +### External Resources Used + +Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | + ### Agreement Checklist #### Scope @@ -327,7 +335,7 @@ Mark as N/A with brief rationale when the feature has no data layer dependencies ## Verification Strategy -Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 (from implementation-approach skill) define completion verification granularity at task execution time. +Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 levels (L1: functional operation works as end-user feature; L2: tests added and passing; L3: build succeeds without errors) define completion verification granularity at task execution time. ### Correctness Proof Method diff --git a/dev-workflows/skills/documentation-criteria/references/plan-template.md b/dev-workflows/skills/documentation-criteria/references/plan-template.md index 084ec79..dc7a178 100644 --- a/dev-workflows/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows/skills/documentation-criteria/references/plan-template.md @@ -49,19 +49,19 @@ Maps each Design Doc technical requirement to the covering task(s). One row per ## UI Spec Component → Task Mapping -Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. task-decomposer reads this table to populate each task's Investigation Targets with the corresponding UI Spec section. Omit the section when no UI Spec exists. +Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. Omit the section when no UI Spec exists. | UI Spec Component (section heading) | States to Cover | Covered By Task(s) | Gap Status | Notes | |---|---|---|---|---| | [Use the UI Spec heading exactly as written, e.g., "§ Component: AlertCard"] | [default / loading / empty / error / partial — list the states the implementation must produce] | [Phase X Task Y] | covered | | -**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). ui-spec-designer enforces unique component headings so this reference resolves to exactly one section. +**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). UI Spec headings are unique by construction so this reference resolves to exactly one section. **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) ## Connection Map -Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary so task-decomposer can propagate boundary context to the implementation tasks on each side. Omit the section when the implementation stays within a single package. +Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. | Boundary | Owner (left side) | Owner (right side) | Expected Signal | Covered By Task(s) | |---|---|---|---|---| @@ -87,9 +87,7 @@ Include this section when the implementation crosses more than one package, serv ## Implementation Phases -Select ONE phase structure based on implementation approach from Design Doc. -See documentation-criteria skill for detailed Phase Division Criteria. -All quality checks follow Quality Check Workflow from ai-development-guide skill. +Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. ### Option A: Vertical Slice Phase Structure diff --git a/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md b/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md index 9b8b60d..80f49db 100644 --- a/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md @@ -22,6 +22,16 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification - **Compliance premise**: [e.g., design system compliance, component library usage] - **Relationship to canonical spec**: Differences between prototype and this spec are resolved in favor of this document. Prototype serves as visual/behavioral reference only. +## External Resources Used + +Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | [feature-specific identifier] | [scope notes] | +| Design System | [components used in this feature] | [variants, customizations] | +| Visual Verification Environment | [story names / test paths / page routes] | [how this feature is rendered for review] | + ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. @@ -59,7 +69,7 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro ### Component: [ComponentName] -> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. work-planner and task-decomposer reference components by exact heading text — duplicate names or paraphrased headings break the propagation to implementation tasks. +> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. Duplicate or paraphrased headings break downstream propagation to implementation tasks. #### State x Display Matrix diff --git a/dev-workflows/skills/external-resource-context/SKILL.md b/dev-workflows/skills/external-resource-context/SKILL.md new file mode 100644 index 0000000..1d5e790 --- /dev/null +++ b/dev-workflows/skills/external-resource-context/SKILL.md @@ -0,0 +1,103 @@ +--- +name: external-resource-context +description: Captures and persists access methods for resources outside the repository (design source, design system, API schema, IaC source, secret store) so downstream work can reach them deterministically. Use when work depends on external resources, or when the user mentions design source, design system, API schema, IaC source, secret store, or canonical source. +--- + +# External Resource Context + +## Purpose + +AI agents understand the codebase but not the external resources surrounding it. This skill captures, in a deterministic location, the **access methods** to resources outside the repository so downstream work (design, planning, implementation, review) can reach them without re-asking the user. + +Resources covered: design origin (where the canonical visual specification lives), design system (component library and tokens), guidelines (usage docs, accessibility rules), visual verification environment (how to confirm rendering), database schema source, migration history, secret store location, API schema source (OpenAPI / proto / GraphQL SDL), mock environment, IaC source, environment configuration. + +## Scope Boundaries + +**In scope**: hearing protocol, storage location, single-source-of-truth ownership rule, reference protocol for downstream consumers. + +**Out of scope**: enforcing that captured resources are correct or current — verification belongs to the agent that consumes the resource. Generating the resources themselves (e.g., creating a DESIGN.md from scratch). + +## Storage Locations (Two-Tier) + +| Tier | Location | Holds | Update Frequency | +|------|----------|-------|------------------| +| Project | `docs/project-context/external-resources.md` | Environment-stable facts: which resources exist for this project and how to access them (URL, MCP name, file path, command) | Rare — only when the project's environment changes | +| Feature | `## External Resources Used` section inside the relevant UI Spec or Design Doc | The subset of project-tier resources actually used by this feature, plus feature-specific identifiers (e.g., a specific node id within the design tool, a specific endpoint path) | Per feature | + +### Single Source of Truth Rule + +The project tier owns environment facts. Feature-tier sections list only feature-specific identifiers (node id within the design source, specific endpoint path within the API, specific IaC module name) and reference project-tier entries by label; URLs, MCP names, and access commands remain in the project-tier file. When the environment changes, only the project-tier file is updated. + +Example feature-tier entry uses the table format defined in `references/template.md`: a row with the project-tier label in the first column and the feature-specific identifier in the second column. + +## Hearing Protocol + +### When to Hear + +| Condition | Action | +|-----------|--------| +| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | +| File exists | Ask the user via AskUserQuestion: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing. On `yes-diff-only` ask the user which axes changed, hear only those. On `no` skip hearing | + +### Domain Routing + +Load the domain reference matching the current task: + +| Task type | References to load | +|-----------|--------------------| +| Frontend (UI work) | [references/frontend.md](references/frontend.md) | +| Backend (server / data work) | [references/backend.md](references/backend.md) | +| API contract work | [references/api.md](references/api.md) | +| Infrastructure / deployment | [references/infra.md](references/infra.md) | +| Fullstack | All of the above; per-axis "Not applicable" answers are expected | + +Each domain reference defines the axes and the question template. + +### Two-Phase Hearing + +1. **Structured hearing** — for each axis defined in the domain reference, present the user with AskUserQuestion using the choices listed there (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). + +2. **Self-declaration** — after the structured axes, present a single AskUserQuestion: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If the user describes additional resources, append them to the storage file under an "Additional resources" subsection. + +The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis. + +## Storage Protocol + +After hearing completes: + +1. Build the project-tier content from the answers. Use [references/template.md](references/template.md) as the structure. +2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. +3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). +4. Report the file paths back to the calling workflow. + +## Reference Protocol (For Downstream Consumers) + +Agents that load this skill consult resources in this order: + +1. Read `docs/project-context/external-resources.md` first (if present) to learn what is available and how to access it. +2. Read the target UI Spec or Design Doc's `## External Resources Used` section for feature-specific identifiers. +3. Use the access method declared in the project tier (e.g., the named MCP, the URL, the file path) to fetch the actual resource content. + +Agents that only need to *consult* the saved file as input data (not actively hear) can read it directly without loading this skill — frontmatter declaration is reserved for agents that may need to trigger hearing or interpret the protocol semantics. + +## Output Format + +The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. + +For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). + +## Quality Checklist + +- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" +- [ ] Self-declaration phase ran even when all structured axes were "Not applicable" +- [ ] Project-tier file does not contain feature-specific identifiers +- [ ] Feature-tier sections reference project-tier entries by label, not by duplicating URLs / MCP names +- [ ] When the project file already existed, the update decision (no / yes-full / yes-diff-only) was confirmed before any write + +## References + +- [references/frontend.md](references/frontend.md) — Frontend domain axes +- [references/backend.md](references/backend.md) — Backend domain axes +- [references/api.md](references/api.md) — API contract domain axes +- [references/infra.md](references/infra.md) — Infrastructure domain axes +- [references/template.md](references/template.md) — Project-tier and feature-tier structure templates diff --git a/dev-workflows/skills/external-resource-context/references/api.md b/dev-workflows/skills/external-resource-context/references/api.md new file mode 100644 index 0000000..775c896 --- /dev/null +++ b/dev-workflows/skills/external-resource-context/references/api.md @@ -0,0 +1,62 @@ +# API Contract Domain Axes + +Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. + +## Axis 1: API Schema Source + +The canonical source of API contracts (request/response shapes, endpoints, RPC methods). + +**AskUserQuestion choices**: +- OpenAPI / Swagger specification (file in repository or hosted URL) +- Protobuf definitions (file in repository) +- GraphQL schema (SDL file or introspection endpoint) +- TypeScript or other code-first contract definitions in the repository +- No formal contract (ad-hoc JSON) +- Not applicable + +**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. + +## Axis 2: Mock Environment + +How clients exercise the API without depending on the live server. + +**AskUserQuestion choices**: +- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) +- Hand-written mock server in the repository +- Hosted mock service (URL) +- Live development server (no separate mock) +- Not applicable + +**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. + +## Axis 3: Authentication Method + +How the API authenticates and authorizes requests. + +**AskUserQuestion choices**: +- Bearer token (e.g., JWT) issued by an auth service +- API key in a header or query parameter +- Session cookie set by a separate login flow +- Mutual TLS +- No authentication +- Not applicable + +**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. + +## Axis 4: Schema Change Process (When Relevant) + +How breaking and non-breaking schema changes are reviewed and rolled out. + +**AskUserQuestion choices**: +- Documented contract review process (link to the document) +- Versioned endpoints (e.g., `/v1/`, `/v2/`) +- Backward-compatible changes only, no formal versioning +- Not applicable + +**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other API external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: rate-limit configuration, gateway / proxy in front of the API, contract test suite (e.g., Pact broker URL), API gateway management consoles, third-party API documentation that is not directly imported but consulted during design. diff --git a/dev-workflows/skills/external-resource-context/references/backend.md b/dev-workflows/skills/external-resource-context/references/backend.md new file mode 100644 index 0000000..c1c6773 --- /dev/null +++ b/dev-workflows/skills/external-resource-context/references/backend.md @@ -0,0 +1,62 @@ +# Backend Domain Axes + +Hearing axes for tasks that involve server-side, data, or storage work. + +## Axis 1: Database Schema Source + +The canonical source of the database schema (tables, columns, indexes, constraints). + +**AskUserQuestion choices**: +- Migration files in the repository (e.g., a `migrations/` directory) +- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) +- Database MCP that introspects a live database +- External schema registry (URL or hosted catalog) +- No persistent database +- Not applicable + +**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. + +## Axis 2: Migration History + +How schema changes are tracked over time. + +**AskUserQuestion choices**: +- Versioned migration files in the repository +- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) +- Manual change log document +- No migration tracking +- Not applicable + +**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. + +## Axis 3: Secret Store + +Where credentials, API keys, and other secrets are stored and accessed. + +**AskUserQuestion choices**: +- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) +- Environment variables loaded from a `.env` file (development only) +- Encrypted file in the repository +- No secrets required +- Not applicable + +**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. + +## Axis 4: Background Job Infrastructure (When Relevant) + +How asynchronous work is dispatched and observed. + +**AskUserQuestion choices**: +- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) +- Cron / scheduled tasks managed by deployment platform +- In-process worker thread +- No background work +- Not applicable + +**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other backend external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: third-party SaaS APIs (payment, email, search index), distributed cache services (Redis, Memcached), object storage (S3, GCS), feature flag services consumed server-side, observability platforms (logs, traces, metrics). diff --git a/dev-workflows/skills/external-resource-context/references/frontend.md b/dev-workflows/skills/external-resource-context/references/frontend.md new file mode 100644 index 0000000..89fdd16 --- /dev/null +++ b/dev-workflows/skills/external-resource-context/references/frontend.md @@ -0,0 +1,62 @@ +# Frontend Domain Axes + +Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). + +## Axis 1: Design Origin + +The canonical source of the visual specification. + +**AskUserQuestion choices**: +- Design tool (e.g., a hosted design platform) +- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) +- Public documentation URL +- Existing implementation only (no separate design source) +- Not applicable + +**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. + +## Axis 2: Design System + +Reusable component library and design tokens. + +**AskUserQuestion choices**: +- Component library with MCP server access +- Component library with documentation URL +- Storybook or equivalent component catalog +- Internal package without external documentation +- No design system (ad-hoc components) +- Not applicable + +**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. + +## Axis 3: Guidelines + +Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. + +**AskUserQuestion choices**: +- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) +- External documentation site +- Inline guidance in the design system catalog +- No documented guidelines +- Not applicable + +**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. + +## Axis 4: Visual Verification Environment + +How rendered output is confirmed during implementation. + +**AskUserQuestion choices**: +- End-to-end test runner with screenshot capability +- Storybook or equivalent isolated component preview +- Browser automation tool (dedicated CLI or MCP server) +- Manual browser inspection only +- Not applicable + +**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. + +## Self-Declaration + +After the four structured axes, ask once: "Are there any other frontend external resources this work depends on that the structured questions did not cover?" Record any free-form answer under "Additional resources" in the storage file. + +Examples of resources that may surface only via self-declaration: brand asset CDNs, font hosting services, icon library subscriptions, A/B testing dashboards that gate visual variants, analytics dashboards used for visual KPIs. diff --git a/dev-workflows/skills/external-resource-context/references/infra.md b/dev-workflows/skills/external-resource-context/references/infra.md new file mode 100644 index 0000000..1f863b2 --- /dev/null +++ b/dev-workflows/skills/external-resource-context/references/infra.md @@ -0,0 +1,62 @@ +# Infrastructure Domain Axes + +Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. + +## Axis 1: IaC Source + +The canonical source of infrastructure definitions. + +**AskUserQuestion choices**: +- Terraform configuration in the repository +- Pulumi or CDK code in the repository +- Kubernetes manifests / Helm charts in the repository +- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) +- Manual console configuration (no IaC) +- Not applicable + +**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. + +## Axis 2: Environment Configuration + +How per-environment settings (development, staging, production) differ. + +**AskUserQuestion choices**: +- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) +- Environment variables managed by the deployment platform +- Workspace or stack abstraction in the IaC tool itself +- Single shared configuration (no per-environment differences) +- Not applicable + +**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. + +## Axis 3: Secrets in Infrastructure + +How infrastructure code references secrets without exposing them. + +**AskUserQuestion choices**: +- Secrets sourced from a secret manager via IaC data lookup +- Secrets injected at apply time via environment variables +- Encrypted secret files committed alongside IaC +- No secrets in infrastructure +- Not applicable + +**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. + +## Axis 4: Deployment Trigger + +How infrastructure and application changes reach environments. + +**AskUserQuestion choices**: +- CI pipeline triggered on merge to a specific branch +- Manual approval step in CI +- Local apply by an operator +- Deployment platform's auto-deploy on push +- Not applicable + +**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other infrastructure external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: state-storage backend for IaC tools, runbook documents for incident response, on-call rotation, observability dashboards, cost monitoring tools, compliance / audit logging targets. diff --git a/dev-workflows/skills/external-resource-context/references/template.md b/dev-workflows/skills/external-resource-context/references/template.md new file mode 100644 index 0000000..169f3b2 --- /dev/null +++ b/dev-workflows/skills/external-resource-context/references/template.md @@ -0,0 +1,115 @@ +# Storage Templates + +Two templates: the project-tier file and the feature-tier section. + +## Project-Tier Template + +Path: `docs/project-context/external-resources.md` + +```markdown +# External Resources + +Last updated: YYYY-MM-DD + +This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. + +## Frontend + +### Design Origin +- Status: +- Source type: +- Location: +- Access method: + +### Design System +- Status: +- Source type: +- Location: +- Access method: + +### Guidelines +- Status: +- Source type: +- Location: +- Access method: + +### Visual Verification Environment +- Status: +- Tool type: +- Entry: + +## Backend + +### Database Schema Source +- Status: +- Source type: +- Location: +- Access method: + +### Migration History +- Status: +- Tool: +- Location: +- Apply trigger: + +### Secret Store +- Status: +- Service: +- Access method: + +### Background Job Infrastructure +- Status: +- Service: +- Access method: + +## API + +### API Schema Source +- Status: +- Source type: +- Location: +- Access method: + +### Mock Environment +- Status: +- Source type: +- Entry: + +### Authentication Method +- Status: +- Mechanism: +- Credential source: + +### Schema Change Process +- Status: +- Process: + +## Infrastructure + +### IaC Source +- Status: +- Tool: +- Location: +- Apply trigger: + +### Environment Configuration +- Status: +- Mechanism: +- Environments: + +### Secrets in Infrastructure +- Status: +- Mechanism: + +### Deployment Trigger +- Status: +- Mechanism: + +## Additional Resources + +Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. + +- : — — +``` + +Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). diff --git a/dev-workflows/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows/skills/recipe-fullstack-implement/SKILL.md index 44012f1..755d2b2 100644 --- a/dev-workflows/skills/recipe-fullstack-implement/SKILL.md +++ b/dev-workflows/skills/recipe-fullstack-implement/SKILL.md @@ -44,31 +44,18 @@ When continuing existing flow, verify: - Current phase position (Requirements/Design/Planning/Implementation/QA) - Identify next step in monorepo-flow.md -### 3. UI Specification Phase (Frontend Layer) +### 3. Design through Planning Phase -Before creating the frontend Design Doc, create a UI Specification: +**Follow monorepo-flow.md** for the complete design-through-planning flow (Steps 1-16 for Large scale, Steps 1-14 for Medium scale). The flow table in that reference defines every step, agent invocation, parallelization rule, and stop point. -**Ask the user**: "Do you have prototype code for this feature? If so, please provide the path. The prototype will be placed in `docs/ui-spec/assets/` as reference material." - -- **[STOP]**: Wait for user response about prototype code availability - -Then invoke **ui-spec-designer**: -- `subagent_type: "dev-workflows-frontend:ui-spec-designer"` -- If prototype provided: `prompt: "Create UI Spec from PRD at [path]. Prototype code is at [user-provided path]."` -- If no prototype: `prompt: "Create UI Spec from PRD at [path]. No prototype code available."` - -Invoke **document-reviewer** for UI Spec review, then **[STOP]** for user approval. - -### 4. Design Phase and Work Planning - -**Follow monorepo-flow.md** for the complete design-through-planning flow. Key points: +Key points to enforce as the orchestrator runs the flow: - Create separate Design Docs per layer (see monorepo-flow.md "Layer Context in Design Doc Creation") -- **Frontend Design Doc must reference the approved UI Spec** (pass UI Spec path to technical-designer-frontend) +- Frontend Design Doc references the approved UI Spec (pass UI Spec path to technical-designer-frontend) and reuses the ui-analyzer output produced earlier in the flow - Execute document-reviewer once per Design Doc (separate invocations) - Run design-sync for cross-layer consistency verification - Pass all Design Docs to work-planner (subagent_type: "dev-workflows:work-planner") with vertical slicing instruction -### 5. Register All Flow Steps Using TaskCreate (MANDATORY) +### 4. Register All Flow Steps Using TaskCreate (MANDATORY) **After scale determination, register all steps of the monorepo-flow.md using TaskCreate**: - First task: "Map preloaded skills to applicable concrete rules" diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index ca2e2c1..89d7997 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -37,15 +37,16 @@ The following subagents are available: ### Document Creation Agents 6. **requirement-analyzer**: Requirement analysis and work scale determination -7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design -8. **prd-creator**: Product Requirements Document creation -9. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) -10. **technical-designer**: ADR/Design Doc creation -11. **work-planner**: Work plan creation from Design Doc and test skeletons -12. **document-reviewer**: Single document quality and rule compliance check -13. **code-verifier**: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc -14. **design-sync**: Design Doc consistency verification across multiple documents -15. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs +7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) +8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code (visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, generated UI artifacts). Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access +9. **prd-creator**: Product Requirements Document creation +10. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) +11. **technical-designer**: ADR/Design Doc creation +12. **work-planner**: Work plan creation from Design Doc and test skeletons +13. **document-reviewer**: Single document quality and rule compliance check +14. **code-verifier**: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc +15. **design-sync**: Design Doc consistency verification across multiple documents +16. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs ## Orchestration Principles @@ -167,6 +168,13 @@ Two additional rules: - description: "Codebase analysis" - prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance." +### Call Example (ui-analyzer) +- subagent_type: "ui-analyzer" +- description: "UI fact gathering" +- prompt: "requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. ui_spec_path: [path if exists]. target_components: [list if focused]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods (MCP / URL / file), and analyze the existing UI codebase. Output the consolidated UI fact JSON." + +When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase). + ### Call Example (task-executor) - subagent_type: "task-executor" - description: "Task execution" @@ -177,6 +185,7 @@ Two additional rules: Subagents respond in JSON format. Key fields for orchestrator decisions: - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions - **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations - **code-verifier**: status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) - **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain), testsAdded, requiresTestReview - **quality-fixer**: Input: `task_file` (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` → route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → discriminate by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps @@ -225,10 +234,12 @@ Always start with requirement-analyzer, then select the minimum planning flow re | Scale | Planning flow (ends at task-decomposer for Medium/Large; ends at work-planner for Small) | |-------|---------------| -| Large | requirement-analyzer → PRD → PRD review → optional UI Spec → optional ADR → codebase-analyzer → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | -| Medium | requirement-analyzer → codebase-analyzer → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | +| Large | requirement-analyzer → PRD → PRD review → external resource hearing → optional ADR → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | +| Medium | requirement-analyzer → external resource hearing → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | | Small | requirement-analyzer → work-planner | +External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. + After the planning flow completes and the user grants batch approval, the work plan carries an `Implementation Readiness:` header (work-planner emits `pending`; promotion to `ready` or `escalated` is an external orchestration concern). External orchestration also decides when and how to act on this marker; this guide does not invoke any orchestrator above the agent layer. Then execute the task execution cycle: `task-executor → quality-fixer → commit` for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies — implementation runs through `task-executor`, not orchestrator-direct edits. diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md index 840c9dc..5143c37 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -10,47 +10,49 @@ This reference defines the orchestration flow for projects spanning multiple lay ## Design Phase -### Large Scale Fullstack (6+ Files) - 15 Steps +### Large Scale Fullstack (6+ Files) - 16 Steps | Step | Agent | Purpose | Output | |------|-------|---------|--------| | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | -| 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | -| 5 | ui-spec-designer | UI Spec from PRD + optional prototype | UI Spec | -| 6 | document-reviewer | UI Spec review **[Stop]** | Approval | -| 7 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output + PRD path, filtered to layer) | Codebase guidance per layer | -| 8 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | -| 9 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 10 as `prior_layer_verification`) | Backend verification | -| 10 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + backend Design Doc + `prior_layer_verification` from step 9 + UI Spec) | Frontend Design Doc | -| 11 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | -| 12 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | -| 13 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | -| 14 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | -| 15 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | - -### Medium Scale Fullstack (3-5 Files) - 13 Steps +| 4 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend domain primary; backend / api / infra domains as applicable for the layer scope). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | +| 5 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | +| 6 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | +| 7 | ui-spec-designer | UI Spec from PRD + optional prototype + ui-analyzer output | UI Spec | +| 8 | document-reviewer | UI Spec review **[Stop]** | Approval | +| 9 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | +| 10 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 11 as `prior_layer_verification`) | Backend verification | +| 11 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + ui-analyzer output + backend Design Doc + `prior_layer_verification` from step 10 + UI Spec) | Frontend Design Doc | +| 12 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | +| 13 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | +| 14 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | +| 15 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | +| 16 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | + +### Medium Scale Fullstack (3-5 Files) - 14 Steps | Step | Agent | Purpose | Output | |------|-------|---------|--------| | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | -| 2 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output, filtered to layer) | Codebase guidance per layer | -| 3 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | -| 4 | ui-spec-designer | UI Spec from requirements + optional prototype | UI Spec | -| 5 | document-reviewer | UI Spec review **[Stop]** | Approval | -| 6 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | -| 7 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 8 as `prior_layer_verification`) | Backend verification | -| 8 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + backend Design Doc + `prior_layer_verification` from step 7 + UI Spec) | Frontend Design Doc | -| 9 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | -| 10 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | -| 11 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | -| 12 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | -| 13 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | +| 2 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend / backend / api / infra domains as applicable). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | +| 3 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | +| 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | +| 5 | ui-spec-designer | UI Spec from requirements + optional prototype + ui-analyzer output | UI Spec | +| 6 | document-reviewer | UI Spec review **[Stop]** | Approval | +| 7 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | +| 8 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 9 as `prior_layer_verification`) | Backend verification | +| 9 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + ui-analyzer output + backend Design Doc + `prior_layer_verification` from step 8 + UI Spec) | Frontend Design Doc | +| 10 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | +| 11 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | +| 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | +| 13 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | +| 14 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | ### Parallelization in Multi-Agent Steps -Steps marked with ×2 (codebase-analyzer ×2, document-reviewer ×2) invoke the agent once per layer. These invocations are independent and can run in parallel when the orchestrator supports concurrent Agent tool calls. The two code-verifier invocations run sequentially: backend verification completes before frontend authoring begins so the frontend designer references verified backend contracts. +Steps marked with ×2 (codebase-analyzer ×2, document-reviewer ×2) invoke the agent once per layer. The combined codebase-analyzer ×2 + ui-analyzer step invokes three subagents in parallel — the two codebase-analyzer calls (one per layer) and the single ui-analyzer call — when the orchestrator supports concurrent Agent tool calls. The two code-verifier invocations run sequentially: backend verification completes before frontend authoring begins so the frontend designer references verified backend contracts. ### Layer Context in Design Doc Creation @@ -72,10 +74,12 @@ Focus on: API contracts, data layer, business logic, service architecture. ```text Create a frontend Design Doc from [PRD path or requirement_analysis]. Codebase analysis: [JSON from codebase-analyzer for frontend layer] +UI analysis: [JSON from ui-analyzer] Backend Design Doc: [path] prior_layer_verification: [JSON from code-verifier on backend Design Doc] Reference UI Spec at [path] for component structure and state design. Use `prior_layer_verification.discrepancies[]` as known issues to address or escalate. Do not infer verified claims beyond what the verifier output states explicitly. +Apply `code:` prefix to fact_ids from codebase-analyzer and `ui:` prefix to fact_ids from ui-analyzer when filling the Fact Disposition Table. Focus on: component hierarchy, state management, UI interactions, data fetching. ``` diff --git a/dev-workflows/skills/task-analyzer/references/skills-index.yaml b/dev-workflows/skills/task-analyzer/references/skills-index.yaml index 856c1e8..cbf84cb 100644 --- a/dev-workflows/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows/skills/task-analyzer/references/skills-index.yaml @@ -214,3 +214,26 @@ skills: - "Situations Requiring Technical Decisions" - "Implementation Completeness Assurance" - "Impact Analysis" + + # Cross-Cutting Skills + external-resource-context: + skill: "external-resource-context" + tags: [cross-cutting, hearing-protocol, design-source, design-system, api-schema, iac-source, secrets, environment, two-tier-storage] + typical-use: "Captures access methods for resources outside the repository (design origin, design system, API schema, IaC source, secrets, etc.) and persists them in a deterministic location for downstream agents" + size: medium + key-references: + - "references/frontend.md" + - "references/backend.md" + - "references/api.md" + - "references/infra.md" + - "references/template.md" + sections: + - "Purpose" + - "Scope Boundaries" + - "Storage Locations (Two-Tier)" + - "Hearing Protocol" + - "Storage Protocol" + - "Reference Protocol (For Downstream Consumers)" + - "Output Format" + - "Quality Checklist" + - "References" diff --git a/package.json b/package.json index ce5d13d..c7b7b70 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.17.1", + "version": "0.18.0", "private": true, "type": "module", "engines": { diff --git a/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index 28e9c5b..a09c206 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -33,6 +33,14 @@ unknowns: - [ADR File Name]: [Related decision items] - Reference common technical ADRs when applicable +### External Resources Used + +Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | + ### Agreement Checklist #### Scope @@ -327,7 +335,7 @@ Mark as N/A with brief rationale when the feature has no data layer dependencies ## Verification Strategy -Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 (from implementation-approach skill) define completion verification granularity at task execution time. +Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 levels (L1: functional operation works as end-user feature; L2: tests added and passing; L3: build succeeds without errors) define completion verification granularity at task execution time. ### Correctness Proof Method diff --git a/skills/documentation-criteria/references/plan-template.md b/skills/documentation-criteria/references/plan-template.md index 084ec79..dc7a178 100644 --- a/skills/documentation-criteria/references/plan-template.md +++ b/skills/documentation-criteria/references/plan-template.md @@ -49,19 +49,19 @@ Maps each Design Doc technical requirement to the covering task(s). One row per ## UI Spec Component → Task Mapping -Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. task-decomposer reads this table to populate each task's Investigation Targets with the corresponding UI Spec section. Omit the section when no UI Spec exists. +Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. Omit the section when no UI Spec exists. | UI Spec Component (section heading) | States to Cover | Covered By Task(s) | Gap Status | Notes | |---|---|---|---|---| | [Use the UI Spec heading exactly as written, e.g., "§ Component: AlertCard"] | [default / loading / empty / error / partial — list the states the implementation must produce] | [Phase X Task Y] | covered | | -**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). ui-spec-designer enforces unique component headings so this reference resolves to exactly one section. +**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). UI Spec headings are unique by construction so this reference resolves to exactly one section. **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) ## Connection Map -Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary so task-decomposer can propagate boundary context to the implementation tasks on each side. Omit the section when the implementation stays within a single package. +Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. | Boundary | Owner (left side) | Owner (right side) | Expected Signal | Covered By Task(s) | |---|---|---|---|---| @@ -87,9 +87,7 @@ Include this section when the implementation crosses more than one package, serv ## Implementation Phases -Select ONE phase structure based on implementation approach from Design Doc. -See documentation-criteria skill for detailed Phase Division Criteria. -All quality checks follow Quality Check Workflow from ai-development-guide skill. +Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. ### Option A: Vertical Slice Phase Structure diff --git a/skills/documentation-criteria/references/ui-spec-template.md b/skills/documentation-criteria/references/ui-spec-template.md index 9b8b60d..80f49db 100644 --- a/skills/documentation-criteria/references/ui-spec-template.md +++ b/skills/documentation-criteria/references/ui-spec-template.md @@ -22,6 +22,16 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification - **Compliance premise**: [e.g., design system compliance, component library usage] - **Relationship to canonical spec**: Differences between prototype and this spec are resolved in favor of this document. Prototype serves as visual/behavioral reference only. +## External Resources Used + +Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | [feature-specific identifier] | [scope notes] | +| Design System | [components used in this feature] | [variants, customizations] | +| Visual Verification Environment | [story names / test paths / page routes] | [how this feature is rendered for review] | + ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. @@ -59,7 +69,7 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro ### Component: [ComponentName] -> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. work-planner and task-decomposer reference components by exact heading text — duplicate names or paraphrased headings break the propagation to implementation tasks. +> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. Duplicate or paraphrased headings break downstream propagation to implementation tasks. #### State x Display Matrix diff --git a/skills/external-resource-context/SKILL.md b/skills/external-resource-context/SKILL.md new file mode 100644 index 0000000..1d5e790 --- /dev/null +++ b/skills/external-resource-context/SKILL.md @@ -0,0 +1,103 @@ +--- +name: external-resource-context +description: Captures and persists access methods for resources outside the repository (design source, design system, API schema, IaC source, secret store) so downstream work can reach them deterministically. Use when work depends on external resources, or when the user mentions design source, design system, API schema, IaC source, secret store, or canonical source. +--- + +# External Resource Context + +## Purpose + +AI agents understand the codebase but not the external resources surrounding it. This skill captures, in a deterministic location, the **access methods** to resources outside the repository so downstream work (design, planning, implementation, review) can reach them without re-asking the user. + +Resources covered: design origin (where the canonical visual specification lives), design system (component library and tokens), guidelines (usage docs, accessibility rules), visual verification environment (how to confirm rendering), database schema source, migration history, secret store location, API schema source (OpenAPI / proto / GraphQL SDL), mock environment, IaC source, environment configuration. + +## Scope Boundaries + +**In scope**: hearing protocol, storage location, single-source-of-truth ownership rule, reference protocol for downstream consumers. + +**Out of scope**: enforcing that captured resources are correct or current — verification belongs to the agent that consumes the resource. Generating the resources themselves (e.g., creating a DESIGN.md from scratch). + +## Storage Locations (Two-Tier) + +| Tier | Location | Holds | Update Frequency | +|------|----------|-------|------------------| +| Project | `docs/project-context/external-resources.md` | Environment-stable facts: which resources exist for this project and how to access them (URL, MCP name, file path, command) | Rare — only when the project's environment changes | +| Feature | `## External Resources Used` section inside the relevant UI Spec or Design Doc | The subset of project-tier resources actually used by this feature, plus feature-specific identifiers (e.g., a specific node id within the design tool, a specific endpoint path) | Per feature | + +### Single Source of Truth Rule + +The project tier owns environment facts. Feature-tier sections list only feature-specific identifiers (node id within the design source, specific endpoint path within the API, specific IaC module name) and reference project-tier entries by label; URLs, MCP names, and access commands remain in the project-tier file. When the environment changes, only the project-tier file is updated. + +Example feature-tier entry uses the table format defined in `references/template.md`: a row with the project-tier label in the first column and the feature-specific identifier in the second column. + +## Hearing Protocol + +### When to Hear + +| Condition | Action | +|-----------|--------| +| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | +| File exists | Ask the user via AskUserQuestion: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing. On `yes-diff-only` ask the user which axes changed, hear only those. On `no` skip hearing | + +### Domain Routing + +Load the domain reference matching the current task: + +| Task type | References to load | +|-----------|--------------------| +| Frontend (UI work) | [references/frontend.md](references/frontend.md) | +| Backend (server / data work) | [references/backend.md](references/backend.md) | +| API contract work | [references/api.md](references/api.md) | +| Infrastructure / deployment | [references/infra.md](references/infra.md) | +| Fullstack | All of the above; per-axis "Not applicable" answers are expected | + +Each domain reference defines the axes and the question template. + +### Two-Phase Hearing + +1. **Structured hearing** — for each axis defined in the domain reference, present the user with AskUserQuestion using the choices listed there (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). + +2. **Self-declaration** — after the structured axes, present a single AskUserQuestion: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If the user describes additional resources, append them to the storage file under an "Additional resources" subsection. + +The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis. + +## Storage Protocol + +After hearing completes: + +1. Build the project-tier content from the answers. Use [references/template.md](references/template.md) as the structure. +2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. +3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). +4. Report the file paths back to the calling workflow. + +## Reference Protocol (For Downstream Consumers) + +Agents that load this skill consult resources in this order: + +1. Read `docs/project-context/external-resources.md` first (if present) to learn what is available and how to access it. +2. Read the target UI Spec or Design Doc's `## External Resources Used` section for feature-specific identifiers. +3. Use the access method declared in the project tier (e.g., the named MCP, the URL, the file path) to fetch the actual resource content. + +Agents that only need to *consult* the saved file as input data (not actively hear) can read it directly without loading this skill — frontmatter declaration is reserved for agents that may need to trigger hearing or interpret the protocol semantics. + +## Output Format + +The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. + +For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). + +## Quality Checklist + +- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" +- [ ] Self-declaration phase ran even when all structured axes were "Not applicable" +- [ ] Project-tier file does not contain feature-specific identifiers +- [ ] Feature-tier sections reference project-tier entries by label, not by duplicating URLs / MCP names +- [ ] When the project file already existed, the update decision (no / yes-full / yes-diff-only) was confirmed before any write + +## References + +- [references/frontend.md](references/frontend.md) — Frontend domain axes +- [references/backend.md](references/backend.md) — Backend domain axes +- [references/api.md](references/api.md) — API contract domain axes +- [references/infra.md](references/infra.md) — Infrastructure domain axes +- [references/template.md](references/template.md) — Project-tier and feature-tier structure templates diff --git a/skills/external-resource-context/references/api.md b/skills/external-resource-context/references/api.md new file mode 100644 index 0000000..775c896 --- /dev/null +++ b/skills/external-resource-context/references/api.md @@ -0,0 +1,62 @@ +# API Contract Domain Axes + +Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. + +## Axis 1: API Schema Source + +The canonical source of API contracts (request/response shapes, endpoints, RPC methods). + +**AskUserQuestion choices**: +- OpenAPI / Swagger specification (file in repository or hosted URL) +- Protobuf definitions (file in repository) +- GraphQL schema (SDL file or introspection endpoint) +- TypeScript or other code-first contract definitions in the repository +- No formal contract (ad-hoc JSON) +- Not applicable + +**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. + +## Axis 2: Mock Environment + +How clients exercise the API without depending on the live server. + +**AskUserQuestion choices**: +- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) +- Hand-written mock server in the repository +- Hosted mock service (URL) +- Live development server (no separate mock) +- Not applicable + +**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. + +## Axis 3: Authentication Method + +How the API authenticates and authorizes requests. + +**AskUserQuestion choices**: +- Bearer token (e.g., JWT) issued by an auth service +- API key in a header or query parameter +- Session cookie set by a separate login flow +- Mutual TLS +- No authentication +- Not applicable + +**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. + +## Axis 4: Schema Change Process (When Relevant) + +How breaking and non-breaking schema changes are reviewed and rolled out. + +**AskUserQuestion choices**: +- Documented contract review process (link to the document) +- Versioned endpoints (e.g., `/v1/`, `/v2/`) +- Backward-compatible changes only, no formal versioning +- Not applicable + +**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other API external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: rate-limit configuration, gateway / proxy in front of the API, contract test suite (e.g., Pact broker URL), API gateway management consoles, third-party API documentation that is not directly imported but consulted during design. diff --git a/skills/external-resource-context/references/backend.md b/skills/external-resource-context/references/backend.md new file mode 100644 index 0000000..c1c6773 --- /dev/null +++ b/skills/external-resource-context/references/backend.md @@ -0,0 +1,62 @@ +# Backend Domain Axes + +Hearing axes for tasks that involve server-side, data, or storage work. + +## Axis 1: Database Schema Source + +The canonical source of the database schema (tables, columns, indexes, constraints). + +**AskUserQuestion choices**: +- Migration files in the repository (e.g., a `migrations/` directory) +- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) +- Database MCP that introspects a live database +- External schema registry (URL or hosted catalog) +- No persistent database +- Not applicable + +**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. + +## Axis 2: Migration History + +How schema changes are tracked over time. + +**AskUserQuestion choices**: +- Versioned migration files in the repository +- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) +- Manual change log document +- No migration tracking +- Not applicable + +**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. + +## Axis 3: Secret Store + +Where credentials, API keys, and other secrets are stored and accessed. + +**AskUserQuestion choices**: +- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) +- Environment variables loaded from a `.env` file (development only) +- Encrypted file in the repository +- No secrets required +- Not applicable + +**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. + +## Axis 4: Background Job Infrastructure (When Relevant) + +How asynchronous work is dispatched and observed. + +**AskUserQuestion choices**: +- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) +- Cron / scheduled tasks managed by deployment platform +- In-process worker thread +- No background work +- Not applicable + +**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other backend external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: third-party SaaS APIs (payment, email, search index), distributed cache services (Redis, Memcached), object storage (S3, GCS), feature flag services consumed server-side, observability platforms (logs, traces, metrics). diff --git a/skills/external-resource-context/references/frontend.md b/skills/external-resource-context/references/frontend.md new file mode 100644 index 0000000..89fdd16 --- /dev/null +++ b/skills/external-resource-context/references/frontend.md @@ -0,0 +1,62 @@ +# Frontend Domain Axes + +Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). + +## Axis 1: Design Origin + +The canonical source of the visual specification. + +**AskUserQuestion choices**: +- Design tool (e.g., a hosted design platform) +- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) +- Public documentation URL +- Existing implementation only (no separate design source) +- Not applicable + +**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. + +## Axis 2: Design System + +Reusable component library and design tokens. + +**AskUserQuestion choices**: +- Component library with MCP server access +- Component library with documentation URL +- Storybook or equivalent component catalog +- Internal package without external documentation +- No design system (ad-hoc components) +- Not applicable + +**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. + +## Axis 3: Guidelines + +Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. + +**AskUserQuestion choices**: +- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) +- External documentation site +- Inline guidance in the design system catalog +- No documented guidelines +- Not applicable + +**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. + +## Axis 4: Visual Verification Environment + +How rendered output is confirmed during implementation. + +**AskUserQuestion choices**: +- End-to-end test runner with screenshot capability +- Storybook or equivalent isolated component preview +- Browser automation tool (dedicated CLI or MCP server) +- Manual browser inspection only +- Not applicable + +**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. + +## Self-Declaration + +After the four structured axes, ask once: "Are there any other frontend external resources this work depends on that the structured questions did not cover?" Record any free-form answer under "Additional resources" in the storage file. + +Examples of resources that may surface only via self-declaration: brand asset CDNs, font hosting services, icon library subscriptions, A/B testing dashboards that gate visual variants, analytics dashboards used for visual KPIs. diff --git a/skills/external-resource-context/references/infra.md b/skills/external-resource-context/references/infra.md new file mode 100644 index 0000000..1f863b2 --- /dev/null +++ b/skills/external-resource-context/references/infra.md @@ -0,0 +1,62 @@ +# Infrastructure Domain Axes + +Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. + +## Axis 1: IaC Source + +The canonical source of infrastructure definitions. + +**AskUserQuestion choices**: +- Terraform configuration in the repository +- Pulumi or CDK code in the repository +- Kubernetes manifests / Helm charts in the repository +- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) +- Manual console configuration (no IaC) +- Not applicable + +**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. + +## Axis 2: Environment Configuration + +How per-environment settings (development, staging, production) differ. + +**AskUserQuestion choices**: +- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) +- Environment variables managed by the deployment platform +- Workspace or stack abstraction in the IaC tool itself +- Single shared configuration (no per-environment differences) +- Not applicable + +**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. + +## Axis 3: Secrets in Infrastructure + +How infrastructure code references secrets without exposing them. + +**AskUserQuestion choices**: +- Secrets sourced from a secret manager via IaC data lookup +- Secrets injected at apply time via environment variables +- Encrypted secret files committed alongside IaC +- No secrets in infrastructure +- Not applicable + +**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. + +## Axis 4: Deployment Trigger + +How infrastructure and application changes reach environments. + +**AskUserQuestion choices**: +- CI pipeline triggered on merge to a specific branch +- Manual approval step in CI +- Local apply by an operator +- Deployment platform's auto-deploy on push +- Not applicable + +**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. + +## Self-Declaration + +After the structured axes, ask once: "Are there any other infrastructure external resources this work depends on that the structured questions did not cover?" + +Examples that may surface only via self-declaration: state-storage backend for IaC tools, runbook documents for incident response, on-call rotation, observability dashboards, cost monitoring tools, compliance / audit logging targets. diff --git a/skills/external-resource-context/references/template.md b/skills/external-resource-context/references/template.md new file mode 100644 index 0000000..169f3b2 --- /dev/null +++ b/skills/external-resource-context/references/template.md @@ -0,0 +1,115 @@ +# Storage Templates + +Two templates: the project-tier file and the feature-tier section. + +## Project-Tier Template + +Path: `docs/project-context/external-resources.md` + +```markdown +# External Resources + +Last updated: YYYY-MM-DD + +This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. + +## Frontend + +### Design Origin +- Status: +- Source type: +- Location: +- Access method: + +### Design System +- Status: +- Source type: +- Location: +- Access method: + +### Guidelines +- Status: +- Source type: +- Location: +- Access method: + +### Visual Verification Environment +- Status: +- Tool type: +- Entry: + +## Backend + +### Database Schema Source +- Status: +- Source type: +- Location: +- Access method: + +### Migration History +- Status: +- Tool: +- Location: +- Apply trigger: + +### Secret Store +- Status: +- Service: +- Access method: + +### Background Job Infrastructure +- Status: +- Service: +- Access method: + +## API + +### API Schema Source +- Status: +- Source type: +- Location: +- Access method: + +### Mock Environment +- Status: +- Source type: +- Entry: + +### Authentication Method +- Status: +- Mechanism: +- Credential source: + +### Schema Change Process +- Status: +- Process: + +## Infrastructure + +### IaC Source +- Status: +- Tool: +- Location: +- Apply trigger: + +### Environment Configuration +- Status: +- Mechanism: +- Environments: + +### Secrets in Infrastructure +- Status: +- Mechanism: + +### Deployment Trigger +- Status: +- Mechanism: + +## Additional Resources + +Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. + +- : — — +``` + +Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md new file mode 100644 index 0000000..b096fa9 --- /dev/null +++ b/skills/recipe-front-adjust/SKILL.md @@ -0,0 +1,161 @@ +--- +name: recipe-front-adjust +description: Adjust an already-implemented UI in-session with verification against the design source +disable-model-invocation: true +--- + +**Context**: UI adjustment on already-implemented features. The verification loop (edit → check against the design source → refine) runs in the parent session. + +## Execution Pattern + +**Core Identity**: "I am a guided executor. I run the adjustment and the verification loop myself; subagents handle one-shot tasks." + +**Execution Protocol**: +1. **Delegate to subagents** (one-shot calls): ui-analyzer, work-planner, quality-fixer-frontend. +2. **Run in the parent session** (multi-step loops and user dialogs): external-resource hearing via AskUserQuestion, write-set confirmation, scale judgment, adjustment edits, verification against the design source, iteration until acceptance. +3. **Stop at every `[Stop: ...]` marker** before proceeding. + +## Initial Mandatory Tasks + +**Task Registration**: Before Step 1, register the recipe's execution flow using TaskCreate so progress is trackable. Register Steps 1-7 below as individual tasks plus a final task "Verify completion against Completion Criteria". Update status using TaskUpdate as each step starts and completes. + +## Workflow Overview + +``` +Adjustment request → external resource hearing (parent session, AskUserQuestion) + ↓ + ui-analyzer (subagent: fetch external sources + analyze code + propose candidateWriteSet) + ↓ + write-set confirmation (parent session, AskUserQuestion) + ↓ + scale judgment on confirmed write set (documentation-criteria matrix) + ↓ + ┌────────────────────┴────────────────────┐ + ↓ ↓ + (1-2 files: inline) (3-5 files: work-planner subagent → [Stop]) + ↓ ↓ + └─→ adjustment + verification (parent session) ←──┘ + ↓ + quality-fixer-frontend (subagent: typecheck/lint/test) + ↓ + commit +``` + +## Scope Boundaries + +**Included in this skill**: +- External resource hearing per the external-resource-context skill +- UI fact gathering via ui-analyzer +- Scale judgment via documentation-criteria's Creation Decision Matrix +- Optional work plan creation via work-planner +- Adjustment edits and verification against the design source (run in this session) +- Quality verification via quality-fixer-frontend +- Commit per adjustment unit + +**Responsibility Boundary**: This skill completes when the adjustment is committed and quality has passed. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. + +**Escalation Boundary**: Escalate to the full frontend design phase when the request requires PRD, UI Spec, Design Doc, new architecture, multi-screen redesign, or any ADR Creation Condition from documentation-criteria. + +Adjustment request: $ARGUMENTS + +## Execution Flow + +### Step 1: External Resource Hearing +Run the hearing protocol per the external-resource-context skill (frontend domain). + +### Step 2: UI Fact Gathering + +- Invoke **ui-analyzer** using Agent tool + - `subagent_type: "dev-workflows-frontend:ui-analyzer"` + - `description: "UI fact gathering for adjustment"` + - `prompt: "requirement_analysis: { affectedFiles: [files inferred from the adjustment request], scale: 'small', purpose: 'UI adjustment', technicalConsiderations: [] }. requirements: [adjustment request]. target_components: [components named in the request]. ui_spec_path: [path if an existing UI Spec covers the affected components, else absent]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods, and analyze the existing UI codebase. Populate candidateWriteSet[] with the files most likely to require modification."` + +### Step 3: Scale Judgment + +1. Read `candidateWriteSet[]` from ui-analyzer output. +2. Present the candidate list to the user via AskUserQuestion: "Confirmed write set for this adjustment? (a) accept high-confidence entries / (b) accept all entries / (c) edit list manually". On `c`, send a follow-up plain message asking the user to paste the edited file list, then proceed with that list. +3. Apply the Creation Decision Matrix from the documentation-criteria skill to the **confirmed write set count**: + - **0 files**: The adjustment request did not map to any existing file. Escalate to the user with the message "No write target identified from the adjustment request. Please clarify which component(s) should change, or run the full frontend design phase if this is a new feature." Stop this recipe. + - **1-2 files**: Direct adjustment, no work plan. + - **3-5 files**: Work plan required. + - **6+ files** OR any ADR Creation Condition triggered (architecture changes, contract changes affecting 3+ locations, complex multi-state logic, etc.): Adjustment scope exceeded. Escalate the user to the full frontend design phase. Stop this recipe. + +### Step 4: Plan Creation (Conditional) +Branch on the scale outcome. + +#### Branch A — 1-2 files +No work plan. Build a minimal adjustment context for the parent session: +- Adjustment request (verbatim) +- ui-analyzer focusAreas[] (raw fact_id; the `ui:` prefix is only applied when merging with codebase-analysis facts in a Fact Disposition Table, which Branch A does not do) +- Affected files list +- External resources fetched_summary and access methods that the verification loop will use + +Present the adjustment context to the user for review. +- **[STOP]**: User confirms the adjustment context covers the work. + +#### Branch B — 3-5 files +Create a right-sized work plan. Invoke **work-planner** using Agent tool: +- `subagent_type: "dev-workflows-frontend:work-planner"` +- `description: "Adjustment work plan"` +- `prompt: "Create a work plan for this UI adjustment. Adjustment request: [verbatim]. ui_analysis: [ui-analyzer JSON]. External resources: docs/project-context/external-resources.md. Scale: 3-5 files (no Design Doc, no ADR). Each phase should be implementable as 1-3 commits. Include a quality checklist matched to the affected components: visual verification, accessibility, i18n parity, generated artifact regeneration when relevant. Output path: docs/plans/[YYYYMMDD]-adjust-[short-description].md."` + +After work-planner returns: +- Present the work plan to the user. +- **[STOP]**: Wait for plan approval or revision request. If the user requests changes, re-invoke work-planner with revised guidance. + +### Step 5: Adjustment + Verification (parent session) + +For each adjustment unit (per file in Branch A; per work plan phase in Branch B): +1. **Plan the edit** based on ui-analyzer focusAreas and the relevant external resource (e.g., design origin's fetched_summary). +2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. +3. **Verify against external sources** using whichever access method `docs/project-context/external-resources.md` declares for each axis: + - Design origin: compare current rendering against the design source via the declared access method (e.g., design-tool MCP, WebFetch from a public URL, file read from a specification path) + - Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL) + - Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path) +4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. +5. When the adjustment unit converges, proceed to Step 6 for that unit. + +When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available. + +### Step 6: Quality Verification (per adjustment unit) + +- Invoke **quality-fixer-frontend** using Agent tool + - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` + - `description: "Quality verification for adjustment unit"` + - Build the prompt by branch. Scope is always `filesModified`; `task_file` (when passed) is a supplementary hint that quality-fixer-frontend may use to read the document's "Quality Assurance Mechanisms" section. + - **Branch A (1-2 files)**: omit `task_file`. Pass `filesModified: [list of files edited in this adjustment unit]`. + - **Branch B (3-5 files)**: pass `task_file: ` (supplementary hint) AND `filesModified: [list of files edited in this adjustment unit]` (primary scope). + - Example (Branch A): `prompt: "filesModified: [src/components/Card/Card.tsx, src/components/Card/Card.module.css]. Run quality checks across the listed files."` + - Example (Branch B): `prompt: "task_file: docs/plans/[plan-name].md. filesModified: [src/components/Card/Card.tsx, src/components/Card/Card.module.css]. Run quality checks across the listed files."` +- Route the quality-fixer-frontend response by `status`: + - `approved` → proceed to Step 7 + - `stub_detected` → return to Step 5 to complete the implementation for this unit, then re-invoke quality-fixer-frontend + - `blocked` → read `reason`. When `"Cannot determine due to unclear specification"`, surface `blockingIssues[]` to the user and stop. When `"Execution prerequisites not met"`, surface `missingPrerequisites[]` with `resolutionSteps` to the user and stop + +### Step 7: Commit (per adjustment unit) +Commit the adjustment unit on quality approval. Include the affected files and any regenerated artifacts (CSS module typings, message catalog typings, etc.) flagged by ui-analyzer's `generatedArtifacts` section. + +Then loop back to Step 5 for the next unit (Branch B work plan phase, or next file in Branch A) until all units are committed. + +## Completion Criteria + +- [ ] External resource hearing executed (project-tier file written or update explicitly skipped) +- [ ] ui-analyzer returned a JSON output, including externalResources fetch_status per axis and candidateWriteSet +- [ ] Write set confirmed by the user before scale judgment +- [ ] Scale judgment applied to the confirmed write set; 6+ files or ADR conditions escalated to the design phase +- [ ] Branch A: adjustment context presented and confirmed; Branch B: work plan approved +- [ ] All adjustment units edited and verified using the project's declared verification mechanism (manual confirmation when no automated mechanism is declared) +- [ ] Each adjustment unit passed quality-fixer-frontend with explicit `filesModified` scoping +- [ ] Each adjustment unit committed + +## Output Example + +``` +Frontend adjustment completed. +- External resources: docs/project-context/external-resources.md (updated|unchanged) +- UI fact gathering: ui-analyzer focused on [N] components, [M] focus areas, external sources [fetched|partial|not_recorded] +- Scale: <1-2 files | 3-5 files> +- Work plan: +- Adjustment units committed: [count] +- Quality status: all passed +``` diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index 2c18f47..36016e6 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -13,7 +13,7 @@ disable-model-invocation: true **Execution Protocol**: 1. **Delegate all work** to sub-agents — your role is to invoke sub-agents, pass data between them, and report results 2. **Follow subagents-orchestration-guide skill design flow** (this recipe covers medium/large frontend; refer to the guide for scale-specific variations): - - Execute: requirement-analyzer → codebase-analyzer → ui-spec-designer → technical-designer-frontend → code-verifier → document-reviewer → design-sync + - Execute: requirement-analyzer → external resource hearing → codebase-analyzer + ui-analyzer (parallel) → ui-spec-designer → technical-designer-frontend → code-verifier → document-reviewer → design-sync - **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval @@ -24,7 +24,11 @@ disable-model-invocation: true ``` Requirements → requirement-analyzer → [Stop: Scale determination] ↓ - codebase-analyzer → ui-spec-designer → [Stop: UI Spec approval] + external resource hearing (frontend domain) + ↓ + codebase-analyzer + ui-analyzer (parallel) + ↓ + ui-spec-designer → [Stop: UI Spec approval] ↓ technical-designer-frontend ↓ @@ -37,7 +41,8 @@ Requirements → requirement-analyzer → [Stop: Scale determination] **Included in this skill**: - Requirement analysis with requirement-analyzer -- Codebase analysis with codebase-analyzer (before technical design) +- External resource hearing per the external-resource-context skill +- Codebase analysis with codebase-analyzer and ui-analyzer in parallel (before document creation) - UI Specification creation with ui-spec-designer (prototype code inquiry included) - ADR creation (if architecture changes, new technology, or data flow changes) - Design Doc creation with technical-designer-frontend @@ -57,7 +62,7 @@ Considering the deep impact on design, first engage in dialogue to understand th - Expected outcomes and success criteria - Relationship with existing systems -Once the user has answered the three dialogue questions above, execute the process below within design scope. Follow subagents-orchestration-guide Call Examples for codebase-analyzer and code-verifier invocations. +Once the user has answered the three dialogue questions above, execute the process below within design scope. Follow subagents-orchestration-guide Call Examples for codebase-analyzer, ui-analyzer, and code-verifier invocations. - Invoke **requirement-analyzer** using Agent tool - `subagent_type: "dev-workflows-frontend:requirement-analyzer"` @@ -65,8 +70,21 @@ Once the user has answered the three dialogue questions above, execute the proce - `prompt: "Requirements: [user requirements] Execute requirement analysis and scale determination"` - **[STOP]**: Review requirement analysis results and address question items -### Step 2: UI Specification Phase -After requirement analysis approval, ask the user about prototype code: +### Step 1.5: External Resource Hearing +Run the hearing protocol per the external-resource-context skill (frontend domain). The orchestrator owns this step because it requires AskUserQuestion. The skill defines file-existence branching, two-phase hearing (structured axes + self-declaration), and persistence to `docs/project-context/external-resources.md`. + +### Step 2: UI Fact Gathering +Invoke codebase-analyzer and ui-analyzer **in parallel** (single message with two Agent tool calls). They share input but produce complementary output. ui-analyzer reads the project-tier external-resources file and fetches external UI sources via the inherited MCP/URL access methods, then analyzes the UI codebase. codebase-analyzer covers data, contracts, dependencies, and quality assurance mechanisms. + +- Invoke **codebase-analyzer** using Agent tool + - `subagent_type: "dev-workflows-frontend:codebase-analyzer"`, `description: "Codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. requirements: [user requirements]. Analyze existing codebase for frontend design guidance (data, contracts, dependencies, quality assurance mechanisms)."` +- Invoke **ui-analyzer** using Agent tool (parallel with the call above) + - `subagent_type: "dev-workflows-frontend:ui-analyzer"`, `description: "UI fact gathering"`, `prompt: "requirement_analysis: [JSON from Step 1]. requirements: [user requirements]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods, and analyze the existing UI codebase."` + +Both outputs (codebase-analyzer JSON and ui-analyzer JSON) are reused by ui-spec-designer in Step 3 and by technical-designer-frontend in Step 4. + +### Step 3: UI Specification Phase +After Step 2 outputs are received, ask the user about prototype code: **Ask the user**: "Do you have prototype code for this feature? If so, please provide the path to the code. The prototype will be placed in `docs/ui-spec/assets/` as reference material for the UI Spec." @@ -76,28 +94,26 @@ Then create the UI Specification: - Invoke **ui-spec-designer** using Agent tool - `subagent_type: "dev-workflows-frontend:ui-spec-designer"` - `description: "UI Spec creation"` - - If PRD exists and prototype provided: `prompt: "Create UI Spec from PRD at [path]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/"` - - If PRD exists and no prototype: `prompt: "Create UI Spec from PRD at [path]. No prototype code available."` - - If no PRD (medium scale): `prompt: "Create UI Spec based on the following requirements: [requirements analysis output from Step 1]. No PRD available."` (add prototype path if provided) + - Build the prompt by including: + - Source: PRD path (Large scale) or requirement-analyzer output (Medium scale) + - `ui_analysis`: ui-analyzer JSON from Step 2 (includes externalResources fetched_summary and componentStructure / propsPatterns / cssLayout / etc.) + - Prototype path when provided + - Example: `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from Step 2 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."` - Invoke **document-reviewer** to verify UI Spec - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "UI Spec review"`, `prompt: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"` - **[STOP]**: Present UI Spec for user approval -### Step 3: Design Document Creation Phase -First, analyze the existing codebase: -- Invoke **codebase-analyzer** using Agent tool - - `subagent_type: "dev-workflows-frontend:codebase-analyzer"`, `description: "Codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. requirements: [user requirements]. Analyze existing codebase for frontend design guidance."` - -Create appropriate design documents according to scale determination. technical-designer-frontend presents at least two architecture alternatives (technology selection, data flow design) with trade-offs for each: +### Step 4: Design Document Creation Phase +Create appropriate design documents according to scale determination. technical-designer-frontend presents at least two architecture alternatives (technology selection, data flow design) with trade-offs for each. Pass both Step 2 outputs: - Invoke **technical-designer-frontend** using Agent tool - For ADR: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Present at least two alternatives with trade-offs."` - - For Design Doc: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on requirements. Codebase analysis: [codebase analysis output from this step]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Present at least two architecture alternatives with trade-offs."` + - For Design Doc: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on requirements. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 2]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table. Present at least two architecture alternatives with trade-offs."` - **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-frontend:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - Invoke **document-reviewer** to verify consistency (pass code-verifier results for Design Doc; omit for ADR) - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "Document review"`, `prompt: "Review [document path] for consistency and completeness. code_verification: [code verification output from this step] (Design Doc only)"` -### Step 4: Design Consistency Verification +### Step 5: Design Consistency Verification - Invoke **design-sync** using Agent tool - `subagent_type: "dev-workflows-frontend:design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."` - **[STOP]**: Present design documents and design-sync results, obtain user approval @@ -105,9 +121,10 @@ Create appropriate design documents according to scale determination. technical- ## Completion Criteria - [ ] Executed requirement-analyzer and determined scale -- [ ] Executed codebase-analyzer and passed results to technical-designer-frontend -- [ ] Created UI Specification with ui-spec-designer (when applicable) -- [ ] Created appropriate design document (ADR or Design Doc) with technical-designer-frontend +- [ ] Executed external resource hearing per the external-resource-context skill (file written or update explicitly skipped by user) +- [ ] Executed codebase-analyzer and ui-analyzer in parallel; outputs reused by ui-spec-designer and technical-designer-frontend +- [ ] Created UI Specification with ui-spec-designer (when applicable) — its External Resources Used section is filled +- [ ] Created appropriate design document (ADR or Design Doc) with technical-designer-frontend — its External Resources Used subsection is filled when present - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification @@ -118,5 +135,3 @@ Frontend design phase completed. - UI Specification: docs/ui-spec/[feature-name]-ui-spec.md - Design document: docs/design/[document-name].md or docs/adr/[document-name].md - Approval status: User approved - - diff --git a/skills/recipe-fullstack-implement/SKILL.md b/skills/recipe-fullstack-implement/SKILL.md index 44012f1..755d2b2 100644 --- a/skills/recipe-fullstack-implement/SKILL.md +++ b/skills/recipe-fullstack-implement/SKILL.md @@ -44,31 +44,18 @@ When continuing existing flow, verify: - Current phase position (Requirements/Design/Planning/Implementation/QA) - Identify next step in monorepo-flow.md -### 3. UI Specification Phase (Frontend Layer) +### 3. Design through Planning Phase -Before creating the frontend Design Doc, create a UI Specification: +**Follow monorepo-flow.md** for the complete design-through-planning flow (Steps 1-16 for Large scale, Steps 1-14 for Medium scale). The flow table in that reference defines every step, agent invocation, parallelization rule, and stop point. -**Ask the user**: "Do you have prototype code for this feature? If so, please provide the path. The prototype will be placed in `docs/ui-spec/assets/` as reference material." - -- **[STOP]**: Wait for user response about prototype code availability - -Then invoke **ui-spec-designer**: -- `subagent_type: "dev-workflows-frontend:ui-spec-designer"` -- If prototype provided: `prompt: "Create UI Spec from PRD at [path]. Prototype code is at [user-provided path]."` -- If no prototype: `prompt: "Create UI Spec from PRD at [path]. No prototype code available."` - -Invoke **document-reviewer** for UI Spec review, then **[STOP]** for user approval. - -### 4. Design Phase and Work Planning - -**Follow monorepo-flow.md** for the complete design-through-planning flow. Key points: +Key points to enforce as the orchestrator runs the flow: - Create separate Design Docs per layer (see monorepo-flow.md "Layer Context in Design Doc Creation") -- **Frontend Design Doc must reference the approved UI Spec** (pass UI Spec path to technical-designer-frontend) +- Frontend Design Doc references the approved UI Spec (pass UI Spec path to technical-designer-frontend) and reuses the ui-analyzer output produced earlier in the flow - Execute document-reviewer once per Design Doc (separate invocations) - Run design-sync for cross-layer consistency verification - Pass all Design Docs to work-planner (subagent_type: "dev-workflows:work-planner") with vertical slicing instruction -### 5. Register All Flow Steps Using TaskCreate (MANDATORY) +### 4. Register All Flow Steps Using TaskCreate (MANDATORY) **After scale determination, register all steps of the monorepo-flow.md using TaskCreate**: - First task: "Map preloaded skills to applicable concrete rules" diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index ca2e2c1..89d7997 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -37,15 +37,16 @@ The following subagents are available: ### Document Creation Agents 6. **requirement-analyzer**: Requirement analysis and work scale determination -7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design -8. **prd-creator**: Product Requirements Document creation -9. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) -10. **technical-designer**: ADR/Design Doc creation -11. **work-planner**: Work plan creation from Design Doc and test skeletons -12. **document-reviewer**: Single document quality and rule compliance check -13. **code-verifier**: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc -14. **design-sync**: Design Doc consistency verification across multiple documents -15. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs +7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) +8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code (visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, generated UI artifacts). Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access +9. **prd-creator**: Product Requirements Document creation +10. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) +11. **technical-designer**: ADR/Design Doc creation +12. **work-planner**: Work plan creation from Design Doc and test skeletons +13. **document-reviewer**: Single document quality and rule compliance check +14. **code-verifier**: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc +15. **design-sync**: Design Doc consistency verification across multiple documents +16. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs ## Orchestration Principles @@ -167,6 +168,13 @@ Two additional rules: - description: "Codebase analysis" - prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance." +### Call Example (ui-analyzer) +- subagent_type: "ui-analyzer" +- description: "UI fact gathering" +- prompt: "requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. ui_spec_path: [path if exists]. target_components: [list if focused]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods (MCP / URL / file), and analyze the existing UI codebase. Output the consolidated UI fact JSON." + +When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase). + ### Call Example (task-executor) - subagent_type: "task-executor" - description: "Task execution" @@ -177,6 +185,7 @@ Two additional rules: Subagents respond in JSON format. Key fields for orchestrator decisions: - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions - **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations - **code-verifier**: status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) - **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain), testsAdded, requiresTestReview - **quality-fixer**: Input: `task_file` (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` → route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → discriminate by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps @@ -225,10 +234,12 @@ Always start with requirement-analyzer, then select the minimum planning flow re | Scale | Planning flow (ends at task-decomposer for Medium/Large; ends at work-planner for Small) | |-------|---------------| -| Large | requirement-analyzer → PRD → PRD review → optional UI Spec → optional ADR → codebase-analyzer → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | -| Medium | requirement-analyzer → codebase-analyzer → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | +| Large | requirement-analyzer → PRD → PRD review → external resource hearing → optional ADR → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | +| Medium | requirement-analyzer → external resource hearing → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer | | Small | requirement-analyzer → work-planner | +External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. + After the planning flow completes and the user grants batch approval, the work plan carries an `Implementation Readiness:` header (work-planner emits `pending`; promotion to `ready` or `escalated` is an external orchestration concern). External orchestration also decides when and how to act on this marker; this guide does not invoke any orchestrator above the agent layer. Then execute the task execution cycle: `task-executor → quality-fixer → commit` for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies — implementation runs through `task-executor`, not orchestrator-direct edits. diff --git a/skills/subagents-orchestration-guide/references/monorepo-flow.md b/skills/subagents-orchestration-guide/references/monorepo-flow.md index 840c9dc..5143c37 100644 --- a/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -10,47 +10,49 @@ This reference defines the orchestration flow for projects spanning multiple lay ## Design Phase -### Large Scale Fullstack (6+ Files) - 15 Steps +### Large Scale Fullstack (6+ Files) - 16 Steps | Step | Agent | Purpose | Output | |------|-------|---------|--------| | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | -| 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | -| 5 | ui-spec-designer | UI Spec from PRD + optional prototype | UI Spec | -| 6 | document-reviewer | UI Spec review **[Stop]** | Approval | -| 7 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output + PRD path, filtered to layer) | Codebase guidance per layer | -| 8 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | -| 9 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 10 as `prior_layer_verification`) | Backend verification | -| 10 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + backend Design Doc + `prior_layer_verification` from step 9 + UI Spec) | Frontend Design Doc | -| 11 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | -| 12 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | -| 13 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | -| 14 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | -| 15 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | - -### Medium Scale Fullstack (3-5 Files) - 13 Steps +| 4 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend domain primary; backend / api / infra domains as applicable for the layer scope). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | +| 5 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | +| 6 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | +| 7 | ui-spec-designer | UI Spec from PRD + optional prototype + ui-analyzer output | UI Spec | +| 8 | document-reviewer | UI Spec review **[Stop]** | Approval | +| 9 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | +| 10 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 11 as `prior_layer_verification`) | Backend verification | +| 11 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + ui-analyzer output + backend Design Doc + `prior_layer_verification` from step 10 + UI Spec) | Frontend Design Doc | +| 12 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | +| 13 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | +| 14 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | +| 15 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | +| 16 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | + +### Medium Scale Fullstack (3-5 Files) - 14 Steps | Step | Agent | Purpose | Output | |------|-------|---------|--------| | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | -| 2 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output, filtered to layer) | Codebase guidance per layer | -| 3 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | -| 4 | ui-spec-designer | UI Spec from requirements + optional prototype | UI Spec | -| 5 | document-reviewer | UI Spec review **[Stop]** | Approval | -| 6 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | -| 7 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 8 as `prior_layer_verification`) | Backend verification | -| 8 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + backend Design Doc + `prior_layer_verification` from step 7 + UI Spec) | Frontend Design Doc | -| 9 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | -| 10 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | -| 11 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | -| 12 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | -| 13 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | +| 2 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend / backend / api / infra domains as applicable). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | +| 3 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | +| 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | +| 5 | ui-spec-designer | UI Spec from requirements + optional prototype + ui-analyzer output | UI Spec | +| 6 | document-reviewer | UI Spec review **[Stop]** | Approval | +| 7 | technical-designer | **Backend** Design Doc (with backend codebase-analyzer context) | Backend Design Doc | +| 8 | code-verifier | Verify **Backend** Design Doc against existing code (its result JSON is passed to step 9 as `prior_layer_verification`) | Backend verification | +| 9 | technical-designer-frontend | **Frontend** Design Doc (with frontend codebase-analyzer context + ui-analyzer output + backend Design Doc + `prior_layer_verification` from step 8 + UI Spec) | Frontend Design Doc | +| 10 | code-verifier | Verify **Frontend** Design Doc against existing code | Frontend verification | +| 11 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as `code_verification`) | Reviews | +| 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | +| 13 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | +| 14 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan | ### Parallelization in Multi-Agent Steps -Steps marked with ×2 (codebase-analyzer ×2, document-reviewer ×2) invoke the agent once per layer. These invocations are independent and can run in parallel when the orchestrator supports concurrent Agent tool calls. The two code-verifier invocations run sequentially: backend verification completes before frontend authoring begins so the frontend designer references verified backend contracts. +Steps marked with ×2 (codebase-analyzer ×2, document-reviewer ×2) invoke the agent once per layer. The combined codebase-analyzer ×2 + ui-analyzer step invokes three subagents in parallel — the two codebase-analyzer calls (one per layer) and the single ui-analyzer call — when the orchestrator supports concurrent Agent tool calls. The two code-verifier invocations run sequentially: backend verification completes before frontend authoring begins so the frontend designer references verified backend contracts. ### Layer Context in Design Doc Creation @@ -72,10 +74,12 @@ Focus on: API contracts, data layer, business logic, service architecture. ```text Create a frontend Design Doc from [PRD path or requirement_analysis]. Codebase analysis: [JSON from codebase-analyzer for frontend layer] +UI analysis: [JSON from ui-analyzer] Backend Design Doc: [path] prior_layer_verification: [JSON from code-verifier on backend Design Doc] Reference UI Spec at [path] for component structure and state design. Use `prior_layer_verification.discrepancies[]` as known issues to address or escalate. Do not infer verified claims beyond what the verifier output states explicitly. +Apply `code:` prefix to fact_ids from codebase-analyzer and `ui:` prefix to fact_ids from ui-analyzer when filling the Fact Disposition Table. Focus on: component hierarchy, state management, UI interactions, data fetching. ``` diff --git a/skills/task-analyzer/references/skills-index.yaml b/skills/task-analyzer/references/skills-index.yaml index 856c1e8..cbf84cb 100644 --- a/skills/task-analyzer/references/skills-index.yaml +++ b/skills/task-analyzer/references/skills-index.yaml @@ -214,3 +214,26 @@ skills: - "Situations Requiring Technical Decisions" - "Implementation Completeness Assurance" - "Impact Analysis" + + # Cross-Cutting Skills + external-resource-context: + skill: "external-resource-context" + tags: [cross-cutting, hearing-protocol, design-source, design-system, api-schema, iac-source, secrets, environment, two-tier-storage] + typical-use: "Captures access methods for resources outside the repository (design origin, design system, API schema, IaC source, secrets, etc.) and persists them in a deterministic location for downstream agents" + size: medium + key-references: + - "references/frontend.md" + - "references/backend.md" + - "references/api.md" + - "references/infra.md" + - "references/template.md" + sections: + - "Purpose" + - "Scope Boundaries" + - "Storage Locations (Two-Tier)" + - "Hearing Protocol" + - "Storage Protocol" + - "Reference Protocol (For Downstream Consumers)" + - "Output Format" + - "Quality Checklist" + - "References" diff --git a/skills/test-implement/references/e2e.md b/skills/test-implement/references/e2e.md index 47cdbe5..ec89f32 100644 --- a/skills/test-implement/references/e2e.md +++ b/skills/test-implement/references/e2e.md @@ -2,7 +2,7 @@ ## Lane Selection -E2E tests in this workflow split into two lanes (defined in integration-e2e-testing skill): +E2E tests in this workflow split into two lanes: | Lane | Backend setup | Use these patterns | |------|---------------|-------------------| @@ -225,7 +225,7 @@ Before service-integration-e2e tests can pass, verify: - [ ] Environment variables are set (`E2E_*` prefixed) - [ ] External services are either available or stubbed -When the work plan includes dedicated environment setup tasks (Phase 0 — see work-planner E2E Environment Prerequisites extraction), follow those tasks. When no setup tasks exist in the plan, address missing prerequisites as part of the test implementation task itself, OR consider whether the verification could move to fixture-e2e instead. +When the work plan includes dedicated environment setup tasks (Phase 0; see the work plan's E2E Environment Prerequisites section), follow those tasks. When no setup tasks exist in the plan, address missing prerequisites as part of the test implementation task itself, OR consider whether the verification could move to fixture-e2e instead. ## Locator Strategy