owflow 0.1.4 → 0.1.6

package/dist/skills/performance/SKILL.md

@@ -24,6 +24,7 @@ Static-analysis-first performance optimization workflow. Identifies bottlenecks
 2. **Create Task Directory**: `.owflow/tasks/performance/YYYY-MM-DD-task-name/`
 3. **Create Subdirectories**: `analysis/`, `analysis/user-profiling-data/`, `implementation/`, `verification/`
 4. **Initialize State**: Create `orchestrator-state.yml` with performance context
+   - **CRITICAL**: Use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-performance.yml`.
 5. **Discover project documentation**: Read `.owflow/docs/INDEX.md` (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs. Store as `project_context.project_doc_paths` in state.
 
 **Output**:
@@ -168,6 +169,12 @@ question - "Performance analysis complete. [N] bottlenecks identified ([P0 count
 
 **SELF-CHECK**: Did you just invoke the Task tool with `specification-creator`? Or did you start writing spec.md yourself? If the latter, STOP and invoke the Task tool.
 
+**Part C — Diagram Refinement (Skill, content-preserving)**:
+
+5. Invoke Skill tool: `diagrams-mermaid` to refine `implementation/spec.md`
+6. Add diagrams that clarify bottleneck flows and optimization boundaries without replacing specification text.
+7. If context for a diagram is missing, document gaps and avoid speculative dependencies.
+
 → Pause
 
 question - Display executive summary before asking. Read `implementation/spec.md` and extract: optimization targets, approach chosen, number of changes planned, expected impact. Format as brief overview then "Continue to specification audit?"
@@ -217,6 +224,12 @@ question - Display executive summary before asking. Read `verification/spec-audi
 
 **SELF-CHECK**: Did you just invoke the Task tool with `implementation-planner`? Or did you start writing the plan yourself? If the latter, STOP and invoke the Task tool.
 
+**Post-plan diagram refinement (Skill, content-preserving)**:
+
+- Invoke Skill tool: `diagrams-mermaid` for `implementation/implementation-plan.md`
+- Add one compact optimization execution flow (task-group dependency or state flow).
+- Keep plan steps authoritative; diagrams are explanatory additions only.
+
 → Pause
 
 question - Display executive summary before asking. Read `implementation/implementation-plan.md` and extract: number of task groups, total steps, key dependencies, optimization sequence. Format as brief overview then "Continue to implementation?"
@@ -341,36 +354,7 @@ question - Display executive summary: total issues found, issues fixed, issues r
 
 Performance-specific fields in `orchestrator-state.yml`:
 
-```yaml
-performance_context:
-  bottlenecks_identified: null # count from bottleneck-analyzer
-  user_data_available: false # whether user provided profiling data
-  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
-
-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
-```
+Refer to the template [src/templates/orchestrator-state-performance.yml](../../templates/orchestrator-state-performance.yml).
 
 ---
 

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**:
 
@@ -326,6 +327,14 @@ question - "Brainstorming complete. Continue to high-level design?"
 - Key decision highlights (1 line each)
 - Integration points with existing system (if applicable)
 
+**Part D — Diagram Refinement (Skill, content-preserving)**:
+
+5. Invoke Skill tool: `diagrams-mermaid` to refine visual communication in `outputs/high-level-design.md`
+6. Add diagrams that supplement (not replace) existing architecture content:
+   - one architecture view (`C4Container` preferred, `C4Component` only if needed),
+   - one interaction/state view (`sequenceDiagram` or `flowchart`) for the critical flow.
+7. If minimum context for a diagram is missing, record explicit gaps in the document and avoid speculative components/relationships.
+
 → Pause
 
 question - "Design complete. Continue to output generation?"
@@ -361,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).
 
 ---
 
@@ -460,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