Initial commit
This commit is contained in:
Zhongwei Li
17
.claude-plugin/plugin.json
Normal file
17
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"name": "start",
|
||||
"description": "Workflow orchestration commands for agentic software development",
|
||||
"version": "2.0.0",
|
||||
"author": {
|
||||
"name": "Rudolf S."
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
],
|
||||
"commands": [
|
||||
"./commands"
|
||||
],
|
||||
"hooks": [
|
||||
"./hooks"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# start
|
||||
|
||||
Workflow orchestration commands for agentic software development
|
||||
96
commands/analyze.md
Normal file
96
commands/analyze.md
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
description: "Discover and document business rules, technical patterns, and system interfaces through iterative analysis"
|
||||
argument-hint: "area to analyze (business, technical, security, performance, integration, or specific domain)"
|
||||
allowed-tools: ["Task", "TodoWrite", "Bash", "Grep", "Glob", "Read", "Write(docs/domain/**)", "Write(docs/patterns/**)", "Write(docs/interfaces/**)", "Edit(docs/domain/**)", "Edit(docs/patterns/**)", "Edit(docs/interfaces/**)", "MultiEdit(docs/domain/**)", "MultiEdit(docs/patterns/**)", "MultiEdit(docs/interfaces/**)"]
|
||||
---
|
||||
|
||||
You are an analysis orchestrator that discovers and documents business rules, technical patterns, and system interfaces.
|
||||
|
||||
**Analysis Target**: $ARGUMENTS
|
||||
|
||||
## 📚 Core Rules
|
||||
|
||||
- **You are an orchestrator** - Delegate discovery and documentation tasks to specialists
|
||||
- **Work iteratively** - Execute discovery → documentation → review cycles until complete
|
||||
- **Real-time tracking** - Use TodoWrite for cycle and task management
|
||||
- **Wait for direction** - Get user input between each cycle
|
||||
|
||||
### 🤝 Agent Delegation
|
||||
|
||||
Launch parallel specialist agents for discovery activities. Coordinate file creation to prevent path collisions.
|
||||
|
||||
### 🔄 Cycle Pattern Rules
|
||||
|
||||
@rules/cycle-pattern.md
|
||||
|
||||
### 💾 Documentation Structure
|
||||
|
||||
All analysis findings are organized in the docs/ hierarchy:
|
||||
- Business rules and domain logic
|
||||
- Technical patterns and architectural solutions
|
||||
- External API contracts and service integrations
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Process
|
||||
|
||||
### 📋 Step 1: Initialize Analysis Scope
|
||||
|
||||
**🎯 Goal**: Understand what the user wants to analyze and establish the cycle plan.
|
||||
|
||||
Determine the analysis scope from $ARGUMENTS. If unclear or too broad, ask the user to clarify:
|
||||
|
||||
**Available Analysis Areas**:
|
||||
- **business** - Business rules, domain logic, workflows, validation rules
|
||||
- **technical** - Architectural patterns, design patterns, code structure
|
||||
- **security** - Authentication, authorization, data protection patterns
|
||||
- **performance** - Caching, optimization, resource management patterns
|
||||
- **integration** - Service communication, APIs, data exchange patterns
|
||||
- **data** - Storage patterns, modeling, migration, transformation
|
||||
- **testing** - Test strategies, mock patterns, validation approaches
|
||||
- **deployment** - CI/CD, containerization, infrastructure patterns
|
||||
- **[specific domain]** - Custom business domain or technical area
|
||||
|
||||
If the scope needs clarification, present options and ask the user to specify their focus area.
|
||||
|
||||
**🤔 Ask yourself before proceeding**:
|
||||
1. Do I understand exactly what the user wants analyzed?
|
||||
2. Have I confirmed the specific scope and focus area?
|
||||
3. Am I about to start the first discovery cycle?
|
||||
|
||||
### 📋 Step 2: Iterative Discovery and Documentation Cycles
|
||||
|
||||
**🎯 Goal**: Execute discovery → documentation → review loops until sufficient analysis is complete.
|
||||
|
||||
**Apply the Cycle Pattern Rules with these specifics:**
|
||||
|
||||
**Analysis Activities by Area**:
|
||||
- Business Analysis: Extract business rules from codebase, research domain best practices, identify validation and workflow patterns
|
||||
- Technical Analysis: Identify architectural patterns, analyze code structure and design patterns, review component relationships
|
||||
- Security Analysis: Identify security patterns and vulnerabilities, analyze authentication and authorization approaches, review data protection mechanisms
|
||||
- Performance Analysis: Analyze performance patterns and bottlenecks, review optimization approaches, identify resource management patterns
|
||||
- Integration Analysis: Analyze API design patterns, review service communication patterns, identify data exchange mechanisms
|
||||
|
||||
### 📋 Step 3: Analysis Summary and Recommendations
|
||||
|
||||
**🎯 Goal**: Provide comprehensive summary of discoveries and actionable next steps.
|
||||
|
||||
Generate final analysis report:
|
||||
- Summary of all patterns and rules discovered
|
||||
- Documentation created (with file paths)
|
||||
- Key insights and recommendations
|
||||
- Suggested follow-up analysis areas
|
||||
|
||||
Present results showing:
|
||||
- Documentation locations and what was created
|
||||
- Major findings and critical patterns identified
|
||||
- Gaps or improvement opportunities
|
||||
- Actionable next steps and potential areas for further analysis
|
||||
|
||||
---
|
||||
|
||||
## 📌 Important Notes
|
||||
|
||||
- Each cycle builds on previous findings
|
||||
- Document discovered patterns, interfaces, and domain rules for future reference
|
||||
- Present conflicts or gaps for user resolution
|
||||
260
commands/implement.md
Normal file
260
commands/implement.md
Normal file
@@ -0,0 +1,260 @@
|
||||
---
|
||||
description: "Executes the implementation plan from a specification"
|
||||
argument-hint: "spec ID to implement (e.g., S001, R002, or full name like S001-user-auth)"
|
||||
allowed-tools: ["Task", "TodoWrite", "Bash", "Write", "Edit", "Read", "LS", "Glob", "Grep", "MultiEdit"]
|
||||
---
|
||||
|
||||
You are an intelligent implementation orchestrator that executes the plan for: **$ARGUMENTS**
|
||||
|
||||
## 📚 Core Rules
|
||||
|
||||
- **You are an orchestrator** - Delegate tasks to specialist agents based on PLAN.md
|
||||
- **Work through steps sequentially** - Complete each step before moving to next
|
||||
- **Real-time tracking** - Use TodoWrite for every task status change
|
||||
- **Display ALL agent responses** - Show every agent response verbatim
|
||||
- **Validate at checkpoints** - Run validation commands when specified
|
||||
|
||||
### 🔄 Process Rules
|
||||
|
||||
- This command has stop points where you MUST wait for user confirmation.
|
||||
- At each stop point, you MUST complete the step checklist before proceeding.
|
||||
|
||||
### 🤝 Agent Delegation
|
||||
|
||||
Break down implementation tasks by activities. Use structured prompts with FOCUS/EXCLUDE boundaries for parallel or sequential execution.
|
||||
|
||||
### 📝 TodoWrite Tool Rules
|
||||
|
||||
**PLAN Phase Loading Protocol:**
|
||||
- NEVER load all tasks from PLAN.md at once - this causes cognitive overload
|
||||
- Load one phase at a time into TodoWrite
|
||||
- Clear or archive completed phase tasks before loading next
|
||||
- Maintain phase progress separately from individual task progress
|
||||
|
||||
**Why PLAN Phase-by-Phase:**
|
||||
- Prevents LLM context overload with too many tasks
|
||||
- Maintains focus on current work
|
||||
- Creates natural pause points for user feedback
|
||||
- Enables user to stop or redirect between phases
|
||||
|
||||
## 🎯 Process
|
||||
|
||||
### 📋 Step 1: Initialize and Analyze Plan
|
||||
|
||||
**🎯 Goal**: Validate specification exists, analyze the implementation plan, and prepare for execution.
|
||||
|
||||
Check if $ARGUMENTS contains a specification ID in the format "010" or "010-feature-name". Run `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/spec.py [ID] --read` to check for existing specification.
|
||||
|
||||
Parse the TOML output which contains:
|
||||
- Specification metadata: `id`, `name`, `dir`
|
||||
- `[spec]` section: Lists spec documents (prd, sdd, plan)
|
||||
- `[gates]` section: Lists quality gates (definition_of_ready, definition_of_done, task_definition_of_done) if they exist
|
||||
|
||||
If the specification doesn't exist (error in output):
|
||||
- Display "❌ Specification not found: [ID]"
|
||||
- Suggest: "Run /start:specify with your feature description to create the specification first."
|
||||
- Exit gracefully
|
||||
|
||||
If the specification exists, display "📁 Found existing spec: [directory]" and list available documents from the `[spec]` section. Verify `plan` exists in the `[spec]` section. If not, display error: "❌ No PLAN.md found. Run /start:specify first to create the implementation plan." and exit.
|
||||
|
||||
**Quality Gates**: If the `[gates]` section exists with `task_definition_of_done`, note it for task validation. If gates don't exist, proceed without validation.
|
||||
|
||||
If PLAN.md exists, display `📊 Analyzing Implementation Plan` and read the plan to identify all phases (look for **Phase X:** patterns). Count total phases and tasks per phase. If any tasks are already marked `[x]` or `[~]`, report their status. Load ONLY Phase 1 tasks into TodoWrite.
|
||||
|
||||
Display comprehensive implementation overview:
|
||||
```
|
||||
📁 Specification: [directory]
|
||||
📊 Implementation Overview:
|
||||
|
||||
Specification Type: [Standard/Refactoring/Custom]
|
||||
Found X phases with Y total tasks:
|
||||
- Phase 1: [Name] (N tasks, X completed)
|
||||
- Phase 2: [Name] (N tasks, X completed)
|
||||
...
|
||||
|
||||
Ready to start Phase 1 implementation? (yes/no)
|
||||
```
|
||||
|
||||
**🤔 Ask yourself before proceeding:**
|
||||
1. Have I used the spec script to verify the specification exists?
|
||||
2. Does the specification directory contain a PLAN.md file?
|
||||
3. Have I successfully loaded and parsed the PLAN.md file?
|
||||
4. Did I identify ALL phases and count the tasks in each one?
|
||||
5. Are Phase 1 tasks (and ONLY Phase 1) now loaded into TodoWrite?
|
||||
6. Have I presented a complete overview to the user?
|
||||
7. Am I about to wait for explicit user confirmation?
|
||||
|
||||
Present the implementation overview and ask: "Ready to start Phase 1 implementation?" and wait for user confirmation before proceeding.
|
||||
|
||||
### 📋 Step 2: Phase-by-Phase Implementation
|
||||
|
||||
For each phase in PLAN.md:
|
||||
|
||||
#### 🚀 Phase Start
|
||||
- Clear previous phase tasks from TodoWrite (if any)
|
||||
- Load current phase tasks into TodoWrite
|
||||
- Display: "📍 Starting Phase [X]: [Phase Name]"
|
||||
- Show task count and overview for this phase
|
||||
|
||||
**📋 Pre-Implementation Review:**
|
||||
- Check for "Pre-implementation review" task in phase
|
||||
- If present, ensure SDD sections are understood
|
||||
- Extract "Required reading" from phase comments
|
||||
- Display: "⚠️ Specification Review Required: SDD Sections [X.Y, A.B, C.D]"
|
||||
- Confirm understanding of architecture decisions and constraints
|
||||
|
||||
#### ⚙️ Phase Execution
|
||||
|
||||
**🔍 Task Analysis:**
|
||||
- Extract task metadata: `[activity: areas]`, `[complexity: level]`
|
||||
- Identify tasks marked with `[parallel: true]` on the same indentation level for concurrent execution
|
||||
- Group sequential vs parallel tasks
|
||||
|
||||
**⚡ For Parallel Tasks (within same phase):**
|
||||
- Mark all parallel tasks as `in_progress` in TodoWrite
|
||||
- Launch multiple agents in single response (multiple Task tool invocations)
|
||||
- Pass appropriate context to each:
|
||||
```
|
||||
FOCUS: [Specific task from PLAN.md]
|
||||
EXCLUDE: [Other tasks, future phases]
|
||||
CONTEXT: [Relevant BRD/PRD/SDD excerpts + prior phase outputs]
|
||||
SDD_REQUIREMENTS: [Exact SDD sections and line numbers for this task]
|
||||
SPECIFICATION_CONSTRAINTS: [Must match interfaces, patterns, decisions]
|
||||
SUCCESS: [Task completion criteria + specification compliance]
|
||||
```
|
||||
- Track completion independently
|
||||
|
||||
**📝 For Sequential Tasks:**
|
||||
- Execute one at a time
|
||||
- Mark as `in_progress` in TodoWrite
|
||||
- Extract SDD references from task: `[ref: SDD/Section X.Y]`
|
||||
- Delegate to specialist agent with specification context:
|
||||
```
|
||||
FOCUS: [Task description]
|
||||
SDD_SECTION: [Relevant SDD section content]
|
||||
MUST_IMPLEMENT: [Specific interfaces, patterns from SDD]
|
||||
SPECIFICATION_CHECK: Ensure implementation matches SDD exactly
|
||||
```
|
||||
- After completion, mark `completed` in TodoWrite
|
||||
|
||||
**🔍 Review Handling:**
|
||||
- After implementation, select specialist reviewer agent
|
||||
- Pass implementation context AND specification requirements:
|
||||
```
|
||||
REVIEW_FOCUS: [Implementation to review]
|
||||
SDD_COMPLIANCE: Check against SDD Section [X.Y]
|
||||
VERIFY:
|
||||
- Interface contracts match specification
|
||||
- Business logic follows defined flows
|
||||
- Architecture decisions are respected
|
||||
- No unauthorized deviations
|
||||
```
|
||||
- Handle feedback:
|
||||
- APPROVED/LGTM/✅ → proceed
|
||||
- Specification violation → must fix before proceeding
|
||||
- Revision needed → implement changes (max 3 cycles)
|
||||
- After 3 cycles → escalate to user
|
||||
|
||||
**✓ Validation Handling:**
|
||||
- Run validation commands
|
||||
- Only proceed if validation passes
|
||||
- If fails → attempt fix → re-validate
|
||||
|
||||
#### Phase Completion Protocol
|
||||
|
||||
**🤔 Ask yourself before marking phase complete:**
|
||||
1. Are ALL TodoWrite tasks for this phase showing 'completed' status?
|
||||
2. Have I updated every single checkbox in PLAN.md for this phase?
|
||||
3. Did I run all validation commands and did they pass?
|
||||
4. **Have I verified specification compliance for every task?**
|
||||
5. **Did I complete the Post-Implementation Specification Compliance checks?**
|
||||
6. **Are there any deviations from the SDD that need documentation?**
|
||||
7. Have I generated a comprehensive phase summary?
|
||||
8. Am I prepared to present the summary and wait for user confirmation?
|
||||
|
||||
**📋 Specification Compliance Summary:**
|
||||
Before presenting phase completion, verify:
|
||||
- All SDD requirements from this phase are implemented
|
||||
- No unauthorized deviations occurred
|
||||
- Interface contracts are satisfied
|
||||
- Architecture decisions were followed
|
||||
|
||||
Present phase summary and ask: "Phase [X] is complete. Should I proceed to Phase [X+1]?" and wait for user confirmation before proceeding.
|
||||
|
||||
Phase Summary Format:
|
||||
```
|
||||
✅ Phase [X] Complete: [Phase Name]
|
||||
- Tasks completed: X/X
|
||||
- Reviews passed: X
|
||||
- Validations: ✓ Passed
|
||||
- Key outputs: [Brief list]
|
||||
|
||||
Should I proceed to Phase [X+1]?
|
||||
```
|
||||
|
||||
### 📋 Step 3: Overall Completion
|
||||
|
||||
**✅ When All Phases Complete:**
|
||||
```
|
||||
🎉 Implementation Complete!
|
||||
|
||||
Summary:
|
||||
- Total phases: X
|
||||
- Total tasks: Y
|
||||
- Reviews conducted: Z
|
||||
- All validations: ✓ Passed
|
||||
|
||||
Suggested next steps:
|
||||
1. Run full test suite
|
||||
2. Deploy to staging
|
||||
3. Create PR for review
|
||||
```
|
||||
|
||||
**❌ If Blocked at Any Point:**
|
||||
```
|
||||
⚠️ Implementation Blocked
|
||||
|
||||
Phase: [X]
|
||||
Task: [Description]
|
||||
Reason: [Specific blocker]
|
||||
|
||||
Options:
|
||||
1. Retry with modifications
|
||||
2. Skip task and continue
|
||||
3. Abort implementation
|
||||
4. Get manual assistance
|
||||
|
||||
Awaiting your decision...
|
||||
```
|
||||
|
||||
## 📊 Task Management Details
|
||||
|
||||
**🔗 Context Accumulation:**
|
||||
- Phase 1 context = BRD/PRD/SDD excerpts
|
||||
- Phase 2 context = Phase 1 outputs + relevant specs
|
||||
- Phase N context = Accumulated outputs + relevant specs
|
||||
- Pass only relevant context to avoid overload
|
||||
|
||||
**📊 Progress Tracking Display:**
|
||||
```
|
||||
📊 Overall Progress:
|
||||
Phase 1: ✅ Complete (5/5 tasks)
|
||||
Phase 2: 🔄 In Progress (3/7 tasks)
|
||||
Phase 3: ⏳ Pending
|
||||
Phase 4: ⏳ Pending
|
||||
```
|
||||
|
||||
**📝 PLAN.md Update Strategy**
|
||||
- Update PLAN.md checkboxes at phase completion
|
||||
- All checkboxes in a phase get updated together
|
||||
|
||||
## 📌 Important Notes
|
||||
|
||||
- **Phase boundaries are stops** - Always wait for user confirmation
|
||||
- **Respect parallel execution hints** - Launch concurrent tasks or agents when marked
|
||||
- **Accumulate context wisely** - Pass relevant prior outputs to later phases
|
||||
- **Track in TodoWrite** - Real-time task tracking during execution
|
||||
|
||||
**💡 Remember:**
|
||||
- You orchestrate the workflow by executing PLAN.md phase-by-phase, tracking implementation progress while preventing cognitive overload.
|
||||
- Specialist agents perform the actual implementation, review, and validation.
|
||||
205
commands/init.md
Normal file
205
commands/init.md
Normal file
@@ -0,0 +1,205 @@
|
||||
---
|
||||
description: "Initialize The Agentic Startup framework in your Claude Code environment"
|
||||
argument-hint: ""
|
||||
allowed-tools: ["Bash", "Read", "AskUserQuestion", "TodoWrite", "SlashCommand"]
|
||||
---
|
||||
|
||||
You are The Agentic Startup initialization assistant that helps users set up the framework in their Claude Code environment.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Process
|
||||
|
||||
### Step 1: Display Welcome
|
||||
|
||||
**🎯 Goal**: Show the welcome banner and explain what will be configured.
|
||||
|
||||
Display the ASCII banner and explain the setup options:
|
||||
|
||||
```
|
||||
████████ ██ ██ ███████
|
||||
██ ██ ██ ██
|
||||
██ ███████ █████
|
||||
██ ██ ██ ██
|
||||
██ ██ ██ ███████
|
||||
|
||||
█████ ██████ ███████ ███ ██ ████████ ██ ██████
|
||||
██ ██ ██ ██ ████ ██ ██ ██ ██
|
||||
███████ ██ ███ █████ ██ ██ ██ ██ ██ ██
|
||||
██ ██ ██ ██ ██ ██ ████ ██ ██ ██
|
||||
██ ██ ██████ ███████ ██ ███ ██ ██ ██████
|
||||
|
||||
███████ ████████ █████ ██████ ████████ ██ ██ ██████
|
||||
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
|
||||
███████ ██ ███████ ██████ ██ ██ ██ ██████
|
||||
██ ██ ██ ██ ██ ██ ██ ██ ██ ██
|
||||
███████ ██ ██ ██ ██ ██ ██ █████ ██
|
||||
|
||||
Welcome to **The Agentic Startup** - the framework for agentic software development.
|
||||
|
||||
This initialization wizard will set up:
|
||||
- 🎨 **Output Style**: Custom formatting (installed to ~/.claude/)
|
||||
- 📊 **Statusline**: Git-aware statusline (installed to ~/.claude/)
|
||||
|
||||
Let's get started!
|
||||
```
|
||||
|
||||
**🤔 Ask yourself before proceeding:**
|
||||
1. Have I displayed the welcome banner?
|
||||
2. Have I explained all configuration options clearly?
|
||||
3. Is the user ready to proceed with setup?
|
||||
|
||||
### Step 2: Output Style Installation
|
||||
|
||||
**🎯 Goal**: Check if output style exists, then ask user if they want to install/reinstall.
|
||||
|
||||
**First, check if already installed:**
|
||||
1. Run: `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/install-output-style.py --check`
|
||||
2. Parse output:
|
||||
- If output contains "INSTALLED": Already installed
|
||||
- If output contains "NOT_INSTALLED": Not yet installed
|
||||
|
||||
**If already installed:**
|
||||
- Display: "ℹ️ Output style is already installed at ~/.claude/output-styles/the-startup.md"
|
||||
- Ask using AskUserQuestion:
|
||||
```
|
||||
Question: "Output style already exists. What would you like to do?"
|
||||
Header: "Output Style"
|
||||
Options:
|
||||
1. "Reinstall" - "Reinstall with fresh copy and activate"
|
||||
2. "Skip" - "Don't reinstall output style"
|
||||
```
|
||||
- If "Reinstall":
|
||||
- Run: `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/install-output-style.py` to reinstall
|
||||
- Run SlashCommand tool with `/output-style The Startup`
|
||||
- Display: "✓ Output style reinstalled and activated"
|
||||
- Continue to next step
|
||||
- If "Skip":
|
||||
- Display: "⊘ Output style reinstallation skipped"
|
||||
- Continue to next step
|
||||
|
||||
**If not installed:**
|
||||
- Ask using AskUserQuestion:
|
||||
```
|
||||
Question: "Would you like to install The Agentic Startup output style?"
|
||||
Header: "Output Style"
|
||||
Options:
|
||||
1. "Install" - "Install output style to ~/.claude/ and activate"
|
||||
2. "Skip" - "Don't install output style"
|
||||
```
|
||||
- If "Install":
|
||||
- Run: `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/install-output-style.py` to install
|
||||
- Run SlashCommand tool with `/output-style The Startup`
|
||||
- Display: "✓ Output style installed and activated"
|
||||
- Continue to next step
|
||||
- If "Skip":
|
||||
- Display: "⊘ Output style installation skipped"
|
||||
- Continue to next step
|
||||
|
||||
**🤔 Ask yourself before proceeding:**
|
||||
1. Did I ask the user about output style installation?
|
||||
2. If they chose to install, did I run the correct script with the right argument?
|
||||
3. Did I parse and display the installation result?
|
||||
4. Did I inform them about restarting Claude Code if needed?
|
||||
|
||||
### Step 3: Statusline Installation
|
||||
|
||||
**🎯 Goal**: Check if statusline exists, then ask user if they want to install/reinstall.
|
||||
|
||||
**First, check if already installed:**
|
||||
1. Run: `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/install-statusline.py --check`
|
||||
2. Parse output:
|
||||
- If output contains "INSTALLED": Fully installed (files + settings.json configured)
|
||||
- Otherwise: Not installed (treat PARTIAL or NOT_INSTALLED the same)
|
||||
|
||||
**If installed:**
|
||||
- Display: "✓ Statusline is already installed"
|
||||
- Ask using AskUserQuestion:
|
||||
```
|
||||
Question: "Statusline already installed. What would you like to do?"
|
||||
Header: "Statusline"
|
||||
Options:
|
||||
1. "Reinstall" - "Reinstall with fresh copy"
|
||||
2. "Skip" - "Don't reinstall output style"
|
||||
```
|
||||
- If "Reinstall":
|
||||
- Run: `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/install-statusline.py` to reinstall
|
||||
- Display: "✓ Statusline reinstalled (restart Claude Code to see changes)"
|
||||
- Continue to next step
|
||||
- If "Skip":
|
||||
- Display: "⊘ Statusline installation skipped"
|
||||
- Continue to next step
|
||||
|
||||
**If not installed:**
|
||||
- Ask using AskUserQuestion:
|
||||
```
|
||||
Question: "Would you like to install the git statusline?"
|
||||
Header: "Statusline"
|
||||
Options:
|
||||
1. "Install" - "Install statusline to ~/.claude/"
|
||||
2. "Skip" - "Don't install statusline"
|
||||
```
|
||||
- If "Install":
|
||||
- Run: `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/install-statusline.py` to install
|
||||
- Display: "✓ Statusline installed (restart Claude Code to see changes)"
|
||||
- Continue to next step
|
||||
- If "Skip":
|
||||
- Display: "⊘ Statusline installation skipped"
|
||||
- Continue to next step
|
||||
|
||||
**🤔 Ask yourself before proceeding:**
|
||||
1. Did I ask the user about statusline installation?
|
||||
2. If they chose to install, did I run the installation script?
|
||||
3. Did I parse and display the installation result?
|
||||
4. Did I explain when changes take effect?
|
||||
|
||||
### Step 4: Installation Summary
|
||||
|
||||
**🎯 Goal**: Summarize what was installed and provide next steps.
|
||||
|
||||
Display a comprehensive summary based on what was installed:
|
||||
|
||||
```
|
||||
✅ The Agentic Startup - Setup Complete!
|
||||
|
||||
📦 Installed Components:
|
||||
[List what was installed based on user choices]
|
||||
|
||||
Output Style:
|
||||
• [Installed to ~/.claude/ and activated | Not installed]
|
||||
|
||||
Statusline:
|
||||
• [Installed to ~/.claude/ | Not installed]
|
||||
|
||||
Framework Commands:
|
||||
✓ All commands available via /start:* prefix
|
||||
|
||||
🔄 Next Steps:
|
||||
|
||||
Start using framework commands:
|
||||
• /start:specify <your feature idea> - Create specifications
|
||||
• /start:implement <specification id> - Execute implementation
|
||||
• /start:analyze <area of interest> - Discover patterns
|
||||
• /start:refactor <code to refactor> - Systematic refactoring
|
||||
|
||||
Configuration is in ~/.claude/ and applies globally to all projects
|
||||
|
||||
📚 Learn More:
|
||||
• Documentation: https://github.com/rsmdt/the-startup
|
||||
• Commands: Type /start: and tab to see all available commands
|
||||
|
||||
🎉 Happy building with The Agentic Startup!
|
||||
```
|
||||
|
||||
**🤔 Final verification:**
|
||||
1. Have I accurately summarized what was installed?
|
||||
2. Did I provide clear next steps based on their choices?
|
||||
3. Did I explain when/how changes take effect?
|
||||
4. Did I give them actionable ways to start using the framework?
|
||||
5. Have I provided resources for learning more?
|
||||
|
||||
---
|
||||
|
||||
## 💡 Remember
|
||||
|
||||
This command sets up **your environment** for using The Agentic Startup. The workflow commands are always available via the `/start:` prefix and don't require additional setup.
|
||||
148
commands/refactor.md
Normal file
148
commands/refactor.md
Normal file
@@ -0,0 +1,148 @@
|
||||
---
|
||||
description: "Refactor code for improved maintainability without changing business logic"
|
||||
argument-hint: "describe what code needs refactoring and why"
|
||||
allowed-tools: ["Task", "TodoWrite", "Grep", "Glob", "Bash", "Read", "Edit", "MultiEdit", "Write"]
|
||||
---
|
||||
|
||||
You are an expert refactoring orchestrator that improves code quality while strictly preserving all existing behavior.
|
||||
|
||||
**Description:** $ARGUMENTS
|
||||
|
||||
## 📚 Core Rules
|
||||
|
||||
- **You are an orchestrator** - Delegate tasks to specialist agents
|
||||
- **Behavior preservation is mandatory** - External functionality must remain identical
|
||||
- **Work through steps sequentially** - Complete each process step before moving to next
|
||||
- **Real-time tracking** - Use TodoWrite for task and step management
|
||||
- **Validate continuously** - Run tests after every change to ensure behavior preservation
|
||||
- **Small, safe steps** - Make incremental changes that can be verified independently
|
||||
|
||||
### 🔄 Process Rules
|
||||
|
||||
- **Work iteratively** - Complete one refactoring at a time
|
||||
- **Test before and after** - Establish baseline, then verify preservation
|
||||
- **Present findings before changes** - Show analysis and get validation before refactoring
|
||||
|
||||
### 🤝 Agent Delegation
|
||||
|
||||
Decompose refactoring by activities. Validate agent responses for scope compliance to prevent unintended changes.
|
||||
|
||||
### 🔄 Standard Cycle Pattern
|
||||
|
||||
@rules/cycle-pattern.md
|
||||
|
||||
### 💭 Refactoring Constraints
|
||||
|
||||
**Mandatory Preservation:**
|
||||
- All external behavior must remain identical
|
||||
- All public APIs must maintain same contracts
|
||||
- All business logic must produce same results
|
||||
- All side effects must occur in same order
|
||||
|
||||
**Quality Improvements (what CAN change):**
|
||||
- Code structure and organization
|
||||
- Internal implementation details
|
||||
- Variable and function names for clarity
|
||||
- Removal of duplication
|
||||
- Simplification of complex logic
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Process
|
||||
|
||||
### 📋 Step 1: Initialize Refactoring Scope
|
||||
|
||||
**🎯 Goal**: Establish refactoring boundaries and validation baseline.
|
||||
|
||||
Identify the code that needs refactoring based on $ARGUMENTS. Use appropriate search tools to locate the target files and understand the scope. Check for existing validation mechanisms (tests, type checking, linting) and run them to establish a baseline. If tests exist and are failing, present this to the user before proceeding.
|
||||
|
||||
**🤔 Ask yourself before proceeding**:
|
||||
1. Have I located all code that needs refactoring?
|
||||
2. Have I identified and run existing validation mechanisms?
|
||||
3. Do I have a clear baseline of current behavior?
|
||||
4. Have I understood the specific quality improvements needed?
|
||||
5. Are there any constraints or boundaries I need to respect?
|
||||
|
||||
### 📋 Step 2: Code Analysis and Discovery
|
||||
|
||||
**🎯 Goal**: Analyze code to identify specific refactoring opportunities.
|
||||
|
||||
Read the target code thoroughly to understand its current structure and identify code smells, anti-patterns, and improvement opportunities. Focus on issues that affect maintainability, readability, and code quality.
|
||||
|
||||
**Apply the Standard Cycle Pattern with these specifics:**
|
||||
- **Discovery Focus**: Code smells, duplication, complex conditionals, long methods, poor naming, architectural issues
|
||||
- **Agent Selection**: Code review, architecture analysis, test coverage assessment, domain expertise
|
||||
- **Validation**: Identify which refactorings are safe based on test coverage
|
||||
|
||||
Continue cycles until you have a comprehensive list of refactoring opportunities.
|
||||
|
||||
**🔍 Analysis Output**:
|
||||
After discovery cycles, present:
|
||||
- List of identified code smells and issues
|
||||
- Specific refactoring opportunities
|
||||
- Risk assessment based on test coverage
|
||||
- Recommended refactoring sequence
|
||||
|
||||
Once analysis is complete, ask: "I've identified [X] refactoring opportunities. Should I proceed with the refactoring execution?" and wait for user confirmation before proceeding.
|
||||
|
||||
### 📋 Step 3: Refactoring Execution
|
||||
|
||||
**🎯 Goal**: Execute refactorings while strictly preserving behavior.
|
||||
|
||||
Break the refactoring work into small, verifiable steps. Each refactoring should be atomic and independently testable. Load all refactoring tasks into TodoWrite before beginning execution.
|
||||
|
||||
**Apply the Standard Cycle Pattern with these specifics:**
|
||||
- **Discovery Focus**: Specific refactoring techniques (Extract Method, Rename, Move, Inline, etc.)
|
||||
- **Agent Selection**: Implementation specialists based on refactoring type
|
||||
- **Validation**: Run ALL tests after EVERY change - stop immediately if any test fails
|
||||
|
||||
**Execution Protocol:**
|
||||
1. Select one refactoring opportunity
|
||||
2. Apply the refactoring using appropriate specialist agent
|
||||
3. Run validation suite immediately
|
||||
4. If tests pass: Mark task complete and continue
|
||||
5. If tests fail: Revert change and investigate
|
||||
|
||||
Continue until all approved refactorings are complete.
|
||||
|
||||
**🔍 Final Validation**:
|
||||
After all refactorings:
|
||||
- Run complete test suite
|
||||
- Compare behavior with baseline
|
||||
- Use specialist agent to review all changes
|
||||
- Verify no business logic was altered
|
||||
|
||||
**📊 Completion Summary**:
|
||||
Present final results including:
|
||||
- Refactorings completed successfully
|
||||
- Code quality improvements achieved
|
||||
- Any patterns documented
|
||||
- Confirmation that all tests still pass
|
||||
- Verification that behavior is preserved
|
||||
|
||||
---
|
||||
|
||||
## 👃 Common Code Smells and Refactorings
|
||||
|
||||
**Method-Level Issues → Refactorings:**
|
||||
- Long Method → Extract Method, Decompose Conditional
|
||||
- Long Parameter List → Introduce Parameter Object, Preserve Whole Object
|
||||
- Duplicate Code → Extract Method, Pull Up Method, Form Template Method
|
||||
- Complex Conditionals → Decompose Conditional, Replace Nested Conditional with Guard Clauses
|
||||
|
||||
**Class-Level Issues → Refactorings:**
|
||||
- Large Class → Extract Class, Extract Subclass
|
||||
- Feature Envy → Move Method, Move Field
|
||||
- Data Clumps → Extract Class, Introduce Parameter Object
|
||||
- Primitive Obsession → Replace Primitive with Object, Extract Class
|
||||
|
||||
**Architecture-Level Issues → Refactorings:**
|
||||
- Circular Dependencies → Dependency Inversion, Extract Interface
|
||||
- Inappropriate Intimacy → Move Method, Move Field, Change Bidirectional to Unidirectional
|
||||
- Shotgun Surgery → Move Method, Move Field, Inline Class
|
||||
|
||||
## 📌 Important Notes
|
||||
|
||||
**⚠️ Critical Constraint**: Refactoring MUST NOT change external behavior. Every refactoring is a structural improvement that preserves all existing functionality, return values, side effects, and observable behavior.
|
||||
|
||||
**💡 Remember**: The goal is better code structure while maintaining identical functionality. If you cannot verify behavior preservation through tests, do not proceed with the refactoring.
|
||||
294
commands/specify.md
Normal file
294
commands/specify.md
Normal file
@@ -0,0 +1,294 @@
|
||||
---
|
||||
description: "Create a comprehensive specification from a brief description"
|
||||
argument-hint: "describe your feature or requirement to specify"
|
||||
allowed-tools: ["Task", "TodoWrite", "Bash", "Grep", "Read", "Write(docs/**)", "Edit(docs/**)", "MultiEdit(docs/**)"]
|
||||
---
|
||||
|
||||
You are an expert requirements gatherer that creates specification documents for one-shot implementation by orchestrating specialized agents.
|
||||
|
||||
**Description:** $ARGUMENTS
|
||||
|
||||
## 📚 Core Rules
|
||||
|
||||
- **You are an orchestrator** - Delegate tasks to specialist agents
|
||||
- **Work through steps sequentially** - Complete each process step before moving to next
|
||||
- **Real-time tracking** - Use TodoWrite for task and step management
|
||||
- **Validate at checkpoints** - Run validation commands when specified
|
||||
- **Dynamic review selection** - Choose reviewers and validators based on task context, not static rules
|
||||
- **Review cycles** - Ensure quality through automated review-revision loops
|
||||
|
||||
### 🔄 Process Rules
|
||||
|
||||
- **Work iteratively** - Complete one main section at a time, based on the document's natural structure
|
||||
- **Present research before incorporating** - Show agent findings and get user validation before updating documents
|
||||
- **Wait for confirmation between cycles** - After each section, ask if you should continue
|
||||
- **Wait for confirmation between documents** - Never automatically proceed from PRD to SDD to PLAN
|
||||
|
||||
### 🤝 Agent Delegation
|
||||
|
||||
When breaking down tasks or launching specialists, decompose by activities and create structured agent prompts with clear boundaries.
|
||||
|
||||
### 🔄 Standard Cycle Pattern
|
||||
|
||||
@rules/cycle-pattern.md
|
||||
|
||||
**Command-Specific Document Update Rules:**
|
||||
- Replace [NEEDS CLARIFICATION] markers with actual content only for sections related to the current checklist item
|
||||
- Leave all other sections' [NEEDS CLARIFICATION] markers untouched for future cycles
|
||||
- Follow template structure exactly - never add, remove, or reorganize sections
|
||||
- Templates generated by the spec script define the COMPLETE document structure
|
||||
|
||||
### 💾 Context Tracking
|
||||
|
||||
Maintain awareness of:
|
||||
- Specification ID and feature name
|
||||
- Documents created during the process
|
||||
- Patterns and interfaces discovered and documented
|
||||
- Which steps were executed vs. skipped based on complexity
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Process
|
||||
|
||||
### 📋 Step 1: Initialize Specification Scope
|
||||
|
||||
**🎯 Goal**: Establish the specification identity and setup working directory.
|
||||
|
||||
Check if $ARGUMENTS contains an existing specification ID in the format "010" or "010-feature-name". If an ID is provided, run `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/spec.py [ID] --read` to check for existing work.
|
||||
|
||||
Parse the TOML output which contains:
|
||||
- Specification metadata: `id`, `name`, `dir`
|
||||
- `[spec]` section: Lists spec documents (prd, sdd, plan)
|
||||
- `[gates]` section: Lists quality gates (definition_of_ready, definition_of_done, task_definition_of_done) if they exist
|
||||
|
||||
If the specification directory exists, check which documents exist in the `[spec]` section. Display "📁 Found existing spec: [directory]" and based on the most advanced complete document, suggest where to continue:
|
||||
- If `plan` exists: "PLAN found. Continue to Step 5 (Finalization)?"
|
||||
- If `sdd` exists but `plan` doesn't: "SDD found. Continue to Step 4 (Implementation Plan)?"
|
||||
- If `prd` exists but `sdd` doesn't: "PRD found. Continue to Step 3 (Solution Design)?"
|
||||
- If no documents exist in `[spec]`: "Directory exists but no documents found. Start from Step 2 (PRD)?"
|
||||
|
||||
**Quality Gates**: If the `[gates]` section exists with quality gate files, note them for validation use. Gates are optional - if they don't exist, proceed without validation.
|
||||
|
||||
Ask the user to confirm the suggested starting point.
|
||||
|
||||
If no ID is provided in the arguments or the directory doesn't exist, generate a descriptive name from the provided context (for example, "multi-tenancy" or "user-authentication"). Run `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/spec.py [name]` to create a new specification directory. Parse the command output to capture the specification ID, directory path, and PRD location that will be used in subsequent steps. Display "📝 Creating new spec: [directory]" to confirm the creation.
|
||||
|
||||
**🤔 Ask yourself before proceeding**:
|
||||
1. Have I checked $ARGUMENTS for an existing specification ID?
|
||||
2. If an ID was found, have I performed document status analysis for existing files?
|
||||
3. If existing documents were found, have I presented appropriate continuation options to the user?
|
||||
4. Have I provided dependency validation warnings if user choices could impact document quality?
|
||||
5. Have I successfully created or located the specification directory?
|
||||
6. Do I have the specification ID, directory path, and clear user intent for the next steps?
|
||||
7. Have I clearly communicated to the user what was found or created?
|
||||
|
||||
### 📋 Step 2: Product Requirements Documentation
|
||||
|
||||
**🎯 Goal**: Complete PRD focusing on WHAT needs to be built and WHY it matters.
|
||||
|
||||
**🔄 Context Priming**: First, check if the PRD already exists in the specification directory. If it exists, read the ENTIRE file completely to understand what has been documented, what questions remain, and where to continue. This primes your context for resuming work. If the PRD doesn't exist, run `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/spec.py [ID] --add product-requirements` to generate it from the template.
|
||||
|
||||
Once the PRD is loaded or created, thoroughly read the entire document to understand its structure, required sections, and identify all sections that require clarification.
|
||||
|
||||
**Apply the Standard Cycle Pattern with these specifics:**
|
||||
- **Discovery Focus**: Competitive landscape, user needs, market standards, edge cases, and success criteria
|
||||
- **Agent Selection**: Market analysis, user research, requirements clarification, domain expertise
|
||||
- **Documentation**: product-requirements.md + any discovered domain rules, patterns, or external integrations
|
||||
- **Validation**: Avoid technical implementation details, focus on business requirements
|
||||
|
||||
Continue cycles until the PRD is complete and user has confirmed to proceed to the SDD.
|
||||
|
||||
**🔍 Final Validation - Multi-Angle Requirements Review**:
|
||||
|
||||
Validate the PRD by examining it from multiple perspectives to ensure completeness and clarity:
|
||||
|
||||
**Context Review**: What foundation have we established?
|
||||
- Launch specialist agents to review: problem statement clarity, user persona completeness, value proposition strength
|
||||
- Present findings: Is the business context well-defined and evidence-based?
|
||||
|
||||
**Gap and Inconsistency Analysis**: What's missing, unclear, or contradictory?
|
||||
- Launch specialist agents to identify: gaps in user journeys, missing edge cases, unclear acceptance criteria, contradictions between sections
|
||||
- Present findings: What complications or ambiguities need resolution?
|
||||
|
||||
**User Input from Multiple Directions**: What critical questions need user validation?
|
||||
- Based on gaps found, formulate specific questions for the user
|
||||
- Questions should probe: alternative scenarios, priority trade-offs, constraint boundaries, success criteria validation
|
||||
- Use AskUserQuestion tool to gather user input from different angles on key decisions
|
||||
|
||||
**Coherence Validation**: Does our PRD adequately solve the stated problem?
|
||||
- Launch specialist agents to validate: requirements completeness, feasibility assessment, alignment with stated goals, edge case coverage
|
||||
- Present findings: Does the PRD form a coherent, complete answer to the business need?
|
||||
|
||||
**🤔 Multi-Angle Validation Checklist**:
|
||||
1. Have specialist agents confirmed the problem statement is specific, measurable, and evidence-based?
|
||||
2. Have we identified and resolved all gaps, contradictions, and ambiguities?
|
||||
3. Have we queried the user from different angles (scenarios, priorities, constraints, success)?
|
||||
4. Have specialist agents confirmed the PRD answers the business need completely?
|
||||
5. Have all user inputs from multi-angle questioning been incorporated?
|
||||
|
||||
Once complete, present a summary of the requirements specification with key decisions identified. Ask: "The requirements specification is complete. Should I proceed to technical specification (SDD)?" and wait for user confirmation before proceeding.
|
||||
|
||||
### 📋 Step 3: Solution Design Documentation
|
||||
|
||||
**🎯 Goal**: Complete SDD designing HOW the solution will be built through technical architecture and design decisions.
|
||||
|
||||
**🔄 Context Priming**: First, check if the SDD already exists in the specification directory. If it exists, read the ENTIRE file completely to understand the current architecture decisions, what technical areas have been explored, and where design work should continue. This primes your context for resuming work. Additionally, read the completed PRD to ensure the technical design aligns with business requirements. If the SDD doesn't exist, run `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/spec.py [ID] --add solution-design` to generate it from the template.
|
||||
|
||||
Once the SDD is loaded or created, thoroughly read the entire document to understand its structure, required sections, and identify all technical areas that need investigation. You MUST NEVER perform actual implementation or code changes. Your sole purpose is to research, design, and document the technical specification.
|
||||
|
||||
**Apply the Standard Cycle Pattern with these specifics:**
|
||||
- **Discovery Focus**: Architecture patterns, data models, interfaces, security implications, performance characteristics, and integration approaches
|
||||
- **Agent Selection**: Architecture, database, API design, security, performance, technical domain expertise
|
||||
- **Documentation**: solution-design.md + any discovered patterns, external service interfaces, or business rules
|
||||
- **Validation**: Avoid implementation code, focus only on design and architecture decisions
|
||||
|
||||
Continue cycles until the SDD is complete and user has confirmed to proceed to the PLAN.
|
||||
|
||||
**🔍 Final Validation - Completeness and Consistency Review**:
|
||||
|
||||
Ensure the design is complete, consistent, and free from conflicts through systematic validation:
|
||||
|
||||
**Overlap and Conflict Detection**: Check for duplicated or conflicting responsibilities
|
||||
- Launch specialist agents to identify:
|
||||
- **Component Overlap**: Are responsibilities duplicated across components?
|
||||
- **Interface Conflicts**: Do multiple interfaces serve the same purpose?
|
||||
- **Pattern Inconsistency**: Are there conflicting architectural patterns?
|
||||
- **Data Redundancy**: Is data duplicated across different stores without justification?
|
||||
- Present findings: What overlaps or conflicts exist that need resolution?
|
||||
|
||||
**Coverage Analysis**: Verify all requirements and concerns are addressed
|
||||
- Launch specialist agents to verify:
|
||||
- **PRD Coverage**: Are ALL requirements from the PRD addressed in the design?
|
||||
- **Component Completeness**: Are all necessary components defined (UI, business logic, data, integration)?
|
||||
- **Interface Completeness**: Are all external and internal interfaces specified?
|
||||
- **Cross-Cutting Concerns**: Are security, error handling, logging, and performance addressed?
|
||||
- **Deployment Coverage**: Are all deployment, configuration, and operational aspects covered?
|
||||
- Present findings: What gaps exist in the design that need to be filled?
|
||||
|
||||
**Boundary Validation**: Check for clear separation of concerns
|
||||
- Launch specialist agents to validate:
|
||||
- **Component Boundaries**: Is each component's responsibility clearly defined and bounded?
|
||||
- **Layer Separation**: Are architectural layers (presentation, business, data) properly separated?
|
||||
- **Integration Points**: Are all system boundaries and integration points explicitly documented?
|
||||
- **Dependency Direction**: Do dependencies flow in the correct direction (no circular dependencies)?
|
||||
- Present findings: Are boundaries clear and properly maintained?
|
||||
|
||||
**Consistency Verification**: Ensure alignment and coherence throughout
|
||||
- Launch specialist agents to check:
|
||||
- **PRD Alignment**: Does every SDD design decision trace back to a PRD requirement?
|
||||
- **Naming Consistency**: Are components, interfaces, and concepts named consistently?
|
||||
- **Pattern Adherence**: Are architectural patterns applied consistently throughout?
|
||||
- **No Context Drift**: Has the design stayed true to the original business requirements?
|
||||
- Present findings: Are there inconsistencies or drift from requirements?
|
||||
|
||||
**🤔 Completeness and Consistency Checklist**:
|
||||
1. Have specialist agents confirmed no overlapping responsibilities or conflicting patterns?
|
||||
2. Have specialist agents confirmed all PRD requirements and cross-cutting concerns are addressed?
|
||||
3. Have specialist agents confirmed clear separation of concerns and proper dependency direction?
|
||||
4. Have specialist agents confirmed alignment with PRD and consistent application of patterns?
|
||||
5. Have all gaps and overlaps identified been resolved?
|
||||
6. Can a developer implement from this design without ambiguity?
|
||||
|
||||
Once complete, present a summary of the technical design with key architectural decisions. Ask: "The technical specification is complete. Should I proceed to implementation planning (PLAN)?" and wait for user confirmation before proceeding.
|
||||
|
||||
### 📋 Step 4: Implementation Plan
|
||||
|
||||
**🎯 Goal**: Complete PLAN developing an actionable plan that breaks down the work into executable tasks.
|
||||
|
||||
**🔄 Context Priming**: First, check if the PLAN already exists in the specification directory. If it exists, read the ENTIRE file completely to understand what implementation phases have been planned, what remains to be detailed, and where planning should continue. This primes your context for resuming work. Additionally, read both the completed PRD and SDD to ensure the implementation plan addresses all requirements and follows the technical design. If the PLAN doesn't exist, run `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/spec.py [ID] --add implementation-plan` to generate it from the template.
|
||||
|
||||
Once the PLAN is loaded or created, thoroughly read the entire document to understand its structure, required sections, and identify all phases that need detailed planning.
|
||||
|
||||
**Apply the Standard Cycle Pattern with these specifics:**
|
||||
- **Discovery Focus**: Implementation activities (database migrations, API endpoints, UI components, validation logic, deployment pipelines, test suites)
|
||||
- **Agent Selection**: Implementation planning, dependency analysis, risk assessment, validation planning
|
||||
- **Documentation**: implementation-plan.md + any discovered patterns, interfaces, or domain rules
|
||||
- **Validation**: Ensure every phase traces back to PRD requirements and SDD design decisions, include specification alignment gates
|
||||
- **Task Sequencing**: Focus on task dependencies and sequencing, NOT time estimates
|
||||
|
||||
Continue cycles until the PLAN is complete and user has confirmed to proceed to final assessment.
|
||||
|
||||
**🔍 Final Validation**:
|
||||
Use specialist agents to validate the complete implementation plan for:
|
||||
- Coverage of all requirements (business and technical)
|
||||
- Feasibility for automated execution
|
||||
- Proper task sequencing and dependencies
|
||||
- Adequate validation and rollback procedures
|
||||
|
||||
Once complete, present a summary of the implementation plan with key phases and execution strategy. Ask: "The implementation plan is complete. Should I proceed to final assessment?" and wait for user confirmation before proceeding.
|
||||
|
||||
### 📋 Step 5: Finalization and Confidence Assessment
|
||||
|
||||
**🎯 Goal**: Review all deliverables, assess implementation readiness, and provide clear next steps.
|
||||
|
||||
Review all documents created in the specification directory. Read through the PRD, SDD, and PLAN to ensure completeness and consistency. Check any patterns or interfaces documented during the process.
|
||||
|
||||
**📊 Generate Final Assessment**:
|
||||
- Compile specification identity and all document paths
|
||||
- List supplementary documentation created
|
||||
- Calculate implementation confidence based on completeness
|
||||
- Identify success enablers and risk factors
|
||||
- Note any remaining information gaps
|
||||
- Check for context drift between documents
|
||||
- Formulate clear recommendation
|
||||
|
||||
**🔍 Context Drift Check**:
|
||||
Compare the final PLAN against the original PRD and SDD to ensure:
|
||||
- All PRD requirements are addressed in the PLAN
|
||||
- PLAN follows the technical design from SDD
|
||||
- No scope creep occurred during specification
|
||||
- Implementation tasks align with original business goals
|
||||
- Technical decisions haven't diverged from requirements
|
||||
|
||||
**🤔 Verify before finalizing**:
|
||||
1. Is TodoWrite showing all specification steps as completed or properly marked as skipped?
|
||||
2. Have all created documents been validated and reviewed?
|
||||
3. Is the confidence assessment based on actual findings from the specification process?
|
||||
4. Would another agent be able to implement this specification successfully?
|
||||
5. Has context drift been checked and any misalignments identified?
|
||||
|
||||
**📝 Present Final Summary** including:
|
||||
- Specification Identity: The ID and feature name
|
||||
- Documents Created: List all core documents (PRD, SDD, PLAN) with their paths
|
||||
- Supplementary Documentation: Patterns and interfaces documented
|
||||
- Context Alignment: Confirmation that PLAN aligns with PRD/SDD (or list misalignments)
|
||||
- Implementation Confidence: Percentage score with justification
|
||||
- Success Enablers: Factors supporting successful implementation
|
||||
- Risk Assessment: Potential challenges or blockers
|
||||
- Information Gaps: Missing details that could impact implementation
|
||||
- Clear Recommendation: Ready for implementation or needs clarification
|
||||
- Next Steps: How to proceed (e.g., `/start:implement [ID]` command)
|
||||
|
||||
---
|
||||
|
||||
## 📁 Document Structure
|
||||
|
||||
All specifications and documentation MUST follow this exact structure:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── specs/
|
||||
│ └── [3-digit-number]-[feature-name]/ # Specification documents
|
||||
│ ├── product-requirements.md # Product Requirements Documentation (if applicable)
|
||||
│ ├── solution-design.md # Solution Design Documentation (if applicable)
|
||||
│ └── implementation-plan.md # Implementation Plan
|
||||
├── domain/ # Business rules, domain logic, workflows, business patterns
|
||||
├── patterns/ # Technical code patterns, architectural solutions
|
||||
├── interfaces/ # External API contracts, service integrations
|
||||
```
|
||||
|
||||
**📝 Template Adherence Rules**:
|
||||
- Templates generated by the spec script define the COMPLETE document structure
|
||||
- ONLY replace [NEEDS CLARIFICATION] markers with actual content
|
||||
- NEVER add, remove, or reorganize sections in the templates
|
||||
- NEVER create new subsections or modify the template hierarchy
|
||||
- The template structure is the contract - follow it exactly
|
||||
|
||||
## 📌 Important Notes
|
||||
|
||||
- Always check for existing specs when ID is provided
|
||||
- Apply validation after every specialist agent response
|
||||
- Show step summaries between major documents
|
||||
- Reference external protocols for detailed rules
|
||||
|
||||
**💡 Remember**: You orchestrate the workflow, gather expertise from specialist agents, and create all necessary documents following the templates.
|
||||
191
hooks/statusline.sh
Executable file
191
hooks/statusline.sh
Executable file
@@ -0,0 +1,191 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# Complete statusline script for Claude Code - Shell implementation
|
||||
# Replicates the functionality of the Go implementation from rsmdt/the-startup
|
||||
#
|
||||
# Features:
|
||||
# - Shows current directory (with ~ for home)
|
||||
# - Shows git branch (if in a git repo)
|
||||
# - Shows model name and output style
|
||||
# - Shows help text with styling
|
||||
# - Terminal width aware
|
||||
# - ANSI color support
|
||||
#
|
||||
# Input: JSON from Claude Code via stdin
|
||||
# Output: Single formatted statusline with ANSI colors
|
||||
#
|
||||
# Performance target: <50ms execution time
|
||||
#
|
||||
|
||||
# ANSI color codes
|
||||
# Main text color: #FAFAFA (very light gray/white)
|
||||
MAIN_COLOR="\033[38;2;250;250;250m"
|
||||
# Help text color: #606060 (gray, muted)
|
||||
HELP_COLOR="\033[38;2;96;96;96m"
|
||||
# Italic style
|
||||
ITALIC="\033[3m"
|
||||
# Reset all styles
|
||||
RESET="\033[0m"
|
||||
|
||||
# Read JSON from stdin in one go
|
||||
IFS= read -r -d '' json_input || true
|
||||
|
||||
# Extract fields from JSON using regex (no jq dependency for speed)
|
||||
# Pattern: "field": "value" or "field":"value"
|
||||
|
||||
# Extract current_dir from workspace.current_dir
|
||||
current_dir=""
|
||||
if [[ "$json_input" =~ \"workspace\"[^}]*\"current_dir\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
|
||||
current_dir="${BASH_REMATCH[1]}"
|
||||
fi
|
||||
|
||||
# Fallback to cwd if current_dir not found
|
||||
if [[ -z "$current_dir" && "$json_input" =~ \"cwd\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
|
||||
current_dir="${BASH_REMATCH[1]}"
|
||||
fi
|
||||
|
||||
# Use current directory if still empty
|
||||
[[ -z "$current_dir" ]] && current_dir="$PWD"
|
||||
|
||||
# Extract model display_name
|
||||
model_name=""
|
||||
if [[ "$json_input" =~ \"model\"[^}]*\"display_name\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
|
||||
model_name="${BASH_REMATCH[1]}"
|
||||
fi
|
||||
[[ -z "$model_name" ]] && model_name="Claude"
|
||||
|
||||
# Extract output_style name
|
||||
output_style=""
|
||||
if [[ "$json_input" =~ \"output_style\"[^}]*\"name\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
|
||||
output_style="${BASH_REMATCH[1]}"
|
||||
fi
|
||||
[[ -z "$output_style" ]] && output_style="default"
|
||||
|
||||
# Home directory substitution
|
||||
# Replace /Users/username or /home/username with ~
|
||||
home_dir="$HOME"
|
||||
if [[ -n "$home_dir" && "$current_dir" == "$home_dir" ]]; then
|
||||
# Exact match: /Users/username -> ~
|
||||
current_dir="~"
|
||||
elif [[ -n "$home_dir" && "$current_dir" == "$home_dir"/* ]]; then
|
||||
# Prefix match: /Users/username/Documents -> ~/Documents
|
||||
current_dir="~${current_dir#$home_dir}"
|
||||
fi
|
||||
|
||||
# Get git branch information
|
||||
get_git_branch() {
|
||||
local dir="$1"
|
||||
|
||||
# Expand tilde to home directory if present
|
||||
[[ "$dir" =~ ^~ ]] && dir="${dir/#\~/$HOME}"
|
||||
|
||||
# Fast path: Direct .git/HEAD file read
|
||||
local git_head="${dir}/.git/HEAD"
|
||||
if [[ -f "$git_head" && -r "$git_head" ]]; then
|
||||
# Read file content
|
||||
local head_content
|
||||
head_content=$(<"$git_head")
|
||||
|
||||
# Extract branch from "ref: refs/heads/branch-name"
|
||||
if [[ "$head_content" =~ ^ref:[[:space:]]*refs/heads/(.+)$ ]]; then
|
||||
echo "${BASH_REMATCH[1]}"
|
||||
return 0
|
||||
fi
|
||||
|
||||
# If HEAD is detached, return HEAD
|
||||
echo "HEAD"
|
||||
return 0
|
||||
fi
|
||||
|
||||
# Fallback: Use git command if available and in git repo
|
||||
if command -v git &>/dev/null && [[ -d "${dir}/.git" ]]; then
|
||||
local branch
|
||||
branch=$(cd "$dir" 2>/dev/null && git symbolic-ref --short HEAD 2>/dev/null || echo "")
|
||||
if [[ -n "$branch" ]]; then
|
||||
echo "$branch"
|
||||
return 0
|
||||
fi
|
||||
# Check if in detached HEAD state
|
||||
if (cd "$dir" 2>/dev/null && git rev-parse --git-dir &>/dev/null); then
|
||||
echo "HEAD"
|
||||
return 0
|
||||
fi
|
||||
fi
|
||||
|
||||
# No git repo
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Get git info with branch symbol
|
||||
git_branch=$(get_git_branch "$current_dir")
|
||||
git_info=""
|
||||
if [[ -n "$git_branch" ]]; then
|
||||
git_info="⎇ $git_branch"
|
||||
fi
|
||||
|
||||
# Get terminal width
|
||||
get_term_width() {
|
||||
local width
|
||||
|
||||
# Method 1: COLUMNS environment variable (most reliable in hooks/scripts)
|
||||
if [[ -n "$COLUMNS" && "$COLUMNS" =~ ^[0-9]+$ && "$COLUMNS" -gt 0 ]]; then
|
||||
echo "$COLUMNS"
|
||||
return 0
|
||||
fi
|
||||
|
||||
# Method 2: tput cols command (if available)
|
||||
if command -v tput &>/dev/null; then
|
||||
width=$(tput cols 2>/dev/null)
|
||||
if [[ -n "$width" && "$width" =~ ^[0-9]+$ && "$width" -gt 0 ]]; then
|
||||
echo "$width"
|
||||
return 0
|
||||
fi
|
||||
fi
|
||||
|
||||
# Method 3: stty size command (if available)
|
||||
if command -v stty &>/dev/null; then
|
||||
local size
|
||||
size=$(stty size 2>/dev/null)
|
||||
if [[ -n "$size" ]]; then
|
||||
width=$(echo "$size" | cut -d' ' -f2)
|
||||
if [[ -n "$width" && "$width" =~ ^[0-9]+$ && "$width" -gt 0 ]]; then
|
||||
echo "$width"
|
||||
return 0
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Default fallback
|
||||
echo "120"
|
||||
}
|
||||
|
||||
term_width=$(get_term_width)
|
||||
|
||||
# Build the statusline parts
|
||||
# Format: 📁 <dir> <git> 🤖 <model> (<style>) ? for shortcuts
|
||||
|
||||
# Part 1: Directory with git info
|
||||
if [[ -n "$git_info" ]]; then
|
||||
dir_part="📁 $current_dir $git_info"
|
||||
else
|
||||
dir_part="📁 $current_dir"
|
||||
fi
|
||||
|
||||
# Part 2: Model and output style
|
||||
model_part="🤖 $model_name ($output_style)"
|
||||
|
||||
# Part 3: Help text (styled differently)
|
||||
help_text="? for shortcuts"
|
||||
|
||||
# Calculate spacing (2 spaces between each part)
|
||||
# We need to account for emoji character widths and ANSI codes
|
||||
# For simplicity, we'll use fixed spacing like the Go implementation
|
||||
|
||||
# Build the complete statusline
|
||||
# Main parts with MAIN_COLOR, help text with HELP_COLOR and italic
|
||||
statusline="${RESET}${dir_part} ${model_part} ${HELP_COLOR}${ITALIC}${help_text}${RESET}"
|
||||
|
||||
# Output the statusline
|
||||
echo -e "$statusline"
|
||||
|
||||
exit 0
|
||||
105
plugin.lock.json
Normal file
105
plugin.lock.json
Normal file
@@ -0,0 +1,105 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:rsmdt/the-startup:plugins/start",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "e7fd69fa00a2c65b047d3a5a7017fc3c5ca035b6",
|
||||
"treeHash": "38933d8e22d6129ed45466b11b5335314825b0af1ed7e1832aaf66f5391cd7ef",
|
||||
"generatedAt": "2025-11-28T10:28:04.061431Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "start",
|
||||
"description": "Workflow orchestration commands for agentic software development",
|
||||
"version": "2.0.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "e2da88c360a0c0c37dd07f7d372afcfb64c9564ef2549a0ca37d6d36361465bd"
|
||||
},
|
||||
{
|
||||
"path": "hooks/statusline.sh",
|
||||
"sha256": "ed9f8974962907589544cf075cd5c5784edbb65421347a169dae46fff00390b7"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "ff6db31d3fe6667f30875d797f295e45a231b754c75531273efa0dc96bcd6f6f"
|
||||
},
|
||||
{
|
||||
"path": "commands/implement.md",
|
||||
"sha256": "d60769cb41345129dd4722b7eac1b7320a749c0bd07d4d81585740f767343725"
|
||||
},
|
||||
{
|
||||
"path": "commands/analyze.md",
|
||||
"sha256": "76b7161af0740d90423e48e6d125d47a463a759d047c3fd9526f63e326a60c4b"
|
||||
},
|
||||
{
|
||||
"path": "commands/init.md",
|
||||
"sha256": "96fa0dd44e30805adf0666eb72dfe612b576a9f774bb2517e0528071466b6f84"
|
||||
},
|
||||
{
|
||||
"path": "commands/refactor.md",
|
||||
"sha256": "d6f7adf4c68fb5c458bc36718bc9e219c57e506b68ae98a9dd6a2eb481d1ef53"
|
||||
},
|
||||
{
|
||||
"path": "commands/specify.md",
|
||||
"sha256": "1f54f4747d0a534c6e902d4136db62a3d5c874da024957706bd7384722e183f9"
|
||||
},
|
||||
{
|
||||
"path": "skills/documentation/reference.md",
|
||||
"sha256": "c19988fcf8ed413ef087e5ff4dd6459697e04f98db72fdeaa9b8cad8c7d5099c"
|
||||
},
|
||||
{
|
||||
"path": "skills/documentation/SKILL.md",
|
||||
"sha256": "6e3079351a97c1196047890cf2ed3f736eca2ba3f8b3d4051ed760e82bbb75e1"
|
||||
},
|
||||
{
|
||||
"path": "skills/documentation/templates/domain-template.md",
|
||||
"sha256": "a8f52b1ad0535ea4bb35c564abedaa785680760516b74715e1a93bc9d1d0832c"
|
||||
},
|
||||
{
|
||||
"path": "skills/documentation/templates/pattern-template.md",
|
||||
"sha256": "a1d27bf6f03cb20731a6ce5637fc1eb177614c12fdfb4ceb59c701419d119453"
|
||||
},
|
||||
{
|
||||
"path": "skills/documentation/templates/interface-template.md",
|
||||
"sha256": "66009ee791ed7269fbe7d906c7aa0df9cc448dadb8c0f1110108a97a298e2329"
|
||||
},
|
||||
{
|
||||
"path": "skills/agent-delegation/reference.md",
|
||||
"sha256": "8574b2431d39b616f617884d160201f97bda7ffe88c5832d31d8310447f399c3"
|
||||
},
|
||||
{
|
||||
"path": "skills/agent-delegation/SKILL.md",
|
||||
"sha256": "bd611a160456dbc32c08bca7478e59b942e0d3229082e0c1a3dfd57ac165ea28"
|
||||
},
|
||||
{
|
||||
"path": "skills/agent-delegation/examples/file-coordination.md",
|
||||
"sha256": "5a61b2a4db7b0a8eab17a31b0245281f6aef1b691f27fa0dba8b76ee48bb6b6b"
|
||||
},
|
||||
{
|
||||
"path": "skills/agent-delegation/examples/parallel-research.md",
|
||||
"sha256": "165dae56661e61097737fbde0d4a02c18c02fa33583e1408e570a64060b8bdbf"
|
||||
},
|
||||
{
|
||||
"path": "skills/agent-delegation/examples/sequential-build.md",
|
||||
"sha256": "f671ae522168a30b5af46a6154a5939931947e4eff595ae4fdcdda5c8ef3bdfb"
|
||||
}
|
||||
],
|
||||
"dirSha256": "38933d8e22d6129ed45466b11b5335314825b0af1ed7e1832aaf66f5391cd7ef"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
882
skills/agent-delegation/SKILL.md
Normal file
882
skills/agent-delegation/SKILL.md
Normal file
@@ -0,0 +1,882 @@
|
||||
---
|
||||
name: agent-delegation
|
||||
description: Generate structured agent prompts with FOCUS/EXCLUDE templates for task delegation. Use when breaking down complex tasks, launching parallel specialists, coordinating multiple agents, creating agent instructions, determining execution strategy, or preventing file path collisions. Handles task decomposition, parallel vs sequential logic, scope validation, and retry strategies.
|
||||
allowed-tools: Task, TodoWrite
|
||||
---
|
||||
|
||||
You are an agent delegation specialist that helps orchestrators break down complex tasks and coordinate multiple specialist agents.
|
||||
|
||||
## When to Activate
|
||||
|
||||
Activate this skill when you need to:
|
||||
- **Break down a complex task** into multiple distinct activities
|
||||
- **Launch specialist agents** (parallel or sequential)
|
||||
- **Create structured agent prompts** with FOCUS/EXCLUDE templates
|
||||
- **Coordinate multiple agents** working on related tasks
|
||||
- **Determine execution strategy** (parallel vs sequential)
|
||||
- **Prevent file path collisions** between agents creating files
|
||||
- **Validate agent responses** for scope compliance
|
||||
- **Generate retry strategies** for failed agents
|
||||
- **Assess dependencies** between activities
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Activity-Based Decomposition
|
||||
|
||||
Decompose complex work by **ACTIVITIES** (what needs doing), not roles.
|
||||
|
||||
✅ **DO:** "Analyze security requirements", "Design database schema", "Create API endpoints"
|
||||
❌ **DON'T:** "Backend engineer do X", "Frontend developer do Y"
|
||||
|
||||
**Why:** The system automatically matches activities to specialized agents. Focus on the work, not the worker.
|
||||
|
||||
### Parallel-First Mindset
|
||||
|
||||
**DEFAULT:** Always execute in parallel unless tasks depend on each other.
|
||||
|
||||
Parallel execution maximizes velocity. Only go sequential when dependencies or shared state require it.
|
||||
|
||||
---
|
||||
|
||||
## Task Decomposition
|
||||
|
||||
### Decision Process
|
||||
|
||||
When faced with a complex task:
|
||||
|
||||
1. **Identify distinct activities** - What separate pieces of work are needed?
|
||||
2. **Determine expertise required** - What type of knowledge does each need?
|
||||
3. **Find natural boundaries** - Where do activities naturally separate?
|
||||
4. **Check for dependencies** - Does any activity depend on another's output?
|
||||
5. **Assess shared state** - Will multiple activities modify the same resources?
|
||||
|
||||
### Decomposition Template
|
||||
|
||||
```
|
||||
Original Task: [The complex task to break down]
|
||||
|
||||
Activities Identified:
|
||||
1. [Activity 1 name]
|
||||
- Expertise: [Type of knowledge needed]
|
||||
- Output: [What this produces]
|
||||
- Dependencies: [What it needs from other activities]
|
||||
|
||||
2. [Activity 2 name]
|
||||
- Expertise: [Type of knowledge needed]
|
||||
- Output: [What this produces]
|
||||
- Dependencies: [What it needs from other activities]
|
||||
|
||||
3. [Activity 3 name]
|
||||
- Expertise: [Type of knowledge needed]
|
||||
- Output: [What this produces]
|
||||
- Dependencies: [What it needs from other activities]
|
||||
|
||||
Execution Strategy: [Parallel / Sequential / Mixed]
|
||||
Reasoning: [Why this strategy fits]
|
||||
```
|
||||
|
||||
### When to Decompose
|
||||
|
||||
**Decompose when:**
|
||||
- Multiple distinct activities needed
|
||||
- Independent components that can be validated separately
|
||||
- Natural boundaries between system layers
|
||||
- Different stakeholder perspectives required
|
||||
- Task complexity exceeds single agent capacity
|
||||
|
||||
**Don't decompose when:**
|
||||
- Single focused activity
|
||||
- No clear separation of concerns
|
||||
- Overhead exceeds benefits
|
||||
- Task is already atomic
|
||||
|
||||
### Decomposition Examples
|
||||
|
||||
**Example 1: Add User Authentication**
|
||||
|
||||
```
|
||||
Original Task: Add user authentication to the application
|
||||
|
||||
Activities:
|
||||
1. Analyze security requirements
|
||||
- Expertise: Security analysis
|
||||
- Output: Security requirements document
|
||||
- Dependencies: None
|
||||
|
||||
2. Design database schema
|
||||
- Expertise: Database design
|
||||
- Output: Schema design with user tables
|
||||
- Dependencies: Security requirements (Activity 1)
|
||||
|
||||
3. Create API endpoints
|
||||
- Expertise: Backend development
|
||||
- Output: Login/logout/register endpoints
|
||||
- Dependencies: Database schema (Activity 2)
|
||||
|
||||
4. Build login/register UI
|
||||
- Expertise: Frontend development
|
||||
- Output: Authentication UI components
|
||||
- Dependencies: API endpoints (Activity 3)
|
||||
|
||||
Execution Strategy: Mixed
|
||||
- Sequential: 1 → 2 → (3 & 4 parallel)
|
||||
Reasoning: Early activities inform later ones, but API and UI can be built in parallel once schema exists
|
||||
```
|
||||
|
||||
**Example 2: Research Competitive Landscape**
|
||||
|
||||
```
|
||||
Original Task: Research competitive landscape for pricing strategy
|
||||
|
||||
Activities:
|
||||
1. Analyze competitor A pricing
|
||||
- Expertise: Market research
|
||||
- Output: Competitor A pricing analysis
|
||||
- Dependencies: None
|
||||
|
||||
2. Analyze competitor B pricing
|
||||
- Expertise: Market research
|
||||
- Output: Competitor B pricing analysis
|
||||
- Dependencies: None
|
||||
|
||||
3. Analyze competitor C pricing
|
||||
- Expertise: Market research
|
||||
- Output: Competitor C pricing analysis
|
||||
- Dependencies: None
|
||||
|
||||
4. Synthesize findings
|
||||
- Expertise: Strategic analysis
|
||||
- Output: Unified competitive analysis
|
||||
- Dependencies: All competitor analyses (Activities 1-3)
|
||||
|
||||
Execution Strategy: Mixed
|
||||
- Parallel: 1, 2, 3 → Sequential: 4
|
||||
Reasoning: Each competitor analysis is independent, synthesis requires all results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Decision Making
|
||||
|
||||
When decomposing tasks, explicitly decide whether documentation should be created.
|
||||
|
||||
### Criteria for Documentation
|
||||
|
||||
Include documentation in OUTPUT only when **ALL** criteria are met:
|
||||
|
||||
1. **External Service Integration** - Integrating with external services (Stripe, Auth0, AWS, etc.)
|
||||
2. **Reusable** - Pattern/interface/rule used in 2+ places OR clearly reusable
|
||||
3. **Non-Obvious** - Not standard practices (REST, MVC, CRUD)
|
||||
4. **Not a Duplicate** - Check existing docs first: `grep -ri "keyword" docs/` or `find docs -name "*topic*"`
|
||||
|
||||
### Decision Logic
|
||||
|
||||
- **Found existing docs** → OUTPUT: "Update docs/[category]/[file.md]"
|
||||
- **No existing docs + meets criteria** → OUTPUT: "Create docs/[category]/[file.md]"
|
||||
- **Doesn't meet criteria** → No documentation in OUTPUT
|
||||
|
||||
### Categories
|
||||
|
||||
- **docs/interfaces/** - External service integrations (Stripe, Auth0, AWS, webhooks)
|
||||
- **docs/patterns/** - Technical patterns (caching, auth flow, error handling)
|
||||
- **docs/domain/** - Business rules and domain logic (permissions, pricing, workflows)
|
||||
|
||||
### What NOT to Document
|
||||
|
||||
- ❌ Meta-documentation (SUMMARY.md, REPORT.md, ANALYSIS.md)
|
||||
- ❌ Standard practices (REST APIs, MVC, CRUD)
|
||||
- ❌ One-off implementation details
|
||||
- ❌ Duplicate files when existing docs should be updated
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
Task: Implement Stripe payment processing
|
||||
Check: grep -ri "stripe" docs/ → No results
|
||||
Decision: CREATE docs/interfaces/stripe-payment-integration.md
|
||||
|
||||
OUTPUT:
|
||||
- Payment processing code
|
||||
- docs/interfaces/stripe-payment-integration.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Parallel vs Sequential Determination
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Scenario | Dependencies | Shared State | Validation | File Paths | Recommendation |
|
||||
|----------|--------------|--------------|------------|------------|----------------|
|
||||
| Research tasks | None | Read-only | Independent | N/A | **PARALLEL** ⚡ |
|
||||
| Analysis tasks | None | Read-only | Independent | N/A | **PARALLEL** ⚡ |
|
||||
| Documentation | None | Unique paths | Independent | Unique | **PARALLEL** ⚡ |
|
||||
| Code creation | None | Unique files | Independent | Unique | **PARALLEL** ⚡ |
|
||||
| Build pipeline | Sequential | Shared files | Dependent | Same | **SEQUENTIAL** 📝 |
|
||||
| File editing | None | Same file | Collision risk | Same | **SEQUENTIAL** 📝 |
|
||||
| Dependent tasks | B needs A | Any | Dependent | Any | **SEQUENTIAL** 📝 |
|
||||
|
||||
### Parallel Execution Checklist
|
||||
|
||||
Run this checklist to confirm parallel execution is safe:
|
||||
|
||||
✅ **Independent tasks** - No task depends on another's output
|
||||
✅ **No shared state** - No simultaneous writes to same data
|
||||
✅ **Separate validation** - Each can be validated independently
|
||||
✅ **Won't block** - No resource contention
|
||||
✅ **Unique file paths** - If creating files, paths don't collide
|
||||
|
||||
**Result:** ✅ **PARALLEL EXECUTION** - Launch all agents in single response
|
||||
|
||||
### Sequential Execution Indicators
|
||||
|
||||
Look for these signals that require sequential execution:
|
||||
|
||||
🔴 **Dependency chain** - Task B needs Task A's output
|
||||
🔴 **Shared state** - Multiple tasks modify same resource
|
||||
🔴 **Validation dependency** - Must validate before proceeding
|
||||
🔴 **File path collision** - Multiple tasks write same file
|
||||
🔴 **Order matters** - Business logic requires specific sequence
|
||||
|
||||
**Result:** 📝 **SEQUENTIAL EXECUTION** - Launch agents one at a time
|
||||
|
||||
### Mixed Execution Strategy
|
||||
|
||||
Many complex tasks benefit from mixed strategies:
|
||||
|
||||
**Pattern:** Parallel groups connected sequentially
|
||||
|
||||
```
|
||||
Group 1 (parallel): Tasks A, B, C
|
||||
↓ (sequential)
|
||||
Group 2 (parallel): Tasks D, E
|
||||
↓ (sequential)
|
||||
Group 3: Task F
|
||||
```
|
||||
|
||||
**Example:** Authentication implementation
|
||||
- Group 1: Analyze security, Research best practices (parallel)
|
||||
- Sequential: Design schema (needs Group 1 results)
|
||||
- Group 2: Build API, Build UI (parallel)
|
||||
|
||||
---
|
||||
|
||||
## Agent Prompt Template Generation
|
||||
|
||||
### Base Template Structure
|
||||
|
||||
Every agent prompt should follow this structure:
|
||||
|
||||
```
|
||||
FOCUS: [Complete task description with all details]
|
||||
|
||||
EXCLUDE: [Task-specific things to avoid]
|
||||
- Do not create new patterns when existing ones work
|
||||
- Do not duplicate existing work
|
||||
[Add specific exclusions for this task]
|
||||
|
||||
CONTEXT: [Task background and constraints]
|
||||
- [Include relevant rules for this task]
|
||||
- Follow discovered patterns exactly
|
||||
[Add task-specific context]
|
||||
|
||||
OUTPUT: [Expected deliverables with exact paths if applicable]
|
||||
|
||||
SUCCESS: [Measurable completion criteria]
|
||||
- Follows existing patterns
|
||||
- Integrates with existing system
|
||||
[Add task-specific success criteria]
|
||||
|
||||
TERMINATION: [When to stop]
|
||||
- Completed successfully
|
||||
- Blocked by [specific blockers]
|
||||
- Maximum 3 attempts reached
|
||||
```
|
||||
|
||||
### Template Customization Rules
|
||||
|
||||
#### For File-Creating Agents
|
||||
|
||||
Add **DISCOVERY_FIRST** section at the beginning:
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting your task, understand the environment:
|
||||
- [Appropriate discovery commands for the task type]
|
||||
- Identify existing patterns and conventions
|
||||
- Locate where similar files live
|
||||
- Check project structure and naming conventions
|
||||
|
||||
[Rest of template follows]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting your task, understand the environment:
|
||||
- find . -name "*test*" -o -name "*spec*" -type f | head -20
|
||||
- Identify test framework (Jest, Vitest, Mocha, etc.)
|
||||
- Check existing test file naming patterns
|
||||
- Note test directory structure
|
||||
```
|
||||
|
||||
#### For Review Agents
|
||||
|
||||
Use **REVIEW_FOCUS** variant:
|
||||
|
||||
```
|
||||
REVIEW_FOCUS: [Implementation to review]
|
||||
|
||||
VERIFY:
|
||||
- [Specific criteria to check]
|
||||
- [Quality requirements]
|
||||
- [Specification compliance]
|
||||
- [Security considerations]
|
||||
|
||||
CONTEXT: [Background about what's being reviewed]
|
||||
|
||||
OUTPUT: [Review report format]
|
||||
- Issues found (if any)
|
||||
- Approval status
|
||||
- Recommendations
|
||||
|
||||
SUCCESS: Review completed with clear decision (approve/reject/revise)
|
||||
|
||||
TERMINATION: Review decision made OR blocked by missing context
|
||||
```
|
||||
|
||||
#### For Research Agents
|
||||
|
||||
Emphasize **OUTPUT** format specificity:
|
||||
|
||||
```
|
||||
FOCUS: [Research question or area]
|
||||
|
||||
EXCLUDE: [Out of scope topics]
|
||||
|
||||
CONTEXT: [Why this research is needed]
|
||||
|
||||
OUTPUT: Structured findings including:
|
||||
- Executive Summary (2-3 sentences)
|
||||
- Key Findings (bulleted list)
|
||||
- Detailed Analysis (organized by theme)
|
||||
- Recommendations (actionable next steps)
|
||||
- References (sources consulted)
|
||||
|
||||
SUCCESS: All sections completed with actionable insights
|
||||
|
||||
TERMINATION: Research complete OR information unavailable
|
||||
```
|
||||
|
||||
### Context Insertion Strategy
|
||||
|
||||
**Always include in CONTEXT:**
|
||||
|
||||
1. **Relevant rules** - Extract applicable rules from CLAUDE.md or project docs
|
||||
2. **Project constraints** - Technical stack, coding standards, conventions
|
||||
3. **Prior outputs** - For sequential tasks, include relevant results from previous steps
|
||||
4. **Specification references** - For implementation tasks, cite PRD/SDD/PLAN sections
|
||||
|
||||
**Context Example:**
|
||||
```
|
||||
CONTEXT: Testing authentication service handling login, tokens, and sessions.
|
||||
- TDD required: Write tests before implementation
|
||||
- One behavior per test: Each test should verify single behavior
|
||||
- Mock externals only: Don't mock internal application code
|
||||
- Follow discovered test patterns exactly
|
||||
- Current auth flow: docs/patterns/authentication-flow.md
|
||||
- Security requirements: PRD Section 3.2
|
||||
```
|
||||
|
||||
### Template Generation Examples
|
||||
|
||||
**Example 1: Parallel Research Tasks**
|
||||
|
||||
```
|
||||
Agent 1 - Competitor A Analysis:
|
||||
|
||||
FOCUS: Research Competitor A's pricing strategy, tiers, and feature bundling
|
||||
- Identify all pricing tiers
|
||||
- Map features to tiers
|
||||
- Note promotional strategies
|
||||
- Calculate price per feature value
|
||||
|
||||
EXCLUDE: Don't analyze their technology stack or implementation
|
||||
- Don't make pricing recommendations yet
|
||||
- Don't compare to other competitors
|
||||
|
||||
CONTEXT: We're researching competitive landscape for our pricing strategy.
|
||||
- Focus on B2B SaaS pricing
|
||||
- Competitor A is our primary competitor
|
||||
- Looking for pricing patterns and positioning
|
||||
|
||||
OUTPUT: Structured analysis including:
|
||||
- Pricing tiers table
|
||||
- Feature matrix by tier
|
||||
- Key insights about their strategy
|
||||
- Notable patterns or differentiators
|
||||
|
||||
SUCCESS: Complete analysis with actionable data
|
||||
- All tiers documented
|
||||
- Features mapped accurately
|
||||
- Insights are specific and evidence-based
|
||||
|
||||
TERMINATION: Analysis complete OR information not publicly available
|
||||
```
|
||||
|
||||
**Example 2: Sequential Implementation Tasks**
|
||||
|
||||
```
|
||||
Agent 1 - Database Schema (runs first):
|
||||
|
||||
DISCOVERY_FIRST: Before starting, understand the environment:
|
||||
- Check existing database migrations
|
||||
- Identify ORM/database tool in use
|
||||
- Review existing table structures
|
||||
- Note naming conventions
|
||||
|
||||
FOCUS: Design database schema for user authentication
|
||||
- Users table with email, password hash, created_at
|
||||
- Sessions table for active sessions
|
||||
- Use appropriate indexes for performance
|
||||
|
||||
EXCLUDE: Don't implement the actual migration yet
|
||||
- Don't add OAuth tables (separate feature)
|
||||
- Don't modify existing tables
|
||||
|
||||
CONTEXT: From security analysis, we need:
|
||||
- Bcrypt password hashing (cost factor 12)
|
||||
- Email uniqueness constraint
|
||||
- Session expiry mechanism
|
||||
- Follow discovered database patterns exactly
|
||||
|
||||
OUTPUT: Schema design document at docs/patterns/auth-schema.md
|
||||
- Table definitions with types
|
||||
- Indexes and constraints
|
||||
- Relationships between tables
|
||||
|
||||
SUCCESS: Schema designed and documented
|
||||
- Follows project conventions
|
||||
- Meets security requirements
|
||||
- Ready for migration implementation
|
||||
|
||||
TERMINATION: Design complete OR blocked by missing requirements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Creation Coordination
|
||||
|
||||
### Collision Prevention Protocol
|
||||
|
||||
When multiple agents will create files:
|
||||
|
||||
**Check before launching:**
|
||||
1. ✅ Are file paths specified explicitly in each agent's OUTPUT?
|
||||
2. ✅ Are all file paths unique (no two agents write same path)?
|
||||
3. ✅ Do paths follow project conventions?
|
||||
4. ✅ Are paths deterministic (not ambiguous)?
|
||||
|
||||
**If any check fails:** 🔴 Adjust OUTPUT sections to prevent collisions
|
||||
|
||||
### Path Assignment Strategies
|
||||
|
||||
#### Strategy 1: Explicit Unique Paths
|
||||
|
||||
Assign each agent a specific file path:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: Create pattern at docs/patterns/authentication-flow.md
|
||||
Agent 2 OUTPUT: Create interface at docs/interfaces/oauth-providers.md
|
||||
Agent 3 OUTPUT: Create domain rule at docs/domain/user-permissions.md
|
||||
```
|
||||
|
||||
**Result:** ✅ No collisions possible
|
||||
|
||||
#### Strategy 2: Discovery-Based Paths
|
||||
|
||||
Use placeholder that agent discovers:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: Test file at [DISCOVERED_LOCATION]/AuthService.test.ts
|
||||
where DISCOVERED_LOCATION is found via DISCOVERY_FIRST
|
||||
|
||||
Agent 2 OUTPUT: Test file at [DISCOVERED_LOCATION]/UserService.test.ts
|
||||
where DISCOVERED_LOCATION is found via DISCOVERY_FIRST
|
||||
```
|
||||
|
||||
**Result:** ✅ Agents discover same location, but filenames differ
|
||||
|
||||
#### Strategy 3: Hierarchical Paths
|
||||
|
||||
Use directory structure to separate agents:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: docs/patterns/backend/api-versioning.md
|
||||
Agent 2 OUTPUT: docs/patterns/frontend/state-management.md
|
||||
Agent 3 OUTPUT: docs/patterns/database/migration-strategy.md
|
||||
```
|
||||
|
||||
**Result:** ✅ Different directories prevent collisions
|
||||
|
||||
### Coordination Checklist
|
||||
|
||||
Before launching agents that create files:
|
||||
|
||||
- [ ] Each agent has explicit OUTPUT with file path
|
||||
- [ ] All file paths are unique
|
||||
- [ ] Paths follow project naming conventions
|
||||
- [ ] If using DISCOVERY, filenames differ
|
||||
- [ ] No potential for race conditions
|
||||
|
||||
---
|
||||
|
||||
## Scope Validation & Response Review
|
||||
|
||||
### Auto-Accept Criteria 🟢
|
||||
|
||||
Continue without user review when agent delivers:
|
||||
|
||||
**Security improvements:**
|
||||
- Vulnerability fixes
|
||||
- Input validation additions
|
||||
- Authentication enhancements
|
||||
- Error handling improvements
|
||||
|
||||
**Quality improvements:**
|
||||
- Code clarity enhancements
|
||||
- Documentation updates
|
||||
- Test coverage additions (if in scope)
|
||||
- Performance optimizations under 10 lines
|
||||
|
||||
**Specification compliance:**
|
||||
- Exactly matches FOCUS requirements
|
||||
- Respects all EXCLUDE boundaries
|
||||
- Delivers expected OUTPUT format
|
||||
- Meets SUCCESS criteria
|
||||
|
||||
### Requires User Review 🟡
|
||||
|
||||
Present to user for confirmation when agent delivers:
|
||||
|
||||
**Architectural changes:**
|
||||
- New external dependencies added
|
||||
- Database schema modifications
|
||||
- Public API changes
|
||||
- Design pattern changes
|
||||
- Configuration file updates
|
||||
|
||||
**Scope expansions:**
|
||||
- Features beyond FOCUS (but valuable)
|
||||
- Additional improvements requested
|
||||
- Alternative approaches suggested
|
||||
|
||||
### Auto-Reject Criteria 🔴
|
||||
|
||||
Reject as scope creep when agent delivers:
|
||||
|
||||
**Out of scope work:**
|
||||
- Features not in requirements
|
||||
- Work explicitly in EXCLUDE list
|
||||
- Breaking changes without migration path
|
||||
- Untested code modifications
|
||||
|
||||
**Quality issues:**
|
||||
- Missing required OUTPUT format
|
||||
- Doesn't meet SUCCESS criteria
|
||||
- "While I'm here" additions
|
||||
- Unrequested improvements
|
||||
|
||||
**Process violations:**
|
||||
- Skipped DISCOVERY_FIRST when required
|
||||
- Ignored CONTEXT constraints
|
||||
- Exceeded TERMINATION conditions
|
||||
|
||||
### Validation Report Format
|
||||
|
||||
When reviewing agent responses:
|
||||
|
||||
```
|
||||
✅ Agent Response Validation
|
||||
|
||||
Agent: [Agent type/name]
|
||||
Task: [Original FOCUS]
|
||||
|
||||
Deliverables Check:
|
||||
✅ [Deliverable 1]: Matches OUTPUT requirement
|
||||
✅ [Deliverable 2]: Matches OUTPUT requirement
|
||||
⚠️ [Deliverable 3]: Extra feature added (not in FOCUS)
|
||||
🔴 [Deliverable 4]: Violates EXCLUDE constraint
|
||||
|
||||
Scope Compliance:
|
||||
- FOCUS coverage: [%]
|
||||
- EXCLUDE violations: [count]
|
||||
- OUTPUT format: [matched/partial/missing]
|
||||
- SUCCESS criteria: [met/partial/unmet]
|
||||
|
||||
Recommendation:
|
||||
🟢 ACCEPT - Fully compliant
|
||||
🟡 REVIEW - User decision needed on [specific item]
|
||||
🔴 REJECT - Scope creep, retry with stricter FOCUS
|
||||
```
|
||||
|
||||
### When Agent Response Seems Off
|
||||
|
||||
**Ask yourself:**
|
||||
- Did I provide ambiguous instructions in FOCUS?
|
||||
- Should I have been more explicit in EXCLUDE?
|
||||
- Is this actually valuable despite being out of scope?
|
||||
- Would stricter FOCUS help or create more issues?
|
||||
|
||||
**Response options:**
|
||||
1. **Accept and update requirements** - If valuable and safe
|
||||
2. **Reject and retry** - With refined FOCUS/EXCLUDE
|
||||
3. **Cherry-pick** - Keep compliant parts, discard scope creep
|
||||
4. **Escalate to user** - For architectural decisions
|
||||
|
||||
---
|
||||
|
||||
## Failure Recovery & Retry Strategies
|
||||
|
||||
### Fallback Chain
|
||||
|
||||
When an agent fails, follow this escalation:
|
||||
|
||||
```
|
||||
1. 🔄 Retry with refined prompt
|
||||
- More specific FOCUS
|
||||
- More explicit EXCLUDE
|
||||
- Better CONTEXT
|
||||
↓ (if still fails)
|
||||
|
||||
2. 🔄 Try different specialist agent
|
||||
- Different expertise angle
|
||||
- Simpler task scope
|
||||
↓ (if still fails)
|
||||
|
||||
3. 🔄 Break into smaller tasks
|
||||
- Decompose further
|
||||
- Sequential smaller steps
|
||||
↓ (if still fails)
|
||||
|
||||
4. 🔄 Sequential instead of parallel
|
||||
- Dependency might exist
|
||||
- Coordination issue
|
||||
↓ (if still fails)
|
||||
|
||||
5. 🔄 Handle directly (DIY)
|
||||
- Task too specialized
|
||||
- Agent limitation
|
||||
↓ (if blocked)
|
||||
|
||||
6. ⚠️ Escalate to user
|
||||
- Present options
|
||||
- Request guidance
|
||||
```
|
||||
|
||||
### Retry Decision Tree
|
||||
|
||||
**Agent failed? Diagnose why:**
|
||||
|
||||
| Symptom | Likely Cause | Solution |
|
||||
|---------|--------------|----------|
|
||||
| Scope creep | FOCUS too vague | Refine FOCUS, expand EXCLUDE |
|
||||
| Wrong approach | Wrong specialist | Try different agent type |
|
||||
| Incomplete work | Task too complex | Break into smaller tasks |
|
||||
| Blocked/stuck | Missing dependency | Check if should be sequential |
|
||||
| Wrong output | OUTPUT unclear | Specify exact format/path |
|
||||
| Quality issues | CONTEXT insufficient | Add more constraints/examples |
|
||||
|
||||
### Template Refinement for Retry
|
||||
|
||||
**Original (failed):**
|
||||
```
|
||||
FOCUS: Implement authentication
|
||||
|
||||
EXCLUDE: Don't add tests
|
||||
```
|
||||
|
||||
**Why it failed:** Too vague, agent added OAuth when we wanted JWT
|
||||
|
||||
**Refined (retry):**
|
||||
```
|
||||
FOCUS: Implement JWT-based authentication for REST API endpoints
|
||||
- Create middleware for token validation
|
||||
- Add POST /auth/login endpoint that returns JWT
|
||||
- Add POST /auth/logout endpoint that invalidates token
|
||||
- Use bcrypt for password hashing (cost factor 12)
|
||||
- JWT expiry: 24 hours
|
||||
|
||||
EXCLUDE: OAuth implementation (separate feature)
|
||||
- Don't modify existing user table schema
|
||||
- Don't add frontend components
|
||||
- Don't implement refresh tokens yet
|
||||
- Don't add password reset flow
|
||||
|
||||
CONTEXT: API-only authentication for mobile app consumption.
|
||||
- Follow REST API patterns in docs/patterns/api-design.md
|
||||
- Security requirements from PRD Section 3.2
|
||||
- Use existing User model from src/models/User.ts
|
||||
|
||||
OUTPUT:
|
||||
- Middleware: src/middleware/auth.ts
|
||||
- Routes: src/routes/auth.ts
|
||||
- Tests: src/routes/auth.test.ts
|
||||
|
||||
SUCCESS:
|
||||
- Login returns valid JWT
|
||||
- Protected routes require valid token
|
||||
- All tests pass
|
||||
- Follows existing API patterns
|
||||
|
||||
TERMINATION: Implementation complete OR blocked by missing User model
|
||||
```
|
||||
|
||||
**Changes:**
|
||||
- ✅ Specific JWT requirement (not generic "authentication")
|
||||
- ✅ Explicit endpoint specifications
|
||||
- ✅ Detailed EXCLUDE (OAuth, frontend, etc.)
|
||||
- ✅ Exact file paths in OUTPUT
|
||||
- ✅ Measurable SUCCESS criteria
|
||||
|
||||
### Partial Success Handling
|
||||
|
||||
**When agent delivers partial results:**
|
||||
|
||||
1. **Assess what worked:**
|
||||
- Which deliverables are complete?
|
||||
- Which meet SUCCESS criteria?
|
||||
- What's missing?
|
||||
|
||||
2. **Determine if acceptable:**
|
||||
- Can we ship partial results?
|
||||
- Is missing work critical?
|
||||
- Can we iterate on what exists?
|
||||
|
||||
3. **Options:**
|
||||
- **Accept partial + new task** - Ship what works, new agent for missing parts
|
||||
- **Retry complete task** - If partial isn't useful
|
||||
- **Sequential completion** - Build on partial results
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Agent delivered:
|
||||
✅ POST /auth/login endpoint (works perfectly)
|
||||
✅ JWT generation logic (correct)
|
||||
🔴 POST /auth/logout endpoint (missing)
|
||||
🔴 Tests (missing)
|
||||
|
||||
Decision: Accept partial
|
||||
- Login endpoint is production-ready
|
||||
- Launch new agent for logout + tests
|
||||
- Faster than full retry
|
||||
```
|
||||
|
||||
### Retry Limit
|
||||
|
||||
**Maximum retries: 3 attempts**
|
||||
|
||||
After 3 failed attempts:
|
||||
1. **Present to user** - Explain what failed and why
|
||||
2. **Offer options** - Different approaches to try
|
||||
3. **Get guidance** - User decides next steps
|
||||
|
||||
**Don't infinite loop** - If it's not working after 3 tries, human input needed.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
After delegation work, always report:
|
||||
|
||||
```
|
||||
🎯 Task Decomposition Complete
|
||||
|
||||
Original Task: [The complex task]
|
||||
|
||||
Activities Identified: [N]
|
||||
1. [Activity 1] - [Parallel/Sequential]
|
||||
2. [Activity 2] - [Parallel/Sequential]
|
||||
3. [Activity 3] - [Parallel/Sequential]
|
||||
|
||||
Execution Strategy: [Parallel / Sequential / Mixed]
|
||||
Reasoning: [Why this strategy]
|
||||
|
||||
Agent Prompts Generated: [Yes/No]
|
||||
File Coordination: [Checked/Not applicable]
|
||||
Ready to launch: [Yes/No - if No, explain blocker]
|
||||
```
|
||||
|
||||
**For scope validation:**
|
||||
```
|
||||
✅ Scope Validation Complete
|
||||
|
||||
Agent: [Agent name]
|
||||
Result: [ACCEPT / REVIEW NEEDED / REJECT]
|
||||
|
||||
Summary:
|
||||
- Deliverables: [N matched, N extra, N missing]
|
||||
- Scope compliance: [percentage]
|
||||
- Recommendation: [Action to take]
|
||||
|
||||
[If REVIEW or REJECT, provide details]
|
||||
```
|
||||
|
||||
**For retry strategy:**
|
||||
```
|
||||
🔄 Retry Strategy Generated
|
||||
|
||||
Agent: [Agent name]
|
||||
Failure cause: [Diagnosis]
|
||||
Retry approach: [What's different]
|
||||
|
||||
Template refinements:
|
||||
- FOCUS: [What changed]
|
||||
- EXCLUDE: [What was added]
|
||||
- CONTEXT: [What was enhanced]
|
||||
|
||||
Retry attempt: [N of 3]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### When to Use This Skill
|
||||
|
||||
✅ "Break down this complex task"
|
||||
✅ "Launch parallel agents for these activities"
|
||||
✅ "Create agent prompts with FOCUS/EXCLUDE"
|
||||
✅ "Should these run in parallel or sequential?"
|
||||
✅ "Validate this agent response for scope"
|
||||
✅ "Generate retry strategy for failed agent"
|
||||
✅ "Coordinate file creation across agents"
|
||||
|
||||
### Key Principles
|
||||
|
||||
1. **Activity-based decomposition** (not role-based)
|
||||
2. **Parallel-first mindset** (unless dependencies exist)
|
||||
3. **Explicit FOCUS/EXCLUDE** (no ambiguity)
|
||||
4. **Unique file paths** (prevent collisions)
|
||||
5. **Scope validation** (auto-accept/review/reject)
|
||||
6. **Maximum 3 retries** (then escalate to user)
|
||||
|
||||
### Template Checklist
|
||||
|
||||
Every agent prompt needs:
|
||||
- [ ] FOCUS: Complete, specific task description
|
||||
- [ ] EXCLUDE: Explicit boundaries
|
||||
- [ ] CONTEXT: Relevant rules and constraints
|
||||
- [ ] OUTPUT: Expected deliverables with paths
|
||||
- [ ] SUCCESS: Measurable criteria
|
||||
- [ ] TERMINATION: Clear stop conditions
|
||||
- [ ] DISCOVERY_FIRST: If creating files (optional)
|
||||
|
||||
### Parallel Execution Safety
|
||||
|
||||
Before launching parallel agents, verify:
|
||||
- [ ] No dependencies between tasks
|
||||
- [ ] No shared state modifications
|
||||
- [ ] Independent validation possible
|
||||
- [ ] Unique file paths if creating files
|
||||
- [ ] No resource contention
|
||||
|
||||
If all checked: ✅ **PARALLEL SAFE**
|
||||
495
skills/agent-delegation/examples/file-coordination.md
Normal file
495
skills/agent-delegation/examples/file-coordination.md
Normal file
@@ -0,0 +1,495 @@
|
||||
# Example: File Coordination for Parallel Agents
|
||||
|
||||
This example shows how to prevent file path collisions when multiple agents create documentation in parallel.
|
||||
|
||||
## Scenario
|
||||
|
||||
**User Request:** "Document our codebase patterns for authentication, caching, and error handling"
|
||||
|
||||
## Initial Decomposition (Incorrect)
|
||||
|
||||
```
|
||||
❌ WRONG APPROACH
|
||||
|
||||
Activities:
|
||||
1. Document authentication patterns
|
||||
2. Document caching patterns
|
||||
3. Document error handling patterns
|
||||
|
||||
All parallel, all OUTPUT: "docs/patterns/[pattern-name].md"
|
||||
|
||||
Problem: What if agents choose same filename?
|
||||
- Agent 1 might create: docs/patterns/auth.md
|
||||
- Agent 2 might create: docs/patterns/cache.md
|
||||
- Agent 3 might create: docs/patterns/error.md
|
||||
|
||||
OR worse:
|
||||
- Agent 1: docs/patterns/authentication.md
|
||||
- Agent 2: docs/patterns/authentication-patterns.md
|
||||
- Both trying to document auth? Collision!
|
||||
|
||||
Result: Ambiguous, potential collisions, inconsistent naming
|
||||
```
|
||||
|
||||
## Correct Decomposition (File Coordination)
|
||||
|
||||
```
|
||||
✅ CORRECT APPROACH
|
||||
|
||||
Activities:
|
||||
1. Document authentication patterns
|
||||
- OUTPUT: docs/patterns/authentication-flow.md (EXPLICIT PATH)
|
||||
|
||||
2. Document caching patterns
|
||||
- OUTPUT: docs/patterns/caching-strategy.md (EXPLICIT PATH)
|
||||
|
||||
3. Document error handling patterns
|
||||
- OUTPUT: docs/patterns/error-handling.md (EXPLICIT PATH)
|
||||
|
||||
File Coordination Check:
|
||||
✅ All paths explicit and unique
|
||||
✅ No ambiguity in naming
|
||||
✅ No collision risk
|
||||
|
||||
Status: SAFE FOR PARALLEL EXECUTION
|
||||
```
|
||||
|
||||
## Agent Prompts with File Coordination
|
||||
|
||||
### Agent 1: Authentication Pattern
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, check existing documentation:
|
||||
- List docs/patterns/ directory
|
||||
- Search for existing auth-related files
|
||||
- Note naming conventions used
|
||||
- Check if authentication-flow.md already exists
|
||||
|
||||
FOCUS: Document authentication patterns discovered in codebase
|
||||
- JWT token generation and validation
|
||||
- Password hashing (bcrypt usage)
|
||||
- Session management approach
|
||||
- Protected route patterns
|
||||
- Error responses for auth failures
|
||||
|
||||
EXCLUDE:
|
||||
- Don't document caching (Agent 2 handles this)
|
||||
- Don't document error handling generally (Agent 3 handles this)
|
||||
- Don't create multiple files (single document)
|
||||
- Don't modify existing authentication files if they exist
|
||||
|
||||
CONTEXT: Documenting patterns found in src/middleware/auth.*, src/routes/auth.*
|
||||
- Focus on how authentication works, not implementation details
|
||||
- Use pattern template: docs/templates/pattern-template.md
|
||||
- Follow existing documentation style
|
||||
|
||||
OUTPUT: EXACTLY this path: docs/patterns/authentication-flow.md
|
||||
- If file exists: STOP and report (don't overwrite)
|
||||
- If file doesn't exist: Create new
|
||||
- Use pattern template structure
|
||||
- Include code examples from codebase
|
||||
|
||||
SUCCESS: Authentication patterns documented
|
||||
- File created at exact path specified
|
||||
- Follows pattern template
|
||||
- Includes JWT, bcrypt, and session patterns
|
||||
- Code examples are accurate
|
||||
- No collision with other agents
|
||||
|
||||
TERMINATION:
|
||||
- Documentation complete at specified path
|
||||
- File already exists (report to user)
|
||||
- No authentication patterns found in codebase
|
||||
```
|
||||
|
||||
### Agent 2: Caching Pattern
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, check existing documentation:
|
||||
- List docs/patterns/ directory
|
||||
- Search for existing cache-related files
|
||||
- Note naming conventions
|
||||
- Check if caching-strategy.md already exists
|
||||
|
||||
FOCUS: Document caching patterns discovered in codebase
|
||||
- Redis usage patterns
|
||||
- Cache key naming conventions
|
||||
- TTL (time-to-live) strategies
|
||||
- Cache invalidation approaches
|
||||
- What gets cached and why
|
||||
|
||||
EXCLUDE:
|
||||
- Don't document authentication (Agent 1 handles this)
|
||||
- Don't document error handling (Agent 3 handles this)
|
||||
- Don't create multiple files (single document)
|
||||
- Don't overlap with Agent 1's work
|
||||
|
||||
CONTEXT: Documenting patterns found in src/cache/*, src/services/*
|
||||
- Focus on caching strategy, not Redis API details
|
||||
- Use pattern template
|
||||
- Follow existing documentation style
|
||||
|
||||
OUTPUT: EXACTLY this path: docs/patterns/caching-strategy.md
|
||||
- If file exists: STOP and report (don't overwrite)
|
||||
- If file doesn't exist: Create new
|
||||
- Use pattern template structure
|
||||
- Include code examples from codebase
|
||||
|
||||
SUCCESS: Caching patterns documented
|
||||
- File created at exact path specified
|
||||
- Follows pattern template
|
||||
- Includes Redis patterns and cache strategies
|
||||
- No collision with other agents
|
||||
|
||||
TERMINATION:
|
||||
- Documentation complete at specified path
|
||||
- File already exists (report)
|
||||
- No caching patterns found
|
||||
```
|
||||
|
||||
### Agent 3: Error Handling Pattern
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, check existing documentation:
|
||||
- List docs/patterns/ directory
|
||||
- Search for existing error-related files
|
||||
- Note naming conventions
|
||||
- Check if error-handling.md already exists
|
||||
|
||||
FOCUS: Document error handling patterns discovered in codebase
|
||||
- Error class hierarchy
|
||||
- HTTP status code mapping
|
||||
- Error response format
|
||||
- Logging strategy for errors
|
||||
- Recovery patterns
|
||||
|
||||
EXCLUDE:
|
||||
- Don't document authentication (Agent 1's domain)
|
||||
- Don't document caching (Agent 2's domain)
|
||||
- Don't create multiple files
|
||||
- Don't overlap with other agents
|
||||
|
||||
CONTEXT: Documenting patterns found in src/errors/*, src/middleware/error.*
|
||||
- Focus on error handling strategy and patterns
|
||||
- Use pattern template
|
||||
- Follow existing documentation style
|
||||
|
||||
OUTPUT: EXACTLY this path: docs/patterns/error-handling.md
|
||||
- If file exists: STOP and report (don't overwrite)
|
||||
- If file doesn't exist: Create new
|
||||
- Use pattern template structure
|
||||
- Include code examples
|
||||
|
||||
SUCCESS: Error handling patterns documented
|
||||
- File created at exact path specified
|
||||
- Follows pattern template
|
||||
- Includes error classes and response patterns
|
||||
- No collision with other agents
|
||||
|
||||
TERMINATION:
|
||||
- Documentation complete at specified path
|
||||
- File already exists (report)
|
||||
- No error handling patterns found
|
||||
```
|
||||
|
||||
## File Coordination Checklist
|
||||
|
||||
Before launching these agents:
|
||||
|
||||
```
|
||||
📋 File Coordination Pre-Flight Check
|
||||
|
||||
Agent 1 OUTPUT: docs/patterns/authentication-flow.md
|
||||
Agent 2 OUTPUT: docs/patterns/caching-strategy.md
|
||||
Agent 3 OUTPUT: docs/patterns/error-handling.md
|
||||
|
||||
✅ All paths are explicit (no ambiguity)
|
||||
✅ All paths are unique (no two agents write same file)
|
||||
✅ All paths follow convention (docs/patterns/[name].md)
|
||||
✅ All agents instructed to check if file exists first
|
||||
✅ All agents instructed to STOP if collision detected
|
||||
|
||||
File Collision Risk: NONE
|
||||
Safe to launch in parallel: YES
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Launch All Three Agents in Parallel
|
||||
|
||||
```
|
||||
🚀 Launching 3 parallel documentation agents
|
||||
|
||||
Agent 1: Authentication Pattern → RUNNING
|
||||
TARGET: docs/patterns/authentication-flow.md
|
||||
|
||||
Agent 2: Caching Pattern → RUNNING
|
||||
TARGET: docs/patterns/caching-strategy.md
|
||||
|
||||
Agent 3: Error Handling Pattern → RUNNING
|
||||
TARGET: docs/patterns/error-handling.md
|
||||
|
||||
File coordination: ✅ All unique paths
|
||||
Collision risk: ✅ None
|
||||
Parallel safety: ✅ Confirmed
|
||||
```
|
||||
|
||||
### Monitoring for Collisions
|
||||
|
||||
```
|
||||
⏳ Agents running...
|
||||
|
||||
[Agent 1] Checking: docs/patterns/authentication-flow.md → NOT EXISTS
|
||||
[Agent 1] Safe to create → PROCEEDING
|
||||
|
||||
[Agent 2] Checking: docs/patterns/caching-strategy.md → NOT EXISTS
|
||||
[Agent 2] Safe to create → PROCEEDING
|
||||
|
||||
[Agent 3] Checking: docs/patterns/error-handling.md → NOT EXISTS
|
||||
[Agent 3] Safe to create → PROCEEDING
|
||||
|
||||
No collisions detected. All agents proceeding independently.
|
||||
```
|
||||
|
||||
### Completion
|
||||
|
||||
```
|
||||
Agent 1: COMPLETE ✅ (22 minutes)
|
||||
Created: docs/patterns/authentication-flow.md (3.2 KB)
|
||||
|
||||
Agent 2: COMPLETE ✅ (18 minutes)
|
||||
Created: docs/patterns/caching-strategy.md (2.8 KB)
|
||||
|
||||
Agent 3: COMPLETE ✅ (25 minutes)
|
||||
Created: docs/patterns/error-handling.md (4.1 KB)
|
||||
|
||||
All agents complete. No collisions occurred.
|
||||
```
|
||||
|
||||
## Results
|
||||
|
||||
```
|
||||
📁 docs/patterns/
|
||||
├── authentication-flow.md ✅ Created by Agent 1
|
||||
├── caching-strategy.md ✅ Created by Agent 2
|
||||
└── error-handling.md ✅ Created by Agent 3
|
||||
```
|
||||
|
||||
**Total time:** 25 minutes (parallel)
|
||||
**Sequential would take:** 65 minutes
|
||||
**Time saved:** 40 minutes (61% faster)
|
||||
|
||||
## Alternative Coordination Strategies
|
||||
|
||||
### Strategy 1: Directory Separation
|
||||
|
||||
If agents might create multiple files:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: docs/patterns/authentication/
|
||||
- flow.md
|
||||
- jwt-tokens.md
|
||||
- session-management.md
|
||||
|
||||
Agent 2 OUTPUT: docs/patterns/caching/
|
||||
- redis-usage.md
|
||||
- invalidation.md
|
||||
- key-naming.md
|
||||
|
||||
Agent 3 OUTPUT: docs/patterns/error-handling/
|
||||
- error-classes.md
|
||||
- response-format.md
|
||||
- recovery-patterns.md
|
||||
```
|
||||
|
||||
**Result:** Each agent owns a directory, no file collisions possible.
|
||||
|
||||
### Strategy 2: Timestamp-Based Naming
|
||||
|
||||
For logs or reports that accumulate:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: logs/auth-analysis-2025-01-24-10-30-00.md
|
||||
Agent 2 OUTPUT: logs/cache-analysis-2025-01-24-10-30-00.md
|
||||
Agent 3 OUTPUT: logs/error-analysis-2025-01-24-10-30-00.md
|
||||
```
|
||||
|
||||
**Result:** Timestamps ensure uniqueness even if same topic.
|
||||
|
||||
### Strategy 3: Agent ID Namespacing
|
||||
|
||||
When dynamic number of agents:
|
||||
|
||||
```
|
||||
For each module in [moduleA, moduleB, moduleC, moduleD]:
|
||||
Launch agent with OUTPUT: analysis/module-${MODULE_NAME}.md
|
||||
|
||||
Results:
|
||||
- analysis/module-moduleA.md
|
||||
- analysis/module-moduleB.md
|
||||
- analysis/module-moduleC.md
|
||||
- analysis/module-moduleD.md
|
||||
```
|
||||
|
||||
**Result:** Template-based naming prevents collisions.
|
||||
|
||||
## What Could Go Wrong (Anti-Patterns)
|
||||
|
||||
### ❌ Anti-Pattern 1: Ambiguous Paths
|
||||
|
||||
```
|
||||
BAD:
|
||||
Agent 1 OUTPUT: "Create pattern documentation"
|
||||
Agent 2 OUTPUT: "Document caching patterns"
|
||||
|
||||
Problem: Where exactly? What filename?
|
||||
Result: Agents might choose same name or wrong location
|
||||
```
|
||||
|
||||
### ❌ Anti-Pattern 2: Overlapping Domains
|
||||
|
||||
```
|
||||
BAD:
|
||||
Agent 1 FOCUS: "Document authentication and security"
|
||||
Agent 2 FOCUS: "Document security patterns"
|
||||
|
||||
Problem: Both might document auth security!
|
||||
Result: Duplicate or conflicting documentation
|
||||
```
|
||||
|
||||
**Fix:** Clear FOCUS boundaries, explicit EXCLUDE
|
||||
|
||||
### ❌ Anti-Pattern 3: No Existence Check
|
||||
|
||||
```
|
||||
BAD:
|
||||
OUTPUT: docs/patterns/auth.md
|
||||
(No instruction to check if exists)
|
||||
|
||||
Problem: If file exists, agent might overwrite
|
||||
Result: Lost documentation
|
||||
```
|
||||
|
||||
**Fix:** Always include existence check in FOCUS or OUTPUT
|
||||
|
||||
### ❌ Anti-Pattern 4: Generic Filenames
|
||||
|
||||
```
|
||||
BAD:
|
||||
Agent 1 OUTPUT: docs/patterns/pattern.md
|
||||
Agent 2 OUTPUT: docs/patterns/patterns.md
|
||||
Agent 3 OUTPUT: docs/patterns/pattern-doc.md
|
||||
|
||||
Problem: All similar, confusing, might collide
|
||||
Result: Unclear which agent created what
|
||||
```
|
||||
|
||||
**Fix:** Descriptive, specific filenames
|
||||
|
||||
## File Coordination Best Practices
|
||||
|
||||
### 1. Explicit Paths
|
||||
|
||||
✅ **Always specify exact OUTPUT path:**
|
||||
```
|
||||
OUTPUT: docs/patterns/authentication-flow.md
|
||||
NOT: "Document authentication patterns"
|
||||
```
|
||||
|
||||
### 2. Unique Names
|
||||
|
||||
✅ **Ensure all agents have unique filenames:**
|
||||
```
|
||||
Before launching:
|
||||
- Agent 1: authentication-flow.md
|
||||
- Agent 2: caching-strategy.md
|
||||
- Agent 3: error-handling.md
|
||||
✅ All unique → SAFE
|
||||
```
|
||||
|
||||
### 3. Existence Checks
|
||||
|
||||
✅ **Instruct agents to check before creating:**
|
||||
```
|
||||
OUTPUT: docs/patterns/authentication-flow.md
|
||||
- If file exists: STOP and report (don't overwrite)
|
||||
- If file doesn't exist: Create new
|
||||
```
|
||||
|
||||
### 4. Clear Boundaries
|
||||
|
||||
✅ **Use EXCLUDE to prevent overlap:**
|
||||
```
|
||||
Agent 1:
|
||||
FOCUS: Document authentication
|
||||
EXCLUDE: Don't document caching (Agent 2) or errors (Agent 3)
|
||||
|
||||
Agent 2:
|
||||
FOCUS: Document caching
|
||||
EXCLUDE: Don't document auth (Agent 1) or errors (Agent 3)
|
||||
```
|
||||
|
||||
### 5. Validation
|
||||
|
||||
✅ **Check coordination before launching:**
|
||||
```
|
||||
Checklist:
|
||||
- [ ] All paths explicit
|
||||
- [ ] All paths unique
|
||||
- [ ] All agents have existence checks
|
||||
- [ ] Clear FOCUS boundaries
|
||||
- [ ] No overlap in domains
|
||||
```
|
||||
|
||||
## Integration with Documentation Skill
|
||||
|
||||
When these agents complete, documentation skill may activate:
|
||||
|
||||
```
|
||||
Agent 1 completes → Creates authentication-flow.md
|
||||
↓
|
||||
Documentation skill notices "pattern" created
|
||||
↓
|
||||
Checks: Is this in correct location? (docs/patterns/ ✅)
|
||||
Checks: Does it follow template? (✅)
|
||||
Checks: Should it be cross-referenced? (Yes)
|
||||
↓
|
||||
Documentation skill adds cross-references:
|
||||
- Links to related authentication interfaces
|
||||
- Links to domain rules about user permissions
|
||||
```
|
||||
|
||||
**Coordination:** Agent-delegation ensures unique paths, documentation skill ensures quality and linking.
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### What Worked
|
||||
|
||||
✅ **Explicit paths:** Zero ambiguity, zero collisions
|
||||
✅ **Existence checks:** Prevented accidental overwrites
|
||||
✅ **Clear boundaries:** No domain overlap
|
||||
✅ **Parallel execution:** 61% time savings
|
||||
|
||||
### What to Watch For
|
||||
|
||||
⚠️ **Naming conventions:** Ensure consistency (kebab-case vs snake_case)
|
||||
⚠️ **Template usage:** All agents should use same template
|
||||
⚠️ **Directory structure:** Verify docs/patterns/ exists before launching
|
||||
|
||||
## Reusable Coordination Template
|
||||
|
||||
For any parallel file creation:
|
||||
|
||||
```
|
||||
1. List all files to be created
|
||||
2. Verify all paths are unique
|
||||
3. Add existence checks to OUTPUT
|
||||
4. Use EXCLUDE to prevent overlap
|
||||
5. Launch in parallel with confidence
|
||||
```
|
||||
|
||||
**This prevents:**
|
||||
- File path collisions
|
||||
- Accidental overwrites
|
||||
- Domain overlap
|
||||
- Naming inconsistencies
|
||||
337
skills/agent-delegation/examples/parallel-research.md
Normal file
337
skills/agent-delegation/examples/parallel-research.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# Example: Parallel Research Delegation
|
||||
|
||||
This example shows how to decompose a research task into parallel specialist activities.
|
||||
|
||||
## Scenario
|
||||
|
||||
**User Request:** "Research competitive landscape for our B2B SaaS pricing strategy"
|
||||
|
||||
## Task Decomposition
|
||||
|
||||
```
|
||||
Original Task: Research competitive landscape for B2B SaaS pricing
|
||||
|
||||
Activities Identified:
|
||||
1. Analyze Competitor A (Salesforce) pricing
|
||||
- Expertise: Market research
|
||||
- Output: Pricing analysis document
|
||||
- Dependencies: None
|
||||
|
||||
2. Analyze Competitor B (HubSpot) pricing
|
||||
- Expertise: Market research
|
||||
- Output: Pricing analysis document
|
||||
- Dependencies: None
|
||||
|
||||
3. Analyze Competitor C (Zendesk) pricing
|
||||
- Expertise: Market research
|
||||
- Output: Pricing analysis document
|
||||
- Dependencies: None
|
||||
|
||||
4. Synthesize competitive findings
|
||||
- Expertise: Strategic analysis
|
||||
- Output: Unified competitive strategy
|
||||
- Dependencies: Activities 1, 2, 3
|
||||
|
||||
Execution Strategy: Mixed
|
||||
- Parallel: Activities 1-3 (independent research)
|
||||
- Sequential: Activity 4 (requires all results)
|
||||
|
||||
Reasoning: Each competitor analysis is independent. Synthesis must wait for all analyses to complete.
|
||||
```
|
||||
|
||||
## Agent Prompts Generated
|
||||
|
||||
### Agent 1: Salesforce Analysis
|
||||
|
||||
```
|
||||
FOCUS: Research Salesforce's B2B SaaS pricing strategy
|
||||
- Identify all pricing tiers (Essentials, Professional, Enterprise, Unlimited)
|
||||
- Map features to each tier
|
||||
- Note promotional strategies and discounts
|
||||
- Calculate price-per-user for each tier
|
||||
- Identify what features drive tier upgrades
|
||||
|
||||
EXCLUDE:
|
||||
- Don't analyze their technology stack or implementation
|
||||
- Don't make pricing recommendations yet (synthesis phase)
|
||||
- Don't compare to other competitors (separate analyses)
|
||||
- Don't analyze Salesforce Platform (focus on CRM product)
|
||||
|
||||
CONTEXT: We're researching competitive landscape for our B2B SaaS pricing strategy.
|
||||
- Target market: Mid-market companies (100-500 employees)
|
||||
- Looking for pricing patterns and positioning insights
|
||||
- Focus on transparent, public pricing only
|
||||
|
||||
OUTPUT: Structured analysis document including:
|
||||
- Pricing Tiers Table (tier name, price, billing cycle)
|
||||
- Feature Matrix by Tier (features mapped to each tier)
|
||||
- Key Insights (3-5 bullet points about their strategy)
|
||||
- Notable Patterns (what we can learn from their approach)
|
||||
- Competitive Positioning (how they position each tier)
|
||||
|
||||
SUCCESS: Complete analysis with actionable data
|
||||
- All publicly available tiers documented
|
||||
- Features accurately mapped to tiers
|
||||
- Insights are specific and evidence-based
|
||||
- Patterns identified are relevant to our market
|
||||
|
||||
TERMINATION:
|
||||
- Analysis complete with all sections filled
|
||||
- Information not publicly available (document what's missing)
|
||||
- Maximum 2 hours of research time reached
|
||||
```
|
||||
|
||||
### Agent 2: HubSpot Analysis
|
||||
|
||||
```
|
||||
FOCUS: Research HubSpot's B2B SaaS pricing strategy
|
||||
- Identify all pricing tiers (Starter, Professional, Enterprise)
|
||||
- Map features to each tier
|
||||
- Note freemium offering and upgrade triggers
|
||||
- Calculate price-per-contact for marketing hub
|
||||
- Identify bundling strategy across products
|
||||
|
||||
EXCLUDE:
|
||||
- Don't analyze technology implementation
|
||||
- Don't make pricing recommendations yet
|
||||
- Don't compare to other competitors
|
||||
- Don't analyze HubSpot Academy or services pricing
|
||||
|
||||
CONTEXT: Competitive landscape research for B2B SaaS pricing.
|
||||
- Target market: Mid-market companies (100-500 employees)
|
||||
- Interest in freemium-to-paid conversion strategies
|
||||
- Focus on Marketing Hub and Sales Hub pricing
|
||||
|
||||
OUTPUT: Structured analysis document including:
|
||||
- Pricing Tiers Table
|
||||
- Feature Matrix by Tier
|
||||
- Freemium Analysis (what's free, what triggers upgrade)
|
||||
- Key Insights (3-5 bullet points)
|
||||
- Bundling Strategy (how products bundle together)
|
||||
- Notable Patterns
|
||||
|
||||
SUCCESS: Complete analysis with freemium insights
|
||||
- All tiers documented
|
||||
- Freemium model understood
|
||||
- Bundle pricing analyzed
|
||||
- Insights are actionable
|
||||
|
||||
TERMINATION:
|
||||
- Analysis complete
|
||||
- Information unavailable
|
||||
- 2 hours research time reached
|
||||
```
|
||||
|
||||
### Agent 3: Zendesk Analysis
|
||||
|
||||
```
|
||||
FOCUS: Research Zendesk's B2B SaaS pricing strategy
|
||||
- Identify all pricing tiers (Suite Team, Growth, Professional, Enterprise)
|
||||
- Map features to each tier
|
||||
- Note per-agent pricing model
|
||||
- Analyze add-on pricing strategy
|
||||
- Identify what drives customer to higher tiers
|
||||
|
||||
EXCLUDE:
|
||||
- Don't analyze implementation details
|
||||
- Don't make recommendations yet
|
||||
- Don't compare to competitors
|
||||
- Don't analyze Zendesk Sell (focus on Support product)
|
||||
|
||||
CONTEXT: Competitive research for B2B SaaS pricing strategy.
|
||||
- Target market: Mid-market companies
|
||||
- Interest in per-seat vs per-usage pricing models
|
||||
- Focus on customer support software pricing
|
||||
|
||||
OUTPUT: Structured analysis including:
|
||||
- Pricing Tiers Table
|
||||
- Feature Matrix by Tier
|
||||
- Per-Agent Economics (cost per agent at scale)
|
||||
- Add-On Pricing (what extras cost money)
|
||||
- Key Insights (3-5 bullet points)
|
||||
- Upgrade Drivers (what makes customers move up tiers)
|
||||
|
||||
SUCCESS: Complete analysis with per-seat insights
|
||||
- All tiers documented
|
||||
- Per-agent model understood
|
||||
- Add-on strategy mapped
|
||||
- Insights are specific
|
||||
|
||||
TERMINATION:
|
||||
- Analysis complete
|
||||
- Information unavailable
|
||||
- 2 hours research reached
|
||||
```
|
||||
|
||||
### Agent 4: Synthesis (Sequential, after 1-3)
|
||||
|
||||
```
|
||||
FOCUS: Synthesize competitive pricing findings into unified strategy insights
|
||||
|
||||
EXCLUDE:
|
||||
- Don't create our pricing (separate decision)
|
||||
- Don't add new competitor research
|
||||
- Don't analyze product features (stick to pricing patterns)
|
||||
|
||||
CONTEXT: We have three completed competitor analyses.
|
||||
- Salesforce analysis: [Results from Agent 1]
|
||||
- HubSpot analysis: [Results from Agent 2]
|
||||
- Zendesk analysis: [Results from Agent 3]
|
||||
- Goal: Extract patterns and strategic insights
|
||||
|
||||
OUTPUT: Competitive Pricing Strategy Document including:
|
||||
- Cross-Competitor Patterns (themes across all three)
|
||||
- Pricing Model Comparison (per-user vs per-contact vs per-usage)
|
||||
- Tier Strategy Analysis (how competitors structure tiers)
|
||||
- Freemium Insights (who uses it, how it works)
|
||||
- Feature Differentiation (what features separate tiers)
|
||||
- Positioning Opportunities (gaps or opportunities for us)
|
||||
- Strategic Recommendations (3-5 actionable insights)
|
||||
|
||||
SUCCESS: Unified synthesis with strategic value
|
||||
- Patterns identified across competitors
|
||||
- Comparisons are fair and evidence-based
|
||||
- Recommendations are actionable
|
||||
- No contradiction between analyses
|
||||
|
||||
TERMINATION:
|
||||
- Synthesis complete
|
||||
- Conflicting data needs clarification (escalate)
|
||||
- All sections filled
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 1: Launch Parallel Research (Agents 1-3)
|
||||
|
||||
```
|
||||
🚀 Launching 3 parallel research agents
|
||||
|
||||
Agent 1: Salesforce Analysis → RUNNING
|
||||
Agent 2: HubSpot Analysis → RUNNING
|
||||
Agent 3: Zendesk Analysis → RUNNING
|
||||
|
||||
File Coordination Check:
|
||||
✅ Agent 1 OUTPUT: research/salesforce-pricing.md
|
||||
✅ Agent 2 OUTPUT: research/hubspot-pricing.md
|
||||
✅ Agent 3 OUTPUT: zendesk-pricing.md
|
||||
✅ All paths unique - No collision risk
|
||||
|
||||
Parallel Safety Check:
|
||||
✅ Independent tasks - No dependencies
|
||||
✅ Read-only research - No shared state
|
||||
✅ Separate validation - Each can be reviewed independently
|
||||
✅ Won't block - Different data sources
|
||||
|
||||
Status: ✅ SAFE FOR PARALLEL EXECUTION
|
||||
```
|
||||
|
||||
### Phase 2: Await Completion
|
||||
|
||||
```
|
||||
⏳ Waiting for parallel agents...
|
||||
|
||||
Agent 1: COMPLETE ✅ (45 minutes)
|
||||
- Salesforce analysis delivered
|
||||
- All sections complete
|
||||
- 4 tiers documented
|
||||
|
||||
Agent 2: COMPLETE ✅ (52 minutes)
|
||||
- HubSpot analysis delivered
|
||||
- Freemium model analyzed
|
||||
- 3 tiers + free tier documented
|
||||
|
||||
Agent 3: COMPLETE ✅ (38 minutes)
|
||||
- Zendesk analysis delivered
|
||||
- Per-agent model mapped
|
||||
- 4 tiers + add-ons documented
|
||||
|
||||
All parallel agents complete. Proceeding to synthesis.
|
||||
```
|
||||
|
||||
### Phase 3: Launch Synthesis (Agent 4)
|
||||
|
||||
```
|
||||
🚀 Launching synthesis agent
|
||||
|
||||
Agent 4: Competitive Synthesis → RUNNING
|
||||
|
||||
Context provided:
|
||||
- Salesforce results (from Agent 1)
|
||||
- HubSpot results (from Agent 2)
|
||||
- Zendesk results (from Agent 3)
|
||||
|
||||
Agent 4: COMPLETE ✅ (25 minutes)
|
||||
- Cross-competitor patterns identified
|
||||
- 5 strategic recommendations generated
|
||||
- Positioning opportunities highlighted
|
||||
```
|
||||
|
||||
## Results
|
||||
|
||||
### Total Time: 52 minutes (parallel) + 25 minutes (synthesis) = 77 minutes
|
||||
|
||||
**Compare to sequential:** 45 + 52 + 38 + 25 = 160 minutes
|
||||
**Time saved:** 83 minutes (52% faster)
|
||||
|
||||
### Deliverables
|
||||
|
||||
```
|
||||
📁 research/
|
||||
├── salesforce-pricing.md (Agent 1)
|
||||
├── hubspot-pricing.md (Agent 2)
|
||||
├── zendesk-pricing.md (Agent 3)
|
||||
└── competitive-strategy.md (Agent 4 synthesis)
|
||||
```
|
||||
|
||||
### Key Insights Generated
|
||||
|
||||
From the synthesis agent:
|
||||
|
||||
1. **Tiering Pattern:** All three use 3-4 tier structure with similar progression (basic → professional → enterprise)
|
||||
|
||||
2. **Pricing Models:** Mixed approaches
|
||||
- Salesforce: Per-user, all-inclusive features
|
||||
- HubSpot: Per-contact, freemium base
|
||||
- Zendesk: Per-agent, add-on marketplace
|
||||
|
||||
3. **Feature Gating:** Core features in all tiers, advanced analytics/automation in top tiers
|
||||
|
||||
4. **Freemium:** Only HubSpot uses freemium successfully (strong upgrade triggers identified)
|
||||
|
||||
5. **Opportunity:** Gap in mid-market transparent pricing - competitors hide "contact sales" behind top tier
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### What Worked Well
|
||||
|
||||
✅ **Parallel execution:** Saved 52% time
|
||||
✅ **Independent research:** No coordination overhead
|
||||
✅ **Synthesis phase:** Unified findings effectively
|
||||
✅ **Unique file paths:** No collisions
|
||||
✅ **Explicit FOCUS/EXCLUDE:** Agents stayed on task
|
||||
|
||||
### Improvements for Next Time
|
||||
|
||||
- Add time limits to prevent research rabbit holes
|
||||
- Specify exact format (all agents used slightly different table formats)
|
||||
- Request specific pricing data points (some agents missed cost-per-user calculations)
|
||||
- Consider adding validation agent before synthesis (check data accuracy)
|
||||
|
||||
## Reusable Template
|
||||
|
||||
This pattern works for any parallel research:
|
||||
|
||||
```
|
||||
1. Decompose research into independent topics
|
||||
2. Create identical FOCUS/EXCLUDE templates
|
||||
3. Customize context and output paths only
|
||||
4. Launch all in parallel
|
||||
5. Synthesis agent consolidates findings
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Researching multiple competitors
|
||||
- Analyzing multiple technologies
|
||||
- Gathering multiple data sources
|
||||
- Interviewing multiple stakeholders
|
||||
504
skills/agent-delegation/examples/sequential-build.md
Normal file
504
skills/agent-delegation/examples/sequential-build.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# Example: Sequential Build Delegation
|
||||
|
||||
This example shows how to coordinate dependent implementation tasks that must execute sequentially.
|
||||
|
||||
## Scenario
|
||||
|
||||
**User Request:** "Implement JWT authentication for our REST API"
|
||||
|
||||
## Task Decomposition
|
||||
|
||||
```
|
||||
Original Task: Implement JWT authentication for REST API
|
||||
|
||||
Activities Identified:
|
||||
1. Design authentication database schema
|
||||
- Expertise: Database design
|
||||
- Output: Schema design document
|
||||
- Dependencies: None
|
||||
|
||||
2. Create database migration
|
||||
- Expertise: Database implementation
|
||||
- Output: Migration files
|
||||
- Dependencies: Activity 1 (schema design)
|
||||
|
||||
3. Implement authentication middleware
|
||||
- Expertise: Backend development
|
||||
- Output: JWT middleware code
|
||||
- Dependencies: Activity 2 (tables must exist)
|
||||
|
||||
4. Create auth endpoints (login/logout)
|
||||
- Expertise: Backend development
|
||||
- Output: Auth routes and controllers
|
||||
- Dependencies: Activity 3 (middleware needed)
|
||||
|
||||
5. Add tests for auth flow
|
||||
- Expertise: Test automation
|
||||
- Output: Integration tests
|
||||
- Dependencies: Activity 4 (endpoints must work)
|
||||
|
||||
Execution Strategy: Sequential
|
||||
Reasoning: Each activity depends on the previous one's output. No parallelization possible in this chain.
|
||||
|
||||
Dependency Chain: 1 → 2 → 3 → 4 → 5
|
||||
```
|
||||
|
||||
## Agent Prompts Generated
|
||||
|
||||
### Agent 1: Schema Design (First)
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, understand the environment:
|
||||
- Check existing database structure: ls migrations/ or db/schema/
|
||||
- Identify database system: PostgreSQL, MySQL, SQLite?
|
||||
- Review existing table patterns: user-related tables
|
||||
- Note naming conventions: snake_case, camelCase, PascalCase?
|
||||
|
||||
FOCUS: Design database schema for JWT authentication
|
||||
- Users table (if not exists) with email, password_hash
|
||||
- Sessions table for active JWT tokens
|
||||
- Include created_at, updated_at timestamps
|
||||
- Design appropriate indexes for performance
|
||||
- Plan foreign key relationships
|
||||
|
||||
EXCLUDE:
|
||||
- Don't create the migration yet (next task)
|
||||
- Don't implement OAuth tables (separate feature)
|
||||
- Don't modify existing user table if it exists
|
||||
- Don't add two-factor auth tables (not in scope)
|
||||
|
||||
CONTEXT: Building JWT authentication for REST API.
|
||||
- From security requirements: bcrypt hashing, cost factor 12
|
||||
- Session expiry: 24 hours
|
||||
- Email must be unique
|
||||
- Follow project database conventions exactly
|
||||
|
||||
OUTPUT: Schema design document at docs/patterns/auth-database-schema.md
|
||||
- Table definitions with column types
|
||||
- Indexes and constraints
|
||||
- Foreign key relationships
|
||||
- Example data
|
||||
|
||||
SUCCESS: Schema designed and documented
|
||||
- All required fields included
|
||||
- Performance indexes identified
|
||||
- Follows project conventions
|
||||
- Ready for migration implementation
|
||||
|
||||
TERMINATION:
|
||||
- Design complete and documented
|
||||
- Blocked by missing existing schema info
|
||||
```
|
||||
|
||||
### Agent 2: Database Migration (After Agent 1)
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, understand the environment:
|
||||
- Check migration system: Knex, Sequelize, TypeORM, raw SQL?
|
||||
- Find migration directory location
|
||||
- Review existing migration file format
|
||||
- Note up/down pattern used
|
||||
|
||||
FOCUS: Create database migration for authentication tables
|
||||
- Implement users table from schema design
|
||||
- Implement sessions table from schema design
|
||||
- Add all indexes from schema design
|
||||
- Create both up (create) and down (drop) migrations
|
||||
- Follow migration naming conventions
|
||||
|
||||
EXCLUDE:
|
||||
- Don't run the migration yet (separate step)
|
||||
- Don't seed data (separate concern)
|
||||
- Don't modify existing migrations
|
||||
- Don't add tables not in schema design
|
||||
|
||||
CONTEXT: Implementing schema designed in previous step.
|
||||
- Schema document: docs/patterns/auth-database-schema.md
|
||||
- Tables: users (email, password_hash, created_at, updated_at)
|
||||
- Tables: sessions (id, user_id, token_hash, expires_at, created_at)
|
||||
- Indexes: users.email (unique), sessions.token_hash, sessions.user_id
|
||||
|
||||
OUTPUT: Migration file at [DISCOVERED_MIGRATION_PATH]/[timestamp]_create_auth_tables.js
|
||||
- Up migration creates tables and indexes
|
||||
- Down migration drops tables cleanly
|
||||
- Follows project migration format
|
||||
|
||||
SUCCESS: Migration created and ready to run
|
||||
- Matches schema design exactly
|
||||
- Both up and down work correctly
|
||||
- Follows project patterns
|
||||
- No syntax errors
|
||||
|
||||
TERMINATION:
|
||||
- Migration file created successfully
|
||||
- Blocked by unclear migration system
|
||||
- Migration format doesn't match project (document issue)
|
||||
```
|
||||
|
||||
### Agent 3: JWT Middleware (After Agent 2)
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, understand the environment:
|
||||
- Find existing middleware location: src/middleware/ or app/middleware/?
|
||||
- Check JWT library in use: jsonwebtoken, jose, other?
|
||||
- Review existing middleware patterns
|
||||
- Note error handling style used
|
||||
|
||||
FOCUS: Implement JWT authentication middleware
|
||||
- Verify JWT token from Authorization header
|
||||
- Decode and validate token
|
||||
- Check token against sessions table (not blacklisted)
|
||||
- Attach user object to request
|
||||
- Handle missing/invalid/expired tokens appropriately
|
||||
|
||||
EXCLUDE:
|
||||
- Don't implement login/logout endpoints (next task)
|
||||
- Don't implement token refresh (not in scope)
|
||||
- Don't add rate limiting (separate concern)
|
||||
- Don't implement permission checking (just authentication)
|
||||
|
||||
CONTEXT: JWT middleware for REST API authentication.
|
||||
- JWT secret: from environment variable JWT_SECRET
|
||||
- Token expiry: 24 hours
|
||||
- Sessions table: check if token_hash exists and not expired
|
||||
- Error responses: 401 for invalid/missing token
|
||||
- Follow project error handling patterns
|
||||
|
||||
OUTPUT: Middleware file at [DISCOVERED_LOCATION]/auth.middleware.ts
|
||||
- verifyJWT function (main middleware)
|
||||
- Helper functions (decode, validate, etc.)
|
||||
- Error handling for all cases
|
||||
- TypeScript types if applicable
|
||||
|
||||
SUCCESS: Middleware implemented and ready to use
|
||||
- Verifies JWT correctly
|
||||
- Checks session validity
|
||||
- Attaches user to request
|
||||
- Handles all error cases
|
||||
- Follows project patterns
|
||||
|
||||
TERMINATION:
|
||||
- Middleware complete
|
||||
- Blocked by missing JWT library
|
||||
- Database connection pattern unclear
|
||||
```
|
||||
|
||||
### Agent 4: Auth Endpoints (After Agent 3)
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, understand the environment:
|
||||
- Find routes directory: src/routes/ or app/routes/?
|
||||
- Check router library: Express, Fastify, Koa?
|
||||
- Review existing route patterns
|
||||
- Note controller/handler organization
|
||||
|
||||
FOCUS: Implement authentication endpoints
|
||||
- POST /api/auth/login (email, password → JWT token)
|
||||
- POST /api/auth/logout (invalidate current session)
|
||||
- Use auth middleware from previous step
|
||||
- Create sessions table entry on login
|
||||
- Remove sessions table entry on logout
|
||||
|
||||
EXCLUDE:
|
||||
- Don't implement registration (separate feature)
|
||||
- Don't implement password reset (separate feature)
|
||||
- Don't add OAuth endpoints (separate feature)
|
||||
- Don't implement GET /me endpoint (separate task)
|
||||
|
||||
CONTEXT: Auth endpoints using JWT middleware implemented in previous step.
|
||||
- Middleware location: [from Agent 3 OUTPUT]
|
||||
- Login validates: email format, password against bcrypt hash
|
||||
- Login creates: session entry, JWT token with user_id claim
|
||||
- Logout requires: valid JWT (use middleware)
|
||||
- Logout invalidates: session entry in database
|
||||
|
||||
OUTPUT:
|
||||
- Routes file at [DISCOVERED_LOCATION]/auth.routes.ts
|
||||
- Controller file at [DISCOVERED_LOCATION]/auth.controller.ts
|
||||
- Follow project route organization pattern
|
||||
|
||||
SUCCESS: Endpoints implemented and functional
|
||||
- Login validates credentials correctly
|
||||
- Login returns valid JWT
|
||||
- Logout requires authentication
|
||||
- Logout invalidates session
|
||||
- All errors handled appropriately
|
||||
- Follows project patterns
|
||||
|
||||
TERMINATION:
|
||||
- Endpoints complete
|
||||
- Blocked by unclear auth middleware interface
|
||||
- bcrypt usage pattern unclear
|
||||
```
|
||||
|
||||
### Agent 5: Integration Tests (After Agent 4)
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, understand the environment:
|
||||
- Find test directory: tests/, __tests__/, spec/?
|
||||
- Identify test framework: Jest, Mocha, Vitest?
|
||||
- Review existing test patterns
|
||||
- Note test database setup approach
|
||||
|
||||
FOCUS: Create integration tests for authentication flow
|
||||
- Test successful login (valid credentials → JWT returned)
|
||||
- Test failed login (invalid credentials → 401)
|
||||
- Test logout (valid JWT → session invalidated)
|
||||
- Test protected route with valid JWT (→ 200)
|
||||
- Test protected route with invalid JWT (→ 401)
|
||||
- Test protected route with no JWT (→ 401)
|
||||
|
||||
EXCLUDE:
|
||||
- Don't test registration (not implemented)
|
||||
- Don't test password reset (not implemented)
|
||||
- Don't unit test internal functions (integration tests only)
|
||||
- Don't test OAuth flows (not implemented)
|
||||
|
||||
CONTEXT: Testing JWT authentication implemented in previous steps.
|
||||
- Endpoints: POST /api/auth/login, POST /api/auth/logout
|
||||
- Middleware: JWT verification from auth.middleware.ts
|
||||
- Test database: Use test database, clean between tests
|
||||
- Follow project testing patterns exactly
|
||||
|
||||
OUTPUT: Test file at [DISCOVERED_LOCATION]/auth.integration.test.ts
|
||||
- All test cases listed in FOCUS
|
||||
- Setup and teardown (database, test user)
|
||||
- Clear test descriptions
|
||||
- Assertions verify correct behavior
|
||||
|
||||
SUCCESS: Complete test coverage for auth flow
|
||||
- All tests pass
|
||||
- Tests are independent (can run in any order)
|
||||
- Database cleanup works correctly
|
||||
- Follows project test patterns
|
||||
- Coverage includes happy path and error cases
|
||||
|
||||
TERMINATION:
|
||||
- Tests complete and passing
|
||||
- Blocked by test framework unclear
|
||||
- Test database setup pattern unclear
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 1: Schema Design (Agent 1)
|
||||
|
||||
```
|
||||
🚀 Launching Agent 1: Schema Design
|
||||
|
||||
Status: RUNNING
|
||||
Time: 15 minutes
|
||||
|
||||
Agent 1: COMPLETE ✅
|
||||
Output: docs/patterns/auth-database-schema.md
|
||||
|
||||
Deliverables:
|
||||
- Users table design (5 columns + indexes)
|
||||
- Sessions table design (5 columns + indexes)
|
||||
- Foreign key relationship documented
|
||||
- Performance considerations noted
|
||||
|
||||
Validation: ✅ Ready for migration implementation
|
||||
```
|
||||
|
||||
### Phase 2: Database Migration (Agent 2)
|
||||
|
||||
```
|
||||
🚀 Launching Agent 2: Database Migration
|
||||
Dependencies: Agent 1 complete ✅
|
||||
|
||||
Context provided:
|
||||
- Schema document from Agent 1
|
||||
- Table definitions and indexes
|
||||
|
||||
Status: RUNNING
|
||||
Time: 20 minutes
|
||||
|
||||
Agent 2: COMPLETE ✅
|
||||
Output: migrations/20250124120000_create_auth_tables.js
|
||||
|
||||
Deliverables:
|
||||
- Up migration creates both tables
|
||||
- Down migration drops cleanly
|
||||
- All indexes included
|
||||
- Follows Knex migration pattern
|
||||
|
||||
Validation: ✅ Ready for middleware implementation
|
||||
```
|
||||
|
||||
### Phase 3: JWT Middleware (Agent 3)
|
||||
|
||||
```
|
||||
🚀 Launching Agent 3: JWT Middleware
|
||||
Dependencies: Agent 2 complete ✅
|
||||
|
||||
Context provided:
|
||||
- Migration created tables
|
||||
- Database schema known
|
||||
|
||||
Status: RUNNING
|
||||
Time: 30 minutes
|
||||
|
||||
Agent 3: COMPLETE ✅
|
||||
Output: src/middleware/auth.middleware.ts
|
||||
|
||||
Deliverables:
|
||||
- verifyJWT middleware function
|
||||
- Token validation logic
|
||||
- Session checking against database
|
||||
- Error handling for all cases
|
||||
|
||||
Validation: ✅ Ready for endpoint implementation
|
||||
```
|
||||
|
||||
### Phase 4: Auth Endpoints (Agent 4)
|
||||
|
||||
```
|
||||
🚀 Launching Agent 4: Auth Endpoints
|
||||
Dependencies: Agent 3 complete ✅
|
||||
|
||||
Context provided:
|
||||
- Middleware from Agent 3
|
||||
- Function signatures and usage
|
||||
|
||||
Status: RUNNING
|
||||
Time: 35 minutes
|
||||
|
||||
Agent 4: COMPLETE ✅
|
||||
Output:
|
||||
- src/routes/auth.routes.ts
|
||||
- src/controllers/auth.controller.ts
|
||||
|
||||
Deliverables:
|
||||
- POST /api/auth/login endpoint
|
||||
- POST /api/auth/logout endpoint
|
||||
- Integration with middleware
|
||||
- Error responses
|
||||
|
||||
Validation: ✅ Ready for testing
|
||||
```
|
||||
|
||||
### Phase 5: Integration Tests (Agent 5)
|
||||
|
||||
```
|
||||
🚀 Launching Agent 5: Integration Tests
|
||||
Dependencies: Agent 4 complete ✅
|
||||
|
||||
Context provided:
|
||||
- All endpoints from Agent 4
|
||||
- Middleware from Agent 3
|
||||
- Expected behavior
|
||||
|
||||
Status: RUNNING
|
||||
Time: 25 minutes
|
||||
|
||||
Agent 5: COMPLETE ✅
|
||||
Output: tests/integration/auth.test.ts
|
||||
|
||||
Deliverables:
|
||||
- 6 integration tests
|
||||
- Database setup/teardown
|
||||
- All tests passing ✅
|
||||
- 95% coverage of auth flow
|
||||
|
||||
Validation: ✅ Feature complete and tested
|
||||
```
|
||||
|
||||
## Results
|
||||
|
||||
### Total Time: 125 minutes (sequential)
|
||||
|
||||
**Sequential necessary:** Each task depends on previous
|
||||
**No parallelization possible** in this dependency chain
|
||||
|
||||
### Context Accumulation
|
||||
|
||||
Each agent received growing context:
|
||||
|
||||
- Agent 1: Fresh start
|
||||
- Agent 2: Agent 1's schema design
|
||||
- Agent 3: Agent 2's migration + Agent 1's schema
|
||||
- Agent 4: Agent 3's middleware + all prior context
|
||||
- Agent 5: All previous implementations
|
||||
|
||||
### Deliverables
|
||||
|
||||
```
|
||||
📁 Project structure:
|
||||
├── docs/patterns/
|
||||
│ └── auth-database-schema.md (Agent 1)
|
||||
├── migrations/
|
||||
│ └── 20250124120000_create_auth_tables.js (Agent 2)
|
||||
├── src/
|
||||
│ ├── middleware/
|
||||
│ │ └── auth.middleware.ts (Agent 3)
|
||||
│ ├── routes/
|
||||
│ │ └── auth.routes.ts (Agent 4)
|
||||
│ └── controllers/
|
||||
│ └── auth.controller.ts (Agent 4)
|
||||
└── tests/integration/
|
||||
└── auth.test.ts (Agent 5)
|
||||
```
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### What Worked Well
|
||||
|
||||
✅ **Clear dependency chain:** Each agent knew exactly what it needed
|
||||
✅ **Context accumulation:** Prior outputs informed each subsequent agent
|
||||
✅ **DISCOVERY_FIRST:** Ensured consistency with project patterns
|
||||
✅ **Validation at each step:** Caught issues before they propagated
|
||||
|
||||
### Challenges Encountered
|
||||
|
||||
⚠️ **Agent 2 Issue:** Initial migration didn't match project format
|
||||
- **Solution:** Retry with more specific Knex pattern in CONTEXT
|
||||
- **Lesson:** DISCOVERY_FIRST examples critical
|
||||
|
||||
⚠️ **Agent 3 Issue:** Used wrong JWT library (jose instead of jsonwebtoken)
|
||||
- **Solution:** More explicit in EXCLUDE and CONTEXT
|
||||
- **Lesson:** Specify exact libraries when project uses specific ones
|
||||
|
||||
⚠️ **Agent 5 Issue:** Tests didn't clean up database properly
|
||||
- **Solution:** Retry with explicit teardown requirements
|
||||
- **Lesson:** Test isolation must be explicit in SUCCESS criteria
|
||||
|
||||
### Improvements for Next Time
|
||||
|
||||
1. **Specify exact libraries** in CONTEXT (don't assume agent will discover)
|
||||
2. **Include output of previous agent** verbatim in next agent's CONTEXT
|
||||
3. **Validation step between agents** to catch issues before next dependency
|
||||
4. **Checkpoint approach:** Allow user to review after each agent before launching next
|
||||
|
||||
## Reusable Template
|
||||
|
||||
This pattern works for any sequential build:
|
||||
|
||||
```
|
||||
1. Identify dependency chain (what depends on what)
|
||||
2. Order activities by dependencies
|
||||
3. Each agent's CONTEXT includes prior agent outputs
|
||||
4. Launch sequentially, validate each before next
|
||||
5. Accumulate context as you go
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Building implementation layers (DB → Logic → API → UI)
|
||||
- Pipeline-style workflows (Design → Build → Test → Deploy)
|
||||
- Learning workflows (Research → Design → Implement → Validate)
|
||||
- Any task where B genuinely needs A's output
|
||||
|
||||
## Comparison: What If We Tried Parallel?
|
||||
|
||||
**Attempted parallel (would fail):**
|
||||
|
||||
```
|
||||
Agent 2 (Migration): Needs Agent 1's schema design → BLOCKED
|
||||
Agent 3 (Middleware): Needs Agent 2's tables to exist → BLOCKED
|
||||
Agent 4 (Endpoints): Needs Agent 3's middleware → BLOCKED
|
||||
Agent 5 (Tests): Needs Agent 4's endpoints → BLOCKED
|
||||
|
||||
Result: All agents blocked or produce incorrect results
|
||||
```
|
||||
|
||||
**Lesson:** Don't force parallelization when dependencies exist. Sequential is correct here.
|
||||
825
skills/agent-delegation/reference.md
Normal file
825
skills/agent-delegation/reference.md
Normal file
@@ -0,0 +1,825 @@
|
||||
# Agent Delegation Skill Reference
|
||||
|
||||
Complete reference for advanced delegation patterns, edge cases, and optimization strategies.
|
||||
|
||||
## Advanced Decomposition Patterns
|
||||
|
||||
### Multi-Level Decomposition
|
||||
|
||||
For very complex tasks, decompose in layers:
|
||||
|
||||
**Layer 1: High-Level Activities**
|
||||
```
|
||||
Task: Build e-commerce checkout flow
|
||||
|
||||
Activities:
|
||||
1. Frontend checkout interface
|
||||
2. Backend payment processing
|
||||
3. Order fulfillment system
|
||||
4. Email notifications
|
||||
```
|
||||
|
||||
**Layer 2: Sub-Activity Decomposition**
|
||||
|
||||
Take Activity 2 and decompose further:
|
||||
```
|
||||
Activity: Backend payment processing
|
||||
|
||||
Sub-activities:
|
||||
2.1 Stripe API integration
|
||||
2.2 Payment validation logic
|
||||
2.3 Transaction database schema
|
||||
2.4 Refund handling
|
||||
```
|
||||
|
||||
**Execution Strategy:**
|
||||
- Layer 1: Mixed (some parallel, some sequential)
|
||||
- Layer 2: Decompose only when agent starts Activity 2
|
||||
- Don't decompose all layers upfront (overwhelming)
|
||||
|
||||
### Dependency Graph Decomposition
|
||||
|
||||
For complex dependency chains:
|
||||
|
||||
```
|
||||
Task: Deploy new microservice
|
||||
|
||||
Activity Map:
|
||||
A: Write service code
|
||||
B: Write unit tests (depends on A)
|
||||
C: Create Docker image (depends on A)
|
||||
D: Write integration tests (depends on A, C)
|
||||
E: Deploy to staging (depends on B, C, D)
|
||||
F: Run smoke tests (depends on E)
|
||||
G: Deploy to production (depends on F)
|
||||
|
||||
Execution Groups:
|
||||
Group 1: A (sequential)
|
||||
Group 2: B, C (parallel after A)
|
||||
Group 3: D (sequential after Group 2)
|
||||
Group 4: E (sequential after Group 3)
|
||||
Group 5: F (sequential after E)
|
||||
Group 6: G (sequential after F)
|
||||
```
|
||||
|
||||
**Pattern:** Identify critical path, parallelize where possible.
|
||||
|
||||
### Expertise-Based Decomposition
|
||||
|
||||
When multiple domains are involved:
|
||||
|
||||
```
|
||||
Task: Add real-time chat feature
|
||||
|
||||
Decompose by expertise:
|
||||
1. UI/UX design (design expertise)
|
||||
2. Frontend component (React expertise)
|
||||
3. WebSocket server (Backend expertise)
|
||||
4. Message persistence (Database expertise)
|
||||
5. Security review (Security expertise)
|
||||
6. Performance testing (Performance expertise)
|
||||
|
||||
Execution:
|
||||
- Phase 1: Activity 1 (sequential)
|
||||
- Phase 2: Activities 2-4 (parallel, informed by Activity 1)
|
||||
- Phase 3: Activities 5-6 (parallel review after Phase 2)
|
||||
```
|
||||
|
||||
## Advanced Parallel Patterns
|
||||
|
||||
### Fan-Out/Fan-In Pattern
|
||||
|
||||
Parallel expansion followed by sequential consolidation:
|
||||
|
||||
```
|
||||
Start
|
||||
↓
|
||||
[Activity 1]
|
||||
↓
|
||||
┌─────┼─────┐
|
||||
↓ ↓ ↓
|
||||
[A2] [A3] [A4] ← Fan-out (parallel)
|
||||
↓ ↓ ↓
|
||||
└─────┼─────┘
|
||||
↓
|
||||
[Synthesize] ← Fan-in (sequential)
|
||||
↓
|
||||
Done
|
||||
```
|
||||
|
||||
**Example:** Competitive analysis
|
||||
- Fan-out: Analyze competitors A, B, C in parallel
|
||||
- Fan-in: Synthesize findings into unified strategy
|
||||
|
||||
### Pipeline Pattern
|
||||
|
||||
Sequential groups where each group can be parallel:
|
||||
|
||||
```
|
||||
Stage 1: Research (parallel within stage)
|
||||
- Market research
|
||||
- Competitive analysis
|
||||
- User interviews
|
||||
↓
|
||||
Stage 2: Design (parallel within stage)
|
||||
- UI mockups
|
||||
- API design
|
||||
- Database schema
|
||||
↓
|
||||
Stage 3: Implementation (parallel within stage)
|
||||
- Frontend build
|
||||
- Backend build
|
||||
- Database setup
|
||||
```
|
||||
|
||||
**Pattern:** Stages are sequential, activities within each stage are parallel.
|
||||
|
||||
### MapReduce Pattern
|
||||
|
||||
Parallel processing with aggregation:
|
||||
|
||||
```
|
||||
Map Phase (parallel):
|
||||
Agent 1: Process dataset chunk 1
|
||||
Agent 2: Process dataset chunk 2
|
||||
Agent 3: Process dataset chunk 3
|
||||
Agent 4: Process dataset chunk 4
|
||||
|
||||
Reduce Phase (sequential):
|
||||
Aggregate all results into final output
|
||||
```
|
||||
|
||||
**Example:** Code analysis across modules
|
||||
- Map: Each agent analyzes one module
|
||||
- Reduce: Aggregate findings into project-wide report
|
||||
|
||||
## Advanced Template Patterns
|
||||
|
||||
### Context Accumulation Pattern
|
||||
|
||||
For sequential tasks, accumulate context:
|
||||
|
||||
```
|
||||
Agent 1:
|
||||
CONTEXT: Fresh start, no prior context
|
||||
OUTPUT: Result A
|
||||
|
||||
Agent 2:
|
||||
CONTEXT:
|
||||
- Prior results: [Result A from Agent 1]
|
||||
- Build on: [Specific insights from A]
|
||||
OUTPUT: Result B (informed by A)
|
||||
|
||||
Agent 3:
|
||||
CONTEXT:
|
||||
- Prior results: [Result A, Result B]
|
||||
- Conflicts to resolve: [Any conflicts between A and B]
|
||||
- Build on: [Insights from both]
|
||||
OUTPUT: Result C (synthesizes A and B)
|
||||
```
|
||||
|
||||
**Key:** Each agent gets relevant prior outputs, not everything.
|
||||
|
||||
### Constraint Propagation Pattern
|
||||
|
||||
Cascade constraints through dependent tasks:
|
||||
|
||||
```
|
||||
Agent 1 (Schema Design):
|
||||
SUCCESS:
|
||||
- Uses PostgreSQL (project standard)
|
||||
- Follows naming: snake_case tables
|
||||
- All tables have created_at, updated_at
|
||||
|
||||
Agent 2 (API Implementation, depends on Agent 1):
|
||||
CONTEXT:
|
||||
- Database constraints from Agent 1:
|
||||
* PostgreSQL only
|
||||
* snake_case table names
|
||||
* created_at/updated_at in all tables
|
||||
- Must match schema exactly
|
||||
```
|
||||
|
||||
**Pattern:** SUCCESS criteria from earlier tasks become CONTEXT constraints for later ones.
|
||||
|
||||
### Specification Reference Pattern
|
||||
|
||||
For implementation tasks, reference specs explicitly:
|
||||
|
||||
```
|
||||
FOCUS: Implement user registration endpoint
|
||||
|
||||
CONTEXT:
|
||||
- PRD Section 3.1.2: User registration requirements
|
||||
- SDD Section 4.2: API endpoint specifications
|
||||
- SDD Section 5.3: Database schema for users table
|
||||
- PLAN Phase 2, Task 3: Implementation checklist
|
||||
|
||||
SDD_REQUIREMENTS:
|
||||
- Endpoint: POST /api/auth/register
|
||||
- Request body: { email, password, name }
|
||||
- Response: { user_id, token }
|
||||
- Validation: Email format, password strength (8+ chars)
|
||||
- Security: Bcrypt hashing (cost 12)
|
||||
|
||||
SPECIFICATION_CHECK: Must match SDD Section 4.2 exactly
|
||||
```
|
||||
|
||||
**Pattern:** Explicit spec references prevent context drift.
|
||||
|
||||
## File Coordination Advanced Strategies
|
||||
|
||||
### Timestamp-Based Uniqueness
|
||||
|
||||
When paths might collide, add timestamps:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: logs/analysis-${TIMESTAMP}.md
|
||||
Agent 2 OUTPUT: logs/research-${TIMESTAMP}.md
|
||||
Agent 3 OUTPUT: logs/synthesis-${TIMESTAMP}.md
|
||||
|
||||
where TIMESTAMP = ISO 8601 format
|
||||
```
|
||||
|
||||
**Result:** No collisions even if agents run simultaneously.
|
||||
|
||||
### Directory Hierarchy Assignment
|
||||
|
||||
Assign each agent a subdirectory:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: results/agent-1/findings.md
|
||||
Agent 2 OUTPUT: results/agent-2/findings.md
|
||||
Agent 3 OUTPUT: results/agent-3/findings.md
|
||||
```
|
||||
|
||||
**Result:** Each agent owns a directory, filenames can repeat.
|
||||
|
||||
### Atomic File Creation Pattern
|
||||
|
||||
For critical files, ensure atomic creation:
|
||||
|
||||
```
|
||||
OUTPUT: Create file at exact path: docs/patterns/auth.md
|
||||
- If file exists, FAIL and report (don't overwrite)
|
||||
- Use atomic write (temp file + rename)
|
||||
- Verify write succeeded before marking complete
|
||||
```
|
||||
|
||||
**Pattern:** Prevents race conditions and corruption.
|
||||
|
||||
### Merge Strategy Pattern
|
||||
|
||||
When multiple agents create similar content:
|
||||
|
||||
```
|
||||
Strategy: Sequential merge
|
||||
|
||||
Agent 1: Create base document
|
||||
Agent 2: Read base, add section 2
|
||||
Agent 3: Read base + section 2, add section 3
|
||||
|
||||
Each agent:
|
||||
DISCOVERY_FIRST: Read current state of document
|
||||
FOCUS: Add my section without modifying others
|
||||
OUTPUT: Updated document with my section added
|
||||
```
|
||||
|
||||
**Pattern:** Sequential additions to shared document.
|
||||
|
||||
## Scope Validation Advanced Patterns
|
||||
|
||||
### Severity-Based Acceptance
|
||||
|
||||
Categorize scope creep by severity:
|
||||
|
||||
**Minor (Auto-accept):**
|
||||
- Variable name improvements
|
||||
- Comment additions
|
||||
- Whitespace formatting
|
||||
- Import organization
|
||||
|
||||
**Medium (Review):**
|
||||
- Small refactors related to task
|
||||
- Additional error handling
|
||||
- Logging additions
|
||||
- Documentation updates
|
||||
|
||||
**Major (Reject):**
|
||||
- New features
|
||||
- Architecture changes
|
||||
- Dependency additions
|
||||
- Breaking changes
|
||||
|
||||
### Value-Based Exception Handling
|
||||
|
||||
Sometimes scope creep is valuable:
|
||||
|
||||
```
|
||||
Agent delivered:
|
||||
✅ Required: Authentication endpoint
|
||||
⚠️ Extra: Rate limiting on endpoint (not requested)
|
||||
|
||||
Analysis:
|
||||
- Extra work: Rate limiting
|
||||
- In EXCLUDE? No (not explicitly excluded)
|
||||
- Valuable? Yes (security best practice)
|
||||
- Risky? No (standard pattern)
|
||||
- Increases scope? Minimally
|
||||
|
||||
Decision: 🟡 ACCEPT with note
|
||||
"Agent proactively added rate limiting for security.
|
||||
Aligns with best practices, accepting this valuable addition."
|
||||
```
|
||||
|
||||
**Pattern:** Auto-accept valuable, low-risk extras that align with project goals.
|
||||
|
||||
### Specification Drift Detection
|
||||
|
||||
For implement tasks, detect drift from specs:
|
||||
|
||||
```
|
||||
Validation:
|
||||
1. Check FOCUS matches PLAN task description
|
||||
2. Check implementation matches SDD requirements
|
||||
3. Check business logic matches PRD rules
|
||||
|
||||
Drift detected if:
|
||||
- Implementation differs from SDD design
|
||||
- Business rules differ from PRD
|
||||
- Features not in PLAN added
|
||||
|
||||
Report:
|
||||
📊 Specification Alignment: 85%
|
||||
✅ Aligned: [aspects that match]
|
||||
⚠️ Deviations: [aspects that differ]
|
||||
🔴 Critical drift: [major misalignments]
|
||||
```
|
||||
|
||||
## Retry Strategy Advanced Patterns
|
||||
|
||||
### Progressive Refinement
|
||||
|
||||
Refine template progressively across retries:
|
||||
|
||||
**Attempt 1 (Failed - too vague):**
|
||||
```
|
||||
FOCUS: Add caching
|
||||
```
|
||||
|
||||
**Attempt 2 (Failed - still ambiguous):**
|
||||
```
|
||||
FOCUS: Add Redis caching for API responses
|
||||
EXCLUDE: Don't cache user-specific data
|
||||
```
|
||||
|
||||
**Attempt 3 (Success - specific enough):**
|
||||
```
|
||||
FOCUS: Add Redis caching for public API endpoints
|
||||
- Cache GET requests only
|
||||
- TTL: 5 minutes
|
||||
- Key format: api:endpoint:params:hash
|
||||
- Invalidate on POST/PUT/DELETE to same resource
|
||||
|
||||
EXCLUDE:
|
||||
- Don't cache authenticated user requests
|
||||
- Don't cache admin endpoints
|
||||
- Don't implement cache warming
|
||||
- Don't add Redis cluster setup (single node for now)
|
||||
|
||||
CONTEXT:
|
||||
- Redis already configured: localhost:6379
|
||||
- Use ioredis client
|
||||
- Follow caching pattern: docs/patterns/caching-strategy.md
|
||||
```
|
||||
|
||||
**Pattern:** Each retry adds specificity based on previous failure.
|
||||
|
||||
### Agent Type Rotation
|
||||
|
||||
If specialist fails, try different angle:
|
||||
|
||||
```
|
||||
Attempt 1: Backend specialist
|
||||
- Focused on technical implementation
|
||||
- Failed: Too technical, missed user experience
|
||||
|
||||
Attempt 2: UX specialist
|
||||
- Focused on user flows
|
||||
- Failed: Too high-level, missed technical constraints
|
||||
|
||||
Attempt 3: Product specialist
|
||||
- Balanced user needs with technical reality
|
||||
- Success: Right blend of perspectives
|
||||
```
|
||||
|
||||
**Pattern:** Rotate expertise angle based on failure mode.
|
||||
|
||||
### Scope Reduction Strategy
|
||||
|
||||
If task too complex, reduce scope progressively:
|
||||
|
||||
```
|
||||
Attempt 1 (Failed - too much):
|
||||
FOCUS: Build complete authentication system
|
||||
- Registration, login, logout, password reset
|
||||
- OAuth integration
|
||||
- Two-factor authentication
|
||||
|
||||
Attempt 2 (Failed - still complex):
|
||||
FOCUS: Build basic authentication
|
||||
- Registration, login, logout
|
||||
|
||||
Attempt 3 (Success - minimal):
|
||||
FOCUS: Build login endpoint only
|
||||
- POST /auth/login
|
||||
- Email + password validation
|
||||
- Return JWT token
|
||||
```
|
||||
|
||||
**Pattern:** Reduce scope until agent succeeds, then expand incrementally.
|
||||
|
||||
## Edge Cases and Solutions
|
||||
|
||||
### Edge Case 1: Circular Dependencies
|
||||
|
||||
**Problem:** Agent A needs Agent B's output, Agent B needs Agent A's output
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
Activity A depends on B
|
||||
Activity B depends on A
|
||||
→ Circular dependency detected
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Break the cycle:**
|
||||
```
|
||||
Original:
|
||||
A (needs B) ↔ B (needs A)
|
||||
|
||||
Refactored:
|
||||
C (shared foundation) → A (builds on C) → B (builds on A)
|
||||
```
|
||||
|
||||
2. **Iterative approach:**
|
||||
```
|
||||
Round 1: A (with assumptions about B)
|
||||
Round 2: B (using Round 1 A)
|
||||
Round 3: A (refined with actual B)
|
||||
```
|
||||
|
||||
3. **Merge activities:**
|
||||
```
|
||||
Single agent handles both A and B together
|
||||
(They're too coupled to separate)
|
||||
```
|
||||
|
||||
### Edge Case 2: Dynamic Dependencies
|
||||
|
||||
**Problem:** Don't know dependencies until runtime
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Task: Analyze codebase
|
||||
|
||||
Don't know which modules exist until discovery
|
||||
Can't plan parallel structure upfront
|
||||
```
|
||||
|
||||
**Solution - Two-phase approach:**
|
||||
|
||||
**Phase 1: Discovery (sequential)**
|
||||
```
|
||||
Agent 1: Discover project structure
|
||||
OUTPUT: List of modules
|
||||
|
||||
Result: [moduleA, moduleB, moduleC, moduleD]
|
||||
```
|
||||
|
||||
**Phase 2: Analysis (parallel, dynamic)**
|
||||
```
|
||||
For each module in result:
|
||||
Launch analysis agent
|
||||
|
||||
Agent A: Analyze moduleA
|
||||
Agent B: Analyze moduleB
|
||||
Agent C: Analyze moduleC
|
||||
Agent D: Analyze moduleD
|
||||
```
|
||||
|
||||
**Pattern:** Sequential discovery, dynamic parallel execution.
|
||||
|
||||
### Edge Case 3: Partial Agent Availability
|
||||
|
||||
**Problem:** Some specialist agents unavailable
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Planned:
|
||||
- Frontend specialist (available)
|
||||
- Backend specialist (available)
|
||||
- DevOps specialist (NOT AVAILABLE)
|
||||
```
|
||||
|
||||
**Solution - Fallback delegation:**
|
||||
|
||||
```
|
||||
If specialist unavailable:
|
||||
1. Try broader domain agent (general-purpose)
|
||||
2. Try sequential breakdown (smaller tasks)
|
||||
3. Handle directly if simple enough
|
||||
4. Escalate to user if critical
|
||||
```
|
||||
|
||||
**Example execution:**
|
||||
```
|
||||
DevOps work:
|
||||
Attempt 1: DevOps specialist → UNAVAILABLE
|
||||
Attempt 2: Backend specialist with DevOps context → SUCCESS
|
||||
Reasoning: Backend specialist has some DevOps overlap
|
||||
```
|
||||
|
||||
### Edge Case 4: Agent Response Conflicts
|
||||
|
||||
**Problem:** Parallel agents return conflicting recommendations
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Agent 1 (Security): "Use bcrypt with cost 14 (maximum security)"
|
||||
Agent 2 (Performance): "Use bcrypt with cost 10 (reasonable security, better performance)"
|
||||
```
|
||||
|
||||
**Solution - Conflict resolution:**
|
||||
|
||||
**1. Present to user:**
|
||||
```
|
||||
⚠️ Agent Conflict Detected
|
||||
|
||||
Topic: Bcrypt cost factor
|
||||
Agent 1 (Security): Cost 14 (maximize security)
|
||||
Agent 2 (Performance): Cost 10 (balance security/performance)
|
||||
|
||||
Trade-off:
|
||||
- Cost 14: ~200ms hashing time, highest security
|
||||
- Cost 10: ~50ms hashing time, strong security
|
||||
|
||||
Recommendation needed: Which priority matters more?
|
||||
```
|
||||
|
||||
**2. Specification arbitration:**
|
||||
```
|
||||
Check specs:
|
||||
- SDD Section 5.2: "Use bcrypt cost factor 12"
|
||||
→ Use specification value (12)
|
||||
→ Both agents adjusted to match spec
|
||||
```
|
||||
|
||||
**3. Synthesis agent:**
|
||||
```
|
||||
Launch Agent 3 (Architect):
|
||||
FOCUS: Resolve conflict between security and performance recommendations
|
||||
CONTEXT:
|
||||
- Security recommendation: cost 14
|
||||
- Performance recommendation: cost 10
|
||||
- Trade-offs: [details]
|
||||
OUTPUT: Final recommendation with reasoning
|
||||
```
|
||||
|
||||
### Edge Case 5: Resource Constraints
|
||||
|
||||
**Problem:** Can't launch all parallel agents simultaneously (rate limits, memory, etc.)
|
||||
|
||||
**Solution - Batched parallel execution:**
|
||||
|
||||
```
|
||||
Activities: [A1, A2, A3, A4, A5, A6, A7, A8]
|
||||
Constraint: Maximum 3 parallel agents
|
||||
|
||||
Execution:
|
||||
Batch 1: A1, A2, A3 (parallel)
|
||||
→ Wait for completion
|
||||
Batch 2: A4, A5, A6 (parallel)
|
||||
→ Wait for completion
|
||||
Batch 3: A7, A8 (parallel)
|
||||
→ Complete
|
||||
```
|
||||
|
||||
**Pattern:** Maintain parallelism within constraints.
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Minimize Context Size
|
||||
|
||||
Don't pass everything to every agent:
|
||||
|
||||
❌ **Bad - Full context:**
|
||||
```
|
||||
CONTEXT:
|
||||
- Entire PRD (50 pages)
|
||||
- Entire SDD (40 pages)
|
||||
- All prior agent outputs (30 pages)
|
||||
```
|
||||
|
||||
✅ **Good - Relevant context:**
|
||||
```
|
||||
CONTEXT:
|
||||
- PRD Section 3.2 (User authentication requirements)
|
||||
- SDD Section 4.1 (API endpoint design)
|
||||
- Prior output: Authentication flow diagram from Agent 1
|
||||
```
|
||||
|
||||
**Pattern:** Extract only relevant portions, reference docs by section.
|
||||
|
||||
### Parallel Batching
|
||||
|
||||
Group related parallel tasks:
|
||||
|
||||
```
|
||||
Don't:
|
||||
Launch 20 individual research agents
|
||||
|
||||
Do:
|
||||
Launch 4 research agents, each handles 5 topics
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Fewer coordination overhead
|
||||
- Better context utilization
|
||||
- Faster overall completion
|
||||
|
||||
### Early Termination
|
||||
|
||||
Build termination conditions into templates:
|
||||
|
||||
```
|
||||
TERMINATION:
|
||||
- Completed successfully
|
||||
- Blocked by missing dependency X
|
||||
- Information not publicly available
|
||||
- Maximum 3 attempts reached
|
||||
- ERROR: [specific error conditions]
|
||||
```
|
||||
|
||||
**Pattern:** Let agents fail fast instead of hanging.
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
### With Documentation Skill
|
||||
|
||||
When agents discover patterns:
|
||||
|
||||
```
|
||||
Agent completes task
|
||||
↓
|
||||
Discovers reusable pattern
|
||||
↓
|
||||
Documentation skill activates
|
||||
↓
|
||||
Pattern documented in docs/patterns/
|
||||
↓
|
||||
Reported back to orchestrator
|
||||
```
|
||||
|
||||
**Coordination:** Agent-delegation creates prompts, documentation skill handles pattern storage.
|
||||
|
||||
### With Specification Review Skill
|
||||
|
||||
For implementation tasks:
|
||||
|
||||
```
|
||||
Agent completes implementation
|
||||
↓
|
||||
Agent-delegation validates scope
|
||||
↓
|
||||
Specification review skill validates against PRD/SDD
|
||||
↓
|
||||
Both validations pass → Complete
|
||||
```
|
||||
|
||||
**Coordination:** Agent-delegation handles scope, spec-review handles alignment.
|
||||
|
||||
### With Quality Gates Skill
|
||||
|
||||
At phase boundaries:
|
||||
|
||||
```
|
||||
Phase completes
|
||||
↓
|
||||
Agent-delegation confirms all tasks done
|
||||
↓
|
||||
Quality gates skill runs DOD checks
|
||||
↓
|
||||
Both pass → Proceed to next phase
|
||||
```
|
||||
|
||||
**Coordination:** Agent-delegation manages execution, quality-gates validates quality.
|
||||
|
||||
## Debugging Failed Delegations
|
||||
|
||||
### Symptom: Agents ignore EXCLUDE
|
||||
|
||||
**Diagnosis:**
|
||||
- EXCLUDE too vague
|
||||
- Agent sees value in excluded work
|
||||
- Conflict between FOCUS and EXCLUDE
|
||||
|
||||
**Fix:**
|
||||
```
|
||||
Before:
|
||||
EXCLUDE: Don't add extra features
|
||||
|
||||
After:
|
||||
EXCLUDE: Do not add these specific features:
|
||||
- OAuth integration (separate task)
|
||||
- Password reset flow (separate task)
|
||||
- Two-factor authentication (not in scope)
|
||||
Any feature not explicitly in FOCUS is out of scope.
|
||||
```
|
||||
|
||||
### Symptom: Parallel agents conflict
|
||||
|
||||
**Diagnosis:**
|
||||
- Hidden shared state
|
||||
- File path collision
|
||||
- Dependency not identified
|
||||
|
||||
**Fix:**
|
||||
```
|
||||
Review parallel safety checklist:
|
||||
- Independent tasks? → Check dependencies again
|
||||
- Unique file paths? → Verify OUTPUT sections
|
||||
- No shared state? → Identify what's shared
|
||||
|
||||
If any fail → Make sequential or coordinate better
|
||||
```
|
||||
|
||||
### Symptom: Sequential too slow
|
||||
|
||||
**Diagnosis:**
|
||||
- False dependencies
|
||||
- Over-cautious sequencing
|
||||
- Could be parallel with coordination
|
||||
|
||||
**Fix:**
|
||||
```
|
||||
Re-analyze dependencies:
|
||||
- Must Task B use Task A's output? → True dependency
|
||||
- Could Task B assume Task A's approach? → False dependency
|
||||
|
||||
If false dependency:
|
||||
→ Make parallel with coordinated assumptions
|
||||
```
|
||||
|
||||
### Symptom: Template too complex
|
||||
|
||||
**Diagnosis:**
|
||||
- Too many constraints
|
||||
- Context overload
|
||||
- Agent confused by detail
|
||||
|
||||
**Fix:**
|
||||
```
|
||||
Simplify:
|
||||
1. Keep FOCUS to essentials
|
||||
2. Move details to CONTEXT
|
||||
3. Provide examples instead of rules
|
||||
|
||||
Before (overwhelming):
|
||||
FOCUS: [20 lines of detailed requirements]
|
||||
|
||||
After (simplified):
|
||||
FOCUS: [2 lines of core task]
|
||||
CONTEXT: [Details and constraints]
|
||||
```
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
1. **Decompose by activities**, not roles
|
||||
2. **Parallel by default**, sequential only when necessary
|
||||
3. **Explicit FOCUS/EXCLUDE**, no ambiguity
|
||||
4. **Unique file paths**, verify before launching
|
||||
5. **Minimal context**, only relevant information
|
||||
6. **Auto-accept safe changes**, review architectural ones
|
||||
7. **Maximum 3 retries**, then escalate
|
||||
8. **Early termination**, fail fast when blocked
|
||||
9. **Validate scope**, check FOCUS/EXCLUDE adherence
|
||||
10. **Document patterns**, activate documentation skill when discovered
|
||||
|
||||
## Common Patterns Quick Reference
|
||||
|
||||
| Pattern | When to Use | Structure |
|
||||
|---------|-------------|-----------|
|
||||
| Fan-Out/Fan-In | Parallel research → synthesis | Parallel → Sequential |
|
||||
| Pipeline | Stages with parallel within | Sequential stages, parallel tasks |
|
||||
| MapReduce | Large dataset processing | Parallel map → Sequential reduce |
|
||||
| Progressive Refinement | Retry with more detail | Retry N adds specificity |
|
||||
| Batched Parallel | Resource constraints | Groups of parallel tasks |
|
||||
| Context Accumulation | Sequential with learning | Each task gets prior outputs |
|
||||
| Constraint Propagation | Dependent implementations | SUCCESS → next CONTEXT |
|
||||
| Specification Reference | Implementation tasks | Explicit PRD/SDD references |
|
||||
|
||||
---
|
||||
|
||||
This reference covers advanced scenarios beyond the main skill. Load this when dealing with complex coordination, optimization, or edge cases.
|
||||
213
skills/documentation/SKILL.md
Normal file
213
skills/documentation/SKILL.md
Normal file
@@ -0,0 +1,213 @@
|
||||
---
|
||||
name: documentation
|
||||
description: Document business rules, technical patterns, and service interfaces discovered during analysis or implementation. Use when you find reusable patterns, external integrations, domain-specific rules, or API contracts. Always check existing documentation before creating new files. Handles deduplication and proper categorization.
|
||||
allowed-tools: Read, Write, Edit, Grep, Glob
|
||||
---
|
||||
|
||||
You are a documentation specialist that captures and organizes knowledge discovered during development work.
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
All documentation follows this hierarchy:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── domain/ # Business rules, domain logic, workflows, validation rules
|
||||
├── patterns/ # Technical patterns, architectural solutions, code patterns
|
||||
├── interfaces/ # External API contracts, service integrations, webhooks
|
||||
```
|
||||
|
||||
## Decision Tree: What Goes Where?
|
||||
|
||||
### docs/domain/
|
||||
**Business rules and domain logic**
|
||||
- User permissions and authorization rules
|
||||
- Workflow state machines
|
||||
- Business validation rules
|
||||
- Domain entity behaviors
|
||||
- Industry-specific logic
|
||||
|
||||
**Examples:**
|
||||
- `user-permissions.md` - Who can do what
|
||||
- `order-workflow.md` - Order state transitions
|
||||
- `pricing-rules.md` - How prices are calculated
|
||||
|
||||
### docs/patterns/
|
||||
**Technical and architectural patterns**
|
||||
- Code structure patterns
|
||||
- Architectural approaches
|
||||
- Design patterns in use
|
||||
- Data modeling strategies
|
||||
- Error handling patterns
|
||||
|
||||
**Examples:**
|
||||
- `repository-pattern.md` - Data access abstraction
|
||||
- `caching-strategy.md` - How caching is implemented
|
||||
- `error-handling.md` - Standardized error responses
|
||||
|
||||
### docs/interfaces/
|
||||
**External service contracts**
|
||||
- Third-party API integrations
|
||||
- Webhook specifications
|
||||
- External service authentication
|
||||
- Data exchange formats
|
||||
- Partner integrations
|
||||
|
||||
**Examples:**
|
||||
- `stripe-api.md` - Payment processing integration
|
||||
- `sendgrid-webhooks.md` - Email event handling
|
||||
- `oauth-providers.md` - Authentication integrations
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 0: DEDUPLICATION (REQUIRED - DO THIS FIRST)
|
||||
|
||||
**Always check for existing documentation before creating new files:**
|
||||
|
||||
```bash
|
||||
# Search for existing documentation
|
||||
grep -ri "main keyword" docs/domain/ docs/patterns/ docs/interfaces/
|
||||
find docs -name "*topic-keyword*"
|
||||
```
|
||||
|
||||
**Decision Tree**:
|
||||
- **Found similar documentation** → Use Edit to UPDATE existing file instead
|
||||
- **Found NO similar documentation** → Proceed to Step 1 (Determine Category)
|
||||
|
||||
**Critical**: Always prefer updating existing files over creating new ones. Deduplication prevents documentation fragmentation.
|
||||
|
||||
### Step 1: Determine Category
|
||||
|
||||
Ask yourself:
|
||||
- **Is this about business logic?** → `docs/domain/`
|
||||
- **Is this about how we build?** → `docs/patterns/`
|
||||
- **Is this about external services?** → `docs/interfaces/`
|
||||
|
||||
### Step 2: Choose: Create New or Update Existing
|
||||
|
||||
**Create new** if:
|
||||
- No related documentation exists
|
||||
- Topic is distinct enough to warrant separation
|
||||
- Would create confusion to merge with existing doc
|
||||
|
||||
**Update existing** if:
|
||||
- Related documentation already exists
|
||||
- New info enhances existing document
|
||||
- Same category and closely related topic
|
||||
|
||||
### Step 3: Use Descriptive, Searchable Names
|
||||
|
||||
**Good names:**
|
||||
- `authentication-flow.md` (clear, searchable)
|
||||
- `database-migration-strategy.md` (specific)
|
||||
- `stripe-payment-integration.md` (exact)
|
||||
|
||||
**Bad names:**
|
||||
- `auth.md` (too vague)
|
||||
- `db.md` (unclear)
|
||||
- `api.md` (which API?)
|
||||
|
||||
### Step 4: Follow the Template Structure
|
||||
|
||||
Use the templates in `templates/` for consistent formatting:
|
||||
- `pattern-template.md` - For technical patterns
|
||||
- `interface-template.md` - For external integrations
|
||||
- `domain-template.md` - For business rules
|
||||
|
||||
## Document Structure Standards
|
||||
|
||||
Every document should include:
|
||||
|
||||
1. **Title and Purpose** - What this documents
|
||||
2. **Context** - When/why this applies
|
||||
3. **Details** - The actual content (patterns, rules, contracts)
|
||||
4. **Examples** - Code snippets or scenarios
|
||||
5. **References** - Related docs or external links
|
||||
|
||||
## Deduplication Protocol
|
||||
|
||||
Before creating any documentation:
|
||||
|
||||
1. **Search by topic**: `grep -ri "topic" docs/`
|
||||
2. **Check category**: List files in target category
|
||||
3. **Read related files**: Verify no overlap
|
||||
4. **Decide**: Create new vs enhance existing
|
||||
5. **Cross-reference**: Link between related docs
|
||||
|
||||
## Examples in Action
|
||||
|
||||
### Example 1: API Integration Discovery
|
||||
|
||||
**Scenario:** Implementing Stripe payment processing
|
||||
|
||||
**Analysis:**
|
||||
- External service? → YES → `docs/interfaces/`
|
||||
- Check existing: `find docs/interfaces -name "*stripe*"`
|
||||
- Not found? → Create `docs/interfaces/stripe-payments.md`
|
||||
- Use `interface-template.md`
|
||||
|
||||
### Example 2: Caching Pattern Discovery
|
||||
|
||||
**Scenario:** Found Redis caching in authentication module
|
||||
|
||||
**Analysis:**
|
||||
- External service? → NO
|
||||
- Business rule? → NO
|
||||
- Technical pattern? → YES → `docs/patterns/`
|
||||
- Check existing: `find docs/patterns -name "*cach*"`
|
||||
- Found `caching-strategy.md`? → Update it
|
||||
- Not found? → Create `docs/patterns/caching-strategy.md`
|
||||
|
||||
### Example 3: Permission Rule Discovery
|
||||
|
||||
**Scenario:** Users can only edit their own posts
|
||||
|
||||
**Analysis:**
|
||||
- Business rule? → YES → `docs/domain/`
|
||||
- External service? → NO
|
||||
- Check existing: `find docs/domain -name "*permission*"`
|
||||
- Found `user-permissions.md`? → Update it
|
||||
- Not found? → Create `docs/domain/user-permissions.md`
|
||||
|
||||
## Cross-Referencing
|
||||
|
||||
When documentation relates to other docs:
|
||||
|
||||
```markdown
|
||||
## Related Documentation
|
||||
|
||||
- [Authentication Flow](../patterns/authentication-flow.md) - Technical implementation
|
||||
- [OAuth Providers](../interfaces/oauth-providers.md) - External integrations
|
||||
- [User Permissions](../domain/user-permissions.md) - Business rules
|
||||
```
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before finalizing any documentation:
|
||||
|
||||
- [ ] Checked for existing related documentation
|
||||
- [ ] Chosen correct category (domain/patterns/interfaces)
|
||||
- [ ] Used descriptive, searchable filename
|
||||
- [ ] Included title, context, details, examples
|
||||
- [ ] Added cross-references to related docs
|
||||
- [ ] Used appropriate template structure
|
||||
- [ ] Verified no duplicate content
|
||||
|
||||
## Output Format
|
||||
|
||||
After documenting, always report:
|
||||
|
||||
```
|
||||
📝 Documentation Created/Updated:
|
||||
- docs/[category]/[filename].md
|
||||
Purpose: [Brief description]
|
||||
Action: [Created new / Updated existing / Merged with existing]
|
||||
```
|
||||
|
||||
## Remember
|
||||
|
||||
- **Deduplication is critical** - Always check first
|
||||
- **Categories matter** - Business vs Technical vs External
|
||||
- **Names are discoverable** - Use full, descriptive names
|
||||
- **Templates ensure consistency** - Follow the structure
|
||||
- **Cross-reference liberally** - Connect related knowledge
|
||||
388
skills/documentation/reference.md
Normal file
388
skills/documentation/reference.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# Documentation Skill Reference
|
||||
|
||||
Complete reference for the documentation skill including advanced patterns, edge cases, and detailed protocols.
|
||||
|
||||
## Advanced Categorization Rules
|
||||
|
||||
### Gray Areas and Edge Cases
|
||||
|
||||
#### When Business and Technical Overlap
|
||||
|
||||
**Authentication Example:**
|
||||
- `docs/domain/user-roles.md` - WHO can access WHAT (business rule)
|
||||
- `docs/patterns/authentication-flow.md` - HOW authentication works (technical)
|
||||
- `docs/interfaces/oauth-providers.md` - EXTERNAL services used (integration)
|
||||
|
||||
**Guideline:** If it affects WHAT users can do → domain. If it affects HOW we build it → patterns.
|
||||
|
||||
#### When Pattern Becomes Interface
|
||||
|
||||
**Caching Example:**
|
||||
- Local in-memory caching → `docs/patterns/caching-strategy.md`
|
||||
- Redis/Memcached integration → `docs/interfaces/redis-cache.md`
|
||||
|
||||
**Guideline:** Self-contained code patterns → patterns. External service dependencies → interfaces.
|
||||
|
||||
#### When Multiple Categories Apply
|
||||
|
||||
**Payment Processing Example:**
|
||||
Could span all three:
|
||||
- `docs/domain/payment-rules.md` - Refund policies, pricing rules
|
||||
- `docs/patterns/payment-processing.md` - Internal payment handling
|
||||
- `docs/interfaces/stripe-api.md` - Stripe integration specifics
|
||||
|
||||
**Guideline:** Create separate documents for each perspective. Cross-reference heavily.
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Pattern: `[noun]-[noun/verb].md`
|
||||
|
||||
**Good Examples:**
|
||||
- `error-handling.md`
|
||||
- `database-migrations.md`
|
||||
- `api-versioning.md`
|
||||
- `event-sourcing.md`
|
||||
|
||||
**Avoid:**
|
||||
- Single words: `cache.md`, `auth.md`
|
||||
- Abbreviations: `db-mig.md`, `err-hdl.md`
|
||||
- Generic terms: `utilities.md`, `helpers.md`
|
||||
|
||||
### Interface: `[service-name]-[integration-type].md`
|
||||
|
||||
**Good Examples:**
|
||||
- `stripe-payments.md`
|
||||
- `sendgrid-webhooks.md`
|
||||
- `github-api.md`
|
||||
- `aws-s3-storage.md`
|
||||
|
||||
**Avoid:**
|
||||
- Generic: `payment-gateway.md` (which one?)
|
||||
- Vague: `email.md` (what about email?)
|
||||
- Tech-only: `rest-api.md` (which service?)
|
||||
|
||||
### Domain: `[entity/concept]-[aspect].md`
|
||||
|
||||
**Good Examples:**
|
||||
- `user-permissions.md`
|
||||
- `order-workflow.md`
|
||||
- `inventory-tracking.md`
|
||||
- `pricing-rules.md`
|
||||
|
||||
**Avoid:**
|
||||
- Implementation details: `user-table.md` (that's technical)
|
||||
- Generic: `rules.md` (which rules?)
|
||||
- Too broad: `business-logic.md` (everything?)
|
||||
|
||||
## Update vs Create Decision Matrix
|
||||
|
||||
| Scenario | Existing Doc | Action |
|
||||
|----------|--------------|--------|
|
||||
| New payment provider | `stripe-payments.md` exists | **Create** `paypal-payments.md` (different service) |
|
||||
| Additional caching layer | `caching-strategy.md` exists | **Update** existing (same pattern, new details) |
|
||||
| New user role type | `user-permissions.md` exists | **Update** existing (extends same rule set) |
|
||||
| Different auth method | `jwt-authentication.md` exists | **Create** `oauth-authentication.md` (different approach) |
|
||||
| API version change | `github-api.md` exists | **Update** existing (same service, evolved) |
|
||||
| New business constraint | `order-workflow.md` exists | **Update** if related, **Create** if distinct |
|
||||
|
||||
**Guiding Principle:** Same topic/service = update. Different topic/service = create new.
|
||||
|
||||
## Template Usage Guidelines
|
||||
|
||||
### Pattern Template
|
||||
Use for:
|
||||
- Architectural decisions (MVC, microservices, event-driven)
|
||||
- Code organization patterns (repository, factory, singleton)
|
||||
- Data handling approaches (caching, validation, serialization)
|
||||
- Testing strategies (unit, integration, e2e)
|
||||
|
||||
### Interface Template
|
||||
Use for:
|
||||
- Third-party API integrations
|
||||
- Webhook implementations
|
||||
- External service authentication
|
||||
- Data exchange protocols
|
||||
- Partner system integrations
|
||||
|
||||
### Domain Template
|
||||
Use for:
|
||||
- Business rules and constraints
|
||||
- User permission systems
|
||||
- Workflow state machines
|
||||
- Validation requirements
|
||||
- Domain entity behaviors
|
||||
|
||||
## Deduplication Techniques
|
||||
|
||||
### Technique 1: Keyword Search
|
||||
```bash
|
||||
# Search filenames
|
||||
find docs -type f -name "*.md" | grep -i keyword
|
||||
|
||||
# Search content
|
||||
grep -ri "search term" docs/
|
||||
```
|
||||
|
||||
### Technique 2: Category Listing
|
||||
```bash
|
||||
# List all patterns
|
||||
ls docs/patterns/
|
||||
|
||||
# List all interfaces
|
||||
ls docs/interfaces/
|
||||
|
||||
# List all domain docs
|
||||
ls docs/domain/
|
||||
```
|
||||
|
||||
### Technique 3: Content Scanning
|
||||
```bash
|
||||
# Show first 5 lines of each file
|
||||
find docs/patterns -name "*.md" -exec head -5 {} \; -print
|
||||
|
||||
# Search for specific concept
|
||||
grep -l "authentication" docs/**/*.md
|
||||
```
|
||||
|
||||
### Technique 4: Related Term Mapping
|
||||
|
||||
For a new document about "caching":
|
||||
- Check for: cache, caching, cached, memoization, storage
|
||||
- Check categories: patterns (implementation), interfaces (Redis/Memcached)
|
||||
- Read related files before deciding
|
||||
|
||||
## Merge vs Separate Guidelines
|
||||
|
||||
### Merge When:
|
||||
- Same category and closely related topic
|
||||
- Information enhances without confusing
|
||||
- Single cohesive narrative possible
|
||||
- Total length stays under 500 lines
|
||||
|
||||
**Example:** Merging "JWT tokens" into existing `authentication-flow.md`
|
||||
|
||||
### Keep Separate When:
|
||||
- Different approaches to same problem
|
||||
- Distinct services/technologies
|
||||
- Would make document unfocused
|
||||
- Exceeds reasonable length
|
||||
|
||||
**Example:** `jwt-authentication.md` and `oauth-authentication.md` as separate files
|
||||
|
||||
## Cross-Reference Patterns
|
||||
|
||||
### Within Same Category
|
||||
```markdown
|
||||
## Related Patterns
|
||||
- [Repository Pattern](./repository-pattern.md) - Data access layer
|
||||
- [Service Layer](./service-layer.md) - Business logic organization
|
||||
```
|
||||
|
||||
### Across Categories
|
||||
```markdown
|
||||
## Related Documentation
|
||||
- **Domain:** [User Permissions](../domain/user-permissions.md) - Authorization rules
|
||||
- **Patterns:** [Authentication Flow](../patterns/authentication-flow.md) - Technical implementation
|
||||
- **Interfaces:** [OAuth Providers](../interfaces/oauth-providers.md) - External auth services
|
||||
```
|
||||
|
||||
### To Specifications
|
||||
```markdown
|
||||
## Implementations
|
||||
- [User Authentication](../specs/001-user-auth/SDD.md) - Technical specification
|
||||
- [OAuth Integration](../specs/015-oauth/PRD.md) - Product requirements
|
||||
```
|
||||
|
||||
## Version Management
|
||||
|
||||
### When Patterns Evolve
|
||||
|
||||
**Approach 1: Update in Place**
|
||||
- Add "Version History" section
|
||||
- Document what changed and when
|
||||
- Keep current approach primary
|
||||
|
||||
**Approach 2: Separate Documents**
|
||||
- `authentication-v1.md` (legacy)
|
||||
- `authentication-v2.md` (current)
|
||||
- Clear migration path documented
|
||||
|
||||
**Guideline:** Update in place unless breaking change makes old version still relevant for existing code.
|
||||
|
||||
### Deprecation
|
||||
|
||||
When a pattern/interface is superseded:
|
||||
|
||||
```markdown
|
||||
# Old Authentication Pattern
|
||||
|
||||
> **⚠️ DEPRECATED:** This pattern is no longer recommended.
|
||||
> See [New Authentication Flow](./authentication-flow.md) for current approach.
|
||||
>
|
||||
> This document is maintained for reference by legacy code in modules X, Y, Z.
|
||||
|
||||
[Original content preserved...]
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Completeness Checklist
|
||||
- [ ] Title clearly states what is documented
|
||||
- [ ] Context explains when/why this applies
|
||||
- [ ] Examples show real usage
|
||||
- [ ] Edge cases are covered
|
||||
- [ ] Related docs are linked
|
||||
- [ ] Code snippets use real project conventions
|
||||
|
||||
### Clarity Checklist
|
||||
- [ ] New team member could understand it
|
||||
- [ ] Technical terms are explained
|
||||
- [ ] Assumptions are stated explicitly
|
||||
- [ ] Steps are in logical order
|
||||
- [ ] Diagrams included for complex flows (if applicable)
|
||||
|
||||
### Maintainability Checklist
|
||||
- [ ] Searchable filename
|
||||
- [ ] Correct category
|
||||
- [ ] No duplicate content
|
||||
- [ ] Cross-references are bidirectional
|
||||
- [ ] Version history if evolved
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ Mistake 1: Creating Without Checking
|
||||
**Problem:** Duplicate documentation proliferates
|
||||
**Solution:** Always search first - multiple ways (grep, find, ls)
|
||||
|
||||
### ❌ Mistake 2: Wrong Category
|
||||
**Problem:** Business rules in patterns/, technical details in domain/
|
||||
**Solution:** Ask "Is this about WHAT (domain) or HOW (patterns)?"
|
||||
|
||||
### ❌ Mistake 3: Too Generic Names
|
||||
**Problem:** Can't find documentation later
|
||||
**Solution:** Full descriptive names, not abbreviations
|
||||
|
||||
### ❌ Mistake 4: No Cross-References
|
||||
**Problem:** Related knowledge stays siloed
|
||||
**Solution:** Link liberally between related docs
|
||||
|
||||
### ❌ Mistake 5: Template Ignored
|
||||
**Problem:** Inconsistent structure makes scanning hard
|
||||
**Solution:** Follow templates for consistency
|
||||
|
||||
### ❌ Mistake 6: No Examples
|
||||
**Problem:** Abstract descriptions don't help
|
||||
**Solution:** Include real code snippets and scenarios
|
||||
|
||||
## Edge Case Handling
|
||||
|
||||
### What if Nothing Fits the Categories?
|
||||
|
||||
**Option 1:** Expand categories (rare, think hard first)
|
||||
**Option 2:** Create `docs/architecture/` for cross-cutting concerns
|
||||
**Option 3:** Add to specification docs if feature-specific
|
||||
|
||||
**Example:** ADRs (Architecture Decision Records) might warrant `docs/decisions/`
|
||||
|
||||
### What if It's Too Small to Document?
|
||||
|
||||
**Guideline:** If it's reusable or non-obvious, document it.
|
||||
|
||||
**Too small:**
|
||||
- "We use camelCase" (coding standard, not pattern)
|
||||
- "API returns JSON" (obvious, not worth documenting)
|
||||
|
||||
**Worth documenting:**
|
||||
- "We use optimistic locking for inventory" (non-obvious pattern)
|
||||
- "Rate limiting uses token bucket algorithm" (specific approach)
|
||||
|
||||
### What if It's Extremely Specific?
|
||||
|
||||
**Guideline:** Very feature-specific logic goes in specs, not shared docs.
|
||||
|
||||
**Spec-level:**
|
||||
- `specs/023-checkout/SDD.md` - Checkout flow specifics
|
||||
|
||||
**Shared docs:**
|
||||
- `docs/patterns/state-machines.md` - Reusable state machine pattern
|
||||
- `docs/domain/order-workflow.md` - General order rules
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Keep Docs Focused
|
||||
- Single file shouldn't exceed 1000 lines
|
||||
- Split large topics into multiple focused docs
|
||||
- Use cross-references instead of duplicating
|
||||
|
||||
### Optimize for Searchability
|
||||
- Use keywords in filename
|
||||
- Include synonyms in content
|
||||
- Add tags/topics section at top
|
||||
|
||||
### Progressive Detail
|
||||
```markdown
|
||||
# Caching Strategy
|
||||
|
||||
Quick overview: We use Redis for session and API response caching.
|
||||
|
||||
## Details
|
||||
[Detailed implementation...]
|
||||
|
||||
## Advanced Configuration
|
||||
[Complex edge cases...]
|
||||
```
|
||||
|
||||
## Integration with Specifications
|
||||
|
||||
### During Analysis (`/start:analyze`)
|
||||
Documentation skill captures discovered patterns:
|
||||
- Code analysis reveals patterns → Document in `docs/patterns/`
|
||||
- Business rules discovered → Document in `docs/domain/`
|
||||
- External APIs found → Document in `docs/interfaces/`
|
||||
|
||||
### During Specification (`/start:specify`)
|
||||
- PRD/SDD references existing documentation
|
||||
- New patterns discovered → Document them
|
||||
- Specifications live in `docs/specs/`, reference shared docs
|
||||
|
||||
### During Implementation (`/start:implement`)
|
||||
- Implementation follows documented patterns
|
||||
- Deviations discovered → Update documentation
|
||||
- New patterns emerge → Document for reuse
|
||||
|
||||
## Automation Support
|
||||
|
||||
### Pre-documentation Checks
|
||||
Automate the search process:
|
||||
```bash
|
||||
# Check if topic exists
|
||||
./scripts/check-doc-exists.sh "authentication"
|
||||
|
||||
# List related docs
|
||||
./scripts/find-related-docs.sh "payment"
|
||||
```
|
||||
|
||||
### Post-documentation Validation
|
||||
```bash
|
||||
# Verify no duplicates
|
||||
./scripts/validate-docs.sh
|
||||
|
||||
# Check cross-references
|
||||
./scripts/check-links.sh
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
The documentation skill ensures:
|
||||
1. **No duplication** - Always check before creating
|
||||
2. **Correct categorization** - Business vs Technical vs External
|
||||
3. **Discoverability** - Descriptive names and cross-references
|
||||
4. **Consistency** - Template-based structure
|
||||
5. **Maintainability** - Clear, complete, and up-to-date
|
||||
|
||||
When in doubt, ask:
|
||||
- Does related documentation already exist?
|
||||
- Which category fits best?
|
||||
- What name would I search for?
|
||||
- What template applies?
|
||||
- How does this connect to other knowledge?
|
||||
325
skills/documentation/templates/domain-template.md
Normal file
325
skills/documentation/templates/domain-template.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# [Domain Concept/Entity Name]
|
||||
|
||||
> **Category:** Domain/Business Rules
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Under Review/Deprecated]
|
||||
|
||||
## Overview
|
||||
|
||||
**What:** [What this concept represents in the business]
|
||||
**Why:** [Why this exists, business justification]
|
||||
**Scope:** [Where in the application this applies]
|
||||
|
||||
## Business Context
|
||||
|
||||
### Background
|
||||
|
||||
[Business context and history of this domain concept]
|
||||
|
||||
### Stakeholders
|
||||
|
||||
- **[Role 1]:** [How they interact with this]
|
||||
- **[Role 2]:** [How they interact with this]
|
||||
- **[Role 3]:** [How they interact with this]
|
||||
|
||||
### Business Goals
|
||||
|
||||
1. [Goal 1]
|
||||
2. [Goal 2]
|
||||
3. [Goal 3]
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### [Concept 1]
|
||||
|
||||
**Definition:** [Clear definition]
|
||||
**Examples:** [Real-world examples]
|
||||
**Constraints:** [Business constraints]
|
||||
|
||||
### [Concept 2]
|
||||
|
||||
**Definition:** [Clear definition]
|
||||
**Examples:** [Real-world examples]
|
||||
**Constraints:** [Business constraints]
|
||||
|
||||
## Business Rules
|
||||
|
||||
### Rule 1: [Rule Name]
|
||||
|
||||
**Statement:** [Clear rule statement]
|
||||
|
||||
**Rationale:** [Why this rule exists]
|
||||
|
||||
**Applies to:** [Who/what this affects]
|
||||
|
||||
**Exceptions:** [When this rule doesn't apply]
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Given: [Initial state]
|
||||
When: [Action occurs]
|
||||
Then: [Expected outcome]
|
||||
```
|
||||
|
||||
### Rule 2: [Rule Name]
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## States and Transitions
|
||||
|
||||
### State Machine (if applicable)
|
||||
|
||||
```
|
||||
[Initial State]
|
||||
↓ [Event/Action]
|
||||
[Next State]
|
||||
↓ [Event/Action]
|
||||
[Final State]
|
||||
```
|
||||
|
||||
### State Definitions
|
||||
|
||||
**[State 1]**
|
||||
- **Meaning:** [What this state represents]
|
||||
- **Entry conditions:** [How entity enters this state]
|
||||
- **Exit conditions:** [How entity leaves this state]
|
||||
- **Allowed actions:** [What can happen in this state]
|
||||
|
||||
**[State 2]**
|
||||
[Same structure]
|
||||
|
||||
### Transition Rules
|
||||
|
||||
**[State A] → [State B]**
|
||||
- **Trigger:** [What causes transition]
|
||||
- **Conditions:** [Required conditions]
|
||||
- **Side effects:** [What else happens]
|
||||
- **Validation:** [What must be true]
|
||||
|
||||
## Permissions and Access Control
|
||||
|
||||
### Who Can Do What
|
||||
|
||||
**[Role 1]:**
|
||||
- ✅ Can: [Action 1, Action 2]
|
||||
- ❌ Cannot: [Action 3, Action 4]
|
||||
- ⚠️ Conditional: [Action 5 - under conditions]
|
||||
|
||||
**[Role 2]:**
|
||||
[Same structure]
|
||||
|
||||
### Permission Rules
|
||||
|
||||
**Rule:** [Permission rule statement]
|
||||
**Logic:**
|
||||
```
|
||||
IF [condition]
|
||||
AND [condition]
|
||||
THEN [permission granted/denied]
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Field Validations
|
||||
|
||||
**[Field 1]:**
|
||||
- **Type:** [Data type]
|
||||
- **Required:** [Yes/No]
|
||||
- **Format:** [Pattern or format]
|
||||
- **Range:** [Min/max values]
|
||||
- **Business rule:** [Any business constraint]
|
||||
|
||||
**[Field 2]:**
|
||||
[Same structure]
|
||||
|
||||
### Cross-Field Validations
|
||||
|
||||
**Validation 1:** [Description]
|
||||
```
|
||||
IF [field1] is [value]
|
||||
THEN [field2] must be [constraint]
|
||||
```
|
||||
|
||||
**Validation 2:** [Description]
|
||||
```
|
||||
[Validation logic]
|
||||
```
|
||||
|
||||
## Workflows
|
||||
|
||||
### Workflow 1: [Workflow Name]
|
||||
|
||||
**Trigger:** [What initiates this workflow]
|
||||
|
||||
**Steps:**
|
||||
1. **[Step 1]**
|
||||
- Actor: [Who performs this]
|
||||
- Action: [What happens]
|
||||
- Validation: [What's checked]
|
||||
- Outcome: [Result]
|
||||
|
||||
2. **[Step 2]**
|
||||
[Same structure]
|
||||
|
||||
3. **[Step 3]**
|
||||
[Same structure]
|
||||
|
||||
**Success Criteria:** [What defines success]
|
||||
**Failure Scenarios:** [What can go wrong]
|
||||
|
||||
## Calculations and Algorithms
|
||||
|
||||
### Calculation 1: [Name]
|
||||
|
||||
**Purpose:** [What this calculates]
|
||||
|
||||
**Formula:**
|
||||
```
|
||||
[Mathematical or logical formula]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Given:
|
||||
- input1 = [value]
|
||||
- input2 = [value]
|
||||
|
||||
Calculation:
|
||||
result = [formula applied]
|
||||
|
||||
Output: [result]
|
||||
```
|
||||
|
||||
**Edge Cases:**
|
||||
- [Edge case 1 and handling]
|
||||
- [Edge case 2 and handling]
|
||||
|
||||
## Constraints and Limits
|
||||
|
||||
### Business Constraints
|
||||
|
||||
1. **[Constraint 1]:** [Description and rationale]
|
||||
2. **[Constraint 2]:** [Description and rationale]
|
||||
3. **[Constraint 3]:** [Description and rationale]
|
||||
|
||||
### System Limits
|
||||
|
||||
- **[Limit 1]:** [Value and reason]
|
||||
- **[Limit 2]:** [Value and reason]
|
||||
- **[Limit 3]:** [Value and reason]
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### Edge Case 1: [Scenario]
|
||||
|
||||
**Situation:** [Describe the edge case]
|
||||
**Business Rule:** [How to handle it]
|
||||
**Example:** [Concrete example]
|
||||
|
||||
### Edge Case 2: [Scenario]
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Compliance and Regulations
|
||||
|
||||
### Regulatory Requirements
|
||||
|
||||
**[Regulation 1]:** [How it affects this domain concept]
|
||||
**[Regulation 2]:** [How it affects this domain concept]
|
||||
|
||||
### Audit Requirements
|
||||
|
||||
- **What to log:** [Events/changes to track]
|
||||
- **Retention:** [How long to keep records]
|
||||
- **Who can access:** [Audit log access rules]
|
||||
|
||||
## Reporting and Analytics
|
||||
|
||||
### Key Metrics
|
||||
|
||||
1. **[Metric 1]:** [What it measures and why it matters]
|
||||
2. **[Metric 2]:** [What it measures and why it matters]
|
||||
3. **[Metric 3]:** [What it measures and why it matters]
|
||||
|
||||
### Reporting Requirements
|
||||
|
||||
- **[Report 1]:** [Purpose, frequency, audience]
|
||||
- **[Report 2]:** [Purpose, frequency, audience]
|
||||
|
||||
## Examples and Scenarios
|
||||
|
||||
### Scenario 1: [Happy Path]
|
||||
|
||||
**Description:** [Common successful scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Step with data]
|
||||
3. [Step with outcome]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
### Scenario 2: [Error Case]
|
||||
|
||||
**Description:** [Common error scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Error condition]
|
||||
3. [Error handling per business rules]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
### Scenario 3: [Edge Case]
|
||||
|
||||
**Description:** [Unusual but valid scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Edge condition]
|
||||
3. [Special handling]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
## Integration Points
|
||||
|
||||
### System Touchpoints
|
||||
|
||||
**[System 1]:**
|
||||
- **Interaction:** [How they interact]
|
||||
- **Data shared:** [What data flows]
|
||||
- **Trigger:** [What causes interaction]
|
||||
|
||||
**[System 2]:**
|
||||
[Same structure]
|
||||
|
||||
## Glossary
|
||||
|
||||
**[Term 1]:** [Definition in this context]
|
||||
**[Term 2]:** [Definition in this context]
|
||||
**[Term 3]:** [Definition in this context]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Patterns:** [Pattern Doc](../patterns/doc.md) - [Technical implementation]
|
||||
- **Interfaces:** [Interface Doc](../interfaces/doc.md) - [External systems]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/PRD.md) - [Feature requirements]
|
||||
|
||||
## References
|
||||
|
||||
- [Business document or policy]
|
||||
- [Industry standard or regulation]
|
||||
- [Internal decision document]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Reason | Author |
|
||||
|------|--------|--------|--------|
|
||||
| [Date] | Initial documentation | [Why] | [Name/Tool] |
|
||||
| [Date] | Updated [aspect] | [Why] | [Name/Tool] |
|
||||
255
skills/documentation/templates/interface-template.md
Normal file
255
skills/documentation/templates/interface-template.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# [Service Name] Integration
|
||||
|
||||
> **Category:** External Interface
|
||||
> **Service:** [Service Name]
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Deprecated/Planned]
|
||||
|
||||
## Overview
|
||||
|
||||
**Service:** [Full service name]
|
||||
**Provider:** [Company/organization]
|
||||
**Purpose:** [What this integration accomplishes]
|
||||
**Documentation:** [Link to official API docs]
|
||||
|
||||
## Authentication
|
||||
|
||||
### Method
|
||||
|
||||
[OAuth 2.0 / API Key / Basic Auth / JWT / etc.]
|
||||
|
||||
### Credentials Management
|
||||
|
||||
**Location:** [Where credentials are stored]
|
||||
**Environment Variables:**
|
||||
```bash
|
||||
SERVICE_API_KEY=xxx
|
||||
SERVICE_SECRET=xxx
|
||||
SERVICE_ENDPOINT=https://...
|
||||
```
|
||||
|
||||
**Rotation Policy:** [How often credentials change]
|
||||
|
||||
### Authentication Example
|
||||
|
||||
```[language]
|
||||
// Example of authentication setup
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## API Endpoints Used
|
||||
|
||||
### Endpoint 1: [Name]
|
||||
|
||||
**URL:** `[METHOD] /path/to/endpoint`
|
||||
**Purpose:** [What this endpoint does]
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"field1": "value",
|
||||
"field2": "value"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": { }
|
||||
}
|
||||
```
|
||||
|
||||
**Error Handling:**
|
||||
- `400`: [How we handle]
|
||||
- `401`: [How we handle]
|
||||
- `500`: [How we handle]
|
||||
|
||||
### Endpoint 2: [Name]
|
||||
|
||||
**URL:** `[METHOD] /path/to/endpoint`
|
||||
**Purpose:** [What this endpoint does]
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## Webhooks (if applicable)
|
||||
|
||||
### Webhook 1: [Event Name]
|
||||
|
||||
**Event Type:** `[event.type]`
|
||||
**Trigger:** [When this fires]
|
||||
**URL:** `[Your webhook endpoint]`
|
||||
|
||||
**Payload:**
|
||||
```json
|
||||
{
|
||||
"event": "type",
|
||||
"data": { }
|
||||
}
|
||||
```
|
||||
|
||||
**Signature Verification:**
|
||||
```[language]
|
||||
// How to verify webhook authenticity
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
```[language]
|
||||
// How we process this webhook
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
- **Requests per second:** [Limit]
|
||||
- **Requests per day:** [Limit]
|
||||
- **Burst limit:** [Limit]
|
||||
|
||||
**Handling Strategy:** [How we respect limits]
|
||||
```[language]
|
||||
// Rate limiting implementation
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Data Mapping
|
||||
|
||||
### Our Model → Service Model
|
||||
|
||||
| Our Field | Service Field | Transformation |
|
||||
|-----------|---------------|----------------|
|
||||
| `userId` | `external_id` | String conversion |
|
||||
| `email` | `email_address` | Direct mapping |
|
||||
| `amount` | `total_cents` | Multiply by 100 |
|
||||
|
||||
### Service Model → Our Model
|
||||
|
||||
| Service Field | Our Field | Transformation |
|
||||
|---------------|-----------|----------------|
|
||||
| `id` | `externalId` | Direct mapping |
|
||||
| `status` | `state` | Enum mapping |
|
||||
| `created_at` | `createdAt` | ISO 8601 parse |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Error 1: [Name/Code]**
|
||||
- **Cause:** [What triggers this]
|
||||
- **Recovery:** [How we handle it]
|
||||
- **Retry:** [Yes/No, strategy]
|
||||
|
||||
**Error 2: [Name/Code]**
|
||||
- **Cause:** [What triggers this]
|
||||
- **Recovery:** [How we handle it]
|
||||
- **Retry:** [Yes/No, strategy]
|
||||
|
||||
### Retry Strategy
|
||||
|
||||
```[language]
|
||||
// Exponential backoff implementation
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Credentials
|
||||
|
||||
**Sandbox URL:** `https://sandbox.service.com`
|
||||
**Test API Key:** `[Where to get it]`
|
||||
|
||||
### Mock Server
|
||||
|
||||
**Location:** `tests/mocks/[service]-mock.ts`
|
||||
**Usage:**
|
||||
```[language]
|
||||
// How to use mock in tests
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```[language]
|
||||
// Example integration test
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Health Checks
|
||||
|
||||
**Endpoint:** `[Service status endpoint]`
|
||||
**Frequency:** [How often we check]
|
||||
|
||||
### Metrics to Track
|
||||
|
||||
- Request success rate
|
||||
- Response time (p50, p95, p99)
|
||||
- Error rate by type
|
||||
- Rate limit proximity
|
||||
|
||||
### Alerts
|
||||
|
||||
- **Critical:** [Conditions that trigger urgent alerts]
|
||||
- **Warning:** [Conditions that trigger warnings]
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- [Security consideration 1]
|
||||
- [Security consideration 2]
|
||||
- [Security consideration 3]
|
||||
|
||||
## Compliance
|
||||
|
||||
**Data Handling:**
|
||||
- PII fields: [List]
|
||||
- Retention policy: [Duration]
|
||||
- Geographic restrictions: [Any]
|
||||
|
||||
**Regulations:**
|
||||
- GDPR: [Compliance notes]
|
||||
- CCPA: [Compliance notes]
|
||||
- Other: [Relevant regulations]
|
||||
|
||||
## Cost Considerations
|
||||
|
||||
**Pricing Model:** [How service charges]
|
||||
**Cost per request:** [Estimate]
|
||||
**Monthly estimate:** [Based on usage]
|
||||
|
||||
## Migration/Upgrade Path
|
||||
|
||||
**Current Version:** [Version]
|
||||
**Upgrade Available:** [Yes/No, version]
|
||||
**Breaking Changes:** [List if applicable]
|
||||
|
||||
**Migration Steps:**
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Patterns:** [Pattern Doc](../patterns/doc.md) - [How we use this service]
|
||||
- **Domain:** [Domain Doc](../domain/doc.md) - [Business rules related to this]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Implementation details]
|
||||
|
||||
## External Resources
|
||||
|
||||
- [Official API documentation]
|
||||
- [Status page]
|
||||
- [Developer community/forum]
|
||||
- [SDK/library used]
|
||||
|
||||
## Contact
|
||||
|
||||
**Support:** [How to get help]
|
||||
**Account Manager:** [If applicable]
|
||||
**Escalation:** [Critical issue contact]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Author |
|
||||
|------|--------|--------|
|
||||
| [Date] | Initial integration | [Name/Tool] |
|
||||
| [Date] | Updated to v2 API | [Name/Tool] |
|
||||
144
skills/documentation/templates/pattern-template.md
Normal file
144
skills/documentation/templates/pattern-template.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# [Pattern Name]
|
||||
|
||||
> **Category:** Technical Pattern
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Deprecated/Proposed]
|
||||
|
||||
## Purpose
|
||||
|
||||
[Brief description of what this pattern accomplishes and why it exists]
|
||||
|
||||
## Context
|
||||
|
||||
**When to use this pattern:**
|
||||
- [Scenario 1]
|
||||
- [Scenario 2]
|
||||
- [Scenario 3]
|
||||
|
||||
**When NOT to use this pattern:**
|
||||
- [Anti-scenario 1]
|
||||
- [Anti-scenario 2]
|
||||
|
||||
## Implementation
|
||||
|
||||
### Overview
|
||||
|
||||
[High-level description of how the pattern works]
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
[Directory structure or component organization]
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
**[Component 1 Name]**
|
||||
- Purpose: [What it does]
|
||||
- Responsibilities: [What it handles]
|
||||
- Location: [Where to find it]
|
||||
|
||||
**[Component 2 Name]**
|
||||
- Purpose: [What it does]
|
||||
- Responsibilities: [What it handles]
|
||||
- Location: [Where to find it]
|
||||
|
||||
### Code Example
|
||||
|
||||
```[language]
|
||||
// Example implementation showing the pattern in action
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: [Scenario Name]
|
||||
|
||||
**Situation:** [Describe the use case]
|
||||
|
||||
**Implementation:**
|
||||
```[language]
|
||||
[Code showing how pattern is applied]
|
||||
```
|
||||
|
||||
**Result:** [What this achieves]
|
||||
|
||||
### Example 2: [Scenario Name]
|
||||
|
||||
**Situation:** [Describe the use case]
|
||||
|
||||
**Implementation:**
|
||||
```[language]
|
||||
[Code showing how pattern is applied]
|
||||
```
|
||||
|
||||
**Result:** [What this achieves]
|
||||
|
||||
## Edge Cases and Gotchas
|
||||
|
||||
### Edge Case 1: [Case Name]
|
||||
|
||||
**Problem:** [What can go wrong]
|
||||
**Solution:** [How to handle it]
|
||||
|
||||
### Edge Case 2: [Case Name]
|
||||
|
||||
**Problem:** [What can go wrong]
|
||||
**Solution:** [How to handle it]
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **[Practice 1]:** [Description]
|
||||
2. **[Practice 2]:** [Description]
|
||||
3. **[Practice 3]:** [Description]
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
❌ **Don't:** [What to avoid]
|
||||
**Why:** [Reason]
|
||||
**Instead:** [Better approach]
|
||||
|
||||
❌ **Don't:** [What to avoid]
|
||||
**Why:** [Reason]
|
||||
**Instead:** [Better approach]
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**How to test code using this pattern:**
|
||||
- [Testing approach 1]
|
||||
- [Testing approach 2]
|
||||
- [Testing approach 3]
|
||||
|
||||
**Example test:**
|
||||
```[language]
|
||||
[Test code example]
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **[Aspect 1]:** [Performance implication]
|
||||
- **[Aspect 2]:** [Performance implication]
|
||||
- **[Aspect 3]:** [Performance implication]
|
||||
|
||||
## Related Patterns
|
||||
|
||||
- [Pattern Name](./pattern-file.md) - [Relationship description]
|
||||
- [Pattern Name](./pattern-file.md) - [Relationship description]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Domain:** [Domain Doc](../domain/doc.md) - [Relevance]
|
||||
- **Interfaces:** [Interface Doc](../interfaces/doc.md) - [Relevance]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Relevance]
|
||||
|
||||
## References
|
||||
|
||||
- [External resource 1]
|
||||
- [External resource 2]
|
||||
- [Internal decision doc or RFC]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Author |
|
||||
|------|--------|--------|
|
||||
| [Date] | Initial documentation | [Name/Tool] |
|
||||
Reference in New Issue
Block a user