diff --git a/docs/README.skills.md b/docs/README.skills.md index 8c2876521..3a90f4dfc 100644 --- a/docs/README.skills.md +++ b/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`
`references/anti-patterns.md`
`references/design-principles.md`
`references/review-checklist.md`
`references/workflow-patterns.md`
`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` | diff --git a/skills/agentic-workflow-guide/LICENSE.txt b/skills/agentic-workflow-guide/LICENSE.txt new file mode 100644 index 000000000..f1ca42681 --- /dev/null +++ b/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. + +本ソフトウェアは「現状有姿」で提供され、商品性、特定目的への適合性、 +権利非侵害を含むがこれに限らない明示的または黙示的な保証は一切ありません。 +作者または著作権者は、契約行為、不法行為、またはその他に起因する +いかなる請求、損害、その他の責任についても責任を負いません。 diff --git a/skills/agentic-workflow-guide/SKILL.md b/skills/agentic-workflow-guide/SKILL.md new file mode 100644 index 000000000..559533a1b --- /dev/null +++ b/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) diff --git a/skills/agentic-workflow-guide/references/anti-patterns.md b/skills/agentic-workflow-guide/references/anti-patterns.md new file mode 100644 index 000000000..5befd23cd --- /dev/null +++ b/skills/agentic-workflow-guide/references/anti-patterns.md @@ -0,0 +1,301 @@ +# Anti-Patterns + +A collection of anti-patterns to avoid in agent workflows. + +## Overview + +| Anti-Pattern | Problem | Solution | +| -------------------- | ---------------------------------- | ------------------------------- | +| God Agent | All responsibilities in 1 agent | Split with SRP | +| Context Overload | Passing excessive unnecessary info | Minimize with ISP | +| Silent Failure | Ignoring errors and continuing | Stop immediately with Fail Fast | +| Infinite Loop | Loops without termination | Set maximum iterations | +| Big Bang | Building everything at once | Build small with Iterative | +| Premature Complexity | Complex design from the start | Simplicity First | +| Black Box | Internal state invisible | Transparency | +| Tight Coupling | Tight coupling between agents | Loose Coupling | + +--- + +## Details + +### 1. God Agent + +**Packing all responsibilities into one agent** + +#### Symptoms + +``` +❌ Bad Example: +Agent: "Search, analyze, create report, send email..." +``` + +- One agent handles multiple different tasks +- Prompt becomes bloated +- Debugging is difficult +- Partial changes affect the whole system + +#### Solution + +``` +✅ Good Example: +Agent 1 (Searcher): "Search for relevant information" +Agent 2 (Analyzer): "Analyze information" +Agent 3 (Reporter): "Create report" +Agent 4 (Sender): "Send email" +``` + +**Applicable Principle:** SRP (Single Responsibility Principle) + +--- + +### 2. Context Overload + +**Passing excessive unnecessary information** + +#### Symptoms + +``` +❌ Bad Example: +Context passed to Agent: +- All file contents +- Entire conversation history +- Unrelated configuration info +``` + +- Wasting context window +- Noise buries the essence +- Increased cost +- Increased processing time + +#### Solution + +``` +✅ Good Example: +Context passed to Agent: +- Only files needed for this task +- Only recent relevant conversation +- Only necessary configuration items +``` + +**Applicable Principle:** ISP (Interface Segregation Principle) + +--- + +### 3. Silent Failure + +**Ignoring errors and continuing** + +#### Symptoms + +``` +❌ Bad Example: +try: + result = agent.execute() +except: + pass # Ignore error +``` + +- Processing continues even when errors occur +- Problems propagate to later stages +- Debugging is difficult +- Invalid results are generated + +#### Solution + +``` +✅ Good Example: +try: + result = agent.execute() +except AgentError as e: + log.error(f"Agent failed: {e}") + raise # Stop immediately +``` + +**Applicable Principle:** Fail Fast + +--- + +### 4. Infinite Loop + +**Loops without termination conditions** + +#### Symptoms + +``` +❌ Bad Example: +while not evaluator.is_satisfied(): + result = generator.generate() + # No termination condition +``` + +- May never end +- Resource exhaustion +- Cost explosion + +#### Solution + +``` +✅ Good Example: +MAX_ITERATIONS = 5 +for i in range(MAX_ITERATIONS): + result = generator.generate() + if evaluator.is_satisfied(): + break +else: + log.warning("Max iterations reached") +``` + +**Applicable Principle:** Explicit termination conditions + +--- + +### 5. Big Bang + +**Building everything at once** + +#### Symptoms + +``` +❌ Bad Example: +1. Complete design for all features +2. Implement all agents at once +3. Test everything at the end +→ Late problem discovery, high fix costs +``` + +- Implementing everything at once +- Testing is deferred +- Late problem discovery +- Wide scope of fixes + +#### Solution + +``` +✅ Good Example: +1. Design minimum functionality +2. Implement 1 agent +3. Test and verify +4. Add next agent +5. Repeat +``` + +**Applicable Principle:** Iterative Refinement + +--- + +### 6. Premature Complexity + +**Complex design from the start** + +#### Symptoms + +``` +❌ Bad Example: +From the start: +- 10-agent complex workflow +- Complex conditional branching +- Advanced error handling +→ Turned out not to be needed +``` + +- YAGNI (You Aren't Gonna Need It) violation +- Increased maintenance cost +- Hard to understand + +#### Solution + +``` +✅ Good Example: +1. First try with a single agent +2. Consider splitting if problems occur +3. Add complexity as needed +``` + +**Applicable Principle:** Simplicity First, YAGNI + +**Anthropic's Recommendation:** + +> "Start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short." + +--- + +### 7. Black Box + +**Internal state invisible** + +#### Symptoms + +``` +❌ Bad Example: +Agent: (Processing without any output...) +User: "What are you doing?" +``` + +- Progress unknown +- Difficult to identify causes when problems occur +- User feels anxious + +#### Solution + +``` +✅ Good Example: +Agent: "Step 1/3: Fetching data..." +Agent: "Step 2/3: Analyzing..." +Agent: "Step 3/3: Generating report..." +``` + +**Applicable Principle:** Transparency + +--- + +### 8. Tight Coupling + +**Tight coupling between agents** + +#### Symptoms + +``` +❌ Bad Example: +Change Agent A's output format +→ Agents B, C, D all require changes +``` + +- Wide impact of changes +- Testing is difficult +- Hard to reuse + +#### Solution + +``` +✅ Good Example: +- Standardized interfaces +- Each agent can be tested independently +- Changes are localized +``` + +**Applicable Principle:** Loose Coupling + +--- + +## Checklist + +Verify with this list when designing workflows: + +```markdown +- [ ] God Agent: Is too much responsibility packed into one agent? +- [ ] Context Overload: Is excessive context being passed? +- [ ] Silent Failure: Are errors being ignored and continuing? +- [ ] Infinite Loop: Are there loops without termination conditions? +- [ ] Big Bang: Trying to build everything at once? +- [ ] Premature Complexity: Making it more complex than necessary? +- [ ] Black Box: Is internal state invisible? +- [ ] Tight Coupling: Are agents tightly coupled? +``` + +--- + +## Related Documents + +- [design-principles.md](design-principles.md) - Design principles details +- [review-checklist.md](review-checklist.md) - Review checklist diff --git a/skills/agentic-workflow-guide/references/design-principles.md b/skills/agentic-workflow-guide/references/design-principles.md new file mode 100644 index 000000000..76ab2283f --- /dev/null +++ b/skills/agentic-workflow-guide/references/design-principles.md @@ -0,0 +1,210 @@ +# Design Principles + +A collection of principles for designing agent workflows. + +## Tier 1: Core Principles (Essential) + +### 1. SSOT (Single Source of Truth) + +**Manage information in one place** + +| Aspect | Description | +| ------------------------ | ---------------------------------------------------- | +| **Definition** | Don't define the same information in multiple places | +| **Workflow Application** | Centralize context, configuration, and state | +| **Violation Example** | Each agent maintains the same settings separately | +| **Solution** | Use shared context or configuration files | + +### 2. SRP (Single Responsibility Principle) + +**1 Agent = 1 Responsibility** + +| Aspect | Description | +| ------------------------ | ------------------------------------------------- | +| **Definition** | Each agent focuses on a single responsibility | +| **Workflow Application** | Clearly separate tasks and assign to each agent | +| **Violation Example** | One agent handles "search + analysis + reporting" | +| **Solution** | Split agents by role | + +### 3. Simplicity First + +**Start with the simplest solution** + +| Aspect | Description | +| ------------------------ | -------------------------------------------------------------- | +| **Definition** | Keep complexity to what's necessary and sufficient | +| **Workflow Application** | Try with a single agent first. Add complexity only when needed | +| **Violation Example** | Designing a 10-agent workflow from the start | +| **Solution** | Start minimal, extend gradually | + +**Anthropic's Recommendation:** + +> "Start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short." + +### 4. Fail Fast + +**Detect and fix errors early** + +| Aspect | Description | +| ------------------------ | ------------------------------------------------- | +| **Definition** | Detect errors early and handle immediately | +| **Workflow Application** | Validate at each step, stop immediately if issues | +| **Violation Example** | Ignoring errors and continuing to the end | +| **Solution** | Set up Gates/Checkpoints | + +### 5. Iterative Refinement + +**Build small, improve repeatedly** + +| Aspect | Description | +| ------------------------ | ----------------------------------------------------- | +| **Definition** | Prefer small improvements over large changes | +| **Workflow Application** | MVP → verify → feedback → improve | +| **Violation Example** | Implementing all features at once, testing at the end | +| **Solution** | Implement and verify one task at a time | + +**Related Pattern:** Evaluator-Optimizer + +### 6. Feedback Loop + +**Verify results at each step → adjust** + +| Aspect | Description | +| ------------------------ | -------------------------------------------------- | +| **Definition** | Get feedback from execution results, apply to next | +| **Workflow Application** | Evaluate agent output, re-execute if needed | +| **Violation Example** | One-way flow without result verification | +| **Solution** | Incorporate evaluation steps | + +**Anthropic's Recommendation:** + +> "During execution, it's crucial for the agents to gain 'ground truth' from the environment at each step to assess its progress." + +--- + +## Tier 2: Quality Principles (Recommended) + +### 7. Transparency + +**Show plans and progress explicitly** + +| Aspect | Description | +| ------------------------ | -------------------------------------------------- | +| **Definition** | Make what's happening visible | +| **Workflow Application** | Show start/end of each step, display progress | +| **Violation Example** | Black box with no visibility into what's happening | +| **Solution** | Use logs, progress display, TodoWrite | + +**Anthropic's Recommendation:** + +> "Prioritize transparency by explicitly showing the agent's planning steps." + +### 8. Gate/Checkpoint + +**Validation gates at each step** + +| Aspect | Description | +| ------------------------ | --------------------------------------------- | +| **Definition** | Validate before proceeding to the next step | +| **Workflow Application** | Don't proceed unless quality criteria are met | +| **Violation Example** | Passing through all steps without validation | +| **Solution** | Quality checks with conditional branching | + +### 9. DRY (Don't Repeat Yourself) + +**Eliminate duplication, promote reuse** + +| Aspect | Description | +| ------------------------ | ------------------------------------------ | +| **Definition** | Don't repeat the same logic | +| **Workflow Application** | Template common processes, reuse prompts | +| **Violation Example** | Copy-pasting the same prompt to each agent | +| **Solution** | Create common prompt templates | + +### 10. ISP (Interface Segregation Principle) + +**Minimal context only** + +| Aspect | Description | +| ------------------------ | ---------------------------------------------- | +| **Definition** | Pass only necessary information to each agent | +| **Workflow Application** | Excessive context becomes noise | +| **Violation Example** | Passing all information to all agents | +| **Solution** | Select and pass only task-relevant information | + +### 11. Idempotency + +**Safe to retry** + +| Aspect | Description | +| ------------------------ | --------------------------------------------------------- | +| **Definition** | Same operation produces same result regardless of retries | +| **Workflow Application** | Design to allow retries on failure | +| **Violation Example** | Retrying causes data duplication | +| **Solution** | State checking, use unique IDs | + +--- + +## Tier 3: Scale Principles (Advanced) + +### 12. Human-in-the-Loop + +**Human confirmation at critical points** + +| Aspect | Description | +| ------------------------ | ---------------------------------------------------- | +| **Definition** | Balance automation with human judgment | +| **Workflow Application** | Confirm before important decisions, risky operations | +| **Application Example** | Before production deploy, before mass deletion | + +### 13. KISS (Keep It Simple, Stupid) + +**Keep it simple** + +| Aspect | Description | +| ------------------------ | ------------------------------------------------ | +| **Definition** | Avoid unnecessary complexity | +| **Workflow Application** | Sufficient number of agents, simple coordination | + +### 14. Loose Coupling + +**Loose coupling between agents** + +| Aspect | Description | +| ------------------------ | --------------------------------------- | +| **Definition** | Minimize dependencies between agents | +| **Workflow Application** | Each agent can operate independently | +| **Benefits** | Limit impact of changes, easier testing | + +### 15. Graceful Degradation + +**Continue operation despite partial failures** + +| Aspect | Description | +| ------------------------ | ---------------------------------------------- | +| **Definition** | Maintain overall function even when parts fail | +| **Workflow Application** | Fallback processing, skippable steps | + +--- + +## ACI Design (Agent-Computer Interface) + +**Anthropic's Recommendation:** + +> "Think about how much effort goes into human-computer interfaces (HCI), and plan to invest just as much effort in creating good agent-computer interfaces (ACI)." + +### Tool Design Guidelines + +1. **Clear Description** - Clarify tool purpose and usage +2. **Edge Cases** - Document boundary conditions +3. **Input Format** - Specify expected input format +4. **Error Handling** - Define behavior on failure +5. **Testing** - Actually use it and iterate + +--- + +## References + +- [Building Effective Agents - Anthropic](https://www.anthropic.com/engineering/building-effective-agents) +- [SOLID Principles](https://en.wikipedia.org/wiki/SOLID) +- [12-Factor App](https://12factor.net/) diff --git a/skills/agentic-workflow-guide/references/review-checklist.md b/skills/agentic-workflow-guide/references/review-checklist.md new file mode 100644 index 000000000..bd844ed44 --- /dev/null +++ b/skills/agentic-workflow-guide/references/review-checklist.md @@ -0,0 +1,225 @@ +# Review Checklist + +Review checklist for agent workflows. + +## How to Use + +1. Review this checklist after completing workflow design +2. Mark each item as ✅ or ❌ +3. If there are ❌ items, consider solutions +4. Improve until all items are ✅ + +--- + +## Quick Check (5 minutes) + +Minimum items to verify: + +```markdown +- [ ] Is each agent focused on a single responsibility? (SRP) +- [ ] Can errors be detected and stopped immediately? (Fail Fast) +- [ ] Is it divided into small steps? (Iterative) +- [ ] Can results be verified at each step? (Feedback Loop) +- [ ] Is there any possibility of infinite loops? +``` + +--- + +## Detailed Check + +### Core Principles Check + +```markdown +## SSOT (Single Source of Truth) + +- [ ] Is the same information defined in multiple places? +- [ ] Is configuration/context centrally managed? +- [ ] Is there a mechanism to reflect updates across the entire system? + +## SRP (Single Responsibility Principle) + +- [ ] Is each agent focused on a single responsibility? +- [ ] Are responsibility boundaries clear? +- [ ] Is there role overlap between agents? + +## Simplicity First + +- [ ] Is this the simplest possible solution? +- [ ] Are there unnecessary agents or steps? +- [ ] Could this be achieved with a simpler approach? + +## Fail Fast + +- [ ] Can errors be detected immediately? +- [ ] Can the system stop appropriately on errors? +- [ ] Are error messages clear? + +## Iterative Refinement + +- [ ] Is it divided into small steps? +- [ ] Can each step be verified? +- [ ] Is the structure suitable for gradual improvement? + +## Feedback Loop + +- [ ] Can results be verified at each step? +- [ ] Can feedback be applied to the next step? +- [ ] Is there a structure for improvement cycles? +``` + +### Quality Principles Check + +```markdown +## Transparency + +- [ ] Are plans and progress visualized? +- [ ] Is it clear to users what's happening? +- [ ] Are logs being output sufficiently? + +## Gate/Checkpoint + +- [ ] Is validation performed at each step? +- [ ] Are conditions for proceeding clearly defined? +- [ ] Is handling for validation failures defined? + +## DRY (Don't Repeat Yourself) + +- [ ] Are common processes being reused? +- [ ] Are prompt templates being utilized? +- [ ] Is there duplication of the same logic? + +## ISP (Interface Segregation Principle) + +- [ ] Is only the minimum necessary information being passed? +- [ ] Is unnecessary context being included? +- [ ] Is required information for each agent clear? + +## Idempotency + +- [ ] Is it safe to retry? +- [ ] Does executing the same operation multiple times produce the same result? +- [ ] Are side effects being managed? +``` + +### Scale & Safety Check + +```markdown +## Human-in-the-Loop + +- [ ] Are important decisions requiring human confirmation? +- [ ] Is there confirmation before high-risk operations? +- [ ] Is the balance between automation and human judgment appropriate? + +## Termination Conditions + +- [ ] Is there any possibility of infinite loops? +- [ ] Is a maximum iteration count set? +- [ ] Is a timeout set? + +## Error Handling + +- [ ] Is error handling missing anywhere? +- [ ] Is there handling for unexpected errors? +- [ ] Are recovery procedures defined? + +## Security + +- [ ] Is sensitive information being handled appropriately? +- [ ] Are permissions set to minimum? +- [ ] Can audit logs be collected? +``` + +--- + +## Anti-Pattern Detection + +If any of the following apply, review the design: + +```markdown +- [ ] **God Agent**: Is too much responsibility packed into one agent? + → Split with SRP + +- [ ] **Context Overload**: Is excessive context being passed? + → Minimize with ISP + +- [ ] **Silent Failure**: Are errors being ignored and continuing? + → Stop immediately with Fail Fast + +- [ ] **Infinite Loop**: Are there loops without termination conditions? + → Set maximum iterations + +- [ ] **Big Bang**: Trying to build everything at once? + → Build small with Iterative + +- [ ] **Premature Optimization**: Making it more complex than necessary? + → Apply Simplicity First +``` + +--- + +## Review Result Template + +```markdown +# Workflow Review Results + +## Overview + +- **Workflow Name**: +- **Review Date**: +- **Reviewer**: + +## Check Results + +### Core Principles + +| Principle | Result | Comment | +| -------------------- | ------ | ------- | +| SSOT | ✅/❌ | | +| SRP | ✅/❌ | | +| Simplicity First | ✅/❌ | | +| Fail Fast | ✅/❌ | | +| Iterative Refinement | ✅/❌ | | +| Feedback Loop | ✅/❌ | | + +### Quality Principles + +| Principle | Result | Comment | +| --------------- | ------ | ------- | +| Transparency | ✅/❌ | | +| Gate/Checkpoint | ✅/❌ | | +| DRY | ✅/❌ | | +| ISP | ✅/❌ | | +| Idempotency | ✅/❌ | | + +### Anti-Patterns + +| Pattern | Detected | Solution | +| ---------------- | -------- | -------- | +| God Agent | ✅/❌ | | +| Context Overload | ✅/❌ | | +| Silent Failure | ✅/❌ | | +| Infinite Loop | ✅/❌ | | +| Big Bang | ✅/❌ | | + +## Improvement Proposals + +1. +2. +3. + +## Overall Evaluation + +- [ ] Approved +- [ ] Conditionally Approved (after minor fixes) +- [ ] Requires Revision +``` + +--- + +## Next Steps + +After review completion: + +1. **All ✅** → Proceed to implementation +2. **Minor ❌** → Re-check after fixes +3. **Major ❌** → Revise design, re-review diff --git a/skills/agentic-workflow-guide/references/workflow-patterns.md b/skills/agentic-workflow-guide/references/workflow-patterns.md new file mode 100644 index 000000000..f437b7e36 --- /dev/null +++ b/skills/agentic-workflow-guide/references/workflow-patterns.md @@ -0,0 +1,280 @@ +# Workflow Patterns + +Five fundamental patterns for agent workflows. + +## Pattern Selection Flowchart + +``` +What's the nature of the task? +│ +├─ Sequential processing needed (clear step ordering) +│ └─→ Prompt Chaining +│ +├─ Multiple independent tasks (no mutual impact) +│ └─→ Parallelization +│ +├─ Dynamic number of tasks (not predetermined) +│ └─→ Orchestrator-Workers +│ +├─ Repeat until quality criteria met +│ └─→ Evaluator-Optimizer +│ +└─ Processing varies significantly by input + └─→ Routing +``` + +--- + +## 1. Prompt Chaining + +**Sequential processing with validation at each step** + +```mermaid +graph LR + A[Input] --> B[Step 1] + B --> C{Gate} + C -->|Pass| D[Step 2] + C -->|Fail| E[Handle Error] + D --> F[Step 3] + F --> G[Output] +``` + +### Characteristics + +| Aspect | Description | +| ------------- | -------------------------------------------------------- | +| **Structure** | Serial processing, output of each step is input for next | +| **Gate** | Can set validation gates after each step | +| **Use Cases** | Document translation, code generation → review → fix | + +### When to Use + +- Task can be decomposed into clear subtasks +- Each step's output is needed for the next step +- Intermediate result validation is important + +### Implementation Example + +``` +Step 1: Analyze requirements + ↓ (Gate: Are requirements clear?) +Step 2: Create design + ↓ (Gate: Is design valid?) +Step 3: Implement + ↓ (Gate: Tests passing?) +Step 4: Create documentation +``` + +--- + +## 2. Routing + +**Classify input → Route to specialized handlers** + +```mermaid +graph TD + A[Input] --> B{Router} + B -->|Type A| C[Handler A] + B -->|Type B| D[Handler B] + B -->|Type C| E[Handler C] + C --> F[Output] + D --> F + E --> F +``` + +### Characteristics + +| Aspect | Description | +| ------------- | ---------------------------------------- | +| **Structure** | Classifier + specialized handlers | +| **Benefits** | Each handler can be optimized | +| **Use Cases** | Customer support, inquiry classification | + +### When to Use + +- Input has clear categories +- Different processing is optimal per category +- Classification accuracy is sufficiently high + +### Implementation Example + +``` +Router: Determine inquiry type +├─ Technical question → Technical Support Agent +├─ Billing related → Billing Support Agent +└─ General question → FAQ Agent +``` + +--- + +## 3. Parallelization + +**Execute independent tasks simultaneously** + +```mermaid +graph TD + A[Input] --> B[Task 1] + A --> C[Task 2] + A --> D[Task 3] + B --> E[Aggregator] + C --> E + D --> E + E --> F[Output] +``` + +### Characteristics + +| Aspect | Description | +| -------------- | ----------------------------------------------------- | +| **Structure** | Split → parallel execution → aggregate | +| **Benefits** | Reduced processing time, robustness from independence | +| **Variations** | Sectioning (division), Voting (majority decision) | + +### When to Use + +- Tasks are independent (no shared state) +- Parallel execution can reduce time +- Multiple perspectives/results are desired + +### Implementation Example + +``` +Input: Document +├─ Agent 1: Grammar check +├─ Agent 2: Content accuracy check +└─ Agent 3: Style check + ↓ +Aggregator: Integrate all results +``` + +--- + +## 4. Orchestrator-Workers + +**Dynamically decompose tasks → Dispatch to workers** + +```mermaid +graph TD + A[Input] --> B[Orchestrator] + B --> C[Plan Tasks] + C --> D[Worker 1] + C --> E[Worker 2] + C --> F[Worker N] + D --> G[Synthesizer] + E --> G + F --> G + G --> H[Output] +``` + +### Characteristics + +| Aspect | Description | +| ------------- | ----------------------------------------------- | +| **Structure** | Orchestrator + dynamic workers + synthesizer | +| **Benefits** | Works even when task count is not predetermined | +| **Use Cases** | Code changes (multiple files), research | + +### When to Use + +- Number of subtasks depends on input +- Each subtask can be executed independently +- Result synthesis is required + +### Implementation Example + +``` +Orchestrator: + - Generate file change list + - Assign workers to each file + +Workers: + - Worker 1 → Modify file1.py + - Worker 2 → Modify file2.py + - Worker 3 → Modify test.py + +Synthesizer: + - Merge all changes + - Resolve conflicts +``` + +--- + +## 5. Evaluator-Optimizer + +**Generate → Evaluate → Improve loop** + +```mermaid +graph TD + A[Input] --> B[Generator] + B --> C[Output v1] + C --> D[Evaluator] + D -->|Not Good| E[Feedback] + E --> B + D -->|Good| F[Final Output] +``` + +### Characteristics + +| Aspect | Description | +| ------------- | ------------------------------------------- | +| **Structure** | Generator + evaluator + feedback loop | +| **Benefits** | Improves until quality criteria are met | +| **Use Cases** | Translation, code review, text proofreading | + +### When to Use + +- Clear quality criteria exist +- Iterative improvement increases quality +- Want to mimic human feedback + +### Implementation Example + +``` +Generator: Generate translation + ↓ +Evaluator: + - Is the nuance accurate? + - Is the grammar correct? + - Does it reflect the original intent? + ↓ + ├─ OK → Complete + └─ NG → Regenerate with feedback +``` + +--- + +## Combining Patterns + +In real workflows, multiple patterns are often combined. + +### Example: Code Generation Workflow + +```mermaid +graph TD + A[Requirements] --> B{Routing} + B -->|New Feature| C[Design Agent] + B -->|Bug Fix| D[Analysis Agent] + C --> E[Orchestrator] + D --> E + E --> F[Implementation Worker 1] + E --> G[Implementation Worker 2] + F --> H[Evaluator] + G --> H + H -->|NG| I[Feedback] + I --> F + I --> G + H -->|OK| J[Complete] +``` + +**Patterns Used:** + +1. **Routing** - Branch processing by requirement type +2. **Orchestrator-Workers** - Implement per file +3. **Evaluator-Optimizer** - Review → fix loop + +--- + +## 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) diff --git a/skills/agentic-workflow-guide/scripts/scaffold_workflow.py b/skills/agentic-workflow-guide/scripts/scaffold_workflow.py new file mode 100644 index 000000000..dab87d600 --- /dev/null +++ b/skills/agentic-workflow-guide/scripts/scaffold_workflow.py @@ -0,0 +1,1480 @@ +#!/usr/bin/env python3 +""" +scaffold_workflow.py - Generate directory structure for agent workflows + +Usage: + python scaffold_workflow.py [--pattern ] [--path ] + +Examples: + python scaffold_workflow.py my-workflow + python scaffold_workflow.py code-review --pattern evaluator-optimizer + python scaffold_workflow.py data-pipeline --pattern orchestrator-workers --path ./projects +""" + +import argparse +import os +from pathlib import Path + +# Common templates (used for all patterns) +COMMON_TEMPLATES = { + "Agent.md": '''# {workflow_name} - Agent Workflow + +## Overview + +This workflow implements the **{pattern}** pattern for {purpose}. + +## Agents + +| Agent | Role | Done Criteria | +|-------|------|---------------| +| | | | + +## Workflow Flow + +```mermaid +graph TD + A[Input] --> B[Agent 1] + B --> C[Output] +``` + +## I/O Contract + +- **Input**: [Description of input format] +- **Output**: [Description of output format] +- **IR Format**: (if applicable) Intermediate representation specification + +## Design Principles + +This workflow follows: +- **SSOT**: Single source of truth for all data +- **SRP**: Each agent has one responsibility +- **Fail Fast**: Errors are caught early +- **Iterative**: Small, verifiable steps +- **Idempotency**: Same input → same output + +## Quick Start + +1. Configure agents in `agents/` +2. Set up prompts in `prompts/` +3. Run with your orchestration framework + +## References + +- [Design Document](docs/design.md) +- [agentic-workflow-guide](https://github.com/aktsmm/Agent-Skills/tree/master/agentic-workflow-guide) +''', + + ".github/copilot-instructions.md": '''# Repository Copilot Instructions for {workflow_name} + +In this workflow, Copilot is treated as part of an autonomous agent workflow. + +## Agent Behavior Guidelines + +1. **Plan First**: + - Present a step-by-step plan before tackling complex tasks + - Get user approval before execution + +2. **Context Awareness**: + - Read relevant files before working to understand project context + - Don't write code based on assumptions; check existing implementation patterns + +3. **Self-Correction**: + - After making code changes, run verification when possible + - When errors occur, analyze and present/execute fix proposals + +## Workflow Pattern + +**{pattern}** - {pattern_description} + +## Coding Standards + +- **DRY & SOLID**: Avoid duplication, follow single responsibility principle +- **SSOT**: Manage information in one place, others reference it +- **Fail Fast**: Detect and report errors early + +## Communication Style + +- **Conclusion First**: State conclusion first, then reasons and details +- **Match User Language**: Respond in the user's language + +## File Structure + +- Agent definitions: `agents/*.agent.md` +- Prompts: `prompts/*.prompt.md` +- Configuration: `config/*.yaml` +- Instructions: `.github/instructions/` + +## References + +- [Agent.md](../Agent.md) - Workflow overview +- [docs/design.md](../docs/design.md) - Design document +''', + + ".github/instructions/workflow.instructions.md": '''--- +applyTo: "**" +--- + +# Workflow Instructions + +Rules applied to the entire workflow. + +## Basic Principles + +- Each agent has a single responsibility +- Errors are detected early with clear messages +- Intermediate state is always verifiable + +## Naming Conventions + +- Agents: `{{role}}_agent.md` +- Prompts: `{{purpose}}_prompt.md` +- Config: `{{scope}}_config.yaml` + +## File Structure + +``` +{workflow_name}/ +├── Agent.md # Workflow overview +├── .github/ +│ ├── copilot-instructions.md +│ └── instructions/ +│ └── workflow.instructions.md +├── agents/ # Agent definitions +├── prompts/ # Prompt templates +├── docs/ # Design documents +└── config/ # Configuration files +``` +''', + + ".github/instructions/agents.instructions.md": '''--- +applyTo: "agents/**" +--- + +# Agent Instructions + +Rules applied when editing files in the `agents/` directory. + +## Agent Definition Structure + +```markdown +# Agent: {{name}} + +## Role +Describe the agent's role in one sentence + +## Responsibilities +- Responsibility 1 +- Responsibility 2 + +## Input +- input1: Description + +## Output +- output1: Description + +## Constraints +- Constraint details +``` + +## Best Practices + +1. **1 Agent = 1 Responsibility** - Split if there are multiple responsibilities +2. **Clear I/O** - Avoid ambiguous definitions +3. **Explicit Constraints** - Consider edge cases +''', + + ".github/instructions/prompts.instructions.md": '''--- +applyTo: "prompts/**" +--- + +# Prompt Instructions + +Rules applied when editing files in the `prompts/` directory. + +## Prompt Structure + +```markdown +# {{Purpose}} Prompt + +## Context +Background information + +## Task +Task description + +## Guidelines +1. Guideline 1 +2. Guideline 2 + +## Output Format +Expected output format +``` + +## Best Practices + +1. **Clear Instructions** - Avoid ambiguous expressions +2. **Include Examples** - Show expected output examples +3. **Explicit Constraints** - Write what should NOT be done +4. **Use `{{placeholder}}` format for variables** - Enable dynamic substitution +''', + + "prompts/system_prompt.md": '''# System Prompt + +You are a specialized agent in the {workflow_name} workflow. + +## Your Role + +[Describe the agent's role in one sentence] + +## Guidelines + +1. **Plan First**: Present a plan before executing complex tasks +2. **Single Responsibility**: Focus on your responsibility, delegate the rest +3. **Validate First**: Validate input before processing +4. **Fail Fast**: Detect and report errors early +5. **Transparency**: Report progress explicitly + +## Constraints + +- Do not fill in data based on assumptions (confirm unclear points) +- Stop processing if validation fails +- Request confirmation before destructive operations +- `git push` is prohibited by default + +## Output Format + +- Conclusion first (conclusion → reasons → details) +- Strive for structured output +''', + + "prompts/create-agent.prompt.md": '''# Prompt: Create New Agent + +Prompt for creating a new agent definition (`.agent.md`). + +## Prerequisites + +- Reference: `agents/sample.agent.md` (template) +- Reference: `.github/instructions/agents.instructions.md` + +## Instructions + +1. Define **Role** and **Goals** from user requirements +2. Write **Done Criteria** in verifiable form +3. Follow the principle of least privilege for **Permissions** +4. Clearly define **I/O Contract** +5. Break down **Workflow** into specific steps + +## Output Format + +```markdown +# [Agent Name] + +## Role +[Role in one sentence] + +## Goals +- [Goal 1] +- [Goal 2] + +## Done Criteria +- [Verifiable completion condition 1] +- [Verifiable completion condition 2] + +## Permissions +- **Allowed**: [Permitted operations] +- **Denied**: `git push`, deletion without user permission + +## I/O Contract +- **Input**: [Input format] +- **Output**: [Output format] + +## Workflow +1. **Plan**: Analyze request and present steps +2. **Act**: Execute after approval +3. **Verify**: Verify results + +## Error Handling +- When errors occur, analyze and attempt to fix +- Report to human after 3 consecutive failures + +## Idempotency +- Check existing state before operations +- Avoid duplicate processing +``` +''', + + "prompts/design-workflow.prompt.md": '''# Prompt: Design Agent Workflow + +Prompt for designing an agent workflow. + +## Prerequisites + +- Reference: `docs/design.md` +- Principles: SSOT, SRP, Simplicity First, Fail Fast + +## Instructions + +Design the following based on user requirements: + +### Step 1: Determine Complexity Level + +| Level | Agent Count | Use Case | +|-------|-------------|----------| +| Simple | 1 | Single task, simple processing | +| Medium | 2-3 | Orchestrator + workers | +| Complex | 4+ | Multiple specialized agents | + +**Principle: Start Simple** - Try the minimum configuration first + +### Step 2: Create Design Document + +1. **Workflow Purpose**: What problem does it solve? +2. **Agent Composition**: Roles and responsibilities +3. **I/O Contract**: Input/output definitions +4. **Interaction Flow**: Data flow +5. **Verification Points**: Gate/Checkpoint placement +6. **Error Handling**: Response to failures + +## Output Format + +```markdown +# [Workflow Name] Design + +## Overview +- **Purpose**: +- **Complexity**: Simple | Medium | Complex +- **Pattern**: [Prompt Chaining | Routing | Parallelization | Orchestrator-Workers | Evaluator-Optimizer] + +## Agents +| Agent | Role | Input | Output | +|-------|------|-------|--------| + +## Flow +```mermaid +graph TD + A[Input] --> B[Agent 1] + B --> C{{Gate}} + C -->|Pass| D[Agent 2] + C -->|Fail| E[Error Handler] +``` + +## Checkpoints +1. [Verification points between steps] + +## Error Handling +- [Response on error] +``` +''', + + "prompts/plan-workflow.prompt.md": '''# Prompt: Plan Agent Workflow + +Prompt for planning a combination of multiple agents. + +## Prerequisites + +- Reference: `Agent.md` (list of available agents) + +## Instructions + +Follow these steps to create a plan for achieving the user's task: + +1. **Task Decomposition**: Break down into independent subtasks +2. **Agent Selection**: Choose the optimal agent for each subtask +3. **Flow Definition**: Define data handoff and sequence +4. **Verification Points**: Verification method after each step +5. **Execution Plan**: Specific execution steps + +## Output Example + +### Step 1: Requirements Definition +- **Agent**: orchestrator +- **Goal**: Organize user's requirements +- **Output**: `docs/requirements.md` +- **Validation**: User confirmation + +### Step 2: Implementation +- **Agent**: worker +- **Input**: requirements.md from Step 1 +- **Goal**: Perform implementation +- **Output**: Implementation files +- **Validation**: Run tests +''', + + "prompts/review-agent.prompt.md": '''# Prompt: Review Agent Definition + +Prompt for reviewing agent definitions. + +## Design Principles Checklist + +### Tier 1: Core Principles (Required) +- [ ] **SRP**: Is it 1 agent = 1 responsibility? +- [ ] **SSOT**: Is information centrally managed? +- [ ] **Fail Fast**: Can errors be detected early? + +### Tier 2: Quality Principles (Recommended) +- [ ] **I/O Contract**: Are inputs/outputs clearly defined? +- [ ] **Done Criteria**: Are completion conditions verifiable? +- [ ] **Idempotency**: Is the design retry-safe? +- [ ] **Error Handling**: Is error handling documented? + +### Structure Check +- [ ] Is Role clear in one sentence? +- [ ] Are Goals specific? +- [ ] Are Permissions minimal? +- [ ] Is Workflow broken into steps? + +## Output Format + +```markdown +## Review Result + +### ✅ Good Points +- [Good points] + +### ⚠️ Improvements Needed +- [Improvement points] + +### Recommendation +[Overall evaluation and recommended actions] +``` +''', + + "prompts/error_handling_prompt.md": '''# Error Handling Prompt + +Protocol for handling errors. + +## Error Classification + +| Type | Description | Recovery | +|------|-------------|----------| +| ValidationError | Invalid input data | Fix input and retry | +| ProcessingError | Failure during processing | Analyze cause and retry | +| TimeoutError | Timeout | Retry or skip | +| DependencyError | External service failure | Fallback | + +## Response Format + +```yaml +error: + type: {{error_type}} + message: {{error_message}} + context: {{relevant_context}} + recovery: + possible: true/false + suggestion: {{recovery_suggestion}} + retry_count: {{current_retry}}/3 +``` + +## Escalation Rules + +1. **Retry**: Same error up to 3 times max +2. **Fallback**: Try alternative method if possible +3. **Handoff**: Report to human after 3 failures +4. **Log**: Record all context + +## Fail Fast Principle + +- Detect errors early +- Report immediately when problems occur +- Do not continue in an ambiguous state +''', + + "prompts/review-retrospective-learnings.prompt.md": '''# Prompt: Agent Design Retro + +Extract reusable design insights from events (incident response, errors, fix PRs) +and reflect them in design assets for prevention and quality improvement. + +## Your Role +You are an "AI Agent Design Improvement Architect". + +## Premises +- Do not make changes based on assumptions. Always read target files first. +- Prioritize additions over new content. Use reference links for duplicates. +- For destructive changes, always confirm first. + +## Input +- Response history (timeline, logs, error messages, fixes) +- Scope of reflection (Agents.md / *.agent.md / instructions) + +## Steps + +### Step 0: Context Collection +1. Read target files (Agents.md, agents/*.agent.md, instructions/*.md) +2. Summarize existing rules in 5 lines or less + +### Step 1: Extract and Classify Learnings +- Design principle level (separation of concerns, idempotency) +- Workflow level (call order, preconditions, error handling) +- Agent-specific rules (input assumptions, prohibitions) + +Format: Learning (1 line) + Evidence + Impact + +### Step 2: Generalization Judgment +For each learning, determine: +- Individual response / Generalize / Strengthen existing rules +- Check for duplicates/conflicts + +### Step 3: Determine Reflection Target +- Common principles → Agents.md +- Agent-specific → .github/agents/*.agent.md +- Overall constraints → .github/instructions/*.md + +### Step 4: Present Update Content +Show "exactly how to rewrite" in code blocks: +- add / replace / restructure +- Change granularity (add heading, bullet points, etc.) + +### Step 5: Final Check +- Design philosophy is consistent +- Reusability and maintainability improve +- Same trouble is less likely to recur +''', + + "prompts/create-agentWF.prompt.md": '''# Create Agent Workflow Prompt + +Hearing prompt for designing agent workflows through user dialogue. + +## Mode: Start Hearing + +You are an agent workflow design facilitator. + +## Step 1: Confirm Purpose + +``` +What kind of agent workflow do you want to create? + +Please tell me: +1. **What do you want to achieve?** (report generation, automation, analysis...) +2. **For whom?** (personal, team, customer demo...) +3. **Trigger?** (manual, schedule, event...) +``` + +## Step 2: Define Input/Output + +``` +**Input:** +- What will you receive? (file, API, user input...) +- Format? (JSON, text, CLI arguments...) + +**Output:** +- What to generate? (report, diagram, file...) +- Format? (Markdown, CSV, PDF...) +- Destination? (file, Issue, Slack...) +``` + +## Step 3: Confirm Tools/APIs + +``` +- **External API**: Azure CLI, GitHub CLI, REST API... +- **Authentication**: Via environment variables? +- **Existing tools**: Scripts in the project? +``` + +## Step 4: Consider Workflow Structure + +``` +1. **Complexity**: Single agent or multiple? +2. **Steps**: How many stages? +3. **Review**: Human confirmation points? +4. **On error**: Retry? Report to human? + +Examples: +- Simple → 1 agent +- Medium → Orchestrator + 1-2 workers +- Large → Orchestrator + multiple workers +``` + +## Step 5: Design Principles Confirmation + +``` +This workflow follows: +- Two-stage architecture: Input → IR → Output +- Idempotency: Same input → same result +- Separation of concerns +- Fail-safe with error handling +- Observability with logs +``` + +## Step 6: Generate Deliverables + +``` +Deliverables: +1. Agent definition (.github/agents/{{name}}.agent.md) +2. IR schema (if needed) +3. Report template (if needed) +``` + +## Hearing Result IR Template + +```yaml +workflow: + name: "{{{{workflow_name}}}}" + purpose: "{{{{purpose}}}}" + trigger: "{{{{trigger}}}}" +io: + input: {{ source: "", format: "" }} + output: {{ type: "", format: "", destination: "" }} +architecture: + complexity: "simple|medium|complex" + agents: [] + human_checkpoints: [] + error_handling: "" +``` +''' +} + +# Extended instruction templates (optional, generated with --include-instructions flag) +EXTENDED_INSTRUCTIONS = { + ".github/instructions/agent-design.instructions.md": '''--- +applyTo: "**" +--- + +# Agent Workflow Design Instructions + +## Part 1: Agent Design Principles + +### 1. Single Responsibility Principle (SRP) +- **1 Agent, 1 Goal**: Give each agent one clearly defined role. +- **Separation of Roles**: Separate by phase: "planning", "implementation", "review", "testing". + +### 2. Stateless & Idempotency +- Design agents to judge based on file system state, not conversation history. +- Design workflows to converge to correct state when re-run. + +### 3. Orchestration +- For complex tasks, use "manager agent" delegating to "worker agents". +- Clearly define expected deliverables for handoffs. + +### 4. Fail-safe & Human-in-the-loop +- Before irreversible operations, ask human confirmation. +- Design prompts to analyze errors and attempt fixes. + +### 5. Observability +- Record decisions as Issue comments or documents. +- For long tasks, have regular status reports. + +## Part 2: Workflow Architecture + +### 6. Two-stage Architecture +Input → IR (Intermediate Representation) → Output + +### 7. IR Specification +- Define allowed structure (JSON/YAML/structured Markdown) +- Strict validation; do not auto-complete + +### 8. Separation of Concerns +| Responsibility | Description | +|---------------|-------------| +| Generate | Generate IR | +| Validate | Verify IR | +| Transform | Convert IR to output | +| Render | Output to final format | + +### 9. Determinism +Same IR → Same output. No creativity in transformation. +''', + + ".github/instructions/communication.instructions.md": '''--- +applyTo: "**" +--- + +# Communication Instructions + +## 1. Response Style +- **Conclusion First**: State conclusion, then reasons and details. +- **Conciseness**: Avoid verbose explanations. +- **Logical Structure**: Use bullet points, tables, headings. + +## 2. Language Settings +- Match user's language for dialogue +- Follow existing comment style in code + +## 3. Citation of References +- Include relative paths for file references +- Include URLs for external resources + +## 4. Confirmation and Approval +Always seek user confirmation before: +- File deletion or large-scale changes +- External service connections +- Design policy decisions + +## 5. Error Reporting Format +1. What happened (overview) +2. Why (cause analysis) +3. What to do (recommended remediation) +''', + + ".github/instructions/git.instructions.md": '''--- +applyTo: "**" +--- + +# Git Commit Instructions + +Use **Conventional Commits** format. + +## Format +``` +(): +``` + +## Types +- **feat**: New feature +- **fix**: Bug fix +- **docs**: Documentation only +- **style**: Formatting (no code change) +- **refactor**: Code change (no feature/bug) +- **test**: Adding/correcting tests +- **chore**: Build/tool changes + +## Rules +- Use imperative form ("add" not "added") +- No period at end +- Lowercase first letter + +## Important +- **Push Prohibited**: No `git push` without explicit instruction +- Split commits for multiple logical changes +''', + + ".github/instructions/terminal.instructions.md": '''--- +applyTo: "**" +--- + +# Terminal Instructions + +## 1. Confirm Current Directory +Always verify location before commands: +```powershell +Get-Location +Set-Location "path/to/project" +``` + +## 2. Command Syntax (PowerShell) +- Use `;` to chain commands (not `&&`) +- Use pipeline `|` for data operations + +## 3. Destructive Operations +- Verify paths before delete/move +- Avoid wildcards; use specific names + +## 4. Long-running Processes +- Use background execution for servers +- Inform user about non-terminating commands +''', + + ".github/instructions/security.instructions.md": '''--- +applyTo: "**" +--- + +# Security Instructions + +## 1. Confidential Information +**Prohibited:** +- Hardcoding API keys, passwords, tokens +- Committing `.env` or secret files + +**Recommended:** +- Use environment variables +- Use secret management (Key Vault, GitHub Secrets) +- Configure `.gitignore` + +## 2. External Libraries +- Check license compatibility +- Check for vulnerabilities (npm audit, pip-audit) + +## 3. API Calls +- Principle of least privilege +- Implement rate limiting and backoff + +## 4. Git Operations +- No `git push` without instruction +- No `--force` push +- Use PR-based workflow + +## 5. Input Validation +- Sanitize for injection attacks +- Prevent directory traversal +''', + + ".github/instructions/microsoft-docs.instructions.md": '''--- +applyTo: "**" +--- + +# Microsoft Documentation Instructions + +## Basic Policy +Reference latest official documentation for Microsoft/Azure answers. + +## Required Procedure +1. Use MCP tools to get latest info +2. Always include reference URLs +3. Note API versions + +## MCP Tool Workflow +``` +1. microsoft_docs_search → Find docs +2. microsoft_code_sample_search → Get code samples +3. microsoft_docs_fetch → Get full content +``` + +## Answer Format +```markdown +## Answer +[Content] + +### References +- [Doc Title](URL) - Microsoft Learn +- API Version: 2024-01-01 +``` + +## Priority +1. Official docs via MCP tools (highest) +2. Official GitHub repos +3. Official blogs/announcements +''' +} + +# Templates for each workflow pattern +PATTERNS = { + "basic": { + "description": "Basic workflow structure", + "structure": { + "agents": { + "__description__": "Agent definitions", + "sample.agent.md": '''# Sample Agent + +## Role + +You are a [role name]. You perform [action] on [target]. + +## Goals + +- [Goal 1] +- [Goal 2] + +## Done Criteria + +- [Completion condition 1: Describe in verifiable form] +- [Completion condition 2] + +## Permissions + +- **Allowed**: File reading, proposal creation +- **Denied**: `git push`, file deletion without user permission + +## I/O Contract + +- **Input**: [Description of input format] +- **Output**: [Description of output format] +- **IR Format**: (if applicable) Structured data specification + +## References + +- [Workflow Instructions](../.github/instructions/workflow.instructions.md) + +## Workflow + +1. **Plan**: Analyze user's request and present steps +2. **Act**: Execute after approval +3. **Verify**: Confirm results + +## Error Handling + +- When errors occur, analyze error messages and attempt to fix +- Report to human after 3 consecutive failures +- Always request confirmation before destructive operations + +## Idempotency + +- Check for existing files before operations +- Always check state to avoid duplicate processing +''', + "orchestrator.agent.md": '''# Orchestrator Agent + +## Role + +You are the orchestrator (commander). You analyze user requests, delegate work to appropriate sub-agents, and manage overall progress. + +## Goals + +- Understand user requests and decompose tasks +- Assign appropriate work to each sub-agent +- Monitor progress and report results to users + +## Done Criteria + +- All subtasks have `completed` or `skipped` status +- Final report has been presented to the user + +## Permissions + +- **Allowed**: Task decomposition, delegation to sub-agents, progress reporting +- **Denied**: Direct code editing, file deletion, `git push` + +## Non-Goals (What not to do) + +- Do not write code directly (delegate implementation to specialized agents) +- Do not review yourself (delegate reviews to specialized agents) +- Do not assume user intent (confirm unclear points) + +## I/O Contract + +- **Input**: Natural language request from user +- **Output**: + - Task decomposition results + - Final report (deliverables list + status) + +## Workflow + +1. **Analyze**: Analyze user request and identify required tasks +2. **Plan**: Decompose tasks and present plan for which sub-agent to delegate to +3. **Delegate**: After user approval, invoke sub-agents +4. **Monitor**: Check results from each sub-agent and handle any issues +5. **Report**: Report overall results to user + +## Error Handling + +- If a sub-agent fails 3 times consecutively, report to human and handoff +- Log failed tasks and maintain retry-capable state + +## Idempotency + +- Always read task state from files (do not depend on conversation history) +- Do not re-execute already completed tasks +''' + }, + "prompts": { + "__description__": "Prompt templates" + }, + "docs": { + "__description__": "Design documents", + "design.md": '''# Workflow Design Document + +## Overview +- **Name**: +- **Purpose**: +- **Pattern**: + +## Agents +| Agent | Role | Input | Output | +|-------|------|-------|--------| +| | | | | + +## Flow +```mermaid +graph TD + A[Start] --> B[Agent 1] + B --> C[Agent 2] + C --> D[End] +``` + +## Design Principles Check +- [ ] SSOT: Is information centrally managed? +- [ ] SRP: Is each agent single responsibility? +- [ ] Fail Fast: Stop immediately on error? +- [ ] Iterative: Is it divided into small steps? +- [ ] Feedback Loop: Can results be verified? +''', + "review_notes.md": '''# Review Notes + +## Review Date +- + +## Reviewer +- + +## Checklist Results +See: agentic-workflow-guide/references/review-checklist.md + +## Issues Found +1. + +## Action Items +1. +''' + }, + "config": { + "__description__": "Configuration files", + "workflow_config.yaml": '''# Workflow Configuration + +name: "{workflow_name}" +version: "1.0.0" + +# Agents +agents: + - name: agent_1 + prompt: prompts/system_prompt.md + +# Flow +flow: + - step: 1 + agent: agent_1 + next: 2 + +# Error handling +error_handling: + max_retries: 3 + on_failure: stop +''' + } + } + }, + "prompt-chaining": { + "description": "Sequential processing pattern", + "structure": { + "agents": { + "__description__": "Sequentially executed agents", + "step1_agent.md": "# Step 1 Agent\n\n## Role\nHandle the first step\n", + "step2_agent.md": "# Step 2 Agent\n\n## Role\nHandle the second step\n", + "step3_agent.md": "# Step 3 Agent\n\n## Role\nHandle the final step\n" + }, + "prompts": { + "__description__": "Prompts for each step" + }, + "gates": { + "__description__": "Validation gates between steps", + "gate_template.md": '''# Gate: Step N → Step N+1 + +## Validation Criteria +- [ ] Condition 1 +- [ ] Condition 2 + +## On Pass +Proceed to next step + +## On Fail +Error handling or retry +''' + }, + "docs": { + "__description__": "Design documents", + "design.md": "# Prompt Chaining Workflow\n\n## Pattern: Prompt Chaining\nSequential processing with validation at each step\n" + }, + "config": { + "__description__": "Configuration files" + } + } + }, + "parallelization": { + "description": "Parallel processing pattern", + "structure": { + "agents": { + "__description__": "Parallel executed agents", + "worker1_agent.md": "# Worker 1 Agent\n\n## Role\nHandle parallel task 1\n", + "worker2_agent.md": "# Worker 2 Agent\n\n## Role\nHandle parallel task 2\n", + "worker3_agent.md": "# Worker 3 Agent\n\n## Role\nHandle parallel task 3\n", + "aggregator_agent.md": "# Aggregator Agent\n\n## Role\nAggregate results from all workers\n" + }, + "prompts": { + "__description__": "Prompts for workers" + }, + "docs": { + "__description__": "Design documents", + "design.md": "# Parallelization Workflow\n\n## Pattern: Parallelization\nExecute independent tasks simultaneously\n" + }, + "config": { + "__description__": "Configuration files" + } + } + }, + "orchestrator-workers": { + "description": "Orchestrator + workers pattern", + "structure": { + "agents": { + "__description__": "Orchestrator and workers", + "orchestrator_agent.md": '''# Orchestrator Agent + +## Role +Dynamically decompose tasks and assign to workers + +## Responsibilities +1. Analyze input +2. Generate subtasks +3. Launch workers +4. Integrate results +''', + "worker_agent.md": '''# Worker Agent Template + +## Role +Execute assigned subtask + +## Input +- task: Subtask content +- context: Required context + +## Output +- result: Task result +- status: Success/Failure +''', + "synthesizer_agent.md": '''# Synthesizer Agent + +## Role +Integrate results from all workers to generate final output +''' + }, + "prompts": { + "__description__": "Prompts for each agent" + }, + "docs": { + "__description__": "Design documents", + "design.md": "# Orchestrator-Workers Workflow\n\n## Pattern: Orchestrator-Workers\nDynamically decompose tasks and dispatch to workers\n" + }, + "config": { + "__description__": "Configuration files" + } + } + }, + "evaluator-optimizer": { + "description": "Evaluation-improvement loop pattern", + "structure": { + "agents": { + "__description__": "Generator and evaluator", + "generator_agent.md": '''# Generator Agent + +## Role +Generate content + +## Input +- request: Generation request +- feedback: Previous feedback (if any) + +## Output +- content: Generated content +''', + "evaluator_agent.md": '''# Evaluator Agent + +## Role +Evaluate generated content + +## Criteria +- [ ] Criterion 1 +- [ ] Criterion 2 +- [ ] Criterion 3 + +## Output +- passed: true/false +- feedback: Improvement points (on failure) +''' + }, + "prompts": { + "__description__": "Generation and evaluation prompts" + }, + "docs": { + "__description__": "Design documents", + "design.md": '''# Evaluator-Optimizer Workflow + +## Pattern: Evaluator-Optimizer +Generate → Evaluate → Improve loop + +## Flow +```mermaid +graph TD + A[Input] --> B[Generator] + B --> C[Output] + C --> D[Evaluator] + D -->|Not Good| E[Feedback] + E --> B + D -->|Good| F[Final Output] +``` + +## Loop Control +- max_iterations: 5 +- on_max_reached: return_best +''' + }, + "config": { + "__description__": "Configuration files", + "loop_config.yaml": '''# Evaluator-Optimizer Loop Configuration + +max_iterations: 5 +evaluation_criteria: + - name: criteria_1 + weight: 0.4 + - name: criteria_2 + weight: 0.3 + - name: criteria_3 + weight: 0.3 + +threshold: 0.8 +on_max_reached: return_best # or: fail +''' + } + } + }, + "routing": { + "description": "Routing pattern", + "structure": { + "agents": { + "__description__": "Router and specialized handlers", + "router_agent.md": '''# Router Agent + +## Role +Classify input and route to appropriate handler + +## Categories +- type_a: Route to Handler A +- type_b: Route to Handler B +- type_c: Route to Handler C +''', + "handler_a_agent.md": "# Handler A Agent\n\n## Role\nHandle Type A processing\n", + "handler_b_agent.md": "# Handler B Agent\n\n## Role\nHandle Type B processing\n", + "handler_c_agent.md": "# Handler C Agent\n\n## Role\nHandle Type C processing\n" + }, + "prompts": { + "__description__": "Routing and handler prompts" + }, + "docs": { + "__description__": "Design documents", + "design.md": "# Routing Workflow\n\n## Pattern: Routing\nClassify input and route to specialized processing\n" + }, + "config": { + "__description__": "Configuration files" + } + } + } +} + + +def create_structure(base_path: Path, structure: dict, workflow_name: str): + """Recursively create directory structure""" + for name, content in structure.items(): + if name == "__description__": + continue + + path = base_path / name + + if isinstance(content, dict): + # Create directory + path.mkdir(parents=True, exist_ok=True) + # Create .gitkeep for empty directory + if not any(k for k in content.keys() if k != "__description__"): + (path / ".gitkeep").touch() + else: + create_structure(path, content, workflow_name) + else: + # Create file + file_content = content.format( + workflow_name=workflow_name, + name=workflow_name, + role_description="", + context="", + task_description="", + output_format="" + ) + path.write_text(file_content, encoding="utf-8") + + +def scaffold_workflow(name: str, pattern: str = "basic", output_path: str = ".", include_instructions: bool = False): + """Generate workflow directory structure + + Args: + name: Workflow name + pattern: Workflow pattern (basic, prompt-chaining, etc.) + output_path: Output directory + include_instructions: If True, generate extended instruction templates + """ + + if pattern not in PATTERNS: + print(f"❌ Unknown pattern: {pattern}") + print(f" Available patterns: {', '.join(PATTERNS.keys())}") + return False + + pattern_info = PATTERNS[pattern] + base_path = Path(output_path) / name + + if base_path.exists(): + print(f"❌ Directory already exists: {base_path}") + return False + + print(f"🚀 Creating workflow: {name}") + print(f" Pattern: {pattern} - {pattern_info['description']}") + print(f" Location: {base_path.absolute()}") + print() + + # Create directory structure + base_path.mkdir(parents=True, exist_ok=True) + create_structure(base_path, pattern_info["structure"], name) + + # Create .github directory and instructions + github_dir = base_path / ".github" + github_dir.mkdir(parents=True, exist_ok=True) + instructions_dir = github_dir / "instructions" + instructions_dir.mkdir(parents=True, exist_ok=True) + + # Generate common templates + for filename, template in COMMON_TEMPLATES.items(): + file_path = base_path / filename + file_path.parent.mkdir(parents=True, exist_ok=True) + + content = template.format( + workflow_name=name, + pattern=pattern, + pattern_description=pattern_info['description'], + purpose="your use case", + agent_role="Describe your agent's role here", + context="", + task_description="", + input_data="", + output_format="", + good_example="", + bad_example="" + ) + file_path.write_text(content, encoding="utf-8") + + # Generate extended instructions if requested + if include_instructions: + print("📋 Generating extended instructions...") + for filename, template in EXTENDED_INSTRUCTIONS.items(): + file_path = base_path / filename + file_path.parent.mkdir(parents=True, exist_ok=True) + file_path.write_text(template, encoding="utf-8") + + # Generate README.md + readme_content = f'''# {name} + +## Overview +Generated with `agentic-workflow-guide` skill. + +## Pattern +**{pattern}** - {pattern_info['description']} + +## Directory Structure +``` +{name}/ +├── Agent.md # Workflow overview +├── .github/ +│ ├── copilot-instructions.md # Copilot instructions +│ └── instructions/ # Individual instructions +│ ├── workflow.instructions.md +│ ├── agents.instructions.md +│ └── prompts.instructions.md +''' + + for dir_name, dir_content in pattern_info["structure"].items(): + if dir_name != "__description__": + desc = dir_content.get("__description__", "") + readme_content += f"├── {dir_name}/ # {desc}\n" + + readme_content += '''``` + +## Quick Start + +1. Edit **Agent.md** to describe your workflow overview +2. Create agent definitions in **agents/** +3. Customize prompt templates in **prompts/** +4. Document design in **docs/design.md** +5. Adjust settings in **config/** + +## Files + +| File | Purpose | +|------|---------| +| `Agent.md` | Workflow overview and agent list | +| `.github/copilot-instructions.md` | Development guidelines for GitHub Copilot | +| `.github/instructions/*.instructions.md` | File pattern-specific rules | +| `prompts/system_prompt.md` | System prompt for agents | +| `prompts/task_prompt.md` | Task prompt template | +| `prompts/error_handling_prompt.md` | Error handling prompt | + +## Design Principles + +This workflow should follow: + +- **SSOT** - Single Source of Truth +- **SRP** - Single Responsibility Principle +- **Fail Fast** - Early error detection +- **Iterative Refinement** - Small iterations +- **Feedback Loop** - Verify results + +See: `agentic-workflow-guide` for full checklist. + +## References + +- [agentic-workflow-guide](https://github.com/aktsmm/Agent-Skills/tree/master/agentic-workflow-guide) +- [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) +''' + + (base_path / "README.md").write_text(readme_content, encoding="utf-8") + + print("✅ Created structure:") + print(f" 📄 Agent.md") + print(f" 📄 README.md") + print(f" 📁 .github/") + print(f" 📄 copilot-instructions.md") + print(f" 📁 instructions/") + print(f" 📄 workflow.instructions.md") + print(f" 📄 agents.instructions.md") + print(f" 📄 prompts.instructions.md") + for dir_name in pattern_info["structure"].keys(): + if dir_name != "__description__": + print(f" 📁 {dir_name}/") + + print(f"\n✅ Workflow '{name}' scaffolded successfully!") + print("\nGenerated files:") + print(" 📄 Agent.md - Workflow overview") + print(" 📄 .github/copilot-instructions.md - Copilot instructions") + print(" 📄 .github/instructions/*.instructions.md - Individual rules") + print(" 📄 prompts/*.md - Prompt templates") + print("\nNext steps:") + print("1. Edit Agent.md to describe your workflow") + print("2. Customize agents/ for your use case") + print("3. Update prompts/ with your prompts") + print("4. Review with agentic-workflow-guide checklist") + + return True + + +def main(): + parser = argparse.ArgumentParser( + description="Generate agent workflow directory structure" + ) + parser.add_argument("name", nargs="?", help="Workflow name") + parser.add_argument( + "--pattern", "-p", + choices=list(PATTERNS.keys()), + default="basic", + help="Workflow pattern (default: basic)" + ) + parser.add_argument( + "--path", + default=".", + help="Output directory (default: current directory)" + ) + parser.add_argument( + "--list-patterns", + action="store_true", + help="List available patterns" + ) + parser.add_argument( + "--include-instructions", "-i", + action="store_true", + help="Include extended instruction templates (agent-design, git, security, etc.)" + ) + + args = parser.parse_args() + + if args.list_patterns: + print("Available patterns:\n") + for name, info in PATTERNS.items(): + print(f" {name}") + print(f" {info['description']}") + print() + print("Extended instructions (use --include-instructions):") + print(" - agent-design.instructions.md") + print(" - communication.instructions.md") + print(" - git.instructions.md") + print(" - terminal.instructions.md") + print(" - security.instructions.md") + print(" - microsoft-docs.instructions.md") + return + + if not args.name: + parser.print_help() + return + + scaffold_workflow(args.name, args.pattern, args.path, args.include_instructions) + + +if __name__ == "__main__": + main()