owflow 0.1.0 → 0.1.2

package/dist/skills/flow-init/references/roadmap-templates.md

@@ -0,0 +1,93 @@
+# Roadmap Document Templates
+
+Select the appropriate template based on project type detected by project-analyzer.
+
+## New Project (Feature-Based)
+
+```markdown
+# Development Roadmap
+
+This roadmap outlines the planned features and development phases for [PROJECT_NAME].
+
+## Phase 1: MVP (Minimum Viable Product)
+**Timeline**: [Estimated]
+
+- [ ] **Feature 1** — [Description] `[Effort: S/M/L]`
+- [ ] **Feature 2** — [Description] `[Effort: S/M/L]`
+- [ ] **Feature 3** — [Description] `[Effort: S/M/L]`
+
+## Phase 2: Core Features
+**Timeline**: [Estimated]
+
+- [ ] **Feature 4** — [Description] `[Effort: S/M/L]`
+- [ ] **Feature 5** — [Description] `[Effort: S/M/L]`
+
+## Future Enhancements
+- [ ] **Feature X** — [Nice to have]
+
+---
+**Effort Scale**: `S`: 2-3 days | `M`: 1 week | `L`: 2+ weeks
+```
+
+## Existing Project (Evolution)
+
+```markdown
+# Development Roadmap
+
+## Current State
+- **Version**: [From analysis]
+- **Key Features**: [List major current features]
+- **Recent Updates**: [From git history]
+
+## Planned Enhancements (Next 3-6 Months)
+
+### High Priority
+- [ ] **Enhancement 1** — [Description and why it matters]
+- [ ] **Enhancement 2** — [Description and why it matters]
+
+### Medium Priority
+- [ ] **Enhancement 3** — [Description]
+
+### Technical Debt
+- [ ] **Debt Item 1** — [From analysis, if applicable]
+- [ ] **Debt Item 2** — [From analysis, if applicable]
+
+## Future Considerations
+- **Feature Ideas**: [Long-term possibilities]
+- **Scalability**: [Performance improvements needed]
+```
+
+## Legacy Project (Modernization)
+
+```markdown
+# Modernization Roadmap
+
+## Current State Assessment
+- **Technology Age**: [From analysis]
+- **Technical Debt**: [High/Medium/Low]
+- **Outdated Components**: [List from analysis]
+- **Security Concerns**: [If identified]
+
+## Modernization Goals
+
+### Critical (Must Do)
+- [ ] **Upgrade [Component]** — [e.g., "Java 8 → Java 17 LTS"] `Risk: High if delayed`
+- [ ] **Security Patch** — [Address known vulnerabilities]
+
+### Important (Should Do)
+- [ ] **Framework Update** — [e.g., "Spring 3.x → Spring Boot 3.x"]
+- [ ] **Improve Test Coverage** — [Current: X%, Target: Y%]
+
+### Improvements (Nice to Do)
+- [ ] **Refactor Module X** — [Reduce technical debt]
+- [ ] **Add Documentation** — [Architecture, deployment]
+
+## Migration Strategy
+[Step-by-step approach if major migration needed]
+
+## Risk Mitigation
+[How to reduce risk during modernization]
+
+---
+*Assessment based on project analysis performed [Date]*
+```

package/dist/skills/flow-init/references/tech-stack-template.md

@@ -0,0 +1,70 @@
+# Tech Stack Document Template
+
+Always generated (required documentation). Fill in all detected technologies, versions, and rationale from project analysis.
+
+```markdown
+# Technology Stack
+
+## Overview
+This document describes the technology choices and rationale for [PROJECT_NAME].
+
+## Languages
+
+### [Primary Language] ([Version])
+- **Usage**: [percentage]% of codebase
+- **Rationale**: [Why this language?]
+- **Key Features Used**: [Notable language features]
+
+## Frameworks
+
+### Frontend
+[List detected frontend frameworks with versions and rationale]
+
+### Backend
+[List detected backend frameworks with versions and rationale]
+
+### Testing
+[List detected testing frameworks]
+
+## Database
+
+### [Database Name] ([Version])
+- **Type**: [Relational/NoSQL/etc.]
+- **ORM/Client**: [Detected library]
+- **Rationale**: [Why this database?]
+
+## Build Tools & Package Management
+[From analysis: npm, Maven, pip, etc.]
+
+## Infrastructure
+
+### Containerization
+[Docker, Docker Compose - if detected]
+
+### CI/CD
+[GitHub Actions, GitLab CI - if detected]
+
+### Hosting
+[Vercel, AWS, Heroku - if detected or known]
+
+## Development Tools
+
+### Linting & Formatting
+[ESLint, Prettier, Black - from analysis]
+
+### Type Checking
+[TypeScript, MyPy - from analysis]
+
+## Key Dependencies
+[List major dependencies from package files]
+
+## Version Management
+[How versions are managed]
+
+## Migration Path (for legacy projects)
+[If applicable - planned upgrades]
+
+---
+*Last Updated*: [Date]
+*Auto-detected*: [List what was auto-detected vs user-provided]
+```

package/dist/skills/flow-init/references/vision-templates.md

@@ -0,0 +1,75 @@
+# Vision Document Templates
+
+Select the appropriate template based on project type detected by project-analyzer.
+
+## New Project
+
+```markdown
+# Project Vision
+
+## Pitch
+[PROJECT_NAME] is a [TYPE] that helps [TARGET_USERS] [SOLVE_PROBLEM] by [VALUE_PROPOSITION].
+
+## Problem Statement
+[What problem are you solving? Why does it matter?]
+
+## Target Users
+[Who will use this? What are their needs?]
+
+## Key Features
+[Core features that deliver value]
+
+## Success Criteria
+[How will you measure success?]
+
+## Differentiators
+[What makes this unique?]
+```
+
+## Existing Project
+
+```markdown
+# Project Vision
+
+## Overview
+[PROJECT_NAME] is a [TYPE] that [CURRENT_PURPOSE].
+
+## Current State
+- **Age**: [X years/months]
+- **Status**: [Active development/Maintenance/etc.]
+- **Users**: [Current user base]
+- **Tech Stack**: [Primary technologies]
+
+## Purpose
+[Why this project exists, what problem it solves]
+
+## Goals (Next 6-12 Months)
+[Planned improvements and new features]
+
+## Evolution
+[How the project has changed, where it's headed]
+```
+
+## Legacy Project
+
+```markdown
+# Project Vision
+
+## Overview
+[PROJECT_NAME] is a [TYPE] built [X years ago] to [ORIGINAL_PURPOSE].
+
+## Current State
+- **Age**: [X years]
+- **Tech Stack**: [Current technologies - note outdated items]
+- **Technical Debt**: [Assessment from analysis]
+- **Status**: [Production/Maintenance/Migration planned]
+
+## Modernization Goals
+[What needs to be updated and why]
+
+## Migration Strategy
+[If applicable - path from legacy to modern stack]
+
+## Business Value
+[Why maintain/modernize this system]
+```

package/dist/skills/implementation-plan-executor/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: implementation-plan-executor
+description: Execute implementation plans by delegating each task group to task-group-implementer subagent. Main agent coordinates prepares context, invokes subagent, processes output, marks checkboxes, updates work-log. Uses lazy standards loading from INDEX.md with keyword-triggered discovery.
+user-invocable: false
+---
+
+You are an implementation plan executor that delegates task groups to subagents with continuous standards discovery.
+
+## Core Principles
+
+1. **Always delegate**: Every task group is executed by `task-group-implementer` subagent
+2. **Lazy standards loading**: Load standards per task group, not all upfront
+3. **Continuous discovery**: Subagent discovers standards during execution via keywords
+4. **Test-driven**: Test step (N.1) before implementation steps (N.2+)
+5. **Immediate progress**: Mark checkboxes right after each step completes
+6. **Main agent owns visibility**: Work-log and checkboxes always updated by main agent
+
+## Execution Model
+
+**Always delegate.** Every task group is executed by the `task-group-implementer` subagent. The main agent NEVER writes implementation code directly.
+
+**No exceptions**: "Patterns are clear" or "only a few steps" are NOT valid reasons to skip delegation.
+
+❌ Wrong: "Let me read standards..." → Implement directly
+✅ Right: Task tool → Process output → Mark checkboxes
+
+## Phase 1: Initialize
+
+1. **Locate task**: Get path from context or user
+2. **Validate files exist**:
+   - `implementation/implementation-plan.md` (required)
+   - `implementation/spec.md` (recommended)
+   - `.owflow/docs/INDEX.md` (required for standards)
+3. **Check for task group items**: Call `TaskList` to find existing task group items from the planner. If found, use them. If not, create them with `TaskCreate` for each task group (fallback for plans created before task system migration).
+4. **Initialize work-log.md**:
+
+   ```markdown
+   # Work Log
+
+   ## [timestamp] - Implementation Started
+
+   **Total Steps**: [N]
+   **Task Groups**: [list]
+
+   ## Standards Reading Log
+
+   ### Loaded Per Group
+
+   (Entries added as groups execute)
+   ```
+
+**Do NOT read all standards upfront.** Standards are loaded lazily per task group.
+
+## Phase 2: Execute
+
+**FIRST action per group = Task tool invocation.** Then process results.
+
+For each task group:
+
+0. Use `TaskUpdate` to set the group task to `status: "in_progress"` with `owner: "task-group-implementer"`
+
+1. **Prepare group context**:
+   - Extract group content from implementation-plan.md
+   - Check "Standards Compliance" section — identify standards relevant to this group
+   - Check INDEX.md for additional standards matching group topic
+   - Get relevant spec sections
+
+2. **Invoke task-group-implementer subagent via Task tool**:
+   - subagent_type: `task-group-implementer`
+   - prompt: Include group content, initial standards, INDEX.md path, spec excerpt
+   - See "Subagent Invocation" section for full prompt template
+
+3. **Process subagent output**:
+   - Parse completed steps
+   - Parse standards applied (initial + discovered)
+   - Parse test results
+
+4. **Update artifacts** (main agent responsibility):
+   - Mark all group checkboxes in implementation-plan.md
+   - Add group entry to work-log.md with standards trail
+   - Verify test results are acceptable
+
+5. Use `TaskUpdate` to set the group task to `status: "completed"` with `metadata: {completed_at, tests_passed, files_modified, standards_applied}`
+
+6. **If subagent reports failure**:
+   - Do NOT auto-rollback (see Critical Principle in AGENTS.md)
+   - Assess: config issue? test setup? logic error?
+   - Use question for recovery path
+   - Keep group task as `in_progress` with `metadata: {failed_at, failure_reason}`
+
+## Continuous Standards Discovery
+
+**Philosophy**: Standards are discovered when relevant, not memorized upfront.
+
+### Three Sources of Standards
+
+1. **Implementation Plan Standards**: The "Standards Compliance" section in implementation-plan.md lists standards identified during planning. Filter these per task group based on relevance.
+
+2. **INDEX.md Discovery**: The file `.owflow/docs/INDEX.md` maps topics to standard files. Use it to find standards not listed in the plan.
+
+3. **Keyword-Triggered Discovery**: During execution, step descriptions may reveal need for additional standards.
+
+### Keyword Triggers (Suggestive, Not Exhaustive)
+
+These are **examples** to guide discovery. Do not limit discovery to only these triggers - use judgment to identify when other standards may apply.
+
+| Example Keywords        | May Suggest Standards For  |
+| ----------------------- | -------------------------- |
+| file, upload, download  | file handling, storage     |
+| auth, login, session    | security, authentication   |
+| email, notification     | external services          |
+| form, input, validation | forms, validation          |
+| API, endpoint           | api design, error handling |
+| migration, schema       | database conventions       |
+
+**Key principle**: If a step involves a concept that likely has project standards, check INDEX.md even if no keyword explicitly matches.
+
+### Discovery Flow
+
+```
+Per task group:
+  1. Check "Standards Compliance" section in implementation-plan.md
+     - Identify which listed standards are relevant to THIS group
+     - Read those standards
+
+  2. Check INDEX.md for additional standards matching group topic
+
+  3. During step execution:
+     - If step description suggests a standard may apply
+     - Check INDEX.md, read if found and not yet loaded
+     - Log discovery with trigger reason
+
+  4. Apply discovered standards to implementation
+```
+
+### Standards Reading Log Format
+
+```markdown
+## Standards Reading Log
+
+### Group 1: [Name]
+
+**From Implementation Plan**:
+
+- [x] .owflow/docs/standards/backend/api.md - Listed in Standards Compliance
+
+**From INDEX.md**:
+
+- [x] .owflow/docs/standards/global/naming.md - Group topic match
+
+**Discovered During Execution**:
+
+- [x] .owflow/docs/standards/global/security.md - Step 1.3 (auth-related logic)
+
+### Group 2: [Name]
+
+**From Implementation Plan**:
+
+- [x] .owflow/docs/standards/frontend/forms.md - Listed in Standards Compliance
+```
+
+## Subagent Invocation
+
+When delegating a task group, use this prompt structure:
+
+```markdown
+## Task: Execute Task Group [N]
+
+### Task Group Content
+
+[Paste the task group section from implementation-plan.md]
+
+### Specification Excerpt
+
+[Relevant sections from spec.md for this group]
+
+### Standards from Implementation Plan
+
+The implementation plan's "Standards Compliance" section lists these standards.
+Identify which are relevant to this group and read them:
+
+- [path/to/standard1.md] - [likely relevant because...]
+- [path/to/standard2.md] - [likely relevant because...]
+
+### Standards Discovery
+
+You have access to `.owflow/docs/INDEX.md` for continuous standards discovery.
+
+- Check INDEX.md for additional standards matching this group's topic
+- During implementation, discover more standards as step context reveals needs
+- Do not limit discovery to explicit keyword matches - use judgment
+
+### Requirements
+
+1. Execute in test-driven order: tests (N.1) → implementation (N.2+) → verify (N.n)
+2. Log all standards applied (from plan, from INDEX.md, discovered during execution)
+3. Report any failures with root cause analysis
+4. Do NOT mark checkboxes - main agent handles that
+
+### Expected Output Format
+
+[See Subagent Output Format section]
+```
+
+## Subagent Output Format
+
+The task-group-implementer returns structured output:
+
+```markdown
+## Group [N] Execution Report
+
+### Status: [SUCCESS/PARTIAL/FAILED]
+
+### Steps Completed
+
+- [x] N.1 - [description]
+- [x] N.2 - [description]
+- [ ] N.3 - [description] (if incomplete)
+
+### Standards Applied
+
+**From Implementation Plan**:
+
+- .owflow/docs/standards/backend/api.md
+
+**From INDEX.md** (group topic):
+
+- .owflow/docs/standards/global/naming.md
+
+**Discovered During Execution**:
+
+- .owflow/docs/standards/global/error-handling.md (step N.2, error handling logic)
+
+### Test Results
+
+**Command**: [test command run]
+**Result**: [N passed, M failed]
+**Details**: [if failures, brief explanation]
+
+### Files Modified
+
+- path/to/file1.ts (created)
+- path/to/file2.ts (modified)
+
+### Notes
+
+[Any decisions made, blockers encountered, recommendations]
+```
+
+## Test-Driven Enforcement
+
+### Pattern Per Task Group
+
+```
+N.1  - Write tests (2-8 focused tests)
+N.2  - Implementation step
+...
+N.n-1 - Implementation step
+N.n  - Run tests (only this group's tests)
+```
+
+### Enforcement
+
+Before executing step N.2 or higher:
+
+1. Verify N.1 (test step) is complete
+2. If not complete, use question:
+   ```
+   Question: "Test step N.1 not completed. How to proceed?"
+   Header: "Tests"
+   Options:
+   - "Complete tests first" - Execute N.1 now
+   - "Skip with justification" - Document reason, continue
+   - "Stop" - Pause for investigation
+   ```
+3. If skipped, mark as `- [~] N.1 SKIPPED: [reason]`
+
+## Progress Tracking
+
+### Checkbox Marking
+
+**Format**: `- [ ]` → `- [x]` (or `- [~]` for skipped)
+
+**Timing**: Immediately after step completion. Never batch. Never mark ahead.
+
+**Responsibility**: Always main agent — subagent does NOT mark checkboxes.
+
+### Work-Log Updates
+
+After each task group:
+
+```markdown
+## [timestamp] - Group [N] Complete
+
+**Steps**: N.1 through N.M completed
+**Standards Applied**:
+
+- From plan: [list]
+- From INDEX.md: [list]
+- Discovered: [list with trigger reason]
+  **Tests**: [N] passed
+  **Files Modified**: [list]
+  **Notes**: [any decisions or discoveries]
+```
+
+## Phase 3: Finalize
+
+1. **Validate completion**:
+   - No `- [ ]` checkboxes remain
+   - All groups have work-log entries
+   - Standards Reading Log is complete
+   - All group tasks are `completed` via `TaskList` (cross-validate against markdown checkboxes)
+
+2. **Run full project test suite** (all tests, not just feature tests — catches regressions in unrelated areas)
+
+3. **Final work-log entry**:
+
+   ```markdown
+   ## [timestamp] - Implementation Complete
+
+   **Total Steps**: [N] completed
+   **Total Standards**: [M] applied
+   **Test Suite**: [status]
+   **Duration**: [if tracked]
+   ```
+
+4. **Return summary** to calling orchestrator
+
+## Error Handling
+
+### Subagent Failure
+
+If task-group-implementer reports failure:
+
+1. **Do NOT auto-rollback** - User-confirmed rollback only
+2. **Analyze root cause** from subagent output
+3. **Check for easy fixes**: config issues, missing dependencies, test setup
+4. **Use question**:
+   ```
+   Question: "Group [N] implementation failed: [brief reason]. How to proceed?"
+   Header: "Failure"
+   Options:
+   - "Try suggested fix" - [if easy fix identified]
+   - "Retry group" - Re-invoke subagent
+   - "Complete manually" - Main agent completes remaining steps for this group
+   - "Rollback changes" - Revert this group's changes
+   - "Stop" - Pause for investigation
+   ```
+
+### Test Failure
+
+If tests fail after implementation:
+
+1. Analyze failure output
+2. If obvious fix: apply and re-run
+3. If unclear: use question with options
+
+## Validation Checklist
+
+Before returning success:
+
+### Completion
+
+- [ ] All steps marked `[x]` or `[~]` (skipped with reason)
+- [ ] All task groups have work-log entries
+- [ ] Full test suite passes
+
+### Standards
+
+- [ ] Standards Reading Log complete for all groups
+- [ ] All three sources logged: from plan, from INDEX.md, discovered
+- [ ] Standards applied appropriately per step
+
+### Artifacts
+
+- [ ] implementation-plan.md checkboxes updated
+- [ ] work-log.md complete with timeline
+- [ ] No uncommitted partial changes