owflow 0.1.1 → 0.1.2

package/dist/skills/codebase-analyzer/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: codebase-analyzer
+description: Analyzes codebase using adaptive parallel Explore subagents based on task complexity. Selects agent roles from a pool, launches Explore agents, then delegates report generation to codebase-analysis-reporter subagent.
+user-invocable: false
+---
+
+# Codebase Analyzer Skill
+
+Orchestrates parallel codebase analysis using built-in Explore subagents. Adaptively selects which agent roles to activate based on task complexity, then delegates report synthesis to a specialized subagent.
+
+## Core Principles
+
+1. **Adaptive Agent Selection**: Select roles from a pool based on task complexity — no fixed count
+2. **Task-Type Awareness**: Adapt prompts and focus based on task type
+3. **Delegated Reporting**: Raw findings go to `codebase-analysis-reporter` subagent for synthesis
+
+---
+
+## Input Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `task_description` | Yes | Description of the development task |
+| `description` | Yes | Task description from user |
+| `task_path` | Yes | Path to task directory |
+| `artifact_name` | No | Override output filename (default: `codebase-analysis.md`) |
+
+---
+
+## Execution Workflow
+
+### Step 1: Parse Input and Determine Focus
+
+Extract keywords, component names, file hints, domain, and technology hints from the description.
+
+Determine primary focus from the task description:
+
+| Signal in Description | Primary Focus | Key Questions |
+|----------------------|---------------|---------------|
+| Error/crash/broken language | Find buggy code path | Where does the issue occur? What's the execution flow? |
+| Improve/enhance/existing | Find existing feature | What files implement this feature? How does it work? |
+| Add/new/create | Find patterns/integration points | What similar patterns exist? Where should this integrate? |
+
+### Step 2: Select Agent Roles
+
+Choose which roles to activate from the pool. Each role is a distinct analysis concern.
+
+| Role | Purpose | When Needed |
+|------|---------|-------------|
+| **File Discovery** | Find relevant files by patterns, keywords, naming | Almost always |
+| **Code Analysis** | Analyze code structure, patterns, execution flow | When understanding existing behavior matters |
+| **Context Discovery** | Find tests, consumers, dependencies | When understanding impact/coverage matters |
+| **Pattern Mining** | Find similar implementations as templates | New features following existing patterns |
+| **Migration Target** | Analyze target technology/compatibility | Migrations comparing current vs target |
+
+**Decision signals:**
+- **Specificity** (exact files mentioned → fewer agents)
+- **Scope breadth** (multiple domains → more agents)
+- **Uncertainty** (unclear location → more agents)
+- **Task type** (bugs tend focused, features broad, migrations broadest)
+
+**Examples:**
+
+| Task Description | Roles Selected | Count |
+|------------------|---------------|-------|
+| "Fix null check in `utils/parser.ts`" | File Discovery + Code Analysis (combined) | 1 |
+| "Add sorting to user table" | File Discovery, Code Analysis | 2 |
+| "Fix login timeout" | File Discovery + Code Analysis (combined), Context Discovery | 2 |
+| "Add OAuth authentication system" | File Discovery, Code Analysis, Context Discovery | 3 |
+| "Add export feature similar to import" | File Discovery, Code Analysis, Pattern Mining | 3 |
+| "Migrate from REST to GraphQL" | File Discovery, Code Analysis, Context Discovery, Migration Target | 4 |
+
+When selecting fewer agents, merge related concerns into a single prompt — don't drop concerns.
+
+State which roles you selected and why (1 sentence).
+
+### Step 3: Read Prompt Templates and Launch Agents
+
+> **STOP — Do NOT skip this step. Do NOT write prompts from memory.**
+>
+> Before launching ANY Explore agent, you MUST use the Read tool to load the prompt template for each selected role. This is non-negotiable.
+
+**3a. Read templates** — Use the Read tool to load ONLY the files for your selected roles:
+
+| Role | Read This File |
+|------|--------------|
+| File Discovery | `references/file-discovery.md` |
+| Code Analysis | `references/code-analysis.md` |
+| Context Discovery | `references/context-discovery.md` |
+| Pattern Mining | `references/pattern-mining.md` |
+| Migration Target | `references/migration-target.md` |
+
+If combining roles into one agent, also read `references/combined.md` for merging guidance.
+
+**3b. Adapt templates** — Replace `[description]` with the actual task description. Select the correct task-type section (Bug / Enhancement / Feature).
+
+**3c. Launch agents** — Use the Task tool with `subagent_type="Explore"` — one call per selected role, all in ONE message.
+
+**IMPORTANT**: Every Explore agent prompt MUST include this instruction:
+> IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+**SELF-CHECK**: Did you read the template files with the Read tool? If not, go back to 3a. Do not proceed.
+
+### Step 4: Delegate Report Generation
+
+After all Explore agents complete, delegate to `codebase-analysis-reporter` subagent via Task tool:
+
+```
+Task tool:
+  subagent_type: "codebase-analysis-reporter"
+  description: "Merge findings into analysis report"
+  prompt: |
+    You are the codebase-analysis-reporter. Merge these raw findings into a structured analysis report.
+
+    Task description: [description]
+    Agent roles used: [list of roles]
+    Agent count: [N]
+    Output path: [task_path]/analysis/[artifact_name]
+
+    ## Raw Findings
+
+    ### [Role 1 Name]
+    [paste raw output from agent 1]
+
+    ### [Role 2 Name]
+    [paste raw output from agent 2]
+
+    [... for each agent]
+```
+
+The subagent produces the final report at `{task_path}/analysis/{artifact_name}` and returns structured results.
+
+### Step 5: Return Results to Orchestrator
+
+Pass through the subagent's structured output:
+
+```yaml
+status: success|partial|failed
+report_path: analysis/[artifact_name]
+summary: "[1-2 sentence summary]"
+files_found: [count]
+complexity: simple|moderate|complex
+risk_level: low|low-medium|medium|medium-high|high
+```
+
+---
+
+## Error Handling
+
+- **No files found**: Report partial results, suggest user provide more specific hints
+- **Agent timeout**: Use results from completed agents, note incomplete analysis
+- **Conflicting results**: Pass all perspectives to reporter subagent, which highlights conflicts
+
+---
+
+## Integration
+
+| Orchestrator | Phase | artifact_name |
+|-------------|-------|---------------|
+| development orchestrator | Phase 1 | `codebase-analysis.md` (default) |
+| migration orchestrator | Phase 1 | `current-state-analysis.md` |
+| performance orchestrator | Phase 1 | `codebase-analysis.md` (default) |

package/dist/skills/codebase-analyzer/references/code-analysis.md

@@ -0,0 +1,63 @@
+# Code Analysis — Prompt Templates
+
+Replace `[description]` with the actual task description.
+
+## Bug
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Analyze the code related to: "[description]"
+
+Focus on:
+1. Trace execution flow from input to output
+2. Identify state changes and side effects
+3. Look for edge cases, error conditions, race conditions
+4. Find validation logic and where it might fail
+5. Check for recent changes that might have introduced the bug
+
+Output:
+- Execution flow diagram (text-based)
+- Key functions/methods involved
+- Potential problem areas
+- State management approach
+```
+
+## Enhancement
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Analyze the existing implementation of: "[description]"
+
+Focus on:
+1. Understand current functionality and capabilities
+2. Identify the component/service architecture
+3. Document the data flow (props, state, API calls)
+4. Note coding patterns used (hooks, classes, functional)
+5. Assess complexity (simple/moderate/complex)
+
+Output:
+- Current functionality summary
+- Architecture overview
+- Key functions and their purposes
+- Coding patterns observed
+```
+
+## Feature
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Analyze the codebase architecture for adding: "[description]"
+
+Focus on:
+1. Understand the overall project structure
+2. Identify architectural patterns in use (MVC, component-based, etc.)
+3. Document naming conventions and code style
+4. Find the data layer patterns (API, state management)
+5. Note any relevant abstractions or base classes
+
+Output:
+- Project structure overview
+- Architectural patterns to follow
+- Naming conventions to match
+- Recommended approach for new feature
+```

package/dist/skills/codebase-analyzer/references/combined.md

@@ -0,0 +1,31 @@
+# Combined Prompts — Guidance
+
+When merging multiple roles into a single agent, integrate concerns logically rather than concatenating prompts. Read the individual role templates first, then merge them into a coherent single prompt.
+
+## Example: File Discovery + Code Analysis (Bug)
+
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Explore and analyze the codebase for: "[description]"
+
+1. Find files where the bug likely occurs (search for error keywords, related functionality)
+2. Trace the code path through these files - entry points, handlers, processing logic
+3. Identify state changes, side effects, and potential failure points
+4. Look for edge cases, validation logic, and error handling
+5. Check for related configuration that might affect behavior
+
+Output:
+- Relevant files with paths and why they matter
+- Execution flow through identified files
+- Key functions/methods and their roles
+- Potential problem areas and root cause hypotheses
+```
+
+## Merging Principles
+
+- Unify the focus areas into a single logical flow (don't just list both sets of bullet points)
+- Combine the output sections — avoid duplicate asks
+- Keep the total prompt concise (aim for 8-12 focus items max)
+- The merged prompt should read as one coherent task, not two tasks stitched together
+- Always include the no-write constraint: "IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only."

package/dist/skills/codebase-analyzer/references/context-discovery.md

@@ -0,0 +1,63 @@
+# Context Discovery — Prompt Templates
+
+Replace `[description]` with the actual task description.
+
+## Bug
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Find testing and context information for: "[description]"
+
+Focus on:
+1. Find existing tests that cover this functionality
+2. Look for test files that might help reproduce the bug
+3. Identify test data or fixtures used
+4. Find related integration or E2E tests
+5. Check for any existing bug reports or TODOs in comments
+
+Output:
+- Relevant test files and what they test
+- Test coverage gaps
+- Reproduction hints from tests
+- Related issues or TODOs found in code
+```
+
+## Enhancement
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Find dependencies and consumers for: "[description]"
+
+Focus on:
+1. Find all files that import/use this feature (consumers)
+2. Identify what this feature depends on (dependencies)
+3. Locate test files and assess coverage
+4. Find API endpoints or routes related to this feature
+5. Check for documentation or comments
+
+Output:
+- Consumer list (who uses this)
+- Dependency list (what this uses)
+- Test files and coverage assessment
+- Integration points
+```
+
+## Feature
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Find integration requirements for: "[description]"
+
+Focus on:
+1. Identify where this feature needs to be registered/routed
+2. Find existing integration patterns (how other features connect)
+3. Look for shared dependencies this feature will need
+4. Check for authentication/authorization patterns to follow
+5. Find configuration or environment requirements
+
+Output:
+- Required integration points
+- Patterns to follow for registration
+- Shared dependencies to use
+- Configuration requirements
+```

package/dist/skills/codebase-analyzer/references/file-discovery.md

@@ -0,0 +1,51 @@
+# File Discovery — Prompt Templates
+
+Replace `[description]` with the actual task description.
+
+## Bug
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Explore the codebase to find files related to: "[description]"
+
+Focus on:
+1. Find files where the bug likely occurs (search for error keywords, related functionality)
+2. Trace the code path - entry points, handlers, processing logic
+3. Look for related error handling, validation, edge cases
+4. Find configuration files that might affect this behavior
+
+Output a list of relevant files with their paths and why they're relevant.
+Be thorough - check multiple naming conventions (PascalCase, kebab-case, snake_case).
+```
+
+## Enhancement
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Explore the codebase to find files that implement: "[description]"
+
+Focus on:
+1. Find the main files for this feature (components, services, controllers)
+2. Look for related files (types, utilities, hooks, styles)
+3. Check multiple naming patterns: *{keyword}*, {Domain}{Component}, etc.
+4. Search in likely directories: src/components/, src/services/, src/features/
+
+Output a ranked list of files with confidence indicators.
+Include file paths, approximate line counts, and why each file is relevant.
+```
+
+## Feature
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Explore the codebase to find patterns and integration points for: "[description]"
+
+Focus on:
+1. Find similar existing features/components to use as templates
+2. Identify where this new feature should live (directory structure)
+3. Look for shared utilities, hooks, or base classes to extend
+4. Find entry points where this feature needs to integrate (routes, menus, etc.)
+
+List the files that serve as good examples or integration points.
+Include reasoning for why each pattern/location is appropriate.
+```

package/dist/skills/codebase-analyzer/references/migration-target.md

@@ -0,0 +1,23 @@
+# Migration Target — Prompt Template
+
+Primarily for migrations. Replace `[description]` with the actual task description.
+
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Analyze the target state for migration: "[description]"
+
+Focus on:
+1. Find any existing usage of the target technology/pattern in the codebase
+2. Look for partial migration attempts or hybrid implementations
+3. Identify compatibility layers, adapters, or shims already in use
+4. Check for migration-related configuration (build tools, transpilers, polyfills)
+5. Document the target conventions and patterns to follow
+
+Output:
+- Existing target technology usage (if any)
+- Partial migration progress found
+- Compatibility concerns identified
+- Target conventions to follow
+- Migration configuration requirements
+```

package/dist/skills/codebase-analyzer/references/pattern-mining.md

@@ -0,0 +1,22 @@
+# Pattern Mining — Prompt Template
+
+Primarily for features, usable for enhancements. Replace `[description]` with the actual task description.
+
+```
+IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
+
+Find similar implementations and reusable patterns for: "[description]"
+
+Focus on:
+1. Find the most similar existing feature/component in the codebase
+2. Identify reusable abstractions, base classes, or utilities that can be extended
+3. Document the conventions these similar implementations follow (file structure, naming, patterns)
+4. Note any generators, templates, or scaffolding tools available
+5. Identify shared hooks, mixins, or helper functions that should be reused
+
+Output:
+- Best template/example to replicate (with file paths)
+- Reusable abstractions and utilities (with file paths)
+- Convention checklist to follow
+- Anti-patterns observed in existing similar features (what NOT to copy)
+```