@haoyiyin/workflow 0.2.11 → 0.3.0

package/src/skills/index.ts

@@ -11,3 +11,4 @@ export { reviewDiffSkill, ReviewDiffSkill } from './review-diff/index.js'
 export { tddSkill, TDDSkill } from './tdd/index.js'
 export { systematicDebuggingSkill, SystematicDebuggingSkill } from './systematic-debugging/index.js'
 export { agentsMdSkill, AgentsMdSkill } from './agents-md/index.js'
+export { routerSkill, RouterSkill } from './router/index.js'

package/src/skills/quick-task/index.ts

@@ -134,7 +134,7 @@ export class QuickTaskSkill extends Skill<QuickTaskInput, QuickTaskOutput> {
     context: SkillContext,
   ): Promise<QuickTaskOutput> {
     const { config, logger } = context
-    const dispatcher = createDispatcher(logger)
+    const dispatcher = createDispatcher({ logger })
     const guard = createMainAgentGuard({}, logger)
     let totalTokens = 0
 

package/src/skills/review-diff/index.ts

@@ -213,7 +213,7 @@ export class ReviewDiffSkill extends Skill<ReviewDiffInput, ReviewDiffOutput> {
     context: SkillContext,
   ): Promise<ReviewDiffOutput> {
     const { config, logger } = context
-    const dispatcher = createDispatcher(logger)
+    const dispatcher = createDispatcher({ logger })
     const guard = createMainAgentGuard({}, logger)
 
     guard.activateEmbargo()

package/src/skills/router/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: router
+priority: 999
+description: MANDATORY ENTRY POINT for ALL user requests. Implements 5-layer GSD routing (State → Lifecycle → Intent → Semantic → Confidence). Thin dispatcher - delegates all routing logic to subagents.
+requires: []
+---
+
+## ⛔ MAIN AGENT CONSTRAINT (CRITICAL)
+
+You are a THIN DISPATCHER. Your ONLY job is to dispatch subagents.
+
+**YOU MUST NOT:**
+- Read source files (except STATE.md and PLAN.md)
+- Search code or explore the codebase
+- Write or edit any files
+- Run tests or commands
+- Execute git operations
+- Make routing decisions yourself
+- Perform ANY work beyond dispatching
+
+**YOU MAY ONLY:**
+- Read STATE.md and PLAN.md files
+- Dispatch subagents via the Agent tool
+- Relay results between subagents
+- Return the final routing decision from subagent output
+
+**FOR EVERY USER REQUEST:** Dispatch a subagent. Never execute routing logic yourself.
+
+---
+
+## Purpose
+
+The router skill is the **mandatory entry point** for all user requests in the GSD (Get Stuff Done) architecture. It implements a 5-layer filtering system to determine the appropriate target skill for any given request.
+
+This skill enforces the thin dispatcher pattern: the main agent reads state/plan files and immediately dispatches to a routing subagent that performs the actual 5-layer analysis.
+
+---
+
+## 5-Layer GSD Routing Architecture
+
+The routing subagent applies these layers in sequence:
+
+### Layer 1: State Check
+- Read `.pi/state/STATE.md` for current workflow state
+- Check if there's an active plan in progress
+- Determine phase: `idle`, `planning`, `executing`, `verifying`, `blocked`
+- If blocked, route to `systematic-debugging`
+- If executing with active tasks, route to `execute-plan` continuation
+
+### Layer 2: Lifecycle Gate
+- Check PLAN.md existence and status
+- If no plan exists and request is complex, route to `to-plan`
+- If plan exists but not approved, route to plan review
+- If plan approved and ready to execute, proceed to execution routing
+
+### Layer 3: Intent Classification
+- Parse user request for intent signals:
+  - **Plan signals**: "plan", "design", "break down", "how should I"
+  - **Quick signals**: "fix typo", "rename", "quick", "small"
+  - **Review signals**: "review", "check", "audit", "CR"
+  - **Debug signals**: "bug", "error", "failing", "investigate"
+  - **TDD signals**: "test", "TDD", "implement with tests"
+  - **Execute signals**: "do it", "implement", "execute", "start"
+
+### Layer 4: Semantic Analysis
+- Analyze request complexity and scope:
+  - **Trivial**: <30 chars, single file, typo/rename/format
+  - **Small**: 1-5 files, well-understood change
+  - **Medium**: 5-10 files, some exploration needed
+  - **Large**: 10+ files or architectural changes
+- Check for risk indicators: "refactor core", "migration", "upgrade"
+
+### Layer 5: Confidence Score
+- Calculate routing confidence (0.0 - 1.0)
+- High confidence (>0.8): Route directly to target skill
+- Medium confidence (0.5-0.8): Dispatch clarifier subagent
+- Low confidence (<0.5): Route to `to-plan` for exploration
+
+---
+
+## Target Skills
+
+The router dispatches to one of these target skills:
+
+| Skill | When Routed |
+|-------|-------------|
+| `to-plan` | Complex feature, unknown scope, architectural change, low confidence |
+| `execute-plan` | Active plan ready to execute, continuation of execution |
+| `quick-task` | Trivial change, typo/rename, <5 files, high confidence |
+| `review-diff` | Code review request, PR audit, change validation |
+| `systematic-debugging` | Bug investigation, test failures, blocked execution |
+| `tdd` | Explicit TDD request, test-first implementation |
+
+---
+
+## Workflow
+
+```
+User Request
+    ↓
+[Main Agent] Read STATE.md + PLAN.md
+    ↓
+[Main Agent] Dispatch routing subagent with 5-layer prompt
+    ↓
+[Routing Subagent] Apply 5-layer filtering
+    ↓
+[Routing Subagent] Return { targetSkill, confidence, reasoning }
+    ↓
+[Main Agent] Return routing decision to caller
+```
+
+---
+
+## Dispatch Contract
+
+### Input to Routing Subagent
+
+```typescript
+{
+  userRequest: string;        // The original user request
+  stateContent: string;      // Contents of STATE.md (if exists)
+  planContent: string;       // Contents of PLAN.md (if exists)
+  conversationContext: string; // Recent conversation history
+}
+```
+
+### Output from Routing Subagent
+
+```typescript
+{
+  targetSkill: string;       // One of: to-plan, execute-plan, quick-task, 
+                              //         review-diff, systematic-debugging, tdd
+  confidence: number;        // 0.0 - 1.0
+  reasoning: string;         // Explanation of routing decision
+  layerDecisions: {
+    state: string;           // State check result
+    lifecycle: string;       // Lifecycle gate result
+    intent: string;          // Intent classification
+    semantic: string;        // Semantic analysis
+    confidence: string;      // Confidence calculation
+  };
+  suggestedInput?: object;   // Pre-processed input for target skill
+}
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| STATE.md read fails | Proceed with empty state, assume `idle` phase |
+| PLAN.md read fails | Proceed with no plan, assume planning needed |
+| Routing subagent fails | Retry once; on second failure, default to `to-plan` |
+| Invalid target skill returned | Validate against allowed list, fallback to `to-plan` |
+| Confidence < 0.3 | Route to `to-plan` for exploration regardless of other signals |
+
+---
+
+## Routing Decision Matrix
+
+| Request Pattern | State | Lifecycle | Intent | Semantic | Target |
+|-----------------|-------|-----------|--------|----------|--------|
+| "Fix typo in README" | idle | no plan | quick | trivial | `quick-task` |
+| "Plan feature X" | idle | no plan | plan | unknown | `to-plan` |
+| "Implement the plan" | idle | plan approved | execute | - | `execute-plan` |
+| "Review my changes" | any | any | review | - | `review-diff` |
+| "Debug failing test" | blocked | plan executing | debug | - | `systematic-debugging` |
+| "TDD this feature" | idle | no plan | tdd | small | `tdd` |
+| "Refactor core module" | idle | no plan | refactor | large | `to-plan` |
+| "Continue execution" | executing | plan active | execute | - | `execute-plan` |
+
+---
+
+## Constraints Summary
+
+1. **Never execute routing logic in main agent** - Always dispatch to subagent
+2. **Only read STATE.md and PLAN.md** - No codebase exploration
+3. **Return subagent output directly** - No transformation or filtering
+4. **Single dispatch per request** - One routing subagent per user request
+5. **Fail safe** - When uncertain, route to `to-plan` for exploration