owflow 0.2.0 → 0.3.0

package/dist/skills/orchestrator-framework/references/orchestrator-creation-checklist.md

@@ -9,6 +9,8 @@ Use when creating NEW orchestrators or auditing existing ones. Not loaded during
 Before considering an orchestrator complete, verify ALL items:
 
 - [ ] **Step 0: Load Framework** — Initialization reads `orchestrator-patterns.md`
+- [ ] **Entry Gate** — Skill body opens with the Entry Gate contract (argument resolution, prerequisite table, blocked output, skip/resume semantics — see [Gate Contract](gate-contract.md))
+- [ ] **Exit Gate** — Skill body closes with the Exit Gate contract (results box, results-acceptance question, next-step hint on Accept, STOP — see [Gate Contract](gate-contract.md))
 - [ ] **State file creation** — Explicit step to CREATE `orchestrator-state.yml`
 - [ ] **State verification** — Explicit step to use `verify_template` to check YAML validity after creation
 - [ ] **Phase structure** — Each phase has: Purpose, Execute, Output, State, Transition (`→ Pause` / `→ AUTO-CONTINUE` / `→ Conditional`)
@@ -39,6 +41,7 @@ Before considering an orchestrator complete, verify ALL items:
 | Stopping at AUTO-CONTINUE transitions   | Brief summary is fine, but must proceed immediately |
 | Missing standards references            | INDEX.md must be referenced in relevant phases      |
 | Auto-accepting subagent decisions       | User must consent via question                      |
+| Ending without results-acceptance       | Exit Gate question MUST fire before next-step hint  |
 
 ---
 

package/dist/skills/orchestrator-framework/references/orchestrator-patterns.md

@@ -2,58 +2,14 @@
 
 Shared execution rules, schemas, and patterns for all workflow orchestrators.
 
----
-
-## 1. Delegation Rules
-
-**Always use Skill/Task tools to delegate. Never execute delegated work inline.**
-
-When a phase requires delegation:
-
-1. Use the **Skill tool** for **skills** — loads SKILL.md instructions into the main agent's context; the main agent executes the skill's instructions and continues with the orchestrator workflow afterward
-2. Use the **Task tool** for **subagents/agents** — spawns an isolated subprocess that returns results when complete
-3. Wait for completion before continuing
-
-**Skills and agents are NOT interchangeable.** Skills always use Skill tool; agents always use Task tool. Never invoke a skill via Task tool (`subagent_type`) — it will fail with "Agent type not found."
-
-**Why skills MUST use Skill tool**: Skills like `codebase-analyzer`, `implementation-plan-executor`, and `implementation-verifier` spawn their own subagents (Explore agents, reporters, planners). Subagents cannot spawn other subagents — so these skills must run in the main agent context via Skill tool.
-
-**Companion agent pattern** (e.g., `docs-operator`): Only works for skills that do NOT spawn subagents (like `docs-manager` which only does file operations). A companion agent preloads the skill via the `skills` frontmatter field and is invoked via Task tool. This pattern fails for any skill that needs to spawn subagents.
-
-### Anti-Patterns
-
-| Anti-Pattern                            | Why It's Wrong                              | Correct Approach                                      |
-| --------------------------------------- | ------------------------------------------- | ----------------------------------------------------- |
-| "I'll analyze the codebase..."          | Bypasses codebase-analyzer skill            | Use `Skill` tool with `codebase-analyzer`             |
-| "Let me create the specification..."    | Bypasses specification-creator              | Use `Task` tool with `specification-creator` subagent |
-| "Looking at the gaps between..."        | Bypasses gap-analyzer subagent              | Use `Task` tool with `gap-analyzer`                   |
-| "I'll implement this by..."             | Bypasses implementation-plan-executor skill | Use `Skill` tool with `implementation-plan-executor`  |
-| Reading a SKILL.md then doing the work  | Skill files are instructions FOR skills     | Use Skill tool to invoke                              |
-| Spawning Explore agents in orchestrator | Codebase-analyzer manages its own agents    | Invoke skill, let IT spawn agents                     |
-
-### When Inline Execution is Acceptable
-
-These do NOT require delegation:
-
-1. **Clarifying questions phases** — question is direct
-2. **State updates** — Reading/writing orchestrator-state.yml
-3. **Phase announcements** — Outputting status messages
-4. **Simple decisions** — Enabling/disabling optional phases
-5. **Finalization** — Creating summary, updating metadata
+Some heavily cross-referenced sections live in their own reference files:
 
-For all analysis, planning, implementation, and verification phases: **ALWAYS DELEGATE**.
+- [Delegation Rules](delegation-rules.md) — Skill/Task tool delegation contract (was Section 1)
+- [Dispatcher & Handoff Pattern](dispatcher-handoff.md) — subskill loop, mode table, per-step state writes (was Section 7)
+- [Command Namespacing](command-namespacing.md) — `owflow:` prefix rules (was Section 8)
+- [Gate Contract](gate-contract.md) — Entry Gate & Exit Gate skill contract, incl. exceptions (was Section 9)
 
-**Never acceptable inline** (regardless of perceived task simplicity):
-
-- Specification creation → always delegate to `specification-creator` subagent
-- Implementation planning → always delegate to `implementation-planner` subagent
-- Gap analysis → always delegate to `gap-analyzer` subagent
-- Codebase analysis → always delegate to `codebase-analyzer` skill
-- Code review → always delegate to `code-reviewer` subagent
-- Test execution → always delegate to `test-suite-runner` subagent
-- Implementation completeness → always delegate to `implementation-completeness-checker` subagent
-
-"The task is simple" is NOT a valid reason to skip delegation.
+Section numbering below is kept as-is so existing cross-references stay valid.
 
 ---
 
@@ -272,3 +228,5 @@ If prerequisites missing, use question: "Start from Phase 1", "Specify different
 | User chooses "Proceed with known issues" | Proceed with warning logged                        |
 | Max iterations (3) reached               | Ask user how to proceed                            |
 | Critical issues remain unresolved        | **MUST NOT proceed** — require user approval first |
+
+---

package/dist/skills/performance/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: performance
+name: owflow:performance
 description: Orchestrates performance optimization workflows using static code analysis to identify bottlenecks (N+1 queries, missing indexes, O(n^2) algorithms, blocking I/O, memory leaks). Accepts optional user-provided profiling data. Reuses standard specification, planning, implementation, and verification phases.
 user-invocable: true
 ---
@@ -8,24 +8,36 @@ user-invocable: true
 
 Static-analysis-first performance optimization workflow. Identifies bottlenecks by reading code, then uses the standard specification/planning/implementation/verification pipeline to fix them.
 
-## Initialization
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md).
+
+## Entry Gate
 
 **BEFORE executing any phase, you MUST complete these steps:**
 
-### Step 1: Load Framework Patterns
+### Argument resolution
+
+- **Performance issue description provided** → use it as the task description.
+- **Task path / identifier** (directory under `.owflow/tasks/performance/`) → resume mode: read `orchestrator-state.yml`, find the first incomplete phase (`--from=PHASE` overrides), validate existing artifacts, then continue from there.
+- **Nothing provided** → ask via `question`: "What is slow or performance-constrained? Describe the symptom (endpoint, page, job), expected vs actual behavior, and any profiling data you have." — collect the description, plus optional profiling data paths, before proceeding.
+
+### Prerequisites
 
-**Read the framework reference file NOW using the Read tool:**
+| Required for this skill | Where verified                                        | Produced by                  |
+| ----------------------- | ----------------------------------------------------- | ---------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml` (resume mode)    | prior `/owflow:performance` run |
 
-1. `../orchestrator-framework/references/orchestrator-patterns.md` - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution
+On resume, if the state file is missing → print: `No performance task found at <path>. Run /owflow:performance <description> to start from scratch.` and STOP. Validate expected artifacts for completed phases (remove entries with missing artifacts).
 
-### Step 2: Initialize Workflow
+### Execution steps
 
-1. **Create Task Items**: Use `TaskCreate` for all phases (see Phase Configuration), then set dependencies with `TaskUpdate addBlockedBy`
-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.
+1. **Load framework patterns** — Read `../orchestrator-framework/references/orchestrator-patterns.md` NOW: delegation rules, interactive mode, state schema, initialization, context passing, issue resolution.
+2. **Initialize workflow:**
+   1. **Create Task Items**: Use `TaskCreate` for all phases (see Phase Configuration), then set dependencies with `TaskUpdate addBlockedBy`
+   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**:
 
@@ -326,11 +338,11 @@ question - Display executive summary: total issues found, issues fixed, issues r
 
 ---
 
-### Phase 9: Finalization
+### Phase 9: Finalization → Exit Gate
 
 > **Phase gate**: Requires `question` confirmation from Phase 8 before executing.
 
-**Purpose**: Complete workflow and provide next steps
+**Purpose**: Present optimization results, confirm correctness with the user, and close the workflow (Exit Gate contract, [Gate Contract](../orchestrator-framework/references/gate-contract.md))
 **Execute**: Direct - create summary, update state, guide commit
 **Output**: Workflow summary
 **State**: Set `task.status: completed`
@@ -339,12 +351,34 @@ question - Display executive summary: total issues found, issues fixed, issues r
 
 1. Create workflow summary (bottlenecks found, optimizations implemented, verification result)
 2. Update task status to "completed"
-3. Provide commit message template
-4. Guide performance-specific next steps:
+3. **Results box**:
+
+```markdown
+## ✅ PERFORMANCE WORKFLOW COMPLETE — <task name>
+
+**Bottlenecks found** — [count by severity]
+**Optimizations applied** — [count + key ones]
+**Verification** — [final verdict]
+**Estimated improvement** — [range from analysis]
+
+**Artifacts**
+- `analysis/performance-analysis.md`
+- `implementation/work-log.md`
+- `verification/implementation-verification.md`
+```
+
+4. **Results-acceptance question** — use `question` — "Are these results correct?" with options:
+   - **Accept** — workflow is complete; print next steps below.
+   - **Adjust** — re-run the affected phase (additional optimizations, re-verification) with the user's corrections, then re-present the results box.
+   - **Discuss** — walk through bottleneck findings, optimization rationale, and measurement caveats in more depth; then re-ask.
+   - **Stop here** — print the resume command (`/owflow:performance <task-path>`) and end.
+
+5. **Next steps (after Accept)** — performance-specific guidance:
    - Run the application and verify improvements manually
    - Consider profiling with runtime tools to measure actual impact
    - Monitor production metrics after deployment
    - Address remaining P2/P3 bottlenecks if needed
+   - `/owflow:standards-update "<lesson learned>"` — capture optimization patterns as standards
 
 → End of workflow
 
@@ -396,7 +430,7 @@ Refer to the template [src/templates/orchestrator-state-performance.yml](../../t
 
 Invoked via:
 
-- `/performance [description]` (new)
-- `/performance [task-path] [--from=PHASE]` (resume)
+- `/owflow:performance [description]` (new)
+- `/owflow:performance [task-path] [--from=PHASE]` (resume)
 
 Task directory: `.owflow/tasks/performance/YYYY-MM-DD-task-name/`

package/dist/skills/research/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: research
+name: owflow:research
 description: Orchestrates comprehensive research workflows from question definition through findings documentation. Handles technical, requirements, literature, and mixed research types with adaptive methodology, multi-source gathering, pattern synthesis, and evidence-based reporting. Supports standalone research tasks and embedded research phase in other workflows.
 user-invocable: true
 ---
@@ -8,22 +8,34 @@ user-invocable: true
 
 Systematic research workflow from question definition to evidence-based documentation.
 
-## Initialization
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md).
+
+## Entry Gate
 
 **BEFORE executing any phase, you MUST complete these steps:**
 
-### Step 1: Load Framework Patterns
+### Argument resolution
+
+- **Research question provided** → use it as the task description.
+- **Task path / identifier** (directory under `.owflow/tasks/research/`) → resume mode: read `orchestrator-state.yml`, find the first incomplete phase (`--from=PHASE` overrides), validate existing artifacts, then continue from there.
+- **Nothing provided** → ask via `question`: "What is your research question?" (free-form answer), then proceed.
+
+### Prerequisites
 
-**Read the framework reference file NOW using the Read tool:**
+| Required for this skill | Where verified                                        | Produced by                |
+| ----------------------- | ----------------------------------------------------- | -------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml` (resume mode)    | prior `/owflow:research` run |
 
-1. `../orchestrator-framework/references/orchestrator-patterns.md` - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution
+On resume, if the state file is missing → print: `No research task found at <path>. Run /owflow:research <question> to start from scratch.` and STOP. Validate expected artifacts for completed phases (remove entries with missing artifacts).
 
-### Step 2: Initialize Workflow
+### Execution steps
 
-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`.
+1. **Load framework patterns** — Read `../orchestrator-framework/references/orchestrator-patterns.md` NOW: delegation rules, interactive mode, state schema, initialization, context passing, issue resolution.
+2. **Initialize workflow:**
+   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**:
 
@@ -341,26 +353,47 @@ question - "Design complete. Continue to output generation?"
 
 ---
 
-### Phase 6: Completion
+### Phase 6: Completion → Exit Gate
 
 > **Phase gate**: Requires `question` confirmation from the preceding phase before executing.
 
-**Purpose**: Summarize research results and suggest next steps
+**Purpose**: Present research results, confirm correctness with the user, and hand off (Exit Gate contract, [Gate Contract](../orchestrator-framework/references/gate-contract.md))
 **Execute**: Direct
 **Output**: No new files — summarizes existing outputs
 
 **Process**:
 
 1. Inventory all generated outputs: `outputs/research-report.md` (always), plus conditional: `solution-exploration.md`, `high-level-design.md`, `decision-log.md`
-2. Present executive summary to user:
-   - Key findings and confidence level
-   - Which optional phases ran (brainstorming, design)
-   - Key decision highlights (if brainstorming/design ran)
-3. If design artifacts exist, suggest starting development in a fresh session:
-   ```
-   To start development based on this research, clear context first or start a new session, then run:
-   /development [task-path]
-   ```
+2. **Results box**:
+
+```markdown
+## ✅ RESEARCH COMPLETE — <research question>
+
+**Type** — [research type]
+**Confidence** — [confidence level]
+**Phases run** — [e.g. 1, 3-4 brainstorm, 5 design]
+**Key findings** — [2-3 one-line highlights]
+**Decisions** — [count of ADRs, if design ran]
+
+**Artifacts**
+- `outputs/research-report.md`
+- `outputs/solution-exploration.md` [conditional]
+- `outputs/high-level-design.md` [conditional]
+- `outputs/decision-log.md` [conditional]
+```
+
+3. **Results-acceptance question** — use `question` — "Are these results correct?" with options:
+   - **Accept** — research is complete; print next steps (below).
+   - **Adjust** — re-run the affected phase (re-gather, re-brainstorm, re-design) with the user's corrections, then re-present the results box.
+   - **Discuss** — walk through specific findings or decisions in more depth; then re-ask.
+   - **Stop here** — print the resume command (`/owflow:research <task-path>`) and end.
+
+4. **Next steps (after Accept)** — if design artifacts exist, suggest starting development in a fresh session:
+
+```
+To start development based on this research, clear context first or start a new session, then run:
+→ /owflow:development <task-path>
+```
 
 → End of workflow
 
@@ -420,7 +453,7 @@ Refer to the template [src/templates/orchestrator-state-research.yml](../../temp
 
 ### As Standalone Research
 
-**Command**: `/research [research-question]`
+**Command**: `/owflow:research [research-question]`
 **Flow**: Complete all phases, save outputs in task directory
 
 ### As Embedded Research Phase
@@ -444,8 +477,8 @@ Refer to `research_outputs` in the template [src/templates/orchestrator-state-re
 
 Invoked via:
 
-- `/research [question] [--type=TYPE] [--brainstorm] [--no-brainstorm] [--design] [--no-design]` (new)
-- `/research [task-path] [--from=PHASE]` (resume)
+- `/owflow:research [question] [--type=TYPE] [--brainstorm] [--no-brainstorm] [--design] [--no-design]` (new)
+- `/owflow:research [task-path] [--from=PHASE]` (resume)
 
 **Brainstorming flags**: