@haoyiyin/workflow 0.2.0 → 0.2.3

package/src/router/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Router system types - Controls all user input routing
+ */
+
+import type { SubagentConfig, SubagentResult } from '../agents/types.js'
+
+/** Classification of user intent */
+export type IntentType =
+  | 'plan'           // Needs planning (complex, multi-step)
+  | 'quick-task'     // Small scoped task (trivial edit, small fix)
+  | 'execute'        // Execute approved plan
+  | 'review'         // Review code/diff
+  | 'debug'          // Systematic debugging
+  | 'tdd'            // Test-driven development
+  | 'general'        // Catch-all for other queries
+
+export interface IntentClassification {
+  type: IntentType
+  confidence: number  // 0-1
+  reasoning: string
+  suggestedAgent: string
+}
+
+export interface RouterConfig {
+  /** Default model for subagents */
+  defaultModel: string
+  /** Threshold for routing to quick-task vs to-plan */
+  planningThreshold: number
+  /** Max tokens before forcing subagent dispatch */
+  maxMainAgentTokens: number
+  /** Whether to auto-route based on keywords */
+  autoRoute: boolean
+}
+
+export interface RoutingDecision {
+  /** The subagent to dispatch */
+  subagent: SubagentConfig
+  /** Contract/prompt for the subagent */
+  contract: SubagentContract
+  /** Whether to wait for result or stream */
+  async: boolean
+}
+
+export interface SubagentContract {
+  /** What this subagent is allowed to do */
+  permissions: PermissionSet
+  /** Exact prompt to send */
+  prompt: string
+  /** Required output format */
+  outputSchema?: Record<string, unknown>
+  /** Files this subagent owns */
+  owns: string[]
+  /** Files this subagent may read */
+  reads: string[]
+}
+
+export interface PermissionSet {
+  readFiles: boolean
+  searchCode: boolean
+  runCommands: boolean
+  writeFiles: boolean
+  gitOperations: boolean
+}
+
+export interface RouterResult {
+  decision: RoutingDecision
+  /** Estimated token usage */
+  estimatedTokens: number
+  /** Fallback if subagent fails */
+  fallbackStrategy: 'retry' | 'escalate' | 'abort'
+}
+
+export interface ExecutionResult {
+  success: boolean
+  result?: SubagentResult
+  error?: string
+  /** Tokens used by entire routing chain */
+  totalTokens: number
+  /** Time taken */
+  duration: number
+}
+
+/** Input to the router: raw request + classification context. */
+export interface RouterInput {
+  /** Raw user request text */
+  request: string
+  /** Whether a plan file already exists */
+  planFileExists: boolean
+  /** Whether mid-execution of a plan */
+  isExecutingPlan: boolean
+  /** Whether there are uncommitted changes */
+  hasUncommittedChanges: boolean
+  /** Current git branch */
+  currentBranch?: string
+  /** Files mentioned by the user */
+  mentionedFiles: string[]
+}
+
+/** Output from the router: classification + full routing decision. */
+export interface RouterOutput {
+  classification: IntentClassification
+  routing: RoutingDecision
+  confidence: number
+  matchedRule: string
+}
+
+/** Main Agent is NEVER allowed to do these */
+export const MAIN_AGENT_PROHIBITED = {
+  readSourceFiles: true,      // ❌ Cannot read .ts, .js, .py, etc.
+  searchCodebase: true,       // ❌ Cannot search/grep
+  writeFiles: true,           // ❌ Cannot write any files
+  runBuildCommands: true,     // ❌ Cannot npm build, tsc, etc.
+  runTests: true,             // ❌ Cannot run tests
+  editLargeFiles: true,       // ❌ Cannot edit >50 lines
+  longRunningTasks: true,     // ❌ Cannot run >30s tasks
+}
+
+/** Keywords that trigger specific routes */
+export const ROUTE_KEYWORDS: Record<IntentType, string[]> = {
+  plan: ['plan', 'implement', 'add feature', 'refactor', 'migrate', 'create'],
+  'quick-task': ['fix typo', 'rename', 'small change', 'quick', 'trivial'],
+  execute: ['execute', 'run plan', 'do plan', 'implement plan'],
+  review: ['review', 'check code', 'audit', 'review diff', 'cr'],
+  debug: ['debug', 'fix bug', 'investigate', 'root cause', 'flaky'],
+  tdd: ['tdd', 'test first', 'red green', 'write test'],
+  general: ['what', 'how', 'explain', 'tell me', 'search', 'find'],
+}

package/src/skills/agents-md/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: agents-md
+description: Create or update agent instruction files (CLAUDE.md, AGENTS.md, CONTEXT.md) from repo evidence.
+requires: []
+---
+
+## ⛔ MAIN AGENT CONSTRAINT
+
+You are a THIN DISPATCHER. Your ONLY job is to dispatch subagents.
+You MUST NOT: read source files, search code, write/edit files, run tests, run git commands.
+You MAY only: read plan/state files, dispatch subagents via Agent tool, relay results.
+For EVERY user request (including this skill), dispatch a subagent. Never execute yourself.
+
+---
+
+## Use/Exclude Matrix
+
+| Use When | Exclude When |
+|---|---|
+| Initializing or updating project agent instructions | File already exists and is comprehensive |
+| New project onboarding | Project has no package.json or README |
+| Adding CLAUDE.md to a repo | File was just created and needs no update |
+| Updating after major tech stack change | Minor wording/polish changes |
+
+## Workflow
+
+1. **Collect Evidence** — Dispatch explorer subagent to read package.json, README, and any existing instruction file.
+2. **Write Instructions** — Dispatch implementer subagent to create/update the target file with Overview, Tech Stack, Commands, and Conventions sections.
+
+## Output Spec
+
+| Field | Type | Description |
+|---|---|---|
+| `filePath` | string | Name of the created/updated file (CLAUDE.md, AGENTS.md, or CONTEXT.md) |
+| `mode` | enum | `created` or `updated` |
+| `evidence` | string[] | Source files used as evidence |
+| `summary` | string | Human-readable result |
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Explorer fails to read sources | Write instructions based on available evidence only |
+| Implementer fails to write file | Error propagates to caller |
+| Target file type invalid | Zod schema rejects at input validation |

package/src/skills/agents-md/index.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod'
+import { Skill } from '../skill.js'
+import type { SkillContext } from '../types.js'
+import { createDispatcher } from '../../agents/dispatcher.js'
+import { createMainAgentGuard } from '../../guard/main-agent.js'
+
+const P = { readFiles: true, searchCode: false, runCommands: false, writeFiles: false, gitOperations: false }
+const PRW = { readFiles: true, searchCode: false, runCommands: false, writeFiles: true, gitOperations: false }
+
+const AgentsMdInputSchema = z.object({ type: z.enum(['CLAUDE','AGENTS','CONTEXT']).default('CLAUDE'), update: z.boolean().default(false), model: z.string().optional() })
+export class AgentsMdSkill extends Skill<any, any> {
+  constructor() { super({ name: 'agents-md', description: 'Create/update agent instructions', requires: [], inputSchema: AgentsMdInputSchema as any }) }
+  async execute(input: any, context: SkillContext): Promise<any> {
+    const { config, logger } = context
+    const dispatcher = createDispatcher(logger)
+    const guard = createMainAgentGuard({}, logger)
+    const filename = `${input.type}.md`
+    guard.activateEmbargo()
+    try {
+      const explore = await dispatcher.dispatch(
+        { role: 'explorer', model: input.model || config.defaultModel },
+        { permissions: P, prompt: `Collect repo evidence: package.json, README, configs.`, owns: [], reads: ['package.json','README.md',filename] },
+      )
+      await dispatcher.dispatch(
+        { role: 'implementer', model: input.model || 'sonnet' },
+        { permissions: PRW, prompt: `${input.update?'Update':'Create'} ${filename}. Evidence: ${explore.output.slice(0,3000)}. Include: Overview, Tech Stack, Commands, Conventions.`, owns: [filename], reads: [] },
+      )
+      return { filePath: filename, mode: input.update?'updated':'created', evidence: ['package.json'], rules: ['Overview'], assumptions: [], summary: `${filename} done` }
+    } finally { guard.deactivateEmbargo() }
+  }
+}
+export const agentsMdSkill = new AgentsMdSkill()
+export default agentsMdSkill

package/src/skills/execute-plan/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: execute-plan
+description: Execute approved plans via 9-step isolated subagent dispatch with review, verification, auto-commit, and auto-merge.
+requires: [to-plan, tdd, review-diff, systematic-debugging]
+---
+
+## ⛔ MAIN AGENT CONSTRAINT
+
+You are a THIN DISPATCHER. Your ONLY job is to dispatch subagents.
+You MUST NOT: read source files, search code, write/edit files, run tests, run git commands.
+You MAY only: read plan/state files, dispatch subagents via Agent tool, relay results.
+For EVERY user request (including this skill), dispatch a subagent. Never execute yourself.
+
+---
+
+## Use/Exclude Matrix
+
+| Use When | Exclude When |
+|---|---|
+| Approved plan ready for execution | Plan not yet created or approved |
+| Multi-task implementation with dependencies | Single trivial change (use quick-task) |
+| Need review gate per task | No review requirement |
+| Want auto-commit/merge on success | Manual commit workflow preferred |
+
+## Workflow
+
+1. **Parse Plan** — Read plan file, extract tasks with owns/reads/dependencies metadata.
+2. **Create State** — Build execution state tracking completed, failed, and in-progress tasks.
+3. **Execute Tasks** — Dispatch implementer subagents per task in dependency order, each in isolated worktree.
+4. **Review Each** — Dispatch reviewer subagent per completed task; BLOCKED tasks move to failed.
+5. **Integrate** — Collect approved changes; detect and report file-level conflicts.
+6. **Verify** — Dispatch verifier subagent to run full test suite and goal-backward check.
+7. **Auto-Commit** — If `config.autoMerge` and all tasks pass, commit changes via subagent.
+8. **Auto-Merge** — Detect base branch, merge feature branch back via subagent.
+9. **Cleanup** — If `config.autoCleanup`, archive plan and delete feature branch.
+
+## Output Spec
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | enum | `success`, `failure`, `partial` |
+| `tasksCompleted` | number | Count of successfully completed tasks |
+| `tasksFailed` | number | Count of failed/blocked tasks |
+| `tasksTotal` | number | Total tasks in the plan |
+| `summary` | string | Human-readable execution summary |
+| `actions` | array | List of actions taken (commit, merge, archive) |
+| `commitSha` | string? | Commit SHA if auto-committed |
+| `baseBranch` | string? | Detected base branch for merge |
+| `tokensUsed` | number | Total tokens consumed |
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Plan file not found | Throw with path; caller must verify path |
+| Plan contains no parseable tasks | Throw; suggest re-running to-plan |
+| Implementer subagent fails | Record in failed map; continue remaining tasks |
+| Reviewer returns BLOCKED | Move task to failed with reviewer feedback |
+| Verifier reports FAIL | Return partial status with failure details |
+| Merge conflict during auto-merge | Report conflict; do NOT force-resolve |