Drive a request to PR readiness with ak:vibe

Use ak:vibe when one well-bounded GitHub issue or feature request should move through an isolated worktree, validated plan, implementation or repair, local review, pull request, and optional merge. The pipeline coordinates the owning Skills; it does not replace their tests, approval gates, branch protections, or security rules.

Choose ak:vibe for end-to-end delivery

Use ak:vibe when

• A GitHub issue is the source of truth for a feature or bugfix.
• A concrete natural-language request should become an issue and reviewed PR.
• You want the same pipeline to choose ak:cook for feature work or ak:fix for bug, regression, failing CI, or incident evidence.
• You want optional beta delivery, dual-stage promotion, or advisory checkpoints.

Choose another workflow when

• Requirements or product scope still need exploration. Start with ak:brainstorm or ak:plan.
• You need local implementation only and do not authorize GitHub mutations, branch push, or PR creation. Use ak:cook or ak:fix directly.
• You only need review. Use ak:code-review or ak:review-pr.
• The current repository does not match the supplied issue repository.
• The work must run directly on a protected or shared integration branch.

Prepare delivery authority

Before you start:

• Complete Onboarding, and confirm all orchestrated Engineer Skills are installed for the runtime and scope.
• Open the matching Git repository with a clean or reusable isolated feature worktree strategy.
• Install the AgentKit CLI, Git, and authenticated gh CLI with the permissions needed for issue, label, branch, PR, review, and any requested merge actions.
• Provide a GitHub issue URL/number or a feature request with outcome, scope, constraints, acceptance criteria, and non-goals.
• Decide whether the run may only reach PR readiness or may merge and converge CI.
• Preserve unrelated work and identify protected branches and promotion policy.

See Runtime adapters before starting a long, mutation-heavy run outside the runtime with the strongest evidence.

Choose the ship mode deliberately

/ak:vibe --beta "Add exportable audit logs with existing authorization, focused tests, and no breaking API changes"

/ak:vibe --beta "Add exportable audit logs with existing authorization, focused tests, and no breaking API changes"

$ak:vibe --beta "Add exportable audit logs with existing authorization, focused tests, and no breaking API changes"

Mode resolution is --both over --beta over default stable. When both flags appear, the Skill warns once and continues in dual-stage mode. --ultra composes with every ship mode and does not fan out cook, fix, or ship. With --advice, shared advisory supervision detects the host and routes Kongming to Fable 5 for a Claude subscription, gpt-6-astra with low effort for Codex, or claude-fable-5-high for Cursor. Kongming returns counsel, never code; the main agent remains responsible for every decision, edit, and gate. --advice is forwarded to supporting Skills that accept it: ak:plan, ak:cook, ak:fix, ak:code-review, ak:ship, ak:review-pr, and ak:test. At planning it forwards the handover contract so phase files include explicit success criteria, mechanical Verify conditions, and a Failure Protocol. ak:cook and ak:fix inherit that contract and stop for kongming before self-reasoning on the first unexpected failed verification. Pipeline runs do not forward --advice to ak:docs, because that Skill prompts for confirmation. Kongming also checkpoints after investigation, plan gates, implementation, local review, testing/docs, and after PR CI is terminal and green.

Understand what happens during a run

1. The Skill resolves the request. It verifies repository identity, reads issue title, body, and comments when supplied, extracts the contract, chooses feature or bugfix route, and searches for an existing durable plan.
2. It creates isolation. ak:worktree creates or reuses a matching clean worktree and descriptive branch. It never implements directly on common protected or integration branches.
3. It investigates when the route needs it. A bugfix or failing-CI path can run ak:debug before planning. New or unfamiliar technology can run ak:research. Those Skills do not replace the plan gate.
4. It validates the plan. A valid existing plan.md is reused; otherwise ak:plan --tdd creates one. --ultra and --advice are forwarded to plan when you set them on vibe. With --advice, that planning step authors handover phase files with explicit success criteria, mechanical Verify conditions, and a Failure Protocol. Validation, red-team, and a whole-plan consistency sweep always run before implementation.
5. It projects state to GitHub. The workflow creates missing delivery labels, creates or updates the source issue, records branch, route, plan, mode, and acceptance criteria, then links the issue into the local plan index.
6. It implements the scoped work. Features use ak:cook --tdd --auto; bugfixes use ak:fix --auto. --advice is forwarded to cook or fix when set, so they honor the plan Failure Protocol and stop for kongming on the first unexpected failed verification before self-reasoning. Parallel implementation uses disjoint file ownership, serializes shared files, and prefers a separate worktree when two writers would touch the same file. The issue changes from ready to cook to in progress before code changes begin.
7. It performs local review. ak:code-review --pending checks spec compliance and quality. --ultra and --advice are forwarded here when set. Critical and Important findings are fixed and relevant validation reruns.
8. It verifies and updates docs when the contract changed. Observable behavior, boundaries, or invariants can run ak:test create, audit, or optimize. Official/stable ship mode skips in-repo ak:docs update so ak:ship official owns that write. --beta mode can run ak:docs update when public contracts, APIs, or agent context changed; it does not pass --advice on that docs step. --advice is still forwarded to ak:test when set.
9. It ships a PR. ak:ship beta or ak:ship official finalizes plan files, merges the target branch into the feature branch, tests, reviews, commits, pushes, opens the PR, and records the linked PR. --advice is forwarded to ak:ship when set.
10. It converges PR review. ak:review-pr --fix --reply reviews the full PR, fixes actionable findings, pushes verified fixes, posts the final review, and waits for required checks to become terminal and green. --advice is forwarded to ak:review-pr when set. After CI is green, Kongming posts an assessment on the PR and the source issue.
11. It marks readiness. The issue and PR receive the correct ready label; stale implementation labels are removed.
12. It optionally merges and monitors. --ship and --both merge through repository conventions, watch target-branch CI or deploy workflows, and run bounded follow-up fix branches for deterministic failures.

Dual-stage mode does not begin stable delivery until beta CI is green. Before a promotion merge, the Skill lists carried commits and stops for approval if the promotion would sweep unrelated work.

Keep approval gates intact

• --ship authorizes merging a PR only after readiness gates pass; it does not authorize force push, direct push to protected targets, bypassing review, or hiding a failing check.
• --both authorizes two delivery stages but not an unrelated promotion sweep.
• A public-contract, security-sensitive, business, or irreversible decision remains a human gate even in automatic implementation modes.
• Branch protection and required reviews remain authoritative. Pending checks may use repository-supported auto-merge; failed or conflicting state cannot be forced through.
• The same unresolved CI blocker is attempted at most three times before the run stops and hands off evidence.
• --advice adds counsel and external PR/issue comments. Kongming never edits code or supplies approval on the user's behalf.

Account for network, process, disk, and cost

• GitHub issue, label, PR, review, merge, and workflow operations use authenticated network requests and mutate shared repository state.
• Worktree creation writes another checkout; its owning Skill may install dependencies based on lockfiles, using substantial network, CPU, and disk.
• Planning, implementation, tests, builds, reviews, commits, and follow-up fixes can spawn many local processes and create durable files.
• CI and deploy workflows consume repository runner or provider capacity after pushes and merges. The Skill defines no price; account billing and quotas apply.
• Issue bodies, comments, plans, PR text, logs, and advisory comments must exclude secrets, tokens, customer data, private environment values, and unredacted sensitive command output.

Verify the result

A complete PR-readiness run should give you:

• Source issue or created issue URL, isolated branch and worktree, durable plan, implementation route, and resolved ship mode.
• Acceptance criteria backed by current tests and local review evidence.
• A pushed PR with structured evidence, linked plan, final review verdict, green required checks, and the correct ready label.
• No unresolved Critical or Important review findings.
• A completion report naming review iterations, blockers, and unresolved questions.

A merge-enabled run must additionally show the merge result, merge commit, target-branch CI conclusions, and every follow-up fix. Dual-stage completion requires separate beta and stable PR/merge/CI evidence.

Troubleshoot or continue

Know the current limits

• The full run depends on compatible nested Skills, GitHub access, repository conventions, branch protection, test infrastructure, and CI availability.
• Natural-language input causes GitHub issue creation after plan gates; it is not a local-only shortcut.
• Automatic implementation does not remove business or irreversible-action gates.