owflow 0.1.5 → 0.1.6

package/dist/skills/quick-bugfix/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: true
 
 # Quick Bug Fix
 
-Lightweight TDD-driven bug fix workflow with planning mode. Analyze the bug, present a fix plan for approval, then reproduce with a failing test, fix, and verify. No orchestrator state, no task directory, no subagents.
+Lightweight TDD-driven bug fix workflow with planning mode. Analyze the bug, present a fix plan for approval, then reproduce with a failing test, fix, and verify. No orchestrator state, no subagents. Creates lightweight task directory for artifact anchoring.
 
 For complex bugs that grow beyond a quick fix, suggests escalating to the full development workflow (`/development`).
 
@@ -48,7 +48,20 @@ For complex bugs that grow beyond a quick fix, suggests escalating to the full d
   "Describe the bug — what's the expected behavior vs actual behavior?"
   ```
 
-### Step 2: Discover Standards
+### Step 2: Create Task Directory
+
+**Create a lightweight task directory for artifact anchoring.**
+
+1. Generate a task name from the bug description:
+   - Extract 3–5 key words, convert to lowercase kebab-case
+   - Prepend today's date: `YYYY-MM-DD-kebab-name`
+   - Examples: "Fix login timeout bug" → `2026-05-28-fix-login-timeout`, "Login form submits twice on slow connections" → `2026-05-28-login-double-submit`
+2. Create directory: `.owflow/tasks/quick-bugfix/YYYY-MM-DD-task-name/`
+3. Create `analysis/` subdirectory inside it
+4. Write `task.yml` with initial state using the template [src/templates/quick-bugfix-task.yml](../../templates/quick-bugfix-task.yml).
+5. **CRITICAL**: Use the `verify_template` tool immediately after creation to check YAML validity against `quick-bugfix-task.yml`.
+
+### Step 3: Discover Standards
 
 **CRITICAL: This step MUST complete before entering plan mode.**
 
@@ -62,6 +75,7 @@ For complex bugs that grow beyond a quick fix, suggests escalating to the full d
    - The area of the bug (e.g., API, frontend, database)
    - Keywords in the bug description
 3. **READ the applicable standard files** (see Standards Reading Enforcement below)
+4. **Update `task.yml`**: Add paths of standards read to `standards_applied` list
 
 **If not exists:**
 
@@ -86,7 +100,7 @@ For complex bugs that grow beyond a quick fix, suggests escalating to the full d
 - Bug in form validation → Read validation and frontend standards
 - Bug in database query → Read database and backend standards
 
-### Step 3: Analyze & Assess Complexity
+### Step 4: Analyze & Assess Complexity
 
 **Explore the codebase to understand the bug:**
 
@@ -109,20 +123,57 @@ Assess whether this bug exceeds quick-fix scope. If **2 or more** of these signa
 
 **If escalation triggered:**
 
+**Write `analysis/findings.md`** in the task directory with the analysis captured so far:
+
+```markdown
+# Bug Analysis
+
+## Root Cause
+[Root cause hypothesis with evidence — file paths, code references]
+
+## Affected Files
+- `path/to/file` — reason
+
+## Complexity Assessment
+- [ ] Changes span 5+ files across multiple modules
+- [ ] Requires database schema changes
+- [ ] Multiple valid fix approaches with architectural trade-offs
+- [ ] Security-sensitive code
+- [ ] Root cause unclear after initial analysis
+
+Signals detected: X of 5
+
+## Test Strategy
+[How the bug will be reproduced with a failing test]
+
+## Standards Referenced
+- [standard file]: [key guideline applied]
+```
+
 Use question:
 
 - Question: "This bug appears more complex than a quick fix — [describe why]. How would you like to proceed?"
 - Options:
   1. "Continue with quick fix" — proceed, accepting the complexity
-  2. "Switch to full development workflow" — stop here and suggest running `/development` with the bug description and analysis context
+  2. "Switch to full development workflow" — escalate (see below)
+
+**If user chooses to escalate:**
+
+1. Ensure `analysis/findings.md` is written (above)
+2. Update `task.yml`: set `status: escalated`, `escalation_reason: "[signals detected]"`, `updated: [now]`
+3. Tell the user: "Run `/development .owflow/tasks/quick-bugfix/YYYY-MM-DD-task-name` to continue with full workflow."
+4. Do NOT set `escalated_to` — the development orchestrator will set it
+5. `summary.md` is NOT written on escalation
+
+**If no escalation needed or user chooses to continue:**
 
-**If no escalation needed or user chooses to continue:** proceed to Step 4.
+Write `analysis/findings.md` (same template above — captures analysis for auditability), then proceed to Step 5.
 
-### Step 4: Enter Planning Mode
+### Step 5: Enter Planning Mode
 
 **Use the `Plan Agent` to present the fix plan for user approval.**
 
-Standards context from Step 2 and analysis from Step 3 MUST inform the plan.
+Standards context from Step 3 and analysis from Step 4 MUST inform the plan.
 
 **Plan file content:**
 
@@ -163,7 +214,7 @@ If no standards exist: "No AI SDLC standards found. Consider running `/flow-init
 
 If any section is missing, add it before asking for user approval.
 
-### Step 5: TDD Red Gate
+### Step 6: TDD Red Gate
 
 **Write a failing test that reproduces the bug.**
 
@@ -182,12 +233,12 @@ If any section is missing, add it before asking for user approval.
 - Investigate further — re-read the bug description, check if conditions are correct
 - Use question: "The reproduction test passes — the expected behavior already works under these conditions. Is the bug description accurate, or are there additional conditions?"
 
-### Step 6: Fix & Verify (TDD Green)
+### Step 7: Fix & Verify (TDD Green)
 
 **Implement the fix:**
 
-1. Apply the fix based on the approved plan from Step 4
-2. **Apply discovered standards** from Step 2
+1. Apply the fix based on the approved plan from Step 5
+2. **Apply discovered standards** from Step 3
 3. Run the failing test — it MUST now pass
 4. Run the full test file and related test files to check for regressions
 
@@ -203,16 +254,34 @@ If any section is missing, add it before asking for user approval.
 - Stop and present findings to the user
 - Suggest escalating to `/development` for a more thorough approach
 
-### Step 7: Summary
+### Step 8: Summary
+
+**Write `summary.md`** in the task directory:
+
+```markdown
+# Task Summary
 
-**Provide completion summary:**
+**Command**: quick-bugfix
+**Date**: YYYY-MM-DD
+**Status**: completed
+
+## What Was Done
+[Root cause and fix description]
+
+## Files Modified
+- `path/to/file`
+
+## Standards Applied
+- [standard]: [guideline]
+
+## Tests
+- [test file] — [result]
+
+## Commit Suggestion
+[conventional commit message]
+```
 
-- **Root cause**: What caused the bug
-- **Fix**: What was changed and why
-- **Files modified**: List of changed files
-- **Standards applied**: Which standards from INDEX.md were followed
-- **Tests**: Which tests were run and their results (including the TDD red→green transition)
-- **Commit suggestion**: Propose a commit message
+**Update `task.yml`**: set `status: completed`, `updated: [now]`.
 
 **Post-implementation: verify standards compliance using the checklist from the plan file.**
 
@@ -221,13 +290,14 @@ If any section is missing, add it before asking for user approval.
 ## What This Does
 
 1. **Parses** bug description from user input
-2. **Discovers** applicable standards from `.owflow/docs/INDEX.md`
-3. **Analyzes** codebase to find root cause and assess complexity
-4. **Escalates** to full development workflow if bug is too complex
-5. **Plans** the fix and presents for user approval via planning mode
-6. **Reproduces** bug with a failing test (TDD Red)
-7. **Fixes** the bug and verifies test passes (TDD Green)
-8. **Summarizes** root cause, fix, standards applied, and test results
+2. **Creates** lightweight task directory with `task.yml` for artifact anchoring
+3. **Discovers** applicable standards from `.owflow/docs/INDEX.md`
+4. **Analyzes** codebase to find root cause, writes `analysis/findings.md`, and assesses complexity
+5. **Escalates** to full development workflow if bug is too complex (updates `task.yml` status to `escalated`)
+6. **Plans** the fix and presents for user approval via planning mode
+7. **Reproduces** bug with a failing test (TDD Red)
+8. **Fixes** the bug and verifies test passes (TDD Green)
+9. **Summarizes** in `summary.md`, updates `task.yml` status to `completed`
 
 ## Graceful Fallback
 

package/dist/skills/research/SKILL.md

@@ -23,6 +23,7 @@ Systematic research workflow from question definition to evidence-based document
 1. **Create Task Items**: Use `TaskCreate` for all phases (see Phase Configuration), then set dependencies with `TaskUpdate addBlockedBy`
 2. **Create Task Directory**: `.owflow/tasks/research/YYYY-MM-DD-task-name/`
 3. **Initialize State**: Create `orchestrator-state.yml` with research context
+   - **CRITICAL**: Use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-research.yml`.
 
 **Output**:
 
@@ -369,40 +370,7 @@ question - "Design complete. Continue to output generation?"
 
 Research-specific fields in `orchestrator-state.yml`:
 
-```yaml
-research_context:
-  research_type: "technical" | "requirements" | "literature" | "mixed"
-  research_question: "[user's question]"
-  scope:
-    included: []
-    excluded: []
-    constraints: []
-  methodology: []
-  sources: []
-  confidence_level: "high" | "medium" | "low"
-  gathering_strategy:
-    categories: []       # e.g., ["codebase", "documentation", "external-apis"]
-    count: 4             # number of gatherer instances
-    source: "planner" | "default"  # where strategy came from
-  phase_summaries:
-    phase-1:
-      summary: "..."
-      steps_completed: []  # track which steps completed for resume
-    phase-3:
-      summary: "..."
-    phase-4:
-      summary: "..."
-      decision_areas: []        # list of {area, alternatives_count, chosen_approach}
-      deferred_ideas: []
-    phase-5:
-      summary: "..."
-      architecture_style: null
-      decisions_count: 0
-
-options:
-  brainstorming_enabled: null  # null=not yet decided, set by Phase 2 or --brainstorm/--no-brainstorm flag
-  design_enabled: null          # independent, set by Phase 2 or --design/--no-design flag
-```
+Refer to the template [src/templates/orchestrator-state-research.yml](../../templates/orchestrator-state-research.yml).
 
 ---
 
@@ -468,14 +436,7 @@ options:
 
 **Handoff**:
 
-```yaml
-research_outputs:
-  research_report: "[path to outputs/research-report.md]"
-  findings_directory: "[path to analysis/findings/]"
-  solution_exploration: "[path to outputs/solution-exploration.md]"
-  high_level_design: "[path to outputs/high-level-design.md]"
-  decision_log: "[path to outputs/decision-log.md]"
-```
+Refer to `research_outputs` in the template [src/templates/orchestrator-state-research.yml](../../templates/orchestrator-state-research.yml).
 
 ---
 

package/dist/templates/orchestrator-state-base.yml

@@ -0,0 +1,17 @@
+orchestrator:
+  started_phase: null
+  completed_phases: []
+  failed_phases: []
+  auto_fix_attempts: {}
+  options: {}
+  created: "YYYY-MM-DDTHH:MM:SSZ"
+  updated: "YYYY-MM-DDTHH:MM:SSZ"
+  task_path: null
+  task_ids: {}
+
+task:
+  title: null
+  description: null
+  status: pending
+  tags: []
+  priority: null

package/dist/templates/orchestrator-state-development.yml

@@ -0,0 +1,94 @@
+orchestrator:
+  started_phase: null
+  completed_phases: []
+  failed_phases: []
+  auto_fix_attempts:
+    phase-1: 0
+    phase-2: 0
+    phase-3: 0
+    phase-4: 0
+    phase-5: 0
+    phase-6: 0
+    phase-7: 0
+    phase-8: 0
+    phase-9: 0
+    phase-10: 0
+    phase-11: 0
+    phase-12: 0
+    phase-13: 0
+  options:
+    spec_audit_enabled: true
+    skip_test_suite: true
+    e2e_enabled: null
+    user_docs_enabled: null
+    code_review_enabled: true
+    pragmatic_review_enabled: true
+    reality_check_enabled: true
+    production_check_enabled: true
+  created: "YYYY-MM-DDTHH:MM:SSZ"
+  updated: "YYYY-MM-DDTHH:MM:SSZ"
+  task_path: null
+  task_ids: {}
+
+task:
+  title: null
+  description: null
+  status: pending
+  tags: []
+  priority: null
+
+task_context:
+  risk_level: null
+  clarifications_resolved: null
+  scope_expanded: null
+  architecture_decision: null
+  task_characteristics:
+    has_reproducible_defect: false
+    modifies_existing_code: false
+    creates_new_entities: false
+    involves_data_operations: false
+    ui_heavy: false
+  user_journey:
+    reachability: null
+    persona_impact: null
+    flow_integration: null
+    navigation_consistency: null
+    discoverability_before: null
+    discoverability_after: null
+  data_lifecycle:
+    three_layer_framework: null
+    backend_user_operability: null
+    orphaned_display_detected: null
+    orphaned_input_detected: null
+    layer_3_critical_checks: null
+    multi_touchpoint_discovery: null
+    crud_completeness: null
+    scope_expansion_recommended: null
+    safety_critical_awareness: null
+  gaps: []
+  research_reference:
+    path: null
+    research_question: null
+    research_type: null
+    confidence_level: null
+  quick_reference:
+    path: null
+    command: null
+    escalation_reason: null
+  phase_summaries:
+    research: { summary: null, key_findings: [], recommended_approach: null }
+    quick_analysis: { summary: null, affected_files: [], root_cause: null }
+    codebase_analysis: { key_files: [], primary_language: null, summary: null }
+    clarifications: []
+    gap_analysis: { integration_points: [], summary: null }
+    scope_clarifications: { scope_expanded: null, summary: null }
+    ui_mockups: { components_designed: [], summary: null }
+    specification: { summary: null }
+    architecture_decision: { decision: null, summary: null }
+
+verification_context:
+  last_status: null
+  issues_found: []
+  fixes_applied: []
+  decisions_made: []
+  reverify_count: 0

package/dist/templates/orchestrator-state-migration.yml

@@ -0,0 +1,55 @@
+orchestrator:
+  started_phase: null
+  completed_phases: []
+  failed_phases: []
+  auto_fix_attempts:
+    phase-1: 0
+    phase-2: 0
+    phase-3: 0
+    phase-4: 0
+    phase-5: 0
+    phase-6: 0
+    phase-7: 0
+    phase-8: 0
+  options:
+    docs_enabled: false
+  created: "YYYY-MM-DDTHH:MM:SSZ"
+  updated: "YYYY-MM-DDTHH:MM:SSZ"
+  task_path: null
+  task_ids: {}
+
+task:
+  title: null
+  description: null
+  status: pending
+  tags: []
+  priority: null
+
+migration_context:
+  migration_type: "code | data | architecture | general"
+  current_system:
+    description: null
+    technologies: []
+  target_system:
+    description: null
+    technologies: []
+  migration_strategy:
+    approach: "incremental | big-bang | dual-run | phased"
+    phases: []
+  risk_level: null
+  breaking_changes: []
+  rollback_plan_created: false
+  dual_run_configured: false
+
+external_research:
+  performed: false
+  category: null
+  breaking_changes: []
+  migration_guide_url: null
+
+verification_context:
+  last_status: null
+  issues_found: null
+  fixes_applied: []
+  decisions_made: []
+  reverify_count: 0

package/dist/templates/orchestrator-state-performance.yml

@@ -0,0 +1,53 @@
+orchestrator:
+  started_phase: null
+  completed_phases: []
+  failed_phases: []
+  auto_fix_attempts:
+    phase-1: 0
+    phase-2: 0
+    phase-3: 0
+    phase-4: 0
+    phase-5: 0
+    phase-6: 0
+    phase-7: 0
+    phase-8: 0
+    phase-9: 0
+  options:
+    spec_audit_enabled: null
+    skip_test_suite: true
+    code_review_enabled: true
+    pragmatic_review_enabled: true
+    reality_check_enabled: true
+    production_check_enabled: null
+  created: "YYYY-MM-DDTHH:MM:SSZ"
+  updated: "YYYY-MM-DDTHH:MM:SSZ"
+  task_path: null
+  task_ids: {}
+
+task:
+  title: null
+  description: null
+  status: pending
+  tags: []
+  priority: null
+
+performance_context:
+  bottlenecks_identified: null
+  user_data_available: false
+  bottleneck_priorities:
+    p0: 0
+    p1: 0
+    p2: 0
+    p3: 0
+  phase_summaries:
+    codebase_analysis: { key_files: [], summary: null }
+    bottleneck_analysis:
+      { bottlenecks: [], summary: null, user_data_incorporated: false }
+    specification: { summary: null }
+
+verification_context:
+  last_status: null
+  issues_found: null
+  fixes_applied: []
+  decisions_made: []
+  reverify_count: 0

package/dist/templates/orchestrator-state-research.yml

@@ -0,0 +1,61 @@
+orchestrator:
+  started_phase: null
+  completed_phases: []
+  failed_phases: []
+  auto_fix_attempts:
+    phase-1: 0
+    phase-2: 0
+    phase-3: 0
+    phase-4: 0
+    phase-5: 0
+    phase-6: 0
+  options:
+    brainstorming_enabled: null
+    design_enabled: null
+  created: "YYYY-MM-DDTHH:MM:SSZ"
+  updated: "YYYY-MM-DDTHH:MM:SSZ"
+  task_path: null
+  task_ids: {}
+
+task:
+  title: null
+  description: null
+  status: pending
+  tags: []
+  priority: null
+
+research_context:
+  research_type: "technical | requirements | literature | mixed"
+  research_question: null
+  scope:
+    included: []
+    excluded: []
+    constraints: []
+  methodology: []
+  sources: []
+  confidence_level: "high | medium | low"
+  gathering_strategy:
+    categories: []
+    count: 0
+    source: "planner | default"
+  phase_summaries:
+    phase-1:
+      summary: null
+      steps_completed: []
+    phase-3:
+      summary: null
+    phase-4:
+      summary: null
+      decision_areas: []
+      deferred_ideas: []
+    phase-5:
+      summary: null
+      architecture_style: null
+      decisions_count: 0
+
+research_outputs:
+  research_report: null
+  findings_directory: null
+  solution_exploration: null
+  high_level_design: null
+  decision_log: null

package/dist/templates/quick-bugfix-task.yml

@@ -0,0 +1,10 @@
+command: quick-bugfix
+title: "Short title from bug description"
+description: "Full bug description as provided by user"
+status: in_progress
+created: "YYYY-MM-DDTHH:MM:SSZ"
+updated: "YYYY-MM-DDTHH:MM:SSZ"
+task_path: .owflow/tasks/quick-bugfix/YYYY-MM-DD-task-name
+escalated_to: null
+escalation_reason: null
+standards_applied: []

package/dist/templates/quick-dev-task.yml

@@ -0,0 +1,10 @@
+command: quick-dev
+title: "Short title from task description"
+description: "Full task description as provided by user"
+status: in_progress
+created: "YYYY-MM-DDTHH:MM:SSZ"
+updated: "YYYY-MM-DDTHH:MM:SSZ"
+task_path: .owflow/tasks/quick-dev/YYYY-MM-DD-task-name
+escalated_to: null
+escalation_reason: null
+standards_applied: []

package/dist/templates/quick-plan-task.yml

@@ -0,0 +1,11 @@
+command: quick-plan
+title: "Short title from task description"
+description: "Full task description as provided by user"
+status: in_progress
+created: "YYYY-MM-DDTHH:MM:SSZ"
+updated: "YYYY-MM-DDTHH:MM:SSZ"
+task_path: .owflow/tasks/quick-plan/YYYY-MM-DD-task-name
+escalated_to: null
+escalation_reason: null
+standards_applied: []
+plan_path: null

package/dist/tools/verify_template.js

@@ -0,0 +1,61 @@
+import { tool } from "@opencode-ai/plugin";
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "yaml";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const verify_template = tool({
+    description: "Check if file in the given path exists and follows correct YAML structure by checking against the template file from /templates.",
+    args: {
+        filePath: tool.schema.string().describe("Path to the file to check"),
+        templateName: tool.schema.string().describe("Name of the template from /templates (e.g. orchestrator-state-development.yml)"),
+    },
+    async execute({ filePath, templateName }, context) {
+        const absolutePath = path.resolve(context.directory, filePath);
+        if (!fs.existsSync(absolutePath)) {
+            return { output: `File not found at ${filePath}. Hint: Double-check the path, create the file if it's missing, or verify you are in the correct directory.` };
+        }
+        const templatePath = path.join(__dirname, "../templates", templateName);
+        if (!fs.existsSync(templatePath)) {
+            return { output: `Template '${templateName}' not found. Hint: Verify the template name is correct and exists in the /templates folder (e.g., 'orchestrator-state-development.yml').` };
+        }
+        let targetYaml;
+        try {
+            const fileContent = fs.readFileSync(absolutePath, "utf8");
+            targetYaml = yaml.parse(fileContent);
+        }
+        catch (error) {
+            return { output: `YAML Syntax Error in ${filePath}: ${error.message}. Hint: Check the file content for invalid YAML formatting, such as incorrect indentation or unescaped strings, and fix them.` };
+        }
+        let templateYaml;
+        try {
+            const templateContent = fs.readFileSync(templatePath, "utf8");
+            templateYaml = yaml.parse(templateContent);
+        }
+        catch (error) {
+            return { output: `Internal Error: Failed to parse reference template YAML '${templateName}': ${error.message}. Hint: The template file itself contains invalid YAML syntax.` };
+        }
+        function checkStructure(templateObj, targetObj, currentPath = "") {
+            let errors = [];
+            if (typeof templateObj !== 'object' || templateObj === null) {
+                return errors;
+            }
+            for (const key of Object.keys(templateObj)) {
+                const newPath = currentPath ? `${currentPath}.${key}` : key;
+                if (typeof targetObj !== 'object' || targetObj === null || !(key in targetObj)) {
+                    errors.push(`Missing key: ${newPath}`);
+                    continue;
+                }
+                if (typeof templateObj[key] === 'object' && templateObj[key] !== null && !Array.isArray(templateObj[key])) {
+                    errors.push(...checkStructure(templateObj[key], targetObj[key], newPath));
+                }
+            }
+            return errors;
+        }
+        const errors = checkStructure(templateYaml, targetYaml);
+        if (errors.length > 0) {
+            return { output: `YAML Structure Validation Failed. Your file is missing the following required keys:\n- ${errors.join("\n- ")}\n\nHint: Update the file at ${filePath} to include these missing keys so it matches the structure of '${templateName}'.` };
+        }
+        return { output: "File exists and follows the correct YAML structure." };
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owflow",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Spec-driven development AI workflow for OpenCode",
   "type": "module",
   "module": "index.ts",
@@ -12,9 +12,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc && npm run copy-markdowns",
+    "build": "rm -rf dist && tsc && bun run copy-markdowns",
     "copy-markdowns": "node ./scripts/copy-markdowns.js",
-    "prepack": "npm run build"
+    "prepack": "bun run build",
+    "test": "bun test"
   },
   "keywords": [
     "opencode",