start-workflow

name	start-workflow
description	Explicit entry point for ticket-granularity work (implement a component, fix a non-trivial bug, refactor a module, add a feature). The user invokes /start-workflow at the start of such tasks. The skill enforces an orchestration sequence — clarify → aegis → plan → optionally ADR → implement (parent by default, delegate by context impact) → fresh-context review → commit/PR — so the work follows the project's rules-driven standards. Skip for one-line fixes, config tweaks, docs-only changes, and trivial typo fixes — handle those directly.
user_invocable	true

Start Workflow

The orchestration entry point that turns a user request into a finished, reviewed, committable change. The parent session implements directly by default and delegates by context impact (ADR-0012). Read this once at the beginning; do not re-read it per subtask.

When this skill applies

Apply when the user asks for:

• A new component, page, or screen
• A bug fix that involves more than a one-line change
• A refactor across multiple files
• A new utility plus its tests
• An integration change (DB schema, API route, auth flow)

Skip (handle directly, no sequence) for:

• One-line fixes / typo corrections
• Config-only edits (*.json, *.toml, .gitignore, package.json field tweaks)
• Docs-only changes (*.md)
• Anything the user explicitly says "just do it quickly"

If unsure, lean toward applying — the cost of skipping orchestration on a borderline-non-trivial task is higher than the cost of using it on a borderline-trivial one.

The sequence

1. Clarify

Read the user's request. If acceptance criteria or constraints are ambiguous, ask at most one clarifying question — focused on whichever ambiguity blocks the work the most. Prefer resolving ambiguity from the codebase or real data (files, assets, git history) before asking. Do not bombard with a checklist.

If the request is clear enough, say so and proceed.

2. Compile context via aegis

Call aegis_compile_context with target_files (the files that will be edited or created) and plan (one-line goal). aegis returns the relevant rule and ADR documents deterministically, with relevance scores. Use this output as the single source of truth for "what rules apply to this task" — do not also paste in the full rule content; the rules are already in the prompt baseline.

If aegis returns nothing relevant, that is itself a signal: either the knowledge base needs new docs (raise via aegis_observe with event_type: "compile_miss" after the work is done), or the task is genuinely outside any documented decision.

3. Decide on ADR

If the work involves a non-obvious design choice — picking between credible alternatives, introducing a new pattern, or reversing an earlier decision — draft the ADR before implementing. ADRs go in docs/adr/ per the index there.

If the work is purely mechanical (no design call), skip the ADR.

4. Plan

Draft a short plan in the parent session. The plan should include:

• One sentence on the goal
• Files to create or edit, with one-line description per file
• Acceptance criteria
• Verification steps (bun run typecheck / bun run test / build / manual smoke test as applicable)

Keep the plan tight. For genuinely complex multi-step work (≥ 5 distinct edits across unrelated areas, or work requiring TDD discipline), delegate the plan-writing itself to superpowers:writing-plans or use superpowers:brainstorming first. Per ADR-0006, superpowers' methodology skills are tools called from inside this orchestration — not parallel orchestrators. Do not let them auto-trigger as independent decision-makers.

If the feature involves non-obvious state transitions (wizards / multi-step forms, auth or session flows, async guards like disable-while-loading or unsaved-changes, permission branching), write a specs/<feature>.spec.md (format: specs/README.md) and verify it via /verify-spec specs/<feature>.spec.md. Per ADR-0015 this is a flat two-agent pipeline you orchestrate: dispatch the spec-verifier agent (hunter) → it formalizes the spec and returns the machine + candidate counterexamples → dispatch the spec-checker agent with the machine and candidates → it replays each and returns the CONFIRMED survivors. Fix the design for every CONFIRMED counterexample before implementing (ADR-0010/0015). Do NOT auto re-run — a repeat verification is a fresh pass the user explicitly asks for after reviewing the findings. The deciding factor is interaction complexity, not scale.

5. Implement

The parent implements directly by default. Use superpowers:test-driven-development for pure functions and well-specified logic. The per-edit lint/typecheck hook keeps quality continuous.

Delegate only when the delegation criteria (AGENTS.md / ADR-0012) are met:

• Heavy exploration (bulk file reads, log digging, cross-cutting investigation): dispatch an Explore/research subagent so the raw output never enters the parent's context — only the summary returns.
• Independent parallel units (no shared files, no output dependency): dispatch parallel general-purpose subagents (model: "sonnet") via multiple Agent calls in one message. Dispatch prompts must be self-contained — plan, file paths, rules, acceptance criteria; the subagent will not see the parent conversation. Escalate to opus for non-trivial design judgment, after a weak sonnet result, or for long-horizon autonomous work.
• Implementation dispatches block the next step — the platform runs subagents in the background and notifies on completion; wait for that completion and integrate before proceeding. Do not fire-and-forget implementation work or rely on SendMessage resumption for it.

6. Review

Once implementation is complete:

• Read the full diff (git status / git diff) — for dispatched work, do not trust the summary alone
• Run bun run typecheck and bun run test — the PostToolUse hook already checks per-edit, but a final pass catches gaps
• Verify the acceptance criteria from step 4 are met
• Review the uncommitted diff (users can also trigger it as /review-diff; pass high for a deeper multi-lens verification). Per ADR-0015 this is a flat two-agent pipeline you orchestrate: dispatch the code-reviewer agent (finder) → it returns candidate findings across all lenses (bug hunt + AGENTS.md and path-scoped rules) → dispatch the review-verifier agent with those candidates (even if zero) → it adversarially refutes each and returns CONFIRMED/PLAUSIBLE survivors, and its completion stamps the commit gate via a PostToolUse(Agent) hook. This is the bias check: neither agent's context has seen the implementation reasoning. Both are depth-1 dispatches you wait on directly. Address every finding or explicitly justify it as out of scope before committing. A PreToolUse hook enforces the gate — git commit is blocked until the verifier has stamped it.
• The parent fixes findings directly. Re-review only after major rework.

7. Commit and PR

When the diff is correct, propose a commit split per the Commits discipline in AGENTS.md and ask the user for confirmation — never auto-commit. Create PRs with gh pr create (English summary) only when the user asks.

What this skill does not do

• It does not enforce TDD on every task. TDD is appropriate for pure functions and well-specified logic; it's overhead for UI assembly. Decide per-task.
• It does not mandate delegation. Dispatch is a context-protection tool, not a quality ritual — the review step is the quality gate.

Anti-patterns

• Skipping the plan step "because the task is obvious": if it's truly obvious it's probably trivial enough to skip the whole skill. If you need this skill, write the plan.
• Dispatching scoped work the parent could do directly: briefing cost, summary-induced information loss, and round-trip latency buy nothing when the scope is already understood. Delegate for context protection, not by habit.
• Letting exploration noise into the parent: if an investigation will read many files or dump logs, that is exactly what Explore subagents are for — keep the parent's context for implementation and judgment.
• Multiple parallel dispatches when tasks are coupled: if unit B depends on unit A's output, run them sequentially — or just do both in the parent. Parallel only for independent work.
• Copying the plan into a commit message: the plan is throwaway. Commit messages and ADRs are the durable record.