Deliver software with the smallest useful workflow

Use this guide when the outcome is a tested software change. Choose the smallest path that matches uncertainty and risk; do not run a ceremonial chain when one bounded Skill can safely finish the task.

Choose the delivery mode

Use Planning and research when the approach is still unclear, Debug and fix for a concrete failure, and Review and ship once implementation is ready.

Prepare the delivery contract

User-visible outcome:
Approved scope and non-goals:
Repository/module boundary:
Acceptance criteria:
Required test and browser evidence:
Compatibility, migration, and rollback constraints:
Authority for dependencies, Git, external systems, and deploy:

Read the repository instructions and preserve unrelated work. Name any action that must not occur, such as package installation, commit, push, PR creation, provider mutation, or deployment.

Recipe 1: quick implement for known scope

Use ak:cook directly when a separate research and plan phase adds little value.

/ak:cook --fast "Add a disabled state to the existing submit button while its current mutation is pending. Reuse the component and tokens, add the focused test, and do not install packages, commit, or deploy."

--fast reduces research overhead; it does not remove the concise plan, tests, review, or completion checks inside the Skill. Add --advice only when the small task still contains a consequential decision.

Before accepting the result, verify the changed behavior, focused test, affected neighboring checks, final diff, and actions intentionally left undone.

Recipe 2: classic feature delivery

Use this path for unclear shape, multi-file impact, or elevated risk.

1. Understand and decide

Use ak:brainstorm when several viable directions exist. Use ak:scout or ak:research only for questions that can change the decision.

/ak:brainstorm "Compare recovery approaches for offline drafts; preserve the document format and avoid a new service; stop after recommending one direction"

Record the chosen direction, evidence, rejected options, and open questions.

2. Produce and approve the plan

/ak:plan --hard --tdd "Implement the accepted offline-draft recovery direction; include crash/reload behavior, compatibility, tests, rollback, and stop before coding"

Review the plan path. For high-impact work, run ak:plan red-team <plan-path> and ak:plan validate <plan-path> before approval.

3. Implement the approved plan

/ak:cook @<approved-plan-path> --tdd

Pass the current repository state, phases approved for this run, authority boundary, and acceptance criteria. Stop if implementation requires unplanned scope or invalidates a decision.

4. Verify independently

/ak:test
/ak:code-review --pending

Return test or review failures to implementation. Do not weaken acceptance criteria to make the workflow green.

5. Deliver only with authority

Follow Review and ship. Commit, push, PR, merge, and deploy remain distinct approval boundaries.

Recipe 3: start a greenfield project

Use ak:bootstrap when one command should coordinate research, stack decisions, design, planning, implementation, and documentation.

/ak:bootstrap "Create a local-first issue tracker for a five-person team; web app only; offline read/write; no billing or production deploy; document the chosen stack and stop at a reviewable local build"

This is a broad workflow. Review stack, dependency, data, security, and deployment decisions before allowing irreversible work.

For more control, stage it:

/ak:research "Compare only the stack decisions that affect local-first sync and deployment"
/ak:brainstorm "Choose one architecture from the evidence"
/ak:plan --deep --tdd "Plan the accepted greenfield architecture"
/ak:cook @<approved-plan-path> --tdd
/ak:docs update

Recipe 4: issue to plan, then pause

/ak:issue-to-plan <issue-number-or-url>

Review the resulting evidence, plan, validation findings, and issue handoff. Start ak:cook only after a human approves the plan. This path is preferable to autopilot when the issue is incomplete or the repository is unfamiliar.

Recipe 5: full autopilot to PR readiness

ak:vibe can coordinate isolated planning, implementation or repair, tests, review, and PR delivery.

/ak:vibe <issue-number-or-url>

Use it only for a trusted, bounded request with the correct repository and clear GitHub authority. --advice adds advisory checkpoints; it does not remove review or ship gates. Add ship/merge modes only when those actions are explicitly intended.

Practical handoff after each stage

Artifact produced and location:
Decision or change made:
Checks passed/failed:
Scope consumed and remaining:
New evidence or changed assumptions:
Next Skill and its exact input:
Authority still missing:

Use ak:handoff before switching session, owner, or runtime.

Completion checklist

• The path matched the actual uncertainty and risk.
• The implementation stayed within an approved contract.
• Required behavior, tests, and review passed on the final diff.
• Compatibility, migration, rollout, and rollback were handled where relevant.
• GitHub and external actions are completed only when authorized and otherwise listed accurately in the handoff.

Planning and research

Use this chapter when the answer is not yet “what code should change?” Research only the unknowns that can change a decision, then turn the evidence into one approved implementation contract.

Start with a bounded decision brief:

Decision to make:
Current evidence and constraints:
Questions that could change the decision:
Options already considered:
Required output and stop point:

For an unfamiliar change, run:

/ak:scout "Locate the ownership, data flow, tests, and repository instructions for offline draft recovery. Return evidence only; do not edit files."
/ak:research "Compare the viable recovery approaches against the observed repository constraints. Cite primary sources for external claims."
/ak:brainstorm "Recommend one approach, list rejected alternatives and trade-offs, and stop before planning."
/ak:plan --hard --tdd "Turn the accepted approach into phases, acceptance criteria, tests, compatibility checks, rollback, and explicit approval gates."

For high-impact work, review the saved plan, then run:

/ak:plan red-team <plan-path>
/ak:plan validate <plan-path>

ak:advise is a standalone consultation when you need an opinion before choosing the next Skill. --advice adds advisory checkpoints inside supported workflows such as brainstorm, plan, cook, fix, and vibe; it does not replace plan approval or review.

Stop before implementation if evidence conflicts, ownership is unclear, the plan changes public behavior without compatibility treatment, or the required Git/external authority is missing. The handoff to implementation must include the approved plan path, accepted decisions, non-goals, current repository state, and checks required on the final diff.

Debug and fix

Use this chapter for a reproducible failure. Keep diagnosis separate from the first plausible patch, and prove that the final change addresses the observed cause.

Prepare a failure contract before changing code:

Expected behavior:
Observed behavior and exact error:
Smallest reproduction:
Environment and version:
Last known good state:
Evidence collected; hypotheses not yet proven:
Allowed scope and actions:

When the cause is already bounded:

/ak:fix "Reproduce the timeout from <test-or-command>. Identify the cause, make the smallest compatible fix, add a regression test, run affected checks, and do not commit or deploy."

When it is not:

/ak:debug "Reproduce <failure>; trace the failing path; distinguish evidence from hypotheses; stop after identifying the most likely cause and the next falsifying check."
/ak:fix --advice "Apply the cause-aligned fix from the debug handoff, preserve unrelated behavior, add a regression test, and report any changed assumption."
/ak:test
/ak:code-review --pending

For browser-only failures, record viewport, route, interaction, console/network errors, and before/after screenshots. Do not call a failure fixed because a reload made it disappear.

After two attempts with the same failure, stop the patch loop. Re-check the reproduction and environment, list disproved hypotheses, and escalate with the smallest useful evidence bundle. Never delete user data, weaken tests, bypass a safety mechanism, or broaden permissions merely to make the symptom disappear.

Review and ship

Use this chapter when implementation exists. Review the actual final diff, close findings with evidence, and treat commit, push, PR, merge, and deploy as separate actions.

Give the reviewer a compact packet:

Outcome and acceptance criteria:
Approved plan or issue:
Changed files and intentional non-changes:
Tests and browser evidence:
Compatibility, migration, security, and rollback notes:
Known limits and actions not authorized:

For local work:

/ak:test
/ak:code-review --pending

Fix material findings, rerun affected checks, then review the updated diff—not the earlier version. For an existing PR:

/ak:review-pr 482
/ak:review-pr 482 --fix --reply

Use --fix --reply only when the finding is understood and the task allows code changes plus GitHub replies. Unresolved high-severity findings, failing required checks, drift from the approved scope, or missing rollout/rollback evidence are stop conditions.

Only after approval and explicit authority, use the narrow delivery action:

/ak:git cm
/ak:ship official

The final handoff must state the commit/PR, checks run on the final revision, unresolved findings, merge/deploy state, and rollback owner. “Ready to merge” is not the same as “merged,” and “merged” is not the same as “deployed.”

High-risk delivery

Use this chapter for authentication, authorization, payments, public APIs, secrets, migrations, or infrastructure. Add a domain Skill and an independent security/review gate; do not rely on a generic implementation chain alone.

Protected assets and trust boundaries:
Threats and abuse cases:
Data classification and retention:
Compatibility and migration contract:
Rollback and incident path:
Required approver and prohibited actions:

Choose the narrow domain entry point, then plan:

/ak:better-auth "Design the required authentication change; preserve current sessions and define migration and rollback constraints. Stop before implementation."
/ak:plan --hard --tdd "Plan the accepted auth change with negative authorization tests, compatibility, rollout, rollback, and approval gates."
/ak:cook @<approved-plan-path> --tdd
/ak:security --red-team --iterations 12
/ak:code-review --pending

For payments, start with ak:payment-integration; for a bounded repository scan, use ak:security-scan <path>. A security scan complements domain tests and review—it does not prove authorization logic, payment idempotency, safe secret handling, or migration reversibility.

Require evidence for denial paths, replay/idempotency where relevant, secret exposure checks, migration rehearsal, rollback, and final independent review. Stop on an unclassified breaking change, unresolved critical/high finding, unowned migration, missing rollback, or unclear production authority.

Frontend delivery

Use this chapter when the outcome must match a design and work in a real browser. Define the UI contract before implementation so visual polish cannot hide broken behavior or accessibility.

Route and user task:
Reference screenshot/design system:
Required states: loading, empty, error, success, disabled:
Viewports and browsers:
Keyboard, focus, and screen-reader expectations:
Performance budget and existing components to reuse:

Choose the entry point that matches the evidence:

• ak:ui-ux-pro-max for a new UX direction or system-level design decision.
• ak:frontend-design for a defined visual surface and interaction states.
• ak:frontend-development for implementation against an accepted contract.
• ak:react-best-practices for a React performance or architecture pass.
• ak:agent-browser or ak:web-testing for real-browser verification.

A practical design-to-browser chain:

/ak:frontend-design "Define the responsive states for <route> using the existing tokens and components. Include loading, error, empty, focus, and narrow desktop behavior."
/ak:frontend-development "Implement the accepted UI contract; preserve unrelated layout; add focused component tests; do not install packages or deploy."
/ak:web-testing "Verify <route> at <viewports>; exercise keyboard and primary interactions; capture console/network errors and before/after evidence."
/ak:code-review --pending

For pixel-faithful work, include the reference viewport and compare the same content/state at the same dimensions. For performance work, record a baseline, change one bounded cause, and compare the same scenario afterward. Complete only when required states, keyboard/focus behavior, responsive layouts, console and network checks, focused tests, and final diff review pass.

Parallel delivery

Use parallel work only when there are at least three genuinely independent workstreams, ownership can be exclusive, and one integrator owns the final system result. Parallelism is not a substitute for decomposition.

Define the work graph before dispatch:

Shared outcome and acceptance criteria:
Workstream A — owner, files, input, output:
Workstream B — owner, files, input, output:
Workstream C — owner, files, input, output:
Dependencies and shared contracts:
Integrator and merge order:
Final tests, review, and rollback owner:

For a plan that already has safe phase boundaries:

/ak:plan --parallel "Split <outcome> into independent file ownership, shared contracts, integration order, and one final verification phase."
/ak:cook @<approved-plan-path> --parallel
/ak:test
/ak:code-review --pending

For explicit agent coordination:

/ak:orchestrate "Execute the approved work graph; enforce exclusive file ownership; require artifact handoffs; keep integration and final verification with one owner."

Use ak:worktree when branches must be isolated, but inspect current worktrees and preserve user changes before creating or removing any. The integrator must validate shared contracts, resolve semantic—not only textual—conflicts, run the combined tests, review the combined diff, and report the actual merge/PR state. Stop parallel execution when two workers need the same files, a shared contract changes, or no owner can verify the integrated result.