feat(skills): Add agentic-workflow-guide

docs/README.skills.md

@@ -22,4 +22,5 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
 
 | Name | Description | Bundled Assets |
 | ---- | ----------- | -------------- |
+| [agentic-workflow-guide](../skills/agentic-workflow-guide/SKILL.md) | Design, review, and improve agent workflows based on proven design principles (SSOT, SRP, Fail Fast, Iterative Refinement). Supports Prompt Chaining, Parallelization, Orchestrator-Workers, Evaluator-Optimizer patterns. Use when: (1) Designing new agent workflows, (2) Reviewing/improving existing workflows, (3) Planning multi-agent architectures, (4) Detecting anti-patterns, (5) Scaffolding workflow templates/directory structures, (6) Creating agent definitions, prompts, or copilot-instructions | `LICENSE.txt`<br />`references/anti-patterns.md`<br />`references/design-principles.md`<br />`references/review-checklist.md`<br />`references/workflow-patterns.md`<br />`scripts/scaffold_workflow.py` |
 | [webapp-testing](../skills/webapp-testing/SKILL.md) | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `test-helper.js` |

skills/agentic-workflow-guide/LICENSE.txt

@@ -0,0 +1,35 @@
+MIT License / MIT ライセンス
+
+Copyright (c) 2025 yamapan (aktsmm)
+https://github.com/aktsmm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+本ソフトウェアおよび関連ドキュメントファイル（以下「ソフトウェア」）のコピーを
+取得するすべての人に対し、無償で以下の許可を与えます：ソフトウェアを無制限に
+使用、コピー、変更、マージ、公開、配布、サブライセンス、販売/または販売する
+こと。ただし、以下の条件に従うものとします：
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+上記の著作権表示および本許諾表示を、ソフトウェアのすべてのコピーまたは
+重要な部分に含めること。
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+本ソフトウェアは「現状有姿」で提供され、商品性、特定目的への適合性、
+権利非侵害を含むがこれに限らない明示的または黙示的な保証は一切ありません。
+作者または著作権者は、契約行為、不法行為、またはその他に起因する
+いかなる請求、損害、その他の責任についても責任を負いません。

skills/agentic-workflow-guide/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: agentic-workflow-guide
+description: "Design, review, and improve agent workflows based on proven design principles (SSOT, SRP, Fail Fast, Iterative Refinement). Supports Prompt Chaining, Parallelization, Orchestrator-Workers, Evaluator-Optimizer patterns. Use when: (1) Designing new agent workflows, (2) Reviewing/improving existing workflows, (3) Planning multi-agent architectures, (4) Detecting anti-patterns, (5) Scaffolding workflow templates/directory structures, (6) Creating agent definitions, prompts, or copilot-instructions"
+---
+
+# Agentic Workflow Guide
+
+A comprehensive guide for designing, reviewing, and improving agent workflows based on proven design principles.
+
+## When to Use
+
+- **New Workflow Design** - Define agent roles, responsibilities, and execution order
+- **Workflow Review** - Detect issues by checking against design principles
+- **Pattern Selection** - Choose the right workflow pattern for your task
+- **Quality Improvement** - Iteratively refine workflows step by step
+- **Scaffolding** - Generate workflow directory structures and templates
+
+## Core Principles
+
+→ See **[references/design-principles.md](references/design-principles.md)** for details
+
+### Tier 1: Essential Principles
+
+| Principle                | Description                      | Check Point                                      |
+| ------------------------ | -------------------------------- | ------------------------------------------------ |
+| **SSOT**                 | Single source of truth           | Is the same info defined in multiple places?     |
+| **SRP**                  | 1 agent = 1 responsibility       | Does one agent handle multiple responsibilities? |
+| **Simplicity First**     | Start with the simplest solution | Is the design overly complex?                    |
+| **Fail Fast**            | Detect and fix errors early      | Can errors be detected and stopped immediately?  |
+| **Iterative Refinement** | Build small, improve repeatedly  | Is it broken into small steps?                   |
+| **Feedback Loop**        | Verify results at each step      | Can results be verified at each step?            |
+
+### Tier 2: Quality Principles
+
+| Principle           | Description                        | Check Point                           |
+| ------------------- | ---------------------------------- | ------------------------------------- |
+| **Transparency**    | Show plans and progress explicitly | Is progress visible?                  |
+| **Gate/Checkpoint** | Validate at each step              | Is validation done before proceeding? |
+| **DRY**             | Don't repeat yourself              | Are common processes reused?          |
+| **ISP**             | Minimal context only               | Is unnecessary info being passed?     |
+| **Idempotency**     | Safe to retry                      | Is it safe to retry operations?       |
+
+## Workflow Patterns
+
+→ See **[references/workflow-patterns.md](references/workflow-patterns.md)** for details
+
+### Pattern Selection Guide
+
+```
+What's the nature of the task?
+├─ Sequential processing needed ──→ Prompt Chaining
+├─ Multiple independent tasks ────→ Parallelization
+├─ Dynamic task decomposition ────→ Orchestrator-Workers
+├─ Until quality criteria met ────→ Evaluator-Optimizer
+└─ Processing varies by input ────→ Routing
+```
+
+### Pattern Overview
+
+| Pattern                  | Use Case                           | Iterative Level |
+| ------------------------ | ---------------------------------- | --------------- |
+| **Prompt Chaining**      | Sequential with validation         | ⭐⭐⭐          |
+| **Routing**              | Classify → route to specialists    | ⭐⭐            |
+| **Parallelization**      | Execute independent tasks together | ⭐⭐            |
+| **Orchestrator-Workers** | Dynamic decomposition → workers    | ⭐⭐⭐          |
+| **Evaluator-Optimizer**  | Generate → evaluate → improve loop | ⭐⭐⭐⭐⭐      |
+
+## Design Workflow
+
+### Step 1: Requirements Gathering
+
+```markdown
+## Workflow Design Interview
+
+1. **Goal**: What do you want to achieve?
+2. **Task Decomposition**: What subtasks can this be broken into?
+3. **Dependencies**: Are there ordering dependencies between tasks?
+4. **Parallelism**: Which tasks can run independently?
+5. **Quality Criteria**: What defines success/failure?
+6. **Error Handling**: How should failures be handled?
+```
+
+### Step 2: Pattern Selection
+
+Choose the optimal pattern based on requirements:
+
+| Condition                         | Recommended Pattern  |
+| --------------------------------- | -------------------- |
+| Tasks have clear ordering         | Prompt Chaining      |
+| Tasks are independent             | Parallelization      |
+| Number of tasks is dynamic        | Orchestrator-Workers |
+| Repeat until quality criteria met | Evaluator-Optimizer  |
+| Processing varies by input type   | Routing              |
+
+### Step 3: Create Design Diagram
+
+Visualize with Mermaid:
+
+```mermaid
+graph TD
+    A[Start] --> B{Task Classification}
+    B -->|Type A| C[Agent 1]
+    B -->|Type B| D[Agent 2]
+    C --> E[Reviewer]
+    D --> E
+    E -->|OK| F[End]
+    E -->|NG| G[Feedback]
+    G --> C
+    G --> D
+```
+
+### Step 4: Principle Check
+
+Validate design against principles (use review checklist)
+
+### Step 5: Implement & Iterate
+
+Build small → verify → get feedback → improve
+
+## Review Checklist
+
+→ See **[references/review-checklist.md](references/review-checklist.md)** for details
+
+### Quick Check
+
+```markdown
+## Workflow Review Checklist
+
+### Core Principles
+
+- [ ] **SSOT**: Is the same info defined in multiple places?
+- [ ] **SRP**: Is each agent focused on a single responsibility?
+- [ ] **Simplicity**: Is this the simplest possible solution?
+- [ ] **Fail Fast**: Can errors be detected and stopped immediately?
+- [ ] **Iterative**: Is it broken into small steps?
+- [ ] **Feedback Loop**: Can results be verified at each step?
+
+### Quality Principles
+
+- [ ] **Transparency**: Are plans and progress visible?
+- [ ] **Gate/Checkpoint**: Is validation done at each step?
+- [ ] **DRY**: Are common processes reused?
+- [ ] **ISP**: Is only necessary info being passed?
+- [ ] **Idempotency**: Is it safe to retry?
+
+### Anti-Pattern Detection
+
+- [ ] Is too much responsibility packed into one agent?
+- [ ] Is excessive context being passed?
+- [ ] Is error handling missing?
+- [ ] Is there potential for infinite loops?
+- [ ] Are there points where human-in-the-loop is needed?
+```
+
+## Anti-Patterns
+
+→ See **[references/anti-patterns.md](references/anti-patterns.md)** for details
+
+| Anti-Pattern         | Problem                         | Solution                        |
+| -------------------- | ------------------------------- | ------------------------------- |
+| **God Agent**        | All responsibilities in 1 agent | Split with SRP                  |
+| **Context Overload** | Passing excessive info          | Minimize with ISP               |
+| **Silent Failure**   | Ignoring errors and continuing  | Stop immediately with Fail Fast |
+| **Infinite Loop**    | No termination condition        | Set max iterations              |
+| **Big Bang**         | Building everything at once     | Build small with Iterative      |
+
+## Scaffold Workflow
+
+Automatically generate workflow directory structures.
+
+### Usage
+
+```bash
+# Basic workflow
+python scripts/scaffold_workflow.py my-workflow
+
+# Specify pattern
+python scripts/scaffold_workflow.py code-review --pattern evaluator-optimizer
+
+# Specify output path
+python scripts/scaffold_workflow.py data-pipeline --pattern orchestrator-workers --path ./projects
+
+# List available patterns
+python scripts/scaffold_workflow.py --list-patterns
+```
+
+### Available Patterns
+
+| Pattern                | Description                    |
+| ---------------------- | ------------------------------ |
+| `basic`                | Basic workflow structure       |
+| `prompt-chaining`      | Sequential processing pattern  |
+| `parallelization`      | Parallel processing pattern    |
+| `orchestrator-workers` | Orchestrator + workers pattern |
+| `evaluator-optimizer`  | Evaluation-improvement loop    |
+| `routing`              | Routing pattern                |
+
+### Generated Structure
+
+```
+my-workflow/
+├── Agent.md                    # Workflow overview & agent list
+├── README.md                   # Usage guide
+├── .github/
+│   ├── copilot-instructions.md # GitHub Copilot instructions
+│   └── instructions/           # File-pattern-specific rules
+│       ├── workflow.instructions.md
+│       ├── agents.instructions.md
+│       └── prompts.instructions.md
+├── agents/                     # Agent definitions
+├── prompts/                    # Prompt templates
+│   ├── system_prompt.md
+│   ├── task_prompt.md
+│   └── error_handling_prompt.md
+├── docs/                       # Design documentation
+│   ├── design.md
+│   └── review_notes.md
+└── config/                     # Configuration files
+```
+
+## Resources
+
+| File                                                    | Content                       |
+| ------------------------------------------------------- | ----------------------------- |
+| [design-principles.md](references/design-principles.md) | Detailed design principles    |
+| [workflow-patterns.md](references/workflow-patterns.md) | Workflow pattern details      |
+| [review-checklist.md](references/review-checklist.md)   | Review checklist              |
+| [anti-patterns.md](references/anti-patterns.md)         | Anti-pattern collection       |
+| [scaffold_workflow.py](scripts/scaffold_workflow.py)    | Directory structure generator |
+
+## References
+
+- [Building Effective Agents - Anthropic](https://www.anthropic.com/engineering/building-effective-agents)
+- [Workflows and Agents - LangChain](https://docs.langchain.com/oss/python/langgraph/workflows-agents)
+- [subagent-driven-development - obra/superpowers](https://github.com/obra/superpowers/tree/main/skills/subagent-driven-development)
+- [dispatching-parallel-agents - obra/superpowers](https://github.com/obra/superpowers/tree/main/skills/dispatching-parallel-agents)