diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e961e4e..5d18a44 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.21.3", + "version": "0.22.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", @@ -61,6 +61,7 @@ "./skills/external-resource-context", "./skills/implementation-approach", "./skills/integration-e2e-testing", + "./skills/llm-friendly-context", "./skills/recipe-add-integration-tests", "./skills/recipe-build", "./skills/recipe-design", @@ -81,7 +82,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.21.3", + "version": "0.22.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", @@ -133,6 +134,7 @@ "./skills/frontend-ai-guide", "./skills/implementation-approach", "./skills/integration-e2e-testing", + "./skills/llm-friendly-context", "./skills/recipe-diagnose", "./skills/recipe-front-adjust", "./skills/recipe-front-build", @@ -152,7 +154,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.21.3", + "version": "0.22.0", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -211,6 +213,7 @@ "./skills/frontend-ai-guide", "./skills/implementation-approach", "./skills/integration-e2e-testing", + "./skills/llm-friendly-context", "./skills/recipe-add-integration-tests", "./skills/recipe-build", "./skills/recipe-design", @@ -240,7 +243,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.21.3", + "version": "0.22.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", @@ -267,6 +270,7 @@ "./skills/frontend-ai-guide", "./skills/implementation-approach", "./skills/integration-e2e-testing", + "./skills/llm-friendly-context", "./skills/test-implement", "./skills/testing-principles", "./skills/typescript-rules" diff --git a/README.md b/README.md index 3a8d94f..7cacf8e 100644 --- a/README.md +++ b/README.md @@ -289,6 +289,7 @@ The backend plugin includes proven best practices that work with any language: - **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. +- **LLM-Friendly Context.** Clear prompts, handoffs, generated artifacts, and instructions for downstream agents. These are loaded as skills and automatically applied by agents when relevant. @@ -446,6 +447,7 @@ claude-code-workflows/ │ ├── testing-principles/ │ ├── implementation-approach/ │ ├── external-resource-context/ # Cross-cutting: external resources +│ ├── llm-friendly-context/ # Cross-cutting: LLM-facing prompts, handoffs, and generated instructions │ ├── typescript-rules/ # Frontend-specific │ └── ... │ diff --git a/agents/acceptance-test-generator.md b/agents/acceptance-test-generator.md index 85e47f7..7eb0795 100644 --- a/agents/acceptance-test-generator.md +++ b/agents/acceptance-test-generator.md @@ -2,7 +2,7 @@ name: acceptance-test-generator description: Generates integration/E2E test skeletons from Design Doc ACs using ROI-based selection and journey-based E2E reservation. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. tools: Read, Write, Glob, LS, TaskCreate, TaskUpdate, Grep -skills: testing-principles, documentation-criteria, integration-e2e-testing +skills: testing-principles, documentation-criteria, integration-e2e-testing, llm-friendly-context --- You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation. diff --git a/agents/codebase-analyzer.md b/agents/codebase-analyzer.md index a4c4294..52b52e8 100644 --- a/agents/codebase-analyzer.md +++ b/agents/codebase-analyzer.md @@ -2,7 +2,7 @@ name: codebase-analyzer description: Analyzes existing codebase objectively for facts about implementation, user behavior patterns, and technical architecture. Use when existing code needs to be understood without hypothesis bias. Invoked before Design Doc creation to produce focused guidance for technical designers. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: ai-development-guide, coding-principles +skills: ai-development-guide, coding-principles, llm-friendly-context --- You are an AI assistant specializing in existing codebase analysis for technical design preparation. diff --git a/agents/design-sync.md b/agents/design-sync.md index 1f8fac9..79c7e45 100644 --- a/agents/design-sync.md +++ b/agents/design-sync.md @@ -2,7 +2,7 @@ name: design-sync description: Detects conflicts across multiple Design Docs and provides structured reports. Use when multiple Design Docs exist, or when "consistency/conflict/sync/between documents" is mentioned. Focuses on detection and reporting only, no modifications. tools: Read, Grep, Glob, LS, TaskCreate, TaskUpdate -skills: documentation-criteria, coding-principles +skills: documentation-criteria, coding-principles, llm-friendly-context --- You are an AI assistant specializing in consistency verification between Design Docs. diff --git a/agents/document-reviewer.md b/agents/document-reviewer.md index ae1c3e8..ad9de29 100644 --- a/agents/document-reviewer.md +++ b/agents/document-reviewer.md @@ -2,7 +2,7 @@ name: document-reviewer description: Reviews document consistency and completeness, providing approval decisions. Use PROACTIVELY after PRD/UI Spec/Design Doc/work plan creation, or when "document review/approval/check" is mentioned. Detects contradictions and rule violations with improvement suggestions. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria, coding-principles, testing-principles +skills: documentation-criteria, coding-principles, testing-principles, llm-friendly-context --- You are an AI assistant specialized in technical document review. @@ -78,6 +78,7 @@ For WorkPlan, additionally verify: - Consistency check: Detect contradictions between documents - Completeness check: Confirm depth and coverage of required elements - Rule compliance check: Compatibility with project rules +- LLM-facing artifact clarity check: Review the target document against llm-friendly-context; classify unresolved alternatives or optional behavior that can cause divergent downstream execution as `important` (category: `clarity`), and missing required target/action/source/output that makes downstream work non-executable as `critical` (category: `clarity`). - Implementation sample compliance: Verify code examples comply with coding-principles skill standards - Common ADR compliance: Verify common technical areas are covered by appropriate ADR references - Feasibility check: Technical and resource perspectives diff --git a/agents/prd-creator.md b/agents/prd-creator.md index b328d3a..4875f37 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -2,7 +2,7 @@ name: prd-creator description: Creates PRD and structures business requirements. Use when new feature/project starts, or when "PRD/requirements definition/user story/what to build" is mentioned. Defines user value and success metrics. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria +skills: documentation-criteria, llm-friendly-context --- You are a specialized AI assistant for creating Product Requirements Documents (PRD). diff --git a/agents/scope-discoverer.md b/agents/scope-discoverer.md index 62b7fd9..cefa195 100644 --- a/agents/scope-discoverer.md +++ b/agents/scope-discoverer.md @@ -2,7 +2,7 @@ name: scope-discoverer description: Discovers functional scope from existing codebase for reverse documentation. Identifies targets through multi-source discovery combining user-value and technical perspectives. Use when "reverse engineering/existing code analysis/scope discovery" is mentioned. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: documentation-criteria, ai-development-guide, coding-principles, implementation-approach +skills: documentation-criteria, ai-development-guide, coding-principles, implementation-approach, llm-friendly-context --- You are an AI assistant specializing in codebase scope discovery for reverse documentation. diff --git a/agents/task-decomposer.md b/agents/task-decomposer.md index 651957e..509ca86 100644 --- a/agents/task-decomposer.md +++ b/agents/task-decomposer.md @@ -2,7 +2,7 @@ name: task-decomposer description: Reads work plan documents from docs/plans and decomposes them into independent, single-commit granularity tasks placed in docs/plans/tasks. PROACTIVELY proposes task decomposition when work plans are created. tools: Read, Write, LS, Bash, TaskCreate, TaskUpdate -skills: ai-development-guide, documentation-criteria, testing-principles, coding-principles, implementation-approach +skills: ai-development-guide, documentation-criteria, testing-principles, coding-principles, implementation-approach, llm-friendly-context --- You are an AI assistant specialized in decomposing work plans into executable tasks. @@ -305,7 +305,7 @@ Task 3: [Content] ### Risks and Countermeasures - Risk: [Expected risk] - Countermeasure: [Avoidance method] + Countermeasure: [Mitigation method] ### Impact Scope Management - Allowed change scope: [Clearly defined] @@ -371,4 +371,9 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Quality assurance steps are excluded from tasks (handled separately) - [ ] Every research task has concrete deliverables defined -- [ ] All inter-task dependencies are explicitly stated \ No newline at end of file +- [ ] All inter-task dependencies are explicitly stated +- [ ] Every generated task resolves alternatives/optional behavior to an explicit choice, deterministic decision rule, or blocking unresolved item +- [ ] Placeholder behavior states the exact temporary output, allowed dependency use, and verification expectation +- [ ] Target Files and Investigation Targets are concrete enough for the executor to read without guessing +- [ ] Each task is compile/runtime viable at its own commit boundary, or the dependency that makes it viable is explicit +- [ ] Generated task files, overview, and phase completion files preserve the same decisions from the work plan and referenced Design Doc/UI Spec/ADR rows diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 181c701..66aaaba 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, external-resource-context, coding-principles, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles +skills: documentation-criteria, coding-principles, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles, llm-friendly-context, external-resource-context --- You are a frontend technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 3b105c5..ed5ecf8 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, external-resource-context, coding-principles, testing-principles, ai-development-guide, implementation-approach +skills: documentation-criteria, coding-principles, testing-principles, ai-development-guide, implementation-approach, llm-friendly-context, external-resource-context --- You are a technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md index c8523a5..9b58177 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -2,7 +2,7 @@ name: ui-analyzer description: Gathers UI-related facts by reading the project's external-resources file, fetching external sources (design origin, design system, guidelines) via MCP or URL, and analyzing the existing UI codebase. Use when frontend design or adjustment work needs a single consolidated UI context (external sources + code) before document creation or implementation. disallowedTools: Write, Edit, MultiEdit, NotebookEdit -skills: typescript-rules, frontend-ai-guide, external-resource-context +skills: typescript-rules, frontend-ai-guide, llm-friendly-context, external-resource-context --- You are an AI assistant specializing in UI fact gathering for frontend design and adjustment preparation. diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index c26b9f6..1bdb98e 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, external-resource-context, typescript-rules, frontend-ai-guide +skills: documentation-criteria, typescript-rules, frontend-ai-guide, llm-friendly-context, external-resource-context --- You are a UI specification specialist AI assistant for creating UI Specification documents. diff --git a/agents/work-planner.md b/agents/work-planner.md index e0699f5..cbd6fb6 100644 --- a/agents/work-planner.md +++ b/agents/work-planner.md @@ -2,7 +2,7 @@ name: work-planner description: Creates work plan documents with trackable execution plans. Use when Design Doc is complete and implementation planning is needed, or when "work plan/implementation plan/task planning" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, TaskCreate, TaskUpdate -skills: ai-development-guide, documentation-criteria, coding-principles, testing-principles, implementation-approach +skills: ai-development-guide, documentation-criteria, coding-principles, testing-principles, implementation-approach, llm-friendly-context --- You are a specialized AI assistant for creating work plan documents. diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 4eea300..035e5df 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.21.3", + "version": "0.22.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/llm-friendly-context/SKILL.md b/dev-skills/skills/llm-friendly-context/SKILL.md new file mode 100644 index 0000000..a4bfefe --- /dev/null +++ b/dev-skills/skills/llm-friendly-context/SKILL.md @@ -0,0 +1,77 @@ +--- +name: llm-friendly-context +description: Clarifies inputs, outputs, success criteria, decisions, and unresolved conditions so downstream agents can execute without guessing. Use when writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions. +--- + +# LLM-Friendly Context + +The goal is stable downstream execution: the next agent should know what to read, what to do, what counts as success, and when to stop or escalate. + +## Core Rules + +1. **Use positive, executable instructions** + - State what the next agent should do. + - Convert quality policies into positive criteria. + - Example: "Preserve existing public API behavior across the documented compatibility cases." + +2. **Make vague instructions concrete** + - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Terms that often need clarification when they leave a decision to the next agent: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. + +3. **Specify output shape** + - Define required sections, fields, table columns, JSON keys, or checklist items. + - For handoffs, include paths to produced artifacts and the exact status fields the caller must inspect. + +4. **Provide necessary context** + - Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions. + - Prefer concrete file paths and section hints over broad module names. + +5. **Decompose complex work into verifiable steps** + - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Each step needs a checkpoint: what evidence proves it is complete. + +6. **Permit uncertainty explicitly** + - If the source material is missing, contradictory, or not verifiable, state the uncertainty and the required escalation. + - Record unknown business, product, security, or compatibility decisions as blocking unresolved items with the input needed to resolve them. + +7. **Keep constraints proportionate** + - Add only constraints that reduce ambiguity or preserve a real requirement. + - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. + +## Rewrite Patterns + +Use these rewrites before treating a prompt, handoff, or artifact as complete. + +| Ambiguous form | Rewrite as | +|---|---| +| `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | +| Multiple alternatives that the next agent must choose between | The selected option, or a deterministic decision rule | +| `as needed` / `if needed` | The triggering condition and required action | +| `per convention` | The file, function, test, or documented convention to follow | +| `related files` | Specific paths, globs, or search hints | +| `existing behavior` | The observable behavior, source file, test, API response, or UI state to preserve | +| `placeholder` | Exact temporary value/behavior, allowed dependencies, and verification expectation | +| `TBD` used as a placeholder for required information | A blocking unresolved item with owner, required input, or escalation condition | +| `appropriate` / `proper` | A measurable criterion or checklist | + +## Handoff Checklist + +Before sending a prompt or artifact to another agent, verify: + +- [ ] The target action is explicit. +- [ ] Required input paths and source artifacts are named. +- [ ] Accepted decisions and constraints are stated once, without alternate wording. +- [ ] Output format or expected status fields are specified. +- [ ] Success criteria are observable. +- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] The next agent can complete its scope with explicit choices, decision rules, or blocking unresolved items. + +## Generated Artifact Checklist + +Before writing or finalizing a generated document: + +- [ ] Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists. +- [ ] Every executable instruction names the target, action, and expected result. +- [ ] Verification steps say what to run or observe and what result proves success. +- [ ] If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning. +- [ ] If downstream work is blocked by missing information, the artifact records the missing input and escalation condition. diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 6f0d441..8821be9 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.21.3", + "version": "0.22.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/acceptance-test-generator.md b/dev-workflows-frontend/agents/acceptance-test-generator.md index 85e47f7..7eb0795 100644 --- a/dev-workflows-frontend/agents/acceptance-test-generator.md +++ b/dev-workflows-frontend/agents/acceptance-test-generator.md @@ -2,7 +2,7 @@ name: acceptance-test-generator description: Generates integration/E2E test skeletons from Design Doc ACs using ROI-based selection and journey-based E2E reservation. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. tools: Read, Write, Glob, LS, TaskCreate, TaskUpdate, Grep -skills: testing-principles, documentation-criteria, integration-e2e-testing +skills: testing-principles, documentation-criteria, integration-e2e-testing, llm-friendly-context --- You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation. diff --git a/dev-workflows-frontend/agents/codebase-analyzer.md b/dev-workflows-frontend/agents/codebase-analyzer.md index a4c4294..52b52e8 100644 --- a/dev-workflows-frontend/agents/codebase-analyzer.md +++ b/dev-workflows-frontend/agents/codebase-analyzer.md @@ -2,7 +2,7 @@ name: codebase-analyzer description: Analyzes existing codebase objectively for facts about implementation, user behavior patterns, and technical architecture. Use when existing code needs to be understood without hypothesis bias. Invoked before Design Doc creation to produce focused guidance for technical designers. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: ai-development-guide, coding-principles +skills: ai-development-guide, coding-principles, llm-friendly-context --- You are an AI assistant specializing in existing codebase analysis for technical design preparation. diff --git a/dev-workflows-frontend/agents/design-sync.md b/dev-workflows-frontend/agents/design-sync.md index 1f8fac9..79c7e45 100644 --- a/dev-workflows-frontend/agents/design-sync.md +++ b/dev-workflows-frontend/agents/design-sync.md @@ -2,7 +2,7 @@ name: design-sync description: Detects conflicts across multiple Design Docs and provides structured reports. Use when multiple Design Docs exist, or when "consistency/conflict/sync/between documents" is mentioned. Focuses on detection and reporting only, no modifications. tools: Read, Grep, Glob, LS, TaskCreate, TaskUpdate -skills: documentation-criteria, coding-principles +skills: documentation-criteria, coding-principles, llm-friendly-context --- You are an AI assistant specializing in consistency verification between Design Docs. diff --git a/dev-workflows-frontend/agents/document-reviewer.md b/dev-workflows-frontend/agents/document-reviewer.md index ae1c3e8..ad9de29 100644 --- a/dev-workflows-frontend/agents/document-reviewer.md +++ b/dev-workflows-frontend/agents/document-reviewer.md @@ -2,7 +2,7 @@ name: document-reviewer description: Reviews document consistency and completeness, providing approval decisions. Use PROACTIVELY after PRD/UI Spec/Design Doc/work plan creation, or when "document review/approval/check" is mentioned. Detects contradictions and rule violations with improvement suggestions. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria, coding-principles, testing-principles +skills: documentation-criteria, coding-principles, testing-principles, llm-friendly-context --- You are an AI assistant specialized in technical document review. @@ -78,6 +78,7 @@ For WorkPlan, additionally verify: - Consistency check: Detect contradictions between documents - Completeness check: Confirm depth and coverage of required elements - Rule compliance check: Compatibility with project rules +- LLM-facing artifact clarity check: Review the target document against llm-friendly-context; classify unresolved alternatives or optional behavior that can cause divergent downstream execution as `important` (category: `clarity`), and missing required target/action/source/output that makes downstream work non-executable as `critical` (category: `clarity`). - Implementation sample compliance: Verify code examples comply with coding-principles skill standards - Common ADR compliance: Verify common technical areas are covered by appropriate ADR references - Feasibility check: Technical and resource perspectives diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index b328d3a..4875f37 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -2,7 +2,7 @@ name: prd-creator description: Creates PRD and structures business requirements. Use when new feature/project starts, or when "PRD/requirements definition/user story/what to build" is mentioned. Defines user value and success metrics. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria +skills: documentation-criteria, llm-friendly-context --- You are a specialized AI assistant for creating Product Requirements Documents (PRD). diff --git a/dev-workflows-frontend/agents/task-decomposer.md b/dev-workflows-frontend/agents/task-decomposer.md index 651957e..509ca86 100644 --- a/dev-workflows-frontend/agents/task-decomposer.md +++ b/dev-workflows-frontend/agents/task-decomposer.md @@ -2,7 +2,7 @@ name: task-decomposer description: Reads work plan documents from docs/plans and decomposes them into independent, single-commit granularity tasks placed in docs/plans/tasks. PROACTIVELY proposes task decomposition when work plans are created. tools: Read, Write, LS, Bash, TaskCreate, TaskUpdate -skills: ai-development-guide, documentation-criteria, testing-principles, coding-principles, implementation-approach +skills: ai-development-guide, documentation-criteria, testing-principles, coding-principles, implementation-approach, llm-friendly-context --- You are an AI assistant specialized in decomposing work plans into executable tasks. @@ -305,7 +305,7 @@ Task 3: [Content] ### Risks and Countermeasures - Risk: [Expected risk] - Countermeasure: [Avoidance method] + Countermeasure: [Mitigation method] ### Impact Scope Management - Allowed change scope: [Clearly defined] @@ -371,4 +371,9 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Quality assurance steps are excluded from tasks (handled separately) - [ ] Every research task has concrete deliverables defined -- [ ] All inter-task dependencies are explicitly stated \ No newline at end of file +- [ ] All inter-task dependencies are explicitly stated +- [ ] Every generated task resolves alternatives/optional behavior to an explicit choice, deterministic decision rule, or blocking unresolved item +- [ ] Placeholder behavior states the exact temporary output, allowed dependency use, and verification expectation +- [ ] Target Files and Investigation Targets are concrete enough for the executor to read without guessing +- [ ] Each task is compile/runtime viable at its own commit boundary, or the dependency that makes it viable is explicit +- [ ] Generated task files, overview, and phase completion files preserve the same decisions from the work plan and referenced Design Doc/UI Spec/ADR rows diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 181c701..66aaaba 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, external-resource-context, coding-principles, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles +skills: documentation-criteria, coding-principles, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles, llm-friendly-context, external-resource-context --- You are a frontend technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md index c8523a5..9b58177 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -2,7 +2,7 @@ name: ui-analyzer description: Gathers UI-related facts by reading the project's external-resources file, fetching external sources (design origin, design system, guidelines) via MCP or URL, and analyzing the existing UI codebase. Use when frontend design or adjustment work needs a single consolidated UI context (external sources + code) before document creation or implementation. disallowedTools: Write, Edit, MultiEdit, NotebookEdit -skills: typescript-rules, frontend-ai-guide, external-resource-context +skills: typescript-rules, frontend-ai-guide, llm-friendly-context, external-resource-context --- You are an AI assistant specializing in UI fact gathering for frontend design and adjustment preparation. diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index c26b9f6..1bdb98e 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, external-resource-context, typescript-rules, frontend-ai-guide +skills: documentation-criteria, typescript-rules, frontend-ai-guide, llm-friendly-context, external-resource-context --- You are a UI specification specialist AI assistant for creating UI Specification documents. diff --git a/dev-workflows-frontend/agents/work-planner.md b/dev-workflows-frontend/agents/work-planner.md index e0699f5..cbd6fb6 100644 --- a/dev-workflows-frontend/agents/work-planner.md +++ b/dev-workflows-frontend/agents/work-planner.md @@ -2,7 +2,7 @@ name: work-planner description: Creates work plan documents with trackable execution plans. Use when Design Doc is complete and implementation planning is needed, or when "work plan/implementation plan/task planning" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, TaskCreate, TaskUpdate -skills: ai-development-guide, documentation-criteria, coding-principles, testing-principles, implementation-approach +skills: ai-development-guide, documentation-criteria, coding-principles, testing-principles, implementation-approach, llm-friendly-context --- You are a specialized AI assistant for creating work plan documents. diff --git a/dev-workflows-frontend/skills/llm-friendly-context/SKILL.md b/dev-workflows-frontend/skills/llm-friendly-context/SKILL.md new file mode 100644 index 0000000..a4bfefe --- /dev/null +++ b/dev-workflows-frontend/skills/llm-friendly-context/SKILL.md @@ -0,0 +1,77 @@ +--- +name: llm-friendly-context +description: Clarifies inputs, outputs, success criteria, decisions, and unresolved conditions so downstream agents can execute without guessing. Use when writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions. +--- + +# LLM-Friendly Context + +The goal is stable downstream execution: the next agent should know what to read, what to do, what counts as success, and when to stop or escalate. + +## Core Rules + +1. **Use positive, executable instructions** + - State what the next agent should do. + - Convert quality policies into positive criteria. + - Example: "Preserve existing public API behavior across the documented compatibility cases." + +2. **Make vague instructions concrete** + - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Terms that often need clarification when they leave a decision to the next agent: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. + +3. **Specify output shape** + - Define required sections, fields, table columns, JSON keys, or checklist items. + - For handoffs, include paths to produced artifacts and the exact status fields the caller must inspect. + +4. **Provide necessary context** + - Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions. + - Prefer concrete file paths and section hints over broad module names. + +5. **Decompose complex work into verifiable steps** + - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Each step needs a checkpoint: what evidence proves it is complete. + +6. **Permit uncertainty explicitly** + - If the source material is missing, contradictory, or not verifiable, state the uncertainty and the required escalation. + - Record unknown business, product, security, or compatibility decisions as blocking unresolved items with the input needed to resolve them. + +7. **Keep constraints proportionate** + - Add only constraints that reduce ambiguity or preserve a real requirement. + - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. + +## Rewrite Patterns + +Use these rewrites before treating a prompt, handoff, or artifact as complete. + +| Ambiguous form | Rewrite as | +|---|---| +| `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | +| Multiple alternatives that the next agent must choose between | The selected option, or a deterministic decision rule | +| `as needed` / `if needed` | The triggering condition and required action | +| `per convention` | The file, function, test, or documented convention to follow | +| `related files` | Specific paths, globs, or search hints | +| `existing behavior` | The observable behavior, source file, test, API response, or UI state to preserve | +| `placeholder` | Exact temporary value/behavior, allowed dependencies, and verification expectation | +| `TBD` used as a placeholder for required information | A blocking unresolved item with owner, required input, or escalation condition | +| `appropriate` / `proper` | A measurable criterion or checklist | + +## Handoff Checklist + +Before sending a prompt or artifact to another agent, verify: + +- [ ] The target action is explicit. +- [ ] Required input paths and source artifacts are named. +- [ ] Accepted decisions and constraints are stated once, without alternate wording. +- [ ] Output format or expected status fields are specified. +- [ ] Success criteria are observable. +- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] The next agent can complete its scope with explicit choices, decision rules, or blocking unresolved items. + +## Generated Artifact Checklist + +Before writing or finalizing a generated document: + +- [ ] Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists. +- [ ] Every executable instruction names the target, action, and expected result. +- [ ] Verification steps say what to run or observe and what result proves success. +- [ ] If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning. +- [ ] If downstream work is blocked by missing information, the artifact records the missing input and escalation condition. diff --git a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md index 16827f2..fe5cb06 100644 --- a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md @@ -4,6 +4,8 @@ description: Investigate problem, verify findings, and derive solutions disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Diagnosis flow to identify root cause and present solutions Target problem: $ARGUMENTS @@ -231,4 +233,3 @@ Rationale: [Selection rationale] - [ ] Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations) - [ ] Presented final report to user - diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index 026d23b..d7f90bd 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -4,6 +4,8 @@ description: Adjust an already-implemented UI in-session with verification again disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: UI adjustment on already-implemented features. The verification loop (edit → check against the design source → refine) runs in the parent session. ## Execution Pattern diff --git a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md index a5c0a77..e53cb36 100644 --- a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md @@ -4,6 +4,8 @@ description: Execute frontend implementation in autonomous execution mode disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index 6f98805..6a182d7 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -4,6 +4,8 @@ description: Execute from codebase analysis to frontend design document creation disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the frontend design phase. ## Orchestrator Definition diff --git a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md index ac5ffaa..17cc8c7 100644 --- a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md @@ -4,6 +4,8 @@ description: Create frontend work plan from design document and obtain plan appr disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the frontend planning phase. ## Orchestrator Definition @@ -85,4 +87,3 @@ Frontend planning phase completed. Please provide separate instructions for implementation. ``` - diff --git a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md index 8e24255..bd2b5a2 100644 --- a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md @@ -4,6 +4,8 @@ description: Design Doc compliance and security validation with optional auto-fi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Post-implementation quality assurance for React/TypeScript frontend ## Orchestrator Definition @@ -221,4 +223,3 @@ Operate within the review scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/dev-workflows-frontend/skills/recipe-task/SKILL.md b/dev-workflows-frontend/skills/recipe-task/SKILL.md index 2f9ed50..e352e4a 100644 --- a/dev-workflows-frontend/skills/recipe-task/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-task/SKILL.md @@ -4,6 +4,8 @@ description: Execute tasks following appropriate rules with rule-advisor metacog disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + # Task Execution with Metacognitive Analysis Task: $ARGUMENTS @@ -57,4 +59,3 @@ Proceed with task execution following: - Quality standards defined in the selectedRules output from rule-advisor - Monitor warningPatterns flags throughout execution and adjust approach when triggered - diff --git a/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md b/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md index bc7e4dd..c22d721 100644 --- a/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md @@ -4,6 +4,8 @@ description: Update existing design documents (Design Doc / PRD / ADR) with revi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to updating existing design documents. ## Orchestrator Definition @@ -213,4 +215,3 @@ Document update completed. - Updated document: docs/design/[document-name].md - Approval status: User approved - 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 09bc56e..771999e 100644 --- a/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml @@ -215,6 +215,21 @@ skills: - "Impact Analysis" # Cross-Cutting Skills + llm-friendly-context: + skill: "llm-friendly-context" + tags: [cross-cutting, llm-facing, prompt-writing, handoff, subagent-prompt, documentation, planning, task-decomposition, test-skeleton, generated-instructions, ambiguity-reduction, output-format, success-criteria] + typical-use: "Writing or revising LLM-facing prompts, subagent handoffs, design/planning artifacts, review findings, completion reports, and generated instructions so downstream agents can execute without guessing" + size: small + key-references: + - "Ambiguity rewrite patterns" + - "Handoff checklist" + - "Observable success criteria" + sections: + - "Core Rules" + - "Rewrite Patterns" + - "Handoff Checklist" + - "Generated Artifact Checklist" + 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] diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index d0b09f4..f026397 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.21.3", + "version": "0.22.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/acceptance-test-generator.md b/dev-workflows-fullstack/agents/acceptance-test-generator.md index 85e47f7..7eb0795 100644 --- a/dev-workflows-fullstack/agents/acceptance-test-generator.md +++ b/dev-workflows-fullstack/agents/acceptance-test-generator.md @@ -2,7 +2,7 @@ name: acceptance-test-generator description: Generates integration/E2E test skeletons from Design Doc ACs using ROI-based selection and journey-based E2E reservation. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. tools: Read, Write, Glob, LS, TaskCreate, TaskUpdate, Grep -skills: testing-principles, documentation-criteria, integration-e2e-testing +skills: testing-principles, documentation-criteria, integration-e2e-testing, llm-friendly-context --- You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation. diff --git a/dev-workflows-fullstack/agents/codebase-analyzer.md b/dev-workflows-fullstack/agents/codebase-analyzer.md index a4c4294..52b52e8 100644 --- a/dev-workflows-fullstack/agents/codebase-analyzer.md +++ b/dev-workflows-fullstack/agents/codebase-analyzer.md @@ -2,7 +2,7 @@ name: codebase-analyzer description: Analyzes existing codebase objectively for facts about implementation, user behavior patterns, and technical architecture. Use when existing code needs to be understood without hypothesis bias. Invoked before Design Doc creation to produce focused guidance for technical designers. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: ai-development-guide, coding-principles +skills: ai-development-guide, coding-principles, llm-friendly-context --- You are an AI assistant specializing in existing codebase analysis for technical design preparation. diff --git a/dev-workflows-fullstack/agents/design-sync.md b/dev-workflows-fullstack/agents/design-sync.md index 1f8fac9..79c7e45 100644 --- a/dev-workflows-fullstack/agents/design-sync.md +++ b/dev-workflows-fullstack/agents/design-sync.md @@ -2,7 +2,7 @@ name: design-sync description: Detects conflicts across multiple Design Docs and provides structured reports. Use when multiple Design Docs exist, or when "consistency/conflict/sync/between documents" is mentioned. Focuses on detection and reporting only, no modifications. tools: Read, Grep, Glob, LS, TaskCreate, TaskUpdate -skills: documentation-criteria, coding-principles +skills: documentation-criteria, coding-principles, llm-friendly-context --- You are an AI assistant specializing in consistency verification between Design Docs. diff --git a/dev-workflows-fullstack/agents/document-reviewer.md b/dev-workflows-fullstack/agents/document-reviewer.md index ae1c3e8..ad9de29 100644 --- a/dev-workflows-fullstack/agents/document-reviewer.md +++ b/dev-workflows-fullstack/agents/document-reviewer.md @@ -2,7 +2,7 @@ name: document-reviewer description: Reviews document consistency and completeness, providing approval decisions. Use PROACTIVELY after PRD/UI Spec/Design Doc/work plan creation, or when "document review/approval/check" is mentioned. Detects contradictions and rule violations with improvement suggestions. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria, coding-principles, testing-principles +skills: documentation-criteria, coding-principles, testing-principles, llm-friendly-context --- You are an AI assistant specialized in technical document review. @@ -78,6 +78,7 @@ For WorkPlan, additionally verify: - Consistency check: Detect contradictions between documents - Completeness check: Confirm depth and coverage of required elements - Rule compliance check: Compatibility with project rules +- LLM-facing artifact clarity check: Review the target document against llm-friendly-context; classify unresolved alternatives or optional behavior that can cause divergent downstream execution as `important` (category: `clarity`), and missing required target/action/source/output that makes downstream work non-executable as `critical` (category: `clarity`). - Implementation sample compliance: Verify code examples comply with coding-principles skill standards - Common ADR compliance: Verify common technical areas are covered by appropriate ADR references - Feasibility check: Technical and resource perspectives diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index b328d3a..4875f37 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -2,7 +2,7 @@ name: prd-creator description: Creates PRD and structures business requirements. Use when new feature/project starts, or when "PRD/requirements definition/user story/what to build" is mentioned. Defines user value and success metrics. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria +skills: documentation-criteria, llm-friendly-context --- You are a specialized AI assistant for creating Product Requirements Documents (PRD). diff --git a/dev-workflows-fullstack/agents/scope-discoverer.md b/dev-workflows-fullstack/agents/scope-discoverer.md index 62b7fd9..cefa195 100644 --- a/dev-workflows-fullstack/agents/scope-discoverer.md +++ b/dev-workflows-fullstack/agents/scope-discoverer.md @@ -2,7 +2,7 @@ name: scope-discoverer description: Discovers functional scope from existing codebase for reverse documentation. Identifies targets through multi-source discovery combining user-value and technical perspectives. Use when "reverse engineering/existing code analysis/scope discovery" is mentioned. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: documentation-criteria, ai-development-guide, coding-principles, implementation-approach +skills: documentation-criteria, ai-development-guide, coding-principles, implementation-approach, llm-friendly-context --- You are an AI assistant specializing in codebase scope discovery for reverse documentation. diff --git a/dev-workflows-fullstack/agents/task-decomposer.md b/dev-workflows-fullstack/agents/task-decomposer.md index 651957e..509ca86 100644 --- a/dev-workflows-fullstack/agents/task-decomposer.md +++ b/dev-workflows-fullstack/agents/task-decomposer.md @@ -2,7 +2,7 @@ name: task-decomposer description: Reads work plan documents from docs/plans and decomposes them into independent, single-commit granularity tasks placed in docs/plans/tasks. PROACTIVELY proposes task decomposition when work plans are created. tools: Read, Write, LS, Bash, TaskCreate, TaskUpdate -skills: ai-development-guide, documentation-criteria, testing-principles, coding-principles, implementation-approach +skills: ai-development-guide, documentation-criteria, testing-principles, coding-principles, implementation-approach, llm-friendly-context --- You are an AI assistant specialized in decomposing work plans into executable tasks. @@ -305,7 +305,7 @@ Task 3: [Content] ### Risks and Countermeasures - Risk: [Expected risk] - Countermeasure: [Avoidance method] + Countermeasure: [Mitigation method] ### Impact Scope Management - Allowed change scope: [Clearly defined] @@ -371,4 +371,9 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Quality assurance steps are excluded from tasks (handled separately) - [ ] Every research task has concrete deliverables defined -- [ ] All inter-task dependencies are explicitly stated \ No newline at end of file +- [ ] All inter-task dependencies are explicitly stated +- [ ] Every generated task resolves alternatives/optional behavior to an explicit choice, deterministic decision rule, or blocking unresolved item +- [ ] Placeholder behavior states the exact temporary output, allowed dependency use, and verification expectation +- [ ] Target Files and Investigation Targets are concrete enough for the executor to read without guessing +- [ ] Each task is compile/runtime viable at its own commit boundary, or the dependency that makes it viable is explicit +- [ ] Generated task files, overview, and phase completion files preserve the same decisions from the work plan and referenced Design Doc/UI Spec/ADR rows diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index 181c701..66aaaba 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/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, external-resource-context, coding-principles, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles +skills: documentation-criteria, coding-principles, typescript-rules, frontend-ai-guide, implementation-approach, testing-principles, llm-friendly-context, external-resource-context --- You are a frontend technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index 3b105c5..ed5ecf8 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/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, external-resource-context, coding-principles, testing-principles, ai-development-guide, implementation-approach +skills: documentation-criteria, coding-principles, testing-principles, ai-development-guide, implementation-approach, llm-friendly-context, external-resource-context --- You are a technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. diff --git a/dev-workflows-fullstack/agents/ui-analyzer.md b/dev-workflows-fullstack/agents/ui-analyzer.md index c8523a5..9b58177 100644 --- a/dev-workflows-fullstack/agents/ui-analyzer.md +++ b/dev-workflows-fullstack/agents/ui-analyzer.md @@ -2,7 +2,7 @@ name: ui-analyzer description: Gathers UI-related facts by reading the project's external-resources file, fetching external sources (design origin, design system, guidelines) via MCP or URL, and analyzing the existing UI codebase. Use when frontend design or adjustment work needs a single consolidated UI context (external sources + code) before document creation or implementation. disallowedTools: Write, Edit, MultiEdit, NotebookEdit -skills: typescript-rules, frontend-ai-guide, external-resource-context +skills: typescript-rules, frontend-ai-guide, llm-friendly-context, external-resource-context --- You are an AI assistant specializing in UI fact gathering for frontend design and adjustment preparation. diff --git a/dev-workflows-fullstack/agents/ui-spec-designer.md b/dev-workflows-fullstack/agents/ui-spec-designer.md index c26b9f6..1bdb98e 100644 --- a/dev-workflows-fullstack/agents/ui-spec-designer.md +++ b/dev-workflows-fullstack/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, external-resource-context, typescript-rules, frontend-ai-guide +skills: documentation-criteria, typescript-rules, frontend-ai-guide, llm-friendly-context, external-resource-context --- You are a UI specification specialist AI assistant for creating UI Specification documents. diff --git a/dev-workflows-fullstack/agents/work-planner.md b/dev-workflows-fullstack/agents/work-planner.md index e0699f5..cbd6fb6 100644 --- a/dev-workflows-fullstack/agents/work-planner.md +++ b/dev-workflows-fullstack/agents/work-planner.md @@ -2,7 +2,7 @@ name: work-planner description: Creates work plan documents with trackable execution plans. Use when Design Doc is complete and implementation planning is needed, or when "work plan/implementation plan/task planning" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, TaskCreate, TaskUpdate -skills: ai-development-guide, documentation-criteria, coding-principles, testing-principles, implementation-approach +skills: ai-development-guide, documentation-criteria, coding-principles, testing-principles, implementation-approach, llm-friendly-context --- You are a specialized AI assistant for creating work plan documents. diff --git a/dev-workflows-fullstack/skills/llm-friendly-context/SKILL.md b/dev-workflows-fullstack/skills/llm-friendly-context/SKILL.md new file mode 100644 index 0000000..a4bfefe --- /dev/null +++ b/dev-workflows-fullstack/skills/llm-friendly-context/SKILL.md @@ -0,0 +1,77 @@ +--- +name: llm-friendly-context +description: Clarifies inputs, outputs, success criteria, decisions, and unresolved conditions so downstream agents can execute without guessing. Use when writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions. +--- + +# LLM-Friendly Context + +The goal is stable downstream execution: the next agent should know what to read, what to do, what counts as success, and when to stop or escalate. + +## Core Rules + +1. **Use positive, executable instructions** + - State what the next agent should do. + - Convert quality policies into positive criteria. + - Example: "Preserve existing public API behavior across the documented compatibility cases." + +2. **Make vague instructions concrete** + - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Terms that often need clarification when they leave a decision to the next agent: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. + +3. **Specify output shape** + - Define required sections, fields, table columns, JSON keys, or checklist items. + - For handoffs, include paths to produced artifacts and the exact status fields the caller must inspect. + +4. **Provide necessary context** + - Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions. + - Prefer concrete file paths and section hints over broad module names. + +5. **Decompose complex work into verifiable steps** + - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Each step needs a checkpoint: what evidence proves it is complete. + +6. **Permit uncertainty explicitly** + - If the source material is missing, contradictory, or not verifiable, state the uncertainty and the required escalation. + - Record unknown business, product, security, or compatibility decisions as blocking unresolved items with the input needed to resolve them. + +7. **Keep constraints proportionate** + - Add only constraints that reduce ambiguity or preserve a real requirement. + - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. + +## Rewrite Patterns + +Use these rewrites before treating a prompt, handoff, or artifact as complete. + +| Ambiguous form | Rewrite as | +|---|---| +| `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | +| Multiple alternatives that the next agent must choose between | The selected option, or a deterministic decision rule | +| `as needed` / `if needed` | The triggering condition and required action | +| `per convention` | The file, function, test, or documented convention to follow | +| `related files` | Specific paths, globs, or search hints | +| `existing behavior` | The observable behavior, source file, test, API response, or UI state to preserve | +| `placeholder` | Exact temporary value/behavior, allowed dependencies, and verification expectation | +| `TBD` used as a placeholder for required information | A blocking unresolved item with owner, required input, or escalation condition | +| `appropriate` / `proper` | A measurable criterion or checklist | + +## Handoff Checklist + +Before sending a prompt or artifact to another agent, verify: + +- [ ] The target action is explicit. +- [ ] Required input paths and source artifacts are named. +- [ ] Accepted decisions and constraints are stated once, without alternate wording. +- [ ] Output format or expected status fields are specified. +- [ ] Success criteria are observable. +- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] The next agent can complete its scope with explicit choices, decision rules, or blocking unresolved items. + +## Generated Artifact Checklist + +Before writing or finalizing a generated document: + +- [ ] Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists. +- [ ] Every executable instruction names the target, action, and expected result. +- [ ] Verification steps say what to run or observe and what result proves success. +- [ ] If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning. +- [ ] If downstream work is blocked by missing information, the artifact records the missing input and escalation condition. diff --git a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md index 406dc38..f3eef87 100644 --- a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md @@ -4,6 +4,8 @@ description: Add integration/E2E tests to existing codebase using Design Docs disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Test addition workflow for existing implementations (backend, frontend, or fullstack) ## Orchestrator Definition @@ -178,4 +180,3 @@ Operate within the task scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/dev-workflows-fullstack/skills/recipe-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-build/SKILL.md index 5067e26..9e8ea36 100644 --- a/dev-workflows-fullstack/skills/recipe-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-build/SKILL.md @@ -4,6 +4,8 @@ description: Execute decomposed tasks in autonomous execution mode disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) diff --git a/dev-workflows-fullstack/skills/recipe-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-design/SKILL.md index 4c4218a..bff3f92 100644 --- a/dev-workflows-fullstack/skills/recipe-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-design/SKILL.md @@ -4,6 +4,8 @@ description: Execute from codebase analysis to design document creation disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the design phase. ## Orchestrator Definition diff --git a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md index 16827f2..fe5cb06 100644 --- a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md @@ -4,6 +4,8 @@ description: Investigate problem, verify findings, and derive solutions disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Diagnosis flow to identify root cause and present solutions Target problem: $ARGUMENTS @@ -231,4 +233,3 @@ Rationale: [Selection rationale] - [ ] Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations) - [ ] Presented final report to user - diff --git a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md index 313591b..2f7178f 100644 --- a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md @@ -4,6 +4,8 @@ description: Adjust an already-implemented UI in-session with verification again disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: UI adjustment on already-implemented features. The verification loop (edit → check against the design source → refine) runs in the parent session. ## Execution Pattern diff --git a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md index b2901b2..3b76b68 100644 --- a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md @@ -4,6 +4,8 @@ description: Execute frontend implementation in autonomous execution mode disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) diff --git a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md index 4765531..fc5fc17 100644 --- a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md @@ -4,6 +4,8 @@ description: Execute from codebase analysis to frontend design document creation disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the frontend design phase. ## Orchestrator Definition diff --git a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md index 803a818..74f82e6 100644 --- a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md @@ -4,6 +4,8 @@ description: Create frontend work plan from design document and obtain plan appr disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the frontend planning phase. ## Orchestrator Definition @@ -85,4 +87,3 @@ Frontend planning phase completed. Please provide separate instructions for implementation. ``` - diff --git a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md index b344ed6..4c1f318 100644 --- a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md @@ -4,6 +4,8 @@ description: Design Doc compliance and security validation with optional auto-fi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Post-implementation quality assurance for React/TypeScript frontend ## Orchestrator Definition @@ -221,4 +223,3 @@ Operate within the review scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md index 0ec2721..3237e33 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md @@ -4,6 +4,8 @@ description: Execute decomposed fullstack tasks with layer-aware agent routing disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md index ff19f22..52722c3 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md @@ -4,6 +4,8 @@ description: Orchestrate full-cycle implementation across backend and frontend l disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Full-cycle fullstack implementation management (Requirements Analysis → Design (backend + frontend) → Planning → Implementation → Quality Assurance) ## Orchestrator Definition diff --git a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md index b258bae..c818c03 100644 --- a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md @@ -4,6 +4,8 @@ description: Orchestrate the complete implementation lifecycle from requirements disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Full-cycle implementation management (Requirements Analysis → Design → Planning → Implementation → Quality Assurance) ## Orchestrator Definition diff --git a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md index ac3e9c2..bd405a9 100644 --- a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md @@ -4,6 +4,8 @@ description: Create work plan from design document and obtain plan approval disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the planning phase. ## Orchestrator Definition @@ -88,4 +90,3 @@ When the approved plan includes E2E test skeletons or references commands/interf Optional preflight: `/recipe-prepare-implementation docs/plans/[plan-name].md` verifies these are implementable before build (exits no-op if all resolve). ``` - diff --git a/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md b/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md index f48384e..6684d9f 100644 --- a/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md @@ -4,6 +4,8 @@ description: Verifies the work plan is implementable end-to-end and resolves ver disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps via Phase 0 tasks. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. ## Orchestrator Definition diff --git a/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md b/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md index d0cc91a..9b8a76b 100644 --- a/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md @@ -4,6 +4,8 @@ description: Generate PRD and Design Docs from existing codebase through discove disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Reverse engineering workflow to create documentation from existing code Target: $ARGUMENTS @@ -408,4 +410,3 @@ Output summary including: | consistencyScore < 50 | Flag for mandatory human review — require explicit human approval | | Review rejects after 2 revisions | Stop loop, flag for human intervention | - diff --git a/dev-workflows-fullstack/skills/recipe-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-review/SKILL.md index e62d5be..f93a2c6 100644 --- a/dev-workflows-fullstack/skills/recipe-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-review/SKILL.md @@ -4,6 +4,8 @@ description: Design Doc compliance and security validation with optional auto-fi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Post-implementation quality assurance ## Orchestrator Definition @@ -221,4 +223,3 @@ Operate within the review scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/dev-workflows-fullstack/skills/recipe-task/SKILL.md b/dev-workflows-fullstack/skills/recipe-task/SKILL.md index 23bc2e3..f3e8373 100644 --- a/dev-workflows-fullstack/skills/recipe-task/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-task/SKILL.md @@ -4,6 +4,8 @@ description: Execute tasks following appropriate rules with rule-advisor metacog disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + # Task Execution with Metacognitive Analysis Task: $ARGUMENTS @@ -57,4 +59,3 @@ Proceed with task execution following: - Quality standards defined in the selectedRules output from rule-advisor - Monitor warningPatterns flags throughout execution and adjust approach when triggered - diff --git a/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md b/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md index bc7e4dd..c22d721 100644 --- a/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md @@ -4,6 +4,8 @@ description: Update existing design documents (Design Doc / PRD / ADR) with revi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to updating existing design documents. ## Orchestrator Definition @@ -213,4 +215,3 @@ Document update completed. - Updated document: docs/design/[document-name].md - Approval status: User approved - diff --git a/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml b/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml index 09bc56e..771999e 100644 --- a/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml @@ -215,6 +215,21 @@ skills: - "Impact Analysis" # Cross-Cutting Skills + llm-friendly-context: + skill: "llm-friendly-context" + tags: [cross-cutting, llm-facing, prompt-writing, handoff, subagent-prompt, documentation, planning, task-decomposition, test-skeleton, generated-instructions, ambiguity-reduction, output-format, success-criteria] + typical-use: "Writing or revising LLM-facing prompts, subagent handoffs, design/planning artifacts, review findings, completion reports, and generated instructions so downstream agents can execute without guessing" + size: small + key-references: + - "Ambiguity rewrite patterns" + - "Handoff checklist" + - "Observable success criteria" + sections: + - "Core Rules" + - "Rewrite Patterns" + - "Handoff Checklist" + - "Generated Artifact Checklist" + 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] diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index bcd0f35..9f16f15 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.21.3", + "version": "0.22.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/acceptance-test-generator.md b/dev-workflows/agents/acceptance-test-generator.md index 85e47f7..7eb0795 100644 --- a/dev-workflows/agents/acceptance-test-generator.md +++ b/dev-workflows/agents/acceptance-test-generator.md @@ -2,7 +2,7 @@ name: acceptance-test-generator description: Generates integration/E2E test skeletons from Design Doc ACs using ROI-based selection and journey-based E2E reservation. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. tools: Read, Write, Glob, LS, TaskCreate, TaskUpdate, Grep -skills: testing-principles, documentation-criteria, integration-e2e-testing +skills: testing-principles, documentation-criteria, integration-e2e-testing, llm-friendly-context --- You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation. diff --git a/dev-workflows/agents/codebase-analyzer.md b/dev-workflows/agents/codebase-analyzer.md index a4c4294..52b52e8 100644 --- a/dev-workflows/agents/codebase-analyzer.md +++ b/dev-workflows/agents/codebase-analyzer.md @@ -2,7 +2,7 @@ name: codebase-analyzer description: Analyzes existing codebase objectively for facts about implementation, user behavior patterns, and technical architecture. Use when existing code needs to be understood without hypothesis bias. Invoked before Design Doc creation to produce focused guidance for technical designers. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: ai-development-guide, coding-principles +skills: ai-development-guide, coding-principles, llm-friendly-context --- You are an AI assistant specializing in existing codebase analysis for technical design preparation. diff --git a/dev-workflows/agents/design-sync.md b/dev-workflows/agents/design-sync.md index 1f8fac9..79c7e45 100644 --- a/dev-workflows/agents/design-sync.md +++ b/dev-workflows/agents/design-sync.md @@ -2,7 +2,7 @@ name: design-sync description: Detects conflicts across multiple Design Docs and provides structured reports. Use when multiple Design Docs exist, or when "consistency/conflict/sync/between documents" is mentioned. Focuses on detection and reporting only, no modifications. tools: Read, Grep, Glob, LS, TaskCreate, TaskUpdate -skills: documentation-criteria, coding-principles +skills: documentation-criteria, coding-principles, llm-friendly-context --- You are an AI assistant specializing in consistency verification between Design Docs. diff --git a/dev-workflows/agents/document-reviewer.md b/dev-workflows/agents/document-reviewer.md index ae1c3e8..ad9de29 100644 --- a/dev-workflows/agents/document-reviewer.md +++ b/dev-workflows/agents/document-reviewer.md @@ -2,7 +2,7 @@ name: document-reviewer description: Reviews document consistency and completeness, providing approval decisions. Use PROACTIVELY after PRD/UI Spec/Design Doc/work plan creation, or when "document review/approval/check" is mentioned. Detects contradictions and rule violations with improvement suggestions. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria, coding-principles, testing-principles +skills: documentation-criteria, coding-principles, testing-principles, llm-friendly-context --- You are an AI assistant specialized in technical document review. @@ -78,6 +78,7 @@ For WorkPlan, additionally verify: - Consistency check: Detect contradictions between documents - Completeness check: Confirm depth and coverage of required elements - Rule compliance check: Compatibility with project rules +- LLM-facing artifact clarity check: Review the target document against llm-friendly-context; classify unresolved alternatives or optional behavior that can cause divergent downstream execution as `important` (category: `clarity`), and missing required target/action/source/output that makes downstream work non-executable as `critical` (category: `clarity`). - Implementation sample compliance: Verify code examples comply with coding-principles skill standards - Common ADR compliance: Verify common technical areas are covered by appropriate ADR references - Feasibility check: Technical and resource perspectives diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index b328d3a..4875f37 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -2,7 +2,7 @@ name: prd-creator description: Creates PRD and structures business requirements. Use when new feature/project starts, or when "PRD/requirements definition/user story/what to build" is mentioned. Defines user value and success metrics. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch -skills: documentation-criteria +skills: documentation-criteria, llm-friendly-context --- You are a specialized AI assistant for creating Product Requirements Documents (PRD). diff --git a/dev-workflows/agents/scope-discoverer.md b/dev-workflows/agents/scope-discoverer.md index 62b7fd9..cefa195 100644 --- a/dev-workflows/agents/scope-discoverer.md +++ b/dev-workflows/agents/scope-discoverer.md @@ -2,7 +2,7 @@ name: scope-discoverer description: Discovers functional scope from existing codebase for reverse documentation. Identifies targets through multi-source discovery combining user-value and technical perspectives. Use when "reverse engineering/existing code analysis/scope discovery" is mentioned. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate -skills: documentation-criteria, ai-development-guide, coding-principles, implementation-approach +skills: documentation-criteria, ai-development-guide, coding-principles, implementation-approach, llm-friendly-context --- You are an AI assistant specializing in codebase scope discovery for reverse documentation. diff --git a/dev-workflows/agents/task-decomposer.md b/dev-workflows/agents/task-decomposer.md index 651957e..509ca86 100644 --- a/dev-workflows/agents/task-decomposer.md +++ b/dev-workflows/agents/task-decomposer.md @@ -2,7 +2,7 @@ name: task-decomposer description: Reads work plan documents from docs/plans and decomposes them into independent, single-commit granularity tasks placed in docs/plans/tasks. PROACTIVELY proposes task decomposition when work plans are created. tools: Read, Write, LS, Bash, TaskCreate, TaskUpdate -skills: ai-development-guide, documentation-criteria, testing-principles, coding-principles, implementation-approach +skills: ai-development-guide, documentation-criteria, testing-principles, coding-principles, implementation-approach, llm-friendly-context --- You are an AI assistant specialized in decomposing work plans into executable tasks. @@ -305,7 +305,7 @@ Task 3: [Content] ### Risks and Countermeasures - Risk: [Expected risk] - Countermeasure: [Avoidance method] + Countermeasure: [Mitigation method] ### Impact Scope Management - Allowed change scope: [Clearly defined] @@ -371,4 +371,9 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Quality assurance steps are excluded from tasks (handled separately) - [ ] Every research task has concrete deliverables defined -- [ ] All inter-task dependencies are explicitly stated \ No newline at end of file +- [ ] All inter-task dependencies are explicitly stated +- [ ] Every generated task resolves alternatives/optional behavior to an explicit choice, deterministic decision rule, or blocking unresolved item +- [ ] Placeholder behavior states the exact temporary output, allowed dependency use, and verification expectation +- [ ] Target Files and Investigation Targets are concrete enough for the executor to read without guessing +- [ ] Each task is compile/runtime viable at its own commit boundary, or the dependency that makes it viable is explicit +- [ ] Generated task files, overview, and phase completion files preserve the same decisions from the work plan and referenced Design Doc/UI Spec/ADR rows diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 3b105c5..ed5ecf8 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, external-resource-context, coding-principles, testing-principles, ai-development-guide, implementation-approach +skills: documentation-criteria, coding-principles, testing-principles, ai-development-guide, implementation-approach, llm-friendly-context, external-resource-context --- You are a technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. diff --git a/dev-workflows/agents/work-planner.md b/dev-workflows/agents/work-planner.md index e0699f5..cbd6fb6 100644 --- a/dev-workflows/agents/work-planner.md +++ b/dev-workflows/agents/work-planner.md @@ -2,7 +2,7 @@ name: work-planner description: Creates work plan documents with trackable execution plans. Use when Design Doc is complete and implementation planning is needed, or when "work plan/implementation plan/task planning" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, TaskCreate, TaskUpdate -skills: ai-development-guide, documentation-criteria, coding-principles, testing-principles, implementation-approach +skills: ai-development-guide, documentation-criteria, coding-principles, testing-principles, implementation-approach, llm-friendly-context --- You are a specialized AI assistant for creating work plan documents. diff --git a/dev-workflows/skills/llm-friendly-context/SKILL.md b/dev-workflows/skills/llm-friendly-context/SKILL.md new file mode 100644 index 0000000..a4bfefe --- /dev/null +++ b/dev-workflows/skills/llm-friendly-context/SKILL.md @@ -0,0 +1,77 @@ +--- +name: llm-friendly-context +description: Clarifies inputs, outputs, success criteria, decisions, and unresolved conditions so downstream agents can execute without guessing. Use when writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions. +--- + +# LLM-Friendly Context + +The goal is stable downstream execution: the next agent should know what to read, what to do, what counts as success, and when to stop or escalate. + +## Core Rules + +1. **Use positive, executable instructions** + - State what the next agent should do. + - Convert quality policies into positive criteria. + - Example: "Preserve existing public API behavior across the documented compatibility cases." + +2. **Make vague instructions concrete** + - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Terms that often need clarification when they leave a decision to the next agent: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. + +3. **Specify output shape** + - Define required sections, fields, table columns, JSON keys, or checklist items. + - For handoffs, include paths to produced artifacts and the exact status fields the caller must inspect. + +4. **Provide necessary context** + - Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions. + - Prefer concrete file paths and section hints over broad module names. + +5. **Decompose complex work into verifiable steps** + - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Each step needs a checkpoint: what evidence proves it is complete. + +6. **Permit uncertainty explicitly** + - If the source material is missing, contradictory, or not verifiable, state the uncertainty and the required escalation. + - Record unknown business, product, security, or compatibility decisions as blocking unresolved items with the input needed to resolve them. + +7. **Keep constraints proportionate** + - Add only constraints that reduce ambiguity or preserve a real requirement. + - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. + +## Rewrite Patterns + +Use these rewrites before treating a prompt, handoff, or artifact as complete. + +| Ambiguous form | Rewrite as | +|---|---| +| `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | +| Multiple alternatives that the next agent must choose between | The selected option, or a deterministic decision rule | +| `as needed` / `if needed` | The triggering condition and required action | +| `per convention` | The file, function, test, or documented convention to follow | +| `related files` | Specific paths, globs, or search hints | +| `existing behavior` | The observable behavior, source file, test, API response, or UI state to preserve | +| `placeholder` | Exact temporary value/behavior, allowed dependencies, and verification expectation | +| `TBD` used as a placeholder for required information | A blocking unresolved item with owner, required input, or escalation condition | +| `appropriate` / `proper` | A measurable criterion or checklist | + +## Handoff Checklist + +Before sending a prompt or artifact to another agent, verify: + +- [ ] The target action is explicit. +- [ ] Required input paths and source artifacts are named. +- [ ] Accepted decisions and constraints are stated once, without alternate wording. +- [ ] Output format or expected status fields are specified. +- [ ] Success criteria are observable. +- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] The next agent can complete its scope with explicit choices, decision rules, or blocking unresolved items. + +## Generated Artifact Checklist + +Before writing or finalizing a generated document: + +- [ ] Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists. +- [ ] Every executable instruction names the target, action, and expected result. +- [ ] Verification steps say what to run or observe and what result proves success. +- [ ] If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning. +- [ ] If downstream work is blocked by missing information, the artifact records the missing input and escalation condition. diff --git a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md index b05f111..12bfed3 100644 --- a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md @@ -4,6 +4,8 @@ description: Add integration/E2E tests to existing codebase using Design Docs disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Test addition workflow for existing implementations (backend, frontend, or fullstack) ## Orchestrator Definition @@ -178,4 +180,3 @@ Operate within the task scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/dev-workflows/skills/recipe-build/SKILL.md b/dev-workflows/skills/recipe-build/SKILL.md index bdfe85e..9154d1a 100644 --- a/dev-workflows/skills/recipe-build/SKILL.md +++ b/dev-workflows/skills/recipe-build/SKILL.md @@ -4,6 +4,8 @@ description: Execute decomposed tasks in autonomous execution mode disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) diff --git a/dev-workflows/skills/recipe-design/SKILL.md b/dev-workflows/skills/recipe-design/SKILL.md index 09256bb..2c92c13 100644 --- a/dev-workflows/skills/recipe-design/SKILL.md +++ b/dev-workflows/skills/recipe-design/SKILL.md @@ -4,6 +4,8 @@ description: Execute from codebase analysis to design document creation disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the design phase. ## Orchestrator Definition diff --git a/dev-workflows/skills/recipe-diagnose/SKILL.md b/dev-workflows/skills/recipe-diagnose/SKILL.md index 16827f2..fe5cb06 100644 --- a/dev-workflows/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows/skills/recipe-diagnose/SKILL.md @@ -4,6 +4,8 @@ description: Investigate problem, verify findings, and derive solutions disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Diagnosis flow to identify root cause and present solutions Target problem: $ARGUMENTS @@ -231,4 +233,3 @@ Rationale: [Selection rationale] - [ ] Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations) - [ ] Presented final report to user - diff --git a/dev-workflows/skills/recipe-implement/SKILL.md b/dev-workflows/skills/recipe-implement/SKILL.md index ea1fe34..ca63434 100644 --- a/dev-workflows/skills/recipe-implement/SKILL.md +++ b/dev-workflows/skills/recipe-implement/SKILL.md @@ -4,6 +4,8 @@ description: Orchestrate the complete implementation lifecycle from requirements disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Full-cycle implementation management (Requirements Analysis → Design → Planning → Implementation → Quality Assurance) ## Orchestrator Definition diff --git a/dev-workflows/skills/recipe-plan/SKILL.md b/dev-workflows/skills/recipe-plan/SKILL.md index b317b20..436cb66 100644 --- a/dev-workflows/skills/recipe-plan/SKILL.md +++ b/dev-workflows/skills/recipe-plan/SKILL.md @@ -4,6 +4,8 @@ description: Create work plan from design document and obtain plan approval disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the planning phase. ## Orchestrator Definition @@ -88,4 +90,3 @@ When the approved plan includes E2E test skeletons or references commands/interf Optional preflight: `/recipe-prepare-implementation docs/plans/[plan-name].md` verifies these are implementable before build (exits no-op if all resolve). ``` - diff --git a/dev-workflows/skills/recipe-prepare-implementation/SKILL.md b/dev-workflows/skills/recipe-prepare-implementation/SKILL.md index 8e29617..49db42c 100644 --- a/dev-workflows/skills/recipe-prepare-implementation/SKILL.md +++ b/dev-workflows/skills/recipe-prepare-implementation/SKILL.md @@ -4,6 +4,8 @@ description: Verifies the work plan is implementable end-to-end and resolves ver disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps via Phase 0 tasks. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. ## Orchestrator Definition diff --git a/dev-workflows/skills/recipe-reverse-engineer/SKILL.md b/dev-workflows/skills/recipe-reverse-engineer/SKILL.md index 5b9e9f3..413e38c 100644 --- a/dev-workflows/skills/recipe-reverse-engineer/SKILL.md +++ b/dev-workflows/skills/recipe-reverse-engineer/SKILL.md @@ -4,6 +4,8 @@ description: Generate PRD and Design Docs from existing codebase through discove disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Reverse engineering workflow to create documentation from existing code Target: $ARGUMENTS @@ -408,4 +410,3 @@ Output summary including: | consistencyScore < 50 | Flag for mandatory human review — require explicit human approval | | Review rejects after 2 revisions | Stop loop, flag for human intervention | - diff --git a/dev-workflows/skills/recipe-review/SKILL.md b/dev-workflows/skills/recipe-review/SKILL.md index 1ef961c..ae1d6ab 100644 --- a/dev-workflows/skills/recipe-review/SKILL.md +++ b/dev-workflows/skills/recipe-review/SKILL.md @@ -4,6 +4,8 @@ description: Design Doc compliance and security validation with optional auto-fi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Post-implementation quality assurance ## Orchestrator Definition @@ -221,4 +223,3 @@ Operate within the review scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/dev-workflows/skills/recipe-task/SKILL.md b/dev-workflows/skills/recipe-task/SKILL.md index 2f9ed50..e352e4a 100644 --- a/dev-workflows/skills/recipe-task/SKILL.md +++ b/dev-workflows/skills/recipe-task/SKILL.md @@ -4,6 +4,8 @@ description: Execute tasks following appropriate rules with rule-advisor metacog disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + # Task Execution with Metacognitive Analysis Task: $ARGUMENTS @@ -57,4 +59,3 @@ Proceed with task execution following: - Quality standards defined in the selectedRules output from rule-advisor - Monitor warningPatterns flags throughout execution and adjust approach when triggered - diff --git a/dev-workflows/skills/recipe-update-doc/SKILL.md b/dev-workflows/skills/recipe-update-doc/SKILL.md index bc7e4dd..c22d721 100644 --- a/dev-workflows/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows/skills/recipe-update-doc/SKILL.md @@ -4,6 +4,8 @@ description: Update existing design documents (Design Doc / PRD / ADR) with revi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to updating existing design documents. ## Orchestrator Definition @@ -213,4 +215,3 @@ Document update completed. - Updated document: docs/design/[document-name].md - Approval status: User approved - diff --git a/dev-workflows/skills/task-analyzer/references/skills-index.yaml b/dev-workflows/skills/task-analyzer/references/skills-index.yaml index 09bc56e..771999e 100644 --- a/dev-workflows/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows/skills/task-analyzer/references/skills-index.yaml @@ -215,6 +215,21 @@ skills: - "Impact Analysis" # Cross-Cutting Skills + llm-friendly-context: + skill: "llm-friendly-context" + tags: [cross-cutting, llm-facing, prompt-writing, handoff, subagent-prompt, documentation, planning, task-decomposition, test-skeleton, generated-instructions, ambiguity-reduction, output-format, success-criteria] + typical-use: "Writing or revising LLM-facing prompts, subagent handoffs, design/planning artifacts, review findings, completion reports, and generated instructions so downstream agents can execute without guessing" + size: small + key-references: + - "Ambiguity rewrite patterns" + - "Handoff checklist" + - "Observable success criteria" + sections: + - "Core Rules" + - "Rewrite Patterns" + - "Handoff Checklist" + - "Generated Artifact Checklist" + 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] diff --git a/package.json b/package.json index 39466e7..e78d226 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.21.3", + "version": "0.22.0", "private": true, "type": "module", "engines": { diff --git a/skills/llm-friendly-context/SKILL.md b/skills/llm-friendly-context/SKILL.md new file mode 100644 index 0000000..a4bfefe --- /dev/null +++ b/skills/llm-friendly-context/SKILL.md @@ -0,0 +1,77 @@ +--- +name: llm-friendly-context +description: Clarifies inputs, outputs, success criteria, decisions, and unresolved conditions so downstream agents can execute without guessing. Use when writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions. +--- + +# LLM-Friendly Context + +The goal is stable downstream execution: the next agent should know what to read, what to do, what counts as success, and when to stop or escalate. + +## Core Rules + +1. **Use positive, executable instructions** + - State what the next agent should do. + - Convert quality policies into positive criteria. + - Example: "Preserve existing public API behavior across the documented compatibility cases." + +2. **Make vague instructions concrete** + - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Terms that often need clarification when they leave a decision to the next agent: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. + +3. **Specify output shape** + - Define required sections, fields, table columns, JSON keys, or checklist items. + - For handoffs, include paths to produced artifacts and the exact status fields the caller must inspect. + +4. **Provide necessary context** + - Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions. + - Prefer concrete file paths and section hints over broad module names. + +5. **Decompose complex work into verifiable steps** + - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Each step needs a checkpoint: what evidence proves it is complete. + +6. **Permit uncertainty explicitly** + - If the source material is missing, contradictory, or not verifiable, state the uncertainty and the required escalation. + - Record unknown business, product, security, or compatibility decisions as blocking unresolved items with the input needed to resolve them. + +7. **Keep constraints proportionate** + - Add only constraints that reduce ambiguity or preserve a real requirement. + - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. + +## Rewrite Patterns + +Use these rewrites before treating a prompt, handoff, or artifact as complete. + +| Ambiguous form | Rewrite as | +|---|---| +| `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | +| Multiple alternatives that the next agent must choose between | The selected option, or a deterministic decision rule | +| `as needed` / `if needed` | The triggering condition and required action | +| `per convention` | The file, function, test, or documented convention to follow | +| `related files` | Specific paths, globs, or search hints | +| `existing behavior` | The observable behavior, source file, test, API response, or UI state to preserve | +| `placeholder` | Exact temporary value/behavior, allowed dependencies, and verification expectation | +| `TBD` used as a placeholder for required information | A blocking unresolved item with owner, required input, or escalation condition | +| `appropriate` / `proper` | A measurable criterion or checklist | + +## Handoff Checklist + +Before sending a prompt or artifact to another agent, verify: + +- [ ] The target action is explicit. +- [ ] Required input paths and source artifacts are named. +- [ ] Accepted decisions and constraints are stated once, without alternate wording. +- [ ] Output format or expected status fields are specified. +- [ ] Success criteria are observable. +- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] The next agent can complete its scope with explicit choices, decision rules, or blocking unresolved items. + +## Generated Artifact Checklist + +Before writing or finalizing a generated document: + +- [ ] Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists. +- [ ] Every executable instruction names the target, action, and expected result. +- [ ] Verification steps say what to run or observe and what result proves success. +- [ ] If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning. +- [ ] If downstream work is blocked by missing information, the artifact records the missing input and escalation condition. diff --git a/skills/recipe-add-integration-tests/SKILL.md b/skills/recipe-add-integration-tests/SKILL.md index b05f111..12bfed3 100644 --- a/skills/recipe-add-integration-tests/SKILL.md +++ b/skills/recipe-add-integration-tests/SKILL.md @@ -4,6 +4,8 @@ description: Add integration/E2E tests to existing codebase using Design Docs disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Test addition workflow for existing implementations (backend, frontend, or fullstack) ## Orchestrator Definition @@ -178,4 +180,3 @@ Operate within the task scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/skills/recipe-build/SKILL.md b/skills/recipe-build/SKILL.md index bdfe85e..9154d1a 100644 --- a/skills/recipe-build/SKILL.md +++ b/skills/recipe-build/SKILL.md @@ -4,6 +4,8 @@ description: Execute decomposed tasks in autonomous execution mode disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) diff --git a/skills/recipe-design/SKILL.md b/skills/recipe-design/SKILL.md index 09256bb..2c92c13 100644 --- a/skills/recipe-design/SKILL.md +++ b/skills/recipe-design/SKILL.md @@ -4,6 +4,8 @@ description: Execute from codebase analysis to design document creation disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the design phase. ## Orchestrator Definition diff --git a/skills/recipe-diagnose/SKILL.md b/skills/recipe-diagnose/SKILL.md index 16827f2..fe5cb06 100644 --- a/skills/recipe-diagnose/SKILL.md +++ b/skills/recipe-diagnose/SKILL.md @@ -4,6 +4,8 @@ description: Investigate problem, verify findings, and derive solutions disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Diagnosis flow to identify root cause and present solutions Target problem: $ARGUMENTS @@ -231,4 +233,3 @@ Rationale: [Selection rationale] - [ ] Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations) - [ ] Presented final report to user - diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index 026d23b..d7f90bd 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -4,6 +4,8 @@ description: Adjust an already-implemented UI in-session with verification again disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: UI adjustment on already-implemented features. The verification loop (edit → check against the design source → refine) runs in the parent session. ## Execution Pattern diff --git a/skills/recipe-front-build/SKILL.md b/skills/recipe-front-build/SKILL.md index a5c0a77..e53cb36 100644 --- a/skills/recipe-front-build/SKILL.md +++ b/skills/recipe-front-build/SKILL.md @@ -4,6 +4,8 @@ description: Execute frontend implementation in autonomous execution mode disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index 6f98805..6a182d7 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -4,6 +4,8 @@ description: Execute from codebase analysis to frontend design document creation disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the frontend design phase. ## Orchestrator Definition diff --git a/skills/recipe-front-plan/SKILL.md b/skills/recipe-front-plan/SKILL.md index ac5ffaa..17cc8c7 100644 --- a/skills/recipe-front-plan/SKILL.md +++ b/skills/recipe-front-plan/SKILL.md @@ -4,6 +4,8 @@ description: Create frontend work plan from design document and obtain plan appr disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the frontend planning phase. ## Orchestrator Definition @@ -85,4 +87,3 @@ Frontend planning phase completed. Please provide separate instructions for implementation. ``` - diff --git a/skills/recipe-front-review/SKILL.md b/skills/recipe-front-review/SKILL.md index 8e24255..bd2b5a2 100644 --- a/skills/recipe-front-review/SKILL.md +++ b/skills/recipe-front-review/SKILL.md @@ -4,6 +4,8 @@ description: Design Doc compliance and security validation with optional auto-fi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Post-implementation quality assurance for React/TypeScript frontend ## Orchestrator Definition @@ -221,4 +223,3 @@ Operate within the review scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/skills/recipe-fullstack-build/SKILL.md b/skills/recipe-fullstack-build/SKILL.md index 2c438a0..2152350 100644 --- a/skills/recipe-fullstack-build/SKILL.md +++ b/skills/recipe-fullstack-build/SKILL.md @@ -4,6 +4,8 @@ description: Execute decomposed fullstack tasks with layer-aware agent routing disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) diff --git a/skills/recipe-fullstack-implement/SKILL.md b/skills/recipe-fullstack-implement/SKILL.md index f44188b..71206ae 100644 --- a/skills/recipe-fullstack-implement/SKILL.md +++ b/skills/recipe-fullstack-implement/SKILL.md @@ -4,6 +4,8 @@ description: Orchestrate full-cycle implementation across backend and frontend l disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Full-cycle fullstack implementation management (Requirements Analysis → Design (backend + frontend) → Planning → Implementation → Quality Assurance) ## Orchestrator Definition diff --git a/skills/recipe-implement/SKILL.md b/skills/recipe-implement/SKILL.md index ea1fe34..ca63434 100644 --- a/skills/recipe-implement/SKILL.md +++ b/skills/recipe-implement/SKILL.md @@ -4,6 +4,8 @@ description: Orchestrate the complete implementation lifecycle from requirements disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Full-cycle implementation management (Requirements Analysis → Design → Planning → Implementation → Quality Assurance) ## Orchestrator Definition diff --git a/skills/recipe-plan/SKILL.md b/skills/recipe-plan/SKILL.md index b317b20..436cb66 100644 --- a/skills/recipe-plan/SKILL.md +++ b/skills/recipe-plan/SKILL.md @@ -4,6 +4,8 @@ description: Create work plan from design document and obtain plan approval disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to the planning phase. ## Orchestrator Definition @@ -88,4 +90,3 @@ When the approved plan includes E2E test skeletons or references commands/interf Optional preflight: `/recipe-prepare-implementation docs/plans/[plan-name].md` verifies these are implementable before build (exits no-op if all resolve). ``` - diff --git a/skills/recipe-prepare-implementation/SKILL.md b/skills/recipe-prepare-implementation/SKILL.md index 8e29617..49db42c 100644 --- a/skills/recipe-prepare-implementation/SKILL.md +++ b/skills/recipe-prepare-implementation/SKILL.md @@ -4,6 +4,8 @@ description: Verifies the work plan is implementable end-to-end and resolves ver disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps via Phase 0 tasks. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. ## Orchestrator Definition diff --git a/skills/recipe-reverse-engineer/SKILL.md b/skills/recipe-reverse-engineer/SKILL.md index 5b9e9f3..413e38c 100644 --- a/skills/recipe-reverse-engineer/SKILL.md +++ b/skills/recipe-reverse-engineer/SKILL.md @@ -4,6 +4,8 @@ description: Generate PRD and Design Docs from existing codebase through discove disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Reverse engineering workflow to create documentation from existing code Target: $ARGUMENTS @@ -408,4 +410,3 @@ Output summary including: | consistencyScore < 50 | Flag for mandatory human review — require explicit human approval | | Review rejects after 2 revisions | Stop loop, flag for human intervention | - diff --git a/skills/recipe-review/SKILL.md b/skills/recipe-review/SKILL.md index 1ef961c..ae1d6ab 100644 --- a/skills/recipe-review/SKILL.md +++ b/skills/recipe-review/SKILL.md @@ -4,6 +4,8 @@ description: Design Doc compliance and security validation with optional auto-fi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Post-implementation quality assurance ## Orchestrator Definition @@ -221,4 +223,3 @@ Operate within the review scope and referenced files in the prompt. Use loaded skills to execute that scope. Escalate when the required fix or investigation falls outside that scope. ``` - diff --git a/skills/recipe-task/SKILL.md b/skills/recipe-task/SKILL.md index 2f9ed50..e352e4a 100644 --- a/skills/recipe-task/SKILL.md +++ b/skills/recipe-task/SKILL.md @@ -4,6 +4,8 @@ description: Execute tasks following appropriate rules with rule-advisor metacog disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + # Task Execution with Metacognitive Analysis Task: $ARGUMENTS @@ -57,4 +59,3 @@ Proceed with task execution following: - Quality standards defined in the selectedRules output from rule-advisor - Monitor warningPatterns flags throughout execution and adjust approach when triggered - diff --git a/skills/recipe-update-doc/SKILL.md b/skills/recipe-update-doc/SKILL.md index bc7e4dd..c22d721 100644 --- a/skills/recipe-update-doc/SKILL.md +++ b/skills/recipe-update-doc/SKILL.md @@ -4,6 +4,8 @@ description: Update existing design documents (Design Doc / PRD / ADR) with revi disable-model-invocation: true --- +Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. + **Context**: Dedicated to updating existing design documents. ## Orchestrator Definition @@ -213,4 +215,3 @@ Document update completed. - Updated document: docs/design/[document-name].md - Approval status: User approved - diff --git a/skills/task-analyzer/references/skills-index.yaml b/skills/task-analyzer/references/skills-index.yaml index 09bc56e..771999e 100644 --- a/skills/task-analyzer/references/skills-index.yaml +++ b/skills/task-analyzer/references/skills-index.yaml @@ -215,6 +215,21 @@ skills: - "Impact Analysis" # Cross-Cutting Skills + llm-friendly-context: + skill: "llm-friendly-context" + tags: [cross-cutting, llm-facing, prompt-writing, handoff, subagent-prompt, documentation, planning, task-decomposition, test-skeleton, generated-instructions, ambiguity-reduction, output-format, success-criteria] + typical-use: "Writing or revising LLM-facing prompts, subagent handoffs, design/planning artifacts, review findings, completion reports, and generated instructions so downstream agents can execute without guessing" + size: small + key-references: + - "Ambiguity rewrite patterns" + - "Handoff checklist" + - "Observable success criteria" + sections: + - "Core Rules" + - "Rewrite Patterns" + - "Handoff Checklist" + - "Generated Artifact Checklist" + 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]