@haoyiyin/workflow 0.2.2 → 0.2.3

package/src/skills/tdd/index.ts

@@ -0,0 +1,409 @@
+/**
+ * TDD Skill - Enforces RED/GREEN/REFACTOR cycle via subagent dispatch
+ *
+ * Use case: Implement feature with test-first approach
+ * Pattern: RED (write failing test) → GREEN (minimal implementation) →
+ *          REFACTOR (improve while green) → VERIFY (full suite)
+ *
+ * Spawns implementer subagent with TDD contract at each phase.
+ * Enforces the cycle: no implementation before a failing test exists.
+ */
+
+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'
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const TDDInputSchema = z.object({
+  behavior: z.string().min(1, 'Behavior to implement is required'),
+  testFile: z.string().optional(),
+  targetFile: z.string().min(1, 'Target implementation file is required'),
+  testLevel: z
+    .enum(['unit', 'integration', 'e2e', 'contract'])
+    .default('unit'),
+  model: z.string().optional(),
+})
+
+const PhaseResultSchema = z.object({
+  phase: z.enum(['red', 'green', 'refactor']),
+  status: z.enum(['pass', 'fail', 'skipped']),
+  command: z.string(),
+  evidence: z.string(),
+})
+
+const TDDOutputSchema = z.object({
+  status: z.enum(['success', 'failure', 'invalid-red']),
+  phases: z.array(PhaseResultSchema),
+  broaderVerification: z.object({
+    command: z.string(),
+    result: z.enum(['PASS', 'FAIL', 'NOT_RUN']),
+  }),
+  filesModified: z.array(z.string()),
+  summary: z.string(),
+  tokensUsed: z.number(),
+})
+
+type TDDInput = z.infer<typeof TDDInputSchema>
+type TDDOutput = z.infer<typeof TDDOutputSchema>
+type PhaseResult = z.infer<typeof PhaseResultSchema>
+
+// ---------------------------------------------------------------------------
+// Prompt builders (pure functions)
+// ---------------------------------------------------------------------------
+
+function buildRedPrompt(
+  behavior: string,
+  targetFile: string,
+  testFile: string | undefined,
+  testLevel: string,
+): string {
+  return [
+    `## TDD Phase: RED - Write Failing Test`,
+    '',
+    `**Behavior**: ${behavior}`,
+    `**Test Level**: ${testLevel}`,
+    `**Target File**: ${targetFile}`,
+    testFile ? `**Test File**: ${testFile}` : '',
+    '',
+    '## Instructions',
+    '',
+    '1. Read the target file to understand current state',
+    '2. Write a minimal, focused test that MUST fail',
+    '3. The test should describe the expected behavior precisely',
+    '4. Run the test and confirm it FAILS for the RIGHT reason',
+    '',
+    '## Validation',
+    '',
+    '- Test must fail because the behavior is NOT yet implemented',
+    '- If the test PASSES immediately, the behavior may already exist',
+    '- If test fails due to setup/syntax error, fix the test first',
+    '',
+    '## Anti-Goals',
+    '',
+    '- Do NOT implement the feature',
+    '- Do NOT write more than one test',
+    '- Do NOT modify the target file',
+    '',
+    '## Output',
+    '',
+    'Report: test file path, test command used, test output (must show FAIL).',
+    'If test unexpectedly passes, output: INVALID_RED',
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+function buildGreenPrompt(
+  behavior: string,
+  targetFile: string,
+  testFile: string | undefined,
+  redEvidence: string,
+): string {
+  return [
+    `## TDD Phase: GREEN - Make Test Pass`,
+    '',
+    `**Behavior**: ${behavior}`,
+    `**Target File**: ${targetFile}`,
+    testFile ? `**Test File**: ${testFile}` : '',
+    '',
+    '## RED Phase Evidence',
+    redEvidence.slice(0, 500),
+    '',
+    '## Instructions',
+    '',
+    '1. Read the failing test to understand what is expected',
+    '2. Write the MINIMAL code to make the test pass',
+    '3. Code can be hacky, hardcoded, or ugly — refactor comes next',
+    '4. Run the test and confirm it PASSES',
+    '',
+    '## Anti-Goals',
+    '',
+    '- Do NOT refactor or prettify the code',
+    '- Do NOT add features beyond what the test checks',
+    '- Do NOT change the test',
+    '- Do NOT write additional tests',
+    '',
+    '## Output',
+    '',
+    'Report: implementation summary, test command, test output (must show PASS).',
+  ].join('\n')
+}
+
+function buildRefactorPrompt(
+  targetFile: string,
+): string {
+  return [
+    `## TDD Phase: REFACTOR - Clean Up`,
+    '',
+    `**Target File**: ${targetFile}`,
+    '',
+    '## Instructions',
+    '',
+    '1. Read the current implementation',
+    '2. Improve code quality: remove duplication, better naming, extract helpers',
+    '3. Run tests after EACH change to stay green',
+    '4. Run the full test suite at the end',
+    '',
+    '## Allowed',
+    '',
+    '- Rename variables/functions for clarity',
+    '- Extract repeated logic into helper functions',
+    '- Add type annotations',
+    '- Reorganize code for readability',
+    '',
+    '## Anti-Goals',
+    '',
+    '- Do NOT change behavior',
+    '- Do NOT add new features',
+    '- Do NOT modify test expectations',
+    '- Do NOT break any test',
+    '',
+    '## Output',
+    '',
+    'Report: what was refactored, test command, test output (must show ALL PASS).',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Skill class
+// ---------------------------------------------------------------------------
+
+export class TDDSkill extends Skill<TDDInput, TDDOutput> {
+  constructor() {
+    super({
+      name: 'tdd',
+      description:
+        'Enforce RED/GREEN/REFACTOR TDD cycle with isolated implementer subagents',
+      requires: [],
+      inputSchema: TDDInputSchema as z.ZodType<TDDInput>,
+      outputSchema: TDDOutputSchema,
+    })
+  }
+
+  async execute(
+    input: TDDInput,
+    context: SkillContext,
+  ): Promise<TDDOutput> {
+    const { config, logger } = context
+    const dispatcher = createDispatcher(logger)
+    const guard = createMainAgentGuard({}, logger)
+
+    const phases: PhaseResult[] = []
+    const filesModified: string[] = []
+    let totalTokens = 0
+
+    guard.activateEmbargo()
+
+    try {
+      // ---- Phase 1: RED - Write failing test ----
+      logger.info(`[tdd] RED phase: writing failing test for "${input.behavior}"`)
+      const redResult = await dispatcher.dispatch(
+        {
+          role: 'implementer',
+          model: input.model || config.defaultModel,
+          isolation: 'worktree',
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: true,
+            gitOperations: false,
+          },
+          prompt: buildRedPrompt(
+            input.behavior,
+            input.targetFile,
+            input.testFile,
+            input.testLevel,
+          ),
+          owns: input.testFile ? [input.testFile] : [],
+          reads: [input.targetFile],
+        },
+      )
+
+      totalTokens += redResult.tokensUsed
+
+      if (redResult.output.includes('INVALID_RED')) {
+        return {
+          status: 'invalid-red',
+          phases,
+          broaderVerification: { command: '', result: 'NOT_RUN' },
+          filesModified,
+          summary: 'RED phase invalid: behavior may already exist or test is misconfigured',
+          tokensUsed: totalTokens,
+        }
+      }
+
+      if (redResult.status !== 'success') {
+        phases.push({
+          phase: 'red',
+          status: 'fail',
+          command: '',
+          evidence: redResult.errors.join(', '),
+        })
+        return {
+          status: 'failure',
+          phases,
+          broaderVerification: { command: '', result: 'NOT_RUN' },
+          filesModified,
+          summary: `RED phase failed: ${redResult.errors.join(', ')}`,
+          tokensUsed: totalTokens,
+        }
+      }
+
+      phases.push({
+        phase: 'red',
+        status: 'pass',
+        command: '(test runner)',
+        evidence: redResult.output.slice(0, 300),
+      })
+      if (input.testFile) filesModified.push(input.testFile)
+
+      // ---- Phase 2: GREEN - Make test pass ----
+      logger.info('[tdd] GREEN phase: implementing minimal code')
+      const greenResult = await dispatcher.dispatch(
+        {
+          role: 'implementer',
+          model: input.model || config.defaultModel,
+          isolation: 'worktree',
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: true,
+            gitOperations: false,
+          },
+          prompt: buildGreenPrompt(
+            input.behavior,
+            input.targetFile,
+            input.testFile,
+            redResult.output,
+          ),
+          owns: [input.targetFile],
+          reads: [],
+        },
+      )
+
+      totalTokens += greenResult.tokensUsed
+
+      if (greenResult.status !== 'success') {
+        phases.push({
+          phase: 'green',
+          status: 'fail',
+          command: '',
+          evidence: greenResult.errors.join(', '),
+        })
+        return {
+          status: 'failure',
+          phases,
+          broaderVerification: { command: '', result: 'NOT_RUN' },
+          filesModified,
+          summary: `GREEN phase failed: ${greenResult.errors.join(', ')}`,
+          tokensUsed: totalTokens,
+        }
+      }
+
+      phases.push({
+        phase: 'green',
+        status: 'pass',
+        command: '(test runner)',
+        evidence: greenResult.output.slice(0, 300),
+      })
+      filesModified.push(input.targetFile)
+
+      // ---- Phase 3: REFACTOR - Clean up while staying green ----
+      logger.info('[tdd] REFACTOR phase: improving code quality')
+      const refactorResult = await dispatcher.dispatch(
+        {
+          role: 'implementer',
+          model: input.model || config.defaultModel,
+          isolation: 'worktree',
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: true,
+            gitOperations: false,
+          },
+          prompt: buildRefactorPrompt(input.targetFile),
+          owns: [input.targetFile],
+          reads: [],
+        },
+      )
+
+      totalTokens += refactorResult.tokensUsed
+
+      phases.push({
+        phase: 'refactor',
+        status: refactorResult.status === 'success' ? 'pass' : 'skipped',
+        command: '(test runner)',
+        evidence: refactorResult.output.slice(0, 300),
+      })
+
+      // ---- Phase 4: Broader verification ----
+      logger.info('[tdd] Running broader verification')
+      const verifyResult = await dispatcher.dispatch(
+        {
+          role: 'verifier',
+          model: input.model || config.defaultModel,
+        },
+        {
+          permissions: {
+            readFiles: false,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: [
+            'Run broader verification for the TDD implementation:',
+            '',
+            `Behavior: ${input.behavior}`,
+            `Target: ${input.targetFile}`,
+            '',
+            '1. Run the full test suite (not just the new test)',
+            '2. Check for regressions',
+            '3. Verify the behavior works end-to-end if applicable',
+            '',
+            'Return: command executed, exit code, summary of results.',
+          ].join('\n'),
+          owns: [],
+          reads: [],
+        },
+      )
+
+      totalTokens += verifyResult.tokensUsed
+
+      const redStatus = phases[0]?.status ?? 'fail'
+      const greenStatus = phases[1]?.status ?? 'fail'
+      const refactorStatus = phases[2]?.status ?? 'skipped'
+
+      return {
+        status: 'success',
+        phases,
+        broaderVerification: {
+          command: '(verification)',
+          result: verifyResult.status === 'success' ? 'PASS' : 'FAIL',
+        },
+        filesModified: [...new Set(filesModified)],
+        summary: `TDD complete: RED(${redStatus}) → GREEN(${greenStatus}) → REFACTOR(${refactorStatus}). Used ${totalTokens} tokens.`,
+        tokensUsed: totalTokens,
+      }
+    } finally {
+      guard.deactivateEmbargo()
+    }
+  }
+}
+
+export const tddSkill = new TDDSkill()
+export default tddSkill

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

@@ -0,0 +1,56 @@
+---
+name: to-plan
+description: Create implementation plans via 5-step subagent dispatch. Classify, explore codebase, synthesize findings, write plan, validate.
+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 |
+|---|---|
+| Feature implementation needs planning | Trivial typo/rename (use quick-task) |
+| Bugfix with unknown scope | Already have an approved plan |
+| Refactor spanning multiple files | Single-file change with known solution |
+| Architectural changes | Task fits in <30 chars description |
+
+## Workflow
+
+Each step below is delegated to a subagent. The main agent only dispatches.
+
+1. **Classify** — Dispatch classifier subagent to determine type, complexity, risk, and exploration areas.
+2. **Explore** — Dispatch 1-3 read-only explorer subagents in parallel, each focused on one exploration area.
+3. **Synthesize** — Dispatch planner subagent to cross-reference findings and produce unified task list with execution model.
+4. **Write Plan** — Dispatch writer subagent to write the plan to disk in markdown format.
+5. **Check Plan** — Dispatch reviewer subagent to validate plan completeness, dependency acyclicity, and task sizing.
+
+## Output Spec
+
+| Field | Type | Description |
+|---|---|---|
+| `planPath` | string | Absolute path to the written plan file |
+| `executionModel` | enum | `single-agent`, `ordered-non-parallel`, `fan-out-fan-in` |
+| `classification.type` | string | `feature`, `bugfix`, `migration`, `cleanup`, `refactor` |
+| `classification.complexity` | enum | `low`, `medium`, `high` |
+| `classification.risk` | enum | `low`, `medium`, `high` |
+| `planCheckerPassed` | boolean | Whether the plan validation passed |
+| `tasks` | TaskDef[] | Parsed tasks with id, title, description, owns, reads, dependencies, verification |
+| `tokensUsed` | number | Total tokens consumed across all subagents |
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Classification subagent fails | Retry once; fall back to defaults (type=feature, complexity=medium) |
+| All explorations fail | Synthesize with empty exploration data |
+| Write subagent fails | Write fallback plan directly from synthesis data |
+| Plan checker returns BLOCKED | Return result with `planCheckerPassed: false`; caller decides retry |
+| Invalid plan path directory | Auto-create directory via `mkdir -p` |