zhongwei/gh-jpicklyk-task-orchestrator-claude-plugins-task-orchestrator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:29:28 +08:00
commit 87c03319a3
50 changed files with 21409 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
skills/feature-orchestration/SKILL.md Normal file
View File

@@ -0,0 +1,411 @@
---
skill: feature-orchestration
description: Intelligent feature lifecycle management with smart routing, parallel execution planning, and quality gate enforcement. Replaces Feature Management Skill with enhanced capabilities.
---
# Feature Orchestration Skill
Comprehensive feature lifecycle management from creation through completion, with intelligent complexity assessment and automatic orchestration.
## When to Use This Skill
**Activate for:**
- "Create a feature for X"
- "What's next for feature Y?"
- "Complete feature Z"
- "Check feature progress"
- "Plan feature execution"
**This skill handles:**
- Feature creation with complexity assessment
- Task breakdown coordination
- Parallel execution planning
- Feature status progression
- Quality gate validation
- Feature completion
## Tools Available
- `query_container` - Read features, tasks, projects
- `query_sections` - Read sections with tag filtering (**Token optimized**)
- `manage_container` - Create/update features and tasks
- `query_workflow_state` - Check workflow state, cascade events, prerequisites (**NEW**)
- `query_templates` - Discover available templates
- `apply_template` - Apply templates to features
- `recommend_agent` - Route tasks to specialists
- `manage_sections` - Create feature documentation
## Section Tag Taxonomy
**When reading feature/task sections, use tag filtering for token efficiency:**
**Contextual Tags** (Planning Specialist reads from features):
- **context** - Business context, user needs, dependencies
- **requirements** - Functional requirements, must-haves, constraints
- **acceptance-criteria** - Completion criteria, quality standards
**Actionable Tags** (Implementation Specialist reads from tasks):
- **workflow-instruction** - Step-by-step processes
- **checklist** - Validation checklists, completion criteria
- **commands** - Bash commands to execute
- **guidance** - Implementation patterns
- **process** - Workflow processes
**Reference Tags** (Read as needed):
- **reference** - Examples, patterns
- **technical-details** - Deep technical specs
**Example - Efficient Section Reading:**
```javascript
// Planning Specialist reads only context/requirements from feature
sections = query_sections(
entityType="FEATURE",
entityId=featureId,
tags="context,requirements,acceptance-criteria",
includeContent=true
)
// Token cost: ~2-3k vs ~7k+ with all sections (60% savings)
// Implementation Specialist reads only actionable content from task
sections = query_sections(
entityType="TASK",
entityId=taskId,
tags="workflow-instruction,checklist,commands,guidance",
includeContent=true
)
// Token cost: ~800-1.5k vs ~3-5k with all sections (50% savings)
```
**Note:** Subagents (Feature Architect, Planning Specialist, Implementation Specialist) automatically use tag filtering. This reference is for direct tool usage.
## Cascade Event Detection (Automatic)
**Recommended Approach:** Use `query_workflow_state` for automatic cascade event detection instead of manual checks.
```javascript
// After task completion or status change
workflowState = query_workflow_state(
containerType="feature",
id=task.featureId
)
// Check for detected cascade events
if (workflowState.detectedEvents.length > 0) {
for (event of workflowState.detectedEvents) {
// Event structure:
// - event: "all_tasks_complete", "first_task_started", etc.
// - suggestedStatus: Next recommended status
// - automatic: Whether to apply automatically
// - reason: Human-readable explanation
if (event.automatic) {
"✅ Cascade event detected: ${event.event}
Suggested next status: ${event.suggestedStatus}
Reason: ${event.reason}
Use Status Progression Skill to apply this transition."
}
}
}
```
**Benefits:**
- Automatic detection based on config-driven workflows
- Works with custom user flows, not just defaults
- Handles complex prerequisite checking
- Provides human-readable explanations
## Status Progression Trigger Points (Manual Detection)
**Legacy Pattern:** Manual detection is still available but `query_workflow_state` is preferred.
**CRITICAL:** Never directly change feature status. Always use Status Progression Skill for ALL status changes.
These are universal events that trigger status progression checks, regardless of the user's configured status flow:
| Event | When to Check | Detection Pattern | Condition | Action |
|-------|---------------|-------------------|-----------|--------|
| **first_task_started** | After any task status changes to execution phase | `query_container(operation="overview", containerType="feature", id=task.featureId)` | `taskCounts.byStatus["in-progress"] == 1` | Use Status Progression Skill to progress feature |
| **all_tasks_complete** | After any task marked completed/cancelled | `query_container(operation="overview", containerType="feature", id=task.featureId)` | `taskCounts.byStatus.pending == 0 && taskCounts.byStatus["in-progress"] == 0` | Use Status Progression Skill to progress feature |
| **tests_passed** | After test execution completes | External test hook or manual trigger | `testResults.allPassed == true` | Use Status Progression Skill with context: `{testsPass: true, totalTests: N}` |
| **tests_failed** | After test execution completes | External test hook or manual trigger | `testResults.anyFailed == true` | Use Status Progression Skill with context: `{testsFailed: true, failures: [...]}` |
| **review_approved** | After human review | User/external signal | Review completed with approval | Use Status Progression Skill |
| **changes_requested** | After human review | User/external signal | Review rejected, rework needed | Use Status Progression Skill (may move backward) |
| **completion_requested** | User asks to complete feature | Direct user request | User says "complete feature" | Use Status Progression Skill, ask user to confirm if prerequisites met |
### Detection Example: All Tasks Complete
```javascript
// After a task is marked complete, check feature progress
task = query_container(operation="get", containerType="task", id=taskId)
if (task.featureId) {
// Query feature to check all task statuses
feature = query_container(
operation="overview",
containerType="feature",
id=task.featureId
)
// Detect event: all tasks complete
pending = feature.taskCounts.byStatus.pending || 0
inProgress = feature.taskCounts.byStatus["in-progress"] || 0
if (pending == 0 && inProgress == 0) {
// EVENT DETECTED: all_tasks_complete
// Delegate to Status Progression Skill
"Use Status Progression Skill to progress feature status.
Context: All ${feature.taskCounts.total} tasks complete
(${feature.taskCounts.byStatus.completed} completed,
${feature.taskCounts.byStatus.cancelled || 0} cancelled)."
// Status Progression Skill determines next status based on config
}
}
```
For more detection examples, see [examples.md](examples.md)
## Core Workflows
### 1. Smart Feature Creation
**Assess complexity first:**
- Simple: Request < 200 chars, clear purpose, expected tasks < 3
- Complex: Multiple components, integration requirements, expected tasks ≥ 5
**For SIMPLE features:**
1. Discover templates: `query_templates(operation="list", targetEntityType="FEATURE", isEnabled=true)`
2. Create feature with templates: `manage_container(operation="create", containerType="feature", status="draft", ...)`
3. Create 2-3 tasks directly (tasks start in "backlog" status)
4. Use Status Progression Skill to move feature: draft → planning
**For COMPLEX features:**
1. **Launch Feature Architect subagent** for detailed planning:
```
Use Task tool with subagent_type="Feature Architect" and prompt:
"Create a feature for [user's request].
- Read context from [file path if provided]
- Formalize requirements
- Discover and apply appropriate templates
- Create comprehensive feature structure with sections"
```
2. Feature Architect will create feature with templates and sections
3. **Then launch Planning Specialist** for task breakdown:
```
Use Task tool with subagent_type="Planning Specialist" and prompt:
"Break down feature [feature-id] into domain-isolated tasks with dependencies.
Create execution graph with parallel batches."
```
**CRITICAL:** For complex features (8+ tasks from the testing prompt), ALWAYS launch Feature Architect first, then Planning Specialist. DO NOT create features and tasks directly.
See [examples.md](examples.md) for detailed scenarios.
### 2. Task Breakdown Coordination
**After feature creation:**
**For SIMPLE breakdown (< 5 tasks):**
- Create tasks directly with templates
- Discover task templates: `query_templates(operation="list", targetEntityType="TASK", isEnabled=true)`
- Create 2-4 tasks in "backlog" status
**For COMPLEX breakdown (5+ tasks, multiple domains):**
1. **Launch Planning Specialist subagent** (MANDATORY):
```
Use Task tool with subagent_type="Planning Specialist" and prompt:
"Break down feature [feature-id or name] into domain-isolated tasks.
Feature: [brief description]
Create:
- Domain-isolated tasks (database, backend, frontend, testing, docs)
- BLOCKS dependencies between tasks
- Execution graph with parallel batches
- Provide execution order recommendation"
```
2. Planning Specialist will create all tasks with dependencies automatically
3. Planning Specialist returns execution graph showing batch order
**CRITICAL:** For the testing prompt (8 features with varying task counts), use Planning Specialist for features with 4+ tasks. DO NOT create tasks manually for complex features.
### 2.5. Phase 3 Handoff (Before Task Execution)
**CRITICAL: Before delegating to Task Orchestration Skill, progress feature status.**
When tasks are ready to execute (Phase 3 of coordinate_feature_development):
1. **Check current feature status:**
```javascript
feature = query_container(operation="get", containerType="feature", id=featureId)
```
2. **If status is "planning" or "draft" and tasks exist:**
```javascript
if ((feature.status == "planning" || feature.status == "draft") && taskCount > 0) {
"Use Status Progression Skill to progress feature status.
Cascade Event: tasks_ready_to_execute
Current Status: ${feature.status}
The Status Progression Skill will:
1. Call get_next_status to determine appropriate next status (config-driven)
2. Apply the recommended status based on your workflow
3. Different workflows may use different status names (e.g., 'in-development', 'active', 'implementing')
Why this matters: Feature status must reflect current development phase.
Skipping this causes feature to jump directly to completion, missing execution phase."
}
```
3. **Then delegate to Task Orchestration Skill:**
```
Skill(command="task-orchestration")
"Execute tasks for feature [featureName].
Feature ID: [featureId]
Execution graph:
[paste execution graph]
Guide me through parallel execution."
```
**When to perform this handoff:**
- After Phase 2 (task breakdown) completes
- Before Phase 3 (task execution) begins
- When resuming paused feature work
**Why this is critical:**
- Prevents feature status from being stuck in "planning" during active development
- Enables proper cascade event detection (tasks_ready_to_execute)
- Ensures workflow state accurately reflects reality (config determines execution phase status)
- Required for StatusValidator prerequisite checking
- Respects user's custom workflow definitions (not hardcoded to specific status names)
### 3. Feature Progress Tracking
**Check feature status:**
```javascript
feature = query_container(operation="overview", containerType="feature", id="...")
// Analyze task counts
if (all tasks completed) {
// Use Status Progression Skill to move to testing/completion
} else if (has blocked tasks) {
// Address blockers first
} else if (has pending tasks) {
// Launch next batch
}
```
### 4. Quality Gate Validation
**Prerequisites Enforced Automatically:**
Status Progression Skill validates prerequisites when changing status. You don't manually check these - just attempt the status change and handle validation errors.
| Transition | Prerequisites | Enforced By |
|------------|---------------|-------------|
| planning → in-development | ≥1 task created | StatusValidator |
| in-development → testing | All tasks completed/cancelled | StatusValidator |
| testing/validating → completed | All tasks completed/cancelled | StatusValidator |
**Validation Pattern:**
1. Use Status Progression Skill to change status
2. If validation fails → Skill returns detailed error
3. Resolve blocker (create tasks, complete dependencies, etc.)
4. Retry via Status Progression Skill
For common validation errors and solutions, see [troubleshooting.md](troubleshooting.md)
### 5. Feature Completion
**Tool Orchestration Pattern:**
```javascript
// Step 1: Check all tasks complete
overview = query_container(operation="overview", containerType="feature", id="...")
// Step 2: Create feature summary section (optional but recommended)
manage_sections(operation="add", entityType="FEATURE", ...)
// Step 3: Use Status Progression Skill to mark complete
"Use Status Progression Skill to mark feature as completed"
// Skill validates prerequisites automatically
// If validation fails, returns detailed error with what's missing
```
## Status Progression Flow (Config-Driven)
**The actual status flow depends on the user's `.taskorchestrator/config.yaml` and feature tags.**
**Common flows:**
- **default_flow**: draft → planning → in-development → testing → validating → completed
- **rapid_prototype_flow**: draft → in-development → completed (skip testing)
- **with_review_flow**: ... → validating → pending-review → completed
**How flow is determined:**
1. Status Progression Skill calls `get_next_status(featureId)`
2. Tool reads `.taskorchestrator/config.yaml`
3. Tool matches feature tags against `flow_mappings`
4. Tool recommends next status from matched flow
5. StatusValidator validates prerequisites at write-time
**Your role:** Detect events (table above), delegate to Status Progression Skill, let config determine actual statuses.
For flow details and examples, see [config-reference.md](config-reference.md)
## Token Efficiency
- Use `operation="overview"` for status checks (90% token reduction vs full get)
- Batch operations where possible
- Return brief status updates, not full context
- Delegate complex work to subagents
- Query only necessary task fields
**Example:**
```javascript
// Efficient: 1.2k tokens
query_container(operation="overview", containerType="feature", id="...")
// Inefficient: 18k tokens
query_container(operation="get", containerType="feature", id="...", includeSections=true)
```
## Integration with Other Skills
**Works alongside:**
- **Task Orchestration Skill** - Delegates task execution
- **Dependency Orchestration Skill** - For complex dependency analysis
- **Status Progression Skill** - For status management (ALWAYS use this for status changes)
**Launches subagents:**
- **Feature Architect** - Complex feature formalization
- **Planning Specialist** - Complex task breakdown
## Best Practices
1. **Always assess complexity** before creating features
2. **Always discover templates** via `query_templates` before creation
3. **Use overview operations** for status checks (token efficiency)
4. **Batch task creation** when creating multiple tasks
5. **Delegate to Status Progression Skill** for ALL status changes
6. **Return concise summaries** to orchestrator
7. **Delegate to subagents** when complexity exceeds threshold
8. **Monitor feature progress** after task completions
## Success Metrics
- Simple features created in < 5 tool calls
- 40% time savings with parallel execution
- 60% token reduction vs old Feature Management skill
- 95% successful quality gate validation
- Zero manual intervention for standard workflows
## Additional Resources
- **Detailed Examples**: See [examples.md](examples.md) for complete walkthroughs
- **Error Handling**: See [troubleshooting.md](troubleshooting.md) for validation errors
- **Configuration**: See [config-reference.md](config-reference.md) for flow customization

540
skills/feature-orchestration/config-reference.md Normal file
View File

@@ -0,0 +1,540 @@
# Feature Orchestration - Configuration Reference
Complete guide to configuring feature status workflows in `.taskorchestrator/config.yaml`.
## Status Flow Configuration
Feature workflows are configured in `.taskorchestrator/config.yaml` using the `status_flows` section.
### Built-in Flows
#### default_flow (Most Common)
```yaml
feature_status_flows:
default_flow:
- draft
- planning
- in-development
- testing
- validating
- completed
```
**Use for:** Standard feature development with full QA process
**Phases:**
- **draft** → **planning**: Initial concept, gathering requirements
- **planning** → **in-development**: Requirements defined, tasks created, work begins
- **in-development** → **testing**: All tasks complete, ready for QA
- **testing** → **validating**: Tests pass, final checks
- **validating** → **completed**: All validation complete, feature shipped
**Prerequisites:**
- planning → in-development: ≥1 task created
- in-development → testing: All tasks completed/cancelled
- testing → validating: Tests passed
- validating → completed: All tasks completed/cancelled
---
#### rapid_prototype_flow
```yaml
feature_status_flows:
rapid_prototype_flow:
- draft
- in-development
- completed
```
**Use for:** Quick prototypes, spikes, proof-of-concepts
**Phases:**
- **draft** → **in-development**: Start coding immediately
- **in-development** → **completed**: Work done, skip testing
**Prerequisites:**
- draft → in-development: None (can start immediately)
- in-development → completed: All tasks completed/cancelled
**Warning:** No testing phase - use only for throwaway prototypes
---
#### with_review_flow
```yaml
feature_status_flows:
with_review_flow:
- draft
- planning
- in-development
- testing
- validating
- pending-review
- completed
```
**Use for:** Features requiring human approval (security, architecture, UX)
**Phases:**
- Same as default_flow until **validating**
- **validating** → **pending-review**: Automated checks pass, waiting for human review
- **pending-review** → **completed**: Review approved, ship it
- **pending-review** → **in-development**: Changes requested, back to work (if allow_backward: true)
**Prerequisites:**
- All default_flow prerequisites plus:
- validating → pending-review: All validation complete
- pending-review → completed: Review approved (external signal)
---
## Flow Mapping (Tag-Based Routing)
Control which features use which flow via tags.
### Configuration Pattern
```yaml
status_flows:
feature_flows:
flow_mappings:
- tags: ["prototype", "spike", "poc"]
flow_name: rapid_prototype_flow
- tags: ["security", "architecture", "breaking-change"]
flow_name: with_review_flow
- tags: [] # Default - matches any feature without specific tags
flow_name: default_flow
```
### How Matching Works
1. Feature has tags: `["backend", "security", "api"]`
2. get_next_status checks mappings in order:
- First mapping: Does feature have ANY of `["prototype", "spike", "poc"]`? → No
- Second mapping: Does feature have ANY of `["security", "architecture", "breaking-change"]`? → Yes (security)
- **Match found** → Use `with_review_flow`
3. Feature has tags: `["frontend", "ui"]`
- First mapping: No match
- Second mapping: No match
- Third mapping: Empty tags `[]` → **Always matches** → Use `default_flow`
### Tag Strategy Best Practices
**Domain Tags** (don't affect flow):
- backend, frontend, database, testing, documentation
**Flow Routing Tags** (affect status flow):
- prototype, spike, poc → rapid_prototype_flow
- security, architecture, breaking-change → with_review_flow
**Example Feature Tagging:**
```javascript
// Standard feature - uses default_flow
manage_container(
operation="create",
containerType="feature",
tags="backend,api,user-management"
)
// Prototype - uses rapid_prototype_flow
manage_container(
operation="create",
containerType="feature",
tags="frontend,prototype,ui-experiment"
)
// Security feature - uses with_review_flow
manage_container(
operation="create",
containerType="feature",
tags="backend,security,oauth-integration"
)
```
---
## Prerequisite Validation
Configured in `status_validation` section.
### Validation Matrix
| Transition | Prerequisite | Validation Rule | Error if Failed |
|------------|--------------|-----------------|-----------------|
| planning → in-development | Task count ≥ 1 | `taskCounts.total >= 1` | "Feature must have at least 1 task before transitioning to IN_DEVELOPMENT" |
| in-development → testing | All tasks complete | `taskCounts.byStatus.pending == 0 && taskCounts.byStatus["in-progress"] == 0` | "Cannot transition to TESTING: X task(s) not completed" |
| testing → validating | Tests passed | External signal | "Cannot transition to VALIDATING: Tests not run or failing" |
| validating → completed | All tasks complete | `taskCounts.byStatus.pending == 0 && taskCounts.byStatus["in-progress"] == 0` | "Cannot transition to COMPLETED: X task(s) not completed" |
### Configuration Options
```yaml
status_validation:
validate_prerequisites: true # Enable validation (default: true)
```
**Production:** Always keep `validate_prerequisites: true`
**Development/Testing:** Set to `false` to bypass validation temporarily
---
## Backward Movement
Allow moving features backward in workflow (e.g., testing → in-development for rework).
### Configuration
```yaml
status_flows:
feature_flows:
allow_backward: true # Enable backward movement (default: false)
```
### When to Use
**Enable backward movement** (`allow_backward: true`):
- Code review finds issues → pending-review → in-development
- Tests fail → testing → in-development
- Requirements change during development
**Disable backward movement** (`allow_backward: false`):
- Strict waterfall process
- Audit/compliance requirements
- Prevent accidental status regression
### Example Backward Transition
```javascript
// Feature in testing, tests fail
feature.status = "testing"
// With allow_backward: true
"Use Status Progression Skill to move feature back to in-development"
// Allowed: testing → in-development
// With allow_backward: false
// Error: "Backward movement not allowed"
// Must cancel feature or fix in testing phase
```
---
## Emergency Transitions
Special transitions allowed from ANY status, regardless of flow configuration.
### Available Emergency Statuses
**blocked** - Cannot proceed due to external dependency
**on-hold** - Paused, not cancelled
**cancelled** - Work abandoned
**archived** - Completed work, no longer relevant
### Configuration
```yaml
status_flows:
feature_flows:
allow_emergency_transitions: true # Default: true
```
### Example Usage
```javascript
// Feature blocked by external API dependency
"Use Status Progression Skill to mark feature as blocked.
Context: Waiting for external API access from partner team"
// Feature on-hold due to business priority shift
"Use Status Progression Skill to put feature on-hold.
Context: Deprioritized for Q2, will resume in Q3"
```
---
## Quality Gates
Hook-based validation before status transitions.
### Configuration
```yaml
quality_gates:
enabled: true
feature_gates:
testing:
hook: "test_runner"
required: true
validating:
hook: "code_coverage"
required: false # Warning only
```
### Gate Behavior
**required: true** - Blocks status transition if gate fails
**required: false** - Shows warning but allows progression
### Example Gate Failure
```
Error: Cannot complete feature - testing gate failed
Hook: test_runner
Status: FAILED
Output: 3 test failures in authentication module
Actions:
1. Fix test failures
2. Re-run hook
3. Retry status transition
```
---
## Complete Configuration Example
```yaml
# .taskorchestrator/config.yaml
status_flows:
feature_flows:
# Feature status flows
default_flow:
- draft
- planning
- in-development
- testing
- validating
- completed
rapid_prototype_flow:
- draft
- in-development
- completed
with_review_flow:
- draft
- planning
- in-development
- testing
- validating
- pending-review
- completed
# Tag-based flow routing
flow_mappings:
- tags: ["prototype", "spike", "poc"]
flow_name: rapid_prototype_flow
- tags: ["security", "architecture", "breaking-change"]
flow_name: with_review_flow
- tags: [] # Default
flow_name: default_flow
# Behavior settings
allow_backward: true
allow_emergency_transitions: true
# Prerequisite validation
status_validation:
validate_prerequisites: true # Enforce prerequisite checks
# Quality gates (optional)
quality_gates:
enabled: false # Disable hooks for now
```
---
## Migration from Hardcoded Flows
**Before (v1.x - Hardcoded):**
```kotlin
// Code assumed specific status names
if (allTasksComplete) {
feature.status = "testing" // Breaks with custom configs
}
```
**After (v2.0 - Config-Driven):**
```javascript
// Skills detect events, delegate to Status Progression Skill
if (allTasksComplete) {
"Use Status Progression Skill to progress feature status.
Context: All tasks complete"
// Status Progression Skill:
// 1. Calls get_next_status tool
// 2. Tool reads user's config.yaml
// 3. Matches feature tags to flow_mappings
// 4. Recommends next status from matched flow
// Result: Could be "testing", "completed", "validating", etc.
}
```
---
## Custom Flow Creation
### Step 1: Define Flow Sequence
```yaml
status_flows:
feature_flows:
my_custom_flow:
- draft
- design
- implementation
- qa
- production
```
### Step 2: Add Flow Mapping
```yaml
status_flows:
feature_flows:
flow_mappings:
- tags: ["custom-process"]
flow_name: my_custom_flow
```
### Step 3: Tag Features
```javascript
manage_container(
operation="create",
containerType="feature",
tags="backend,custom-process",
name="New Feature"
)
```
### Step 4: Use Status Progression Skill
```javascript
"Use Status Progression Skill to progress feature to next status"
// Skill calls get_next_status
// Tool finds flow via tags → my_custom_flow
// Recommends next status from custom flow
```
---
## Troubleshooting Configuration
### Flow Not Activating
**Symptom:** Feature uses default_flow instead of custom flow
**Check:**
1. Feature has correct tags: `query_container(operation="get", containerType="feature", id="...")`
2. Tags match flow_mappings: Compare feature.tags to config.yaml mappings
3. Mapping order: Mappings checked top-to-bottom, first match wins
4. Empty tags mapping: Should always be last (catches all)
**Fix:**
```javascript
// Add missing tag
manage_container(
operation="update",
containerType="feature",
id="...",
tags="existing-tag,prototype" // Add flow routing tag
)
```
### Validation Blocking Progression
**Symptom:** Status change rejected with prerequisite error
**Check:**
1. Task counts: `query_container(operation="overview", containerType="feature", id="...")`
2. Review taskCounts.byStatus for incomplete tasks
3. Check config: Is `validate_prerequisites: true`?
**Fix Option A - Resolve Prerequisites:**
```javascript
// Complete or cancel remaining tasks
"Use Status Progression Skill to complete task X"
```
**Fix Option B - Bypass Validation (Development Only):**
```yaml
# .taskorchestrator/config.yaml
status_validation:
validate_prerequisites: false # Temporary bypass
```
### Backward Movement Blocked
**Symptom:** Cannot move feature from testing → in-development
**Check:**
```yaml
status_flows:
feature_flows:
allow_backward: false # ← This blocks backward movement
```
**Fix:**
```yaml
status_flows:
feature_flows:
allow_backward: true
```
---
## Best Practices
### 1. Start with default_flow
Most features should use the standard flow. Only add custom flows when needed.
### 2. Use flow routing tags sparingly
Too many flow routing tags creates confusion. Stick to:
- prototype/spike/poc → rapid_prototype_flow
- security/architecture/breaking-change → with_review_flow
- Everything else → default_flow
### 3. Keep validation enabled in production
```yaml
status_validation:
validate_prerequisites: true # Always in production
```
Only disable for local development/testing.
### 4. Document custom flows
If you create custom flows, document them in your project's README:
```markdown
## Custom Workflows
### design-first-flow
Used for features requiring upfront UX design approval.
Tags: ["ux-design", "design-first"]
Flow: draft → design → design-review → implementation → testing → completed
```
### 5. Test flow transitions
Before deploying custom config:
1. Create test feature with appropriate tags
2. Progress through each status
3. Verify prerequisites enforced correctly
4. Test backward movement (if enabled)
5. Test emergency transitions
---
## Related Documentation
- **Event-Driven Pattern**: See `docs/event-driven-status-progression-pattern.md`
- **Status Progression Skill**: See `.claude/skills/status-progression/SKILL.md`
- **Troubleshooting**: See `troubleshooting.md`
- **Examples**: See `examples.md`

553
skills/feature-orchestration/examples.md Normal file
View File

@@ -0,0 +1,553 @@
# Feature Orchestration Skill - Examples
## Example 1: Simple Feature Creation
**User Request:**
> "Create a user profile feature"
**Skill Assessment:**
- Description: Short and clear (< 50 characters)
- Scope: Single purpose (user profile)
- Expected tasks: 2-3 (database, backend, frontend)
- Complexity: Simple
**Actions:**
1. Query templates for FEATURE type
2. Create feature with "Requirements Specification" template
3. Create 3 tasks directly:
- Database: "Create user profile schema"
- Backend: "Implement profile API endpoints"
- Frontend: "Build profile UI component"
**Output:**
```
✓ Feature created: User Profile
Status: planning
Tasks: 3 created
Templates: Requirements Specification
Next: Ready for task execution. Use Task Orchestration Skill to begin.
```
---
## Example 2: Complex Feature - Delegate to Feature Architect
**User Request:**
> "Build a comprehensive OAuth integration system supporting Google, GitHub, and Microsoft authentication with JWT token management, refresh token handling, secure session storage, role-based access control, and audit logging"
**Skill Assessment:**
- Description: Long (> 200 characters)
- Scope: Multiple systems (OAuth providers, JWT, RBAC, audit)
- Technical complexity: High (authentication, security)
- Expected tasks: 8+ tasks
- Complexity: Complex
**Actions:**
1. Assess complexity score: 9/10
2. Return recommendation to orchestrator
**Output:**
```
⚠️ Complex Feature Detected
This feature requires detailed planning:
- Multiple integration points (3 OAuth providers)
- Security-critical components
- Cross-cutting concerns (RBAC, audit)
- Estimated 8+ tasks
**Decision: COMPLEX feature → Launch Feature Architect**
**Execution Pattern:**
```javascript
// Step 1: Launch Feature Architect subagent
Use Task tool with:
- subagent_type: "Feature Architect"
- description: "Create OAuth integration feature"
- prompt: `Create a feature for comprehensive OAuth integration system.
Requirements:
- Support Google, GitHub, and Microsoft authentication
- JWT token management
- Refresh token handling
- Secure session storage
- Role-based access control
- Audit logging
Steps:
1. Formalize requirements and create feature structure
2. Discover and apply appropriate templates (security, API design)
3. Create comprehensive sections
4. Return feature ID for task breakdown`
// Step 2: After Feature Architect completes, launch Planning Specialist
Use Task tool with:
- subagent_type: "Planning Specialist"
- description: "Break down OAuth feature into tasks"
- prompt: `Break down feature [feature-id-from-architect] into domain-isolated tasks.
Feature: OAuth integration system with multi-provider support
Create:
- Domain-isolated tasks (database, backend, frontend, security, testing, docs)
- BLOCKS dependencies showing execution order
- Execution graph with parallel batches`
```
---
## Example 2B: Multi-Feature Creation from Testing Plan
**User Request:**
> "Create a test project to validate our v2.0 event-driven feature and task orchestration workflows. Please read the testing plan at D:\Projects\task-orchestrator\tests\workflow-testing-plan.md"
**Skill Assessment:**
- Request involves: Creating 8 features with varying complexity
- Features range from 2 tasks to 8+ tasks
- Multiple workflow patterns to test
- File reference provided
- Complexity: VERY COMPLEX
**CRITICAL Decision: This requires Feature Architect for EACH complex feature**
**Execution Pattern:**
```javascript
// For EACH feature in the testing plan:
// Feature 1: Simple User Profile (2-3 tasks) → CREATE DIRECTLY
manage_container(operation="create", containerType="feature", name="User Profile Management", ...)
// Create 2-3 tasks directly
// Feature 2: Complex Payment System (8+ tasks) → LAUNCH FEATURE ARCHITECT
Use Task tool with:
- subagent_type: "Feature Architect"
- prompt: `Create feature: Payment Processing System
Read requirements from: D:\Projects\task-orchestrator\tests\workflow-testing-plan.md
Feature details in Test 2.2
Expected: 8+ tasks, complex workflow
Return feature ID when complete`
// After Feature Architect returns:
Use Task tool with:
- subagent_type: "Planning Specialist"
- prompt: `Break down feature [feature-id] into tasks per testing plan Test 2.2`
// Feature 3: Product Catalog (4 parallel tasks) → LAUNCH PLANNING SPECIALIST
manage_container(operation="create", containerType="feature", name="Product Catalog", ...)
Use Task tool with:
- subagent_type: "Planning Specialist"
- prompt: `Break down Product Catalog feature into 4 independent tasks (Test 3.1)`
// ... Repeat pattern for all 8 features
```
**Rules for Testing Plan:**
- Simple features (< 4 tasks): Create directly + create tasks directly
- Complex features (4-7 tasks): Create directly + **launch Planning Specialist**
- Very complex features (8+ tasks): **Launch Feature Architect + Planning Specialist**
**DO NOT:**
- ❌ Create all features and tasks manually (defeats the purpose of testing orchestration)
- ❌ Skip Planning Specialist for features with dependencies
- ❌ Skip Feature Architect for features with 8+ tasks
**Expected Workflow:**
1. Read testing plan file
2. For each feature, assess complexity
3. Route appropriately (direct, Planning Specialist, or Feature Architect → Planning Specialist)
4. Verify orchestration works correctly
---
## Example 3: Progress Feature to Testing
**User Request:**
> "Check status of authentication feature"
**Actions:**
1. Query feature with overview operation
2. Analyze task status:
- Total: 5 tasks
- Completed: 4 tasks
- In Progress: 1 task
3. Determine next status: Cannot progress yet
**Output:**
```
Feature: Authentication System
Status: in-development (80% complete)
Tasks:
✓ Database schema (completed)
✓ Backend API (completed)
✓ Frontend UI (completed)
✓ Unit tests (completed)
⏳ Integration tests (in-progress)
Cannot progress to testing yet - 1 task still in progress.
Next action: Wait for integration tests to complete.
```
---
## Example 4: Feature Completion with Quality Gates
**User Request:**
> "Complete authentication feature"
**Actions:**
1. Check all tasks completed: ✓
2. Trigger testing hook
3. Tests pass: ✓
4. Create feature summary section
5. Mark feature complete
**Output:**
```
✓ Feature Completed: Authentication System
Summary:
- 5 tasks completed
- All tests passing
- Coverage: 87%
Key Changes:
- OAuth integration with Google, GitHub
- JWT token management
- Session handling and refresh tokens
- Comprehensive test suite
Files Changed: 23 files
- Backend: 12 files
- Frontend: 8 files
- Tests: 3 files
```
---
## Example 5: Quality Gate Failure
**User Request:**
> "Complete user management feature"
**Actions:**
1. Validate completion readiness
2. All tasks complete: ✓
3. Trigger testing hook
4. Tests fail: ✗
**Output:**
```
✗ Cannot Complete Feature: Quality Gates Failing
Testing Gate: FAILED
- 3 test failures detected
• UserManagementTest.testDeleteUser
• UserManagementTest.testUpdatePermissions
• UserManagementTest.testBulkImport
Coverage Gate: WARNING
- Current: 68%
- Required: 80%
- Missing: 12% coverage
Actions Required:
1. Fix 3 failing tests
2. Add tests to reach 80% coverage threshold
3. Re-run testing gate
Suggestion: Launch Test Engineer to address failures.
```
---
## Example 6: Parallel Execution Planning
**User Request:**
> "Plan execution for notification system feature"
**Actions:**
1. Get all tasks (6 tasks total)
2. Analyze dependencies
3. Create execution batches
**Output:**
```
Execution Plan: Notification System
Batch 1 (Parallel - 40% time saved):
├─ Database schema (Complexity: 4)
├─ Email templates (Complexity: 3)
└─ UI notification center (Complexity: 5)
Total: 12 units → 5 units (parallel)
Batch 2 (Sequential):
└─ Backend notification service (Complexity: 7)
Depends on: Database schema
Batch 3 (Parallel - 33% time saved):
├─ Integration tests (Complexity: 5)
└─ Documentation (Complexity: 4)
Total: 9 units → 5 units (parallel)
Estimated Time Savings: 40% overall
Next: Launch Batch 1 with 3 specialists in parallel
```
---
## Example 7: Check Feature Progress
**User Request:**
> "What's next for the API redesign feature?"
**Actions:**
1. Query feature overview
2. Analyze current state
3. Determine blockers and next actions
**Output:**
```
Feature: API Redesign
Status: in-development
Progress: 60% (6/10 tasks)
Current Status:
✓ 4 completed
⏳ 2 in progress
• API versioning implementation
• Swagger documentation
⏸️ 4 pending
Blockers: None
Next Actions:
1. Wait for current 2 tasks to complete
2. Then launch Batch 3 (2 parallel tasks):
- Integration tests
- Migration scripts
Parallel opportunity available once current batch completes.
```
---
## Example 8: Feature with Review Gate
**User Request:**
> "Complete payment integration feature"
**Actions:**
1. Check configuration: review gate enabled
2. All tasks complete: ✓
3. Tests passing: ✓
4. Update status to pending-review
**Output:**
```
Feature: Payment Integration
Status: validating → pending-review
✓ All Prerequisites Met:
• All 8 tasks completed
• Tests passing (94% coverage)
• No blockers
⏸️ Awaiting Review:
Review required before completion (configured in .taskorchestrator/config.yaml)
Next: Review feature implementation, then:
• Approve: Move to completed
• Request changes: Return to in-development
```
---
## Token Usage Examples
### Efficient Status Check
```javascript
// Using overview operation
query_container(operation="overview", containerType="feature", id="uuid")
// Returns: ~1,200 tokens (task list + counts, no sections)
```
### Inefficient Status Check (Don't do this)
```javascript
// Using get with sections
query_container(operation="get", containerType="feature", id="uuid", includeSections=true)
// Returns: ~18,500 tokens (full sections + tasks)
```
**Savings: 93% token reduction**
---
## Integration Examples
### With Task Orchestration Skill
```
1. Feature Orchestration: Creates feature + tasks
2. Task Orchestration: Executes tasks in parallel batches
3. Feature Orchestration: Validates quality gates
4. Feature Orchestration: Marks complete
```
### With Dependency Orchestration Skill
```
User: "This feature has complex dependencies"
1. Feature Orchestration: Creates feature
2. Dependency Orchestration: Analyzes dependency graph
3. Task Orchestration: Uses analysis for batching
```
### With Status Progression Skill
```
User: "Progress feature through workflow"
1. Status Progression: Validates transition
2. Status Progression: Checks prerequisites
3. Feature Orchestration: Enforces quality gates
4. Status Progression: Updates status
```
---
## Event Detection Examples
### Detection: First Task Started
```javascript
// Triggered when ANY task changes to execution phase
function onTaskStatusChange(taskId, oldStatus, newStatus) {
// Check if transitioned into execution
if (isExecutionPhase(newStatus) && !isExecutionPhase(oldStatus)) {
task = query_container(operation="get", containerType="task", id=taskId)
if (task.featureId) {
// Query feature to check task counts
feature = query_container(
operation="overview",
containerType="feature",
id=task.featureId
)
// Count how many tasks in execution
inProgressCount = feature.taskCounts.byStatus["in-progress"] || 0
if (inProgressCount == 1) {
// This is the FIRST task to start work!
// EVENT DETECTED: first_task_started
"Use Status Progression Skill to progress feature status.
Context: First task started - ${task.title}"
// Possible outcomes based on user's config:
// - default_flow: planning → in-development
// - rapid_prototype_flow: draft → in-development
}
}
}
}
```
### Detection: Tests Passed
```javascript
// Triggered by external test hook or manual trigger
function onTestsComplete(featureId, testResults) {
if (testResults.allPassed) {
// EVENT DETECTED: tests_passed
"Use Status Progression Skill to progress feature status.
Context: Tests passed - ${testResults.total} tests successful"
// Possible outcomes:
// - default_flow: testing → validating
// - with_review_flow: testing → validating → pending-review
// - rapid_prototype_flow: (no testing, wouldn't get here)
}
}
```
### Detection: Review Completed
```javascript
// Triggered by user or external review system
function onReviewComplete(featureId, reviewResult) {
if (reviewResult.approved) {
// EVENT DETECTED: review_approved
"Use Status Progression Skill to progress feature status.
Context: Review approved by ${reviewResult.reviewer}"
// Possible outcome:
// - with_review_flow: pending-review → completed
} else {
// EVENT DETECTED: changes_requested
"Use Status Progression Skill to move feature back for rework.
Context: Changes requested - ${reviewResult.changesRequested}"
// Backward movement (if allow_backward: true):
// - pending-review → in-development
}
}
```
---
## Complexity Assessment Algorithm
```python
def assess_feature_complexity(user_request, context):
score = 0
# Length indicators
if len(user_request) > 200:
score += 2 # Long description suggests complexity
# Technical complexity keywords
integration_keywords = ["oauth", "api", "integration", "authentication",
"third-party", "external", "webhook"]
if has_keywords(user_request, integration_keywords):
score += 3 # Integrations add complexity
# Domain indicators
domains = count_domains(user_request) # database, backend, frontend, etc.
if domains >= 3:
score += 2 # Multiple domains = complex
# Scope clarity
unclear_keywords = ["might", "maybe", "possibly", "unclear", "TBD"]
if has_keywords(user_request, unclear_keywords):
score += 2 # Unclear scope needs exploration
# Expected task count
estimated_tasks = estimate_task_count(user_request)
if estimated_tasks >= 8:
score += 3 # Many tasks = complex
elif estimated_tasks >= 5:
score += 2 # Medium tasks = moderate
elif estimated_tasks >= 3:
score += 1 # Few tasks = simple
# Decision thresholds
if score <= 3:
return "simple" # Create directly with Feature Orchestration
elif score <= 6:
return "moderate" # Could go either way
else:
return "complex" # Launch Feature Architect subagent
```
**Example Assessments:**
| Request | Length | Integration | Domains | Tasks | Score | Result |
|---------|--------|-------------|---------|-------|-------|--------|
| "User profile feature" | 0 | 0 | 1 | 1 | 1 | Simple |
| "API for user management with CRUD operations" | 0 | 0 | 2 | 1 | 1 | Simple |
| "OAuth integration for Google and GitHub" | 0 | 3 | 2 | 2 | 7 | Complex |
| "Build comprehensive reporting system with analytics, dashboards, PDF export, scheduled emails, and data warehouse integration" | 2 | 3 | 3 | 3 | 13 | Complex |

286
skills/feature-orchestration/troubleshooting.md Normal file
View File

@@ -0,0 +1,286 @@
# Feature Orchestration - Troubleshooting Guide
Common validation errors and how to resolve them.
## Validation Error Patterns
### Error: "Feature must have at least 1 task before transitioning to IN_DEVELOPMENT"
**Cause:** Attempting to move feature from `planning` to `in-development` without creating any tasks.
**Solution:**
```javascript
// 1. Create at least one task for the feature
manage_container(
operation="create",
containerType="task",
title="Initial implementation task",
description="First task to start development",
featureId="feature-uuid",
priority="high",
complexity=5,
status="backlog" // Tasks start in backlog
)
// 2. Now use Status Progression Skill to transition status
"Use Status Progression Skill to move feature to in-development"
```
**Prevention:** Always create tasks before moving features into development. Use Feature Architect or Planning Specialist for task breakdown.
---
### Error: "Cannot transition to TESTING: X task(s) not completed"
**Cause:** Attempting to move feature to `testing` while tasks are still pending or in-progress.
**Solution:**
```javascript
// 1. Check which tasks are incomplete
overview = query_container(operation="overview", containerType="feature", id="...")
// Review: overview.taskCounts.byStatus
// 2. Complete remaining tasks OR cancel unnecessary tasks
// Option A: Complete tasks (use Status Progression Skill)
"Use Status Progression Skill to mark task as completed"
// Option B: Cancel tasks that are no longer needed (use Status Progression Skill)
"Use Status Progression Skill to mark task as cancelled"
// 3. Retry feature status transition via Status Progression Skill
"Use Status Progression Skill to move feature to testing"
```
**Prevention:** Track task progress regularly. Use `query_container(operation="overview")` to monitor completion status before attempting status changes.
---
### Error: "Cannot transition to COMPLETED: X task(s) not completed"
**Cause:** Attempting to complete feature with pending/in-progress tasks.
**Solution:**
```javascript
// 1. Identify incomplete tasks
tasks = query_container(
operation="search",
containerType="task",
featureId="...",
status="pending,in-progress"
)
// 2. For each incomplete task, decide:
// Option A: Complete the task (if work is done, use Status Progression Skill)
"Use Status Progression Skill to mark task as completed"
// Option B: Cancel the task (if no longer needed, use Status Progression Skill)
"Use Status Progression Skill to mark task as cancelled"
// 3. Verify all tasks are resolved
overview = query_container(operation="overview", containerType="feature", id="...")
// Check: overview.taskCounts.byStatus.pending === 0
// Check: overview.taskCounts.byStatus['in-progress'] === 0
// 4. Retry feature completion via Status Progression Skill
"Use Status Progression Skill to mark feature as completed"
```
**Prevention:** Regularly review task status. Cancel tasks early if scope changes. Don't leave tasks in limbo.
---
### Error: "Task summary is required before completion"
**Cause:** Attempting to mark task as complete without setting the summary field.
**Solution:**
```javascript
// 1. Add summary to task (300-500 characters recommended)
manage_container(
operation="update",
containerType="task",
id="task-uuid",
summary="Implemented user authentication with JWT tokens. Added login/logout endpoints, password hashing with bcrypt, and refresh token rotation. All tests passing."
)
// 2. Now use Status Progression Skill to mark task complete
"Use Status Progression Skill to mark task as completed"
```
**Prevention:** Add summaries as you complete work. Summaries help future reference and provide context for downstream tasks.
---
### Error: "Task summary must be 300-500 characters (current: X)"
**Cause:** Summary too short (< 300 chars) or too long (> 500 chars).
**Solution:**
```javascript
// If too short - add more detail
summary = "User authentication implementation. Added JWT tokens." // 60 chars - TOO SHORT
// Expand with:
summary = "Implemented comprehensive user authentication system with JWT token generation and validation. Added login/logout endpoints with proper session management. Integrated bcrypt for password hashing with configurable salt rounds. Implemented refresh token rotation for enhanced security. All endpoints include proper error handling and input validation. Test coverage at 94%." // 380 chars - GOOD
// If too long - condense
summary = "Very long detailed description..." // 612 chars - TOO LONG
// Condense to key points:
summary = "Implemented user auth with JWT tokens (login/logout/refresh). Added bcrypt password hashing, session management, and comprehensive error handling. Includes validation, proper security practices, and 94% test coverage. All API endpoints documented in Swagger." // 270 chars - needs 30 more
manage_container(operation="update", containerType="task", id="...", summary=summary)
```
**Prevention:** Aim for 350-450 characters. Include what was done, key technical decisions, and test coverage.
---
## Bypassing Validation (Development/Testing Only)
**When validation is too strict during development:**
```yaml
# Edit .taskorchestrator/config.yaml
status_validation:
validate_prerequisites: false # Temporarily disable validation
```
**Warning:** Only disable validation for:
- Development/testing workflows
- Prototyping and experimentation
- Fixing broken states
**Re-enable validation for production workflows:**
```yaml
status_validation:
validate_prerequisites: true # Default production setting
```
---
## Debugging Validation Issues
### Check Current Validation Settings
```javascript
// Validation is config-driven - check .taskorchestrator/config.yaml
// Default: validate_prerequisites: true
```
### View Detailed Error Messages
```javascript
result = manage_container(operation="setStatus", ...)
if (!result.success) {
console.log("Error:", result.error)
// Error message includes:
// - What validation failed
// - How many tasks are incomplete
// - Names of incomplete tasks
}
```
### Common Validation Failure Patterns
1. **Task count = 0** → Create tasks before starting development
2. **Incomplete tasks** → Complete or cancel tasks before progressing
3. **Missing summary** → Add task summary before marking complete
4. **Summary wrong length** → Adjust to 300-500 characters
5. **Status transition invalid** → Check status progression flow
---
## Quality Gate Failures
### Tests Failing
```
Error: Cannot complete feature - testing gate failed
- 3 test failures in authentication module
```
**Solution:**
1. Review test failures
2. Fix code or update tests
3. Re-run tests
4. Retry feature completion
**Or delegate:**
```
"Launch Test Engineer subagent to investigate and fix test failures"
```
### Coverage Below Threshold
```
Warning: Code coverage below threshold
- Current: 68%
- Required: 80%
- Missing: 12% coverage
```
**Solution:**
1. Identify uncovered code
2. Write additional tests
3. Re-run coverage report
4. Retry feature completion
---
## Common Anti-Patterns
### ❌ Skipping Template Discovery
```javascript
// DON'T: Create without checking templates
manage_container(operation="create", containerType="feature", ...)
```
```javascript
// DO: Always discover templates first
templates = query_templates(operation="list", targetEntityType="FEATURE", isEnabled=true)
manage_container(operation="create", containerType="feature", templateIds=[...])
```
### ❌ Directly Changing Status
```javascript
// DON'T: Direct status change
manage_container(operation="setStatus", containerType="feature", status="testing")
```
```javascript
// DO: Use Status Progression Skill
"Use Status Progression Skill to progress feature to next status"
```
### ❌ Not Checking Task Counts
```javascript
// DON'T: Assume all tasks complete
"Use Status Progression Skill to mark feature complete"
```
```javascript
// DO: Check task counts first
overview = query_container(operation="overview", containerType="feature", id="...")
if (overview.taskCounts.byStatus.pending == 0 &&
overview.taskCounts.byStatus["in-progress"] == 0) {
"Use Status Progression Skill to mark feature complete"
}
```
### ❌ Using includeSections for Status Checks
```javascript
// DON'T: Expensive query for simple check
feature = query_container(operation="get", containerType="feature",
id="...", includeSections=true) // 18k tokens!
```
```javascript
// DO: Use overview operation
feature = query_container(operation="overview", containerType="feature",
id="...") // 1.2k tokens (93% savings)
```