Add LLM-friendly context skill

.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"

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
 │   └── ...
 │

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.

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.

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.

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

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).

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.

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
+- [ ] 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

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.

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.

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.

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.

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.

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"

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.

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"