vibe-backlog

CLI-first project workflow for solo builders using GitHub issues + postflight artifacts. One-liner: vibe-backlog turns issue context, git state, and postflight artifacts into one repeatable development loop.

This project has two usage modes:

• Canonical and reproducible commands (recommended for agents): pnpm build && node dist/cli.cjs ...
• Convenience commands (for shorter typing): global vibe via pnpm link --global + hash -r

Do not rely only on the global bin path. Always keep the canonical path available.

Quickstart (5 min)

Fastest path to first success in another repo:

# in vibe-backlog repo
pnpm install
pnpm build
pnpm link --global
hash -r

# in your target repo
cd /path/to/another-repo
vibe init --dry-run
vibe init
vibe preflight
vibe postflight --apply --dry-run

init now skips tracker bootstrap by default. If you want to create tracker taxonomy immediately, run:

vibe init --bootstrap-tracker

For phased sharing (pilot -> beta -> social) and copy/paste launch messages, see SHARE.md.

0) Requirements

pnpm -v
gh auth status
git --version

1) Create a new repo (local + private remote)

# 1) create folder and git
mkdir my-project && cd my-project
git init -b main

# 2) minimal gitignore
cat > .gitignore <<'EOF'
node_modules
dist
.DS_Store
*.log
.vibe/runtime
.vibe/artifacts
EOF

# 3) first commit
git add .
git commit -m "chore: init"

# 4) create private remote and push
git remote -v
# if empty:
gh repo create <NAME> --private --source=. --remote=origin --push

2) Install vibe-backlog (from the vibe-backlog repo, dev mode)

This is for developing vibe-backlog from source.

# inside vibe-backlog repo
pnpm install
pnpm test
pnpm build

# option A (recommended for agents / reproducible)
node dist/cli.cjs --help

# option B (convenience: global "vibe" command)
pnpm link --global
hash -r
vibe --help

3) Use vibe-backlog in another repo (with global bin already linked)

cd /path/to/another-repo

# one-time setup for agent-first workflow
vibe init --dry-run
vibe init
# optional: create tracker labels/milestones immediately
# vibe init --bootstrap-tracker
# compatibility alias (same default behavior):
# vibe init --skip-tracker

# now these commands are valid
vibe preflight
vibe self update --check
vibe update --check
vibe postflight
vibe postflight --apply --dry-run

If you want to avoid global bin drift, run from the vibe-backlog repo path:

node /path/to/vibe-backlog/dist/cli.cjs preflight

4) Recommended workflow (Issue-first + Postflight)

# 0) one-time setup in this repo
vibe init --dry-run
vibe init

# 1) inspect repo + issue state
vibe preflight
vibe status
vibe review --dry-run

# 2) set the real active issue id before apply
# Edit .vibe/artifacts/postflight.json and replace:
#   "issue_id": "1"
# with your real issue number, for example:
#   "issue_id": "42"

# 3) validate artifact
vibe postflight

# 4) preview tracker updates first
vibe postflight --apply --dry-run

# 5) apply for real
vibe postflight --apply
# optional: skip automatic local branch cleanup
# vibe postflight --apply --skip-branch-cleanup

preflight now prints a security snapshot (policy, gitleaks availability, last scan), a hint when .vibe exists but tracker bootstrap marker is missing, and read-only semantic milestone suggestions for issues without milestone. preflight also performs a best-effort, non-blocking tool version check and prints an explicit self update command when a newer vibe-backlog release is available. update checks/applies .vibe scaffold updates with metadata tracking in .vibe/scaffold.json, dry-run diff preview, and marker-safe preservation of protected sections. init scaffolds local .vibe files and skips tracker bootstrap by default; use --bootstrap-tracker to opt in tracker GH operations during init. init/update also scaffold a managed README workflow section (<!-- vibe:workflow-docs:start --> ... <!-- vibe:workflow-docs:end -->) with a Mermaid diagram, preserving non-managed README content. update --json includes readme_workflow_status with one of: created (workflow block created, including first insertion into an existing README), updated (existing managed block refreshed), unchanged (already up-to-date), repaired (malformed markers were repaired). status shows active turn, in-progress issues, hygiene warnings, and branch PR snapshot. ui serve boots a local cockpit shell with workspace project selector + baseline branch/turn/issue cards (node dist/cli.cjs ui serve --workspace <path>). Non-loopback hosts require explicit --allow-remote. turn start --issue <n> now auto-creates .vibe/reviews/<n>/ templates (implementation, security, quality, ux, ops) when missing. turn start --issue <n> now enforces a remote-state guard (git fetch origin, git status -sb, git branch -vv, PR state check on current branch) and blocks branch creation on behind/diverged or closed/merged-PR branch states with explicit remediation commands. postflight --apply now runs automatic local branch cleanup for upstream gone branches (safe delete for merged, force delete for patch-equivalent, non-merged require explicit manual confirmation). Use --skip-branch-cleanup to bypass it. branch cleanup provides explicit cleanup control, including dry-run planning and guarded force path for non-merged branches. security scan runs gitleaks in staged, working-tree, or history mode with configurable warn|fail policy (.vibe/contract.yml by default). review runs the 5 role passes via external agent command, retries up to --max-attempts, publishes one final PR report, and can auto-create/update a single follow-up issue per source issue when unresolved findings remain. In non-dry-run mode, when unresolved findings reach 0, it auto-closes open follow-up issues for that source marker; close failures are reported as warnings and do not fail the run. Summary counters (Findings observed, Unresolved findings, Resolved findings) use lifecycle totals from vibe-managed PR review threads plus current-run findings. pr open creates/reuses an open PR for the issue, injects deterministic architecture/rationale sections plus Fixes #<issue>, and enforces a review gate by HEAD marker (unless explicitly skipped). pr ready validates final merge-readiness (OPEN, non-draft, mergeStateStatus=CLEAN, remote head sync, review marker) and prints non-destructive remediation for stale/desync states. tracker reconcile fills missing module:* labels and milestone metadata using semantic signals (title/body/module history); when no existing milestone matches strongly, it can plan/create a repo-specific delivery milestone.

Agent workflow (AGENTS.md)

This repo supports LLM-driven development. The file AGENTS.md is the agent contract:

• Issue-first (one topic = one issue)
• Mandatory preflight -> work -> postflight
• Append-only (never overwrite user notes)
• Multi-pass reviews (Security/Quality/UX/Ops)

LLMs (Codex, Claude, etc.) must read and follow AGENTS.md before making changes.

Security

• Vulnerability reporting policy: SECURITY.md
• CI log/artifact hardening policy: .github/CI_SECURITY.md

Repository policy (publish + sharing)

Publish posture (current):

• npm publish is disabled for now; this repository is not released as a package yet.
• package.json is intentionally set to "private": true to prevent accidental publish.
• package.json uses "license": "MIT" to match LICENSE.

Default gitleaks policy for repos using .vibe:

• vibe init scaffolds .vibe/contract.yml with security.gitleaks.policy: warn.
• warn keeps scans visible but non-blocking while setup is still in progress.
• vibe does not auto-install gitleaks on user machines; installation is explicit (local toolchain and/or CI).

Manual checklist for sharing this repo with sebas / juli / fer (GitHub Admin):

1. Go to Settings -> Collaborators and teams.
2. Invite sebas, juli, and fer.
3. Set role Admin for each collaborator.
4. Confirm each invite is accepted and access works.
5. Record completion in the active issue/postflight comment for audit trail.

Canonical commands (recommended)

Use these for deterministic execution:

pnpm build
node dist/cli.cjs preflight
node dist/cli.cjs self update --check
node dist/cli.cjs self update --dry-run
node dist/cli.cjs update --check
node dist/cli.cjs update --dry-run
node dist/cli.cjs update
node dist/cli.cjs status
node dist/cli.cjs security scan --dry-run
node dist/cli.cjs security scan --mode staged
node dist/cli.cjs security scan --mode history --policy fail
node dist/cli.cjs branch cleanup --dry-run
node dist/cli.cjs branch cleanup
node dist/cli.cjs branch cleanup --force-unmerged --yes
node dist/cli.cjs review --dry-run
node dist/cli.cjs review threads resolve --pr <n> --all-unresolved --dry-run
node dist/cli.cjs review threads resolve --pr <n> --thread-id <id>
node dist/cli.cjs pr open --dry-run --issue <n> --branch <name>
node dist/cli.cjs pr open --force-review --issue <n> --branch <name>
node dist/cli.cjs pr ready --pr <n> --wait-seconds 30
node dist/cli.cjs pr ready --branch <name> --refresh --wait-seconds 30
node dist/cli.cjs init --dry-run
node dist/cli.cjs init
node dist/cli.cjs init --bootstrap-tracker
node dist/cli.cjs tracker bootstrap --dry-run
node dist/cli.cjs tracker bootstrap
node dist/cli.cjs tracker reconcile --dry-run
node dist/cli.cjs tracker reconcile --fallback-module module:core --fallback-milestone "<milestone>"
node dist/cli.cjs ui serve --workspace /path/to/projects
node dist/cli.cjs postflight
node dist/cli.cjs postflight --apply --dry-run
node dist/cli.cjs postflight --apply
node dist/cli.cjs postflight --apply --skip-branch-cleanup

vibe branch cleanup command reference

vibe branch cleanup [options]

Options:

• --dry-run: plan cleanup without deleting local branches.
• --base <name>: override base ref for merged/patch-equivalent checks (default: origin/HEAD, fallback main).
• --force-unmerged: allow deleting non-merged branches (requires confirmation).
• --yes: confirmation required when using --force-unmerged.
• --no-fetch-prune: skip git fetch --prune origin before branch detection.

Policy:

• Candidate pool: local branches with upstream gone.
• Protected branches: current branch, main, and resolved base branch.
• Deletion mode:
  • merged into base -> git branch -d
  • patch-equivalent -> git branch -D
  • merged PR with matching head SHA -> git branch -D (safe pr-merged path)
• If multiple merged PR rows exist for the same branch name, cleanup matches any row whose headRefOid equals local branch HEAD.
• GitHub PR lookup is retried with timeout; on persistent lookup failure, cleanup warns and keeps branch in guarded non-merged flow.
• non-merged -> skipped unless --force-unmerged --yes

vibe security scan command reference

vibe security scan [options]

Options:

• --mode <staged|working-tree|history>: scan scope (default staged).
• --policy <warn|fail>: override policy for current run.
• --dry-run: print resolved command/policy without running gitleaks.

Policy resolution:

1. --policy flag (if provided)
2. .vibe/contract.yml -> security.gitleaks.policy
3. default warn

Behavior:

• warn: findings/missing gitleaks are reported but do not fail command.
• fail: findings/missing gitleaks fail command (exit code 1).
• Last scan summary is stored at .vibe/runtime/security-scan.json for preflight visibility.

Portability note:

• The CLI security scan is intended for any repo using .vibe + vibe.
• This repository includes CI wiring for gitleaks; vibe init does not scaffold that workflow yet.

CI setup/troubleshooting (gitleaks workflow):

• Symptom: GitHub Actions run fails with startup_failure and No jobs were run.
• Root cause: repository Actions policy blocks non-owner actions, so the workflow is rejected before job startup.
• This workflow requires these external actions:
  • actions/checkout@v4
  • pnpm/action-setup@v4
  • actions/setup-node@v4
• Safer restricted option (recommended): in GitHub Settings -> Actions -> General, keep restricted policy and add the exact actions above to the allow list.
• Simple fallback: set Actions permissions to allow all actions and reusable workflows.
• Verification: rerun the gitleaks workflow and confirm job security-scan starts (not No jobs were run) and reaches Run vibe security scan (fail policy).

vibe tracker reconcile command reference

vibe tracker reconcile [options]

Options:

• --dry-run: build and print reconcile plan only.
• --fallback-module <name>: module label/name to use when module inference is uncertain.
• --fallback-milestone <title>: milestone title to use when milestone inference is uncertain.

Behavior:

• Default mode applies updates (gh issue edit) to open issues with missing module:* or milestone.
• If milestone affinity is low, reconcile generates a delivery-goal milestone title (<Area>: <Objective>) and creates it before issue assignment.
• preflight remains read-only; milestone creation happens only in write flows (e.g. reconcile/apply flows).
• Reconcile never removes/replaces existing module labels or milestone; it only fills missing metadata.

vibe review command reference

vibe review [options]

Options:

• --issue <n>: issue override (highest priority).
• --agent-provider <auto|codex|claude|gemini|command>: provider selection (default auto).
• --agent-cmd "<cmd>": explicit external command (highest priority). Fallback: VIBE_REVIEW_AGENT_CMD.
• --dry-run: run planning path without mutating git/GitHub.
• --no-autofix: disable agent autofix mode.
• --no-autopush: disable final auto commit/push.
• --no-publish: skip PR summary/review/inline publication.
• --max-attempts <n>: max retry attempts (default 5).
• --compute-class <L1-fast|L2-standard|L3-deep|L4-critical>: policy preset for agent invocation retry resilience + conservative pruning.
• --strict: exit non-zero when unresolved findings remain after final attempt.
• --followup-label bug|enhancement: override follow-up issue label.
• --rationale-signals-json: print machine-readable rationale signal extraction details (profile, modules, fallback_reasons).
  • Output contract: JSON includes schema_version: 1 for compatibility checks.

Compute class notes:

• --compute-class does not change --max-attempts (findings/autofix loop).
• It controls retry resilience for agent invocation failures (timeouts/transient provider errors) inside a single review attempt.
• It can activate conservative docs-only pruning; output still includes all 6 passes, and pruned passes are emitted as skipped by policy.
• Defaults:
  • vibe review manual: L3-deep
  • vibe pr open auto-review gate: L2-standard

Issue/base context resolution (without requiring an active turn):

1. --issue <n> (if provided)
2. valid active turn
3. branch inference:
   • issue-<n>-...
   • <feat|fix|chore|docs|refactor|test>/<n>-...
4. open PR body autoclose references (Fixes #<n>, Closes #<n>, Resolves #<n>)

If issue resolution still fails, command exits with remediation to provide --issue <n>.

Follow-up issue behavior:

• Unresolved findings after final attempt (max-attempts) create/update a single follow-up issue.
• All issue creation flows in vibe use gh issue create --body-file (never inline --body) to preserve markdown formatting.
• Non-dry-run with unresolved findings 0 attempts to auto-close open follow-up issues for the same source marker.
• Auto-close failures are emitted in the review summary warnings and do not abort vibe review.
• Review prompt treats .vibe/reviews/<issue>/*.md and .vibe/artifacts/postflight.json as expected generated artifacts (not unplanned changes by themselves).

Postflight review metrics:

• review_metrics.phase_timings_ms: latest per-phase elapsed/status snapshot for the run.
• review_metrics.phase_timings_delta_ms: delta in milliseconds vs previous persisted snapshot (null when no previous snapshot exists).
• review_metrics.phase_timings_ms_history: bounded snapshot history (latest 20 entries) to compare trend changes within/after review runs.

Provider resolution (highest priority first):

1. --agent-cmd
2. VIBE_REVIEW_AGENT_CMD
3. --agent-provider forced mode (codex|claude|gemini|command)
4. --agent-provider auto (default):
   • persisted provider in .vibe/runtime/review-agent-provider.json
   • current host detection
   • available provider binaries/env overrides (codex > claude > gemini)

Provider-specific env overrides:

• VIBE_REVIEW_CODEX_CMD
• VIBE_REVIEW_CLAUDE_CMD
• VIBE_REVIEW_GEMINI_CMD

Codex same-session behavior:

• If CODEX_THREAD_ID exists, vibe review first tries codex exec resume <thread_id>.
• If resume fails or returns invalid JSON, it falls back to external non-interactive Codex execution.
• This is best-effort only; resume unavailability does not fail the run by itself.

Review policy marker:

• Review summary comments embed a v2 policy marker that includes core review flags plus compute_class and pass_profile.
• pr open / pr ready preserve legacy marker compatibility and can ignore pass_profile differences for gate dedupe in the MVP.

vibe pr open command reference

vibe pr open [options]

Options:

• --issue <n>: issue override.
• --branch <name>: branch override.
• --base <name>: base branch override.
• --dry-run: print PR payload plan only.
• --rationale-signals-json: print machine-readable rationale signal extraction details (profile, modules, fallback_reasons).
  • Output contract: JSON includes schema_version: 1 for compatibility checks.
• --skip-review-gate: bypass review gate and publish an auditable PR comment marker.
• --force-review: force review rerun even when existing gate markers satisfy the current HEAD.

Review gate behavior:

• Default pr open enforces review execution for the target PR branch HEAD (resolved from --branch/turn/current branch).
• Dedupe is marker-based on PR comments: <!-- vibe:review-summary --> + <!-- vibe:review-head:<sha> --> (+ optional <!-- vibe:review-policy:<key> -->).
• Progressive compatibility:
  • legacy summary comments without policy marker still satisfy gate for matching HEAD.
  • if policy marker exists, pr open requires HEAD + policy match.
• If marker is missing, pr open auto-runs vibe review (L2-standard profile, non-strict).
• If --force-review is set, pr open reruns vibe review even when gate markers already match.
• For non-dry-run gate execution, target branch must be checked out before auto-review can run.
• If --skip-review-gate is set, no auto-review runs; PR receives <!-- vibe:review-gate-skipped -->.
• --skip-review-gate and --force-review are mutually exclusive.
• If pr open creates a PR and auto-review fails, the PR remains open and command exits with error.

vibe pr ready command reference

vibe pr ready [options]

Options:

• --pr <n>: PR number override.
• --branch <name>: branch override when resolving open PR without --pr.
• --refresh: run git fetch origin before readiness checks.
• --wait-seconds <n>: wait/poll window for mergeStateStatus=UNKNOWN (default 0).

Behavior:

• Resolves exactly one open PR target (--pr explicit or by branch lookup).
• Requires:
  • PR state=OPEN
  • PR isDraft=false
  • mergeStateStatus=CLEAN
  • git ls-remote --heads origin <headRefName> equals PR headRefOid
  • review gate marker exists for current HEAD + policy key
• On stale/unknown/desync failures, prints deterministic remediation:
  • node dist/cli.cjs pr ready --pr <n> --refresh --wait-seconds 30
• On success, prints freeze guidance before merge:
  • do not run vibe review, vibe pr open, or push new commits.

vibe review threads resolve command reference

vibe review threads resolve [options]

Options:

• --pr <n>: PR number override. If omitted, resolve against the open PR for the current branch.
• --thread-id <id>: target thread id (repeatable). Single-target mode.
• --all-unresolved: batch mode for all unresolved threads on the target PR (including outdated threads).
• --body <text>: optional manual reply body (overrides auto-generated detailed body).
• --dry-run: show plan without replying/resolving.

Rules:

• Exactly one targeting mode is required: --thread-id (one or more) or --all-unresolved.
• In apply mode, each selected thread gets:
  1. reply comment (addPullRequestReviewThreadReply)
  2. resolve mutation (resolveReviewThread)
• Auto-body (when --body is not provided) includes: PR, HEAD, thread id, outdated status, location, finding title/severity/pass and fingerprint when available.

Vibe Workflow (Managed)

This section is managed by vibe init / vibe update.

flowchart LR
    A["preflight"] --> B["pick issue"]
    B --> C["implement + tests"]
    C --> D["postflight"]
    D --> E{"apply updates?"}
    E -- "dry-run" --> F["postflight --apply --dry-run"]
    E -- "yes" --> G["postflight --apply"]
    G --> H["tracker synced"]

Loading

Workflow steps (text fallback):

1. Run vibe preflight.
2. Pick one issue and keep scope focused.
3. Implement and run tests/build.
4. Validate vibe postflight.
5. Preview tracker changes with vibe postflight --apply --dry-run.
6. Apply tracker updates with vibe postflight --apply.