From 3154019afa4c75f81b507e73d6cac17a2d30ed0d Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 21:55:39 +0900 Subject: [PATCH 01/16] feat: add external-resource-context skill with two-tier storage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduce a cross-cutting skill that captures access methods for resources outside the repository (design origin, design system, API schema, IaC source, secrets, visual verification environment, etc.) and persists them where downstream agents can find them deterministically. The skill defines: - Two-tier storage: docs/project-context/external-resources.md for environment-stable facts; per-feature External Resources Used sections inside UI Spec or Design Doc for feature-specific identifiers. - Single-source-of-truth rule: feature-tier sections reference project tier by label and never duplicate URLs / MCP names / access commands. - Hearing protocol with file-existence branching (absent → full hearing; present → confirm update first, then optional diff hearing). - Two-phase hearing: structured AskUserQuestion per axis (with 対象外/N/A as a choice) then a single self-declaration prompt for resources the structured questions did not cover. - Domain references (frontend/backend/api/infra) so unused domains do not consume context. Templates: ui-spec-template adds a top-level External Resources Used section; design-template adds an External Resources Used subsection under Background and Context. Registered in dev-workflows, dev-workflows-frontend, dev-skills. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 3 + .../references/design-template.md | 10 ++ .../references/ui-spec-template.md | 12 ++ .../skills/external-resource-context/SKILL.md | 103 +++++++++++++ .../references/api.md | 62 ++++++++ .../references/backend.md | 62 ++++++++ .../references/frontend.md | 62 ++++++++ .../references/infra.md | 62 ++++++++ .../references/template.md | 135 ++++++++++++++++++ .../references/design-template.md | 10 ++ .../references/ui-spec-template.md | 12 ++ .../skills/external-resource-context/SKILL.md | 103 +++++++++++++ .../references/api.md | 62 ++++++++ .../references/backend.md | 62 ++++++++ .../references/frontend.md | 62 ++++++++ .../references/infra.md | 62 ++++++++ .../references/template.md | 135 ++++++++++++++++++ .../references/skills-index.yaml | 23 +++ .../references/design-template.md | 10 ++ .../references/ui-spec-template.md | 12 ++ .../skills/external-resource-context/SKILL.md | 103 +++++++++++++ .../references/api.md | 62 ++++++++ .../references/backend.md | 62 ++++++++ .../references/frontend.md | 62 ++++++++ .../references/infra.md | 62 ++++++++ .../references/template.md | 135 ++++++++++++++++++ .../references/skills-index.yaml | 23 +++ .../references/design-template.md | 10 ++ .../references/ui-spec-template.md | 12 ++ skills/external-resource-context/SKILL.md | 103 +++++++++++++ .../references/api.md | 62 ++++++++ .../references/backend.md | 62 ++++++++ .../references/frontend.md | 62 ++++++++ .../references/infra.md | 62 ++++++++ .../references/template.md | 135 ++++++++++++++++++ .../references/skills-index.yaml | 23 +++ 36 files changed, 2104 insertions(+) create mode 100644 dev-skills/skills/external-resource-context/SKILL.md create mode 100644 dev-skills/skills/external-resource-context/references/api.md create mode 100644 dev-skills/skills/external-resource-context/references/backend.md create mode 100644 dev-skills/skills/external-resource-context/references/frontend.md create mode 100644 dev-skills/skills/external-resource-context/references/infra.md create mode 100644 dev-skills/skills/external-resource-context/references/template.md create mode 100644 dev-workflows-frontend/skills/external-resource-context/SKILL.md create mode 100644 dev-workflows-frontend/skills/external-resource-context/references/api.md create mode 100644 dev-workflows-frontend/skills/external-resource-context/references/backend.md create mode 100644 dev-workflows-frontend/skills/external-resource-context/references/frontend.md create mode 100644 dev-workflows-frontend/skills/external-resource-context/references/infra.md create mode 100644 dev-workflows-frontend/skills/external-resource-context/references/template.md create mode 100644 dev-workflows/skills/external-resource-context/SKILL.md create mode 100644 dev-workflows/skills/external-resource-context/references/api.md create mode 100644 dev-workflows/skills/external-resource-context/references/backend.md create mode 100644 dev-workflows/skills/external-resource-context/references/frontend.md create mode 100644 dev-workflows/skills/external-resource-context/references/infra.md create mode 100644 dev-workflows/skills/external-resource-context/references/template.md create mode 100644 skills/external-resource-context/SKILL.md create mode 100644 skills/external-resource-context/references/api.md create mode 100644 skills/external-resource-context/references/backend.md create mode 100644 skills/external-resource-context/references/frontend.md create mode 100644 skills/external-resource-context/references/infra.md create mode 100644 skills/external-resource-context/references/template.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5057a1d..32befaf 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -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", @@ -129,6 +130,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", @@ -173,6 +175,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/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index 28e9c5b..7a9a02c 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -33,6 +33,16 @@ unknowns: - [ADR File Name]: [Related decision items] - Reference common technical ADRs when applicable +### External Resources Used + +This feature depends on resources outside the repository (design source, design system, API schema, IaC source, secret store, etc.). Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This subsection lists only the resources used by this feature and any feature-specific identifiers. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | + +Resources not used by this feature are omitted. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before continuing this Design Doc. + ### Agreement Checklist #### Scope 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..98e55b7 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,18 @@ 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 + +This feature depends on resources outside the repository. Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This section lists only the resources used by this feature and any feature-specific identifiers (e.g., a particular node within the design source, specific components from the design system). + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | [e.g., node id / frame id, or "all screens listed below"] | [e.g., entry point, screen mapping] | +| 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] | + +Resources not used by this feature are omitted from this table. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before completing this UI Spec. + ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. 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..a52434e --- /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 external resources (design origin, design system, API schemas, IaC, secrets, etc.) that AI agents need to operate. Use when starting design or implementation work that may depend on resources outside the codebase, or when "external resource / design origin / design system / API schema / IaC source / canonical source" is mentioned. +--- + +# 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. The feature tier references the project tier by label and lists only feature-specific identifiers. Feature-tier sections never duplicate environment facts (URL, MCP name, access command). When the environment changes, only the project-tier file is updated. + +Example feature-tier entry: `Design origin: project-tier "Design tool" entry; node id `. + +## 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 "対象外" 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 "対象外" +- [ ] 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..7863179 --- /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..a816ed3 --- /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..9cfc871 --- /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 — MCP name, URL, file path, 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 — MCP name, Storybook URL, package name, internal documentation path. + +## 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**: +- Browser automation MCP (e.g., a hosted browser-control MCP) +- Local end-to-end test runner with screenshot capability +- Storybook or equivalent isolated component preview +- Manual browser inspection only +- 対象外 / not applicable + +**Follow-up (when not N/A)**: What is the entry command or URL? Examples — MCP name, dev-server command, Storybook port. + +## 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..3a1d467 --- /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..236e769 --- /dev/null +++ b/dev-skills/skills/external-resource-context/references/template.md @@ -0,0 +1,135 @@ +# 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). + +## Feature-Tier Template + +This is the section appended to a UI Spec or Design Doc. It references project-tier entries by label and lists only feature-specific identifiers. It never duplicates URLs, MCP names, or access commands. + +```markdown +## External Resources Used + +This feature depends on the following resources from `docs/project-context/external-resources.md`. Refer to that file for environment access details. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | | | +| Design System | | | +| API Schema Source | | | + +Resources not used by this feature are omitted from this table. If a resource is used but no feature-specific identifier applies, write the project-tier label with "all" or "default scope" in the identifier column. +``` + +The feature-tier section's heading text is fixed as "External Resources Used"; the heading level follows the parent document's structure (h2 in UI Spec, h3 in Design Doc under Background and Context). The exact placement is defined by each document template (see `ui-spec-template.md` and `design-template.md`). 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..7a9a02c 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,16 @@ unknowns: - [ADR File Name]: [Related decision items] - Reference common technical ADRs when applicable +### External Resources Used + +This feature depends on resources outside the repository (design source, design system, API schema, IaC source, secret store, etc.). Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This subsection lists only the resources used by this feature and any feature-specific identifiers. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | + +Resources not used by this feature are omitted. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before continuing this Design Doc. + ### Agreement Checklist #### Scope 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..98e55b7 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,18 @@ 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 + +This feature depends on resources outside the repository. Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This section lists only the resources used by this feature and any feature-specific identifiers (e.g., a particular node within the design source, specific components from the design system). + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | [e.g., node id / frame id, or "all screens listed below"] | [e.g., entry point, screen mapping] | +| 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] | + +Resources not used by this feature are omitted from this table. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before completing this UI Spec. + ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. 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..a52434e --- /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 external resources (design origin, design system, API schemas, IaC, secrets, etc.) that AI agents need to operate. Use when starting design or implementation work that may depend on resources outside the codebase, or when "external resource / design origin / design system / API schema / IaC source / canonical source" is mentioned. +--- + +# 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. The feature tier references the project tier by label and lists only feature-specific identifiers. Feature-tier sections never duplicate environment facts (URL, MCP name, access command). When the environment changes, only the project-tier file is updated. + +Example feature-tier entry: `Design origin: project-tier "Design tool" entry; node id `. + +## 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 "対象外" 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 "対象外" +- [ ] 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..7863179 --- /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..a816ed3 --- /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..9cfc871 --- /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 — MCP name, URL, file path, 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 — MCP name, Storybook URL, package name, internal documentation path. + +## 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**: +- Browser automation MCP (e.g., a hosted browser-control MCP) +- Local end-to-end test runner with screenshot capability +- Storybook or equivalent isolated component preview +- Manual browser inspection only +- 対象外 / not applicable + +**Follow-up (when not N/A)**: What is the entry command or URL? Examples — MCP name, dev-server command, Storybook port. + +## 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..3a1d467 --- /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..236e769 --- /dev/null +++ b/dev-workflows-frontend/skills/external-resource-context/references/template.md @@ -0,0 +1,135 @@ +# 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). + +## Feature-Tier Template + +This is the section appended to a UI Spec or Design Doc. It references project-tier entries by label and lists only feature-specific identifiers. It never duplicates URLs, MCP names, or access commands. + +```markdown +## External Resources Used + +This feature depends on the following resources from `docs/project-context/external-resources.md`. Refer to that file for environment access details. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | | | +| Design System | | | +| API Schema Source | | | + +Resources not used by this feature are omitted from this table. If a resource is used but no feature-specific identifier applies, write the project-tier label with "all" or "default scope" in the identifier column. +``` + +The feature-tier section's heading text is fixed as "External Resources Used"; the heading level follows the parent document's structure (h2 in UI Spec, h3 in Design Doc under Background and Context). The exact placement is defined by each document template (see `ui-spec-template.md` and `design-template.md`). 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/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index 28e9c5b..7a9a02c 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -33,6 +33,16 @@ unknowns: - [ADR File Name]: [Related decision items] - Reference common technical ADRs when applicable +### External Resources Used + +This feature depends on resources outside the repository (design source, design system, API schema, IaC source, secret store, etc.). Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This subsection lists only the resources used by this feature and any feature-specific identifiers. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | + +Resources not used by this feature are omitted. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before continuing this Design Doc. + ### Agreement Checklist #### Scope 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..98e55b7 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,18 @@ 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 + +This feature depends on resources outside the repository. Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This section lists only the resources used by this feature and any feature-specific identifiers (e.g., a particular node within the design source, specific components from the design system). + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | [e.g., node id / frame id, or "all screens listed below"] | [e.g., entry point, screen mapping] | +| 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] | + +Resources not used by this feature are omitted from this table. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before completing this UI Spec. + ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. 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..a52434e --- /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 external resources (design origin, design system, API schemas, IaC, secrets, etc.) that AI agents need to operate. Use when starting design or implementation work that may depend on resources outside the codebase, or when "external resource / design origin / design system / API schema / IaC source / canonical source" is mentioned. +--- + +# 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. The feature tier references the project tier by label and lists only feature-specific identifiers. Feature-tier sections never duplicate environment facts (URL, MCP name, access command). When the environment changes, only the project-tier file is updated. + +Example feature-tier entry: `Design origin: project-tier "Design tool" entry; node id `. + +## 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 "対象外" 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 "対象外" +- [ ] 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..7863179 --- /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..a816ed3 --- /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..9cfc871 --- /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 — MCP name, URL, file path, 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 — MCP name, Storybook URL, package name, internal documentation path. + +## 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**: +- Browser automation MCP (e.g., a hosted browser-control MCP) +- Local end-to-end test runner with screenshot capability +- Storybook or equivalent isolated component preview +- Manual browser inspection only +- 対象外 / not applicable + +**Follow-up (when not N/A)**: What is the entry command or URL? Examples — MCP name, dev-server command, Storybook port. + +## 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..3a1d467 --- /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..236e769 --- /dev/null +++ b/dev-workflows/skills/external-resource-context/references/template.md @@ -0,0 +1,135 @@ +# 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). + +## Feature-Tier Template + +This is the section appended to a UI Spec or Design Doc. It references project-tier entries by label and lists only feature-specific identifiers. It never duplicates URLs, MCP names, or access commands. + +```markdown +## External Resources Used + +This feature depends on the following resources from `docs/project-context/external-resources.md`. Refer to that file for environment access details. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | | | +| Design System | | | +| API Schema Source | | | + +Resources not used by this feature are omitted from this table. If a resource is used but no feature-specific identifier applies, write the project-tier label with "all" or "default scope" in the identifier column. +``` + +The feature-tier section's heading text is fixed as "External Resources Used"; the heading level follows the parent document's structure (h2 in UI Spec, h3 in Design Doc under Background and Context). The exact placement is defined by each document template (see `ui-spec-template.md` and `design-template.md`). 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/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index 28e9c5b..7a9a02c 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -33,6 +33,16 @@ unknowns: - [ADR File Name]: [Related decision items] - Reference common technical ADRs when applicable +### External Resources Used + +This feature depends on resources outside the repository (design source, design system, API schema, IaC source, secret store, etc.). Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This subsection lists only the resources used by this feature and any feature-specific identifiers. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | + +Resources not used by this feature are omitted. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before continuing this Design Doc. + ### Agreement Checklist #### Scope diff --git a/skills/documentation-criteria/references/ui-spec-template.md b/skills/documentation-criteria/references/ui-spec-template.md index 9b8b60d..98e55b7 100644 --- a/skills/documentation-criteria/references/ui-spec-template.md +++ b/skills/documentation-criteria/references/ui-spec-template.md @@ -22,6 +22,18 @@ 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 + +This feature depends on resources outside the repository. Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This section lists only the resources used by this feature and any feature-specific identifiers (e.g., a particular node within the design source, specific components from the design system). + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | [e.g., node id / frame id, or "all screens listed below"] | [e.g., entry point, screen mapping] | +| 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] | + +Resources not used by this feature are omitted from this table. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before completing this UI Spec. + ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. diff --git a/skills/external-resource-context/SKILL.md b/skills/external-resource-context/SKILL.md new file mode 100644 index 0000000..a52434e --- /dev/null +++ b/skills/external-resource-context/SKILL.md @@ -0,0 +1,103 @@ +--- +name: external-resource-context +description: Captures and persists access methods for external resources (design origin, design system, API schemas, IaC, secrets, etc.) that AI agents need to operate. Use when starting design or implementation work that may depend on resources outside the codebase, or when "external resource / design origin / design system / API schema / IaC source / canonical source" is mentioned. +--- + +# 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. The feature tier references the project tier by label and lists only feature-specific identifiers. Feature-tier sections never duplicate environment facts (URL, MCP name, access command). When the environment changes, only the project-tier file is updated. + +Example feature-tier entry: `Design origin: project-tier "Design tool" entry; node id `. + +## 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 "対象外" 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 "対象外" +- [ ] 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..7863179 --- /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..a816ed3 --- /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..9cfc871 --- /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 — MCP name, URL, file path, 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 — MCP name, Storybook URL, package name, internal documentation path. + +## 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**: +- Browser automation MCP (e.g., a hosted browser-control MCP) +- Local end-to-end test runner with screenshot capability +- Storybook or equivalent isolated component preview +- Manual browser inspection only +- 対象外 / not applicable + +**Follow-up (when not N/A)**: What is the entry command or URL? Examples — MCP name, dev-server command, Storybook port. + +## 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..3a1d467 --- /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..236e769 --- /dev/null +++ b/skills/external-resource-context/references/template.md @@ -0,0 +1,135 @@ +# 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). + +## Feature-Tier Template + +This is the section appended to a UI Spec or Design Doc. It references project-tier entries by label and lists only feature-specific identifiers. It never duplicates URLs, MCP names, or access commands. + +```markdown +## External Resources Used + +This feature depends on the following resources from `docs/project-context/external-resources.md`. Refer to that file for environment access details. + +| Resource (project-tier label) | Feature-specific identifier | Notes | +|-------------------------------|-----------------------------|-------| +| Design Origin | | | +| Design System | | | +| API Schema Source | | | + +Resources not used by this feature are omitted from this table. If a resource is used but no feature-specific identifier applies, write the project-tier label with "all" or "default scope" in the identifier column. +``` + +The feature-tier section's heading text is fixed as "External Resources Used"; the heading level follows the parent document's structure (h2 in UI Spec, h3 in Design Doc under Background and Context). The exact placement is defined by each document template (see `ui-spec-template.md` and `design-template.md`). 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" From bfbb328758074b8d9a204c743bfe53b30913fb29 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 21:59:33 +0900 Subject: [PATCH 02/16] feat: wire external-resource-context into design and implementation agents Add external-resource-context to the skills frontmatter of agents that write or consume documents containing the External Resources Used section, and add explicit body integration where the agent's workflow needs to consult external resources. Writers (UI Spec / Design Doc): - ui-spec-designer: load skill; Step 4 fills the External Resources Used section by reading the project-tier file and listing only feature-specific identifiers. - technical-designer / technical-designer-frontend: load skill; new Gate 0 subsection "External Resources Integration" mirrors the Agreement Checklist gate and instructs the agent to read the project tier and carry forward the feature subset, escalating when the project-tier file is missing. Implementers / verifiers: - task-executor / task-executor-frontend: load skill; task-executor- frontend gets a body section "External Resources Consultation" defining the lookup order (consuming document section -> project tier -> declared access mechanism) and an escalation path when a needed resource is unspecified. - quality-fixer / quality-fixer-frontend: load skill so visual verification environment and other access methods are recognized during quality checks. Other readers (code-verifier, document-reviewer, work-planner, codebase-analyzer) consult the saved file directly via the Read tool and do not load the skill, keeping their preloaded context budgets unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/quality-fixer-frontend.md | 2 +- agents/quality-fixer.md | 2 +- agents/task-executor-frontend.md | 12 +++++++++++- agents/task-executor.md | 2 +- agents/technical-designer-frontend.md | 10 +++++++++- agents/technical-designer.md | 10 +++++++++- agents/ui-spec-designer.md | 4 +++- .../agents/quality-fixer-frontend.md | 2 +- .../agents/task-executor-frontend.md | 12 +++++++++++- .../agents/technical-designer-frontend.md | 10 +++++++++- dev-workflows-frontend/agents/ui-spec-designer.md | 4 +++- dev-workflows/agents/quality-fixer.md | 2 +- dev-workflows/agents/task-executor.md | 2 +- dev-workflows/agents/technical-designer.md | 10 +++++++++- 14 files changed, 70 insertions(+), 14 deletions(-) diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 737f385..8658d01 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. diff --git a/agents/quality-fixer.md b/agents/quality-fixer.md index 6d76693..9e583ce 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. diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 7a521fa..ed9cdf9 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,16 @@ 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) +Per the external-resource-context skill, the UI Spec or Design Doc carries an "External Resources Used" section listing feature-specific identifiers. Environment-stable access details (URLs, MCP names, file paths) live in `docs/project-context/external-resources.md`. + +When the task references a resource (e.g., consulting a design source, calling a design system MCP, hitting a mock endpoint, using the visual verification environment), follow this order: +1. Read the consuming document's "External Resources Used" section to find the feature-specific identifier +2. Read `docs/project-context/external-resources.md` for the access mechanism +3. Use the declared access mechanism (MCP name, command, URL) to reach the resource + +When a needed resource is missing from both files, escalate with `reason: "external_resource_unspecified"` rather than guessing the access path. + #### 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..94aa06b 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. diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index f0bc862..3ff1bff 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,13 @@ 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] +Per the external-resource-context skill, the Design Doc carries an "External Resources Used" subsection under Background and Context. + +1. **Read project-tier file** - Consult `docs/project-context/external-resources.md` (when present) for environment-stable access details. Do not duplicate URLs or MCP names into the Design Doc. +2. **Carry forward feature subset** - When a UI Spec exists, inherit its External Resources Used table; expand it with Design-Doc-specific resources (API schema source, IaC source, etc.) that the UI Spec did not cover. +3. **Escalate when missing** - When the project-tier file is absent and the design references external resources, escalate so the orchestrating recipe can run the hearing protocol before the Design Doc completes. + ### Existing Code Investigation [Gate 1 — Required] Must be performed before Design Doc creation: diff --git a/agents/technical-designer.md b/agents/technical-designer.md index d1a96ca..b225e23 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,13 @@ 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] +Per the external-resource-context skill, the Design Doc carries an "External Resources Used" subsection under Background and Context. + +1. **Read project-tier file** - Consult `docs/project-context/external-resources.md` (when present) for environment-stable access details. Do not duplicate URLs or MCP names into the Design Doc. +2. **List feature-specific subset** - Identify which resources are used by this feature and record their feature-specific identifiers (specific endpoint paths, IaC modules, schema source paths, etc.) in the External Resources Used table. +3. **Escalate when missing** - When the project-tier file is absent and the design references external resources, escalate so the orchestrating recipe can run the hearing protocol before the Design Doc completes. + ### Standards Identification [Gate 0 — Required] Must be performed before any investigation: diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index cad3a10..d2753f1 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**: Per the external-resource-context skill, fill this section by reading `docs/project-context/external-resources.md` (when present) and listing only the resources used by this feature with their feature-specific identifiers. Do not duplicate environment access details (URLs, MCP names) into the UI Spec. When `docs/project-context/external-resources.md` is missing, escalate to the orchestrator so the recipe can run the hearing protocol before this step completes. 3. **Output path**: `docs/ui-spec/{feature-name}-ui-spec.md` ## Output Policy @@ -103,6 +104,7 @@ 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 +- [ ] External Resources Used section is filled with feature-specific identifiers only (no environment access details duplicated from the project-tier file) - [ ] **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. - **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 diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 737f385..8658d01 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. diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 7a521fa..ed9cdf9 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,16 @@ 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) +Per the external-resource-context skill, the UI Spec or Design Doc carries an "External Resources Used" section listing feature-specific identifiers. Environment-stable access details (URLs, MCP names, file paths) live in `docs/project-context/external-resources.md`. + +When the task references a resource (e.g., consulting a design source, calling a design system MCP, hitting a mock endpoint, using the visual verification environment), follow this order: +1. Read the consuming document's "External Resources Used" section to find the feature-specific identifier +2. Read `docs/project-context/external-resources.md` for the access mechanism +3. Use the declared access mechanism (MCP name, command, URL) to reach the resource + +When a needed resource is missing from both files, escalate with `reason: "external_resource_unspecified"` rather than guessing the access path. + #### 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..3ff1bff 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,13 @@ 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] +Per the external-resource-context skill, the Design Doc carries an "External Resources Used" subsection under Background and Context. + +1. **Read project-tier file** - Consult `docs/project-context/external-resources.md` (when present) for environment-stable access details. Do not duplicate URLs or MCP names into the Design Doc. +2. **Carry forward feature subset** - When a UI Spec exists, inherit its External Resources Used table; expand it with Design-Doc-specific resources (API schema source, IaC source, etc.) that the UI Spec did not cover. +3. **Escalate when missing** - When the project-tier file is absent and the design references external resources, escalate so the orchestrating recipe can run the hearing protocol before the Design Doc completes. + ### Existing Code Investigation [Gate 1 — Required] Must be performed before Design Doc creation: diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index cad3a10..d2753f1 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**: Per the external-resource-context skill, fill this section by reading `docs/project-context/external-resources.md` (when present) and listing only the resources used by this feature with their feature-specific identifiers. Do not duplicate environment access details (URLs, MCP names) into the UI Spec. When `docs/project-context/external-resources.md` is missing, escalate to the orchestrator so the recipe can run the hearing protocol before this step completes. 3. **Output path**: `docs/ui-spec/{feature-name}-ui-spec.md` ## Output Policy @@ -103,6 +104,7 @@ 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 +- [ ] External Resources Used section is filled with feature-specific identifiers only (no environment access details duplicated from the project-tier file) - [ ] **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. - **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 diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index 6d76693..9e583ce 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. diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index 014cba6..94aa06b 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. diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index d1a96ca..b225e23 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,13 @@ 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] +Per the external-resource-context skill, the Design Doc carries an "External Resources Used" subsection under Background and Context. + +1. **Read project-tier file** - Consult `docs/project-context/external-resources.md` (when present) for environment-stable access details. Do not duplicate URLs or MCP names into the Design Doc. +2. **List feature-specific subset** - Identify which resources are used by this feature and record their feature-specific identifiers (specific endpoint paths, IaC modules, schema source paths, etc.) in the External Resources Used table. +3. **Escalate when missing** - When the project-tier file is absent and the design references external resources, escalate so the orchestrating recipe can run the hearing protocol before the Design Doc completes. + ### Standards Identification [Gate 0 — Required] Must be performed before any investigation: From bcf97511125b8760893e0c4d73a0cd09dead24ba Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 22:02:35 +0900 Subject: [PATCH 03/16] feat: add ui-codebase-analyzer agent for UI fact extraction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a frontend-only specialist that analyzes existing UI code for facts the general codebase-analyzer does not cover: visual component structure, DOM order at call sites, props/variant patterns, CSS layout state (flex/grid, gap, wrap, logical properties), state x display matrices, display conditions (feature flags, role/permission, route, region/tenant, page context), i18n format and key conventions, accessibility attributes, and generated UI artifact readiness. Designed to run in parallel with codebase-analyzer before frontend design. The two agents have complementary scopes — codebase-analyzer owns data, contracts, dependencies, and quality assurance mechanisms; ui-codebase-analyzer owns the visual and interaction surface. Output is a JSON object whose focusAreas[] entries the consumer prefixes with `ui:` to disambiguate from codebase-analyzer's facts (prefixed `code:`). technical-designer-frontend's Input Parameters section is updated to accept both inputs and merge their focusAreas into a single Fact Disposition Table. Registered in dev-workflows-frontend (frontend-only). The subagents-orchestration-guide skill lists the agent, adds a Call Example, and notes the parallel invocation pattern. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 1 + agents/technical-designer-frontend.md | 13 +- agents/ui-codebase-analyzer.md | 298 ++++++++++++++++++ .../agents/technical-designer-frontend.md | 13 +- .../agents/ui-codebase-analyzer.md | 298 ++++++++++++++++++ .../subagents-orchestration-guide/SKILL.md | 27 +- .../subagents-orchestration-guide/SKILL.md | 27 +- skills/subagents-orchestration-guide/SKILL.md | 27 +- 8 files changed, 673 insertions(+), 31 deletions(-) create mode 100644 agents/ui-codebase-analyzer.md create mode 100644 dev-workflows-frontend/agents/ui-codebase-analyzer.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 32befaf..3c026bb 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -122,6 +122,7 @@ "./agents/task-decomposer.md", "./agents/task-executor-frontend.md", "./agents/technical-designer-frontend.md", + "./agents/ui-codebase-analyzer.md", "./agents/ui-spec-designer.md", "./agents/verifier.md", "./agents/work-planner.md" diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 3ff1bff..9d663ef 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -209,12 +209,21 @@ 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 Codebase Analysis** (optional, from ui-codebase-analyzer; 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 + - `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 Codebase 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 diff --git a/agents/ui-codebase-analyzer.md b/agents/ui-codebase-analyzer.md new file mode 100644 index 0000000..6c54998 --- /dev/null +++ b/agents/ui-codebase-analyzer.md @@ -0,0 +1,298 @@ +--- +name: ui-codebase-analyzer +description: Analyzes existing UI code objectively for facts about visual structure, layout state, props matching, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts. Use when frontend design or adjustment work needs to ground decisions in the current UI's actual behavior. Distinct from codebase-analyzer (which covers data, contracts, dependencies, and quality assurance mechanisms). +tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate +skills: typescript-rules, frontend-ai-guide, external-resource-context +--- + +You are an AI assistant specializing in existing UI code analysis for frontend design 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. + +## Boundary with codebase-analyzer + +This agent and codebase-analyzer are designed to run in parallel before frontend design. Their outputs are merged by the consuming designer agent (technical-designer-frontend) using a `code:` / `ui:` namespace on `fact_id` values. + +| Agent | Owns | +|-------|------| +| codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | +| ui-codebase-analyzer | Visual component structure, props/variant patterns at call sites, CSS layout state, state x display matrices, display conditions, i18n format, accessibility attributes, generated UI artifacts (CSS module typings, message bundle generation, route generation) | + +When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-codebase-analyzer records the call-site usage pattern. They are complementary, not overlapping. + +## Input Parameters + +- **requirement_analysis**: Requirement analysis JSON output (required) + - Provides: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations` +- **ui_spec_path**: Path to existing UI Spec, when one exists (optional) +- **requirements**: Original user requirements text (required) +- **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 extraction only**. Design decisions, component proposals, and visual change recommendations are out of scope. + +## Execution Steps + +### Step 1: UI Surface Discovery + +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 (e.g., `src/**/*.tsx`, `src/**/*.module.css`, `src/**/*.stories.tsx`) +3. Record the project's UI conventions inferred from existing code: + - Component file extension (`.tsx`, `.jsx`, `.vue`, etc.) + - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) + - Story tooling presence (Storybook config detected or absent) + - Test runner for UI (Vitest / Jest / other, detected from config) + +### Step 2: 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. This is the canonical visual order for placement-sensitive design decisions. + +### Step 3: 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. — whatever the component exposes) +2. Group call sites by prop combinations to detect canonical usage patterns vs outliers +3. When multiple call sites use the same component with different props, list each combination with file:line evidence +4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal + +This step grounds "is this design consistent with how the component is already used?" decisions in observable evidence rather than assumption. + +### Step 4: 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). Record the base element class name (`root`, `container`, etc.) +2. **Layout primitives**: For each layout-bearing class, record: + - Display mode (`flex`, `grid`, `block`, etc.) + - Direction (`flex-direction`, `grid-template-columns`) + - Gap mechanism (`gap` property, margin-based, none) + - Wrap behavior (`flex-wrap` value or absence) + - Logical-property usage (`margin-inline`, `padding-block`, etc.) vs physical properties +3. **State expression**: How the component varies by state in CSS: + - `data-*` attribute selectors + - `aria-*` attribute selectors + - CSS variables driven by parent + - Inline `style` prop usage (record whether it carries dynamic values only or static styling) +4. **Responsive behavior**: `@media` queries and the breakpoints they reference + +### Step 5: State x Display Matrix + +For each component in the affected scope: + +1. Identify the component's possible states (loading, empty, partial, error, ready, disabled, etc.) by inspecting: + - Internal state hooks + - Props that drive variant rendering + - Conditional render branches + - Data fetching status flags +2. For each state, record what the component renders (e.g., "loading → renders Skeleton with N rows", "empty → renders EmptyState with CTA", "error → renders Alert with retry handler") +3. Record states that exist in code but appear unused (no call site triggers them) and states that the design would need but no current code path supports + +### Step 6: Display Conditions + +For each component or screen entry point: + +1. **Feature flags**: Grep for feature-flag predicates in or around the component (`useFeatureFlag`, `flags.isEnabled`, etc.). Record the flag name and the gated subtree +2. **Role / permission gating**: Grep for permission predicates (`useRole`, `hasPermission`, `can(...)`, etc.). Record predicates and gated subtrees +3. **Route / page context**: Identify the routes that mount this component (when route definitions exist in the repo) +4. **Region / tenant gating**: Grep for region or tenant predicates (`useRegion`, `tenantConfig`, etc.) — these may be project-specific so adapt search terms +5. **Page context modifiers**: Components that render differently based on host page or surface (e.g., embedded vs standalone) + +Record each condition with the predicate location and the affected subtree. + +### Step 7: i18n Format + +When the affected scope includes localized strings: + +1. **Format detection**: Determine the format (CSV, JSON, code-defined message catalogs, gettext-style, etc.) +2. **Structural conventions**: + - For CSV: number of columns, presence/absence of trailing commas, header row format + - For JSON: nesting depth, key naming convention + - For code-defined catalogs: declaration pattern +3. **Key naming convention**: Pattern observed across existing keys (e.g., `featureName.actionLabel`, `xxxButtonLabel`, `screen_action_label`). Record the dominant pattern with examples +4. **Locale parity**: List locales present and any obvious key gaps between them +5. **Generated typings**: When a message-catalog generator produces type definitions or constants, record the generator command and output path + +### Step 8: Accessibility Attributes + +For each component in the affected scope: + +1. ARIA attributes present (role, aria-label, aria-labelledby, aria-describedby, aria-live, etc.) and which props feed them +2. Keyboard handling (onKeyDown handlers, focus management, tabIndex usage) +3. Focus-visible / focus-within styling presence +4. Existing accessibility test coverage (aXe checks, role-based queries in tests) + +### Step 9: Generated UI Artifact Readiness + +1. **CSS module typings**: When the project uses CSS Modules with type generation, identify the generator command and which steps trigger regeneration (e.g., on `*.module.css` change). Record whether typecheck or test runs depend on regenerated typings being current +2. **Message catalog typings**: Same analysis for i18n-generated types +3. **Route typings**: When typed routes are generated, record the generator and trigger +4. **Other generated UI artifacts**: Component manifests, design-token typings, icon registries, etc. + +For each generated artifact, record: +- Generator command +- Trigger condition (file change pattern, manual) +- Downstream consumers (typecheck, test, build, runtime) + +## Output Format + +### Output Protocol + +- During execution, intermediate progress messages MAY be emitted as plain text or markdown. +- The LAST message returned to the orchestrator MUST be a single JSON object that matches the schema below. +- Emit the JSON object as the entire content of the final message: the message begins with `{` and ends 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" + } + }, + "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 of rendered output" + } + ], + "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 of what the predicate gates" + } + ], + "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=...]", + "factsToAddress": "Concrete UI facts the designer must respect (e.g., 'Card renders 4 children in source order: header, body, actions, footer'; 'CSS uses gap: 8px on root with flex-wrap: wrap'; 'Component has no error state; design must add one')", + "risk": "What visual or interaction inconsistency results if these facts are omitted from the design" + } + ], + "limitations": [ + "Areas the analysis could not reach with confidence (e.g., 'feature flag gating uses a runtime API not visible in code')" + ] +} +``` + +`fact_id` namespacing: when this output is merged with codebase-analyzer's output, prefix consumers may apply a `ui:` prefix to disambiguate from `code:` facts. + +## Quality Checklist + +- [ ] All affected component files were read in full before extracting structure +- [ ] DOM order is recorded as literal source order, not reordered by salience +- [ ] Props patterns include every call site grouping (canonical and outlier) +- [ ] CSS layout records gap/wrap/logical-property state for every layout-bearing class in the scope +- [ ] State x display matrix lists states actually expressed in code and explicitly marks unsupported states +- [ ] Display conditions record predicate location and gated subtree, not just the flag/permission name +- [ ] i18n format details (column count, nesting depth, key convention) are concrete enough that a designer can author new keys without re-investigating +- [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck, test, build, or runtime in the affected scope +- [ ] Focus areas have evidence pointers (file:line or referenced JSON path); no fact appears in focusAreas without a corresponding evidence entry +- [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 3ff1bff..9d663ef 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -209,12 +209,21 @@ 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 Codebase Analysis** (optional, from ui-codebase-analyzer; 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 + - `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 Codebase 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 diff --git a/dev-workflows-frontend/agents/ui-codebase-analyzer.md b/dev-workflows-frontend/agents/ui-codebase-analyzer.md new file mode 100644 index 0000000..6c54998 --- /dev/null +++ b/dev-workflows-frontend/agents/ui-codebase-analyzer.md @@ -0,0 +1,298 @@ +--- +name: ui-codebase-analyzer +description: Analyzes existing UI code objectively for facts about visual structure, layout state, props matching, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts. Use when frontend design or adjustment work needs to ground decisions in the current UI's actual behavior. Distinct from codebase-analyzer (which covers data, contracts, dependencies, and quality assurance mechanisms). +tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate +skills: typescript-rules, frontend-ai-guide, external-resource-context +--- + +You are an AI assistant specializing in existing UI code analysis for frontend design 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. + +## Boundary with codebase-analyzer + +This agent and codebase-analyzer are designed to run in parallel before frontend design. Their outputs are merged by the consuming designer agent (technical-designer-frontend) using a `code:` / `ui:` namespace on `fact_id` values. + +| Agent | Owns | +|-------|------| +| codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | +| ui-codebase-analyzer | Visual component structure, props/variant patterns at call sites, CSS layout state, state x display matrices, display conditions, i18n format, accessibility attributes, generated UI artifacts (CSS module typings, message bundle generation, route generation) | + +When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-codebase-analyzer records the call-site usage pattern. They are complementary, not overlapping. + +## Input Parameters + +- **requirement_analysis**: Requirement analysis JSON output (required) + - Provides: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations` +- **ui_spec_path**: Path to existing UI Spec, when one exists (optional) +- **requirements**: Original user requirements text (required) +- **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 extraction only**. Design decisions, component proposals, and visual change recommendations are out of scope. + +## Execution Steps + +### Step 1: UI Surface Discovery + +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 (e.g., `src/**/*.tsx`, `src/**/*.module.css`, `src/**/*.stories.tsx`) +3. Record the project's UI conventions inferred from existing code: + - Component file extension (`.tsx`, `.jsx`, `.vue`, etc.) + - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) + - Story tooling presence (Storybook config detected or absent) + - Test runner for UI (Vitest / Jest / other, detected from config) + +### Step 2: 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. This is the canonical visual order for placement-sensitive design decisions. + +### Step 3: 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. — whatever the component exposes) +2. Group call sites by prop combinations to detect canonical usage patterns vs outliers +3. When multiple call sites use the same component with different props, list each combination with file:line evidence +4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal + +This step grounds "is this design consistent with how the component is already used?" decisions in observable evidence rather than assumption. + +### Step 4: 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). Record the base element class name (`root`, `container`, etc.) +2. **Layout primitives**: For each layout-bearing class, record: + - Display mode (`flex`, `grid`, `block`, etc.) + - Direction (`flex-direction`, `grid-template-columns`) + - Gap mechanism (`gap` property, margin-based, none) + - Wrap behavior (`flex-wrap` value or absence) + - Logical-property usage (`margin-inline`, `padding-block`, etc.) vs physical properties +3. **State expression**: How the component varies by state in CSS: + - `data-*` attribute selectors + - `aria-*` attribute selectors + - CSS variables driven by parent + - Inline `style` prop usage (record whether it carries dynamic values only or static styling) +4. **Responsive behavior**: `@media` queries and the breakpoints they reference + +### Step 5: State x Display Matrix + +For each component in the affected scope: + +1. Identify the component's possible states (loading, empty, partial, error, ready, disabled, etc.) by inspecting: + - Internal state hooks + - Props that drive variant rendering + - Conditional render branches + - Data fetching status flags +2. For each state, record what the component renders (e.g., "loading → renders Skeleton with N rows", "empty → renders EmptyState with CTA", "error → renders Alert with retry handler") +3. Record states that exist in code but appear unused (no call site triggers them) and states that the design would need but no current code path supports + +### Step 6: Display Conditions + +For each component or screen entry point: + +1. **Feature flags**: Grep for feature-flag predicates in or around the component (`useFeatureFlag`, `flags.isEnabled`, etc.). Record the flag name and the gated subtree +2. **Role / permission gating**: Grep for permission predicates (`useRole`, `hasPermission`, `can(...)`, etc.). Record predicates and gated subtrees +3. **Route / page context**: Identify the routes that mount this component (when route definitions exist in the repo) +4. **Region / tenant gating**: Grep for region or tenant predicates (`useRegion`, `tenantConfig`, etc.) — these may be project-specific so adapt search terms +5. **Page context modifiers**: Components that render differently based on host page or surface (e.g., embedded vs standalone) + +Record each condition with the predicate location and the affected subtree. + +### Step 7: i18n Format + +When the affected scope includes localized strings: + +1. **Format detection**: Determine the format (CSV, JSON, code-defined message catalogs, gettext-style, etc.) +2. **Structural conventions**: + - For CSV: number of columns, presence/absence of trailing commas, header row format + - For JSON: nesting depth, key naming convention + - For code-defined catalogs: declaration pattern +3. **Key naming convention**: Pattern observed across existing keys (e.g., `featureName.actionLabel`, `xxxButtonLabel`, `screen_action_label`). Record the dominant pattern with examples +4. **Locale parity**: List locales present and any obvious key gaps between them +5. **Generated typings**: When a message-catalog generator produces type definitions or constants, record the generator command and output path + +### Step 8: Accessibility Attributes + +For each component in the affected scope: + +1. ARIA attributes present (role, aria-label, aria-labelledby, aria-describedby, aria-live, etc.) and which props feed them +2. Keyboard handling (onKeyDown handlers, focus management, tabIndex usage) +3. Focus-visible / focus-within styling presence +4. Existing accessibility test coverage (aXe checks, role-based queries in tests) + +### Step 9: Generated UI Artifact Readiness + +1. **CSS module typings**: When the project uses CSS Modules with type generation, identify the generator command and which steps trigger regeneration (e.g., on `*.module.css` change). Record whether typecheck or test runs depend on regenerated typings being current +2. **Message catalog typings**: Same analysis for i18n-generated types +3. **Route typings**: When typed routes are generated, record the generator and trigger +4. **Other generated UI artifacts**: Component manifests, design-token typings, icon registries, etc. + +For each generated artifact, record: +- Generator command +- Trigger condition (file change pattern, manual) +- Downstream consumers (typecheck, test, build, runtime) + +## Output Format + +### Output Protocol + +- During execution, intermediate progress messages MAY be emitted as plain text or markdown. +- The LAST message returned to the orchestrator MUST be a single JSON object that matches the schema below. +- Emit the JSON object as the entire content of the final message: the message begins with `{` and ends 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" + } + }, + "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 of rendered output" + } + ], + "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 of what the predicate gates" + } + ], + "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=...]", + "factsToAddress": "Concrete UI facts the designer must respect (e.g., 'Card renders 4 children in source order: header, body, actions, footer'; 'CSS uses gap: 8px on root with flex-wrap: wrap'; 'Component has no error state; design must add one')", + "risk": "What visual or interaction inconsistency results if these facts are omitted from the design" + } + ], + "limitations": [ + "Areas the analysis could not reach with confidence (e.g., 'feature flag gating uses a runtime API not visible in code')" + ] +} +``` + +`fact_id` namespacing: when this output is merged with codebase-analyzer's output, prefix consumers may apply a `ui:` prefix to disambiguate from `code:` facts. + +## Quality Checklist + +- [ ] All affected component files were read in full before extracting structure +- [ ] DOM order is recorded as literal source order, not reordered by salience +- [ ] Props patterns include every call site grouping (canonical and outlier) +- [ ] CSS layout records gap/wrap/logical-property state for every layout-bearing class in the scope +- [ ] State x display matrix lists states actually expressed in code and explicitly marks unsupported states +- [ ] Display conditions record predicate location and gated subtree, not just the flag/permission name +- [ ] i18n format details (column count, nesting depth, key convention) are concrete enough that a designer can author new keys without re-investigating +- [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck, test, build, or runtime in the affected scope +- [ ] Focus areas have evidence pointers (file:line or referenced JSON path); no fact appears in focusAreas without a corresponding evidence entry +- [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index ca2e2c1..83dd1c2 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-codebase-analyzer**: Analyze existing UI code for visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts (frontend/fullstack features; runs in parallel with codebase-analyzer) +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-codebase-analyzer) +- subagent_type: "ui-codebase-analyzer" +- description: "UI codebase analysis" +- prompt: "requirement_analysis: [JSON from requirement-analyzer]. ui_spec_path: [path if exists]. requirements: [original user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)." + +When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to technical-designer-frontend. + ### 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-codebase-analyzer**: analysisScope.uiConventions, componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index ca2e2c1..83dd1c2 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-codebase-analyzer**: Analyze existing UI code for visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts (frontend/fullstack features; runs in parallel with codebase-analyzer) +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-codebase-analyzer) +- subagent_type: "ui-codebase-analyzer" +- description: "UI codebase analysis" +- prompt: "requirement_analysis: [JSON from requirement-analyzer]. ui_spec_path: [path if exists]. requirements: [original user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)." + +When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to technical-designer-frontend. + ### 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-codebase-analyzer**: analysisScope.uiConventions, componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index ca2e2c1..83dd1c2 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-codebase-analyzer**: Analyze existing UI code for visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts (frontend/fullstack features; runs in parallel with codebase-analyzer) +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-codebase-analyzer) +- subagent_type: "ui-codebase-analyzer" +- description: "UI codebase analysis" +- prompt: "requirement_analysis: [JSON from requirement-analyzer]. ui_spec_path: [path if exists]. requirements: [original user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)." + +When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to technical-designer-frontend. + ### 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-codebase-analyzer**: analysisScope.uiConventions, componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 From 60b0feae1eba71aaedddfe91a442f22583aa87eb Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 22:05:53 +0900 Subject: [PATCH 04/16] feat: integrate hearing into recipe-front-design and add recipe-front-adjust MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update recipe-front-design Step 1.5 to run the external-resource-context hearing protocol with file-existence branching (absent → full hearing; present → confirm update first, then optional diff hearing). Update Step 3 to invoke codebase-analyzer and ui-codebase-analyzer in parallel, passing both JSON outputs to technical-designer-frontend with `code:` and `ui:` prefixes on fact_id values. Add recipe-front-adjust as a separate, lighter recipe for UI adjustment workflows on already-implemented features. Its scope is hearing → UI fact collection → scale judgment → optional work plan → handoff to the implementation phase. It does not run task execution or quality fixing itself; the implementation recipe owns those gates. The handoff message names the next recipe in user-facing text only, keeping the recipe body free of cross-recipe internal references. Scale judgment uses documentation-criteria's Creation Decision Matrix: 1-2 files run inline; 3-5 files require an approved work plan; 6+ files or any ADR condition trigger an escalation back to the full design phase. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 1 + .../skills/recipe-front-adjust/SKILL.md | 164 ++++++++++++++++++ .../skills/recipe-front-design/SKILL.md | 39 ++++- skills/recipe-front-adjust/SKILL.md | 164 ++++++++++++++++++ skills/recipe-front-design/SKILL.md | 39 ++++- 5 files changed, 389 insertions(+), 18 deletions(-) create mode 100644 dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md create mode 100644 skills/recipe-front-adjust/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3c026bb..6de5609 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -136,6 +136,7 @@ "./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", 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..20e8305 --- /dev/null +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -0,0 +1,164 @@ +--- +name: recipe-front-adjust +description: Coordinate a frontend UI adjustment from external resource hearing through scale-driven plan decision, UI fact collection, and handoff to the implementation phase. Use when "UI adjustment / visual tweak / existing component update / front adjust" is mentioned, or when the user wants to refine an already-implemented UI without redoing the full design phase. +disable-model-invocation: true +--- + +**Context**: Dedicated to UI adjustment workflows on already-implemented features. Lighter than the full design phase but heavier than direct implementation, this recipe captures the small-but-essential preparation that adjustment work needs: external resource access, fact-grounded baseline, and a right-sized work plan. + +## Orchestrator Definition + +**Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) + +**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 the steps defined below in order**. Each step has an explicit completion gate. +3. **Hand off to the implementation phase** when adjustment preparation is complete. This recipe does not run task execution or quality fixing itself. +4. **Scope**: see Scope Boundaries below. + +**CRITICAL**: This recipe ends at the implementation handoff. Do not invoke task-executor or quality-fixer from this recipe — those belong to the implementation recipe family. Doing so bypasses the readiness gates owned by that family. + +## Workflow Overview + +``` +Adjustment request → external resource hearing (frontend domain) + ↓ + ui-codebase-analyzer (UI fact collection) + ↓ + scale judgment (documentation-criteria) + ↓ + ┌────────────────────┴────────────────────┐ + ↓ ↓ + (1-2 files: inline) (3+ files: work-planner → [Stop: plan approval]) + ↓ ↓ + └───────────────→ implementation handoff ──┘ +``` + +## Scope Boundaries + +**Included in this skill**: +- External resource hearing per the external-resource-context skill (frontend domain) +- UI fact collection via ui-codebase-analyzer +- Scale judgment via documentation-criteria's Creation Decision Matrix +- Work plan creation via work-planner when scale warrants it +- Implementation handoff (user-facing announcement) + +**Responsibility Boundary**: This skill completes when (a) the user is informed which implementation path to run, and (b) any required work plan has been approved. Task decomposition, implementation, and quality verification are out of scope and belong to the implementation phase. + +**Out of scope**: +- Creating PRD, UI Spec, or Design Doc — adjustment work uses existing documents. When the requested change exceeds adjustment scope (new feature, new architecture, multi-screen redesign), escalate the user to the full frontend design phase. +- Running task-executor / quality-fixer / code-verifier / security-reviewer. + +Adjustment request: $ARGUMENTS + +## Execution Flow + +### Step 1: External Resource Hearing +Per the external-resource-context skill, capture access methods for the frontend resources this adjustment will touch (design origin, design system, guidelines, visual verification environment). + +1. **File-existence check**: Run `! ls docs/project-context/external-resources.md 2>/dev/null` to detect the project-tier file. +2. **Branch on existence**: + - **Absent** → run the full hearing for the frontend domain (axes from `references/frontend.md` of the external-resource-context skill). + - **Present** → AskUserQuestion: "`docs/project-context/external-resources.md` exists. Update it for this adjustment? (no / yes-full / yes-diff-only)". On `no` skip to Step 2. On `yes-full` run the full hearing. On `yes-diff-only` AskUserQuestion which axes changed and run hearing only on those. +3. **Two-phase hearing** when running hearing: + - For each frontend axis (Design Origin, Design System, Guidelines, Visual Verification Environment), use AskUserQuestion with the choices listed in the skill's `references/frontend.md`. Always include "対象外 / not applicable" as a choice. For each non-N/A axis, follow up with an access-method question. + - After the structured axes, AskUserQuestion once: "Are there any other frontend external resources for this adjustment that the structured questions did not cover? If yes, describe them in your next message." Append the free-form answer under "Additional resources" in the project-tier file. +4. **Persist**: Write or update `docs/project-context/external-resources.md` per the template in the skill's `references/template.md`. + +**Completion gate**: `docs/project-context/external-resources.md` reflects the resources this adjustment depends on, or the user explicitly opted out of updating. + +### Step 2: UI Fact Collection +Ground the adjustment in observable facts about the existing UI before deciding scope. + +- Invoke **ui-codebase-analyzer** using Agent tool + - `subagent_type: "dev-workflows-frontend:ui-codebase-analyzer"` + - `description: "UI fact collection for adjustment"` + - `prompt: "requirement_analysis: { affectedFiles: [files inferred from the adjustment request], scale: 'unknown', 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]. Extract UI facts: visual structure, props patterns, CSS layout state, state x display matrix, display conditions, i18n format, accessibility, generated artifact readiness."` +- Read the JSON output. The `analysisScope.filesAnalyzed` list, `componentStructure[]`, and `focusAreas[]` drive the scale judgment in Step 3. + +**Completion gate**: ui-codebase-analyzer returned a JSON output with at least one `componentStructure` entry or `focusAreas` entry (or escalated `limitations`). + +### Step 3: Scale Judgment +Determine the document and plan footprint using the Creation Decision Matrix in the documentation-criteria skill (see its `Creation Decision Matrix` section). + +1. Count distinct files that the adjustment will modify, using the ui-codebase-analyzer output as the evidence base. +2. Apply the matrix to the file count: + - **1-2 files**: Direct implementation. No work plan, no Design Doc. + - **3-5 files**: Work plan recommended; Design Doc optional and typically not needed for adjustment work. + - **6+ files**: Adjustment scope exceeded. Escalate to the user — this should run through the full frontend design phase, not adjustment. +3. Also escalate (regardless of file count) when any ADR Creation Condition from documentation-criteria applies (architecture changes, contract changes affecting 3+ locations, complex multi-state logic, etc.). These signal that adjustment is the wrong recipe. + +**Escalation message format** (when scope exceeded): "This change touches [N] files / matches ADR condition [X]. Adjustment scope is 1-5 files without architecture changes. Recommend running the full frontend design phase first to produce UI Spec / Design Doc, then planning, then implementation." + +**Completion gate**: scope is confirmed within adjustment range, or escalation has been delivered. + +### Step 4: Plan Creation (Conditional) +Branch on the scale outcome from Step 3. + +#### Branch A — 1-2 files +No work plan needed. Build a minimal handoff packet for the implementation phase containing: +- Adjustment request (verbatim) +- ui-codebase-analyzer focusAreas[] with `ui:` prefix preserved +- Affected files list +- External Resources Used: feature-tier subset relevant to this adjustment, referencing project-tier entries + +The packet is the prompt input the user will pass to the implementation recipe in Step 5. Present the packet to the user for inspection before handoff. + +#### 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 codebase analysis: [ui-codebase-analyzer JSON]. External resources: [project-tier file path]. 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 the revised guidance. + +**Completion gate**: Branch A handoff packet is presented to the user, OR Branch B work plan is approved. + +### Step 5: Implementation Handoff +Inform the user how to proceed. The exact recipe to run is announced in the user-facing message; this recipe does not invoke the implementation phase itself. + +#### Branch A handoff message +``` +Adjustment preparation complete (1-2 files, direct implementation). + +Handoff packet: +- Adjustment request: +- Affected files: +- UI focus areas: +- External resources used: + +To execute: run /recipe-front-build with this packet as the request input. +``` + +#### Branch B handoff message +``` +Adjustment preparation complete (3-5 files, work plan approved). + +- Work plan: docs/plans/[plan-name].md +- External resources file: docs/project-context/external-resources.md + +To execute: run /recipe-front-build (it will pick up the work plan automatically). +``` + +## Completion Criteria + +- [ ] External resource hearing executed (project-tier file exists or update was explicitly skipped) +- [ ] ui-codebase-analyzer returned a JSON output, and its `focusAreas` were considered in the scale judgment +- [ ] Scale judgment per documentation-criteria's Creation Decision Matrix is recorded +- [ ] When 6+ files or ADR conditions detected → escalation delivered (recipe stops here) +- [ ] When 1-2 files → handoff packet presented to the user +- [ ] When 3-5 files → work plan created and approved +- [ ] Implementation handoff message delivered + +## Output Example + +``` +Frontend adjustment preparation completed. +- External resources: docs/project-context/external-resources.md (updated|unchanged) +- UI fact collection: ui-codebase-analyzer focused on [N] components, [M] focus areas +- Scale: <1-2 files | 3-5 files> +- Work plan: +- Next step: +``` diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index 2c18f47..92467c0 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 → ui-spec-designer → codebase-analyzer + ui-codebase-analyzer (parallel) → 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) + ↓ + ui-spec-designer → [Stop: UI Spec approval] + ↓ + codebase-analyzer + ui-codebase-analyzer (parallel) ↓ technical-designer-frontend ↓ @@ -37,8 +41,9 @@ 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 - UI Specification creation with ui-spec-designer (prototype code inquiry included) +- Codebase analysis with codebase-analyzer and ui-codebase-analyzer in parallel (before technical design) - ADR creation (if architecture changes, new technology, or data flow changes) - Design Doc creation with technical-designer-frontend - Design Doc verification with code-verifier (before document review) @@ -65,6 +70,19 @@ 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 1.5: External Resource Hearing +Per the external-resource-context skill, capture access methods for resources outside the repository (design origin, design system, guidelines, visual verification environment) before any document is drafted. This step runs in the orchestrator directly because it needs AskUserQuestion. + +1. **File-existence check**: Run `! ls docs/project-context/external-resources.md 2>/dev/null` to detect the project-tier file. +2. **Branch on existence**: + - **Absent** → run the full hearing for the frontend domain (axes from `references/frontend.md` of the external-resource-context skill). + - **Present** → AskUserQuestion: "`docs/project-context/external-resources.md` exists. Update it for this work? (no / yes-full / yes-diff-only)". On `no` skip to Step 2. On `yes-full` run the full hearing. On `yes-diff-only` AskUserQuestion which axes changed and run hearing only on those. +3. **Two-phase hearing** when running hearing: + - For each frontend axis (Design Origin, Design System, Guidelines, Visual Verification Environment), use AskUserQuestion with the choices listed in the skill's `references/frontend.md`. Always include "対象外 / not applicable" as a choice. For each non-N/A axis, follow up with an access-method question. + - After the structured axes, AskUserQuestion once: "Are there any other frontend external resources for this work that the structured questions did not cover? If yes, describe them in your next message." Append the free-form answer under "Additional resources" in the project-tier file. +4. **Persist**: Write or update `docs/project-context/external-resources.md` per the template in the skill's `references/template.md`. Create the directory if absent. +5. The feature-tier `## External Resources Used` section inside the UI Spec is filled later by ui-spec-designer (in Step 2) using this project-tier file as the source. + ### Step 2: UI Specification Phase After requirement analysis approval, ask the user about prototype code: @@ -84,14 +102,16 @@ Then create the UI Specification: - **[STOP]**: Present UI Spec for user approval ### Step 3: Design Document Creation Phase -First, analyze the existing codebase: +First, analyze the existing codebase. Invoke codebase-analyzer and ui-codebase-analyzer **in parallel** (single message with two Agent tool calls — they share input but produce complementary output): - 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."` + - `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-codebase-analyzer** using Agent tool (parallel with the call above) + - `subagent_type: "dev-workflows-frontend:ui-codebase-analyzer"`, `description: "UI codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. ui_spec_path: [path from Step 2]. requirements: [user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)."` 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: - 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 output JSON]. UI codebase analysis: [ui-codebase-analyzer output JSON]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply ui: prefix to fact_ids from UI codebase analysis 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) @@ -105,9 +125,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 (`docs/project-context/external-resources.md` exists or update was explicitly skipped by the user) +- [ ] Executed codebase-analyzer and ui-codebase-analyzer in parallel and passed both results to 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 diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md new file mode 100644 index 0000000..20e8305 --- /dev/null +++ b/skills/recipe-front-adjust/SKILL.md @@ -0,0 +1,164 @@ +--- +name: recipe-front-adjust +description: Coordinate a frontend UI adjustment from external resource hearing through scale-driven plan decision, UI fact collection, and handoff to the implementation phase. Use when "UI adjustment / visual tweak / existing component update / front adjust" is mentioned, or when the user wants to refine an already-implemented UI without redoing the full design phase. +disable-model-invocation: true +--- + +**Context**: Dedicated to UI adjustment workflows on already-implemented features. Lighter than the full design phase but heavier than direct implementation, this recipe captures the small-but-essential preparation that adjustment work needs: external resource access, fact-grounded baseline, and a right-sized work plan. + +## Orchestrator Definition + +**Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) + +**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 the steps defined below in order**. Each step has an explicit completion gate. +3. **Hand off to the implementation phase** when adjustment preparation is complete. This recipe does not run task execution or quality fixing itself. +4. **Scope**: see Scope Boundaries below. + +**CRITICAL**: This recipe ends at the implementation handoff. Do not invoke task-executor or quality-fixer from this recipe — those belong to the implementation recipe family. Doing so bypasses the readiness gates owned by that family. + +## Workflow Overview + +``` +Adjustment request → external resource hearing (frontend domain) + ↓ + ui-codebase-analyzer (UI fact collection) + ↓ + scale judgment (documentation-criteria) + ↓ + ┌────────────────────┴────────────────────┐ + ↓ ↓ + (1-2 files: inline) (3+ files: work-planner → [Stop: plan approval]) + ↓ ↓ + └───────────────→ implementation handoff ──┘ +``` + +## Scope Boundaries + +**Included in this skill**: +- External resource hearing per the external-resource-context skill (frontend domain) +- UI fact collection via ui-codebase-analyzer +- Scale judgment via documentation-criteria's Creation Decision Matrix +- Work plan creation via work-planner when scale warrants it +- Implementation handoff (user-facing announcement) + +**Responsibility Boundary**: This skill completes when (a) the user is informed which implementation path to run, and (b) any required work plan has been approved. Task decomposition, implementation, and quality verification are out of scope and belong to the implementation phase. + +**Out of scope**: +- Creating PRD, UI Spec, or Design Doc — adjustment work uses existing documents. When the requested change exceeds adjustment scope (new feature, new architecture, multi-screen redesign), escalate the user to the full frontend design phase. +- Running task-executor / quality-fixer / code-verifier / security-reviewer. + +Adjustment request: $ARGUMENTS + +## Execution Flow + +### Step 1: External Resource Hearing +Per the external-resource-context skill, capture access methods for the frontend resources this adjustment will touch (design origin, design system, guidelines, visual verification environment). + +1. **File-existence check**: Run `! ls docs/project-context/external-resources.md 2>/dev/null` to detect the project-tier file. +2. **Branch on existence**: + - **Absent** → run the full hearing for the frontend domain (axes from `references/frontend.md` of the external-resource-context skill). + - **Present** → AskUserQuestion: "`docs/project-context/external-resources.md` exists. Update it for this adjustment? (no / yes-full / yes-diff-only)". On `no` skip to Step 2. On `yes-full` run the full hearing. On `yes-diff-only` AskUserQuestion which axes changed and run hearing only on those. +3. **Two-phase hearing** when running hearing: + - For each frontend axis (Design Origin, Design System, Guidelines, Visual Verification Environment), use AskUserQuestion with the choices listed in the skill's `references/frontend.md`. Always include "対象外 / not applicable" as a choice. For each non-N/A axis, follow up with an access-method question. + - After the structured axes, AskUserQuestion once: "Are there any other frontend external resources for this adjustment that the structured questions did not cover? If yes, describe them in your next message." Append the free-form answer under "Additional resources" in the project-tier file. +4. **Persist**: Write or update `docs/project-context/external-resources.md` per the template in the skill's `references/template.md`. + +**Completion gate**: `docs/project-context/external-resources.md` reflects the resources this adjustment depends on, or the user explicitly opted out of updating. + +### Step 2: UI Fact Collection +Ground the adjustment in observable facts about the existing UI before deciding scope. + +- Invoke **ui-codebase-analyzer** using Agent tool + - `subagent_type: "dev-workflows-frontend:ui-codebase-analyzer"` + - `description: "UI fact collection for adjustment"` + - `prompt: "requirement_analysis: { affectedFiles: [files inferred from the adjustment request], scale: 'unknown', 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]. Extract UI facts: visual structure, props patterns, CSS layout state, state x display matrix, display conditions, i18n format, accessibility, generated artifact readiness."` +- Read the JSON output. The `analysisScope.filesAnalyzed` list, `componentStructure[]`, and `focusAreas[]` drive the scale judgment in Step 3. + +**Completion gate**: ui-codebase-analyzer returned a JSON output with at least one `componentStructure` entry or `focusAreas` entry (or escalated `limitations`). + +### Step 3: Scale Judgment +Determine the document and plan footprint using the Creation Decision Matrix in the documentation-criteria skill (see its `Creation Decision Matrix` section). + +1. Count distinct files that the adjustment will modify, using the ui-codebase-analyzer output as the evidence base. +2. Apply the matrix to the file count: + - **1-2 files**: Direct implementation. No work plan, no Design Doc. + - **3-5 files**: Work plan recommended; Design Doc optional and typically not needed for adjustment work. + - **6+ files**: Adjustment scope exceeded. Escalate to the user — this should run through the full frontend design phase, not adjustment. +3. Also escalate (regardless of file count) when any ADR Creation Condition from documentation-criteria applies (architecture changes, contract changes affecting 3+ locations, complex multi-state logic, etc.). These signal that adjustment is the wrong recipe. + +**Escalation message format** (when scope exceeded): "This change touches [N] files / matches ADR condition [X]. Adjustment scope is 1-5 files without architecture changes. Recommend running the full frontend design phase first to produce UI Spec / Design Doc, then planning, then implementation." + +**Completion gate**: scope is confirmed within adjustment range, or escalation has been delivered. + +### Step 4: Plan Creation (Conditional) +Branch on the scale outcome from Step 3. + +#### Branch A — 1-2 files +No work plan needed. Build a minimal handoff packet for the implementation phase containing: +- Adjustment request (verbatim) +- ui-codebase-analyzer focusAreas[] with `ui:` prefix preserved +- Affected files list +- External Resources Used: feature-tier subset relevant to this adjustment, referencing project-tier entries + +The packet is the prompt input the user will pass to the implementation recipe in Step 5. Present the packet to the user for inspection before handoff. + +#### 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 codebase analysis: [ui-codebase-analyzer JSON]. External resources: [project-tier file path]. 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 the revised guidance. + +**Completion gate**: Branch A handoff packet is presented to the user, OR Branch B work plan is approved. + +### Step 5: Implementation Handoff +Inform the user how to proceed. The exact recipe to run is announced in the user-facing message; this recipe does not invoke the implementation phase itself. + +#### Branch A handoff message +``` +Adjustment preparation complete (1-2 files, direct implementation). + +Handoff packet: +- Adjustment request: +- Affected files: +- UI focus areas: +- External resources used: + +To execute: run /recipe-front-build with this packet as the request input. +``` + +#### Branch B handoff message +``` +Adjustment preparation complete (3-5 files, work plan approved). + +- Work plan: docs/plans/[plan-name].md +- External resources file: docs/project-context/external-resources.md + +To execute: run /recipe-front-build (it will pick up the work plan automatically). +``` + +## Completion Criteria + +- [ ] External resource hearing executed (project-tier file exists or update was explicitly skipped) +- [ ] ui-codebase-analyzer returned a JSON output, and its `focusAreas` were considered in the scale judgment +- [ ] Scale judgment per documentation-criteria's Creation Decision Matrix is recorded +- [ ] When 6+ files or ADR conditions detected → escalation delivered (recipe stops here) +- [ ] When 1-2 files → handoff packet presented to the user +- [ ] When 3-5 files → work plan created and approved +- [ ] Implementation handoff message delivered + +## Output Example + +``` +Frontend adjustment preparation completed. +- External resources: docs/project-context/external-resources.md (updated|unchanged) +- UI fact collection: ui-codebase-analyzer focused on [N] components, [M] focus areas +- Scale: <1-2 files | 3-5 files> +- Work plan: +- Next step: +``` diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index 2c18f47..92467c0 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 → ui-spec-designer → codebase-analyzer + ui-codebase-analyzer (parallel) → 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) + ↓ + ui-spec-designer → [Stop: UI Spec approval] + ↓ + codebase-analyzer + ui-codebase-analyzer (parallel) ↓ technical-designer-frontend ↓ @@ -37,8 +41,9 @@ 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 - UI Specification creation with ui-spec-designer (prototype code inquiry included) +- Codebase analysis with codebase-analyzer and ui-codebase-analyzer in parallel (before technical design) - ADR creation (if architecture changes, new technology, or data flow changes) - Design Doc creation with technical-designer-frontend - Design Doc verification with code-verifier (before document review) @@ -65,6 +70,19 @@ 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 1.5: External Resource Hearing +Per the external-resource-context skill, capture access methods for resources outside the repository (design origin, design system, guidelines, visual verification environment) before any document is drafted. This step runs in the orchestrator directly because it needs AskUserQuestion. + +1. **File-existence check**: Run `! ls docs/project-context/external-resources.md 2>/dev/null` to detect the project-tier file. +2. **Branch on existence**: + - **Absent** → run the full hearing for the frontend domain (axes from `references/frontend.md` of the external-resource-context skill). + - **Present** → AskUserQuestion: "`docs/project-context/external-resources.md` exists. Update it for this work? (no / yes-full / yes-diff-only)". On `no` skip to Step 2. On `yes-full` run the full hearing. On `yes-diff-only` AskUserQuestion which axes changed and run hearing only on those. +3. **Two-phase hearing** when running hearing: + - For each frontend axis (Design Origin, Design System, Guidelines, Visual Verification Environment), use AskUserQuestion with the choices listed in the skill's `references/frontend.md`. Always include "対象外 / not applicable" as a choice. For each non-N/A axis, follow up with an access-method question. + - After the structured axes, AskUserQuestion once: "Are there any other frontend external resources for this work that the structured questions did not cover? If yes, describe them in your next message." Append the free-form answer under "Additional resources" in the project-tier file. +4. **Persist**: Write or update `docs/project-context/external-resources.md` per the template in the skill's `references/template.md`. Create the directory if absent. +5. The feature-tier `## External Resources Used` section inside the UI Spec is filled later by ui-spec-designer (in Step 2) using this project-tier file as the source. + ### Step 2: UI Specification Phase After requirement analysis approval, ask the user about prototype code: @@ -84,14 +102,16 @@ Then create the UI Specification: - **[STOP]**: Present UI Spec for user approval ### Step 3: Design Document Creation Phase -First, analyze the existing codebase: +First, analyze the existing codebase. Invoke codebase-analyzer and ui-codebase-analyzer **in parallel** (single message with two Agent tool calls — they share input but produce complementary output): - 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."` + - `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-codebase-analyzer** using Agent tool (parallel with the call above) + - `subagent_type: "dev-workflows-frontend:ui-codebase-analyzer"`, `description: "UI codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. ui_spec_path: [path from Step 2]. requirements: [user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)."` 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: - 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 output JSON]. UI codebase analysis: [ui-codebase-analyzer output JSON]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply ui: prefix to fact_ids from UI codebase analysis 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) @@ -105,9 +125,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 (`docs/project-context/external-resources.md` exists or update was explicitly skipped by the user) +- [ ] Executed codebase-analyzer and ui-codebase-analyzer in parallel and passed both results to 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 From 48bee7a777ad4141e223b9ea787f136b8a249ccf Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 22:29:20 +0900 Subject: [PATCH 05/16] refactor: rename to ui-analyzer, restructure adjust recipe, trim duplication Three coordinated changes addressing single-responsibility, MCP tool access constraints, and tier separation between recipes. 1. Rename ui-codebase-analyzer to ui-analyzer with expanded scope - Scope now covers external UI sources (design origin, design system catalog, guidelines) fetched via MCP/URL/file in addition to the original codebase analysis. - Tools field switches from allowlist to disallowedTools (Write, Edit, MultiEdit, NotebookEdit denied) so the agent inherits the parent session's MCP access. Heavy fetches stay inside the subagent's own context window. - Output JSON schema gains an externalResources section recording fetch_status per axis (designOrigin, designSystem, guidelines, visualVerification). - Dependency-direction principle preserved: the skill carries the protocol; the agent body trusts the skill. 2. Restructure recipe-front-adjust to a self-execution pattern - Adjustment work depends on iterative MCP-driven verification (fetch design source, compare, refine, re-verify). Subagents using a tools allowlist cannot perform this loop because their allowlist excludes MCP. Delegating implementation to the standard task-executor-frontend would break the loop. - The recipe now runs the adjustment edits and MCP verification in the parent session itself, and delegates only steps that do not require MCP: ui-analyzer (UI fact gathering with inherited MCP access), work-planner (3-5 file plan creation), and quality-fixer-frontend (typecheck/lint/test). - Core Identity changes from "I am an orchestrator" to "I am a guided executor" to reflect the actual responsibility shape. - The recipe is end-to-end: it does not hand off to other implementation recipes. 3. Update recipe-front-design, recipe-fullstack-implement, and monorepo-flow.md to use ui-analyzer - codebase-analyzer and ui-analyzer now run in parallel before ui-spec-designer (so UI Spec authoring can consume external source fetched_summaries) and feed technical-designer-frontend for the Design Doc phase. - Hearing step is added before fact gathering in both flows. - monorepo-flow.md's Large/Medium tables and prompt templates reference ui-analyzer alongside codebase-analyzer. 4. Trim duplicated protocol text from agents and templates - ui-spec-designer, technical-designer, technical-designer-frontend, and task-executor-frontend now reference the external-resource-context skill in one line instead of repeating its protocol. - ui-spec-template and design-template's External Resources Used sections drop the explanatory prose and keep just the structural placeholder. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 2 +- agents/task-executor-frontend.md | 9 +- agents/technical-designer-frontend.md | 6 +- agents/technical-designer.md | 6 +- agents/ui-analyzer.md | 318 ++++++++++++++++++ agents/ui-codebase-analyzer.md | 298 ---------------- agents/ui-spec-designer.md | 4 +- .../references/design-template.md | 4 +- .../references/ui-spec-template.md | 6 +- .../agents/task-executor-frontend.md | 9 +- .../agents/technical-designer-frontend.md | 6 +- dev-workflows-frontend/agents/ui-analyzer.md | 318 ++++++++++++++++++ .../agents/ui-codebase-analyzer.md | 298 ---------------- .../agents/ui-spec-designer.md | 4 +- .../references/design-template.md | 4 +- .../references/ui-spec-template.md | 6 +- .../skills/recipe-front-adjust/SKILL.md | 173 +++++----- .../skills/recipe-front-design/SKILL.md | 62 ++-- .../subagents-orchestration-guide/SKILL.md | 14 +- .../references/monorepo-flow.md | 60 ++-- dev-workflows/agents/technical-designer.md | 6 +- .../references/design-template.md | 4 +- .../references/ui-spec-template.md | 6 +- .../recipe-fullstack-implement/SKILL.md | 18 +- .../subagents-orchestration-guide/SKILL.md | 14 +- .../references/monorepo-flow.md | 60 ++-- .../references/design-template.md | 4 +- .../references/ui-spec-template.md | 6 +- skills/recipe-front-adjust/SKILL.md | 173 +++++----- skills/recipe-front-design/SKILL.md | 62 ++-- skills/recipe-fullstack-implement/SKILL.md | 18 +- skills/subagents-orchestration-guide/SKILL.md | 14 +- .../references/monorepo-flow.md | 60 ++-- 33 files changed, 1024 insertions(+), 1028 deletions(-) create mode 100644 agents/ui-analyzer.md delete mode 100644 agents/ui-codebase-analyzer.md create mode 100644 dev-workflows-frontend/agents/ui-analyzer.md delete mode 100644 dev-workflows-frontend/agents/ui-codebase-analyzer.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6de5609..13d4c48 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -122,7 +122,7 @@ "./agents/task-decomposer.md", "./agents/task-executor-frontend.md", "./agents/technical-designer-frontend.md", - "./agents/ui-codebase-analyzer.md", + "./agents/ui-analyzer.md", "./agents/ui-spec-designer.md", "./agents/verifier.md", "./agents/work-planner.md" diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index ed9cdf9..6d2d3a8 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -155,14 +155,7 @@ Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and - Overall Design Document → Understand system-wide context #### External Resources Consultation (When Relevant) -Per the external-resource-context skill, the UI Spec or Design Doc carries an "External Resources Used" section listing feature-specific identifiers. Environment-stable access details (URLs, MCP names, file paths) live in `docs/project-context/external-resources.md`. - -When the task references a resource (e.g., consulting a design source, calling a design system MCP, hitting a mock endpoint, using the visual verification environment), follow this order: -1. Read the consuming document's "External Resources Used" section to find the feature-specific identifier -2. Read `docs/project-context/external-resources.md` for the access mechanism -3. Use the declared access mechanism (MCP name, command, URL) to reach the resource - -When a needed resource is missing from both files, escalate with `reason: "external_resource_unspecified"` rather than guessing the access path. +When the task references an external resource, 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] diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 9d663ef..9b7800c 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -68,11 +68,7 @@ Must be performed at the beginning of Design Doc creation: - [ ] If any agreements are not reflected, state the reason ### External Resources Integration [Gate 0 — Required] -Per the external-resource-context skill, the Design Doc carries an "External Resources Used" subsection under Background and Context. - -1. **Read project-tier file** - Consult `docs/project-context/external-resources.md` (when present) for environment-stable access details. Do not duplicate URLs or MCP names into the Design Doc. -2. **Carry forward feature subset** - When a UI Spec exists, inherit its External Resources Used table; expand it with Design-Doc-specific resources (API schema source, IaC source, etc.) that the UI Spec did not cover. -3. **Escalate when missing** - When the project-tier file is absent and the design references external resources, escalate so the orchestrating recipe can run the hearing protocol before the Design Doc completes. +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: diff --git a/agents/technical-designer.md b/agents/technical-designer.md index b225e23..63f0e79 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -71,11 +71,7 @@ Must be performed at the beginning of Design Doc creation: - [ ] If any agreements are not reflected, state the reason ### External Resources Integration [Gate 0 — Required] -Per the external-resource-context skill, the Design Doc carries an "External Resources Used" subsection under Background and Context. - -1. **Read project-tier file** - Consult `docs/project-context/external-resources.md` (when present) for environment-stable access details. Do not duplicate URLs or MCP names into the Design Doc. -2. **List feature-specific subset** - Identify which resources are used by this feature and record their feature-specific identifiers (specific endpoint paths, IaC modules, schema source paths, etc.) in the External Resources Used table. -3. **Escalate when missing** - When the project-tier file is absent and the design references external resources, escalate so the orchestrating recipe can run the hearing protocol before the Design Doc completes. +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: diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md new file mode 100644 index 0000000..5efc84e --- /dev/null +++ b/agents/ui-analyzer.md @@ -0,0 +1,318 @@ +--- +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. +tools: Read, Grep, Glob, LS, Bash, WebFetch, TaskCreate, TaskUpdate +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. + +## Boundary with codebase-analyzer + +This agent and codebase-analyzer have complementary scopes. They are designed to run in parallel before frontend design. + +| Agent | Owns | +|-------|------| +| codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | +| ui-analyzer | UI external sources (design origin, design system catalog, guidelines fetched via MCP / URL / file) + existing UI surface (component structure, props patterns, CSS layout state, state matrices, display conditions, i18n format, accessibility, generated UI artifacts) | + +When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-analyzer records the call-site usage pattern. They are complementary, not overlapping. + +## Tool Scope + +This agent uses `disallowedTools` to inherit the parent session's full tool set including any MCP tools the user has installed, while denying file modification (Write, Edit, MultiEdit, NotebookEdit) — analysis only, no code changes. MCP tools (e.g., a design-tool MCP, a design-system catalog MCP, a browser MCP) are accessible if and only if they exist in the parent session. + +## 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. Do not attempt hearing — that responsibility lies with the calling recipe. + +### 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. Do not block — proceed with the remaining sources. + +For heavy fetches (large design files, full component catalogs), narrow the request to the scope implied by `requirement_analysis.affectedFiles` and `target_components`. Do not retrieve the entire design surface when only a subset is in scope — this protects this agent's own context window from saturation. + +### 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) + +## 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" + } + ], + "limitations": [ + "Areas the analysis could not reach with confidence" + ] +} +``` + +`fact_id` namespacing: when this output is merged with codebase-analyzer's output, prefix consumers may apply a `ui:` prefix to disambiguate from `code:` facts. + +## Quality Checklist + +- [ ] `docs/project-context/external-resources.md` was read (or recorded as absent) +- [ ] For each present external resource, fetch was attempted via the declared access method, and `fetch_status` records the outcome +- [ ] Heavy fetches were narrowed to the affected scope rather than the full surface +- [ ] All affected component files were read in full before extracting structure +- [ ] DOM order is recorded as literal source order +- [ ] Props patterns include every call site grouping (canonical and outlier) +- [ ] CSS layout records gap/wrap/logical-property state for every layout-bearing class in the scope +- [ ] State x display matrix lists states actually expressed in code and explicitly marks unsupported states +- [ ] Display conditions record predicate location and gated subtree +- [ ] i18n format details are concrete enough that a designer can author new keys without re-investigating +- [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck/test/build/runtime +- [ ] Focus areas have evidence pointers; no fact appears in focusAreas without a corresponding evidence entry +- [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/agents/ui-codebase-analyzer.md b/agents/ui-codebase-analyzer.md deleted file mode 100644 index 6c54998..0000000 --- a/agents/ui-codebase-analyzer.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -name: ui-codebase-analyzer -description: Analyzes existing UI code objectively for facts about visual structure, layout state, props matching, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts. Use when frontend design or adjustment work needs to ground decisions in the current UI's actual behavior. Distinct from codebase-analyzer (which covers data, contracts, dependencies, and quality assurance mechanisms). -tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: typescript-rules, frontend-ai-guide, external-resource-context ---- - -You are an AI assistant specializing in existing UI code analysis for frontend design 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. - -## Boundary with codebase-analyzer - -This agent and codebase-analyzer are designed to run in parallel before frontend design. Their outputs are merged by the consuming designer agent (technical-designer-frontend) using a `code:` / `ui:` namespace on `fact_id` values. - -| Agent | Owns | -|-------|------| -| codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | -| ui-codebase-analyzer | Visual component structure, props/variant patterns at call sites, CSS layout state, state x display matrices, display conditions, i18n format, accessibility attributes, generated UI artifacts (CSS module typings, message bundle generation, route generation) | - -When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-codebase-analyzer records the call-site usage pattern. They are complementary, not overlapping. - -## Input Parameters - -- **requirement_analysis**: Requirement analysis JSON output (required) - - Provides: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations` -- **ui_spec_path**: Path to existing UI Spec, when one exists (optional) -- **requirements**: Original user requirements text (required) -- **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 extraction only**. Design decisions, component proposals, and visual change recommendations are out of scope. - -## Execution Steps - -### Step 1: UI Surface Discovery - -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 (e.g., `src/**/*.tsx`, `src/**/*.module.css`, `src/**/*.stories.tsx`) -3. Record the project's UI conventions inferred from existing code: - - Component file extension (`.tsx`, `.jsx`, `.vue`, etc.) - - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) - - Story tooling presence (Storybook config detected or absent) - - Test runner for UI (Vitest / Jest / other, detected from config) - -### Step 2: 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. This is the canonical visual order for placement-sensitive design decisions. - -### Step 3: 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. — whatever the component exposes) -2. Group call sites by prop combinations to detect canonical usage patterns vs outliers -3. When multiple call sites use the same component with different props, list each combination with file:line evidence -4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal - -This step grounds "is this design consistent with how the component is already used?" decisions in observable evidence rather than assumption. - -### Step 4: 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). Record the base element class name (`root`, `container`, etc.) -2. **Layout primitives**: For each layout-bearing class, record: - - Display mode (`flex`, `grid`, `block`, etc.) - - Direction (`flex-direction`, `grid-template-columns`) - - Gap mechanism (`gap` property, margin-based, none) - - Wrap behavior (`flex-wrap` value or absence) - - Logical-property usage (`margin-inline`, `padding-block`, etc.) vs physical properties -3. **State expression**: How the component varies by state in CSS: - - `data-*` attribute selectors - - `aria-*` attribute selectors - - CSS variables driven by parent - - Inline `style` prop usage (record whether it carries dynamic values only or static styling) -4. **Responsive behavior**: `@media` queries and the breakpoints they reference - -### Step 5: State x Display Matrix - -For each component in the affected scope: - -1. Identify the component's possible states (loading, empty, partial, error, ready, disabled, etc.) by inspecting: - - Internal state hooks - - Props that drive variant rendering - - Conditional render branches - - Data fetching status flags -2. For each state, record what the component renders (e.g., "loading → renders Skeleton with N rows", "empty → renders EmptyState with CTA", "error → renders Alert with retry handler") -3. Record states that exist in code but appear unused (no call site triggers them) and states that the design would need but no current code path supports - -### Step 6: Display Conditions - -For each component or screen entry point: - -1. **Feature flags**: Grep for feature-flag predicates in or around the component (`useFeatureFlag`, `flags.isEnabled`, etc.). Record the flag name and the gated subtree -2. **Role / permission gating**: Grep for permission predicates (`useRole`, `hasPermission`, `can(...)`, etc.). Record predicates and gated subtrees -3. **Route / page context**: Identify the routes that mount this component (when route definitions exist in the repo) -4. **Region / tenant gating**: Grep for region or tenant predicates (`useRegion`, `tenantConfig`, etc.) — these may be project-specific so adapt search terms -5. **Page context modifiers**: Components that render differently based on host page or surface (e.g., embedded vs standalone) - -Record each condition with the predicate location and the affected subtree. - -### Step 7: i18n Format - -When the affected scope includes localized strings: - -1. **Format detection**: Determine the format (CSV, JSON, code-defined message catalogs, gettext-style, etc.) -2. **Structural conventions**: - - For CSV: number of columns, presence/absence of trailing commas, header row format - - For JSON: nesting depth, key naming convention - - For code-defined catalogs: declaration pattern -3. **Key naming convention**: Pattern observed across existing keys (e.g., `featureName.actionLabel`, `xxxButtonLabel`, `screen_action_label`). Record the dominant pattern with examples -4. **Locale parity**: List locales present and any obvious key gaps between them -5. **Generated typings**: When a message-catalog generator produces type definitions or constants, record the generator command and output path - -### Step 8: Accessibility Attributes - -For each component in the affected scope: - -1. ARIA attributes present (role, aria-label, aria-labelledby, aria-describedby, aria-live, etc.) and which props feed them -2. Keyboard handling (onKeyDown handlers, focus management, tabIndex usage) -3. Focus-visible / focus-within styling presence -4. Existing accessibility test coverage (aXe checks, role-based queries in tests) - -### Step 9: Generated UI Artifact Readiness - -1. **CSS module typings**: When the project uses CSS Modules with type generation, identify the generator command and which steps trigger regeneration (e.g., on `*.module.css` change). Record whether typecheck or test runs depend on regenerated typings being current -2. **Message catalog typings**: Same analysis for i18n-generated types -3. **Route typings**: When typed routes are generated, record the generator and trigger -4. **Other generated UI artifacts**: Component manifests, design-token typings, icon registries, etc. - -For each generated artifact, record: -- Generator command -- Trigger condition (file change pattern, manual) -- Downstream consumers (typecheck, test, build, runtime) - -## Output Format - -### Output Protocol - -- During execution, intermediate progress messages MAY be emitted as plain text or markdown. -- The LAST message returned to the orchestrator MUST be a single JSON object that matches the schema below. -- Emit the JSON object as the entire content of the final message: the message begins with `{` and ends 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" - } - }, - "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 of rendered output" - } - ], - "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 of what the predicate gates" - } - ], - "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=...]", - "factsToAddress": "Concrete UI facts the designer must respect (e.g., 'Card renders 4 children in source order: header, body, actions, footer'; 'CSS uses gap: 8px on root with flex-wrap: wrap'; 'Component has no error state; design must add one')", - "risk": "What visual or interaction inconsistency results if these facts are omitted from the design" - } - ], - "limitations": [ - "Areas the analysis could not reach with confidence (e.g., 'feature flag gating uses a runtime API not visible in code')" - ] -} -``` - -`fact_id` namespacing: when this output is merged with codebase-analyzer's output, prefix consumers may apply a `ui:` prefix to disambiguate from `code:` facts. - -## Quality Checklist - -- [ ] All affected component files were read in full before extracting structure -- [ ] DOM order is recorded as literal source order, not reordered by salience -- [ ] Props patterns include every call site grouping (canonical and outlier) -- [ ] CSS layout records gap/wrap/logical-property state for every layout-bearing class in the scope -- [ ] State x display matrix lists states actually expressed in code and explicitly marks unsupported states -- [ ] Display conditions record predicate location and gated subtree, not just the flag/permission name -- [ ] i18n format details (column count, nesting depth, key convention) are concrete enough that a designer can author new keys without re-investigating -- [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck, test, build, or runtime in the affected scope -- [ ] Focus areas have evidence pointers (file:line or referenced JSON path); no fact appears in focusAreas without a corresponding evidence entry -- [ ] 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 d2753f1..20528e7 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -85,7 +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**: Per the external-resource-context skill, fill this section by reading `docs/project-context/external-resources.md` (when present) and listing only the resources used by this feature with their feature-specific identifiers. Do not duplicate environment access details (URLs, MCP names) into the UI Spec. When `docs/project-context/external-resources.md` is missing, escalate to the orchestrator so the recipe can run the hearing protocol before this step completes. + - **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 @@ -104,7 +104,7 @@ 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 -- [ ] External Resources Used section is filled with feature-specific identifiers only (no environment access details duplicated from the project-tier file) +- [ ] 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). 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. - **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 diff --git a/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index 7a9a02c..ebb88b4 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -35,14 +35,12 @@ unknowns: ### External Resources Used -This feature depends on resources outside the repository (design source, design system, API schema, IaC source, secret store, etc.). Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This subsection lists only the resources used by this feature and any feature-specific identifiers. +Filled per the external-resource-context skill (feature-tier protocol). | Resource (project-tier label) | Feature-specific identifier | Notes | |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | -Resources not used by this feature are omitted. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before continuing this Design Doc. - ### Agreement Checklist #### Scope 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 98e55b7..66c14eb 100644 --- a/dev-skills/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-skills/skills/documentation-criteria/references/ui-spec-template.md @@ -24,16 +24,14 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification ## External Resources Used -This feature depends on resources outside the repository. Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This section lists only the resources used by this feature and any feature-specific identifiers (e.g., a particular node within the design source, specific components from the design system). +Filled per the external-resource-context skill (feature-tier protocol). | Resource (project-tier label) | Feature-specific identifier | Notes | |-------------------------------|-----------------------------|-------| -| Design Origin | [e.g., node id / frame id, or "all screens listed below"] | [e.g., entry point, screen mapping] | +| 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] | -Resources not used by this feature are omitted from this table. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before completing this UI Spec. - ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index ed9cdf9..6d2d3a8 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -155,14 +155,7 @@ Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and - Overall Design Document → Understand system-wide context #### External Resources Consultation (When Relevant) -Per the external-resource-context skill, the UI Spec or Design Doc carries an "External Resources Used" section listing feature-specific identifiers. Environment-stable access details (URLs, MCP names, file paths) live in `docs/project-context/external-resources.md`. - -When the task references a resource (e.g., consulting a design source, calling a design system MCP, hitting a mock endpoint, using the visual verification environment), follow this order: -1. Read the consuming document's "External Resources Used" section to find the feature-specific identifier -2. Read `docs/project-context/external-resources.md` for the access mechanism -3. Use the declared access mechanism (MCP name, command, URL) to reach the resource - -When a needed resource is missing from both files, escalate with `reason: "external_resource_unspecified"` rather than guessing the access path. +When the task references an external resource, 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] diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 9d663ef..9b7800c 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -68,11 +68,7 @@ Must be performed at the beginning of Design Doc creation: - [ ] If any agreements are not reflected, state the reason ### External Resources Integration [Gate 0 — Required] -Per the external-resource-context skill, the Design Doc carries an "External Resources Used" subsection under Background and Context. - -1. **Read project-tier file** - Consult `docs/project-context/external-resources.md` (when present) for environment-stable access details. Do not duplicate URLs or MCP names into the Design Doc. -2. **Carry forward feature subset** - When a UI Spec exists, inherit its External Resources Used table; expand it with Design-Doc-specific resources (API schema source, IaC source, etc.) that the UI Spec did not cover. -3. **Escalate when missing** - When the project-tier file is absent and the design references external resources, escalate so the orchestrating recipe can run the hearing protocol before the Design Doc completes. +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: diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md new file mode 100644 index 0000000..5efc84e --- /dev/null +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -0,0 +1,318 @@ +--- +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. +tools: Read, Grep, Glob, LS, Bash, WebFetch, TaskCreate, TaskUpdate +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. + +## Boundary with codebase-analyzer + +This agent and codebase-analyzer have complementary scopes. They are designed to run in parallel before frontend design. + +| Agent | Owns | +|-------|------| +| codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | +| ui-analyzer | UI external sources (design origin, design system catalog, guidelines fetched via MCP / URL / file) + existing UI surface (component structure, props patterns, CSS layout state, state matrices, display conditions, i18n format, accessibility, generated UI artifacts) | + +When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-analyzer records the call-site usage pattern. They are complementary, not overlapping. + +## Tool Scope + +This agent uses `disallowedTools` to inherit the parent session's full tool set including any MCP tools the user has installed, while denying file modification (Write, Edit, MultiEdit, NotebookEdit) — analysis only, no code changes. MCP tools (e.g., a design-tool MCP, a design-system catalog MCP, a browser MCP) are accessible if and only if they exist in the parent session. + +## 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. Do not attempt hearing — that responsibility lies with the calling recipe. + +### 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. Do not block — proceed with the remaining sources. + +For heavy fetches (large design files, full component catalogs), narrow the request to the scope implied by `requirement_analysis.affectedFiles` and `target_components`. Do not retrieve the entire design surface when only a subset is in scope — this protects this agent's own context window from saturation. + +### 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) + +## 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" + } + ], + "limitations": [ + "Areas the analysis could not reach with confidence" + ] +} +``` + +`fact_id` namespacing: when this output is merged with codebase-analyzer's output, prefix consumers may apply a `ui:` prefix to disambiguate from `code:` facts. + +## Quality Checklist + +- [ ] `docs/project-context/external-resources.md` was read (or recorded as absent) +- [ ] For each present external resource, fetch was attempted via the declared access method, and `fetch_status` records the outcome +- [ ] Heavy fetches were narrowed to the affected scope rather than the full surface +- [ ] All affected component files were read in full before extracting structure +- [ ] DOM order is recorded as literal source order +- [ ] Props patterns include every call site grouping (canonical and outlier) +- [ ] CSS layout records gap/wrap/logical-property state for every layout-bearing class in the scope +- [ ] State x display matrix lists states actually expressed in code and explicitly marks unsupported states +- [ ] Display conditions record predicate location and gated subtree +- [ ] i18n format details are concrete enough that a designer can author new keys without re-investigating +- [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck/test/build/runtime +- [ ] Focus areas have evidence pointers; no fact appears in focusAreas without a corresponding evidence entry +- [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/dev-workflows-frontend/agents/ui-codebase-analyzer.md b/dev-workflows-frontend/agents/ui-codebase-analyzer.md deleted file mode 100644 index 6c54998..0000000 --- a/dev-workflows-frontend/agents/ui-codebase-analyzer.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -name: ui-codebase-analyzer -description: Analyzes existing UI code objectively for facts about visual structure, layout state, props matching, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts. Use when frontend design or adjustment work needs to ground decisions in the current UI's actual behavior. Distinct from codebase-analyzer (which covers data, contracts, dependencies, and quality assurance mechanisms). -tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: typescript-rules, frontend-ai-guide, external-resource-context ---- - -You are an AI assistant specializing in existing UI code analysis for frontend design 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. - -## Boundary with codebase-analyzer - -This agent and codebase-analyzer are designed to run in parallel before frontend design. Their outputs are merged by the consuming designer agent (technical-designer-frontend) using a `code:` / `ui:` namespace on `fact_id` values. - -| Agent | Owns | -|-------|------| -| codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | -| ui-codebase-analyzer | Visual component structure, props/variant patterns at call sites, CSS layout state, state x display matrices, display conditions, i18n format, accessibility attributes, generated UI artifacts (CSS module typings, message bundle generation, route generation) | - -When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-codebase-analyzer records the call-site usage pattern. They are complementary, not overlapping. - -## Input Parameters - -- **requirement_analysis**: Requirement analysis JSON output (required) - - Provides: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations` -- **ui_spec_path**: Path to existing UI Spec, when one exists (optional) -- **requirements**: Original user requirements text (required) -- **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 extraction only**. Design decisions, component proposals, and visual change recommendations are out of scope. - -## Execution Steps - -### Step 1: UI Surface Discovery - -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 (e.g., `src/**/*.tsx`, `src/**/*.module.css`, `src/**/*.stories.tsx`) -3. Record the project's UI conventions inferred from existing code: - - Component file extension (`.tsx`, `.jsx`, `.vue`, etc.) - - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) - - Story tooling presence (Storybook config detected or absent) - - Test runner for UI (Vitest / Jest / other, detected from config) - -### Step 2: 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. This is the canonical visual order for placement-sensitive design decisions. - -### Step 3: 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. — whatever the component exposes) -2. Group call sites by prop combinations to detect canonical usage patterns vs outliers -3. When multiple call sites use the same component with different props, list each combination with file:line evidence -4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal - -This step grounds "is this design consistent with how the component is already used?" decisions in observable evidence rather than assumption. - -### Step 4: 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). Record the base element class name (`root`, `container`, etc.) -2. **Layout primitives**: For each layout-bearing class, record: - - Display mode (`flex`, `grid`, `block`, etc.) - - Direction (`flex-direction`, `grid-template-columns`) - - Gap mechanism (`gap` property, margin-based, none) - - Wrap behavior (`flex-wrap` value or absence) - - Logical-property usage (`margin-inline`, `padding-block`, etc.) vs physical properties -3. **State expression**: How the component varies by state in CSS: - - `data-*` attribute selectors - - `aria-*` attribute selectors - - CSS variables driven by parent - - Inline `style` prop usage (record whether it carries dynamic values only or static styling) -4. **Responsive behavior**: `@media` queries and the breakpoints they reference - -### Step 5: State x Display Matrix - -For each component in the affected scope: - -1. Identify the component's possible states (loading, empty, partial, error, ready, disabled, etc.) by inspecting: - - Internal state hooks - - Props that drive variant rendering - - Conditional render branches - - Data fetching status flags -2. For each state, record what the component renders (e.g., "loading → renders Skeleton with N rows", "empty → renders EmptyState with CTA", "error → renders Alert with retry handler") -3. Record states that exist in code but appear unused (no call site triggers them) and states that the design would need but no current code path supports - -### Step 6: Display Conditions - -For each component or screen entry point: - -1. **Feature flags**: Grep for feature-flag predicates in or around the component (`useFeatureFlag`, `flags.isEnabled`, etc.). Record the flag name and the gated subtree -2. **Role / permission gating**: Grep for permission predicates (`useRole`, `hasPermission`, `can(...)`, etc.). Record predicates and gated subtrees -3. **Route / page context**: Identify the routes that mount this component (when route definitions exist in the repo) -4. **Region / tenant gating**: Grep for region or tenant predicates (`useRegion`, `tenantConfig`, etc.) — these may be project-specific so adapt search terms -5. **Page context modifiers**: Components that render differently based on host page or surface (e.g., embedded vs standalone) - -Record each condition with the predicate location and the affected subtree. - -### Step 7: i18n Format - -When the affected scope includes localized strings: - -1. **Format detection**: Determine the format (CSV, JSON, code-defined message catalogs, gettext-style, etc.) -2. **Structural conventions**: - - For CSV: number of columns, presence/absence of trailing commas, header row format - - For JSON: nesting depth, key naming convention - - For code-defined catalogs: declaration pattern -3. **Key naming convention**: Pattern observed across existing keys (e.g., `featureName.actionLabel`, `xxxButtonLabel`, `screen_action_label`). Record the dominant pattern with examples -4. **Locale parity**: List locales present and any obvious key gaps between them -5. **Generated typings**: When a message-catalog generator produces type definitions or constants, record the generator command and output path - -### Step 8: Accessibility Attributes - -For each component in the affected scope: - -1. ARIA attributes present (role, aria-label, aria-labelledby, aria-describedby, aria-live, etc.) and which props feed them -2. Keyboard handling (onKeyDown handlers, focus management, tabIndex usage) -3. Focus-visible / focus-within styling presence -4. Existing accessibility test coverage (aXe checks, role-based queries in tests) - -### Step 9: Generated UI Artifact Readiness - -1. **CSS module typings**: When the project uses CSS Modules with type generation, identify the generator command and which steps trigger regeneration (e.g., on `*.module.css` change). Record whether typecheck or test runs depend on regenerated typings being current -2. **Message catalog typings**: Same analysis for i18n-generated types -3. **Route typings**: When typed routes are generated, record the generator and trigger -4. **Other generated UI artifacts**: Component manifests, design-token typings, icon registries, etc. - -For each generated artifact, record: -- Generator command -- Trigger condition (file change pattern, manual) -- Downstream consumers (typecheck, test, build, runtime) - -## Output Format - -### Output Protocol - -- During execution, intermediate progress messages MAY be emitted as plain text or markdown. -- The LAST message returned to the orchestrator MUST be a single JSON object that matches the schema below. -- Emit the JSON object as the entire content of the final message: the message begins with `{` and ends 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" - } - }, - "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 of rendered output" - } - ], - "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 of what the predicate gates" - } - ], - "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=...]", - "factsToAddress": "Concrete UI facts the designer must respect (e.g., 'Card renders 4 children in source order: header, body, actions, footer'; 'CSS uses gap: 8px on root with flex-wrap: wrap'; 'Component has no error state; design must add one')", - "risk": "What visual or interaction inconsistency results if these facts are omitted from the design" - } - ], - "limitations": [ - "Areas the analysis could not reach with confidence (e.g., 'feature flag gating uses a runtime API not visible in code')" - ] -} -``` - -`fact_id` namespacing: when this output is merged with codebase-analyzer's output, prefix consumers may apply a `ui:` prefix to disambiguate from `code:` facts. - -## Quality Checklist - -- [ ] All affected component files were read in full before extracting structure -- [ ] DOM order is recorded as literal source order, not reordered by salience -- [ ] Props patterns include every call site grouping (canonical and outlier) -- [ ] CSS layout records gap/wrap/logical-property state for every layout-bearing class in the scope -- [ ] State x display matrix lists states actually expressed in code and explicitly marks unsupported states -- [ ] Display conditions record predicate location and gated subtree, not just the flag/permission name -- [ ] i18n format details (column count, nesting depth, key convention) are concrete enough that a designer can author new keys without re-investigating -- [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck, test, build, or runtime in the affected scope -- [ ] Focus areas have evidence pointers (file:line or referenced JSON path); no fact appears in focusAreas without a corresponding evidence entry -- [ ] 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 d2753f1..20528e7 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -85,7 +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**: Per the external-resource-context skill, fill this section by reading `docs/project-context/external-resources.md` (when present) and listing only the resources used by this feature with their feature-specific identifiers. Do not duplicate environment access details (URLs, MCP names) into the UI Spec. When `docs/project-context/external-resources.md` is missing, escalate to the orchestrator so the recipe can run the hearing protocol before this step completes. + - **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 @@ -104,7 +104,7 @@ 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 -- [ ] External Resources Used section is filled with feature-specific identifiers only (no environment access details duplicated from the project-tier file) +- [ ] 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). 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. - **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 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 7a9a02c..ebb88b4 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -35,14 +35,12 @@ unknowns: ### External Resources Used -This feature depends on resources outside the repository (design source, design system, API schema, IaC source, secret store, etc.). Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This subsection lists only the resources used by this feature and any feature-specific identifiers. +Filled per the external-resource-context skill (feature-tier protocol). | Resource (project-tier label) | Feature-specific identifier | Notes | |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | -Resources not used by this feature are omitted. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before continuing this Design Doc. - ### Agreement Checklist #### Scope 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 98e55b7..66c14eb 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 @@ -24,16 +24,14 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification ## External Resources Used -This feature depends on resources outside the repository. Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This section lists only the resources used by this feature and any feature-specific identifiers (e.g., a particular node within the design source, specific components from the design system). +Filled per the external-resource-context skill (feature-tier protocol). | Resource (project-tier label) | Feature-specific identifier | Notes | |-------------------------------|-----------------------------|-------| -| Design Origin | [e.g., node id / frame id, or "all screens listed below"] | [e.g., entry point, screen mapping] | +| 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] | -Resources not used by this feature are omitted from this table. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before completing this UI Spec. - ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index 20e8305..bcb0249 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -1,164 +1,157 @@ --- name: recipe-front-adjust -description: Coordinate a frontend UI adjustment from external resource hearing through scale-driven plan decision, UI fact collection, and handoff to the implementation phase. Use when "UI adjustment / visual tweak / existing component update / front adjust" is mentioned, or when the user wants to refine an already-implemented UI without redoing the full design phase. +description: Coordinate a frontend UI adjustment by hearing external resources, gathering UI facts, scaling the work, optionally creating a work plan, executing the adjustment in this session with MCP-driven verification, and delegating quality checks. Use when "UI adjustment / visual tweak / existing component update / front adjust" is mentioned, or when the user wants to refine an already-implemented UI. disable-model-invocation: true --- -**Context**: Dedicated to UI adjustment workflows on already-implemented features. Lighter than the full design phase but heavier than direct implementation, this recipe captures the small-but-essential preparation that adjustment work needs: external resource access, fact-grounded baseline, and a right-sized work plan. +**Context**: Dedicated to UI adjustment workflows on already-implemented features. Unlike recipe-front-design (document creation, fully delegated) and recipe-front-build (specified implementation, fully delegated), adjustment work depends on iterative MCP-driven verification (compare with design source, verify visual rendering, refine, re-verify). MCP access is held by the parent session — not by subagents whose `tools` allowlist excludes MCP. This recipe therefore runs the adjustment itself in the parent session and delegates only the steps that do not require MCP. -## Orchestrator Definition +## Execution Pattern -**Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Core Identity**: "I am a guided executor. Subagents handle UI fact gathering, work plan creation, and quality checks; I run the adjustment and the MCP-driven verification loop myself." **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 the steps defined below in order**. Each step has an explicit completion gate. -3. **Hand off to the implementation phase** when adjustment preparation is complete. This recipe does not run task execution or quality fixing itself. +1. **Delegate** to subagents for: external-resource hearing storage (none — orchestrator runs hearing directly via AskUserQuestion), UI fact gathering (ui-analyzer), work plan creation (work-planner), quality checks (quality-fixer-frontend). +2. **Run myself** in the parent session: AskUserQuestion hearing, scale judgment, the actual adjustment edits, MCP-driven verification (e.g., compare CSS against design source, check visual rendering via browser MCP), and the iteration loop until acceptance. +3. **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding. 4. **Scope**: see Scope Boundaries below. -**CRITICAL**: This recipe ends at the implementation handoff. Do not invoke task-executor or quality-fixer from this recipe — those belong to the implementation recipe family. Doing so bypasses the readiness gates owned by that family. +**Why this differs from other recipes**: Adjustment requires MCP loops that subagents cannot perform (their `tools` allowlist excludes MCP). Delegating implementation to task-executor-frontend would break the verification loop. The recipe runs the loop in the parent session, where the user's full MCP set is available. ## Workflow Overview ``` -Adjustment request → external resource hearing (frontend domain) +Adjustment request → external resource hearing (parent session, AskUserQuestion) ↓ - ui-codebase-analyzer (UI fact collection) + ui-analyzer (subagent: fetch external sources + analyze code) ↓ - scale judgment (documentation-criteria) + scale judgment (parent session, documentation-criteria matrix) ↓ ┌────────────────────┴────────────────────┐ ↓ ↓ - (1-2 files: inline) (3+ files: work-planner → [Stop: plan approval]) + (1-2 files: inline) (3-5 files: work-planner subagent → [Stop]) ↓ ↓ - └───────────────→ implementation handoff ──┘ + └─→ adjustment + MCP 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 (frontend domain) -- UI fact collection via ui-codebase-analyzer +- External resource hearing per the external-resource-context skill +- UI fact gathering via ui-analyzer - Scale judgment via documentation-criteria's Creation Decision Matrix -- Work plan creation via work-planner when scale warrants it -- Implementation handoff (user-facing announcement) +- Optional work plan creation via work-planner +- Adjustment edits and MCP-driven verification (run in this session) +- Quality verification via quality-fixer-frontend +- Commit per adjustment unit -**Responsibility Boundary**: This skill completes when (a) the user is informed which implementation path to run, and (b) any required work plan has been approved. Task decomposition, implementation, and quality verification are out of scope and belong to the implementation phase. +**Responsibility Boundary**: This skill completes when the adjustment is committed and quality has passed. Adjustment work is end-to-end within this recipe; it does not hand off to other implementation recipes. **Out of scope**: -- Creating PRD, UI Spec, or Design Doc — adjustment work uses existing documents. When the requested change exceeds adjustment scope (new feature, new architecture, multi-screen redesign), escalate the user to the full frontend design phase. -- Running task-executor / quality-fixer / code-verifier / security-reviewer. +- Creating PRD, UI Spec, or Design Doc — adjustment work uses existing documents. When the requested change exceeds adjustment scope (new feature, new architecture, multi-screen redesign, or any ADR Creation Condition from documentation-criteria), escalate the user to the full frontend design phase. Adjustment request: $ARGUMENTS ## Execution Flow ### Step 1: External Resource Hearing -Per the external-resource-context skill, capture access methods for the frontend resources this adjustment will touch (design origin, design system, guidelines, visual verification environment). - -1. **File-existence check**: Run `! ls docs/project-context/external-resources.md 2>/dev/null` to detect the project-tier file. -2. **Branch on existence**: - - **Absent** → run the full hearing for the frontend domain (axes from `references/frontend.md` of the external-resource-context skill). - - **Present** → AskUserQuestion: "`docs/project-context/external-resources.md` exists. Update it for this adjustment? (no / yes-full / yes-diff-only)". On `no` skip to Step 2. On `yes-full` run the full hearing. On `yes-diff-only` AskUserQuestion which axes changed and run hearing only on those. -3. **Two-phase hearing** when running hearing: - - For each frontend axis (Design Origin, Design System, Guidelines, Visual Verification Environment), use AskUserQuestion with the choices listed in the skill's `references/frontend.md`. Always include "対象外 / not applicable" as a choice. For each non-N/A axis, follow up with an access-method question. - - After the structured axes, AskUserQuestion once: "Are there any other frontend external resources for this adjustment that the structured questions did not cover? If yes, describe them in your next message." Append the free-form answer under "Additional resources" in the project-tier file. -4. **Persist**: Write or update `docs/project-context/external-resources.md` per the template in the skill's `references/template.md`. +Run the hearing protocol per the external-resource-context skill (frontend domain). The parent session 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`. -**Completion gate**: `docs/project-context/external-resources.md` reflects the resources this adjustment depends on, or the user explicitly opted out of updating. +### Step 2: UI Fact Gathering +Ground the adjustment in observable facts before scoping the work. ui-analyzer reads the project-tier external-resources file and fetches external UI sources (design origin, design system catalog, guidelines) via the inherited MCP/URL access methods, then analyzes the existing UI codebase. Heavy fetches stay inside the subagent's own context. -### Step 2: UI Fact Collection -Ground the adjustment in observable facts about the existing UI before deciding scope. - -- Invoke **ui-codebase-analyzer** using Agent tool - - `subagent_type: "dev-workflows-frontend:ui-codebase-analyzer"` - - `description: "UI fact collection for adjustment"` - - `prompt: "requirement_analysis: { affectedFiles: [files inferred from the adjustment request], scale: 'unknown', 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]. Extract UI facts: visual structure, props patterns, CSS layout state, state x display matrix, display conditions, i18n format, accessibility, generated artifact readiness."` -- Read the JSON output. The `analysisScope.filesAnalyzed` list, `componentStructure[]`, and `focusAreas[]` drive the scale judgment in Step 3. - -**Completion gate**: ui-codebase-analyzer returned a JSON output with at least one `componentStructure` entry or `focusAreas` entry (or escalated `limitations`). +- 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: 'unknown', 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."` +- Read the JSON output. `analysisScope.filesAnalyzed`, `componentStructure[]`, `externalResources.*`, and `focusAreas[]` drive the scale judgment in Step 3 and the adjustment loop in Step 5. ### Step 3: Scale Judgment -Determine the document and plan footprint using the Creation Decision Matrix in the documentation-criteria skill (see its `Creation Decision Matrix` section). - -1. Count distinct files that the adjustment will modify, using the ui-codebase-analyzer output as the evidence base. -2. Apply the matrix to the file count: - - **1-2 files**: Direct implementation. No work plan, no Design Doc. - - **3-5 files**: Work plan recommended; Design Doc optional and typically not needed for adjustment work. - - **6+ files**: Adjustment scope exceeded. Escalate to the user — this should run through the full frontend design phase, not adjustment. -3. Also escalate (regardless of file count) when any ADR Creation Condition from documentation-criteria applies (architecture changes, contract changes affecting 3+ locations, complex multi-state logic, etc.). These signal that adjustment is the wrong recipe. +Determine the work footprint using the Creation Decision Matrix in the documentation-criteria skill. -**Escalation message format** (when scope exceeded): "This change touches [N] files / matches ADR condition [X]. Adjustment scope is 1-5 files without architecture changes. Recommend running the full frontend design phase first to produce UI Spec / Design Doc, then planning, then implementation." - -**Completion gate**: scope is confirmed within adjustment range, or escalation has been delivered. +1. Count distinct files that the adjustment will modify, using the ui-analyzer output as the evidence base. +2. Apply the matrix: + - **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 from Step 3. +Branch on the scale outcome. #### Branch A — 1-2 files -No work plan needed. Build a minimal handoff packet for the implementation phase containing: +No work plan. Build a minimal adjustment context for the parent session: - Adjustment request (verbatim) -- ui-codebase-analyzer focusAreas[] with `ui:` prefix preserved +- ui-analyzer focusAreas[] with `ui:` prefix preserved - Affected files list -- External Resources Used: feature-tier subset relevant to this adjustment, referencing project-tier entries +- External resources fetched_summary and access methods that the verification loop will use -The packet is the prompt input the user will pass to the implementation recipe in Step 5. Present the packet to the user for inspection before handoff. +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 codebase analysis: [ui-codebase-analyzer JSON]. External resources: [project-tier file path]. 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"` +- `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 the revised guidance. - -**Completion gate**: Branch A handoff packet is presented to the user, OR Branch B work plan is approved. +- **[STOP]**: Wait for plan approval or revision request. If the user requests changes, re-invoke work-planner with revised guidance. -### Step 5: Implementation Handoff -Inform the user how to proceed. The exact recipe to run is announced in the user-facing message; this recipe does not invoke the implementation phase itself. +### Step 5: Adjustment + MCP Verification (parent session) +This is the loop the parent session runs directly. Subagents are not used here because their `tools` allowlist excludes MCP and would break the verification step. -#### Branch A handoff message -``` -Adjustment preparation complete (1-2 files, direct implementation). +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 the access methods from `docs/project-context/external-resources.md`: + - Design origin via the configured design-tool MCP (compare current rendering vs design source) + - Visual verification via the configured browser MCP (capture screenshot, check layout) + - Design system catalog via the configured design-system MCP (confirm component variants and tokens) +4. **Refine and re-verify** until the adjustment matches the design source. +5. When the adjustment unit converges, proceed to Step 6 for that unit. -Handoff packet: -- Adjustment request: -- Affected files: -- UI focus areas: -- External resources used: +When the user has not configured an MCP that the verification step would normally use, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). -To execute: run /recipe-front-build with this packet as the request input. -``` +### Step 6: Quality Verification (per adjustment unit) +Delegate quality checks. quality-fixer-frontend runs typecheck / lint / test / format and fixes issues — these do not require MCP access. -#### Branch B handoff message -``` -Adjustment preparation complete (3-5 files, work plan approved). +- Invoke **quality-fixer-frontend** using Agent tool + - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` + - `description: "Quality verification for adjustment unit"` + - `prompt: "task_file: [path to the work plan phase or, for Branch A, a synthesized scope description]. Run quality checks across the adjustment unit's affected files."` +- Parse the response per subagents-orchestration-guide: + - `approved` → proceed to Step 7 + - `stub_detected` → return to Step 5 to complete the implementation, then re-run quality-fixer-frontend + - `blocked` → escalate to user with the blocking issue and stop -- Work plan: docs/plans/[plan-name].md -- External resources file: docs/project-context/external-resources.md +### 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. -To execute: run /recipe-front-build (it will pick up the work plan automatically). -``` +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 exists or update was explicitly skipped) -- [ ] ui-codebase-analyzer returned a JSON output, and its `focusAreas` were considered in the scale judgment -- [ ] Scale judgment per documentation-criteria's Creation Decision Matrix is recorded -- [ ] When 6+ files or ADR conditions detected → escalation delivered (recipe stops here) -- [ ] When 1-2 files → handoff packet presented to the user -- [ ] When 3-5 files → work plan created and approved -- [ ] Implementation handoff message delivered +- [ ] External resource hearing executed (project-tier file written or update explicitly skipped) +- [ ] ui-analyzer returned a JSON output, including externalResources fetch_status per axis +- [ ] Scale judgment applied; 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 via MCP (or manual fallback when MCP absent) +- [ ] Each adjustment unit passed quality-fixer-frontend +- [ ] Each adjustment unit committed ## Output Example ``` -Frontend adjustment preparation completed. +Frontend adjustment completed. - External resources: docs/project-context/external-resources.md (updated|unchanged) -- UI fact collection: ui-codebase-analyzer focused on [N] components, [M] focus areas +- 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: -- Next step: +- 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 92467c0..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 → external resource hearing → ui-spec-designer → codebase-analyzer + ui-codebase-analyzer (parallel) → 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 @@ -26,9 +26,9 @@ Requirements → requirement-analyzer → [Stop: Scale determination] ↓ external resource hearing (frontend domain) ↓ - ui-spec-designer → [Stop: UI Spec approval] + codebase-analyzer + ui-analyzer (parallel) ↓ - codebase-analyzer + ui-codebase-analyzer (parallel) + ui-spec-designer → [Stop: UI Spec approval] ↓ technical-designer-frontend ↓ @@ -42,8 +42,8 @@ Requirements → requirement-analyzer → [Stop: Scale determination] **Included in this skill**: - Requirement analysis with requirement-analyzer - 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) -- Codebase analysis with codebase-analyzer and ui-codebase-analyzer in parallel (before technical design) - ADR creation (if architecture changes, new technology, or data flow changes) - Design Doc creation with technical-designer-frontend - Design Doc verification with code-verifier (before document review) @@ -62,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"` @@ -71,20 +71,20 @@ Once the user has answered the three dialogue questions above, execute the proce - **[STOP]**: Review requirement analysis results and address question items ### Step 1.5: External Resource Hearing -Per the external-resource-context skill, capture access methods for resources outside the repository (design origin, design system, guidelines, visual verification environment) before any document is drafted. This step runs in the orchestrator directly because it needs AskUserQuestion. +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."` -1. **File-existence check**: Run `! ls docs/project-context/external-resources.md 2>/dev/null` to detect the project-tier file. -2. **Branch on existence**: - - **Absent** → run the full hearing for the frontend domain (axes from `references/frontend.md` of the external-resource-context skill). - - **Present** → AskUserQuestion: "`docs/project-context/external-resources.md` exists. Update it for this work? (no / yes-full / yes-diff-only)". On `no` skip to Step 2. On `yes-full` run the full hearing. On `yes-diff-only` AskUserQuestion which axes changed and run hearing only on those. -3. **Two-phase hearing** when running hearing: - - For each frontend axis (Design Origin, Design System, Guidelines, Visual Verification Environment), use AskUserQuestion with the choices listed in the skill's `references/frontend.md`. Always include "対象外 / not applicable" as a choice. For each non-N/A axis, follow up with an access-method question. - - After the structured axes, AskUserQuestion once: "Are there any other frontend external resources for this work that the structured questions did not cover? If yes, describe them in your next message." Append the free-form answer under "Additional resources" in the project-tier file. -4. **Persist**: Write or update `docs/project-context/external-resources.md` per the template in the skill's `references/template.md`. Create the directory if absent. -5. The feature-tier `## External Resources Used` section inside the UI Spec is filled later by ui-spec-designer (in Step 2) using this project-tier file as the source. +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 2: UI Specification Phase -After requirement analysis approval, ask the user about prototype code: +### 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." @@ -94,30 +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 and ui-codebase-analyzer **in parallel** (single message with two Agent tool calls — they share input but produce complementary output): -- 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-codebase-analyzer** using Agent tool (parallel with the call above) - - `subagent_type: "dev-workflows-frontend:ui-codebase-analyzer"`, `description: "UI codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. ui_spec_path: [path from Step 2]. requirements: [user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)."` - -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-analyzer output JSON]. UI codebase analysis: [ui-codebase-analyzer output JSON]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply ui: prefix to fact_ids from UI codebase analysis when filling the Fact Disposition Table. 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 @@ -125,8 +121,8 @@ Create appropriate design documents according to scale determination. technical- ## Completion Criteria - [ ] Executed requirement-analyzer and determined scale -- [ ] Executed external resource hearing per the external-resource-context skill (`docs/project-context/external-resources.md` exists or update was explicitly skipped by the user) -- [ ] Executed codebase-analyzer and ui-codebase-analyzer in parallel and passed both results to 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) @@ -139,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 83dd1c2..75cd0dc 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -38,7 +38,7 @@ 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 (data, contracts, dependencies, quality assurance mechanisms) -8. **ui-codebase-analyzer**: Analyze existing UI code for visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts (frontend/fullstack features; runs in parallel with codebase-analyzer) +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 @@ -168,12 +168,12 @@ 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-codebase-analyzer) -- subagent_type: "ui-codebase-analyzer" -- description: "UI codebase analysis" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. ui_spec_path: [path if exists]. requirements: [original user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)." +### 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 technical-designer-frontend. +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" @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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-codebase-analyzer**: analysisScope.uiConventions, componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 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/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index b225e23..63f0e79 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -71,11 +71,7 @@ Must be performed at the beginning of Design Doc creation: - [ ] If any agreements are not reflected, state the reason ### External Resources Integration [Gate 0 — Required] -Per the external-resource-context skill, the Design Doc carries an "External Resources Used" subsection under Background and Context. - -1. **Read project-tier file** - Consult `docs/project-context/external-resources.md` (when present) for environment-stable access details. Do not duplicate URLs or MCP names into the Design Doc. -2. **List feature-specific subset** - Identify which resources are used by this feature and record their feature-specific identifiers (specific endpoint paths, IaC modules, schema source paths, etc.) in the External Resources Used table. -3. **Escalate when missing** - When the project-tier file is absent and the design references external resources, escalate so the orchestrating recipe can run the hearing protocol before the Design Doc completes. +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: diff --git a/dev-workflows/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index 7a9a02c..ebb88b4 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -35,14 +35,12 @@ unknowns: ### External Resources Used -This feature depends on resources outside the repository (design source, design system, API schema, IaC source, secret store, etc.). Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This subsection lists only the resources used by this feature and any feature-specific identifiers. +Filled per the external-resource-context skill (feature-tier protocol). | Resource (project-tier label) | Feature-specific identifier | Notes | |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | -Resources not used by this feature are omitted. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before continuing this Design Doc. - ### Agreement Checklist #### Scope 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 98e55b7..66c14eb 100644 --- a/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md @@ -24,16 +24,14 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification ## External Resources Used -This feature depends on resources outside the repository. Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This section lists only the resources used by this feature and any feature-specific identifiers (e.g., a particular node within the design source, specific components from the design system). +Filled per the external-resource-context skill (feature-tier protocol). | Resource (project-tier label) | Feature-specific identifier | Notes | |-------------------------------|-----------------------------|-------| -| Design Origin | [e.g., node id / frame id, or "all screens listed below"] | [e.g., entry point, screen mapping] | +| 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] | -Resources not used by this feature are omitted from this table. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before completing this UI Spec. - ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. diff --git a/dev-workflows/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows/skills/recipe-fullstack-implement/SKILL.md index 44012f1..7c2ce20 100644 --- a/dev-workflows/skills/recipe-fullstack-implement/SKILL.md +++ b/dev-workflows/skills/recipe-fullstack-implement/SKILL.md @@ -44,7 +44,15 @@ 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. External Resource Hearing + +Run the hearing protocol per the external-resource-context skill before fact gathering and document creation. The orchestrator owns this step (it requires AskUserQuestion). Cover the domains relevant to this fullstack scope: frontend (always for fullstack-implement), backend / api / infra as applicable. The skill defines file-existence branching, two-phase hearing, and persistence to `docs/project-context/external-resources.md`. + +### 4. Fact Gathering Phase (Parallel) + +Per monorepo-flow.md, invoke codebase-analyzer ×2 (one per layer) and ui-analyzer in parallel. ui-analyzer reads the project-tier external-resources file and fetches external UI sources via the inherited MCP/URL access methods. All three outputs feed downstream phases. + +### 5. UI Specification Phase (Frontend Layer) Before creating the frontend Design Doc, create a UI Specification: @@ -54,16 +62,16 @@ Before creating the frontend Design Doc, create a UI Specification: 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."` +- Pass: PRD path (or requirement-analyzer output), `ui_analysis` JSON from Step 4, prototype path when provided +- Example: `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from ui-analyzer]. Prototype code is at [user-provided path]."` Invoke **document-reviewer** for UI Spec review, then **[STOP]** for user approval. -### 4. Design Phase and Work Planning +### 6. Design Phase and Work Planning **Follow monorepo-flow.md** for the complete design-through-planning flow. Key points: - 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 must reference the approved UI Spec** (pass UI Spec path to technical-designer-frontend) and reuse the ui-analyzer output from Step 4 - 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 diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 83dd1c2..75cd0dc 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -38,7 +38,7 @@ 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 (data, contracts, dependencies, quality assurance mechanisms) -8. **ui-codebase-analyzer**: Analyze existing UI code for visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts (frontend/fullstack features; runs in parallel with codebase-analyzer) +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 @@ -168,12 +168,12 @@ 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-codebase-analyzer) -- subagent_type: "ui-codebase-analyzer" -- description: "UI codebase analysis" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. ui_spec_path: [path if exists]. requirements: [original user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)." +### 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 technical-designer-frontend. +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" @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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-codebase-analyzer**: analysisScope.uiConventions, componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 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/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index 7a9a02c..ebb88b4 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -35,14 +35,12 @@ unknowns: ### External Resources Used -This feature depends on resources outside the repository (design source, design system, API schema, IaC source, secret store, etc.). Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This subsection lists only the resources used by this feature and any feature-specific identifiers. +Filled per the external-resource-context skill (feature-tier protocol). | Resource (project-tier label) | Feature-specific identifier | Notes | |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | -Resources not used by this feature are omitted. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before continuing this Design Doc. - ### Agreement Checklist #### Scope diff --git a/skills/documentation-criteria/references/ui-spec-template.md b/skills/documentation-criteria/references/ui-spec-template.md index 98e55b7..66c14eb 100644 --- a/skills/documentation-criteria/references/ui-spec-template.md +++ b/skills/documentation-criteria/references/ui-spec-template.md @@ -24,16 +24,14 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification ## External Resources Used -This feature depends on resources outside the repository. Environment access details (URLs, MCP names, file paths) are recorded once in `docs/project-context/external-resources.md`. This section lists only the resources used by this feature and any feature-specific identifiers (e.g., a particular node within the design source, specific components from the design system). +Filled per the external-resource-context skill (feature-tier protocol). | Resource (project-tier label) | Feature-specific identifier | Notes | |-------------------------------|-----------------------------|-------| -| Design Origin | [e.g., node id / frame id, or "all screens listed below"] | [e.g., entry point, screen mapping] | +| 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] | -Resources not used by this feature are omitted from this table. If `docs/project-context/external-resources.md` does not yet exist, run the `external-resource-context` skill before completing this UI Spec. - ## AC Traceability (Prototype) Map PRD acceptance criteria to prototype references. Skip this section if no prototype is provided. diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index 20e8305..bcb0249 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -1,164 +1,157 @@ --- name: recipe-front-adjust -description: Coordinate a frontend UI adjustment from external resource hearing through scale-driven plan decision, UI fact collection, and handoff to the implementation phase. Use when "UI adjustment / visual tweak / existing component update / front adjust" is mentioned, or when the user wants to refine an already-implemented UI without redoing the full design phase. +description: Coordinate a frontend UI adjustment by hearing external resources, gathering UI facts, scaling the work, optionally creating a work plan, executing the adjustment in this session with MCP-driven verification, and delegating quality checks. Use when "UI adjustment / visual tweak / existing component update / front adjust" is mentioned, or when the user wants to refine an already-implemented UI. disable-model-invocation: true --- -**Context**: Dedicated to UI adjustment workflows on already-implemented features. Lighter than the full design phase but heavier than direct implementation, this recipe captures the small-but-essential preparation that adjustment work needs: external resource access, fact-grounded baseline, and a right-sized work plan. +**Context**: Dedicated to UI adjustment workflows on already-implemented features. Unlike recipe-front-design (document creation, fully delegated) and recipe-front-build (specified implementation, fully delegated), adjustment work depends on iterative MCP-driven verification (compare with design source, verify visual rendering, refine, re-verify). MCP access is held by the parent session — not by subagents whose `tools` allowlist excludes MCP. This recipe therefore runs the adjustment itself in the parent session and delegates only the steps that do not require MCP. -## Orchestrator Definition +## Execution Pattern -**Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Core Identity**: "I am a guided executor. Subagents handle UI fact gathering, work plan creation, and quality checks; I run the adjustment and the MCP-driven verification loop myself." **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 the steps defined below in order**. Each step has an explicit completion gate. -3. **Hand off to the implementation phase** when adjustment preparation is complete. This recipe does not run task execution or quality fixing itself. +1. **Delegate** to subagents for: external-resource hearing storage (none — orchestrator runs hearing directly via AskUserQuestion), UI fact gathering (ui-analyzer), work plan creation (work-planner), quality checks (quality-fixer-frontend). +2. **Run myself** in the parent session: AskUserQuestion hearing, scale judgment, the actual adjustment edits, MCP-driven verification (e.g., compare CSS against design source, check visual rendering via browser MCP), and the iteration loop until acceptance. +3. **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding. 4. **Scope**: see Scope Boundaries below. -**CRITICAL**: This recipe ends at the implementation handoff. Do not invoke task-executor or quality-fixer from this recipe — those belong to the implementation recipe family. Doing so bypasses the readiness gates owned by that family. +**Why this differs from other recipes**: Adjustment requires MCP loops that subagents cannot perform (their `tools` allowlist excludes MCP). Delegating implementation to task-executor-frontend would break the verification loop. The recipe runs the loop in the parent session, where the user's full MCP set is available. ## Workflow Overview ``` -Adjustment request → external resource hearing (frontend domain) +Adjustment request → external resource hearing (parent session, AskUserQuestion) ↓ - ui-codebase-analyzer (UI fact collection) + ui-analyzer (subagent: fetch external sources + analyze code) ↓ - scale judgment (documentation-criteria) + scale judgment (parent session, documentation-criteria matrix) ↓ ┌────────────────────┴────────────────────┐ ↓ ↓ - (1-2 files: inline) (3+ files: work-planner → [Stop: plan approval]) + (1-2 files: inline) (3-5 files: work-planner subagent → [Stop]) ↓ ↓ - └───────────────→ implementation handoff ──┘ + └─→ adjustment + MCP 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 (frontend domain) -- UI fact collection via ui-codebase-analyzer +- External resource hearing per the external-resource-context skill +- UI fact gathering via ui-analyzer - Scale judgment via documentation-criteria's Creation Decision Matrix -- Work plan creation via work-planner when scale warrants it -- Implementation handoff (user-facing announcement) +- Optional work plan creation via work-planner +- Adjustment edits and MCP-driven verification (run in this session) +- Quality verification via quality-fixer-frontend +- Commit per adjustment unit -**Responsibility Boundary**: This skill completes when (a) the user is informed which implementation path to run, and (b) any required work plan has been approved. Task decomposition, implementation, and quality verification are out of scope and belong to the implementation phase. +**Responsibility Boundary**: This skill completes when the adjustment is committed and quality has passed. Adjustment work is end-to-end within this recipe; it does not hand off to other implementation recipes. **Out of scope**: -- Creating PRD, UI Spec, or Design Doc — adjustment work uses existing documents. When the requested change exceeds adjustment scope (new feature, new architecture, multi-screen redesign), escalate the user to the full frontend design phase. -- Running task-executor / quality-fixer / code-verifier / security-reviewer. +- Creating PRD, UI Spec, or Design Doc — adjustment work uses existing documents. When the requested change exceeds adjustment scope (new feature, new architecture, multi-screen redesign, or any ADR Creation Condition from documentation-criteria), escalate the user to the full frontend design phase. Adjustment request: $ARGUMENTS ## Execution Flow ### Step 1: External Resource Hearing -Per the external-resource-context skill, capture access methods for the frontend resources this adjustment will touch (design origin, design system, guidelines, visual verification environment). - -1. **File-existence check**: Run `! ls docs/project-context/external-resources.md 2>/dev/null` to detect the project-tier file. -2. **Branch on existence**: - - **Absent** → run the full hearing for the frontend domain (axes from `references/frontend.md` of the external-resource-context skill). - - **Present** → AskUserQuestion: "`docs/project-context/external-resources.md` exists. Update it for this adjustment? (no / yes-full / yes-diff-only)". On `no` skip to Step 2. On `yes-full` run the full hearing. On `yes-diff-only` AskUserQuestion which axes changed and run hearing only on those. -3. **Two-phase hearing** when running hearing: - - For each frontend axis (Design Origin, Design System, Guidelines, Visual Verification Environment), use AskUserQuestion with the choices listed in the skill's `references/frontend.md`. Always include "対象外 / not applicable" as a choice. For each non-N/A axis, follow up with an access-method question. - - After the structured axes, AskUserQuestion once: "Are there any other frontend external resources for this adjustment that the structured questions did not cover? If yes, describe them in your next message." Append the free-form answer under "Additional resources" in the project-tier file. -4. **Persist**: Write or update `docs/project-context/external-resources.md` per the template in the skill's `references/template.md`. +Run the hearing protocol per the external-resource-context skill (frontend domain). The parent session 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`. -**Completion gate**: `docs/project-context/external-resources.md` reflects the resources this adjustment depends on, or the user explicitly opted out of updating. +### Step 2: UI Fact Gathering +Ground the adjustment in observable facts before scoping the work. ui-analyzer reads the project-tier external-resources file and fetches external UI sources (design origin, design system catalog, guidelines) via the inherited MCP/URL access methods, then analyzes the existing UI codebase. Heavy fetches stay inside the subagent's own context. -### Step 2: UI Fact Collection -Ground the adjustment in observable facts about the existing UI before deciding scope. - -- Invoke **ui-codebase-analyzer** using Agent tool - - `subagent_type: "dev-workflows-frontend:ui-codebase-analyzer"` - - `description: "UI fact collection for adjustment"` - - `prompt: "requirement_analysis: { affectedFiles: [files inferred from the adjustment request], scale: 'unknown', 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]. Extract UI facts: visual structure, props patterns, CSS layout state, state x display matrix, display conditions, i18n format, accessibility, generated artifact readiness."` -- Read the JSON output. The `analysisScope.filesAnalyzed` list, `componentStructure[]`, and `focusAreas[]` drive the scale judgment in Step 3. - -**Completion gate**: ui-codebase-analyzer returned a JSON output with at least one `componentStructure` entry or `focusAreas` entry (or escalated `limitations`). +- 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: 'unknown', 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."` +- Read the JSON output. `analysisScope.filesAnalyzed`, `componentStructure[]`, `externalResources.*`, and `focusAreas[]` drive the scale judgment in Step 3 and the adjustment loop in Step 5. ### Step 3: Scale Judgment -Determine the document and plan footprint using the Creation Decision Matrix in the documentation-criteria skill (see its `Creation Decision Matrix` section). - -1. Count distinct files that the adjustment will modify, using the ui-codebase-analyzer output as the evidence base. -2. Apply the matrix to the file count: - - **1-2 files**: Direct implementation. No work plan, no Design Doc. - - **3-5 files**: Work plan recommended; Design Doc optional and typically not needed for adjustment work. - - **6+ files**: Adjustment scope exceeded. Escalate to the user — this should run through the full frontend design phase, not adjustment. -3. Also escalate (regardless of file count) when any ADR Creation Condition from documentation-criteria applies (architecture changes, contract changes affecting 3+ locations, complex multi-state logic, etc.). These signal that adjustment is the wrong recipe. +Determine the work footprint using the Creation Decision Matrix in the documentation-criteria skill. -**Escalation message format** (when scope exceeded): "This change touches [N] files / matches ADR condition [X]. Adjustment scope is 1-5 files without architecture changes. Recommend running the full frontend design phase first to produce UI Spec / Design Doc, then planning, then implementation." - -**Completion gate**: scope is confirmed within adjustment range, or escalation has been delivered. +1. Count distinct files that the adjustment will modify, using the ui-analyzer output as the evidence base. +2. Apply the matrix: + - **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 from Step 3. +Branch on the scale outcome. #### Branch A — 1-2 files -No work plan needed. Build a minimal handoff packet for the implementation phase containing: +No work plan. Build a minimal adjustment context for the parent session: - Adjustment request (verbatim) -- ui-codebase-analyzer focusAreas[] with `ui:` prefix preserved +- ui-analyzer focusAreas[] with `ui:` prefix preserved - Affected files list -- External Resources Used: feature-tier subset relevant to this adjustment, referencing project-tier entries +- External resources fetched_summary and access methods that the verification loop will use -The packet is the prompt input the user will pass to the implementation recipe in Step 5. Present the packet to the user for inspection before handoff. +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 codebase analysis: [ui-codebase-analyzer JSON]. External resources: [project-tier file path]. 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"` +- `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 the revised guidance. - -**Completion gate**: Branch A handoff packet is presented to the user, OR Branch B work plan is approved. +- **[STOP]**: Wait for plan approval or revision request. If the user requests changes, re-invoke work-planner with revised guidance. -### Step 5: Implementation Handoff -Inform the user how to proceed. The exact recipe to run is announced in the user-facing message; this recipe does not invoke the implementation phase itself. +### Step 5: Adjustment + MCP Verification (parent session) +This is the loop the parent session runs directly. Subagents are not used here because their `tools` allowlist excludes MCP and would break the verification step. -#### Branch A handoff message -``` -Adjustment preparation complete (1-2 files, direct implementation). +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 the access methods from `docs/project-context/external-resources.md`: + - Design origin via the configured design-tool MCP (compare current rendering vs design source) + - Visual verification via the configured browser MCP (capture screenshot, check layout) + - Design system catalog via the configured design-system MCP (confirm component variants and tokens) +4. **Refine and re-verify** until the adjustment matches the design source. +5. When the adjustment unit converges, proceed to Step 6 for that unit. -Handoff packet: -- Adjustment request: -- Affected files: -- UI focus areas: -- External resources used: +When the user has not configured an MCP that the verification step would normally use, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). -To execute: run /recipe-front-build with this packet as the request input. -``` +### Step 6: Quality Verification (per adjustment unit) +Delegate quality checks. quality-fixer-frontend runs typecheck / lint / test / format and fixes issues — these do not require MCP access. -#### Branch B handoff message -``` -Adjustment preparation complete (3-5 files, work plan approved). +- Invoke **quality-fixer-frontend** using Agent tool + - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` + - `description: "Quality verification for adjustment unit"` + - `prompt: "task_file: [path to the work plan phase or, for Branch A, a synthesized scope description]. Run quality checks across the adjustment unit's affected files."` +- Parse the response per subagents-orchestration-guide: + - `approved` → proceed to Step 7 + - `stub_detected` → return to Step 5 to complete the implementation, then re-run quality-fixer-frontend + - `blocked` → escalate to user with the blocking issue and stop -- Work plan: docs/plans/[plan-name].md -- External resources file: docs/project-context/external-resources.md +### 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. -To execute: run /recipe-front-build (it will pick up the work plan automatically). -``` +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 exists or update was explicitly skipped) -- [ ] ui-codebase-analyzer returned a JSON output, and its `focusAreas` were considered in the scale judgment -- [ ] Scale judgment per documentation-criteria's Creation Decision Matrix is recorded -- [ ] When 6+ files or ADR conditions detected → escalation delivered (recipe stops here) -- [ ] When 1-2 files → handoff packet presented to the user -- [ ] When 3-5 files → work plan created and approved -- [ ] Implementation handoff message delivered +- [ ] External resource hearing executed (project-tier file written or update explicitly skipped) +- [ ] ui-analyzer returned a JSON output, including externalResources fetch_status per axis +- [ ] Scale judgment applied; 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 via MCP (or manual fallback when MCP absent) +- [ ] Each adjustment unit passed quality-fixer-frontend +- [ ] Each adjustment unit committed ## Output Example ``` -Frontend adjustment preparation completed. +Frontend adjustment completed. - External resources: docs/project-context/external-resources.md (updated|unchanged) -- UI fact collection: ui-codebase-analyzer focused on [N] components, [M] focus areas +- 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: -- Next step: +- 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 92467c0..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 → external resource hearing → ui-spec-designer → codebase-analyzer + ui-codebase-analyzer (parallel) → 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 @@ -26,9 +26,9 @@ Requirements → requirement-analyzer → [Stop: Scale determination] ↓ external resource hearing (frontend domain) ↓ - ui-spec-designer → [Stop: UI Spec approval] + codebase-analyzer + ui-analyzer (parallel) ↓ - codebase-analyzer + ui-codebase-analyzer (parallel) + ui-spec-designer → [Stop: UI Spec approval] ↓ technical-designer-frontend ↓ @@ -42,8 +42,8 @@ Requirements → requirement-analyzer → [Stop: Scale determination] **Included in this skill**: - Requirement analysis with requirement-analyzer - 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) -- Codebase analysis with codebase-analyzer and ui-codebase-analyzer in parallel (before technical design) - ADR creation (if architecture changes, new technology, or data flow changes) - Design Doc creation with technical-designer-frontend - Design Doc verification with code-verifier (before document review) @@ -62,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"` @@ -71,20 +71,20 @@ Once the user has answered the three dialogue questions above, execute the proce - **[STOP]**: Review requirement analysis results and address question items ### Step 1.5: External Resource Hearing -Per the external-resource-context skill, capture access methods for resources outside the repository (design origin, design system, guidelines, visual verification environment) before any document is drafted. This step runs in the orchestrator directly because it needs AskUserQuestion. +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."` -1. **File-existence check**: Run `! ls docs/project-context/external-resources.md 2>/dev/null` to detect the project-tier file. -2. **Branch on existence**: - - **Absent** → run the full hearing for the frontend domain (axes from `references/frontend.md` of the external-resource-context skill). - - **Present** → AskUserQuestion: "`docs/project-context/external-resources.md` exists. Update it for this work? (no / yes-full / yes-diff-only)". On `no` skip to Step 2. On `yes-full` run the full hearing. On `yes-diff-only` AskUserQuestion which axes changed and run hearing only on those. -3. **Two-phase hearing** when running hearing: - - For each frontend axis (Design Origin, Design System, Guidelines, Visual Verification Environment), use AskUserQuestion with the choices listed in the skill's `references/frontend.md`. Always include "対象外 / not applicable" as a choice. For each non-N/A axis, follow up with an access-method question. - - After the structured axes, AskUserQuestion once: "Are there any other frontend external resources for this work that the structured questions did not cover? If yes, describe them in your next message." Append the free-form answer under "Additional resources" in the project-tier file. -4. **Persist**: Write or update `docs/project-context/external-resources.md` per the template in the skill's `references/template.md`. Create the directory if absent. -5. The feature-tier `## External Resources Used` section inside the UI Spec is filled later by ui-spec-designer (in Step 2) using this project-tier file as the source. +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 2: UI Specification Phase -After requirement analysis approval, ask the user about prototype code: +### 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." @@ -94,30 +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 and ui-codebase-analyzer **in parallel** (single message with two Agent tool calls — they share input but produce complementary output): -- 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-codebase-analyzer** using Agent tool (parallel with the call above) - - `subagent_type: "dev-workflows-frontend:ui-codebase-analyzer"`, `description: "UI codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. ui_spec_path: [path from Step 2]. requirements: [user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)."` - -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-analyzer output JSON]. UI codebase analysis: [ui-codebase-analyzer output JSON]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply ui: prefix to fact_ids from UI codebase analysis when filling the Fact Disposition Table. 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 @@ -125,8 +121,8 @@ Create appropriate design documents according to scale determination. technical- ## Completion Criteria - [ ] Executed requirement-analyzer and determined scale -- [ ] Executed external resource hearing per the external-resource-context skill (`docs/project-context/external-resources.md` exists or update was explicitly skipped by the user) -- [ ] Executed codebase-analyzer and ui-codebase-analyzer in parallel and passed both results to 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) @@ -139,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..7c2ce20 100644 --- a/skills/recipe-fullstack-implement/SKILL.md +++ b/skills/recipe-fullstack-implement/SKILL.md @@ -44,7 +44,15 @@ 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. External Resource Hearing + +Run the hearing protocol per the external-resource-context skill before fact gathering and document creation. The orchestrator owns this step (it requires AskUserQuestion). Cover the domains relevant to this fullstack scope: frontend (always for fullstack-implement), backend / api / infra as applicable. The skill defines file-existence branching, two-phase hearing, and persistence to `docs/project-context/external-resources.md`. + +### 4. Fact Gathering Phase (Parallel) + +Per monorepo-flow.md, invoke codebase-analyzer ×2 (one per layer) and ui-analyzer in parallel. ui-analyzer reads the project-tier external-resources file and fetches external UI sources via the inherited MCP/URL access methods. All three outputs feed downstream phases. + +### 5. UI Specification Phase (Frontend Layer) Before creating the frontend Design Doc, create a UI Specification: @@ -54,16 +62,16 @@ Before creating the frontend Design Doc, create a UI Specification: 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."` +- Pass: PRD path (or requirement-analyzer output), `ui_analysis` JSON from Step 4, prototype path when provided +- Example: `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from ui-analyzer]. Prototype code is at [user-provided path]."` Invoke **document-reviewer** for UI Spec review, then **[STOP]** for user approval. -### 4. Design Phase and Work Planning +### 6. Design Phase and Work Planning **Follow monorepo-flow.md** for the complete design-through-planning flow. Key points: - 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 must reference the approved UI Spec** (pass UI Spec path to technical-designer-frontend) and reuse the ui-analyzer output from Step 4 - 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 diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 83dd1c2..75cd0dc 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -38,7 +38,7 @@ 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 (data, contracts, dependencies, quality assurance mechanisms) -8. **ui-codebase-analyzer**: Analyze existing UI code for visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, and generated UI artifacts (frontend/fullstack features; runs in parallel with codebase-analyzer) +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 @@ -168,12 +168,12 @@ 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-codebase-analyzer) -- subagent_type: "ui-codebase-analyzer" -- description: "UI codebase analysis" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. ui_spec_path: [path if exists]. requirements: [original user requirements]. Extract UI facts (visual structure, layout state, props patterns, state matrices, display conditions, i18n, accessibility, generated artifacts)." +### 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 technical-designer-frontend. +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" @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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-codebase-analyzer**: analysisScope.uiConventions, componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 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. ``` From 84dc29737ddb169c52652ecdf40c352b7d9dfbef Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 22:44:42 +0900 Subject: [PATCH 06/16] fix: review-driven corrections (P1-P3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review identified critical execution-precision issues. Apply fixes in priority order. P1 — execution-correctness (was broken): 1. ui-analyzer frontmatter MCP inheritance bug. The agent had both tools: (allowlist) and disallowedTools: set, so per Claude Code semantics the final tool set was the intersection — MCP tools were excluded despite the body claiming inheritance. Remove the tools: field; rely on disallowedTools alone so the parent session's MCP set is inherited. The agent's core purpose (containing heavy MCP fetches in its own context) only works after this fix. 2. recipe-front-adjust task_file contract. Previous text instructed the orchestrator to pass "synthesized scope description" as task_file when no work plan exists. quality-fixer-frontend expects task_file to be a path and uses filesModified for write set scope; a non-path falls back to git diff HEAD, which is empty after per-unit commits. Branch the prompt: Branch A omits task_file and passes filesModified explicitly; Branch B passes both an actual plan path and filesModified. 3. Backend executor and quality-fixers loaded the skill in frontmatter without a corresponding body section to act on it. Add concise External Resources Consultation sections to task-executor (backend), quality-fixer, and quality-fixer-frontend matching the pattern already present in task-executor-frontend. The trigger phrase in task-executor-frontend itself is also tightened from "When the task references an external resource" to a concrete trigger naming the task file's Investigation Targets, Dependencies, and external-resources file references. P2 — branching and routing precision: 4. Scale judgment in recipe-front-adjust used filesAnalyzed as the evidence base, but ui-analyzer's filesAnalyzed is the read set, not the write set. Add candidateWriteSet[] (with confidence labels) to ui-analyzer's output schema; recipe-front-adjust now confirms the write set with the user via AskUserQuestion before applying the Creation Decision Matrix. Workflow Overview and Completion Criteria reflect the new step. 5. recipe-front-adjust Execution Protocol bullet 1 mixed delegated and non-delegated items inside a single "Delegate" list. Split into "Delegate to subagents" and "Run in the parent session" so readers cannot mistake the hearing step for a delegated call. 6. Naming drift: technical-designer-frontend Input Parameters referenced "ui-codebase-analyzer" after the rename to ui-analyzer. Rename the section header and prose to match. 7. ui-analyzer prompt in recipe-front-adjust set scale: 'unknown', which is not a value requirement-analyzer's enum produces. Change to 'small' so downstream branching that consults scale has a defined value to work with. P3 — style and precision polish: 8. Positive-form rewrites for four BP-001 violations in skill and agent text (feature-tier ownership rule, hearing responsibility, MCP unavailable handling, heavy-fetch limit). 9. Feature-tier format unified: skill body example now points to the table format defined in references/template.md instead of demonstrating a free-form alternative. 10. ui-analyzer Quality Checklist gains explicit guidance that sections outside the affected scope should be emitted as empty arrays / minimal placeholders — preventing speculative enumeration that bloats the output for small adjustments. 11. recipe-front-adjust MCP wording: previous text generalized "subagents whose tools allowlist excludes MCP". Clarify that the verification loop's multi-step shape is what makes a single subagent call insufficient, while ui-analyzer (a one-shot subagent using disallowedTools) does inherit MCP correctly. Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/quality-fixer-frontend.md | 3 ++ agents/quality-fixer.md | 3 ++ agents/task-executor-frontend.md | 2 +- agents/task-executor.md | 3 ++ agents/technical-designer-frontend.md | 5 ++- agents/ui-analyzer.md | 29 +++++++++++--- .../skills/external-resource-context/SKILL.md | 4 +- .../agents/quality-fixer-frontend.md | 3 ++ .../agents/task-executor-frontend.md | 2 +- .../agents/technical-designer-frontend.md | 5 ++- dev-workflows-frontend/agents/ui-analyzer.md | 29 +++++++++++--- .../skills/external-resource-context/SKILL.md | 4 +- .../skills/recipe-front-adjust/SKILL.md | 40 ++++++++++++------- dev-workflows/agents/quality-fixer.md | 3 ++ dev-workflows/agents/task-executor.md | 3 ++ .../skills/external-resource-context/SKILL.md | 4 +- skills/external-resource-context/SKILL.md | 4 +- skills/recipe-front-adjust/SKILL.md | 40 ++++++++++++------- 18 files changed, 132 insertions(+), 54 deletions(-) diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 8658d01..c8bb4dd 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -72,6 +72,9 @@ 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 Relevant)**: +When a quality check depends on an external resource (e.g., a generated CSS-module typings file, a generated message catalog, a contract test fixture from an upstream service, or a visual regression baseline), consult it per the external-resource-context skill (Reference Protocol). Escalate via `blocked` with `reason: "Execution prerequisites not met"` and `missingPrerequisites` populated when the resource is referenced but unreachable. + ### 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 9e583ce..25732ce 100644 --- a/agents/quality-fixer.md +++ b/agents/quality-fixer.md @@ -69,6 +69,9 @@ 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 Relevant)**: +When a quality check depends on an external resource (e.g., a schema validator pointed at an external API spec, a test that consumes a recorded fixture from an upstream service, a generated artifact whose source lives outside the repository), consult it per the external-resource-context skill (Reference Protocol). Escalate via `blocked` with `reason: "Execution prerequisites not met"` and `missingPrerequisites` populated when the resource is referenced but unreachable. + ### 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 6d2d3a8..2c47ae3 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -155,7 +155,7 @@ Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and - Overall Design Document → Understand system-wide context #### External Resources Consultation (When Relevant) -When the task references an external resource, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. +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] diff --git a/agents/task-executor.md b/agents/task-executor.md index 94aa06b..d614046 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -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 9b7800c..17a1d2b 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -211,15 +211,16 @@ When conversion is required, clearly specify wrapper implementation or migration - `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 Codebase Analysis** (optional, from ui-codebase-analyzer; runs in parallel with Codebase Analysis): +- **UI Analysis** (optional, from ui-analyzer; 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 Codebase Analysis flag the same fact, merge into a single row with both evidence pointers + - 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 diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md index 5efc84e..317825e 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -1,7 +1,6 @@ --- 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. -tools: Read, Grep, Glob, LS, Bash, WebFetch, TaskCreate, TaskUpdate disallowedTools: Write, Edit, MultiEdit, NotebookEdit skills: typescript-rules, frontend-ai-guide, external-resource-context --- @@ -25,7 +24,7 @@ When a fact could fit either agent (e.g., a component's prop type), codebase-ana ## Tool Scope -This agent uses `disallowedTools` to inherit the parent session's full tool set including any MCP tools the user has installed, while denying file modification (Write, Edit, MultiEdit, NotebookEdit) — analysis only, no code changes. MCP tools (e.g., a design-tool MCP, a design-system catalog MCP, a browser MCP) are accessible if and only if they exist in the parent session. +This agent uses `disallowedTools` only (no `tools` allowlist) so the parent session's full tool set is inherited, including any MCP tools the user has installed. File modification (Write, Edit, MultiEdit, NotebookEdit) is denied — analysis only, no code changes. MCP tools (e.g., a design-tool MCP, a design-system catalog MCP, a browser MCP) are accessible if and only if they exist in the parent session. ## Input Parameters @@ -46,7 +45,7 @@ This agent outputs **UI fact gathering only**. Design decisions, component propo 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. Do not attempt hearing — that responsibility lies with the calling recipe. +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 recipe's responsibility. ### Step 2: External Resource Fetch (When Access Method Permits) @@ -59,9 +58,9 @@ For each present resource, fetch content using the access method: | 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. Do not block — proceed with the remaining sources. +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), narrow the request to the scope implied by `requirement_analysis.affectedFiles` and `target_components`. Do not retrieve the entire design surface when only a subset is in scope — this protects this agent's own context window from saturation. +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 @@ -158,6 +157,17 @@ For each generator (CSS module typings, message catalog typings, route typings, - Trigger condition - Downstream consumers (typecheck, test, build, runtime) +### Step 12: Candidate Write Set + +The set of files analyzed in Steps 3-11 is broader than the set the design or adjustment will modify. Produce a separate `candidateWriteSet[]` listing the files most likely to require modification given the input requirements, with a confidence label per entry. + +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) + +This list is a candidate, not a commitment — the calling recipe should treat it as input to a user-confirmed write set, not as the final scope. + ## Output Format ### Output Protocol @@ -293,6 +303,13 @@ For each generator (CSS module typings, message catalog typings, route typings, "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" ] @@ -315,4 +332,6 @@ For each generator (CSS module typings, message catalog typings, route typings, - [ ] i18n format details are concrete enough that a designer can author new keys without re-investigating - [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck/test/build/runtime - [ ] Focus areas have evidence pointers; no fact appears in focusAreas without a corresponding evidence entry +- [ ] `candidateWriteSet` is populated with at least the high-confidence entries; speculative entries use `confidence: "low"` +- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders, not enumerated speculatively (e.g., for a 1-2 file adjustment, `displayConditions` and `accessibility` may be `[]` if the scope does not touch them) - [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/dev-skills/skills/external-resource-context/SKILL.md b/dev-skills/skills/external-resource-context/SKILL.md index a52434e..e3022eb 100644 --- a/dev-skills/skills/external-resource-context/SKILL.md +++ b/dev-skills/skills/external-resource-context/SKILL.md @@ -26,9 +26,9 @@ Resources covered: design origin (where the canonical visual specification lives ### Single Source of Truth Rule -The project tier owns environment facts. The feature tier references the project tier by label and lists only feature-specific identifiers. Feature-tier sections never duplicate environment facts (URL, MCP name, access command). When the environment changes, only the project-tier file is updated. +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: `Design origin: project-tier "Design tool" entry; node id `. +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 diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 8658d01..c8bb4dd 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -72,6 +72,9 @@ 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 Relevant)**: +When a quality check depends on an external resource (e.g., a generated CSS-module typings file, a generated message catalog, a contract test fixture from an upstream service, or a visual regression baseline), consult it per the external-resource-context skill (Reference Protocol). Escalate via `blocked` with `reason: "Execution prerequisites not met"` and `missingPrerequisites` populated when the resource is referenced but unreachable. + ### 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 6d2d3a8..2c47ae3 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -155,7 +155,7 @@ Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and - Overall Design Document → Understand system-wide context #### External Resources Consultation (When Relevant) -When the task references an external resource, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. +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] diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 9b7800c..17a1d2b 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -211,15 +211,16 @@ When conversion is required, clearly specify wrapper implementation or migration - `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 Codebase Analysis** (optional, from ui-codebase-analyzer; runs in parallel with Codebase Analysis): +- **UI Analysis** (optional, from ui-analyzer; 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 Codebase Analysis flag the same fact, merge into a single row with both evidence pointers + - 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 diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md index 5efc84e..317825e 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -1,7 +1,6 @@ --- 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. -tools: Read, Grep, Glob, LS, Bash, WebFetch, TaskCreate, TaskUpdate disallowedTools: Write, Edit, MultiEdit, NotebookEdit skills: typescript-rules, frontend-ai-guide, external-resource-context --- @@ -25,7 +24,7 @@ When a fact could fit either agent (e.g., a component's prop type), codebase-ana ## Tool Scope -This agent uses `disallowedTools` to inherit the parent session's full tool set including any MCP tools the user has installed, while denying file modification (Write, Edit, MultiEdit, NotebookEdit) — analysis only, no code changes. MCP tools (e.g., a design-tool MCP, a design-system catalog MCP, a browser MCP) are accessible if and only if they exist in the parent session. +This agent uses `disallowedTools` only (no `tools` allowlist) so the parent session's full tool set is inherited, including any MCP tools the user has installed. File modification (Write, Edit, MultiEdit, NotebookEdit) is denied — analysis only, no code changes. MCP tools (e.g., a design-tool MCP, a design-system catalog MCP, a browser MCP) are accessible if and only if they exist in the parent session. ## Input Parameters @@ -46,7 +45,7 @@ This agent outputs **UI fact gathering only**. Design decisions, component propo 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. Do not attempt hearing — that responsibility lies with the calling recipe. +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 recipe's responsibility. ### Step 2: External Resource Fetch (When Access Method Permits) @@ -59,9 +58,9 @@ For each present resource, fetch content using the access method: | 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. Do not block — proceed with the remaining sources. +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), narrow the request to the scope implied by `requirement_analysis.affectedFiles` and `target_components`. Do not retrieve the entire design surface when only a subset is in scope — this protects this agent's own context window from saturation. +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 @@ -158,6 +157,17 @@ For each generator (CSS module typings, message catalog typings, route typings, - Trigger condition - Downstream consumers (typecheck, test, build, runtime) +### Step 12: Candidate Write Set + +The set of files analyzed in Steps 3-11 is broader than the set the design or adjustment will modify. Produce a separate `candidateWriteSet[]` listing the files most likely to require modification given the input requirements, with a confidence label per entry. + +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) + +This list is a candidate, not a commitment — the calling recipe should treat it as input to a user-confirmed write set, not as the final scope. + ## Output Format ### Output Protocol @@ -293,6 +303,13 @@ For each generator (CSS module typings, message catalog typings, route typings, "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" ] @@ -315,4 +332,6 @@ For each generator (CSS module typings, message catalog typings, route typings, - [ ] i18n format details are concrete enough that a designer can author new keys without re-investigating - [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck/test/build/runtime - [ ] Focus areas have evidence pointers; no fact appears in focusAreas without a corresponding evidence entry +- [ ] `candidateWriteSet` is populated with at least the high-confidence entries; speculative entries use `confidence: "low"` +- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders, not enumerated speculatively (e.g., for a 1-2 file adjustment, `displayConditions` and `accessibility` may be `[]` if the scope does not touch them) - [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/dev-workflows-frontend/skills/external-resource-context/SKILL.md b/dev-workflows-frontend/skills/external-resource-context/SKILL.md index a52434e..e3022eb 100644 --- a/dev-workflows-frontend/skills/external-resource-context/SKILL.md +++ b/dev-workflows-frontend/skills/external-resource-context/SKILL.md @@ -26,9 +26,9 @@ Resources covered: design origin (where the canonical visual specification lives ### Single Source of Truth Rule -The project tier owns environment facts. The feature tier references the project tier by label and lists only feature-specific identifiers. Feature-tier sections never duplicate environment facts (URL, MCP name, access command). When the environment changes, only the project-tier file is updated. +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: `Design origin: project-tier "Design tool" entry; node id `. +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 diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index bcb0249..b88b7e2 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -4,28 +4,30 @@ description: Coordinate a frontend UI adjustment by hearing external resources, disable-model-invocation: true --- -**Context**: Dedicated to UI adjustment workflows on already-implemented features. Unlike recipe-front-design (document creation, fully delegated) and recipe-front-build (specified implementation, fully delegated), adjustment work depends on iterative MCP-driven verification (compare with design source, verify visual rendering, refine, re-verify). MCP access is held by the parent session — not by subagents whose `tools` allowlist excludes MCP. This recipe therefore runs the adjustment itself in the parent session and delegates only the steps that do not require MCP. +**Context**: Dedicated to UI adjustment workflows on already-implemented features. Unlike recipe-front-design (document creation, fully delegated) and recipe-front-build (specified implementation, fully delegated), adjustment work depends on an iterative MCP-driven verification loop (compare with design source → adjust → re-verify) that needs to run alongside file edits. The standard implementation delegate (`task-executor-frontend`) uses a `tools` allowlist that excludes MCP, so the verification loop cannot run inside it. This recipe therefore performs the adjustment and verification in the parent session and delegates only the steps that fit a single subagent call (UI fact gathering, work plan creation, quality checks). ## Execution Pattern **Core Identity**: "I am a guided executor. Subagents handle UI fact gathering, work plan creation, and quality checks; I run the adjustment and the MCP-driven verification loop myself." **Execution Protocol**: -1. **Delegate** to subagents for: external-resource hearing storage (none — orchestrator runs hearing directly via AskUserQuestion), UI fact gathering (ui-analyzer), work plan creation (work-planner), quality checks (quality-fixer-frontend). -2. **Run myself** in the parent session: AskUserQuestion hearing, scale judgment, the actual adjustment edits, MCP-driven verification (e.g., compare CSS against design source, check visual rendering via browser MCP), and the iteration loop until acceptance. +1. **Delegate to subagents**: UI fact gathering (ui-analyzer — uses `disallowedTools` to inherit MCP access for fetching external sources in its own context), work plan creation (work-planner), quality checks (quality-fixer-frontend). +2. **Run in the parent session**: external-resource hearing via AskUserQuestion, scale judgment, the actual adjustment edits, MCP-driven verification (compare CSS against design source, check visual rendering via a browser MCP, etc.), and the iteration loop until acceptance. 3. **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding. 4. **Scope**: see Scope Boundaries below. -**Why this differs from other recipes**: Adjustment requires MCP loops that subagents cannot perform (their `tools` allowlist excludes MCP). Delegating implementation to task-executor-frontend would break the verification loop. The recipe runs the loop in the parent session, where the user's full MCP set is available. +**Why this differs from other recipes**: The adjust verification loop is multi-step (edit → verify against MCP → refine → re-verify). A single subagent call cannot host this loop because returning intermediate results to the orchestrator and re-invoking the subagent for each iteration would amplify context cost. The parent session keeps the loop tight. Delegated subagents (ui-analyzer, work-planner, quality-fixer-frontend) each complete in one call and do not need the loop. ## Workflow Overview ``` Adjustment request → external resource hearing (parent session, AskUserQuestion) ↓ - ui-analyzer (subagent: fetch external sources + analyze code) + ui-analyzer (subagent: fetch external sources + analyze code + propose candidateWriteSet) ↓ - scale judgment (parent session, documentation-criteria matrix) + write-set confirmation (parent session, AskUserQuestion) + ↓ + scale judgment on confirmed write set (documentation-criteria matrix) ↓ ┌────────────────────┴────────────────────┐ ↓ ↓ @@ -67,14 +69,15 @@ Ground the adjustment in observable facts before scoping the work. ui-analyzer r - 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: 'unknown', 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."` -- Read the JSON output. `analysisScope.filesAnalyzed`, `componentStructure[]`, `externalResources.*`, and `focusAreas[]` drive the scale judgment in Step 3 and the adjustment loop in Step 5. + - `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."` +- Read the JSON output. `componentStructure[]`, `externalResources.*`, `focusAreas[]`, and `candidateWriteSet[]` drive the scale judgment in Step 3 and the adjustment loop in Step 5. ### Step 3: Scale Judgment -Determine the work footprint using the Creation Decision Matrix in the documentation-criteria skill. +Scale judgment is based on the **write set** (files that will actually be modified), not on the broader set the analyzer read. The analyzer's `candidateWriteSet[]` is a candidate list, not a commitment — confirm it with the user before branching. -1. Count distinct files that the adjustment will modify, using the ui-analyzer output as the evidence base. -2. Apply the matrix: +1. Read `candidateWriteSet[]` from ui-analyzer output. Distinguish high-confidence entries (likely-to-modify) from medium/low-confidence entries (speculative). +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`, accept the user's edited list. +3. Apply the Creation Decision Matrix from the documentation-criteria skill to the **confirmed write set count**: - **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. @@ -120,10 +123,16 @@ When the user has not configured an MCP that the verification step would normall ### Step 6: Quality Verification (per adjustment unit) Delegate quality checks. quality-fixer-frontend runs typecheck / lint / test / format and fixes issues — these do not require MCP access. +`quality-fixer-frontend` expects `task_file` to be an actual file path and uses `filesModified` as the primary scope for incomplete-implementation checks. After per-unit commits, `git diff HEAD` becomes empty for the just-committed unit, so passing `filesModified` explicitly is required for correct scoping. + - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` - `description: "Quality verification for adjustment unit"` - - `prompt: "task_file: [path to the work plan phase or, for Branch A, a synthesized scope description]. Run quality checks across the adjustment unit's affected files."` + - Build the prompt by branch: + - **Branch A (1-2 files)**: omit `task_file`. Pass `filesModified: [list of files edited in this adjustment unit]` so quality-fixer scopes to those files. + - **Branch B (3-5 files)**: pass `task_file: ` AND `filesModified: [list of files edited in this adjustment unit]`. Both fields together give quality-fixer the work-plan context plus the precise write set. + - 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."` - Parse the response per subagents-orchestration-guide: - `approved` → proceed to Step 7 - `stub_detected` → return to Step 5 to complete the implementation, then re-run quality-fixer-frontend @@ -137,11 +146,12 @@ Then loop back to Step 5 for the next unit (Branch B work plan phase, or next fi ## 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 -- [ ] Scale judgment applied; 6+ files or ADR conditions escalated to the design phase +- [ ] 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 via MCP (or manual fallback when MCP absent) -- [ ] Each adjustment unit passed quality-fixer-frontend +- [ ] Each adjustment unit passed quality-fixer-frontend with explicit `filesModified` scoping - [ ] Each adjustment unit committed ## Output Example diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index 9e583ce..25732ce 100644 --- a/dev-workflows/agents/quality-fixer.md +++ b/dev-workflows/agents/quality-fixer.md @@ -69,6 +69,9 @@ 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 Relevant)**: +When a quality check depends on an external resource (e.g., a schema validator pointed at an external API spec, a test that consumes a recorded fixture from an upstream service, a generated artifact whose source lives outside the repository), consult it per the external-resource-context skill (Reference Protocol). Escalate via `blocked` with `reason: "Execution prerequisites not met"` and `missingPrerequisites` populated when the resource is referenced but unreachable. + ### 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 94aa06b..d614046 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -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/skills/external-resource-context/SKILL.md b/dev-workflows/skills/external-resource-context/SKILL.md index a52434e..e3022eb 100644 --- a/dev-workflows/skills/external-resource-context/SKILL.md +++ b/dev-workflows/skills/external-resource-context/SKILL.md @@ -26,9 +26,9 @@ Resources covered: design origin (where the canonical visual specification lives ### Single Source of Truth Rule -The project tier owns environment facts. The feature tier references the project tier by label and lists only feature-specific identifiers. Feature-tier sections never duplicate environment facts (URL, MCP name, access command). When the environment changes, only the project-tier file is updated. +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: `Design origin: project-tier "Design tool" entry; node id `. +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 diff --git a/skills/external-resource-context/SKILL.md b/skills/external-resource-context/SKILL.md index a52434e..e3022eb 100644 --- a/skills/external-resource-context/SKILL.md +++ b/skills/external-resource-context/SKILL.md @@ -26,9 +26,9 @@ Resources covered: design origin (where the canonical visual specification lives ### Single Source of Truth Rule -The project tier owns environment facts. The feature tier references the project tier by label and lists only feature-specific identifiers. Feature-tier sections never duplicate environment facts (URL, MCP name, access command). When the environment changes, only the project-tier file is updated. +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: `Design origin: project-tier "Design tool" entry; node id `. +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 diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index bcb0249..b88b7e2 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -4,28 +4,30 @@ description: Coordinate a frontend UI adjustment by hearing external resources, disable-model-invocation: true --- -**Context**: Dedicated to UI adjustment workflows on already-implemented features. Unlike recipe-front-design (document creation, fully delegated) and recipe-front-build (specified implementation, fully delegated), adjustment work depends on iterative MCP-driven verification (compare with design source, verify visual rendering, refine, re-verify). MCP access is held by the parent session — not by subagents whose `tools` allowlist excludes MCP. This recipe therefore runs the adjustment itself in the parent session and delegates only the steps that do not require MCP. +**Context**: Dedicated to UI adjustment workflows on already-implemented features. Unlike recipe-front-design (document creation, fully delegated) and recipe-front-build (specified implementation, fully delegated), adjustment work depends on an iterative MCP-driven verification loop (compare with design source → adjust → re-verify) that needs to run alongside file edits. The standard implementation delegate (`task-executor-frontend`) uses a `tools` allowlist that excludes MCP, so the verification loop cannot run inside it. This recipe therefore performs the adjustment and verification in the parent session and delegates only the steps that fit a single subagent call (UI fact gathering, work plan creation, quality checks). ## Execution Pattern **Core Identity**: "I am a guided executor. Subagents handle UI fact gathering, work plan creation, and quality checks; I run the adjustment and the MCP-driven verification loop myself." **Execution Protocol**: -1. **Delegate** to subagents for: external-resource hearing storage (none — orchestrator runs hearing directly via AskUserQuestion), UI fact gathering (ui-analyzer), work plan creation (work-planner), quality checks (quality-fixer-frontend). -2. **Run myself** in the parent session: AskUserQuestion hearing, scale judgment, the actual adjustment edits, MCP-driven verification (e.g., compare CSS against design source, check visual rendering via browser MCP), and the iteration loop until acceptance. +1. **Delegate to subagents**: UI fact gathering (ui-analyzer — uses `disallowedTools` to inherit MCP access for fetching external sources in its own context), work plan creation (work-planner), quality checks (quality-fixer-frontend). +2. **Run in the parent session**: external-resource hearing via AskUserQuestion, scale judgment, the actual adjustment edits, MCP-driven verification (compare CSS against design source, check visual rendering via a browser MCP, etc.), and the iteration loop until acceptance. 3. **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding. 4. **Scope**: see Scope Boundaries below. -**Why this differs from other recipes**: Adjustment requires MCP loops that subagents cannot perform (their `tools` allowlist excludes MCP). Delegating implementation to task-executor-frontend would break the verification loop. The recipe runs the loop in the parent session, where the user's full MCP set is available. +**Why this differs from other recipes**: The adjust verification loop is multi-step (edit → verify against MCP → refine → re-verify). A single subagent call cannot host this loop because returning intermediate results to the orchestrator and re-invoking the subagent for each iteration would amplify context cost. The parent session keeps the loop tight. Delegated subagents (ui-analyzer, work-planner, quality-fixer-frontend) each complete in one call and do not need the loop. ## Workflow Overview ``` Adjustment request → external resource hearing (parent session, AskUserQuestion) ↓ - ui-analyzer (subagent: fetch external sources + analyze code) + ui-analyzer (subagent: fetch external sources + analyze code + propose candidateWriteSet) ↓ - scale judgment (parent session, documentation-criteria matrix) + write-set confirmation (parent session, AskUserQuestion) + ↓ + scale judgment on confirmed write set (documentation-criteria matrix) ↓ ┌────────────────────┴────────────────────┐ ↓ ↓ @@ -67,14 +69,15 @@ Ground the adjustment in observable facts before scoping the work. ui-analyzer r - 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: 'unknown', 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."` -- Read the JSON output. `analysisScope.filesAnalyzed`, `componentStructure[]`, `externalResources.*`, and `focusAreas[]` drive the scale judgment in Step 3 and the adjustment loop in Step 5. + - `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."` +- Read the JSON output. `componentStructure[]`, `externalResources.*`, `focusAreas[]`, and `candidateWriteSet[]` drive the scale judgment in Step 3 and the adjustment loop in Step 5. ### Step 3: Scale Judgment -Determine the work footprint using the Creation Decision Matrix in the documentation-criteria skill. +Scale judgment is based on the **write set** (files that will actually be modified), not on the broader set the analyzer read. The analyzer's `candidateWriteSet[]` is a candidate list, not a commitment — confirm it with the user before branching. -1. Count distinct files that the adjustment will modify, using the ui-analyzer output as the evidence base. -2. Apply the matrix: +1. Read `candidateWriteSet[]` from ui-analyzer output. Distinguish high-confidence entries (likely-to-modify) from medium/low-confidence entries (speculative). +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`, accept the user's edited list. +3. Apply the Creation Decision Matrix from the documentation-criteria skill to the **confirmed write set count**: - **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. @@ -120,10 +123,16 @@ When the user has not configured an MCP that the verification step would normall ### Step 6: Quality Verification (per adjustment unit) Delegate quality checks. quality-fixer-frontend runs typecheck / lint / test / format and fixes issues — these do not require MCP access. +`quality-fixer-frontend` expects `task_file` to be an actual file path and uses `filesModified` as the primary scope for incomplete-implementation checks. After per-unit commits, `git diff HEAD` becomes empty for the just-committed unit, so passing `filesModified` explicitly is required for correct scoping. + - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` - `description: "Quality verification for adjustment unit"` - - `prompt: "task_file: [path to the work plan phase or, for Branch A, a synthesized scope description]. Run quality checks across the adjustment unit's affected files."` + - Build the prompt by branch: + - **Branch A (1-2 files)**: omit `task_file`. Pass `filesModified: [list of files edited in this adjustment unit]` so quality-fixer scopes to those files. + - **Branch B (3-5 files)**: pass `task_file: ` AND `filesModified: [list of files edited in this adjustment unit]`. Both fields together give quality-fixer the work-plan context plus the precise write set. + - 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."` - Parse the response per subagents-orchestration-guide: - `approved` → proceed to Step 7 - `stub_detected` → return to Step 5 to complete the implementation, then re-run quality-fixer-frontend @@ -137,11 +146,12 @@ Then loop back to Step 5 for the next unit (Branch B work plan phase, or next fi ## 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 -- [ ] Scale judgment applied; 6+ files or ADR conditions escalated to the design phase +- [ ] 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 via MCP (or manual fallback when MCP absent) -- [ ] Each adjustment unit passed quality-fixer-frontend +- [ ] Each adjustment unit passed quality-fixer-frontend with explicit `filesModified` scoping - [ ] Each adjustment unit committed ## Output Example From 70671fd8fcfd6438cc6d815e13083ef9e25aa71b Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 22:48:16 +0900 Subject: [PATCH 07/16] refactor: strip human-targeted explanation prose MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Several recently-added passages explain *why* the configuration is what it is, rather than *what* the agent or recipe should do. The agent already has the configuration in its frontmatter and the protocol in the loaded skill, so the explanatory prose only consumes context budget without changing execution. Remove or compress: - ui-analyzer "Tool Scope" section (frontmatter is the source of truth; the agent does not decide its own tool set). - ui-analyzer "Boundary with codebase-analyzer" filler sentences; keep the routing table and the disambiguation rule. - ui-analyzer Step 12 "candidate vs commitment" rationale; the recipe owns that distinction. - recipe-front-adjust Context paragraph compressed; the lengthy comparison to other recipes was framing for human readers. - recipe-front-adjust "Why this differs from other recipes" block removed entirely — the protocol bullets above already define the action shape. - recipe-front-adjust Step 5 leading sentence (Subagents are not used here because...) removed; the heading already states "(parent session)". - recipe-front-adjust Step 1 / Step 2 / Step 3 narrative leads trimmed; numbered steps and Agent invocation blocks carry the action. - recipe-front-adjust Step 6 task_file rationale paragraph removed; the Branch A / Branch B prompt construction is the action and stands alone. - quality-fixer / quality-fixer-frontend Consultation sections trimmed: drop the "(e.g., ...)" example lists; the trigger condition + action + escalation rule is the actual content. Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/quality-fixer-frontend.md | 3 +-- agents/quality-fixer.md | 3 +-- agents/ui-analyzer.md | 14 ++--------- .../agents/quality-fixer-frontend.md | 3 +-- dev-workflows-frontend/agents/ui-analyzer.md | 14 ++--------- .../skills/recipe-front-adjust/SKILL.md | 24 ++++++------------- dev-workflows/agents/quality-fixer.md | 3 +-- skills/recipe-front-adjust/SKILL.md | 24 ++++++------------- 8 files changed, 22 insertions(+), 66 deletions(-) diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index c8bb4dd..7344f95 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -72,8 +72,7 @@ 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 Relevant)**: -When a quality check depends on an external resource (e.g., a generated CSS-module typings file, a generated message catalog, a contract test fixture from an upstream service, or a visual regression baseline), consult it per the external-resource-context skill (Reference Protocol). Escalate via `blocked` with `reason: "Execution prerequisites not met"` and `missingPrerequisites` populated when the resource is referenced but unreachable. +**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: diff --git a/agents/quality-fixer.md b/agents/quality-fixer.md index 25732ce..f777265 100644 --- a/agents/quality-fixer.md +++ b/agents/quality-fixer.md @@ -69,8 +69,7 @@ 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 Relevant)**: -When a quality check depends on an external resource (e.g., a schema validator pointed at an external API spec, a test that consumes a recorded fixture from an upstream service, a generated artifact whose source lives outside the repository), consult it per the external-resource-context skill (Reference Protocol). Escalate via `blocked` with `reason: "Execution prerequisites not met"` and `missingPrerequisites` populated when the resource is referenced but unreachable. +**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: diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md index 317825e..abedb7c 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -13,18 +13,12 @@ You are an AI assistant specializing in UI fact gathering for frontend design an ## Boundary with codebase-analyzer -This agent and codebase-analyzer have complementary scopes. They are designed to run in parallel before frontend design. - | Agent | Owns | |-------|------| | codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | | ui-analyzer | UI external sources (design origin, design system catalog, guidelines fetched via MCP / URL / file) + existing UI surface (component structure, props patterns, CSS layout state, state matrices, display conditions, i18n format, accessibility, generated UI artifacts) | -When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-analyzer records the call-site usage pattern. They are complementary, not overlapping. - -## Tool Scope - -This agent uses `disallowedTools` only (no `tools` allowlist) so the parent session's full tool set is inherited, including any MCP tools the user has installed. File modification (Write, Edit, MultiEdit, NotebookEdit) is denied — analysis only, no code changes. MCP tools (e.g., a design-tool MCP, a design-system catalog MCP, a browser MCP) are accessible if and only if they exist in the parent session. +When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-analyzer records the call-site usage pattern. ## Input Parameters @@ -159,15 +153,11 @@ For each generator (CSS module typings, message catalog typings, route typings, ### Step 12: Candidate Write Set -The set of files analyzed in Steps 3-11 is broader than the set the design or adjustment will modify. Produce a separate `candidateWriteSet[]` listing the files most likely to require modification given the input requirements, with a confidence label per entry. - -For each file: +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) -This list is a candidate, not a commitment — the calling recipe should treat it as input to a user-confirmed write set, not as the final scope. - ## Output Format ### Output Protocol diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index c8bb4dd..7344f95 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -72,8 +72,7 @@ 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 Relevant)**: -When a quality check depends on an external resource (e.g., a generated CSS-module typings file, a generated message catalog, a contract test fixture from an upstream service, or a visual regression baseline), consult it per the external-resource-context skill (Reference Protocol). Escalate via `blocked` with `reason: "Execution prerequisites not met"` and `missingPrerequisites` populated when the resource is referenced but unreachable. +**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: diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md index 317825e..abedb7c 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -13,18 +13,12 @@ You are an AI assistant specializing in UI fact gathering for frontend design an ## Boundary with codebase-analyzer -This agent and codebase-analyzer have complementary scopes. They are designed to run in parallel before frontend design. - | Agent | Owns | |-------|------| | codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | | ui-analyzer | UI external sources (design origin, design system catalog, guidelines fetched via MCP / URL / file) + existing UI surface (component structure, props patterns, CSS layout state, state matrices, display conditions, i18n format, accessibility, generated UI artifacts) | -When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-analyzer records the call-site usage pattern. They are complementary, not overlapping. - -## Tool Scope - -This agent uses `disallowedTools` only (no `tools` allowlist) so the parent session's full tool set is inherited, including any MCP tools the user has installed. File modification (Write, Edit, MultiEdit, NotebookEdit) is denied — analysis only, no code changes. MCP tools (e.g., a design-tool MCP, a design-system catalog MCP, a browser MCP) are accessible if and only if they exist in the parent session. +When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-analyzer records the call-site usage pattern. ## Input Parameters @@ -159,15 +153,11 @@ For each generator (CSS module typings, message catalog typings, route typings, ### Step 12: Candidate Write Set -The set of files analyzed in Steps 3-11 is broader than the set the design or adjustment will modify. Produce a separate `candidateWriteSet[]` listing the files most likely to require modification given the input requirements, with a confidence label per entry. - -For each file: +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) -This list is a candidate, not a commitment — the calling recipe should treat it as input to a user-confirmed write set, not as the final scope. - ## Output Format ### Output Protocol diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index b88b7e2..a2d52a1 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -4,19 +4,16 @@ description: Coordinate a frontend UI adjustment by hearing external resources, disable-model-invocation: true --- -**Context**: Dedicated to UI adjustment workflows on already-implemented features. Unlike recipe-front-design (document creation, fully delegated) and recipe-front-build (specified implementation, fully delegated), adjustment work depends on an iterative MCP-driven verification loop (compare with design source → adjust → re-verify) that needs to run alongside file edits. The standard implementation delegate (`task-executor-frontend`) uses a `tools` allowlist that excludes MCP, so the verification loop cannot run inside it. This recipe therefore performs the adjustment and verification in the parent session and delegates only the steps that fit a single subagent call (UI fact gathering, work plan creation, quality checks). +**Context**: UI adjustment on already-implemented features. The verification loop (edit → MCP-driven check → refine) runs in the parent session. ## Execution Pattern -**Core Identity**: "I am a guided executor. Subagents handle UI fact gathering, work plan creation, and quality checks; I run the adjustment and the MCP-driven verification loop myself." +**Core Identity**: "I am a guided executor. I run the adjustment and the MCP-driven verification loop myself; subagents handle one-shot tasks." **Execution Protocol**: -1. **Delegate to subagents**: UI fact gathering (ui-analyzer — uses `disallowedTools` to inherit MCP access for fetching external sources in its own context), work plan creation (work-planner), quality checks (quality-fixer-frontend). -2. **Run in the parent session**: external-resource hearing via AskUserQuestion, scale judgment, the actual adjustment edits, MCP-driven verification (compare CSS against design source, check visual rendering via a browser MCP, etc.), and the iteration loop until acceptance. -3. **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding. -4. **Scope**: see Scope Boundaries below. - -**Why this differs from other recipes**: The adjust verification loop is multi-step (edit → verify against MCP → refine → re-verify). A single subagent call cannot host this loop because returning intermediate results to the orchestrator and re-invoking the subagent for each iteration would amplify context cost. The parent session keeps the loop tight. Delegated subagents (ui-analyzer, work-planner, quality-fixer-frontend) each complete in one call and do not need the loop. +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, MCP-driven verification, iteration until acceptance. +3. **Stop at every `[Stop: ...]` marker** before proceeding. ## Workflow Overview @@ -61,21 +58,18 @@ Adjustment request: $ARGUMENTS ## Execution Flow ### Step 1: External Resource Hearing -Run the hearing protocol per the external-resource-context skill (frontend domain). The parent session 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`. +Run the hearing protocol per the external-resource-context skill (frontend domain). ### Step 2: UI Fact Gathering -Ground the adjustment in observable facts before scoping the work. ui-analyzer reads the project-tier external-resources file and fetches external UI sources (design origin, design system catalog, guidelines) via the inherited MCP/URL access methods, then analyzes the existing UI codebase. Heavy fetches stay inside the subagent's own context. - 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."` -- Read the JSON output. `componentStructure[]`, `externalResources.*`, `focusAreas[]`, and `candidateWriteSet[]` drive the scale judgment in Step 3 and the adjustment loop in Step 5. ### Step 3: Scale Judgment -Scale judgment is based on the **write set** (files that will actually be modified), not on the broader set the analyzer read. The analyzer's `candidateWriteSet[]` is a candidate list, not a commitment — confirm it with the user before branching. -1. Read `candidateWriteSet[]` from ui-analyzer output. Distinguish high-confidence entries (likely-to-modify) from medium/low-confidence entries (speculative). +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`, accept the user's edited list. 3. Apply the Creation Decision Matrix from the documentation-criteria skill to the **confirmed write set count**: - **1-2 files**: Direct adjustment, no work plan. @@ -106,7 +100,6 @@ After work-planner returns: - **[STOP]**: Wait for plan approval or revision request. If the user requests changes, re-invoke work-planner with revised guidance. ### Step 5: Adjustment + MCP Verification (parent session) -This is the loop the parent session runs directly. Subagents are not used here because their `tools` allowlist excludes MCP and would break the verification step. 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). @@ -121,9 +114,6 @@ For each adjustment unit (per file in Branch A; per work plan phase in Branch B) When the user has not configured an MCP that the verification step would normally use, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). ### Step 6: Quality Verification (per adjustment unit) -Delegate quality checks. quality-fixer-frontend runs typecheck / lint / test / format and fixes issues — these do not require MCP access. - -`quality-fixer-frontend` expects `task_file` to be an actual file path and uses `filesModified` as the primary scope for incomplete-implementation checks. After per-unit commits, `git diff HEAD` becomes empty for the just-committed unit, so passing `filesModified` explicitly is required for correct scoping. - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index 25732ce..f777265 100644 --- a/dev-workflows/agents/quality-fixer.md +++ b/dev-workflows/agents/quality-fixer.md @@ -69,8 +69,7 @@ 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 Relevant)**: -When a quality check depends on an external resource (e.g., a schema validator pointed at an external API spec, a test that consumes a recorded fixture from an upstream service, a generated artifact whose source lives outside the repository), consult it per the external-resource-context skill (Reference Protocol). Escalate via `blocked` with `reason: "Execution prerequisites not met"` and `missingPrerequisites` populated when the resource is referenced but unreachable. +**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: diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index b88b7e2..a2d52a1 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -4,19 +4,16 @@ description: Coordinate a frontend UI adjustment by hearing external resources, disable-model-invocation: true --- -**Context**: Dedicated to UI adjustment workflows on already-implemented features. Unlike recipe-front-design (document creation, fully delegated) and recipe-front-build (specified implementation, fully delegated), adjustment work depends on an iterative MCP-driven verification loop (compare with design source → adjust → re-verify) that needs to run alongside file edits. The standard implementation delegate (`task-executor-frontend`) uses a `tools` allowlist that excludes MCP, so the verification loop cannot run inside it. This recipe therefore performs the adjustment and verification in the parent session and delegates only the steps that fit a single subagent call (UI fact gathering, work plan creation, quality checks). +**Context**: UI adjustment on already-implemented features. The verification loop (edit → MCP-driven check → refine) runs in the parent session. ## Execution Pattern -**Core Identity**: "I am a guided executor. Subagents handle UI fact gathering, work plan creation, and quality checks; I run the adjustment and the MCP-driven verification loop myself." +**Core Identity**: "I am a guided executor. I run the adjustment and the MCP-driven verification loop myself; subagents handle one-shot tasks." **Execution Protocol**: -1. **Delegate to subagents**: UI fact gathering (ui-analyzer — uses `disallowedTools` to inherit MCP access for fetching external sources in its own context), work plan creation (work-planner), quality checks (quality-fixer-frontend). -2. **Run in the parent session**: external-resource hearing via AskUserQuestion, scale judgment, the actual adjustment edits, MCP-driven verification (compare CSS against design source, check visual rendering via a browser MCP, etc.), and the iteration loop until acceptance. -3. **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding. -4. **Scope**: see Scope Boundaries below. - -**Why this differs from other recipes**: The adjust verification loop is multi-step (edit → verify against MCP → refine → re-verify). A single subagent call cannot host this loop because returning intermediate results to the orchestrator and re-invoking the subagent for each iteration would amplify context cost. The parent session keeps the loop tight. Delegated subagents (ui-analyzer, work-planner, quality-fixer-frontend) each complete in one call and do not need the loop. +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, MCP-driven verification, iteration until acceptance. +3. **Stop at every `[Stop: ...]` marker** before proceeding. ## Workflow Overview @@ -61,21 +58,18 @@ Adjustment request: $ARGUMENTS ## Execution Flow ### Step 1: External Resource Hearing -Run the hearing protocol per the external-resource-context skill (frontend domain). The parent session 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`. +Run the hearing protocol per the external-resource-context skill (frontend domain). ### Step 2: UI Fact Gathering -Ground the adjustment in observable facts before scoping the work. ui-analyzer reads the project-tier external-resources file and fetches external UI sources (design origin, design system catalog, guidelines) via the inherited MCP/URL access methods, then analyzes the existing UI codebase. Heavy fetches stay inside the subagent's own context. - 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."` -- Read the JSON output. `componentStructure[]`, `externalResources.*`, `focusAreas[]`, and `candidateWriteSet[]` drive the scale judgment in Step 3 and the adjustment loop in Step 5. ### Step 3: Scale Judgment -Scale judgment is based on the **write set** (files that will actually be modified), not on the broader set the analyzer read. The analyzer's `candidateWriteSet[]` is a candidate list, not a commitment — confirm it with the user before branching. -1. Read `candidateWriteSet[]` from ui-analyzer output. Distinguish high-confidence entries (likely-to-modify) from medium/low-confidence entries (speculative). +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`, accept the user's edited list. 3. Apply the Creation Decision Matrix from the documentation-criteria skill to the **confirmed write set count**: - **1-2 files**: Direct adjustment, no work plan. @@ -106,7 +100,6 @@ After work-planner returns: - **[STOP]**: Wait for plan approval or revision request. If the user requests changes, re-invoke work-planner with revised guidance. ### Step 5: Adjustment + MCP Verification (parent session) -This is the loop the parent session runs directly. Subagents are not used here because their `tools` allowlist excludes MCP and would break the verification step. 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). @@ -121,9 +114,6 @@ For each adjustment unit (per file in Branch A; per work plan phase in Branch B) When the user has not configured an MCP that the verification step would normally use, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). ### Step 6: Quality Verification (per adjustment unit) -Delegate quality checks. quality-fixer-frontend runs typecheck / lint / test / format and fixes issues — these do not require MCP access. - -`quality-fixer-frontend` expects `task_file` to be an actual file path and uses `filesModified` as the primary scope for incomplete-implementation checks. After per-unit commits, `git diff HEAD` becomes empty for the just-committed unit, so passing `filesModified` explicitly is required for correct scoping. - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` From a71988cc033cea8b81865fd61d71f2d7ec405baf Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 22:54:39 +0900 Subject: [PATCH 08/16] fix: review-driven follow-up corrections - candidateWriteSet[] added to subagents-orchestration-guide ui-analyzer key fields list. recipe-front-adjust depends on this field for scale judgment, but it was missing from the orchestrator- facing summary, risking lookup failure. - recipe-front-adjust drops the subagents-orchestration-guide reference. The recipe runs the adjustment loop in the parent session and is not a delegating orchestrator, so referencing the guide pulled the model toward the standard "delegate everything" pattern. Replace "Parse the response per subagents-orchestration- guide" with self-contained quality-fixer-frontend response routing that includes the blocked-reason discrimination. - Branch B task_file is clarified as a supplementary hint; filesModified is the primary scope. quality-fixer-frontend's Quality Assurance Mechanisms lookup uses task_file when it points to a document with that section, but the file scope itself is always driven by filesModified. - AskUserQuestion option c (edit list manually) for write-set confirmation now explicitly instructs a follow-up plain message asking the user to paste the edited list. AskUserQuestion is a single-round structured-choice tool; the follow-up turn was implicit before. - Decision Matrix in Step 3 gains a 0-files branch. When candidateWriteSet[] is empty (the adjustment request did not map to any existing file), escalate to the user instead of falling through the matrix. - ui-analyzer Quality Checklist drops the trailing "not enumerated speculatively" phrase. The preceding positive form "emitted as empty arrays / minimal placeholders" already defines the expected behavior; the negative tail violates BP-001. Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/ui-analyzer.md | 2 +- dev-workflows-frontend/agents/ui-analyzer.md | 2 +- .../skills/recipe-front-adjust/SKILL.md | 15 ++++++++------- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- skills/recipe-front-adjust/SKILL.md | 15 ++++++++------- skills/subagents-orchestration-guide/SKILL.md | 2 +- 7 files changed, 21 insertions(+), 19 deletions(-) diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md index abedb7c..55ef9fe 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -323,5 +323,5 @@ Produce `candidateWriteSet[]` listing the files most likely to require modificat - [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck/test/build/runtime - [ ] Focus areas have evidence pointers; no fact appears in focusAreas without a corresponding evidence entry - [ ] `candidateWriteSet` is populated with at least the high-confidence entries; speculative entries use `confidence: "low"` -- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders, not enumerated speculatively (e.g., for a 1-2 file adjustment, `displayConditions` and `accessibility` may be `[]` if the scope does not touch them) +- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders (e.g., for a 1-2 file adjustment, `displayConditions` and `accessibility` may be `[]` if the scope does not touch them) - [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md index abedb7c..55ef9fe 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -323,5 +323,5 @@ Produce `candidateWriteSet[]` listing the files most likely to require modificat - [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck/test/build/runtime - [ ] Focus areas have evidence pointers; no fact appears in focusAreas without a corresponding evidence entry - [ ] `candidateWriteSet` is populated with at least the high-confidence entries; speculative entries use `confidence: "low"` -- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders, not enumerated speculatively (e.g., for a 1-2 file adjustment, `displayConditions` and `accessibility` may be `[]` if the scope does not touch them) +- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders (e.g., for a 1-2 file adjustment, `displayConditions` and `accessibility` may be `[]` if the scope does not touch them) - [ ] Final message is a single JSON object matching the schema; no trailing commentary diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index a2d52a1..4af1c49 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -70,8 +70,9 @@ Run the hearing protocol per the external-resource-context skill (frontend domai ### 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`, accept the user's edited list. +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. @@ -118,15 +119,15 @@ When the user has not configured an MCP that the verification step would normall - 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: - - **Branch A (1-2 files)**: omit `task_file`. Pass `filesModified: [list of files edited in this adjustment unit]` so quality-fixer scopes to those files. - - **Branch B (3-5 files)**: pass `task_file: ` AND `filesModified: [list of files edited in this adjustment unit]`. Both fields together give quality-fixer the work-plan context plus the precise write set. + - 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."` -- Parse the response per subagents-orchestration-guide: +- Route the quality-fixer-frontend response by `status`: - `approved` → proceed to Step 7 - - `stub_detected` → return to Step 5 to complete the implementation, then re-run quality-fixer-frontend - - `blocked` → escalate to user with the blocking issue and stop + - `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. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 75cd0dc..4528770 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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[] (with `ui:` prefix on fact_id), limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 75cd0dc..4528770 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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[] (with `ui:` prefix on fact_id), limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index a2d52a1..4af1c49 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -70,8 +70,9 @@ Run the hearing protocol per the external-resource-context skill (frontend domai ### 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`, accept the user's edited list. +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. @@ -118,15 +119,15 @@ When the user has not configured an MCP that the verification step would normall - 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: - - **Branch A (1-2 files)**: omit `task_file`. Pass `filesModified: [list of files edited in this adjustment unit]` so quality-fixer scopes to those files. - - **Branch B (3-5 files)**: pass `task_file: ` AND `filesModified: [list of files edited in this adjustment unit]`. Both fields together give quality-fixer the work-plan context plus the precise write set. + - 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."` -- Parse the response per subagents-orchestration-guide: +- Route the quality-fixer-frontend response by `status`: - `approved` → proceed to Step 7 - - `stub_detected` → return to Step 5 to complete the implementation, then re-run quality-fixer-frontend - - `blocked` → escalate to user with the blocking issue and stop + - `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. diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 75cd0dc..4528770 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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[] (with `ui:` prefix on fact_id), limitations +- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (with `ui:` prefix on fact_id), 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 From c4e3ab48d8f701a784f50b0ba7aa207b51798dfc Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 22:56:03 +0900 Subject: [PATCH 09/16] refactor: positive-form Responsibility and Escalation boundaries Two BP-001 violations remained in recipe-front-adjust scope section. Convert both to positive form so the recipe body carries no negative references to other recipes or out-of-scope items. - Responsibility Boundary previously ended with "it does not hand off to other implementation recipes." That phrasing pulls the model toward the recipes it negates. Replace with a positive statement of what this recipe owns: parent session owns edits, verification loops, quality-result routing, and commits. - "Out of scope:" section is reframed as an Escalation Boundary. The rule "escalate to the full frontend design phase when X" is the same constraint stated as a positive trigger condition. Co-Authored-By: Claude Opus 4.7 (1M context) --- dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md | 5 ++--- skills/recipe-front-adjust/SKILL.md | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index 4af1c49..e637dc8 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -48,10 +48,9 @@ Adjustment request → external resource hearing (parent session, AskUserQuestio - 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; it does not hand off to other implementation recipes. +**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. -**Out of scope**: -- Creating PRD, UI Spec, or Design Doc — adjustment work uses existing documents. When the requested change exceeds adjustment scope (new feature, new architecture, multi-screen redesign, or any ADR Creation Condition from documentation-criteria), escalate the user to the full frontend design phase. +**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 diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index 4af1c49..e637dc8 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -48,10 +48,9 @@ Adjustment request → external resource hearing (parent session, AskUserQuestio - 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; it does not hand off to other implementation recipes. +**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. -**Out of scope**: -- Creating PRD, UI Spec, or Design Doc — adjustment work uses existing documents. When the requested change exceeds adjustment scope (new feature, new architecture, multi-screen redesign, or any ADR Creation Condition from documentation-criteria), escalate the user to the full frontend design phase. +**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 From ffc87fbb7f6f940e97407cbc0e9aaa8e90143e35 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 23:12:14 +0900 Subject: [PATCH 10/16] refactor: trim duplicated checklists and verbose samples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply four in-body compressions identified in review. References/ moves are intentionally avoided because Claude Code's progressive disclosure does not reliably load reference files mid-flow. A. recipe-front-adjust:114 — convert "When the user has not configured an MCP that the verification step would normally use" to "When MCP access is unavailable for the verification step" so the fallback condition reads positively. C. ui-analyzer Quality Checklist — trim items that restate the procedural Steps 1-12 and keep only the gates that test final output integrity (per-axis fetch_status, candidateWriteSet presence, focusAreas evidence pointers, scope-out empty arrays, single-JSON output). H. technical-designer-frontend Implementation Sample Standards — the agent already loads typescript-rules and frontend-ai-guide skills, which carry the canonical React patterns. Replace the 45-line code sample with a short directive that defers to those skills for concrete patterns. L. technical-designer and technical-designer-frontend Quality Checklist — drop items that restate Gate 0-3 enforcement (which blocks at the corresponding Mandatory Process subsection) and keep items that test final-output completeness only. Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/technical-designer-frontend.md | 115 ++++-------------- agents/technical-designer.md | 56 ++++----- agents/ui-analyzer.md | 18 +-- .../agents/technical-designer-frontend.md | 115 ++++-------------- dev-workflows-frontend/agents/ui-analyzer.md | 18 +-- .../skills/recipe-front-adjust/SKILL.md | 2 +- dev-workflows/agents/technical-designer.md | 56 ++++----- skills/recipe-front-adjust/SKILL.md | 2 +- 8 files changed, 108 insertions(+), 274 deletions(-) diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 17a1d2b..edca9f7 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -274,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 + +For concrete code patterns, defer to those skills rather than duplicating sample code in the design document. ## Diagram Creation (using mermaid notation) @@ -347,42 +297,31 @@ 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 +- [ ] 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) + +**Create/update mode only**: +- [ ] 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 63f0e79..06b855a 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -325,47 +325,35 @@ 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) +- [ ] 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) + +**Create/update mode only**: +- [ ] 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 index 55ef9fe..b9d05af 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -310,18 +310,8 @@ Produce `candidateWriteSet[]` listing the files most likely to require modificat ## Quality Checklist -- [ ] `docs/project-context/external-resources.md` was read (or recorded as absent) -- [ ] For each present external resource, fetch was attempted via the declared access method, and `fetch_status` records the outcome -- [ ] Heavy fetches were narrowed to the affected scope rather than the full surface -- [ ] All affected component files were read in full before extracting structure -- [ ] DOM order is recorded as literal source order -- [ ] Props patterns include every call site grouping (canonical and outlier) -- [ ] CSS layout records gap/wrap/logical-property state for every layout-bearing class in the scope -- [ ] State x display matrix lists states actually expressed in code and explicitly marks unsupported states -- [ ] Display conditions record predicate location and gated subtree -- [ ] i18n format details are concrete enough that a designer can author new keys without re-investigating -- [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck/test/build/runtime -- [ ] Focus areas have evidence pointers; no fact appears in focusAreas without a corresponding evidence entry -- [ ] `candidateWriteSet` is populated with at least the high-confidence entries; speculative entries use `confidence: "low"` -- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders (e.g., for a 1-2 file adjustment, `displayConditions` and `accessibility` may be `[]` if the scope does not touch them) +- [ ] 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/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 17a1d2b..edca9f7 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -274,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 + +For concrete code patterns, defer to those skills rather than duplicating sample code in the design document. ## Diagram Creation (using mermaid notation) @@ -347,42 +297,31 @@ 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 +- [ ] 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) + +**Create/update mode only**: +- [ ] 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 index 55ef9fe..b9d05af 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -310,18 +310,8 @@ Produce `candidateWriteSet[]` listing the files most likely to require modificat ## Quality Checklist -- [ ] `docs/project-context/external-resources.md` was read (or recorded as absent) -- [ ] For each present external resource, fetch was attempted via the declared access method, and `fetch_status` records the outcome -- [ ] Heavy fetches were narrowed to the affected scope rather than the full surface -- [ ] All affected component files were read in full before extracting structure -- [ ] DOM order is recorded as literal source order -- [ ] Props patterns include every call site grouping (canonical and outlier) -- [ ] CSS layout records gap/wrap/logical-property state for every layout-bearing class in the scope -- [ ] State x display matrix lists states actually expressed in code and explicitly marks unsupported states -- [ ] Display conditions record predicate location and gated subtree -- [ ] i18n format details are concrete enough that a designer can author new keys without re-investigating -- [ ] Generated artifact readiness lists every generator whose output is consumed by typecheck/test/build/runtime -- [ ] Focus areas have evidence pointers; no fact appears in focusAreas without a corresponding evidence entry -- [ ] `candidateWriteSet` is populated with at least the high-confidence entries; speculative entries use `confidence: "low"` -- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders (e.g., for a 1-2 file adjustment, `displayConditions` and `accessibility` may be `[]` if the scope does not touch them) +- [ ] 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/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index e637dc8..210e48e 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -111,7 +111,7 @@ For each adjustment unit (per file in Branch A; per work plan phase in Branch B) 4. **Refine and re-verify** until the adjustment matches the design source. 5. When the adjustment unit converges, proceed to Step 6 for that unit. -When the user has not configured an MCP that the verification step would normally use, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). +When MCP access is unavailable for the verification step, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). ### Step 6: Quality Verification (per adjustment unit) diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 63f0e79..06b855a 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -325,47 +325,35 @@ 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) +- [ ] 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) + +**Create/update mode only**: +- [ ] 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/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index e637dc8..210e48e 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -111,7 +111,7 @@ For each adjustment unit (per file in Branch A; per work plan phase in Branch B) 4. **Refine and re-verify** until the adjustment matches the design source. 5. When the adjustment unit converges, proceed to Step 6 for that unit. -When the user has not configured an MCP that the verification step would normally use, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). +When MCP access is unavailable for the verification step, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). ### Step 6: Quality Verification (per adjustment unit) From 00ba836e162fe0325b4f81e9dd6f26d130687a17 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 23:14:46 +0900 Subject: [PATCH 11/16] fix: clarify implementation-sample directive and restore fact-disposition checklist item Two follow-up corrections from the latest review. - technical-designer-frontend Implementation Sample directive previously read "defer to those skills rather than duplicating sample code in the design document". The phrasing could be misread as forbidding code examples in Design Docs entirely. The intent is the inverse: sample code is permitted in Design Docs, but it should follow the canonical patterns carried by the loaded skills. Replace with the positive form "When sample code is needed, keep it minimal and follow concrete patterns from those skills." - The Quality Checklist trim in the previous commit dropped the Fact Disposition Table self-check from both technical-designer and technical-designer-frontend. Gate 1 enforces table population during creation, but a final self-check entry catches population gaps that survive the gate. Restore one checklist line in both files under "All modes". Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/technical-designer-frontend.md | 3 ++- agents/technical-designer.md | 1 + dev-workflows-frontend/agents/technical-designer-frontend.md | 3 ++- dev-workflows/agents/technical-designer.md | 1 + 4 files changed, 6 insertions(+), 2 deletions(-) diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index edca9f7..75ebd4e 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -282,7 +282,7 @@ Implementation samples in ADR and Design Docs follow the standards loaded from t - Error handling: error boundaries and error state management - Secrets remain server-side -For concrete code patterns, defer to those skills rather than duplicating sample code in the design document. +When sample code is needed, keep it minimal and follow concrete patterns from those skills. ## Diagram Creation (using mermaid notation) @@ -310,6 +310,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] 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**: - [ ] Acceptance criteria are testable from a user-observable, integration/E2E-oriented standpoint diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 06b855a..9b611a7 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -338,6 +338,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] 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) +- [ ] 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**: - [ ] Acceptance criteria are testable (user-observable, integration/E2E-oriented, CI-isolatable) diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index edca9f7..75ebd4e 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -282,7 +282,7 @@ Implementation samples in ADR and Design Docs follow the standards loaded from t - Error handling: error boundaries and error state management - Secrets remain server-side -For concrete code patterns, defer to those skills rather than duplicating sample code in the design document. +When sample code is needed, keep it minimal and follow concrete patterns from those skills. ## Diagram Creation (using mermaid notation) @@ -310,6 +310,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] 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**: - [ ] Acceptance criteria are testable from a user-observable, integration/E2E-oriented standpoint diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 06b855a..9b611a7 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -338,6 +338,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] 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) +- [ ] 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**: - [ ] Acceptance criteria are testable (user-observable, integration/E2E-oriented, CI-isolatable) From 492bb39b1577b724351280f0e593d4abec9eb01d Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 23:38:05 +0900 Subject: [PATCH 12/16] chore: bump to 0.18.0 and refresh README Bump every version field (root package.json, marketplace.json plugin entries, generated plugin.json files) from 0.17.1 to 0.18.0 to release the work in this branch. README updates: - Add a "Which plugin should I start with?" decision table at the top of Quick Start so the install path is decided in one read. - Hoist the common claude + marketplace add steps and inline /reload-plugins next to each plugin install so the order matches the actual command flow. - Drop the previous "What These Plugins Do" section. The same pipeline was rendered four times across the README; remove the duplicated phase list and keep the Mermaid figure plus the seven step "Behind the Scenes" list. - Move the UI Spec rationale next to /recipe-front-design and add a concrete failure example (combined screen with mixed loading / error states). - Add /recipe-front-adjust and ui-analyzer to the recipe and agent tables; add the External Resource Context entry to Built-in Best Practices. - Trim the FAQ entries that duplicated Quick Start content. - Add a one line caption under each Mermaid figure. - Drop emoji from Mermaid nodes; keep section heading emoji. - Replace contrastive "X, not Y" phrasings with positive forms; drop remaining em dashes. - Quote the trapezoid-looking node label in the reverse engineering Mermaid figure ("/recipe-reverse-engineer") so Mermaid does not parse it as a parallelogram shape. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 6 +- README.md | 323 ++++++++---------- dev-skills/.claude-plugin/plugin.json | 2 +- .../.claude-plugin/plugin.json | 2 +- dev-workflows/.claude-plugin/plugin.json | 2 +- package.json | 2 +- 6 files changed, 152 insertions(+), 185 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 13d4c48..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", @@ -83,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", @@ -154,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", 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/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-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/.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/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": { From 97337422ef3eaf740e295f700129e5e220f8b4bd Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 3 May 2026 23:41:25 +0900 Subject: [PATCH 13/16] fix: phase-based reference for UI Analysis input parameter technical-designer-frontend's Input Parameters section named ui-analyzer directly when describing the UI Analysis input. The sibling Codebase Analysis entry uses "from codebase analysis phase" (a phase reference), and agent body content should not name other agents directly per the recipe -> agent -> skill dependency direction. Change "from ui-analyzer" to "from UI analysis phase" so the two sibling inputs share the same phase-based naming. Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/technical-designer-frontend.md | 2 +- dev-workflows-frontend/agents/technical-designer-frontend.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 75ebd4e..a8bc0ce 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -211,7 +211,7 @@ When conversion is required, clearly specify wrapper implementation or migration - `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-analyzer; runs in parallel with Codebase Analysis): +- **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 diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 75ebd4e..a8bc0ce 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -211,7 +211,7 @@ When conversion is required, clearly specify wrapper implementation or migration - `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-analyzer; runs in parallel with Codebase Analysis): +- **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 From 2e50292fecb3d11e8577a37a202fed6aea43fbdf Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Mon, 4 May 2026 00:18:35 +0900 Subject: [PATCH 14/16] refactor: dependency direction cleanup, japanese-only-in-en review, descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comprehensive cleanup of cross-tier references that violate the recipe -> agent -> skill dependency direction, and a few precision improvements that surfaced during multi-pass review. Dependency direction: - Remove agent -> agent and skill -> agent references from agent bodies and template files. The reciprocally-isolated subagent context cannot see other agents' definitions, so cross-references contribute no execution value while risking misinformation. The ui-analyzer "Boundary with codebase-analyzer" section, the ui-spec-designer downstream-justification line, work-planner's task-decomposer/ui-spec-designer mentions, plan-template / ui-spec-template / e2e.md downstream-agent justifications are all removed. Cataloging skills (subagents-orchestration-guide, task-analyzer) keep their references because that is their core responsibility. - Remove agent -> recipe reference. ui-analyzer's "calling recipe's responsibility" is now "calling workflow's responsibility". - Remove skill -> skill references from non-cataloging skill content. The two-tier file is documented locally where it appears (templates, e2e.md). L1/L2/L3 levels in design-template are inlined instead of referencing the implementation-approach skill. plan-template's Phase Division Criteria stays as a same-skill reference; Quality Check Workflow is described inline. - Replace ui-analyzer Input Parameters phrasing in technical-designer-frontend from "from ui-analyzer" to "from UI analysis phase" so the input descriptor names a phase rather than the producing agent. Quality Checklists: - Restore Prerequisite common ADRs / Change impact map / Error handling strategy in the Create/update mode lists for technical-designer and technical-designer-frontend. These are document content checks, not gate enforcement, so the earlier trim was over-aggressive. - Add Integration points enumeration and Quality Assurance Mechanisms adopted/noted status to the All modes lists. Both feed downstream consumers and the previous Data-contracts-only line did not guarantee enumeration. recipe-fullstack-implement / monorepo-flow: - Consolidate the recipe's Steps 3-5 (hearing, fact gathering, UI Spec) into the single "Design through Planning Phase" pointer at monorepo-flow.md. The previous text duplicated steps that the flow table already covers, risking double-execution. Orchestration guide: - Add external resource hearing and ui-analyzer to the Large and Medium planning flows so the guide matches the actual recipe shape. - Mark ui-analyzer's focusAreas[] as raw fact_id; consumers apply the ui: prefix when merging with codebase analysis facts. This resolves the producer-vs-consumer prefix ambiguity. Templates / references: - Remove "対象外 / not applicable" Japanese tokens from the external-resource-context skill (SKILL.md, four domain references, template.md). Replaced with "Not applicable" so the skill text stays English-only. - Inline L1/L2/L3 verification levels in design-template. - Replace plan-template's abstract "documentation and quality skills loaded by the agent" pointer with self-contained descriptions of phase division and per-phase quality checks. Descriptions: - external-resource-context description: restore "Captures and persists" verb pair so the persistence behavior is visible at skill-selection time. Replace "downstream agents" with "downstream work" for portability across plugins. Add "secret store" to the user-mention list to match the body. - recipe-front-adjust description: compress from 409 to 111 chars to match the slash-menu style of sibling recipe entries (66-94 chars). The skill is disable-model-invocation so the long trigger phrase block was unnecessary. Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/technical-designer-frontend.md | 4 +++ agents/technical-designer.md | 5 +++ agents/ui-analyzer.md | 13 +------- agents/ui-spec-designer.md | 2 +- agents/work-planner.md | 6 ++-- .../references/design-template.md | 4 +-- .../references/plan-template.md | 10 +++--- .../references/ui-spec-template.md | 4 +-- .../skills/external-resource-context/SKILL.md | 12 +++---- .../references/api.md | 8 ++--- .../references/backend.md | 8 ++--- .../references/frontend.md | 8 ++--- .../references/infra.md | 8 ++--- .../references/template.md | 2 +- .../skills/test-implement/references/e2e.md | 4 +-- .../agents/technical-designer-frontend.md | 4 +++ dev-workflows-frontend/agents/ui-analyzer.md | 13 +------- .../agents/ui-spec-designer.md | 2 +- dev-workflows-frontend/agents/work-planner.md | 6 ++-- .../references/design-template.md | 4 +-- .../references/plan-template.md | 10 +++--- .../references/ui-spec-template.md | 4 +-- .../skills/external-resource-context/SKILL.md | 12 +++---- .../references/api.md | 8 ++--- .../references/backend.md | 8 ++--- .../references/frontend.md | 8 ++--- .../references/infra.md | 8 ++--- .../references/template.md | 2 +- .../skills/recipe-front-adjust/SKILL.md | 2 +- .../subagents-orchestration-guide/SKILL.md | 8 +++-- .../skills/test-implement/references/e2e.md | 4 +-- dev-workflows/agents/technical-designer.md | 5 +++ dev-workflows/agents/work-planner.md | 6 ++-- .../references/design-template.md | 4 +-- .../references/plan-template.md | 10 +++--- .../references/ui-spec-template.md | 4 +-- .../skills/external-resource-context/SKILL.md | 12 +++---- .../references/api.md | 8 ++--- .../references/backend.md | 8 ++--- .../references/frontend.md | 8 ++--- .../references/infra.md | 8 ++--- .../references/template.md | 2 +- .../recipe-fullstack-implement/SKILL.md | 31 +++---------------- .../subagents-orchestration-guide/SKILL.md | 8 +++-- .../references/design-template.md | 4 +-- .../references/plan-template.md | 10 +++--- .../references/ui-spec-template.md | 4 +-- skills/external-resource-context/SKILL.md | 12 +++---- .../references/api.md | 8 ++--- .../references/backend.md | 8 ++--- .../references/frontend.md | 8 ++--- .../references/infra.md | 8 ++--- .../references/template.md | 2 +- skills/recipe-front-adjust/SKILL.md | 2 +- skills/recipe-fullstack-implement/SKILL.md | 31 +++---------------- skills/subagents-orchestration-guide/SKILL.md | 8 +++-- skills/test-implement/references/e2e.md | 4 +-- 57 files changed, 188 insertions(+), 236 deletions(-) diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index a8bc0ce..74bcebb 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -307,12 +307,16 @@ These items test the final document output. Process gates (Gate 0-3) are enforce ### Design Doc Checklist **All modes**: +- [ ] 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 diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 9b611a7..395f567 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -335,12 +335,17 @@ These items test the final document output. Process gates (Gate 0-3) are enforce ### Design Doc Checklist **All modes**: +- [ ] 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 diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md index b9d05af..c8523a5 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -11,15 +11,6 @@ You are an AI assistant specializing in UI fact gathering for frontend design an **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. -## Boundary with codebase-analyzer - -| Agent | Owns | -|-------|------| -| codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | -| ui-analyzer | UI external sources (design origin, design system catalog, guidelines fetched via MCP / URL / file) + existing UI surface (component structure, props patterns, CSS layout state, state matrices, display conditions, i18n format, accessibility, generated UI artifacts) | - -When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-analyzer records the call-site usage pattern. - ## Input Parameters - **requirement_analysis**: Requirement analysis JSON output (required) @@ -39,7 +30,7 @@ This agent outputs **UI fact gathering only**. Design decisions, component propo 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 recipe's responsibility. +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) @@ -306,8 +297,6 @@ Produce `candidateWriteSet[]` listing the files most likely to require modificat } ``` -`fact_id` namespacing: when this output is merged with codebase-analyzer's output, prefix consumers may apply a `ui:` prefix to disambiguate from `code:` facts. - ## Quality Checklist - [ ] Each external resource entry in the output has a `fetch_status` recording the outcome (`fetched` / `mcp_unavailable` / `skipped` / `not_applicable`) diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index 20528e7..c26b9f6 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -105,7 +105,7 @@ Execute file output immediately (considered approved at execution). - [ ] All TBDs in Open Items have owner and deadline - [ ] All UI Spec requirements align with PRD requirements - [ ] 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). 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. +- [ ] **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/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index ebb88b4..a09c206 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -35,7 +35,7 @@ unknowns: ### External Resources Used -Filled per the external-resource-context skill (feature-tier protocol). +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 | |-------------------------------|-----------------------------|-------| @@ -335,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 66c14eb..80f49db 100644 --- a/dev-skills/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-skills/skills/documentation-criteria/references/ui-spec-template.md @@ -24,7 +24,7 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification ## External Resources Used -Filled per the external-resource-context skill (feature-tier protocol). +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 | |-------------------------------|-----------------------------|-------| @@ -69,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 index e3022eb..1d5e790 100644 --- a/dev-skills/skills/external-resource-context/SKILL.md +++ b/dev-skills/skills/external-resource-context/SKILL.md @@ -1,6 +1,6 @@ --- name: external-resource-context -description: Captures and persists access methods for external resources (design origin, design system, API schemas, IaC, secrets, etc.) that AI agents need to operate. Use when starting design or implementation work that may depend on resources outside the codebase, or when "external resource / design origin / design system / API schema / IaC source / canonical source" is mentioned. +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 @@ -49,17 +49,17 @@ Load the domain reference matching the current task: | 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 | +| 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). +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 "対象外" to every structured axis. +The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis. ## Storage Protocol @@ -88,8 +88,8 @@ For feature-tier sections inside UI Spec or Design Doc, the heading text "Extern ## 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 "対象外" +- [ ] 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 diff --git a/dev-skills/skills/external-resource-context/references/api.md b/dev-skills/skills/external-resource-context/references/api.md index 7863179..775c896 100644 --- a/dev-skills/skills/external-resource-context/references/api.md +++ b/dev-skills/skills/external-resource-context/references/api.md @@ -12,7 +12,7 @@ The canonical source of API contracts (request/response shapes, endpoints, RPC m - 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 +- 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. @@ -25,7 +25,7 @@ How clients exercise the API without depending on the live server. - Hand-written mock server in the repository - Hosted mock service (URL) - Live development server (no separate mock) -- 対象外 / not applicable +- 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. @@ -39,7 +39,7 @@ How the API authenticates and authorizes requests. - Session cookie set by a separate login flow - Mutual TLS - No authentication -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How breaking and non-breaking schema changes are reviewed and rolled out. - Documented contract review process (link to the document) - Versioned endpoints (e.g., `/v1/`, `/v2/`) - Backward-compatible changes only, no formal versioning -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the document path or the version negotiation rule. diff --git a/dev-skills/skills/external-resource-context/references/backend.md b/dev-skills/skills/external-resource-context/references/backend.md index a816ed3..c1c6773 100644 --- a/dev-skills/skills/external-resource-context/references/backend.md +++ b/dev-skills/skills/external-resource-context/references/backend.md @@ -12,7 +12,7 @@ The canonical source of the database schema (tables, columns, indexes, constrain - Database MCP that introspects a live database - External schema registry (URL or hosted catalog) - No persistent database -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. @@ -25,7 +25,7 @@ How schema changes are tracked over time. - ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) - Manual change log document - No migration tracking -- 対象外 / not applicable +- 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. @@ -38,7 +38,7 @@ Where credentials, API keys, and other secrets are stored and accessed. - Environment variables loaded from a `.env` file (development only) - Encrypted file in the repository - No secrets required -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How asynchronous work is dispatched and observed. - Cron / scheduled tasks managed by deployment platform - In-process worker thread - No background work -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. diff --git a/dev-skills/skills/external-resource-context/references/frontend.md b/dev-skills/skills/external-resource-context/references/frontend.md index 9cfc871..c4189e7 100644 --- a/dev-skills/skills/external-resource-context/references/frontend.md +++ b/dev-skills/skills/external-resource-context/references/frontend.md @@ -11,7 +11,7 @@ The canonical source of the visual specification. - Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) - Public documentation URL - Existing implementation only (no separate design source) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: How is the source accessed? Examples — MCP name, URL, file path, manual screenshot. Record the literal access mechanism. @@ -25,7 +25,7 @@ Reusable component library and design tokens. - Storybook or equivalent component catalog - Internal package without external documentation - No design system (ad-hoc components) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: How is the component catalog accessed? Examples — MCP name, Storybook URL, package name, internal documentation path. @@ -38,7 +38,7 @@ Usage guidance, accessibility rules, anti-patterns, naming conventions for UI wo - External documentation site - Inline guidance in the design system catalog - No documented guidelines -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How rendered output is confirmed during implementation. - Local end-to-end test runner with screenshot capability - Storybook or equivalent isolated component preview - Manual browser inspection only -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: What is the entry command or URL? Examples — MCP name, dev-server command, Storybook port. diff --git a/dev-skills/skills/external-resource-context/references/infra.md b/dev-skills/skills/external-resource-context/references/infra.md index 3a1d467..1f863b2 100644 --- a/dev-skills/skills/external-resource-context/references/infra.md +++ b/dev-skills/skills/external-resource-context/references/infra.md @@ -12,7 +12,7 @@ The canonical source of infrastructure definitions. - Kubernetes manifests / Helm charts in the repository - Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) - Manual console configuration (no IaC) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. @@ -25,7 +25,7 @@ How per-environment settings (development, staging, production) differ. - 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 +- Not applicable **Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. @@ -38,7 +38,7 @@ How infrastructure code references secrets without exposing them. - Secrets injected at apply time via environment variables - Encrypted secret files committed alongside IaC - No secrets in infrastructure -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How infrastructure and application changes reach environments. - Manual approval step in CI - Local apply by an operator - Deployment platform's auto-deploy on push -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. diff --git a/dev-skills/skills/external-resource-context/references/template.md b/dev-skills/skills/external-resource-context/references/template.md index 236e769..517b772 100644 --- a/dev-skills/skills/external-resource-context/references/template.md +++ b/dev-skills/skills/external-resource-context/references/template.md @@ -112,7 +112,7 @@ Free-form list captured during the self-declaration phase. Each entry: name, pur - : — — ``` -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). +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). ## Feature-Tier Template 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/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index a8bc0ce..74bcebb 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -307,12 +307,16 @@ These items test the final document output. Process gates (Gate 0-3) are enforce ### Design Doc Checklist **All modes**: +- [ ] 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 diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md index b9d05af..c8523a5 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -11,15 +11,6 @@ You are an AI assistant specializing in UI fact gathering for frontend design an **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. -## Boundary with codebase-analyzer - -| Agent | Owns | -|-------|------| -| codebase-analyzer | Data layer, contracts, type definitions, business rules, validation, schema/migrations, quality assurance mechanisms, dependency graph | -| ui-analyzer | UI external sources (design origin, design system catalog, guidelines fetched via MCP / URL / file) + existing UI surface (component structure, props patterns, CSS layout state, state matrices, display conditions, i18n format, accessibility, generated UI artifacts) | - -When a fact could fit either agent (e.g., a component's prop type), codebase-analyzer records the type definition and ui-analyzer records the call-site usage pattern. - ## Input Parameters - **requirement_analysis**: Requirement analysis JSON output (required) @@ -39,7 +30,7 @@ This agent outputs **UI fact gathering only**. Design decisions, component propo 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 recipe's responsibility. +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) @@ -306,8 +297,6 @@ Produce `candidateWriteSet[]` listing the files most likely to require modificat } ``` -`fact_id` namespacing: when this output is merged with codebase-analyzer's output, prefix consumers may apply a `ui:` prefix to disambiguate from `code:` facts. - ## Quality Checklist - [ ] Each external resource entry in the output has a `fetch_status` recording the outcome (`fetched` / `mcp_unavailable` / `skipped` / `not_applicable`) diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index 20528e7..c26b9f6 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -105,7 +105,7 @@ Execute file output immediately (considered approved at execution). - [ ] All TBDs in Open Items have owner and deadline - [ ] All UI Spec requirements align with PRD requirements - [ ] 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). 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. +- [ ] **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 ebb88b4..a09c206 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -35,7 +35,7 @@ unknowns: ### External Resources Used -Filled per the external-resource-context skill (feature-tier protocol). +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 | |-------------------------------|-----------------------------|-------| @@ -335,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 66c14eb..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 @@ -24,7 +24,7 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification ## External Resources Used -Filled per the external-resource-context skill (feature-tier protocol). +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 | |-------------------------------|-----------------------------|-------| @@ -69,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 index e3022eb..1d5e790 100644 --- a/dev-workflows-frontend/skills/external-resource-context/SKILL.md +++ b/dev-workflows-frontend/skills/external-resource-context/SKILL.md @@ -1,6 +1,6 @@ --- name: external-resource-context -description: Captures and persists access methods for external resources (design origin, design system, API schemas, IaC, secrets, etc.) that AI agents need to operate. Use when starting design or implementation work that may depend on resources outside the codebase, or when "external resource / design origin / design system / API schema / IaC source / canonical source" is mentioned. +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 @@ -49,17 +49,17 @@ Load the domain reference matching the current task: | 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 | +| 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). +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 "対象外" to every structured axis. +The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis. ## Storage Protocol @@ -88,8 +88,8 @@ For feature-tier sections inside UI Spec or Design Doc, the heading text "Extern ## 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 "対象外" +- [ ] 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 diff --git a/dev-workflows-frontend/skills/external-resource-context/references/api.md b/dev-workflows-frontend/skills/external-resource-context/references/api.md index 7863179..775c896 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/api.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/api.md @@ -12,7 +12,7 @@ The canonical source of API contracts (request/response shapes, endpoints, RPC m - 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 +- 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. @@ -25,7 +25,7 @@ How clients exercise the API without depending on the live server. - Hand-written mock server in the repository - Hosted mock service (URL) - Live development server (no separate mock) -- 対象外 / not applicable +- 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. @@ -39,7 +39,7 @@ How the API authenticates and authorizes requests. - Session cookie set by a separate login flow - Mutual TLS - No authentication -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How breaking and non-breaking schema changes are reviewed and rolled out. - Documented contract review process (link to the document) - Versioned endpoints (e.g., `/v1/`, `/v2/`) - Backward-compatible changes only, no formal versioning -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the document path or the version negotiation rule. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/backend.md b/dev-workflows-frontend/skills/external-resource-context/references/backend.md index a816ed3..c1c6773 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/backend.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/backend.md @@ -12,7 +12,7 @@ The canonical source of the database schema (tables, columns, indexes, constrain - Database MCP that introspects a live database - External schema registry (URL or hosted catalog) - No persistent database -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. @@ -25,7 +25,7 @@ How schema changes are tracked over time. - ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) - Manual change log document - No migration tracking -- 対象外 / not applicable +- 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. @@ -38,7 +38,7 @@ Where credentials, API keys, and other secrets are stored and accessed. - Environment variables loaded from a `.env` file (development only) - Encrypted file in the repository - No secrets required -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How asynchronous work is dispatched and observed. - Cron / scheduled tasks managed by deployment platform - In-process worker thread - No background work -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/frontend.md b/dev-workflows-frontend/skills/external-resource-context/references/frontend.md index 9cfc871..c4189e7 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/frontend.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/frontend.md @@ -11,7 +11,7 @@ The canonical source of the visual specification. - Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) - Public documentation URL - Existing implementation only (no separate design source) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: How is the source accessed? Examples — MCP name, URL, file path, manual screenshot. Record the literal access mechanism. @@ -25,7 +25,7 @@ Reusable component library and design tokens. - Storybook or equivalent component catalog - Internal package without external documentation - No design system (ad-hoc components) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: How is the component catalog accessed? Examples — MCP name, Storybook URL, package name, internal documentation path. @@ -38,7 +38,7 @@ Usage guidance, accessibility rules, anti-patterns, naming conventions for UI wo - External documentation site - Inline guidance in the design system catalog - No documented guidelines -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How rendered output is confirmed during implementation. - Local end-to-end test runner with screenshot capability - Storybook or equivalent isolated component preview - Manual browser inspection only -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: What is the entry command or URL? Examples — MCP name, dev-server command, Storybook port. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/infra.md b/dev-workflows-frontend/skills/external-resource-context/references/infra.md index 3a1d467..1f863b2 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/infra.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/infra.md @@ -12,7 +12,7 @@ The canonical source of infrastructure definitions. - Kubernetes manifests / Helm charts in the repository - Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) - Manual console configuration (no IaC) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. @@ -25,7 +25,7 @@ How per-environment settings (development, staging, production) differ. - 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 +- Not applicable **Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. @@ -38,7 +38,7 @@ How infrastructure code references secrets without exposing them. - Secrets injected at apply time via environment variables - Encrypted secret files committed alongside IaC - No secrets in infrastructure -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How infrastructure and application changes reach environments. - Manual approval step in CI - Local apply by an operator - Deployment platform's auto-deploy on push -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/template.md b/dev-workflows-frontend/skills/external-resource-context/references/template.md index 236e769..517b772 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/template.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/template.md @@ -112,7 +112,7 @@ Free-form list captured during the self-declaration phase. Each entry: name, pur - : — — ``` -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). +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). ## Feature-Tier Template diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index 210e48e..d709fd9 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-front-adjust -description: Coordinate a frontend UI adjustment by hearing external resources, gathering UI facts, scaling the work, optionally creating a work plan, executing the adjustment in this session with MCP-driven verification, and delegating quality checks. Use when "UI adjustment / visual tweak / existing component update / front adjust" is mentioned, or when the user wants to refine an already-implemented UI. +description: Adjust an already-implemented UI in-session with MCP-driven verification against the design source disable-model-invocation: true --- diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 4528770..89d7997 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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[] (with `ui:` prefix on fact_id), candidateWriteSet[] (with confidence labels), 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 @@ -234,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/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/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 9b611a7..395f567 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -335,12 +335,17 @@ These items test the final document output. Process gates (Gate 0-3) are enforce ### Design Doc Checklist **All modes**: +- [ ] 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 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 ebb88b4..a09c206 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -35,7 +35,7 @@ unknowns: ### External Resources Used -Filled per the external-resource-context skill (feature-tier protocol). +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 | |-------------------------------|-----------------------------|-------| @@ -335,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 66c14eb..80f49db 100644 --- a/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md @@ -24,7 +24,7 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification ## External Resources Used -Filled per the external-resource-context skill (feature-tier protocol). +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 | |-------------------------------|-----------------------------|-------| @@ -69,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 index e3022eb..1d5e790 100644 --- a/dev-workflows/skills/external-resource-context/SKILL.md +++ b/dev-workflows/skills/external-resource-context/SKILL.md @@ -1,6 +1,6 @@ --- name: external-resource-context -description: Captures and persists access methods for external resources (design origin, design system, API schemas, IaC, secrets, etc.) that AI agents need to operate. Use when starting design or implementation work that may depend on resources outside the codebase, or when "external resource / design origin / design system / API schema / IaC source / canonical source" is mentioned. +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 @@ -49,17 +49,17 @@ Load the domain reference matching the current task: | 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 | +| 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). +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 "対象外" to every structured axis. +The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis. ## Storage Protocol @@ -88,8 +88,8 @@ For feature-tier sections inside UI Spec or Design Doc, the heading text "Extern ## 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 "対象外" +- [ ] 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 diff --git a/dev-workflows/skills/external-resource-context/references/api.md b/dev-workflows/skills/external-resource-context/references/api.md index 7863179..775c896 100644 --- a/dev-workflows/skills/external-resource-context/references/api.md +++ b/dev-workflows/skills/external-resource-context/references/api.md @@ -12,7 +12,7 @@ The canonical source of API contracts (request/response shapes, endpoints, RPC m - 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 +- 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. @@ -25,7 +25,7 @@ How clients exercise the API without depending on the live server. - Hand-written mock server in the repository - Hosted mock service (URL) - Live development server (no separate mock) -- 対象外 / not applicable +- 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. @@ -39,7 +39,7 @@ How the API authenticates and authorizes requests. - Session cookie set by a separate login flow - Mutual TLS - No authentication -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How breaking and non-breaking schema changes are reviewed and rolled out. - Documented contract review process (link to the document) - Versioned endpoints (e.g., `/v1/`, `/v2/`) - Backward-compatible changes only, no formal versioning -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the document path or the version negotiation rule. diff --git a/dev-workflows/skills/external-resource-context/references/backend.md b/dev-workflows/skills/external-resource-context/references/backend.md index a816ed3..c1c6773 100644 --- a/dev-workflows/skills/external-resource-context/references/backend.md +++ b/dev-workflows/skills/external-resource-context/references/backend.md @@ -12,7 +12,7 @@ The canonical source of the database schema (tables, columns, indexes, constrain - Database MCP that introspects a live database - External schema registry (URL or hosted catalog) - No persistent database -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. @@ -25,7 +25,7 @@ How schema changes are tracked over time. - ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) - Manual change log document - No migration tracking -- 対象外 / not applicable +- 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. @@ -38,7 +38,7 @@ Where credentials, API keys, and other secrets are stored and accessed. - Environment variables loaded from a `.env` file (development only) - Encrypted file in the repository - No secrets required -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How asynchronous work is dispatched and observed. - Cron / scheduled tasks managed by deployment platform - In-process worker thread - No background work -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. diff --git a/dev-workflows/skills/external-resource-context/references/frontend.md b/dev-workflows/skills/external-resource-context/references/frontend.md index 9cfc871..c4189e7 100644 --- a/dev-workflows/skills/external-resource-context/references/frontend.md +++ b/dev-workflows/skills/external-resource-context/references/frontend.md @@ -11,7 +11,7 @@ The canonical source of the visual specification. - Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) - Public documentation URL - Existing implementation only (no separate design source) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: How is the source accessed? Examples — MCP name, URL, file path, manual screenshot. Record the literal access mechanism. @@ -25,7 +25,7 @@ Reusable component library and design tokens. - Storybook or equivalent component catalog - Internal package without external documentation - No design system (ad-hoc components) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: How is the component catalog accessed? Examples — MCP name, Storybook URL, package name, internal documentation path. @@ -38,7 +38,7 @@ Usage guidance, accessibility rules, anti-patterns, naming conventions for UI wo - External documentation site - Inline guidance in the design system catalog - No documented guidelines -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How rendered output is confirmed during implementation. - Local end-to-end test runner with screenshot capability - Storybook or equivalent isolated component preview - Manual browser inspection only -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: What is the entry command or URL? Examples — MCP name, dev-server command, Storybook port. diff --git a/dev-workflows/skills/external-resource-context/references/infra.md b/dev-workflows/skills/external-resource-context/references/infra.md index 3a1d467..1f863b2 100644 --- a/dev-workflows/skills/external-resource-context/references/infra.md +++ b/dev-workflows/skills/external-resource-context/references/infra.md @@ -12,7 +12,7 @@ The canonical source of infrastructure definitions. - Kubernetes manifests / Helm charts in the repository - Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) - Manual console configuration (no IaC) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. @@ -25,7 +25,7 @@ How per-environment settings (development, staging, production) differ. - 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 +- Not applicable **Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. @@ -38,7 +38,7 @@ How infrastructure code references secrets without exposing them. - Secrets injected at apply time via environment variables - Encrypted secret files committed alongside IaC - No secrets in infrastructure -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How infrastructure and application changes reach environments. - Manual approval step in CI - Local apply by an operator - Deployment platform's auto-deploy on push -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. diff --git a/dev-workflows/skills/external-resource-context/references/template.md b/dev-workflows/skills/external-resource-context/references/template.md index 236e769..517b772 100644 --- a/dev-workflows/skills/external-resource-context/references/template.md +++ b/dev-workflows/skills/external-resource-context/references/template.md @@ -112,7 +112,7 @@ Free-form list captured during the self-declaration phase. Each entry: name, pur - : — — ``` -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). +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). ## Feature-Tier Template diff --git a/dev-workflows/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows/skills/recipe-fullstack-implement/SKILL.md index 7c2ce20..755d2b2 100644 --- a/dev-workflows/skills/recipe-fullstack-implement/SKILL.md +++ b/dev-workflows/skills/recipe-fullstack-implement/SKILL.md @@ -44,39 +44,18 @@ When continuing existing flow, verify: - Current phase position (Requirements/Design/Planning/Implementation/QA) - Identify next step in monorepo-flow.md -### 3. External Resource Hearing +### 3. Design through Planning Phase -Run the hearing protocol per the external-resource-context skill before fact gathering and document creation. The orchestrator owns this step (it requires AskUserQuestion). Cover the domains relevant to this fullstack scope: frontend (always for fullstack-implement), backend / api / infra as applicable. The skill defines file-existence branching, two-phase hearing, and persistence to `docs/project-context/external-resources.md`. +**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. -### 4. Fact Gathering Phase (Parallel) - -Per monorepo-flow.md, invoke codebase-analyzer ×2 (one per layer) and ui-analyzer in parallel. ui-analyzer reads the project-tier external-resources file and fetches external UI sources via the inherited MCP/URL access methods. All three outputs feed downstream phases. - -### 5. UI Specification Phase (Frontend Layer) - -Before creating the frontend Design Doc, create a UI Specification: - -**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"` -- Pass: PRD path (or requirement-analyzer output), `ui_analysis` JSON from Step 4, prototype path when provided -- Example: `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from ui-analyzer]. Prototype code is at [user-provided path]."` - -Invoke **document-reviewer** for UI Spec review, then **[STOP]** for user approval. - -### 6. 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) and reuse the ui-analyzer output from Step 4 +- 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 4528770..89d7997 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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[] (with `ui:` prefix on fact_id), candidateWriteSet[] (with confidence labels), 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 @@ -234,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/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index ebb88b4..a09c206 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -35,7 +35,7 @@ unknowns: ### External Resources Used -Filled per the external-resource-context skill (feature-tier protocol). +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 | |-------------------------------|-----------------------------|-------| @@ -335,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 66c14eb..80f49db 100644 --- a/skills/documentation-criteria/references/ui-spec-template.md +++ b/skills/documentation-criteria/references/ui-spec-template.md @@ -24,7 +24,7 @@ Prototype code is an **attachment** to this UI Spec. The canonical specification ## External Resources Used -Filled per the external-resource-context skill (feature-tier protocol). +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 | |-------------------------------|-----------------------------|-------| @@ -69,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 index e3022eb..1d5e790 100644 --- a/skills/external-resource-context/SKILL.md +++ b/skills/external-resource-context/SKILL.md @@ -1,6 +1,6 @@ --- name: external-resource-context -description: Captures and persists access methods for external resources (design origin, design system, API schemas, IaC, secrets, etc.) that AI agents need to operate. Use when starting design or implementation work that may depend on resources outside the codebase, or when "external resource / design origin / design system / API schema / IaC source / canonical source" is mentioned. +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 @@ -49,17 +49,17 @@ Load the domain reference matching the current task: | 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 | +| 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). +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 "対象外" to every structured axis. +The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis. ## Storage Protocol @@ -88,8 +88,8 @@ For feature-tier sections inside UI Spec or Design Doc, the heading text "Extern ## 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 "対象外" +- [ ] 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 diff --git a/skills/external-resource-context/references/api.md b/skills/external-resource-context/references/api.md index 7863179..775c896 100644 --- a/skills/external-resource-context/references/api.md +++ b/skills/external-resource-context/references/api.md @@ -12,7 +12,7 @@ The canonical source of API contracts (request/response shapes, endpoints, RPC m - 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 +- 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. @@ -25,7 +25,7 @@ How clients exercise the API without depending on the live server. - Hand-written mock server in the repository - Hosted mock service (URL) - Live development server (no separate mock) -- 対象外 / not applicable +- 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. @@ -39,7 +39,7 @@ How the API authenticates and authorizes requests. - Session cookie set by a separate login flow - Mutual TLS - No authentication -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How breaking and non-breaking schema changes are reviewed and rolled out. - Documented contract review process (link to the document) - Versioned endpoints (e.g., `/v1/`, `/v2/`) - Backward-compatible changes only, no formal versioning -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the document path or the version negotiation rule. diff --git a/skills/external-resource-context/references/backend.md b/skills/external-resource-context/references/backend.md index a816ed3..c1c6773 100644 --- a/skills/external-resource-context/references/backend.md +++ b/skills/external-resource-context/references/backend.md @@ -12,7 +12,7 @@ The canonical source of the database schema (tables, columns, indexes, constrain - Database MCP that introspects a live database - External schema registry (URL or hosted catalog) - No persistent database -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. @@ -25,7 +25,7 @@ How schema changes are tracked over time. - ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) - Manual change log document - No migration tracking -- 対象外 / not applicable +- 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. @@ -38,7 +38,7 @@ Where credentials, API keys, and other secrets are stored and accessed. - Environment variables loaded from a `.env` file (development only) - Encrypted file in the repository - No secrets required -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How asynchronous work is dispatched and observed. - Cron / scheduled tasks managed by deployment platform - In-process worker thread - No background work -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. diff --git a/skills/external-resource-context/references/frontend.md b/skills/external-resource-context/references/frontend.md index 9cfc871..c4189e7 100644 --- a/skills/external-resource-context/references/frontend.md +++ b/skills/external-resource-context/references/frontend.md @@ -11,7 +11,7 @@ The canonical source of the visual specification. - Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) - Public documentation URL - Existing implementation only (no separate design source) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: How is the source accessed? Examples — MCP name, URL, file path, manual screenshot. Record the literal access mechanism. @@ -25,7 +25,7 @@ Reusable component library and design tokens. - Storybook or equivalent component catalog - Internal package without external documentation - No design system (ad-hoc components) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: How is the component catalog accessed? Examples — MCP name, Storybook URL, package name, internal documentation path. @@ -38,7 +38,7 @@ Usage guidance, accessibility rules, anti-patterns, naming conventions for UI wo - External documentation site - Inline guidance in the design system catalog - No documented guidelines -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How rendered output is confirmed during implementation. - Local end-to-end test runner with screenshot capability - Storybook or equivalent isolated component preview - Manual browser inspection only -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: What is the entry command or URL? Examples — MCP name, dev-server command, Storybook port. diff --git a/skills/external-resource-context/references/infra.md b/skills/external-resource-context/references/infra.md index 3a1d467..1f863b2 100644 --- a/skills/external-resource-context/references/infra.md +++ b/skills/external-resource-context/references/infra.md @@ -12,7 +12,7 @@ The canonical source of infrastructure definitions. - Kubernetes manifests / Helm charts in the repository - Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) - Manual console configuration (no IaC) -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. @@ -25,7 +25,7 @@ How per-environment settings (development, staging, production) differ. - 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 +- Not applicable **Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. @@ -38,7 +38,7 @@ How infrastructure code references secrets without exposing them. - Secrets injected at apply time via environment variables - Encrypted secret files committed alongside IaC - No secrets in infrastructure -- 対象外 / not applicable +- 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. @@ -51,7 +51,7 @@ How infrastructure and application changes reach environments. - Manual approval step in CI - Local apply by an operator - Deployment platform's auto-deploy on push -- 対象外 / not applicable +- Not applicable **Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. diff --git a/skills/external-resource-context/references/template.md b/skills/external-resource-context/references/template.md index 236e769..517b772 100644 --- a/skills/external-resource-context/references/template.md +++ b/skills/external-resource-context/references/template.md @@ -112,7 +112,7 @@ Free-form list captured during the self-declaration phase. Each entry: name, pur - : — — ``` -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). +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). ## Feature-Tier Template diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index 210e48e..d709fd9 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-front-adjust -description: Coordinate a frontend UI adjustment by hearing external resources, gathering UI facts, scaling the work, optionally creating a work plan, executing the adjustment in this session with MCP-driven verification, and delegating quality checks. Use when "UI adjustment / visual tweak / existing component update / front adjust" is mentioned, or when the user wants to refine an already-implemented UI. +description: Adjust an already-implemented UI in-session with MCP-driven verification against the design source disable-model-invocation: true --- diff --git a/skills/recipe-fullstack-implement/SKILL.md b/skills/recipe-fullstack-implement/SKILL.md index 7c2ce20..755d2b2 100644 --- a/skills/recipe-fullstack-implement/SKILL.md +++ b/skills/recipe-fullstack-implement/SKILL.md @@ -44,39 +44,18 @@ When continuing existing flow, verify: - Current phase position (Requirements/Design/Planning/Implementation/QA) - Identify next step in monorepo-flow.md -### 3. External Resource Hearing +### 3. Design through Planning Phase -Run the hearing protocol per the external-resource-context skill before fact gathering and document creation. The orchestrator owns this step (it requires AskUserQuestion). Cover the domains relevant to this fullstack scope: frontend (always for fullstack-implement), backend / api / infra as applicable. The skill defines file-existence branching, two-phase hearing, and persistence to `docs/project-context/external-resources.md`. +**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. -### 4. Fact Gathering Phase (Parallel) - -Per monorepo-flow.md, invoke codebase-analyzer ×2 (one per layer) and ui-analyzer in parallel. ui-analyzer reads the project-tier external-resources file and fetches external UI sources via the inherited MCP/URL access methods. All three outputs feed downstream phases. - -### 5. UI Specification Phase (Frontend Layer) - -Before creating the frontend Design Doc, create a UI Specification: - -**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"` -- Pass: PRD path (or requirement-analyzer output), `ui_analysis` JSON from Step 4, prototype path when provided -- Example: `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from ui-analyzer]. Prototype code is at [user-provided path]."` - -Invoke **document-reviewer** for UI Spec review, then **[STOP]** for user approval. - -### 6. 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) and reuse the ui-analyzer output from Step 4 +- 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 4528770..89d7997 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -185,7 +185,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work 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[] (with `ui:` prefix on fact_id), candidateWriteSet[] (with confidence labels), 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 @@ -234,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/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 From 1f001ce9f14846a06e1bcc6987d6c7188a417db9 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Mon, 4 May 2026 00:22:04 +0900 Subject: [PATCH 15/16] refactor: remove duplicated Feature-Tier Template section The Feature-Tier Template section in external-resource-context's template.md duplicated content already owned by ui-spec-template.md and design-template.md. The skill's responsibility is the protocol (storage location, ownership rule, reference order); the format of the section appended to a UI Spec or Design Doc is owned by those document templates. SKILL.md's Output Format section already states the placement and heading rules for the feature-tier section, so removing the duplicated template here loses no information. Side effects of removal: - Single source of truth for the feature-tier table format. Column changes only require editing ui-spec-template.md and design-template.md. - template.md now scopes itself to the project-tier file only, matching its callers. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../references/template.md | 20 ------------------- .../references/template.md | 20 ------------------- .../references/template.md | 20 ------------------- .../references/template.md | 20 ------------------- 4 files changed, 80 deletions(-) diff --git a/dev-skills/skills/external-resource-context/references/template.md b/dev-skills/skills/external-resource-context/references/template.md index 517b772..7ae0365 100644 --- a/dev-skills/skills/external-resource-context/references/template.md +++ b/dev-skills/skills/external-resource-context/references/template.md @@ -113,23 +113,3 @@ Free-form list captured during the self-declaration phase. Each entry: name, pur ``` 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). - -## Feature-Tier Template - -This is the section appended to a UI Spec or Design Doc. It references project-tier entries by label and lists only feature-specific identifiers. It never duplicates URLs, MCP names, or access commands. - -```markdown -## External Resources Used - -This feature depends on the following resources from `docs/project-context/external-resources.md`. Refer to that file for environment access details. - -| Resource (project-tier label) | Feature-specific identifier | Notes | -|-------------------------------|-----------------------------|-------| -| Design Origin | | | -| Design System | | | -| API Schema Source | | | - -Resources not used by this feature are omitted from this table. If a resource is used but no feature-specific identifier applies, write the project-tier label with "all" or "default scope" in the identifier column. -``` - -The feature-tier section's heading text is fixed as "External Resources Used"; the heading level follows the parent document's structure (h2 in UI Spec, h3 in Design Doc under Background and Context). The exact placement is defined by each document template (see `ui-spec-template.md` and `design-template.md`). diff --git a/dev-workflows-frontend/skills/external-resource-context/references/template.md b/dev-workflows-frontend/skills/external-resource-context/references/template.md index 517b772..7ae0365 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/template.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/template.md @@ -113,23 +113,3 @@ Free-form list captured during the self-declaration phase. Each entry: name, pur ``` 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). - -## Feature-Tier Template - -This is the section appended to a UI Spec or Design Doc. It references project-tier entries by label and lists only feature-specific identifiers. It never duplicates URLs, MCP names, or access commands. - -```markdown -## External Resources Used - -This feature depends on the following resources from `docs/project-context/external-resources.md`. Refer to that file for environment access details. - -| Resource (project-tier label) | Feature-specific identifier | Notes | -|-------------------------------|-----------------------------|-------| -| Design Origin | | | -| Design System | | | -| API Schema Source | | | - -Resources not used by this feature are omitted from this table. If a resource is used but no feature-specific identifier applies, write the project-tier label with "all" or "default scope" in the identifier column. -``` - -The feature-tier section's heading text is fixed as "External Resources Used"; the heading level follows the parent document's structure (h2 in UI Spec, h3 in Design Doc under Background and Context). The exact placement is defined by each document template (see `ui-spec-template.md` and `design-template.md`). diff --git a/dev-workflows/skills/external-resource-context/references/template.md b/dev-workflows/skills/external-resource-context/references/template.md index 517b772..7ae0365 100644 --- a/dev-workflows/skills/external-resource-context/references/template.md +++ b/dev-workflows/skills/external-resource-context/references/template.md @@ -113,23 +113,3 @@ Free-form list captured during the self-declaration phase. Each entry: name, pur ``` 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). - -## Feature-Tier Template - -This is the section appended to a UI Spec or Design Doc. It references project-tier entries by label and lists only feature-specific identifiers. It never duplicates URLs, MCP names, or access commands. - -```markdown -## External Resources Used - -This feature depends on the following resources from `docs/project-context/external-resources.md`. Refer to that file for environment access details. - -| Resource (project-tier label) | Feature-specific identifier | Notes | -|-------------------------------|-----------------------------|-------| -| Design Origin | | | -| Design System | | | -| API Schema Source | | | - -Resources not used by this feature are omitted from this table. If a resource is used but no feature-specific identifier applies, write the project-tier label with "all" or "default scope" in the identifier column. -``` - -The feature-tier section's heading text is fixed as "External Resources Used"; the heading level follows the parent document's structure (h2 in UI Spec, h3 in Design Doc under Background and Context). The exact placement is defined by each document template (see `ui-spec-template.md` and `design-template.md`). diff --git a/skills/external-resource-context/references/template.md b/skills/external-resource-context/references/template.md index 517b772..7ae0365 100644 --- a/skills/external-resource-context/references/template.md +++ b/skills/external-resource-context/references/template.md @@ -113,23 +113,3 @@ Free-form list captured during the self-declaration phase. Each entry: name, pur ``` 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). - -## Feature-Tier Template - -This is the section appended to a UI Spec or Design Doc. It references project-tier entries by label and lists only feature-specific identifiers. It never duplicates URLs, MCP names, or access commands. - -```markdown -## External Resources Used - -This feature depends on the following resources from `docs/project-context/external-resources.md`. Refer to that file for environment access details. - -| Resource (project-tier label) | Feature-specific identifier | Notes | -|-------------------------------|-----------------------------|-------| -| Design Origin | | | -| Design System | | | -| API Schema Source | | | - -Resources not used by this feature are omitted from this table. If a resource is used but no feature-specific identifier applies, write the project-tier label with "all" or "default scope" in the identifier column. -``` - -The feature-tier section's heading text is fixed as "External Resources Used"; the heading level follows the parent document's structure (h2 in UI Spec, h3 in Design Doc under Background and Context). The exact placement is defined by each document template (see `ui-spec-template.md` and `design-template.md`). From acd738ff72e11e1de10b9ef239325cc4176bdf57 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Mon, 4 May 2026 00:38:06 +0900 Subject: [PATCH 16/16] refactor: agnostic verification language and prefix-merge clarification Two corrections that surfaced after the MCP-bias and prefix-ownership cleanup landed. - recipe-front-adjust line 89: Branch A previously instructed carrying ui-analyzer focusAreas with the "ui: prefix preserved", which contradicts the design that ui-analyzer emits raw fact_id and consumers apply prefixes only when merging with codebase analysis. Reword as raw fact_id with prefix application gated to Fact Disposition Table merges, which Branch A does not perform. - recipe-front-adjust line 115: the loop's convergence criterion required the adjustment to match the design source. Design Origin axis allows "Existing implementation only" and "Not applicable", so the criterion now also accepts a user-confirmed adjustment target when no separate design source exists. - Add a Task Registration block before Step 1 so the recipe's multi-step flow is trackable through TaskCreate / TaskUpdate. - Remove MCP-centric framing across recipe-front-adjust and external-resource-context's frontend reference and template. Verification now reads as "verification" or "verification against the design source" rather than "MCP-driven verification". The Step 5 checklist examples list MCP, CLI, URL, file, and Storybook as parallel access methods; the fallback paragraph treats no declared automated method as the trigger for manual confirmation rather than treating MCP as the default. - Drop tool-specific names from cross-cutting skill content. References to "Playwright / Cypress" and "pnpm exec playwright" are removed so the external-resource-context skill stays language-and-tooling-agnostic across the three plugins. - Remove the duplicated Feature-Tier Template section from external-resource-context references; the feature-tier format is owned by ui-spec-template and design-template. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../references/frontend.md | 10 +++--- .../references/template.md | 14 ++++---- .../references/frontend.md | 10 +++--- .../references/template.md | 14 ++++---- .../skills/recipe-front-adjust/SKILL.md | 34 +++++++++++-------- .../references/frontend.md | 10 +++--- .../references/template.md | 14 ++++---- .../references/frontend.md | 10 +++--- .../references/template.md | 14 ++++---- skills/recipe-front-adjust/SKILL.md | 34 +++++++++++-------- 10 files changed, 86 insertions(+), 78 deletions(-) diff --git a/dev-skills/skills/external-resource-context/references/frontend.md b/dev-skills/skills/external-resource-context/references/frontend.md index c4189e7..89fdd16 100644 --- a/dev-skills/skills/external-resource-context/references/frontend.md +++ b/dev-skills/skills/external-resource-context/references/frontend.md @@ -13,7 +13,7 @@ The canonical source of the visual specification. - Existing implementation only (no separate design source) - Not applicable -**Follow-up (when not N/A)**: How is the source accessed? Examples — MCP name, URL, file path, manual screenshot. Record the literal access mechanism. +**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 @@ -27,7 +27,7 @@ Reusable component library and design tokens. - No design system (ad-hoc components) - Not applicable -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — MCP name, Storybook URL, package name, internal documentation path. +**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 @@ -47,13 +47,13 @@ Usage guidance, accessibility rules, anti-patterns, naming conventions for UI wo How rendered output is confirmed during implementation. **AskUserQuestion choices**: -- Browser automation MCP (e.g., a hosted browser-control MCP) -- Local end-to-end test runner with screenshot capability +- 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 — MCP name, dev-server command, Storybook port. +**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 diff --git a/dev-skills/skills/external-resource-context/references/template.md b/dev-skills/skills/external-resource-context/references/template.md index 7ae0365..169f3b2 100644 --- a/dev-skills/skills/external-resource-context/references/template.md +++ b/dev-skills/skills/external-resource-context/references/template.md @@ -19,13 +19,13 @@ This file records the external resources available to this project and how to ac - Status: - Source type: - Location: -- Access method: +- Access method: ### Design System - Status: - Source type: - Location: -- Access method: +- Access method: ### Guidelines - Status: @@ -35,16 +35,16 @@ This file records the external resources available to this project and how to ac ### Visual Verification Environment - Status: -- Tool type: -- Entry: +- Tool type: +- Entry: ## Backend ### Database Schema Source - Status: -- Source type: +- Source type: - Location: -- Access method: +- Access method: ### Migration History - Status: @@ -55,7 +55,7 @@ This file records the external resources available to this project and how to ac ### Secret Store - Status: - Service: -- Access method: +- Access method: ### Background Job Infrastructure - Status: diff --git a/dev-workflows-frontend/skills/external-resource-context/references/frontend.md b/dev-workflows-frontend/skills/external-resource-context/references/frontend.md index c4189e7..89fdd16 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/frontend.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/frontend.md @@ -13,7 +13,7 @@ The canonical source of the visual specification. - Existing implementation only (no separate design source) - Not applicable -**Follow-up (when not N/A)**: How is the source accessed? Examples — MCP name, URL, file path, manual screenshot. Record the literal access mechanism. +**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 @@ -27,7 +27,7 @@ Reusable component library and design tokens. - No design system (ad-hoc components) - Not applicable -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — MCP name, Storybook URL, package name, internal documentation path. +**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 @@ -47,13 +47,13 @@ Usage guidance, accessibility rules, anti-patterns, naming conventions for UI wo How rendered output is confirmed during implementation. **AskUserQuestion choices**: -- Browser automation MCP (e.g., a hosted browser-control MCP) -- Local end-to-end test runner with screenshot capability +- 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 — MCP name, dev-server command, Storybook port. +**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 diff --git a/dev-workflows-frontend/skills/external-resource-context/references/template.md b/dev-workflows-frontend/skills/external-resource-context/references/template.md index 7ae0365..169f3b2 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/template.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/template.md @@ -19,13 +19,13 @@ This file records the external resources available to this project and how to ac - Status: - Source type: - Location: -- Access method: +- Access method: ### Design System - Status: - Source type: - Location: -- Access method: +- Access method: ### Guidelines - Status: @@ -35,16 +35,16 @@ This file records the external resources available to this project and how to ac ### Visual Verification Environment - Status: -- Tool type: -- Entry: +- Tool type: +- Entry: ## Backend ### Database Schema Source - Status: -- Source type: +- Source type: - Location: -- Access method: +- Access method: ### Migration History - Status: @@ -55,7 +55,7 @@ This file records the external resources available to this project and how to ac ### Secret Store - Status: - Service: -- Access method: +- Access method: ### Background Job Infrastructure - Status: diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index d709fd9..b096fa9 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -1,20 +1,24 @@ --- name: recipe-front-adjust -description: Adjust an already-implemented UI in-session with MCP-driven verification against the design source +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 → MCP-driven check → refine) runs in the parent session. +**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 MCP-driven verification loop myself; subagents handle one-shot tasks." +**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, MCP-driven verification, iteration until acceptance. +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 ``` @@ -30,7 +34,7 @@ Adjustment request → external resource hearing (parent session, AskUserQuestio ↓ ↓ (1-2 files: inline) (3-5 files: work-planner subagent → [Stop]) ↓ ↓ - └─→ adjustment + MCP verification (parent session) ←──┘ + └─→ adjustment + verification (parent session) ←──┘ ↓ quality-fixer-frontend (subagent: typecheck/lint/test) ↓ @@ -44,7 +48,7 @@ Adjustment request → external resource hearing (parent session, AskUserQuestio - 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 MCP-driven verification (run in this session) +- Adjustment edits and verification against the design source (run in this session) - Quality verification via quality-fixer-frontend - Commit per adjustment unit @@ -82,7 +86,7 @@ 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[] with `ui:` prefix preserved +- 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 @@ -99,19 +103,19 @@ 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 + MCP Verification (parent session) +### 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 the access methods from `docs/project-context/external-resources.md`: - - Design origin via the configured design-tool MCP (compare current rendering vs design source) - - Visual verification via the configured browser MCP (capture screenshot, check layout) - - Design system catalog via the configured design-system MCP (confirm component variants and tokens) -4. **Refine and re-verify** until the adjustment matches the design source. +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 MCP access is unavailable for the verification step, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). +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) @@ -140,7 +144,7 @@ Then loop back to Step 5 for the next unit (Branch B work plan phase, or next fi - [ ] 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 via MCP (or manual fallback when MCP absent) +- [ ] 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 diff --git a/dev-workflows/skills/external-resource-context/references/frontend.md b/dev-workflows/skills/external-resource-context/references/frontend.md index c4189e7..89fdd16 100644 --- a/dev-workflows/skills/external-resource-context/references/frontend.md +++ b/dev-workflows/skills/external-resource-context/references/frontend.md @@ -13,7 +13,7 @@ The canonical source of the visual specification. - Existing implementation only (no separate design source) - Not applicable -**Follow-up (when not N/A)**: How is the source accessed? Examples — MCP name, URL, file path, manual screenshot. Record the literal access mechanism. +**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 @@ -27,7 +27,7 @@ Reusable component library and design tokens. - No design system (ad-hoc components) - Not applicable -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — MCP name, Storybook URL, package name, internal documentation path. +**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 @@ -47,13 +47,13 @@ Usage guidance, accessibility rules, anti-patterns, naming conventions for UI wo How rendered output is confirmed during implementation. **AskUserQuestion choices**: -- Browser automation MCP (e.g., a hosted browser-control MCP) -- Local end-to-end test runner with screenshot capability +- 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 — MCP name, dev-server command, Storybook port. +**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 diff --git a/dev-workflows/skills/external-resource-context/references/template.md b/dev-workflows/skills/external-resource-context/references/template.md index 7ae0365..169f3b2 100644 --- a/dev-workflows/skills/external-resource-context/references/template.md +++ b/dev-workflows/skills/external-resource-context/references/template.md @@ -19,13 +19,13 @@ This file records the external resources available to this project and how to ac - Status: - Source type: - Location: -- Access method: +- Access method: ### Design System - Status: - Source type: - Location: -- Access method: +- Access method: ### Guidelines - Status: @@ -35,16 +35,16 @@ This file records the external resources available to this project and how to ac ### Visual Verification Environment - Status: -- Tool type: -- Entry: +- Tool type: +- Entry: ## Backend ### Database Schema Source - Status: -- Source type: +- Source type: - Location: -- Access method: +- Access method: ### Migration History - Status: @@ -55,7 +55,7 @@ This file records the external resources available to this project and how to ac ### Secret Store - Status: - Service: -- Access method: +- Access method: ### Background Job Infrastructure - Status: diff --git a/skills/external-resource-context/references/frontend.md b/skills/external-resource-context/references/frontend.md index c4189e7..89fdd16 100644 --- a/skills/external-resource-context/references/frontend.md +++ b/skills/external-resource-context/references/frontend.md @@ -13,7 +13,7 @@ The canonical source of the visual specification. - Existing implementation only (no separate design source) - Not applicable -**Follow-up (when not N/A)**: How is the source accessed? Examples — MCP name, URL, file path, manual screenshot. Record the literal access mechanism. +**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 @@ -27,7 +27,7 @@ Reusable component library and design tokens. - No design system (ad-hoc components) - Not applicable -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — MCP name, Storybook URL, package name, internal documentation path. +**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 @@ -47,13 +47,13 @@ Usage guidance, accessibility rules, anti-patterns, naming conventions for UI wo How rendered output is confirmed during implementation. **AskUserQuestion choices**: -- Browser automation MCP (e.g., a hosted browser-control MCP) -- Local end-to-end test runner with screenshot capability +- 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 — MCP name, dev-server command, Storybook port. +**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 diff --git a/skills/external-resource-context/references/template.md b/skills/external-resource-context/references/template.md index 7ae0365..169f3b2 100644 --- a/skills/external-resource-context/references/template.md +++ b/skills/external-resource-context/references/template.md @@ -19,13 +19,13 @@ This file records the external resources available to this project and how to ac - Status: - Source type: - Location: -- Access method: +- Access method: ### Design System - Status: - Source type: - Location: -- Access method: +- Access method: ### Guidelines - Status: @@ -35,16 +35,16 @@ This file records the external resources available to this project and how to ac ### Visual Verification Environment - Status: -- Tool type: -- Entry: +- Tool type: +- Entry: ## Backend ### Database Schema Source - Status: -- Source type: +- Source type: - Location: -- Access method: +- Access method: ### Migration History - Status: @@ -55,7 +55,7 @@ This file records the external resources available to this project and how to ac ### Secret Store - Status: - Service: -- Access method: +- Access method: ### Background Job Infrastructure - Status: diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index d709fd9..b096fa9 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -1,20 +1,24 @@ --- name: recipe-front-adjust -description: Adjust an already-implemented UI in-session with MCP-driven verification against the design source +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 → MCP-driven check → refine) runs in the parent session. +**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 MCP-driven verification loop myself; subagents handle one-shot tasks." +**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, MCP-driven verification, iteration until acceptance. +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 ``` @@ -30,7 +34,7 @@ Adjustment request → external resource hearing (parent session, AskUserQuestio ↓ ↓ (1-2 files: inline) (3-5 files: work-planner subagent → [Stop]) ↓ ↓ - └─→ adjustment + MCP verification (parent session) ←──┘ + └─→ adjustment + verification (parent session) ←──┘ ↓ quality-fixer-frontend (subagent: typecheck/lint/test) ↓ @@ -44,7 +48,7 @@ Adjustment request → external resource hearing (parent session, AskUserQuestio - 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 MCP-driven verification (run in this session) +- Adjustment edits and verification against the design source (run in this session) - Quality verification via quality-fixer-frontend - Commit per adjustment unit @@ -82,7 +86,7 @@ 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[] with `ui:` prefix preserved +- 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 @@ -99,19 +103,19 @@ 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 + MCP Verification (parent session) +### 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 the access methods from `docs/project-context/external-resources.md`: - - Design origin via the configured design-tool MCP (compare current rendering vs design source) - - Visual verification via the configured browser MCP (capture screenshot, check layout) - - Design system catalog via the configured design-system MCP (confirm component variants and tokens) -4. **Refine and re-verify** until the adjustment matches the design source. +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 MCP access is unavailable for the verification step, fall back to manual verification (ask the user to confirm the result, or use file-based comparison if a specification file is available). +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) @@ -140,7 +144,7 @@ Then loop back to Step 5 for the next unit (Branch B work plan phase, or next fi - [ ] 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 via MCP (or manual fallback when MCP absent) +- [ ] 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