Vibe Coding

Vibe Coding

Overview

vibe-coding is the top-level orchestration entry point for multi-turn vibe-coding workflows. It classifies the user's current instruction into one row of the decision table under Workflow Phases, then either routes that row to the visible specialist skill whose metadata matches it — preserving each specialist's own write boundary, approval gate, stop condition, and verification rules — or, for a router-owned row, performs the work itself under the shared effect and commit boundaries carried in this file.

This skill routes work; it does not replace specialist skills and does not authorize host command plumbing, release preparation, generated eval workspaces, or implementation outside the row it selected.

Before any nontrivial state-changing or external-cost action, distinguish selection from permission. Select the action only when the current deliverable requires it or an applicable higher-priority or owning-workflow contract requires it in support of that deliverable. Record the action owner and authority source in routing or workflow state when the distinction is material. Permission, capability, availability, relevance, conventional path placement, or existing tracked status may constrain or support a selected action, but none of them independently selects new work or bypasses a bound identity, proof minimum, consent gate, or stop condition.

Apply the same separation to artifact lifecycle. Authority to create or edit an artifact does not by itself authorize tracking, staging, committing, release-note inclusion, or publishing it. A mandatory repository or owning-workflow coupling may select one of those transitions, but the workflow must cite that obligation rather than infer it from usefulness or visibility.

The checkpoint default in the commit-selection contract below is the one transition a state-changing route's own contract selects, and it reaches only that unit's verified in-scope changes. Deferring the checkpoint is not the conservative choice — it accumulates a change set the user can neither review nor split without re-verifying each block — so treat an unexplained uncommitted pile at the end of a state-changing run as a defect, not as safety.

This skill does not hardcode a specialist roster. Routes are resolved at routing time from the skill metadata visible in the current environment, so the family can grow or shrink without changing this skill.

Activation

Activate this skill only when the current turn has one of these signals:

• An explicit host-specific skill invocation for vibe-coding, such as Claude /vibe-coding or Codex $vibe-coding. These are representative examples, not an exhaustive list of valid AI-agent syntaxes.
• A host-provided invocation signal that says vibe-coding is active.
• An explicit instruction such as "use vibe-coding".

Do not activate when the user merely mentions "vibe coding" as a style, repository label, quoted text, background concept, or example.

After vibe-coding is already active, later related turns may continue through Routing State without a new activation signal. Do not treat that continuation as a fresh activation.

If activation lacks a concrete coding instruction, ask for the instruction and do not select a downstream phase yet. Keep this clarification narrow: do not present a route menu, availability diagnosis, or specialist boundary summary before the user provides enough intent to classify the immediate phase.

Routing State

Routing state has two carriers with different authority. The conversation and the active artifact paths are the authority: approvals, proceed decisions, and stop boundaries are given and read there. The session record at .plans/vibe-sessions/<record_id>.json — the router's default record_id is the workflow id — is a record of that state, not authority. It persists the six routing fields the router owns:

• Current goal.
• Current phase.
• Active artifact path or paths.
• Pending user decision, when one exists.
• Known blocker.
• Next route.

It also names each approval, proceed decision, handoff, commit selection, and gate confirmation as an event with its source, so a recorded event counts only for its enumerated source, only while its status is current, and never becomes a decision the conversation did not make. The write points are under Session Record below; the schema is in references/session-record.md.

Specialist-specific state—such as execution item status, review target identity, debug hypotheses, delegated-work budgets, or verification receipts—stays with the active specialist. Summarize only the minimum needed to resume that specialist after interruption or compaction; the record's routing fields do not duplicate its ledger.

For later related turns, classify the user request before routing:

• continue current workflow
• revise current artifact
• replace workflow
• cancel workflow
• unrelated ordinary request

If stale context would change behavior and the class is unclear, ask one clarifying question before routing. On a continuation turn, rebind from conversation state and the active artifact paths, and from the session record when one is valid: scan the record directory, keep the active, unexpired records that belong to this worktree, and select the one whose host_session_id matches the host's session id when both are known. When more than one candidate remains, the record is conflicting: continue from conversation state, and every gate answers as for a conflicting record. When no valid record exists and context was lost after compaction or a long interruption, rebind from the latest known artifact path; if that is not possible, ask for the missing artifact or decision.

On cancellation or replacement, clear the active phase, next route, pending approvals, active slice, and live artifact bindings, and write the record's tombstone — cancelled, or superseded with a new workflow id for the replacement. Preserve completed artifact paths only as historical context.

When a downstream phase reports that the bound spec or plan is defective — contradictory, stale, infeasible, or contract-breaking — that is a backtracking signal, not a reason to force the current phase forward. Route the next turn to the row that owns the broken artifact: requirements-specification when the requirements artifact, user-visible behavior, scope, or source acceptance criteria are wrong; implementation-planning when the bound plan's acceptance criteria, proof, schema, test, edit-order, or risk contract is wrong. Do not keep executing patch-by-patch against a contract a downstream specialist already flagged as broken; references/phase-boundaries.md has the detail.

Goal-Alignment Gate

Apply this gate to the instruction before classifying it into a row. It fires only when the instruction leaves an unresolved semantic or acceptance ambiguity about history, release, irreversible, or outward-facing effects: the words can reasonably be read two ways that differ in whether history is rewritten, what is released or versioned, whether something is destroyed or otherwise cannot be undone, or whether anything leaves this machine — including when the two readings differ in what counts as done for one of those four effects — and nothing in the turn settles which reading is meant.

It does not fire on:

• A settled direct request whose action, scope, and target are clear, such as a plain request to commit the current changes.
• A negation such as "do not push": a stated boundary is a settled instruction, not an ambiguity.
• Quoted or background material: a commit message that mentions rebase, a pasted log, an audit report, or an example is inert context, not the instruction.
• Plan metadata: a bound plan that carries Commit checkpoints or similar routing metadata settles the checkpoint question rather than raising one.
• An action the request names as out of scope, such as release preparation that an adjacent report suggests and the user excluded.
• Ordinary approval or readiness ambiguity that an active artifact row already settles by asking — "looks good, continue" during requirements, "looks good, go ahead" after planning — unless it also changes a history, release, irreversible, or outward-facing effect.

When it fires, route to the visible goal-alignment specialist — the skill whose visible description matches aligning, confirming, or correcting the agent's understanding before action, matched by its metadata like any other route — and stop for the user's answer. When no such specialist is visible, ask the one confirming question yourself, name the availability source you checked, and stop; the gate is not a phase, so it never reports matched-but-unavailable. In both cases record the user's answer as a confirmation event with source: user-turn and status: current after the answer, then classify the instruction. A completed gate is not proceed evidence for anything else: it settles the reading of the instruction, and every row's own approval, consent, and stop boundaries still apply.

Workflow Phases

Classify the immediate instruction into exactly one row. Choose the immediate next required phase, not the eventual end goal. Router-owned rows (workflow-control, direct-implementation, maintenance) are performed by this skill as ordinary behavior under the shared effect and commit boundaries below; every other row is routed to the visible specialist whose metadata matches it. Read references/route-selection.md when the cells do not settle the classification. Row ids such as requirements-specification are the phase values the session record stores, not route names: when reporting a matched specialist route, name the specialist by the name its visible metadata states, with the row id at most alongside it; for a router-owned route, report the row with its ownership status and invent no specialist name; for an unavailable route, report the row as matched-but-unavailable together with the specialist name the prompt, user-provided material, or visible metadata identifies as absent, and invent none when nothing identifies one. Write every route report under the language gate in User-Facing Output: when a task enumerates represented turns or scenarios under an English wrapper, each turn's language comes from that turn's own request text, and neither the wrapper's language nor the number of scenarios changes it.

The precedence below classifies an instruction that could match more than one row; the goal-alignment gate precedes every item. Each original precedence item maps to a row:

1. Lifecycle commands and unrelated top-level invocations → workflow-control.
2. Stale-context clarification before routing → workflow-control.
3. Active artifact continuation or revision → the row that owns the active artifact (requirements-specification, implementation-planning, plan-execution, plan-pre-check-walkthrough, review, or writing).
4. Review targets and review/fix loops → review.
5. Bug reports, regressions, failed fixes, tool failures, runtime artifact mismatches, and existing-feature repair → debug-and-repair.
6. Interactive pre-execution walkthroughs of a saved implementation plan → plan-pre-check-walkthrough.
7. Commit, staging, and history-repair execution requests → commit-execution.
8. Wording-only deliverables with no review target or Definition-of-Done triage → writing.
9. Clear execution requests for concrete implementation plans → plan-execution.
10. Read-only code-investigation questions with no defect report or edit request → code-investigation.
11. Idea-generation, direction-exploration, or convention-check requests that do not ask for a saved requirements artifact → creative-direction-exploration.
12. Implementation planning for approval-evidenced specs or inputs that need a plan before execution → implementation-planning.
13. Requirements specification for new vague, rough, contradictory, creative, non-technical, or underspecified coding goals → requirements-specification.
14. no matching specialist fallback → workflow-control.

The router-owned rows direct-implementation and then maintenance are classified between items 12 and 13, and always before item 14: a concrete edit or a maintenance unit is not the terminal fallback and never reports matched-but-unavailable.

Before any plain commit

For every consolidation block this package carries, here and in its references: where this package declares a stricter or narrower rule in its own text, that declaration controls. For every gate and schema block this package carries, here and in its references: this package may state which of its phases the block applies to; it may not change the block's inputs, outcomes, or fields.

Never run a plain git commit without naming the selection source it rests on.

• With no user-installed hook enforcing this gate, this wording is the whole gate: apply it yourself before the command runs.
• Name one recorded source before committing: the current user's request (user-turn), the bound plan item (bound-plan-item), or the workflow's own checkpoint of a verified unit (specialist-checkpoint).
• Treat agent-proposed as a recorded proposal, never a selection.
• When the workflow is router-bound, have the router record that source as a commit-selection event before the command runs.
• For a standalone commit with no router active, name the direct current-user request or the verified checkpoint handoff and follow the phase's ordinary confirmation policy.
• When no source can be named, do not commit; ask the user whether a commit is wanted.
• Return allow when the command is not a commit.
• Return ask on every plain commit, quoting from the session record under .plans/vibe-sessions/ the recorded phase and the most recent recorded commit-selection event's source, at, and note.
• Or state that no commit-selection event is recorded, or that the record is absent, malformed, stale, foreign, session-unbound, or conflicting.
• Never return deny from this gate.
• Never allow a plain commit silently: surface the recorded source at the prompt so a self-attested selection is caught there.
• Answer ask, never deny, for a record in any invalid state.

Exception: an amend or other history rewrite belongs to the history-mutation gate, not this one.

This gate applies to every plain commit under a vibe-coding workflow, in any row. The router records the commit-selection event named under Session Record before the command runs, whether the commit is executed by the visible commit-execution specialist or, when none is visible, under the fallback in references/route-selection.md.

Before a history rewrite

Never rewrite git history without stopping and asking the user first.

• With no user-installed hook enforcing this gate, this wording is the whole gate.
• Before running a matched command, stop and ask the user with that reason, and proceed only on the user's answer.
• Match git commit --amend, git rebase, git filter-branch or another filter-* rewrite, git reset --hard, git push, or a scripted or looped replay that rewrites more than one commit.
• Return allow when the command is not a history mutation.
• Return ask for every matched history mutation, naming the matched operation.
• Quote from the session record under .plans/vibe-sessions/ the recorded phase, effect_mode, and the kind and source of every recorded event bearing on it.
• Or state that the record is absent, malformed, stale, foreign, session-unbound, or conflicting, or that no such event is recorded.
• Never return deny from this gate.
• Never allow a matched history mutation silently, whatever the record says: surface the recorded values at the prompt so a self-attested record is caught there rather than trusted.
• Treat history that has left this machine — pushed, fetched by another clone, or otherwise published — as shared; no recorded value makes rewriting it silent.
• Let the record decide only the wording of the reason, never the outcome.
• Answer ask, never deny, for an absent, malformed, stale, foreign, session-unbound, conflicting, or identity-mismatched record.

Exception: a plain git commit belongs to the commit-selection gate, not this one, and a read-only git command is not a history mutation.

This gate applies to every shell action under a vibe-coding workflow, in any row, the router-owned rows included. The router renews the record's lease immediately before a matched command and, when no hook enforces the gate, asks with the wording above before running it.

Before a write in a read-only or artifact-only phase

Never write a path your phase's effect class and recorded allowed_paths do not permit.

• With no user-installed hook enforcing this gate, this wording is the whole gate.
• Count as a write any file-edit or file-write tool call, and any shell command that writes a path — redirection, sed -i, tee, a heredoc, mv, cp, rm, git checkout --.
• In a read-only phase, write only an explicitly requested saved artifact whose canonical path is recorded in allowed_paths; otherwise write no file.
• In an artifact-only phase, write only the artifact it owns, the supporting paths its own text declares, and the scratch root recorded for the unit.
• Refuse a write outside that boundary in the phase itself and report it as a boundary stop.
• Report a denied write verbatim as a boundary stop; never retry it through another tool.
• Return deny only for a fresh, valid, session-bound read-only or artifact-only record whose canonical target lies outside every allowed_paths entry and recorded directory.
• Name the target path in that reason and quote the recorded phase, effect_mode, and allowed_paths.
• Return allow in every other case: a target inside allowed_paths, an effect_mode of state-changing or none, or a record absent, malformed, stale, foreign, session-unbound, conflicting, or identity-mismatched.
• Never return ask from this gate.
• Never let an invalid record state produce deny, so the refusal never rests on unverified host behavior.

Example: in an artifact-only phase whose allowed_paths holds only the artifact it owns, a write to that artifact is inside the boundary; a write to a source file is outside it, and with a fresh, valid, session-bound record the gate returns deny.

Exception: writing the router's own record — .plans/vibe-sessions/<record_id>.json or its rename temp file — is allow at any effect_mode, not a phase write; judge every other path there like any other path, and allowed_paths does not widen.

This gate applies while the recorded row is creative-direction-exploration, code-investigation, requirements-specification, implementation-planning, plan-pre-check-walkthrough, or writing; the state-changing rows and workflow-control are outside it.

Commit selection

Only an explicit user request, a bound plan item, or a workflow's own verified checkpoint selects a commit.

• Select a commit from exactly three sources: an explicit current-user request; a bound approved plan item requiring that checkpoint; or a state-changing workflow closing its own verified, reviewed, in-scope unit under its checkpoint default.
• Never let routing or invocation, edit permission, a convenient stopping point, tracked changes in the working tree, or an available commit-execution workflow select a commit.
• Never treat an unverified unit as a handoff.
• Execute in commit-execution only the commits those sources select; that phase has no checkpoint default of its own.
• Close a self-contained unit of the workflow's own work with a local commit of exactly that unit once it is implemented, verified, reviewed, and its material findings dispositioned.
• Commit that unit without waiting for a separate commit instruction.
• Never let a multi-unit run accumulate as one undifferentiated working tree.
• When the default is suspended, leave the verified changes in the working tree and report the reason.
• Let the checkpoint default reach only local commits of the unit's own verified changes.
• Select no commit from discovery-only, blocked, unchanged, failing, unverified, or work-in-progress state.
• Never widen the staged set beyond the verified unit.
• Exclude pre-existing working-tree changes the workflow did not make, an artifact whose tracked status would itself be new, and paths outside the unit.
• Never treat an available commit-execution workflow or ambient tracked status as a reason to include them.
• When the unit's changes cannot be separated from unrelated working-tree state, report the mixed state and ask instead of committing.
• Route every selected commit through the commit-execution workflow with the verified scope, its test and review evidence, its unrelated-path exclusions, and any proposed message.
• Leave staging, file-set and exact-diff review, message transport, history safety, and post-commit verification to that workflow.
• Never read a request to commit as a request to push.
• Keep push, release preparation, version changes, tags, amend, rebase, reset, stash, squash, destructive actions including cleanup, force-adds, tracking a newly created artifact, external side effects, and unrelated or ambiguous paths separately consent-bound even when a checkpoint was selected.
• Never let a route, checkpoint, or handoff implicitly authorize them.

Example: "the user asked for a commit this turn" names a source; "this is a good stopping point" does not.

Exception: a current no-commit instruction, a bound plan that forbids commits, or project policy against commits suspends the checkpoint default.

For a router-owned row this skill is the state-changing workflow the contract names: its verified edit closes under the checkpoint default, recorded with specialist-checkpoint as the selection source. For a routed row the checkpoint belongs to the specialist; the router records the selection and routes the history action. When a unit's changes cannot be separated from unrelated working-tree state, the router records no new commit-selection event for that blocked checkpoint, reports the mixed state, and asks instead of committing.

What this phase may write

Write nothing beyond what the phase's own effect class and its declared boundary permit.

• Declare exactly one effect class for every workflow phase, in that phase's own text.
• In a read-only phase, read and report; make chat the deliverable — findings, alignment, or direction.
• In a read-only phase, edit no source, test, config, doc, or other file, and run no command that mutates runtime or repository state.
• In a read-only phase, never stage, commit, tag, push, change versions, delete data, or start services.
• In a read-only phase, write a file only when the current user explicitly asks for a saved artifact.
• In an artifact-only phase, create or update the artifact it owns: the requirements spec, the plan, the plan-review state, the instruction files, or the text artifacts the request names.
• In an artifact-only phase, write the supporting paths its own text declares:
  • the text it was asked to revise (comments, docstrings, docs);
  • a confirmed reflection into the bound plan;
  • an ignore file it previewed and the user confirmed;
  • a narrowly confirmed configuration edit its text names;
  • a decision record or findings report its own text declares.
• In an artifact-only phase, leave those verified changes in the working tree.
• In an artifact-only phase, never implement executable behavior, never edit application code or tests as implementation, never produce an artifact another phase owns, and never perform release work.
• Never let an artifact-only phase's artifact authorize same-turn implementation.
• In a state-changing phase, edit files and run commands inside the scope its own text declares — the unit it implements, the repair it proves, the fixes it applies, the round it integrates, or the commit it executes.
• In a state-changing phase, keep its edits to the smallest verified unit of that scope.
• In a state-changing phase, leave paths outside the scope, pre-existing working-tree changes the phase did not make, and runtime or external state beyond the scope unwritten unless the current user selects them.
• Keep every irreversible or outward-facing operation under its own consent.

Each row's class is stated in its owner cell: the router-owned rows direct-implementation and maintenance are state-changing, and workflow-control writes nothing. The router records the active row's class as effect_mode and its declared write boundary as allowed_paths. The router-owned state-changing rows also write docs/decisions/ and docs/reports/findings/ under Durable Records; workflow-control writes neither.

Durable Records

Before recording a settled decision, deferring a finding, closing a unit, or starting this phase, read references/durable-records.md. The router-owned rows direct-implementation and maintenance write docs/decisions/ and docs/reports/findings/, or the repository's existing record directory, as declared supporting paths; workflow-control writes neither.

Before a human-risk decision