owflow 0.2.0 → 0.4.2

package/dist/commands/work.md

@@ -1,5 +1,5 @@
 ---
-name: work
+name: owflow:work
 description: Unified entry point — auto-classifies tasks and routes to appropriate workflow. ALWAYS execute when invoked via slash command.
 ---
 
@@ -12,7 +12,7 @@ Auto-classifies tasks and routes to the appropriate workflow orchestrator. Suppo
 ## Usage
 
 ```bash
-/work [task description | task folder path | issue identifier]
+/owflow:work [task description | task folder path | issue identifier]
 ```
 
 ### Input Types
@@ -31,18 +31,18 @@ Auto-classifies tasks and routes to the appropriate workflow orchestrator. Suppo
 
 ```bash
 # Resume existing task
-/work ".owflow/tasks/development/2025-10-23-login-timeout"
-/work "2025-10-26-user-auth"
+/owflow:work ".owflow/tasks/development/2025-10-23-login-timeout"
+/owflow:work "2025-10-26-user-auth"
 
 # New task (auto-classifies)
-/work "Fix login timeout error on mobile devices"
-/work "Add user authentication with email/password"
-/work "Improve dashboard loading performance"
+/owflow:work "Fix login timeout error on mobile devices"
+/owflow:work "Add user authentication with email/password"
+/owflow:work "Improve dashboard loading performance"
 
 # From issue tracker
-/work "#456"
-/work "PROJ-123"
-/work "AB#789"
+/owflow:work "#456"
+/owflow:work "PROJ-123"
+/owflow:work "AB#789"
 ```
 
 ## How It Works
@@ -145,9 +145,9 @@ Use Skill tool:
 
 Examples:
 
-- Resume development: `skill: "development"` with `args: "--resume .owflow/tasks/development/2025-10-23-fix"`
-- Restart from phase: `skill: "development"` with `args: "--resume .owflow/tasks/development/2025-10-26-auth --from=verify"`
-- Fresh attempts: `skill: "migration"` with `args: "--resume .owflow/tasks/migrations/2025-10-20-redux --reset-attempts"`
+- Resume development: `skill: "owflow:development"` with `args: "--resume .owflow/tasks/development/2025-10-23-fix"`
+- Restart from step: `skill: "owflow:development"` with `args: "--resume .owflow/tasks/development/2025-10-26-auth --from=verification-done"` (dev tasks use descriptive step slugs in `completed_phases`; performance and migration are the remaining `phase-N` holdouts — research uses the descriptive slugs in `templates/orchestrator-state-research.yml`)
+- Fresh attempts: `skill: "owflow:migration"` with `args: "--resume .owflow/tasks/migrations/2025-10-20-redux --reset-attempts"`
 
 ### Step 3: Classify & Route New Task
 
@@ -194,9 +194,9 @@ Use Skill tool:
 
 **Routing examples:**
 
-- development (92%): `skill: "development"` with `args: "Fix login timeout error"`
-- development (88%): `skill: "development"` with `args: "Add filtering to user table"`
-- performance (95%): `skill: "performance"` with `args: "Optimize slow dashboard queries"`
+- development (92%): `skill: "owflow:development"` with `args: "Fix login timeout error"`
+- development (88%): `skill: "owflow:development"` with `args: "Add filtering to user table"`
+- performance (95%): `skill: "owflow:performance"` with `args: "Optimize slow dashboard queries"`
 
 ---
 
@@ -224,9 +224,9 @@ Then route to selected workflow using Skill tool.
 ```
 Display:
 "Task cancelled. You can:
-- Run /work again when ready
+- Run /owflow:work again when ready
 - Use specific workflow commands directly:
-  /development, /performance, etc."
+  /owflow:development, /owflow:performance, etc."
 ```
 
 ---
@@ -235,10 +235,10 @@ Display:
 
 | Workflow Type | Skill         | Args                                                |
 | ------------- | ------------- | --------------------------------------------------- |
-| development   | `development` | `--resume [path] [--from=PHASE] [--reset-attempts]` |
+| development   | `development` | `--resume [path] [--from=<slug>] [--reset-attempts]` |
 | performance   | `performance` | `--resume [path] [--from=PHASE]`                    |
 | migration     | `migration`   | `--resume [path] [--from=PHASE]`                    |
-| research      | `research`    | `--resume [path] [--from=PHASE]`                    |
+| research      | `research`    | `--resume [path] [--from=<slug>]`                   |
 
 ---
 
@@ -246,7 +246,7 @@ Display:
 
 ### With Task Classifier
 
-The `/work` command delegates classification to the task-classifier subagent via Task tool, which:
+The `/owflow:work` command delegates classification to the task-classifier subagent via Task tool, which:
 
 - Fetches issue details from GitHub/Jira/Azure DevOps (via MCP, CLI tools, or WebFetch)
 - Analyzes codebase context for better classification

package/dist/configuration/skills-config.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { PLUGIN_ROOT } from "../constants.js";
+import { PLUGIN_ROOT } from "../utils/plugin-info.js";
 export const configureSkills = (config) => {
     config.skills = config.skills || {};
     config.skills.paths = config.skills.paths || [];

package/dist/index.js

@@ -4,7 +4,9 @@
  */
 import path from "node:path";
 import fs from "node:fs";
+import { PLUGIN_VERSION } from "./utils/plugin-info.js";
 import { verify_template } from "./tools/verify_template.js";
+import { fork_task } from "./tools/fork_task.js";
 import { rereadOrchestratorState } from "./hooks/session-compaction.js";
 import { guardAgainstDestructiveActions } from "./hooks/before-tool.js";
 import { configureSkills } from "./configuration/skills-config.js";
@@ -16,13 +18,14 @@ const OwflowPlugin = async ({ $, directory }) => {
     return {
         tool: {
             verify_template,
+            fork_task,
         },
         /**
          * Register owflow's skills, commands, and agents so OpenCode discovers
          * them without requiring manual config file edits.
          */
         config: async (config) => {
-            console.log("[owflow] Starting plugin installation...");
+            console.log(`[owflow] Starting plugin installation (v${PLUGIN_VERSION})...`);
             let typedConfig = config;
             // Get small_model config for alias resolution
             // Try from config parameter first, fallback to reading opencode.json
@@ -45,7 +48,7 @@ const OwflowPlugin = async ({ $, directory }) => {
             configureCommands(typedConfig);
             configureAgents(typedConfig, smallModel);
             config = typedConfig;
-            console.log("[owflow] Plugin installation completed successfully.");
+            console.log(`[owflow] Plugin installation completed successfully (v${PLUGIN_VERSION}).`);
         },
         "experimental.session.compacting": async (input, output) => {
             await rereadOrchestratorState(directory, output);

package/dist/skills/agents-md-generator/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: owflow:agents-md-generator
+description: >
+  Generate an AGENTS.md onboarding document for AI coding agents working in
+  this repository. Inspects the repo (package manifest, README, scripts,
+  lint/test config, layout, commit history) and writes a concise contributor
+  guide titled "Repository Guidelines". Use when the user invokes
+  /owflow:agents-md-generator, asks to "create AGENTS.md", "write an agent onboarding
+  doc", "generate contributor guide for agents", or similar. The output is
+  optimized to be small, precise, reference-heavy, and ordered with critical
+  rules at the top — so a future agent reads it once and stays unblocked.
+argument-hint: "[directory or file path]"
+user-invocable: true
+---
+
+# AGENTS.md generator
+
+Produce an `AGENTS.md` that serves as an onboarding document for AI coding agents in this repository. The file is short, specific to the repo, and structured so the most important rules appear first.
+
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) (confirm-or-revise exception — see the [Confirm-or-Revise Exception](../orchestrator-framework/references/confirm-or-revise-exception.md)).
+
+## Entry Gate
+
+The input resolution below IS this skill's entry gate:
+
+## Input resolution
+
+`$ARGUMENTS` is optional. It may be:
+
+- empty → write to `AGENTS.md` at the repo root.
+- a directory path → write `AGENTS.md` inside that directory (useful for nested per-area guides, e.g. `src/api/AGENTS.md`).
+- a full file path ending in `.md` → write there verbatim.
+
+If the target file already exists, do **not** silently overwrite. Switch to the update flow under "Procedure → Update path". The default behavior is a surgical edit that preserves still-valid content, not a rewrite.
+
+## Scope detection — repo-level vs. directory-level
+
+The same skill can produce two materially different documents depending on **where** it's invoked from. Detect the scope before discovery so the draft targets the right altitude.
+
+1. **Resolve the target directory.** If `$ARGUMENTS` names a path, that's the target. Otherwise it's the current working directory (`pwd`).
+2. **Compare against the repo root.** Run `git rev-parse --show-toplevel`. If the target directory equals the repo root → **repo-level scope**. If it's a subdirectory (e.g. `src/components/`, `packages/api/src/routes/`, `app/api/`) → **directory-level scope**.
+
+**Repo-level scope.** Follow the procedure and "Output structure" below as written — the document is a high-level onboarding guide (project structure, build commands, CI gate, commit conventions, etc.).
+
+**Directory-level scope.** Drop the repository-onboarding framing entirely. The reader already knows the repo; they need the rules of _this_ directory. Reorient discovery and output:
+
+- **Discover locally first.** Inspect the files actually living next to the target: sibling source files, the nearest `index.ts`/`Application.java`, co-located tests, the parent directory's README if any, and any nested config (e.g. `tsconfig.json`, `.eslintrc`, `application.yml`, route manifests) that overrides repo-level defaults. Only consult repo-root docs (`README.md`, `AGENTS.md`) to **resolve conflicts** or pull a single canonical `@`-reference — not as the primary source.
+- **Infer the local pattern by reading siblings.** What shape do existing files in this directory take? Component file layout, naming (`PascalCase.tsx`, `camelCase.ts`, `*.handler.ts` for Node.js; `PascalCase.java`, `*Controller.java`, `*Service.java` for Spring), default vs. named exports (Node.js) or package-private vs. public visibility (Java), prop/argument conventions, where types/styles/tests live relative to the unit, error-handling idioms, what gets imported from where. The AGENTS.md captures the convention you observed, not generic advice.
+- **Reframe sections around the local unit.** Replace repo-level sections with directory-relevant ones. Useful defaults (adapt to what's there):
+  - _Adding a new \<unit\>_ — concrete steps for the dominant artifact in this directory (component, route handler, migration, hook, worker, etc.), citing one existing sibling as the reference shape via `@./<sibling-file>`.
+  - _File layout & naming_ — naming pattern, co-location rules (test next to source? styles inline? types in a sibling file?), barrel-export policy if one exists.
+  - _Local conventions_ — props/args shape, state/data-flow rules, allowed imports (and forbidden ones — e.g. "components in this directory must not import from `src/server/`"), accessibility or i18n rules visible in siblings.
+  - _Testing this unit_ — the test pattern used by neighbors, how to run just this directory's tests.
+  - _Tripwires_ — directory-specific "never do X" rules visible in siblings or a nearby AGENTS.md fragment.
+- **Skip the repo-level sections.** No top-level project structure map, no monorepo package list, no global build/CI overview, no commit-convention recap — those belong in the root `AGENTS.md`. If the reader needs them, link once: `See @AGENTS.md at the repo root for repo-wide rules.`
+- **Length budget shrinks.** Aim for **120–250 words** of body for directory-level guides; the surface area is smaller, and padding here is worse than at the root.
+
+The Quality guards still apply, with one substitution: guard 5 ("Critical rules first") becomes "Local rules first" — the highest-leverage line is the one that prevents a wrong-shaped sibling from landing in this directory.
+
+## Interactive prompts
+
+Whenever the procedure says _"ask the user"_, use the `question` tool with labeled options. If a step requires free-form input, ask via a plain conversational message instead.
+
+## Parallel research via subagents (optional)
+
+If the repo is large enough to benefit (roughly >20 top-level files), use the `Task` tool to fan out independent reads in **one batched call** (multiple subagents in a single invocation, not sequentially):
+
+- one subagent reads `README.md`, existing `AGENTS.md`, top-level `docs/` index
+- one inspects the manifest + lint/format/type configs
+- one inspects test config + CI workflows
+- one runs the git-history queries via `Bash` (commit conventions, last-touch on AGENTS.md, diff range since `LAST_TOUCH`)
+
+Each subagent should return a **short structured report** (≤200 words: facts only, with `path:line` citations) — not a full file dump. The main agent then synthesizes the AGENTS.md from those reports.
+
+**Skip the fan-out if** the repo is small (under ~20 top-level files), or you've already loaded most of the relevant files in the current context.
+
+**Do not delegate** the synthesis step (drafting and Quality-guard checks). Drafting requires holding the full picture in one context to enforce the 200–400 word budget, ordering, and `@`-reference policy.
+
+## What this skill does NOT do
+
+- Does not invent project facts. Every claim in the output must trace back to a file, command, or commit you actually inspected.
+- Does not embed multi-line code or config snippets. Use `@`-references to canonical files instead (e.g. `@package.json`, `@tsconfig.json`, `@docs/architecture.md`).
+- Does not write generic engineering advice ("write clean code", "follow best practices", "handle errors properly"). If a rule cannot be checked against a diff, drop it or rewrite it concretely.
+- Does not restate framework defaults, language tutorials, or anything the AI assistant already knows from training. Only project-specific knowledge earns a line.
+- Does not edit unrelated files. The skill writes one markdown file and stops.
+
+## Procedure
+
+**First, branch on existence.** Before discovering anything else, check whether the resolved target path already exists (use `Read` or `Glob`). If it does, follow the **Update path** below. If not, follow the **Create path**.
+
+### Create path
+
+1. **Discover.** Read in this order, skipping what doesn't exist:
+   - `README.md`, existing `AGENTS.md`, top-level `docs/` index.
+   - Manifest: `package.json` (scripts, workspaces, engines) for Node.js, or `pom.xml` / `build.gradle` (plugins, dependencies, profiles) for Spring Java.
+   - Lint/format/type configs: `.eslintrc*`, `oxlint*`, `biome.json`, `tsconfig.json`, `.editorconfig` for Node.js; `checkstyle.xml`, `spotbugs-exclude.xml`, `.editorconfig` for Spring Java.
+   - Test config: `vitest.config.*`, `jest.config.*`, `playwright.config.*`, `*.test.*` locations for Node.js; `src/test/`, `*Test.java`, `*IT.java`, Surefire/Failsafe plugin config in `pom.xml` for Spring Java.
+   - CI: `.github/workflows/*` (one or two files; just enough to know the gate).
+   - Layout: top two levels of the tree (use `Glob` or `Bash`), workspace package list if monorepo.
+   - History: `git log --oneline -n 30` to learn commit-message conventions; `git config remote.origin.url` for PR target.
+2. **Extract.** From discovery, write down for yourself:
+   - The 1–3 commands an agent runs most often (build, test, lint, dev server).
+   - The handful of conventions a reviewer would actually flag in PR review (naming patterns, file layout, commit prefix style).
+   - Any hard "never do X" rule visible in `AGENTS.md`, README, or CI validators.
+   - Where deeper docs live, so the AGENTS.md can point to them instead of duplicating.
+3. **Draft.** Write the file per "Output structure" below.
+4. **Self-check before writing.** Run the five guards in "Quality guards". If any fail, revise the draft, do not write yet.
+5. **Write.** Use the `Write` tool to create the file at the resolved path. Confirm the path and word count back to the user.
+
+### Update path
+
+Triggered when the target file already exists. The default is a **surgical edit**: keep what's still true, fix what's stale, fill what's missing, and remove what's been deleted from the repo. Do not rewrite from scratch unless the user asks.
+
+1. **Inventory the existing file.**
+   - Read the full file.
+   - List its current sections (H1/H2/H3 headings) and the rules/commands under each.
+   - Extract every `@`-reference and every relative path or filename it cites.
+
+2. **Date the file via git.**
+   - `git log --follow --format="%h %ad %s" --date=short -- <path>` — full edit history of the file.
+   - Note the **last-touched commit hash** and date. Call this `LAST_TOUCH`.
+   - If the file is untracked (`git ls-files --error-unmatch <path>` fails), treat it as freshly authored: skip git-diff steps and run the full Create path discovery, but still preserve any obviously project-specific content the user wrote.
+
+3. **Diff repo state since `LAST_TOUCH`.** Use these checks (skip any whose target the file doesn't reference):
+   - `git diff --stat LAST_TOUCH..HEAD -- README.md AGENTS.md docs/` — has top-level documentation moved or changed?
+   - `git diff LAST_TOUCH..HEAD -- package.json pom.xml build.gradle` (whichever exists) — for **scripts**, **dependencies**, **engines**, **workspaces**. Pay closest attention to the `scripts` block (Node.js) or plugin/dependency changes (Maven/Gradle): renamed/added/removed scripts or build targets are the most common source of stale AGENTS.md content.
+   - `git diff LAST_TOUCH..HEAD -- .eslintrc* oxlint* biome.json tsconfig.json .editorconfig checkstyle.xml spotbugs-exclude.xml` — has the lint/format/type toolchain changed?
+   - `git diff LAST_TOUCH..HEAD -- vitest.config.* jest.config.* playwright.config.*` (Node.js) or `pom.xml` Surefire/Failsafe sections (Spring Java) — has the test stack or layout changed?
+   - `git diff --stat LAST_TOUCH..HEAD -- .github/workflows/` — has the CI gate changed?
+   - `git log --oneline LAST_TOUCH..HEAD -- <commit-conventions-relevant-area>` and `git log --oneline -n 30` — does the commit-style observation in the file still match recent history?
+   - For each `@`-reference and path the file mentions: use `Read` or `Glob` to check whether the path still exists. If it no longer exists or has been renamed, that line is stale.
+
+4. **Classify each line of the existing file** into one of four buckets:
+   - **KEEP** — still accurate; cited file/command/path still exists with the same shape.
+   - **UPDATE** — directionally right but a detail is stale (renamed script, moved path, changed tool, version bump). Note the exact replacement.
+   - **REMOVE** — the underlying file/command/convention no longer exists, or the rule has been contradicted by a newer source (`AGENTS.md`, README) that you trust more.
+   - **MISSING** — not currently in the file but should be (new top-level package, new required script, new "never do X" rule landed via CI validator, new commit convention visible in `git log`).
+     Keep this classification as a short table you can show the user. Cite `path:line` (in the existing AGENTS.md) for every UPDATE/REMOVE entry, and cite the source-of-truth path (e.g. `package.json:42`) for every UPDATE/MISSING entry.
+
+5. **Confirm scope before editing.** Use the `question` tool with these options:
+   - **Apply the proposed updates** — execute the UPDATE/REMOVE/MISSING list as targeted edit operations; KEEP lines are not touched.
+   - **Show me the change list first** — print the classification table to chat, no edits, then ask again.
+   - **Full regenerate** — discard the existing file and run the Create path. Use only when the existing file is mostly stale or the user explicitly wants a clean slate.
+   - **Cancel** — no changes.
+
+6. **Edit surgically.** For the "Apply" choice, prefer multiple targeted `Write` calls (one per UPDATE/REMOVE/MISSING entry) over a single full-file rewrite. This preserves authorial voice in KEEP sections and produces a reviewable diff. If section ordering violates the "critical rules first" guard from the Quality guards and the user approved updates, you may move whole sections — but only sections, never re-author rule wording silently.
+
+7. **Re-run the Quality guards** on the updated file. The same five gates apply. If a guard now fails because of the update (e.g. body grew past 400 words after MISSING additions), trim KEEP content that has become low-leverage rather than dropping the new MISSING content.
+
+8. **Report.** Confirm path, new word count, and a one-line summary of what changed in each bucket (e.g. _"3 updated, 1 removed, 2 added; section order unchanged"_).
+
+## Output structure
+
+The document title is `# Repository Guidelines`. Target length is **200–400 words** of body content. Use Markdown headings for structure. Adapt sections to what the repo actually has — omit any section that would be empty or speculative.
+
+Order sections by **leverage to a fresh agent**, not by tradition. Critical rules and the most-used commands go first; nice-to-know context goes last. A useful default ordering, when in doubt:
+
+1. **Hard rules / Agent-specific instructions** — the "never do X" list and any tripwires (only include if the repo actually has them; otherwise skip and let conventions carry the weight).
+2. **Project Structure & Module Organization** — top-level directory map, where source/tests/assets live, monorepo package list if relevant. Reference deeper docs with `@path/to/doc.md` instead of inlining them.
+3. **Build, Test, and Development Commands** — the 3–6 commands an agent will actually run, each with a one-line purpose. Prefer `pnpm <script>` (Node.js) or `./mvnw <goal>` / `./gradlew <task>` (Spring Java) over raw tool invocations when the project wraps them.
+4. **Coding Style & Naming Conventions** — indentation, language version, naming patterns (with one short example pattern, not a code block), and the lint/format tools that enforce them.
+5. **Testing Guidelines** — framework, where tests live, naming pattern, how to run a single test, any coverage threshold the repo actually checks.
+6. **Commit & Pull Request Guidelines** — the convention observed in `git log` (e.g. Conventional Commits prefixes seen), PR description expectations, required CI checks.
+7. **Security & Configuration Tips** _(optional)_ — secrets handling, env-file location, validator scripts that fail CI.
+8. **Architecture Overview** _(optional, only if not already covered by a `@`-reference)_ — 3–6 bullets max; otherwise link out.
+
+Open the file with one short paragraph (1–2 sentences) naming what the project is and the primary stack — enough that an agent landing in the repo for the first time has a frame. No mission statements, team intros, or values.
+
+## Quality guards (run before performing a file write operation)
+
+Each guard is a hard gate. If any fails, revise the draft.
+
+1. **Length.** Body is 200–400 words. Under 200 means you skipped specifics; over 400 means you padded or inlined what should be a reference.
+2. **No multi-line snippets.** No fenced code blocks longer than a single command line. Replace example components / configs / migrations with `@path/to/file`. Short single-line command examples (`pnpm test`, `git rebase main`) are fine.
+3. **Every rule is checkable.** Re-read each sentence and ask: _could a reviewer flag a diff against this?_ If not, rewrite it with a concrete pattern, threshold, or named tool. Strike phrases like "clean code", "best practices", "modern patterns", "be consistent", "handle errors properly", "keep it simple".
+4. **No redundant knowledge.** Strike any line you could have written without opening the repo. Framework defaults, language tutorials, and definitions of common terms do not earn a slot. If a rule duplicates `README.md` / `package.json` / lint config, replace it with `@README.md` / `@package.json` / `@.eslintrc.json`.
+5. **Critical rules first.** The first third of the file must contain the highest-stakes rules and the most-used commands. If the only "never do X" rule is at the bottom, move it up. If the top is welcome/mission/values, cut it.
+
+## Tone
+
+Professional, instructional, terse. Second person ("Run `npm test` before pushing" or "Run `./mvnw verify` before pushing") or imperative ("Place new handlers in `src/api/<feature>/`" or "Place new controllers in `src/main/java/<package>/controller/`"). No marketing voice, no emojis, no decorative dividers.
+
+## After writing (Exit Gate — confirm-or-revise form)
+
+Per the shared contract's exception for no-follow-up skills, present the results box, then ask only a confirm-or-revise question (no unsolicited follow-up suggestions):
+
+**Results box**:
+
+```markdown
+## ✅ AGENTS.MD COMPLETE — <path>
+
+**Scope** — [repo-level / directory-level]
+**Words** — [<word count> body words]
+**Sections** — [<1-line section order summary>]
+
+**Written** — `<path>`
+```
+
+Report to the user:
+
+- the file path written,
+- the body word count,
+- a one-line summary of the section order chosen.
+
+**Results-acceptance question** — use `question` — "Is the document correct?" with options:
+
+- **Accept** — keep it. Reminder (always print with or without acceptance): _test the file by running a real task with a fresh agent session — onboarding docs only prove themselves on the next run._
+- **Adjust** — user specifies changes (trim, reorder, re-shape a section); apply them surgically, re-run the Quality guards, re-present the results box.
+- **Discuss** — justify a specific rule or citation (its file source); then re-ask.
+- **Stop here** — keep the file as written; nothing further at this time.
+
+After the user's response, stop. Do not propose further follow-ups unless the user asks.
+
+## Edge cases
+
+- **No `README.md` and no manifest detected.** Stop and tell the user the repo looks empty or unfamiliar; ask for a one-paragraph project description before drafting.
+- **Monorepo with per-package READMEs.** Write a root `AGENTS.md` that lists packages and `@`-references each package's README, rather than duplicating per-package detail. Suggest nested `packages/<name>/AGENTS.md` for any package with rules that materially differ.
+- **Existing rich `AGENTS.md` in the repo.** Treat it as authoritative source material. The new `AGENTS.md` should be a tighter distillation that points back to `@AGENTS.md` for depth, not a verbatim copy.
+- **Existing `AGENTS.md` was edited by hand after its last commit.** `git diff HEAD -- <path>` will show uncommitted changes. Read those changes first and treat them as KEEP unless they directly contradict a CI-enforced rule — the user is mid-edit and you must not clobber in-flight work.
+- **`LAST_TOUCH` is the initial commit of the repo.** Diff range becomes `LAST_TOUCH..HEAD` with no useful signal. Fall back to inspecting current repo state vs. the file's claims, line by line, without the git-diff shortcut.
+- **File exists but is empty or a stub.** Skip the Update path — run the Create path and overwrite, since there is no authorial content to preserve.
+- **Repo with no commit history (`git log` empty).** Skip the commit-conventions section rather than guessing; note in the PR section that the convention is to be defined.
+- **Polyglot repo (e.g. Node.js frontend + Spring Java backend).** Pick the dominant stack by file count for the "Build/Test/Dev" section; mention the secondary stack only if it has its own commands an agent will need. For a typical full-stack repo, cover both `package.json` scripts and Maven/Gradle goals.

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

@@ -1,5 +1,5 @@
 ---
-name: codebase-analyzer
+name: owflow: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
 ---

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

@@ -0,0 +1,115 @@
+---
+name: owflow:dev-analyze
+description: Development — codebase analysis with clarifications, then gap analysis with scope decisions. First work phase of the development workflow.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Dev Analyze — Codebase & Gap Analysis (codebase-analysed, gap-analysed)
+
+Work phase of the development workflow. Runs codebase exploration, requirements clarification, gap analysis, and scope decisions for an existing development task. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related entry points: `/owflow:development` (assisted mode), `/owflow:goal-development` (autonomous mode). Both produce the same state; you may mix them freely.
+
+## Entry Gate
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/development/` (e.g., `2026-01-12-my-task`); resolve to its path.
+- 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 phase. Everything else requires it.
+  2. List available dev-task identifiers (directories under `.owflow/tasks/development/`) to resume from, if any.
+  3. Hint: `Run /owflow:development <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:development <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 development task starting at this step, or decline → print `No development task found at <path>. Run /owflow:development <description> to start a task from scratch.` and STOP.
+2. **Skip/resume**: if `codebase-analysed` is in `completed_phases`, skip that part. If `gap-analysed` is in `completed_phases`, the whole skill is done — report existing results and route to the Exit Gate.
+
+## 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`)
+
+1. Skill tool - `codebase-analyzer`. Pass: task description (`task.description`), task_path, risk-relevant state, `project_doc_paths` from state, research/quick-reference context if present in state.
+2. Direct - use `question` for max 5 critical clarifying questions. Save to `analysis/clarifications.md`; set `task_context.clarifications_resolved`.
+3. **State write**: append `codebase-analysed` to `completed_phases`; update `task_context.risk_level`, `task_context.clarifications_resolved`, `phase_summaries.codebase_analysis`; 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).
+
+### Gap Analysis & Scope (`gap-analysed`)
+
+1. Task tool - `gap-analyzer` subagent. Pass: task_path, risk level, codebase summary, key files, clarifications, `project_doc_paths`.
+2. **Extract structured data from the result** (this gates later phases — do not summarize only):
+   - Read `task_characteristics` (5 fields: `has_reproducible_defect`, `modifies_existing_code`, `creates_new_entities`, `involves_data_operations`, `ui_heavy`) → write to `task_context.task_characteristics`
+   - Read `risk_level` → `task_context.risk_level`
+   - Write 1-2 sentence summary to `phase_summaries.gap_analysis`
+   - **SELF-CHECK**: re-read `orchestrator-state.yml` and verify the 5 characteristic values match the gap-analyzer output.
+3. **Decision gate** (mandatory): if `decisions_needed.critical` or `decisions_needed.important` is non-empty → `question` (one per critical; batch important into multi-select). If empty, note "No scope decisions needed" in state.
+4. Save scope clarifications to `analysis/scope-clarifications.md` (conditional).
+5. **Optional phase defaults**: `ui_heavy: true` → `options.e2e_enabled: true` + `options.user_docs_enabled: true`; `creates_new_entities: true` → `options.user_docs_enabled: true`. Command flags in state (`options`) already set override these.
+6. **State write**: append `gap-analysed` to `completed_phases`; update `task_context.task_characteristics`, `task_context.risk_level`, `phase_summaries.gap_analysis`; record decision-gate outcome (or "No scope decisions needed") in `task_context.gaps`; apply option defaults to `options.*`; bump `orchestrator.updated`. On failure: append `gap-analysed` to `failed_phases`, increment `auto_fix_attempts["gap-analysed"]`. Then re-read state + run `verify_template`.
+
+**ANTI-PATTERN**: Do NOT override `ui_heavy` with your own complexity judgment ("no new screens needed, just..."). It is a gap-analyzer signal.
+
+## State Update Convention (per step)
+
+Apply after EVERY phase/step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (e.g. `codebase-analysed`, `gap-analysed`) 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-development.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.
+
+## 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
+## ✅ DEV ANALYZE COMPLETE — <task name>
+
+**Task type** — [detected type]
+**Risk level** — [risk_level from state]
+**Characteristics** — [key characteristics — TDD gate, E2E, user docs]
+**Scope decisions** — [decisions made / "none needed"]
+
+**Artifacts**
+
+- `analysis/codebase-analysis.md`
+- `analysis/clarifications.md`
+- `analysis/gap-analysis.md`
+- `analysis/scope-clarifications.md` [conditional]
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — analysis is good; continue.
+- **Adjust** — re-run only the affected part (clarifications, gap analysis, or scope decisions), update state and artifacts, re-present the results box.
+- **Discuss** — walk through a specific result (risk level rationale, characteristics, scope decisions) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:dev-analyze <task-path>`) and end.
+
+### Next steps (after Accept)
+
+Read `task_context.task_characteristics` from state and print the suggested command with annotations (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- `has_reproducible_defect: true` → `→ /owflow:dev-tdd-red <task-path>`
+  What: writes a failing test that reproduces the defect — `required` before the spec when a reproducible defect exists; the test becomes the spec's acceptance criterion.
+- otherwise → `→ /owflow:dev-spec <task-path>`
+  What: turns the analysis into a user-approved specification — `required` next phase. There is no shorter alternative path: spec → plan → implement → verify → finalize.
+
+**Other options**:
+
+- `/owflow:dev-spec --quick <task-path>` — `optional` condensed alternative: writes the condensed spec directly on the fly (no specification-creator subagent; audit skipped) instead of the full requirements/spec flow
+- `/owflow:goal-development <task-path>` — `optional` shortcut: runs all remaining phases in one loop (red gate if flagged → spec → plan → implement → verify → finalize)
+- `/owflow:dev-spec <task-path>` — `optional` — skips the TDD gate manually (not recommended for reproducible defects; remaining plan unchanged: plan → implement → verify → finalize)
+
+Then STOP.