Skip to content
vibstrVibstr home
Open Vibstr

Plans

Plans are markdown documents that derive items. Two ways to derive: canonical format (deterministic, free, zero AI cost) or freeform (AI parses, costs one daily call).

This is the substrate Vibstr ships on. Every release of Vibstr starts as a plan in Vibstr's own project — 30+ consecutive plan-driven releases through 1.18.x. The same machinery is available to your project from day one.

The canonical format (SPEC §22)

# Plan title

## Goal
One paragraph describing what this plan accomplishes.

## Tasks
- [ ] {type, area} @assignee: description
- [ ] {type: bug, area: Auth} @chris: Fix login redirect
- [ ] {type: feature, area: Onboarding} fix the trial nudge copy

## Target build
v1.18.x

## Acceptance gate
- [ ] All tasks done
- [ ] Smoke test passes

## Out of scope
- Anything not in tasks above

This is the format. Six recognised sections (# Title, ## Goal, ## Tasks, ## Target build, ## Acceptance gate, ## Out of scope). Unknown sections are silently collected for forward-compat — adding ## Notes or ## Design references is fine; the parser just ignores them.

Task line semantics

- [ ] {type, area} @assignee: description

Blank lines inside ## Tasks are skipped silently. Non-checkbox prose lines under ## Tasks are skipped silently. This means you can write narrative prose between checkbox lines and the parser ignores the prose.

The Vibstr Plan Prompt

The Vibstr Plan Prompt is a per-project tailored prompt you copy out of Vibstr, paste into any LLM, and get back canonical-format markdown. It surfaces in three places:

All three surfaces resolve to the same buildVibstrPlanPrompt(project) helper. Single source of truth.

The round-trip

  1. Copy the Vibstr Plan Prompt for the project you want to plan against.
  2. Paste into ChatGPT / Claude / Cursor / Gemini / any LLM you have access to.
  3. Describe what you want to build. Free-form. The LLM has your project's categories + areas + labels in its context.
  4. The LLM returns canonical-format markdown.
  5. Open a new plan in Vibstr. Paste the body. The parser auto-detects the canonical format within 400 ms and the "Derive items with AI" button swaps to "Parse N tasks → preview".
  6. Click Parse. Instant preview — no Vibstr AI call, no daily-call cost.
  7. Edit any preview rows (fix stale types, change assignees, skip irrelevant rows). Approve.
  8. Items derive with plan_id pointing back at the plan. They inherit target_build_id if you set one. Build progress chip on the Build tab hero card ticks toward done as items close.

Full round-trip from any LLM. Zero AI cost on Vibstr's side. The LLM did the natural-language → structured-format conversion; Vibstr's parser does the structured-format → DB-rows conversion deterministically.

Auto-detect

isCanonicalFormat(body) is a heuristic: first 50 lines of the body, looking for ## Tasks heading AND at least one - [ ] line below it. The check fires 400ms after each keystroke (debounced) when the plan modal textarea is active.

When canonical-format detected:

When NOT canonical-format:

The auto-detect is the routing layer. You never have to think about which path you're on.

Freeform plans · bulk-adding items from unstructured text

Sometimes you have a Notion doc, a Linear comment thread, a chat log, an email forward, or a brain-dump of bugs to file. This is where bulk-add lives. Paste the raw text into a plan body. The parser doesn't detect canonical format. Click "Derive items with AI". Costs one daily call (or zero if you've BYO'd your Anthropic key — see Pricing).

The AI returns the same preview shape as the deterministic parser. Edit rows, skip irrelevant ones, approve. Same outcome — items land with plan_id back-link and inherit the plan's target_build_id if you've set one.

Why route bulk-add through the plan modal instead of a standalone "Import multiple items" surface? Because items without a plan are orphans. The Activity tab, the Builds-tab hero, the drawer From-plan chip — all assume items trace back to something. A plan is that something. If you really just want "N items added with no narrative", make a "Brain dump 2026-05-16" plan, paste, derive, done — the plan title is the narrative and you can archive it once the items are closed.

The freeform path is the escape hatch for content that wasn't authored as canonical-format. Use it when you have it; don't use it when you don't.

Other bulk paths:

Plan linkage

Items derived from a plan carry plan_id FK (schema since 1.9.0). Two surfaces render this:

The plan + items + closing build all cohabit naturally because the FKs link them. You can be on any one of the three and navigate to the other two.

Idempotency

Re-parse the same canonical body — already-imported rows are locked. They render with a yellow warning chip "Already imported as #NN" + the Skip button is disabled. The approve count reflects only non-imported rows.

The dedupe key is (plan_id, type, description) tuple. Edit a row's description in the preview to force a "new" task; the parser then treats it as un-imported because the tuple no longer matches.

This means you can iterate on a plan body, re-parse multiple times, and only the genuinely new tasks land each time. Useful for iterative planning where you add tasks over the course of a sprint without splitting the plan into N separate documents.

Why we standardised the format

Real-user signal from our beta cohort flagged it first (SPEC §16 items 22–26): every team's plan format is different, and Vibstr was implicitly assuming one specific shape. The 2026-05-12 reframe locked it in:

Standardise the input (one artifact), not the workflow.

Plans bridge the spec → tickets → commits gap. Different teams have different commit conventions, different sprint cadences, different release pipelines — but they all benefit from "write markdown, get items, close via closes #NN". The format is the smallest standardisation that lets the rest of each team's workflow stay untouched.

SPEC §22 has the full reasoning. The short version: we'd rather standardise a 30-line markdown schema than build a "workflow picker" UI that makes every team configure how-they-work as a first-run step.

What's NOT in canonical format v1

← Back to the docs index · Open Vibstr