@workflow-manager/runner 0.1.0 → 0.3.0

package/skills/commit-discipline/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: commit-discipline
+description: >
+  Load this skill before staging commits or opening a pull request in
+  workflow-manager. Enforces Conventional Commits, focused diffs, a clean
+  rebase onto origin/main, and PR descriptions that link to the work.
+type: core
+applies_to:
+  - ".git/**"
+  - "**/*"
+---
+
+# Commit Discipline
+
+Use this skill at the moment you are about to `git add`, `git commit`, or `gh pr create`. It encodes how this repo expects commits and PRs to look so that history stays readable and release tooling (release-please, changelogs) keeps working.
+
+## When to use this skill
+
+Load it when you are about to:
+
+- Stage changes for commit.
+- Author a commit message.
+- Rebase onto `origin/main` before opening a PR.
+- Open or update a pull request.
+
+Skip it for purely exploratory commands that do not touch git state.
+
+## Conventional Commits
+
+This repo uses Conventional Commits. The release tooling (`release-please-config.json`) reads commit subjects to decide version bumps and changelog entries. Format:
+
+```
+<type>(<optional-scope>): <imperative summary>
+```
+
+Allowed `type` values:
+
+- `feat` — user-visible new functionality.
+- `fix` — user-visible bug fix.
+- `perf` — performance improvement with no behavior change.
+- `refactor` — internal restructuring, no behavior change, no new feature.
+- `docs` — documentation only.
+- `test` — tests only.
+- `build` — build system, packaging, dependencies.
+- `ci` — CI configuration only.
+- `chore` — repo plumbing that does not fit the above and has no user impact.
+- `revert` — reverts a previous commit; reference the reverted SHA.
+
+Rules:
+
+- Subject in the imperative mood, no trailing period, max 72 chars.
+- Use a scope when the change is localized (e.g., `feat(cli): ...`, `fix(parser): ...`, `feat(remote-registry): ...`).
+- Use `!` for breaking changes (e.g., `feat(cli)!: rename --token to --auth-token`) AND include a `BREAKING CHANGE:` footer explaining the migration.
+- Body (optional) explains _why_, not _what_; reference issues/PRs by number.
+
+## Commit hygiene
+
+- One logical change per commit. Do not bundle unrelated edits.
+- Never commit secrets, `.env*` files, real tokens, generated `dist/` output (unless explicitly requested), `node_modules/`, or local Supabase data.
+- Never amend or force-push commits that already exist on `main`. Force-push to feature branches is allowed only with `--force-with-lease`.
+- If pre-commit / pre-push hooks fail, fix the underlying issue. Do not bypass with `--no-verify` unless the user explicitly asks.
+
+## Before opening a PR
+
+Inside the feature worktree:
+
+```bash
+git fetch origin
+git rebase origin/main
+bun run lint
+bun test
+bun run build
+```
+
+Plus the conditional scripts from `repo-hygiene` / `doc-sync` when applicable.
+
+If the rebase produces conflicts you cannot confidently resolve, stop and surface them to the user instead of force-pushing through them.
+
+## PR description template
+
+Open PRs against `main` with a description that contains:
+
+1. **Summary** — 1–3 bullets describing the change in user-visible terms.
+2. **Why** — link to the issue, spec, or user request driving the change.
+3. **How** — short note on the approach; call out anything non-obvious.
+4. **Validation** — list the exact commands you ran and that they passed (lint, test, build, plus any conditional ones).
+5. **Docs** — link to the doc files updated, or state explicitly "no user-visible behavior changed".
+6. **Risk / rollout** — call out feature flags, migration steps, or follow-ups.
+
+Example title:
+
+```
+feat(cli): add `wfm pull --output` flag for redirecting fetched workflows
+```
+
+## Anti-patterns to refuse
+
+- Subjects like `update stuff`, `wip`, `fix things`, `address review`.
+- Squashing unrelated commits together to "clean up history" right before merge.
+- Pushing to `main` directly.
+- Opening a PR with failing CI and asking reviewers to "ignore the red".
+- Mixing a refactor and a behavior change in the same commit.
+
+## Definition of done
+
+- Every commit subject is a valid Conventional Commit.
+- Branch is rebased on the latest `origin/main`.
+- All required scripts (lint, test, build, plus conditional ones) passed locally.
+- PR description follows the template and links updated docs.

package/skills/doc-sync/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: doc-sync
+description: >
+  Load this skill whenever a change affects user-visible behavior in
+  workflow-manager: CLI flags, command output, workflow schema, public
+  TypeScript types, adapters, the remote registry surface, or environment
+  variables. Ensures README, doc/, AGENTS.md, and in-CLI help stay in sync.
+type: core
+applies_to:
+  - "src/index.ts"
+  - "src/parser.ts"
+  - "src/engine.ts"
+  - "src/types.ts"
+  - "src/remote/**"
+  - "apps/remote-registry/**"
+  - "doc/**"
+  - "README.md"
+  - "AGENTS.md"
+---
+
+# Doc Sync
+
+Use this skill to keep documentation honest. In this repo, documentation is part of the product surface — the CLI is published, workflows are shared via the remote registry, and the docs site is built from `doc/`. Out-of-date docs are a bug.
+
+## When to use this skill
+
+Load it whenever the change does any of the following:
+
+- Adds, removes, or renames a CLI command, flag, or argument in `src/index.ts`.
+- Changes workflow schema, defaults, or validation rules in `src/parser.ts` or `src/types.ts`.
+- Changes engine semantics (approvals, retries, rollback, restart, snapshot shape) in `src/engine.ts`.
+- Adds or changes an adapter (`mock`, `opencode`, `codex`, `claude-code`, future adapters).
+- Changes remote registry behavior in `src/remote/**` or `apps/remote-registry/**`.
+- Introduces or renames an environment variable or required local service.
+- Bumps a public type or contract referenced by docs or other packages.
+
+If none of the above is true, this skill is not needed.
+
+## Required updates by change type
+
+| Change | Update |
+| --- | --- |
+| New / renamed CLI command or flag | Usage text in `src/index.ts`, `README.md` Quickstart and CLI section, the matching `doc/` page, and the man page source if behavior is reflected there. |
+| Workflow schema change | `README.md` schema section, the relevant page under `doc/guide/` or `doc/reference/`, plus the `workflow-manager-cli` skill checklist if authoring rules shift. |
+| Engine semantics change | The corresponding `doc/` engine page and any example workflows in `example-workflow.{md,json}` that no longer demonstrate the new behavior accurately. |
+| Adapter added or changed | List of supported adapters in `AGENTS.md`, `README.md`, and `doc/`. The `workflow-manager-cli` skill must also list it. |
+| Remote registry change | `apps/remote-registry/DESIGN.md` if UI/UX shifts, `README.md` remote section, `doc/` remote pages, and any onboarding snippets. |
+| New env var or required service | `README.md` setup section, `AGENTS.md` Install And Setup, and any `.env.example` files. Never commit real secrets. |
+
+## Workflow
+
+1. Diff your change and list every user-visible surface it touches.
+2. For each surface, open the matching doc file and update it in the same PR. Do not defer to a follow-up.
+3. Rebuild docs to catch broken links or examples:
+   ```bash
+   bun run docs:build
+   ```
+4. If you changed the remote-registry app, also run:
+   ```bash
+   bun run remote-registry:build
+   ```
+5. Re-read the README quickstart end-to-end and confirm the commands you ship still work as written.
+
+## Style rules
+
+- Match the existing tone of the surrounding doc. Do not introduce a new voice.
+- Prefer runnable examples over prose. Examples should match the actual current CLI output.
+- Keep command examples copy-pasteable. No invented flags or fictitious env vars.
+- When you remove or rename a flag, document the migration in the same section, not in a separate changelog-only entry.
+- Cross-link related docs sparingly and only when they meaningfully help the reader.
+
+## Anti-patterns to refuse
+
+- Updating code without updating docs "because the docs are out of date anyway".
+- Adding a doc page that is not linked from the docs nav or another page.
+- Copying README content into `doc/` instead of linking, creating two sources of truth.
+- Leaving `TODO: update docs` markers in a finished PR.
+
+## Definition of done
+
+- Every user-visible behavioral change is reflected in `README.md`, the relevant `doc/` pages, in-CLI `--help`, and `AGENTS.md` where applicable.
+- `bun run docs:build` passes.
+- Examples in updated docs were actually executed (or visually verified) against the new behavior.

package/skills/repo-hygiene/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: repo-hygiene
+description: >
+  Load this skill on any code change in workflow-manager. It enforces the
+  "leave the repo cleaner than you found it" rules: no dead code, no orphan
+  files, no stray comments, no unrelated formatting churn, and validated
+  scripts before declaring done.
+type: core
+applies_to:
+  - "src/**"
+  - "apps/**"
+  - "tests/**"
+  - "scripts/**"
+---
+
+# Repo Hygiene
+
+Use this skill whenever you edit, add, or delete code in this repository. It encodes the cleanliness rules already implied by `AGENTS.md` and `biome.json`, made explicit so they are followed every time.
+
+## When to use this skill
+
+Load it for any change under `src/`, `apps/`, `tests/`, or `scripts/`. Skip only for pure docs work in `doc/` and pure markdown edits at the repo root (those load `doc-sync` instead).
+
+## Core rules
+
+1. Smallest viable change. Edit only what the task requires. Do not refactor unrelated code, do not reformat unrelated files, do not rename unrelated symbols.
+2. No dead code. Remove unused imports, unused exports, unused locals, unreachable branches, and obsolete helpers in the files you touch. Do not leave `TODO`/`FIXME` without an associated issue link or a short, dated reason.
+3. No stray comments. Per `AGENTS.md` code style, do not add explanatory comments unless the user explicitly asks for them. Keep existing comments only if they are still accurate; delete misleading ones.
+4. File placement matters. Source goes in `src/`. Tests go in `tests/`. Remote-registry UI code stays inside `apps/remote-registry/`. Scripts stay in `scripts/`. Do not create new top-level files unless the task explicitly calls for them.
+5. Import discipline. ESM only. Node built-ins use the `node:` prefix. In `src/`, local imports use `.js` extensions; in `tests/`, local imports use `.ts` paths. Keep value imports first, then `import type` imports.
+6. Strict typing. Prefer `unknown` over `any` for untrusted input and narrow it before use. Reuse shared types from `src/types.ts` instead of inventing parallel shapes. Keep payloads JSON-serializable where possible.
+7. Error handling. CLI-facing code exits with clear messages and non-zero codes for failure. Validation errors are returned as strings for ordinary user-input problems, not thrown. Executor flows return structured `OutputEnvelope` failures rather than ad hoc exceptions.
+8. No silent swallowing. Never `catch` and ignore. If an error is intentionally non-fatal, log it with enough context to debug.
+9. No secrets. Never log tokens, env values, or credentials. Never commit `.env*` files or any local Supabase keys.
+
+## Pre-completion checklist
+
+Before declaring a task done, run inside the worktree:
+
+```bash
+bun run lint
+bun test            # narrowest relevant subset first; then full suite
+bun run build
+```
+
+Plus, when applicable:
+
+```bash
+bun run remote-registry:test && bun run remote-registry:build   # apps/remote-registry/**
+bun run docs:build                                              # doc/** or user-facing CLI/schema
+```
+
+If any script fails, fix it or stop and report it. Do not declare completion with a red script.
+
+## Anti-patterns to refuse
+
+- Adding a new dependency without checking `package.json` first.
+- Introducing a new top-level config file when an existing one can be extended.
+- Reformatting whole files because the editor auto-formatted them.
+- Leaving commented-out code "in case we need it later" — git history is the archive.
+- Mixing an unrelated refactor into a feature PR.
+
+## Definition of clean
+
+A change is clean when:
+
+- The diff contains only lines required by the task.
+- `git status` shows no unintended new files.
+- `bun run lint`, `bun test`, and `bun run build` are all green.
+- A future reader can understand the change without an accompanying explanation message.

package/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,33 @@
+# Spec-Driven Development
+
+Write a structured specification before writing any code. The spec is the shared source of truth between you and the engineer - it defines what we're building, why, and how we'll know it's done.
+
+## When to apply
+
+Use spec-driven development when starting projects, handling ambiguous requirements, making architectural decisions, or tackling changes requiring 30+ minutes of work. Skip it for single-line fixes or unambiguous, self-contained changes.
+
+## Six-section spec format
+
+Every spec must cover these six sections in this order:
+
+1. **Objective** - One paragraph: what we are building, why, and the success criteria. Surface assumptions explicitly.
+2. **Commands** - The exact CLI / API surface. Flags, exit codes, examples.
+3. **Project Structure** - File layout with one-line responsibilities per file.
+4. **Code Style** - Language version, modules, error handling pattern, no-classes / no-comments rules, max function length.
+5. **Testing Strategy** - Unit vs integration, what gets mocked vs real, coverage gates, naming conventions.
+6. **Boundaries** - In scope, out of scope, and any non-negotiable constraints.
+
+## Practices
+
+- List assumptions before writing spec content. If they are wrong, the spec is wrong.
+- Reframe vague requirements as measurable success criteria.
+- Treat specs as living documents - update when decisions change.
+- Reference the spec from pull requests so the audit trail is visible.
+
+## Output rules
+
+- Plain markdown only. No preamble.
+- Every spec must contain all six sections, even if a section is "N/A".
+- Code style and testing strategy must include concrete rules, not vague aspirations.
+
+15 minutes of specification prevents hours of rework.

package/skills/workflow-manager-cli/SKILL.md

@@ -3,7 +3,7 @@ name: @workflow-manager/runner/cli
 description: >
   Load this skill when working with the wfm CLI from @workflow-manager/runner, authoring or
   validating workflow definitions, configuring step skills and adapters, or
-  publishing workflows to the remote registry. Covers questions, scaffold,
+  publishing workflows to the remote registry. Covers doctor, agent, scaffold,
   validate, run, auth, publish, pull, search, and remote info.
 type: core
 library: @workflow-manager/runner
@@ -25,6 +25,7 @@ Use this skill when you need to create or operate `workflow-manager` workflows f
 Use it when the user wants to:
 
 - scaffold a new workflow definition
+- create local agent rules for WFM usage
 - validate or run a workflow file
 - configure approvals, retry policy, or adapter initialization
 - publish a workflow to the remote registry
@@ -35,17 +36,19 @@ Use it when the user wants to:
 
 Use this sequence unless the user asks for a narrower task:
 
-1. Discover the workflow intent with `wfm questions`
-2. Scaffold a starter file with `wfm scaffold`
-3. Edit the workflow definition
-4. Validate the file with `wfm validate`
-5. Execute it with `wfm run`
-6. If needed, authenticate and publish with the remote registry commands
+1. Inspect local setup with `wfm doctor`
+2. Create project agent rules with `wfm agent` when local agent guidance is useful
+3. Scaffold a starter file with `wfm scaffold`
+4. Edit the workflow definition
+5. Validate the file with `wfm validate`
+6. Execute it with `wfm run`
+7. If needed, authenticate and publish with the remote registry commands
 
 ## Local workflow commands
 
 ```bash
-wfm questions
+wfm doctor
+wfm agent ./AGENTS.md
 
 wfm scaffold ./example-workflow.md
 wfm scaffold ./example-workflow.json --format json
@@ -90,7 +93,9 @@ wfm pull alice/remote-bunny --output ./remote-bunny.json
 
 ## Adapter and validation notes
 
-- Supported adapters include `mock`, `opencode`, `codex`, and `claude-code`
+- Supported adapters include default `pi-agent` plus explicit `mock`, `opencode`, `codex`, and `claude-code`
+- Omit `taskSpec.adapterKey` to run a task with the `pi` coding agent CLI
+- Put skills, MCP endpoints, system prompts, model, and context under `taskSpec.init`
 - Human approvals should stay explicit in workflow definitions
 - External validation should be deterministic where possible
 - Use the mock adapter for fast tests and scaffolding flows