owflow 0.5.0 → 0.6.0

package/dist/skills/performance-analyze/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: owflow:performance-analyze
+description: Performance — codebase analysis with clarifications, then static bottleneck identification via delegation. First work step of the performance workflow; continues with performance-spec.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Performance Analyze — Codebase & Bottleneck Analysis (codebase-analysed, bottlenecks-identified)
+
+Work step of the performance workflow. Explores the codebase for performance context, gathers clarifications, then delegates static bottleneck identification (N+1 queries, missing indexes, O(n^2) algorithms, blocking I/O, memory leaks, caching opportunities) to the `bottleneck-analyzer` agent. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+The performance metrics and optimization-pattern reference lives in this skill's own folder (`references/performance-optimization-guide.md`).
+
+Related entry points: `/owflow:performance` (assisted mode), `/owflow:goal-performance` (autonomous mode). Both produce the same state; you may mix them freely.
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/performance/` (e.g., `2026-10-02-api-latency`); resolve to its path.
+- **Description** — anything else (free text) is treated as a new performance task description: ask via `question` whether to start a fresh standard task at this step (mid-pipeline bootstrap) or route through `/owflow:performance <description>`; on decline, print the blocked block and STOP.
+- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Prerequisites: none — this is the first work step. Everything else requires it.
+2. List available performance-task identifiers (directories under `.owflow/tasks/performance/`) to resume from, if any.
+3. Hint: `Run /owflow:performance <description> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill    | Where verified                                  | Produced by                  |
+| -------------------------- | ----------------------------------------------- | ---------------------------- |
+| State file exists          | `<task-path>/orchestrator-state.yml`            | `/owflow:performance <desc>` |
+| Task description recorded  | `task.description` non-null in state            | `/owflow:performance <desc>` |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `codebase-analysed`): `question` — create a fresh standard performance task starting at this step, or decline → print `No performance task found at <path>. Run /owflow:performance <description> to start a task from scratch.` and STOP.
+2. **Content check**: if `task.description` is null, 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." — and record it in `task.description` before proceeding.
+3. **Skip/resume (artifacts before state)**: if `codebase-analysed` is in `completed_phases`, validate `analysis/codebase-analysis.md` exists; missing → drop the slug and re-run that step. If both `codebase-analysed` and `bottlenecks-identified` are complete (validated against `analysis/performance-analysis.md`), report existing results and route to the Exit Gate. If only `codebase-analysed` is complete, skip to the bottleneck step.
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) and the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md).
+
+### Codebase Analysis (`codebase-analysed`)
+
+**Artifacts**: `analysis/codebase-analysis.md`, `analysis/clarifications.md`
+
+> **ANTI-PATTERN — never run the codebase analysis yourself. "The codebase is small" is NOT a reason to skip delegation.**
+>
+> - ❌ "Let me explore the codebase myself..." — STOP. Delegate to `codebase-analyzer`.
+> - ❌ "I'll read a few key files and summarize..." — STOP. Delegate to `codebase-analyzer`.
+
+1. **INVOKE NOW** (Skill tool — never the Task tool; this skill spawns its own subagents): Skill tool - `codebase-analyzer`. Pass: task description (`task.description`), task_path, performance-focused guidance (database query patterns, hot code paths, I/O operations, caching layers, connection management, schema/migration files), `performance_context.project_doc_paths` from state, and any files present in `analysis/user-profiling-data/`. The analyzer adaptively selects parallel Explore agents based on complexity.
+2. **SELF-CHECK**: Did you just invoke the Skill tool with `codebase-analyzer`? Or did you start exploring code yourself? If the latter, STOP and invoke the Skill tool.
+3. Direct - use `question` for max 5 critical clarifying questions about performance concerns, hotspots, and optimization goals. Save to `analysis/clarifications.md`; record the outcome in `performance_context.phase_summaries.clarifications` (summary).
+4. **State write**: append `codebase-analysed` to `completed_phases`; update `performance_context.phase_summaries.codebase_analysis` (`key_files` + summary); bump `orchestrator.updated`. On failure: append `codebase-analysed` to `failed_phases`, increment `auto_fix_attempts["codebase-analysed"]`. Then re-read state + run `verify_template` (see State Update Convention).
+
+### Bottleneck Analysis (`bottlenecks-identified`)
+
+**Artifacts**: `analysis/performance-analysis.md`
+
+> **ANTI-PATTERN — never analyze bottlenecks yourself. "The patterns are obvious" is NOT a reason to skip delegation.**
+>
+> - ❌ "Let me analyze the bottlenecks myself..." — STOP. Delegate to `bottleneck-analyzer`.
+> - ❌ "I'll grep for N+1 patterns..." — STOP. Delegate to `bottleneck-analyzer`.
+
+1. **Read `references/performance-optimization-guide.md` NOW using the Read tool** — performance metrics vocabulary and optimization patterns (the reference lives in this skill's own folder). Use it to frame the context you pass to the agent and to interpret its findings.
+2. Check `analysis/user-profiling-data/`. If empty, `question` — "Do you have profiling data to provide (flame graphs, APM screenshots, slow query logs)?" with options "Yes, let me add files to analysis/user-profiling-data/" / "No, proceed with static analysis only". If the user adds files, wait for them, then continue.
+3. **INVOKE NOW** (Task tool — never the Skill tool; this is an agent): Task tool - `bottleneck-analyzer` subagent. Pass (Pattern 7 — accumulated context): task_path, task description, the codebase-analysis summary from `performance_context.phase_summaries.codebase_analysis`, user-data paths (if any), `performance_context.project_doc_paths`, and relevant `performance_context.phase_summaries`. Output: `analysis/performance-analysis.md`.
+4. **Extract structured data from the result** (this gates later steps — do not summarize only): read the bottleneck count into `performance_context.bottlenecks_identified`, the P0-P3 split into `performance_context.bottleneck_priorities.p0…p3`, and `performance_context.user_data_available`; write the bottleneck list and a 1-2 sentence summary into `performance_context.phase_summaries.bottleneck_analysis`. Also set `performance_context.task_characteristics` from the findings (consumed by `specification-creator` and `implementation-planner`): `modifies_existing_code: true`; `involves_data_operations: true` when data-layer access (queries, indexes, schema) is implicated; `creates_new_entities: true` when the fix introduces new components (e.g., a cache layer); `ui_heavy: true` when hot paths are UI rendering; `has_reproducible_defect` stays `false`.
+5. **SELF-CHECK**: Did you just invoke the Task tool with `bottleneck-analyzer`? Or did you start analyzing code yourself? If the latter, STOP and invoke the Task tool.
+6. **State write**: append `bottlenecks-identified` to `completed_phases`; update `performance_context.bottlenecks_identified`, `performance_context.user_data_available`, `performance_context.bottleneck_priorities`, `performance_context.task_characteristics`, and `performance_context.phase_summaries.bottleneck_analysis`; bump `orchestrator.updated`. On failure: append `bottlenecks-identified` to `failed_phases`, increment `auto_fix_attempts["bottlenecks-identified"]`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`codebase-analysed`, `bottlenecks-identified`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the step fails or its retries are abandoned, do NOT append to `completed_phases`; instead append the step's slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-performance.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                                        | Max Attempts | Strategy                                              |
+| ------------------------------------------- | ------------ | ----------------------------------------------------- |
+| Codebase Analysis (`codebase-analysed`)     | 2            | Expand search scope, prompt user for hints            |
+| Bottleneck Analysis (`bottlenecks-identified`) | 2          | Re-analyze with broader patterns, ask user for hotspots |
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ PERFORMANCE ANALYZE COMPLETE — <task name>
+
+**Codebase** — [key files/modules from performance_context.phase_summaries.codebase_analysis]
+**Bottlenecks** — [N identified: X P0 / Y P1 / Z P2 / W P3]
+**User data** — [incorporated / static analysis only]
+**Clarifications** — [key answers / "none needed"]
+
+**Artifacts**
+
+- `analysis/codebase-analysis.md`
+- `analysis/clarifications.md`
+- `analysis/performance-analysis.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — analysis is good; continue.
+- **Adjust** — re-run only the affected step (codebase analysis, clarifications, or bottleneck analysis), update state and artifacts, re-present the results box.
+- **Discuss** — walk through a specific result (bottleneck prioritization, missing-index evidence, improvement estimates) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:performance-analyze <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:performance-spec <task-path>` — `required` next: gathers optimization priorities, constraints, and targets, then writes the specification. Remaining after: plan → implement → verify → finalize.
+
+**Other options**:
+
+- `/owflow:goal-performance <task-path>` — `optional` shortcut: runs all remaining steps in one loop (spec → plan → implement → verify → finalize)
+
+Then STOP.

package/dist/skills/{performance → performance-analyze}/references/performance-optimization-guide.md

@@ -1,12 +1,11 @@
 # Performance Optimization Guide
 
-Reference covering performance metrics knowledge, optimization patterns, and static analysis detection strategies.
+Reference covering performance metrics knowledge and optimization patterns.
 
 ## Table of Contents
 
 1. [Performance Metrics](#performance-metrics)
 2. [Optimization Patterns](#optimization-patterns)
-3. [Static Analysis Detection Patterns](#static-analysis-detection-patterns)
 
 ---
 
@@ -270,96 +269,3 @@ for (let i = 0; i < 1000000; i++) {
 
 ---
 
-# Static Analysis Detection Patterns
-
-Strategies for detecting performance bottlenecks by reading code rather than running profiling tools.
-
-## Database Pattern Detection
-
-### N+1 Query Detection by Framework
-
-**Generic ORM-in-loop patterns** (Grep heuristics):
-- Query call inside `for`/`forEach`/`map`/`while` body
-- `await` + model method inside iteration callback
-- Lazy-loaded relationship access inside loop
-
-**Framework-specific indicators**:
-
-| Framework | N+1 Pattern | Fix Pattern |
-|-----------|-------------|-------------|
-| Sequelize | `.findByPk()`/`.findOne()` in loop | `include: [{ model: X }]` |
-| Prisma | `prisma.x.findUnique()` in loop | `include: { x: true }` |
-| TypeORM | `repository.findOne()` in loop | `relations: ['x']` or QueryBuilder `.leftJoinAndSelect()` |
-| Django | Attribute access in template `{% for %}` | `.select_related()`/`.prefetch_related()` |
-| Rails | Association call without `.includes()` | `.includes(:association)` |
-| SQLAlchemy | Relationship access in loop | `joinedload()`/`subqueryload()` |
-| Hibernate | `@ManyToOne` lazy access in loop | `@Fetch(FetchMode.JOIN)` or JPQL `JOIN FETCH` |
-
-### Missing Index Detection
-
-**Cross-reference strategy**:
-1. Find all index definitions in schema/migration files
-2. Find all query patterns (WHERE, ORDER BY, JOIN columns)
-3. Flag columns queried but not indexed
-
-**Where to find indexes by framework**:
-- **Rails**: `add_index` in `db/migrate/` files
-- **Django**: `db_index=True` in model fields, `indexes` in Meta
-- **Sequelize**: `indexes` array in model definition
-- **Prisma**: `@@index` and `@@unique` in schema.prisma
-- **TypeORM**: `@Index()` decorator
-- **SQL migrations**: `CREATE INDEX` statements
-
-### Slow Query Pattern Indicators
-
-Patterns detectable from code without running queries:
-- `SELECT *` on tables with many columns
-- Missing `LIMIT`/`TOP` on queries against known-large tables
-- `LIKE '%...'` (leading wildcard prevents index use)
-- `OR` conditions on different columns (prevents single index use)
-- Subqueries in WHERE that could be JOINs
-- `DISTINCT` masking a JOIN issue
-
-## Algorithm Pattern Detection
-
-### Nested Loop / O(n^2) Heuristics
-
-**Search patterns**:
-- Nested `for`/`forEach`/`while` loops over same or related collections
-- `.find()`/`.filter()`/`.some()`/`.includes()` inside `.map()`/`.forEach()`/`for`
-- `.indexOf()` inside loop (linear search repeated)
-- `.sort()` inside loop (O(n log n) per iteration)
-
-**Fix indicators**: Can be resolved by pre-building a Map/Set/index before the loop
-
-### Blocking I/O Patterns
-
-**Node.js sync operations**:
-- `readFileSync`, `writeFileSync`, `readdirSync`, `statSync`, `existsSync`
-- `execSync`, `spawnSync`
-- `crypto.pbkdf2Sync`, `crypto.randomBytesSync`
-
-**Sequential awaits** (should be `Promise.all`):
-- Multiple `await` statements on independent operations in same function
-- Sequential HTTP/fetch calls to different endpoints
-- Sequential database queries with no data dependency between them
-
-## Memory Pattern Detection
-
-**Unbounded growth indicators**:
-- `Map`/`Set`/`Object`/`Array` in module or class scope with `.set()`/`push()` but no `.delete()`/eviction
-- No size limit check before adding to collection
-- No TTL or expiration mechanism
-
-**Leak-prone patterns**:
-- `addEventListener`/`.on()` without paired `removeEventListener`/`.off()`
-- `setInterval` without `clearInterval` in cleanup/destroy/unmount
-- Closures in long-lived callbacks capturing large objects
-
-## Caching Opportunity Detection
-
-**Indicators**:
-- Same query/function called multiple times with same parameters in a request lifecycle
-- Database query in a loop that could be batched and cached
-- External API call returning reference/config data (infrequent changes)
-- Expensive computation (sort, aggregate, transform) on data that doesn't change per-request

package/dist/skills/performance-finalize/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: owflow:performance-finalize
+description: Performance — terminal step. Inventories optimization results, presents the workflow results box, records task-completed only after the user accepts it, and provides commit guidance. No handoff.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Performance Finalize — Completion & Commit Guidance (task-completed)
+
+Terminal step of the performance workflow. Summarizes the bottlenecks found, the optimizations applied, and the verification outcome; confirms correctness with the user; records `task-completed` only after the user accepts the results box (state is marked complete only after the gate response); and owns the commit guidance. No new analysis — finalization is inline-legal. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related steps: all performance subskills (`/owflow:performance-analyze` → `/owflow:performance-spec` → `/owflow:performance-plan` → `/owflow:performance-implement` → `/owflow:performance-verify`). This is the terminal skill: its Exit-Gate acceptance is where the goal-performance wrapper's loop ends.
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/performance/` (e.g., `2026-10-02-api-latency`); resolve to its path.
+- **Description** — anything else (free text) is treated as a new performance task description: ask via `question` whether to start a fresh standard task at this step (mid-pipeline bootstrap) or route through `/owflow:performance <description>`; on decline, print the blocked block and STOP.
+- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Steps that must be completed first (in order), each with its command:
+   - Codebase & bottleneck analysis (`codebase-analysed`, `bottlenecks-identified`) → `/owflow:performance-analyze <task-path>`
+   - Requirements, specification & conditional audit (`spec-written`, `spec-audited`) → `/owflow:performance-spec <task-path>`
+   - Implementation planning (`plan-created`) → `/owflow:performance-plan <task-path>`
+   - Implementation (`implementation-done`) → `/owflow:performance-implement <task-path>`
+   - Verification & issue resolution (`options-chosen`, `verification-done`) → `/owflow:performance-verify <task-path>`
+2. List available performance-task identifiers (directories under `.owflow/tasks/performance/`) to resume from, if any.
+3. Hint: `Run /owflow:performance <description> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill | Where verified                                                              | Produced by                              |
+| ----------------------- | --------------------------------------------------------------------------- | ---------------------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                        | `/owflow:performance <desc>`             |
+| Verification done       | `verification-done` in `completed_phases` + `verification/implementation-verification.md` exists | `/owflow:performance-verify <task-path>` |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `task-completed`): `question` — create a fresh standard performance task starting at this step, or decline → print `No performance task found at <path>. Run /owflow:performance <description> to start a task from scratch.` and STOP.
+2. **Skip/resume**: if `task.status` is `completed`, report the existing finalization (the results box from the Finalization step below) and STOP.
+3. **Prerequisite check (presence and content)**: `verification-done` in `completed_phases` AND `verification/implementation-verification.md` exists. If missing → print the blocked block, then STOP:
+   - Steps that must be completed first: verification (`verification-done`).
+   - `Run /owflow:performance-verify <task-path> first` (or the command for the earliest missing earlier step).
+   - If no task exists yet: `Run /owflow:performance <description> to start a task from scratch.`
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) — finalization is inline-legal (creating the summary, updating metadata, and presenting results are direct steps; no agents involved).
+
+### Finalization (`task-completed`, inline)
+
+1. **Inventory results** (state-only; no new files): bottlenecks from `performance_context.bottleneck_priorities` and `performance_context.phase_summaries.bottleneck_analysis`; optimizations from `performance_context.phase_summaries.implementation` and `implementation/work-log.md`; verification outcome from `verification_context.last_status` and `verification/implementation-verification.md`.
+2. **Present the results box** (the workflow-level box — single box, not two):
+
+```markdown
+## ✅ PERFORMANCE WORKFLOW COMPLETE — <task name>
+
+**Bottlenecks found** — [P0/P1/P2/P3 counts]
+**Optimizations applied** — [count + key ones]
+**Verification** — [final verdict]
+**Estimated improvement** — [range from the analysis]
+
+**Artifacts**
+
+- `analysis/performance-analysis.md`
+- `implementation/work-log.md`
+- `verification/implementation-verification.md`
+```
+
+3. **Do NOT write `task-completed` yet** — the Exit Gate below owns the write, and it happens only after the user answers the results-acceptance question (Accept, or explicit proceed-with-issues). State is marked complete only after the gate response; writing it here would make the Adjust option a dead end (the completed task short-circuits on re-entry).
+4. **Prepare (do not print yet) the commit guidance** (owned by this skill): a conventional commit message template referencing the task name, and the artifact set that belongs in the commit. It is printed on Accept, together with the closing guidance.
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`task-completed`) plus that step's fields. `task-completed` is the one slug written **only after the user answers the Exit-Gate acceptance question (Accept, or explicit proceed-with-issues)** — never before the gate. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if finalization fails, do NOT append `task-completed` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["task-completed"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-performance.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                      | Max Attempts | Strategy     |
+| ------------------------- | ------------ | ------------ |
+| Completion (`task-completed`) | 0        | Summary only |
+
+## Exit Gate
+
+Present results, get user confirmation, then close the workflow (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill. **This acceptance is where the goal-performance wrapper's loop ends** (Accept = the wrapper proceeds to its own wrapper Exit Gate; any other option ends the loop with the standard handoff block).
+
+### Results box
+
+The results box from the Finalization step above IS the workflow-level results box — present it here as-is (single box, not two).
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — record `task-completed` (state write below), then print the closing guidance: the commit message template, the artifact set, and the next steps.
+- **Adjust** — re-run the affected earlier step (e.g., `/owflow:performance-implement <task-path>` for additional optimizations, or `/owflow:performance-verify <task-path>` for another verification round), 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-finalize <task-path>`) and end.
+
+**On Accept only**, perform the state write: append `task-completed` to `completed_phases` and set `task.status: completed`; bump `orchestrator.updated`; do NOT write a finalize slot under `performance_context.phase_summaries` (the template has no such slot — finalization is state-only). On failure: append `task-completed` to `failed_phases`, increment `auto_fix_attempts["task-completed"]`. Then re-read state + run `verify_template`. On **Adjust / Discuss / Stop here**, perform NO state write — the workflow stays resumable.
+
+### Next steps (after Accept)
+
+The workflow is finished; no further owflow step is required. All follow-ups are `optional` (post-completion work, none advance phases):
+
+- Run the application and verify the 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>"` — `optional` — captures optimization patterns as project standards; does not advance phases.
+- Commit the changes using the provided message template; open a PR. (Manual steps outside owflow.)
+
+Then STOP.

package/dist/skills/performance-implement/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: owflow:performance-implement
+description: Performance — executes the approved implementation plan via the implementation-plan-executor skill, then records implementation-done. Continues with performance-verify.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Performance Implement — Implementation (implementation-done)
+
+Work step of the performance workflow. Executes the optimization plan via the `implementation-plan-executor` skill, then records the implementation outcome in state. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/performance/` (e.g., `2026-10-02-api-latency`); resolve to its path.
+- **Description** — anything else (free text) is treated as a new performance task description: ask via `question` whether to start a fresh standard task at this step (mid-pipeline bootstrap) or route through `/owflow:performance <description>`; on decline, print the blocked block and STOP.
+- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Steps that must be completed first (in order), each with its command:
+   - Codebase & bottleneck analysis (`codebase-analysed`, `bottlenecks-identified`) → `/owflow:performance-analyze <task-path>`
+   - Requirements, specification & conditional audit (`spec-written`, `spec-audited`) → `/owflow:performance-spec <task-path>`
+   - Implementation planning (`plan-created`) → `/owflow:performance-plan <task-path>`
+2. List available performance-task identifiers (directories under `.owflow/tasks/performance/`) to resume from, if any.
+3. Hint: `Run /owflow:performance <description> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill | Where verified                                                    | Produced by                            |
+| ----------------------- | ----------------------------------------------------------------- | -------------------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml`                              | `/owflow:performance <desc>`           |
+| Spec approved           | `implementation/spec.md` exists                                   | `/owflow:performance-spec <task-path>` |
+| Plan approved           | `implementation/implementation-plan.md` exists                    | `/owflow:performance-plan <task-path>` |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `implementation-done`): `question` — create a fresh standard performance task starting at this step, or decline → print `No performance task found at <path>. Run /owflow:performance <description> to start a task from scratch.` and STOP.
+2. **Skip/resume**: if `implementation-done` is in `completed_phases` and `implementation/work-log.md` exists, backfill `performance_context.phase_summaries.implementation` from the work-log when it is still null, report the existing results, and route to the Exit Gate. If the work-log is missing → drop `implementation-done` and re-run the implementation step.
+3. **Prerequisite check (presence and content)**: `implementation/spec.md` AND `implementation/implementation-plan.md` exist. If missing → print the blocked block, then STOP:
+   - Steps that must be completed first: specification (`spec-written`) → implementation planning (`plan-created`).
+   - `Run /owflow:performance-spec and /owflow:performance-plan <task-path> first` (or `/owflow:performance-analyze <task-path>` for the missing earlier step).
+   - If no task exists yet: `Run /owflow:performance <description> to start a task from scratch.`
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+### Implementation (`implementation-done`, delegated)
+
+**Artifacts**: implemented optimizations, `implementation/work-log.md`
+
+> **ANTI-PATTERN — never implement directly. "Simple enough to code inline" is NOT a reason to skip delegation.**
+>
+> - ❌ "Let me implement this directly..." — STOP. Delegate to `implementation-plan-executor`.
+> - ❌ "This is simple enough to code inline..." — STOP. Simplicity is NOT a reason to skip delegation.
+
+1. **INVOKE NOW** (Skill tool — never the Task tool; this skill spawns its own subagents): Skill tool - `implementation-plan-executor`. Pass: task_path, task_description, `performance_context.task_characteristics`, `performance_context.bottleneck_priorities`, and relevant `performance_context.phase_summaries` (specification, bottleneck_analysis, planning). The skill manages its own subagents, incremental tests, plan checkboxes, and `implementation/work-log.md`. Its terminal **full test-suite run** is what makes the template default `skip_test_suite: true` causally safe — do not swap this engine.
+2. **SELF-CHECK**: Did you just invoke the Skill tool with `implementation-plan-executor`? Or did you start writing code yourself? If the latter, STOP immediately and invoke the Skill tool instead.
+3. **Append this skill's own slug** (replaces the monolith's re-acquire / POST-IMPLEMENTATION block): after the skill returns, re-read `orchestrator-state.yml` to confirm you are the orchestrator, then append `implementation-done` to `completed_phases` and extract a 1-2 sentence summary into `performance_context.phase_summaries.implementation` from `implementation/work-log.md` (task groups completed, files changed, test results, known issues).
+4. **State write**: bump `orchestrator.updated`. On failure: append `implementation-done` to `failed_phases`, increment `auto_fix_attempts["implementation-done"]`; partial progress stays documented in `implementation/work-log.md`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`implementation-done`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the implementation fails or its retries are abandoned, do NOT append to `completed_phases`; instead append the step's slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-performance.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                             | Max Attempts | Strategy                                                             |
+| -------------------------------- | ------------ | -------------------------------------------------------------------- |
+| Implementation (`implementation-done`) | 5      | Fix syntax, imports, tests; return to the executor for the failing group |
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ PERFORMANCE IMPLEMENT COMPLETE — <task name>
+
+**Task groups** — [completed / total]
+**Files changed** — [count + key files, 1-3 lines]
+**Tests** — [incremental + terminal full-suite results from the executor]
+**Known issues** — [deferred items / "none"]
+
+**Artifacts**
+
+- implemented optimizations
+- `implementation/work-log.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — implementation matches the plan; continue.
+- **Adjust** — re-work the affected task groups (fix code, re-run their tests), update state and work-log, re-present the results box.
+- **Discuss** — walk through implementation details (decisions made, files changed, deferred items) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:performance-implement <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:performance-verify <task-path>` — `required` before finalization: picks the additional verification checks and runs the verification pipeline. Remaining after: finalize.
+
+**Other options**:
+
+- `/owflow:goal-performance <task-path>` — `optional` shortcut: runs all remaining steps in one loop (verify → finalize)
+
+Then STOP.

package/dist/skills/performance-plan/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: owflow:performance-plan
+description: Performance — breaks the approved specification into a grouped, dependency-ordered implementation plan via delegation, then adds an execution-flow diagram. Continues with performance-implement.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Performance Plan — Implementation Planning (plan-created)
+
+Work step of the performance workflow. Breaks the approved optimization specification into grouped, dependency-ordered task groups via the `implementation-planner` agent, then adds an execution-flow diagram. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/performance/` (e.g., `2026-10-02-api-latency`); resolve to its path.
+- **Description** — anything else (free text) is treated as a new performance task description: ask via `question` whether to start a fresh standard task at this step (mid-pipeline bootstrap) or route through `/owflow:performance <description>`; on decline, print the blocked block and STOP.
+- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Steps that must be completed first (in order), each with its command:
+   - Codebase & bottleneck analysis (`codebase-analysed`, `bottlenecks-identified`) → `/owflow:performance-analyze <task-path>`
+   - Requirements, specification & conditional audit (`spec-written`, `spec-audited`) → `/owflow:performance-spec <task-path>`
+2. List available performance-task identifiers (directories under `.owflow/tasks/performance/`) to resume from, if any.
+3. Hint: `Run /owflow:performance <description> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill   | Where verified                                                                        | Produced by                              |
+| ------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- |
+| State file exists         | `<task-path>/orchestrator-state.yml`                                                  | `/owflow:performance <desc>`             |
+| Specification approved    | `spec-written` in `completed_phases` + `implementation/spec.md` exists                | `/owflow:performance-spec <task-path>`   |
+| Audit decision settled    | `options.spec_audit_enabled` non-null                                                 | `/owflow:performance-spec <task-path>`   |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `plan-created`): `question` — create a fresh standard performance task starting at this step, or decline → print `No performance task found at <path>. Run /owflow:performance <description> to start a task from scratch.` and STOP.
+2. **Skip/resume (artifacts before state)**: if `plan-created` is complete and `implementation/implementation-plan.md` exists, report the existing plan summary and route to the Exit Gate. If the file exists but its slug is missing, adopt it (append `plan-created`, backfill `performance_context.phase_summaries.planning` when still null) instead of re-running. A slug whose artifact is missing → drop the slug and re-run that step.
+3. **Prerequisite check (presence and content)**: `spec-written` in `completed_phases` AND `implementation/spec.md` exists — the spec must be user-approved before the planner is invoked — AND `options.spec_audit_enabled` is non-null (the audit decision is settled). If missing → print the blocked block, then STOP:
+   - Steps that must be completed first: specification and its audit decision (`spec-written`, audit settled).
+   - `Run /owflow:performance-spec <task-path> first` (or `/owflow:performance-analyze <task-path>` for the missing earlier step).
+   - If no task exists yet: `Run /owflow:performance <description> to start a task from scratch.`
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) and the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md).
+
+### Implementation Planning (`plan-created`, delegated)
+
+**Artifacts**: `implementation/implementation-plan.md`
+
+> **ANTI-PATTERN — never write the implementation plan yourself. "The optimization list is short" is NOT a reason to skip delegation.**
+>
+> - ❌ "Let me create the implementation plan..." — STOP. Delegate to `implementation-planner`.
+> - ❌ "I'll break this into optimization steps..." — STOP. Delegate to `implementation-planner`.
+
+1. **INVOKE NOW** (Task tool — never the Skill tool; this is an agent): Task tool - `implementation-planner` subagent. Pass (Pattern 7 — accumulated context): task_path, task_type="performance", task_description, spec_path (`implementation/spec.md`), `performance_context.task_characteristics`, `performance_context.bottleneck_priorities`, and relevant `performance_context.phase_summaries` (specification, bottleneck_analysis, codebase_analysis). Output: `implementation/implementation-plan.md`.
+2. **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.
+3. **Post-plan diagram refinement** (Skill, optional, content-preserving): Skill tool - `diagrams-mermaid` on `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. A declined or failed refinement is not a failure — note it in `performance_context.phase_summaries.planning`.
+4. **State write**: append `plan-created` to `completed_phases`; set `performance_context.phase_summaries.planning` (task-group count, step count, optimization sequence); bump `orchestrator.updated`. On failure: append `plan-created` to `failed_phases`, increment `auto_fix_attempts["plan-created"]`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`plan-created`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the step fails or its retries are abandoned, do NOT append to `completed_phases`; instead append the step's slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-performance.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                          | Max Attempts | Strategy                                          |
+| ----------------------------- | ------------ | ------------------------------------------------- |
+| Implementation Planning (`plan-created`) | 2  | Regenerate the plan with adjusted spec context    |
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ PERFORMANCE PLAN COMPLETE — <task name>
+
+**Task groups** — [N groups / M steps]
+**Optimization sequence** — [key dependency order]
+**Spec** — [approved spec summary in 1 line]
+**Diagram** — [added / skipped]
+
+**Artifacts**
+
+- `implementation/implementation-plan.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the plan is good; continue.
+- **Adjust** — regenerate the plan with the user's corrections, update state and artifacts, re-present the results box.
+- **Discuss** — walk through the plan's task groups, dependencies, or test strategy in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:performance-plan <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:performance-implement <task-path>` — `required` next: executes the plan via `implementation-plan-executor` (its terminal full-suite run is what keeps `skip_test_suite: true` safe). Remaining after: verify → finalize.
+
+**Other options**:
+
+- `/owflow:goal-performance <task-path>` — `optional` shortcut: runs all remaining steps in one loop (implement → verify → finalize)
+
+Then STOP.