Skip to content

How to contribute

Thanks for considering a contribution. vibecodingisold is a knowledge-injection layer, not a typical code library, so contribution conventions are stricter than usual — every change touches the canonical knowledge that downstream users rely on for production decisions.

The canonical contributor doc is at CONTRIBUTING.md at the repo root. This page summarizes; defer to the canonical file when in doubt.

What we accept

  • Bug fixes to existing items — wrong source citation, broken cross-reference, misaligned Numerical Contract, typo in code example.
  • New items proposed for V1.1+ — must follow the 9-field item template and cite >=2 Tier-1 primary sources. See Adding Items.
  • New profile proposals for V2 — must include the trigger logic, the Mandatory subset filter, and at least one worked example. Open a Discussion first; new profiles touch every integration.
  • Integration improvements — bug fixes to existing integrations under integrations/, or proposals for new tool integrations.
  • Plugin improvements — bug fixes to commands, skill, or smoke-test under plugins/vibecodingisold/.
  • Worked example improvements — fixing inaccurate item references, adding missing items, refining the Step 5 delta-bilanz numbers if they drift.
  • Methodology refinements — methodology/brain-worker-orchestration.md accepts pull requests for clarity, missing patterns, or lessons-learned additions.
  • Documentation improvements — typos, broken links, clarifications in docs/, README.md, or any of the cross-cutting reference files.

What we do NOT accept (without prior discussion)

  • Items without Tier-1 sources or without the 9-field template filled. See Source Tier System.
  • Changes to Numerical Contracts (core/_conflict-resolutions.md) — these are binding across all roles. Open an issue first. See Numerical Contracts.
  • Direct edits to core/PLAN-REQUIREMENTS.template.md — it is regenerated from role files. Edit the source role file instead.
  • Changes that break the source-of-truth hierarchy (see below).
  • Direct edits to plugins/vibecodingisold/core/* — that's the vendored copy. Edit canonical core/* and re-run sync-core.ps1 or .sh.
  • Profile-list expansions in V1.x — V1 ships 6 profiles; new ones are V2 work because they touch every integration.
  • Stack changes in item code snippets without a coordinated multi-file PR — V1 default stack is TypeScript+Node+Postgres throughout.

Source-of-truth hierarchy

When in doubt about which file to edit:

  1. core/_conflict-resolutions.md — Brain decisions, BINDING. Numerical Contracts are non-negotiable.
  2. core/roles/<role>.md — canonical item definitions. All other files are derivatives.
  3. core/PLAN-REQUIREMENTS.template.md — master aggregate. If it diverges from a role file, the role file wins.
  4. core/profiles/*.md — filtered subsets. Must stay consistent with role files.
  5. integrations/* — tool-specific re-formats. Acceptable lag behind role files.
  6. plugins/vibecodingisold/core/* — vendored copy of root core/. Always sync via scripts/sync-core.ps1 or .sh — never edit directly.

Contribution workflow

1. Open an issue first (for non-trivial changes)

For anything beyond a typo or broken link, open an issue first. The issue templates under .github/ISSUE_TEMPLATE/ cover the common cases:

  • bug_report.md — broken behavior, wrong source, misaligned contract.
  • new_item_request.md — proposing a new Mandatory item.
  • profile_request.md — proposing a new project-type profile.

The issue gets a pre-discussion before you spend time on a PR that may not match the project's direction.

2. Fork, branch, edit

Standard GitHub flow. Branch naming convention: <type>/<scope>-<short-description>. Examples:

  • fix/backend-item-12-webhook-tolerance.
  • feat/security-item-53-tls-cipher-pinning.
  • docs/quick-start-cline-clarification.

3. Run validators locally before pushing

pip install jsonschema
python .github/scripts/validate-items.py
python .github/scripts/validate-numerical-contracts.py
python .github/scripts/validate-cross-references.py
python .github/scripts/validate-plugin-sync.py
bash .github/scripts/validate-plugin-fresh-install.sh   # POSIX
# or: .\.github\scripts\validate-plugin-fresh-install.ps1   # Windows

If any validator fails, fix the issue locally before opening the PR. CI will fail anyway, and the maintainer's review time is the constrained resource.

4. Commit message format

Conventional Commits format. Examples from the existing log:

  • phase 7: pre-launch closeout — placeholders, methodology, counts, ASVS.
  • phase 6: launch assets (README polish + worked examples + posts).
  • feat(plugin): add audit command with read-only gap report.
  • fix(security item 8): clarify RLS-and-helper as defense in depth.

One logical change per commit. The maintainer rebases atomic commits when merging large PRs.

5. Open the PR

Use the PR template at .github/PULL_REQUEST_TEMPLATE.md. It asks for:

  • Summary of the change (what / why).
  • Which files were touched (canonical role file + propagated derivatives if applicable).
  • Validators run locally (with output).
  • For new items: source citations with tier classification.
  • For Numerical Contract changes: link to the prior approval issue.

6. Respond to review

The maintainer reviews PRs as time permits — solo maintainer, best-effort response. PRs that pass validators and follow the templates get merged faster than PRs that need clarification rounds.

If the PR sits with no response for >10 days, comment on it to ping. The maintainer doesn't ghost intentional contributions; sometimes life intervenes.

Specific contribution guides

Fixing a bug in an existing item

  1. Edit the canonical role file under core/roles/<role>.md.
  2. Check core/_cross-references.md — propagate to dependent items if needed.
  3. Check the 8 Numerical Contracts in core/_conflict-resolutions.md — if your change touches one of those values, update every file it appears in.
  4. Re-generate or patch core/PLAN-REQUIREMENTS.template.md to reflect the change.
  5. Re-generate or patch any affected core/profiles/<profile>.md.
  6. Re-vendor the plugin core: plugins/vibecodingisold/scripts/sync-core.ps1 (Windows) or sync-core.sh (POSIX).
  7. Run plugins/vibecodingisold/scripts/smoke-test.ps1 (or .sh) to verify nothing is broken.
  8. Open a PR with one logical change per commit.

Adding a new item

See Adding Items for the full re-brief pattern.

Plugin development workflow

When changing anything under plugins/vibecodingisold/:

  1. Edit the source files (commands, SKILL.md, scripts).
  2. If you touched anything that consumes core/ files, run sync-core.ps1 or .sh.
  3. Run smoke-test.ps1 or .sh — it should pass with 0 errors.
  4. Test the install locally: /plugin uninstall vibecodingisold@vibecodingisold then /plugin install vibecodingisold@vibecodingisold.
  5. Verify a slash command works in a real project terminal.

Reporting bugs

Use the issue templates in .github/ISSUE_TEMPLATE/:

  • bug_report.md — broken behavior, wrong source, misaligned contract.
  • new_item_request.md — proposing a new Mandatory item.
  • profile_request.md — proposing a new project-type profile.

For security-sensitive issues (e.g., a Mandatory item teaches an insecure pattern), email instead of opening a public issue. See SECURITY.md for the disclosure process.

Code of conduct

This project follows the Contributor Covenant 2.1. Be respectful of contributors at all skill levels and be specific about technical disagreements.

License

By contributing, you agree your contribution is licensed under MIT.