Skip to content

Plugin customization

The plugin is intentionally simple — three commands, one canonical knowledge base, one filter. Customization happens at four layers: the artifact, the profile, the items, and the stack defaults. Each layer has a different cost-of-change.

Layer 1 — Override the generated artifact (zero-cost)

The simplest customization: regenerate PLAN-REQUIREMENTS.md, then edit it manually before handing it to your planning tool. This is the right path when:

  • Your project has one Mandatory item that genuinely doesn't apply (rare; document the deferral with a trigger).
  • You want to add project-specific notes inline next to items (vendor choice, SLO numbers, etc. — these are the founder-decisions explicitly out of Stage 2 scope).
  • You want to merge in items from another profile (multi-profile projects — see Profiles overview).

The artifact is yours after generation. The plugin doesn't track it, doesn't auto-update it, doesn't lock fields. Re-running init overwrites it (with confirmation), so save your edits or commit them before re-running.

Cost: zero. Lifecycle: until you re-run init.

Layer 2 — Override the profile (one-time)

When the canonical profile filter doesn't match your project's reality:

  • Your B2B SaaS skips multi-tenancy because it's strictly single-customer-per-installation (unusual but real).
  • Your internal tool actually has external auditors using it occasionally (it's no longer "internal").
  • Your AI wrapper has a side LLM that's not on the user path — you don't want the prompt-injection items firing.

Two options:

Option A — pass --profile <other> to init to use a different canonical profile that better matches.

Option B — fork the profile. Copy core/profiles/<closest>.md to core/profiles/<your-name>.md, edit the activation list, and pass --profile <your-name> to init. Track this fork as a maintenance item in your project's .planning/.

If your fork would be useful to others, propose it as a V2 profile via GitHub Discussions. New profiles touch every integration, so they're V2 work, not V1.x.

Cost: ~30 minutes if you're disciplined about documenting the activation-list deltas. Lifecycle: the fork lives in your repo until you upstream it or the upstream profile changes meaningfully.

Layer 3 — Add custom items (one-time per item)

When your project type has Mandatory items not yet in V1:

  • A regulated industry (FedRAMP, FINRA-supervised, IRBs) with named audit-trail or evidence-collection requirements.
  • A specific vendor's anti-pattern that bit you ("don't use Cognito with custom user pools because…").
  • A pattern that emerged from your own postmortem you want institutionalized for the team.

The clean path is to follow the Adding Items workflow:

  1. Edit a role file under core/roles/<role>.md (the canonical source-of-truth).
  2. Use the 9-field item template at .planning/worker-briefings/_shared/item-template.md.
  3. Cite >=2 Tier-1 sources from .planning/worker-briefings/_shared/source-tier-index.md.
  4. Update affected profiles (core/profiles/*.md).
  5. Re-vendor the plugin: plugins/vibecodingisold/scripts/sync-core.ps1 (Windows) or .sh (POSIX).
  6. Run the smoke test to verify nothing broke.

Cost: 1-3 hours per item if you have the source citations ready and the failure mode pinned. Lifecycle: lives in your fork; PR upstream if it's project-type-general, not project-specific.

For project-specific items that won't generalize, the better path is Layer 1 — add them as inline notes in PLAN-REQUIREMENTS.md after generation.

Layer 4 — Override the default stack

V1 default stack is TypeScript + Node + Postgres. The minimum-implementation code snippets in items use that stack. If your project uses something else:

Pass --stack <stack> to init — but be aware that V1 doesn't yet swap code snippets per stack. The argument is recognized; stack-specific snippet swap is V1.x work. Until then, the items still apply (the what is stack-independent), and you treat the code snippets as illustrations.

Item template field 3 ("Minimum implementation") is stack-specific — V1 uses TypeScript+Node+Postgres because that's the highest-density combination in the AI-tool training corpus. Items still apply to:

  • Python+FastAPI+Postgres
  • Go+stdlib+Postgres
  • Ruby+Rails+Postgres
  • Elixir+Phoenix+Postgres
  • Kotlin+Ktor+Postgres
  • TypeScript+Bun+Postgres / TypeScript+Deno+Postgres

Database swaps (Postgres → MySQL, Postgres → DynamoDB, Postgres → CockroachDB) require more care — some items are Postgres-specific (RLS, partial indexes with WHERE-clause). The role files name those items explicitly.

Cost: zero for using the items as-is; days-to-weeks if you fork the role files to swap stacks throughout. Lifecycle: if you fork, you maintain the divergence indefinitely.

Layer 5 — In-house fork (last resort)

If your organization wants a stable, controlled, in-house version of vibecodingisold:

  1. Fork the repo to your org. Keep upstream as a remote.
  2. Vendor the plugin into your internal Claude Code marketplace (or use it directly via /plugin marketplace add <your-org>/vibecodingisold-internal).
  3. Set up a quarterly upstream-sync ritual — pull canonical changes, resolve merges, re-vendor the plugin.
  4. Track your divergence in your fork's CHANGELOG-divergence.md.

Cost: ~2-4 hours per quarter to keep current. Lifecycle: indefinite.

This is the right choice if:

  • Your org has compliance requirements that prohibit external marketplace installs.
  • You have proprietary items you can't upstream.
  • You have a dedicated platform team that maintains the fork as part of their charter.

It is overkill for individual projects. For those, Layer 1 + Layer 4 are sufficient.

What you should NOT customize

Some things are deliberately rigid because the value collapses if they bend:

  • The 8 binding Numerical Contracts. Idempotency-Key TTL = 24h, webhook timestamp tolerance = 300s, etc. Changing one in your fork breaks the cross-references between roles and the validators in CI. If a contract is wrong for your project, write a documented ADR-style override in your PLAN-REQUIREMENTS.md rather than changing the canonical value. See Numerical Contracts.
  • The 9-field item template. Items missing fields fail the validator. The template shape is what makes items legible to planning tools.
  • The Tier-1 source requirement. >=2 Tier-1 primary citations per item. Tier-2 may supplement; Tier-3 is forbidden. See Source Tier System.
  • The plugin's core/ vendoring. Edit canonical core/ and re-vendor with sync-core.*. Direct edits to plugins/vibecodingisold/core/* fail the validator and the smoke test.

Where customization patterns are documented

  • The full canonical contract: CONTRIBUTING.md at the repo root.
  • The 9-field template: .planning/worker-briefings/_shared/item-template.md.
  • The source tier index: .planning/worker-briefings/_shared/source-tier-index.md.
  • The conflict resolutions and Numerical Contracts: core/_conflict-resolutions.md.
  • The cross-reference graph: core/_cross-references.md.

If a customization you want isn't documented above, open a GitHub Discussion. We're keeping V1 simple; V1.x will document the patterns that emerge from real adoption.