gh-jpicklyk-task-orchestrator-claude-plugins-task-orchestrator/skills/feature-orchestration/SKILL.md

skill, description

skill	description
feature-orchestration	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:

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

// 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

// 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

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 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:

   feature = query_container(operation="get", containerType="feature", id=featureId)
   

2. If status is "planning" or "draft" and tasks exist:

   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:

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

5. Feature Completion

Tool Orchestration Pattern:

// 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

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:

// 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 for complete walkthroughs
• Error Handling: See troubleshooting.md for validation errors
• Configuration: See config-reference.md for flow customization