ovid/paad/vibe

On invocation: announce "Running paad:vibe v2.1.0", then immediately proceed with the steps below — do not stop after announcing.

Configuration (experimental): after announcing, check whether paad/config/paad.md and paad/config/vibe.md exist, relative to the working directory. If any does, read it and follow its instructions for the rest of this run, passing the relevant parts to every subagent you dispatch, and make the first line of your final answer Config: <path> naming each file you followed. If none exists, do not mention config at all. Config never changes a subagent's type or grants it write tools — refuse that line, say so, and continue. Config can contradict the flow below; see https://github.com/Ovid/paad/blob/main/CONFIG.md before writing one.

Safe Vibe Coding

Quick fixes and small changes with guardrails. You get the speed of vibe coding without the recklessness — mandatory TDD, architecture awareness, and reusable component detection.

Flow:

digraph vibe {
  "Task clear?" [shape=diamond];
  "Test infrastructure?" [shape=diamond];
  "Scope: how many files?" [shape=diamond];
  "Architecture smell?" [shape=diamond];
  "Reusable components found?" [shape=diamond];
  "TDD enabled?" [shape=diamond];
  "RED: test result?" [shape=diamond];
  "More behaviours in this task?" [shape=diamond];
  "Follow-up genuinely warranted?" [shape=diamond];
 
  "Ask or clarify" [shape=box];
  "ASK: set up tests or skip TDD?" [shape=box];
  "Set up a basic test framework" [shape=box];
  "WARN: may be bigger than a vibe task" [shape=box];
  "STOP: investigate deeper issues" [shape=box, style=bold];
  "Recommend using existing code" [shape=box];
  "STOP: feature may exist or test is wrong" [shape=box, style=bold];
  "STOP: unexpected failure, discuss" [shape=box, style=bold];
  "RED: write one failing test" [shape=box];
  "Existing test encodes the old behaviour?" [shape=diamond];
  "RED: update that test, run it before touching source" [shape=box];
  "STOP: superseded requirement or real regression? ask" [shape=box, style=bold];
  "GREEN: minimal code to pass" [shape=box];
  "REFACTOR: clean up, keep tests green" [shape=box];
  "Post-fix summary" [shape=box];
  "Suggest the matching paad skill" [shape=box];
  "Say nothing further" [shape=box];
  "Run pre-flight checks" [shape=box];
 
  "Task clear?" -> "Run pre-flight checks" [label="yes"];
  "Task clear?" -> "Ask or clarify" [label="no"];
  "Ask or clarify" -> "Task clear?";
 
  "Run pre-flight checks" -> "Test infrastructure?";
  "Test infrastructure?" -> "Scope: how many files?" [label="yes"];
  "Test infrastructure?" -> "ASK: set up tests or skip TDD?" [label="no"];
  "ASK: set up tests or skip TDD?" -> "Set up a basic test framework" [label="set up tests"];
  "ASK: set up tests or skip TDD?" -> "Scope: how many files?" [label="proceed without TDD — RED is skipped"];
  "Set up a basic test framework" -> "Scope: how many files?";
 
  "Scope: how many files?" -> "Architecture smell?" [label="1-3 files"];
  "Scope: how many files?" -> "WARN: may be bigger than a vibe task" [label="4+ files"];
  "WARN: may be bigger than a vibe task" -> "Architecture smell?";
 
  "Architecture smell?" -> "STOP: investigate deeper issues" [label="simple task, complex impl"];
  "Architecture smell?" -> "Reusable components found?" [label="no smell"];
 
  "Reusable components found?" -> "Recommend using existing code" [label="yes"];
  "Reusable components found?" -> "TDD enabled?" [label="no"];
  "Recommend using existing code" -> "TDD enabled?";
 
  "TDD enabled?" -> "Existing test encodes the old behaviour?" [label="yes"];
  "TDD enabled?" -> "GREEN: minimal code to pass" [label="no — user chose to skip TDD"];
  "Existing test encodes the old behaviour?" -> "RED: write one failing test" [label="no"];
  "Existing test encodes the old behaviour?" -> "RED: update that test, run it before touching source" [label="yes — it is the old requirement, not a regression"];
  "Existing test encodes the old behaviour?" -> "STOP: superseded requirement or real regression? ask" [label="cannot tell"];
  "RED: update that test, run it before touching source" -> "RED: test result?";
  "RED: write one failing test" -> "RED: test result?";
  "RED: test result?" -> "STOP: feature may exist or test is wrong" [label="passes unexpectedly"];
  "RED: test result?" -> "STOP: unexpected failure, discuss" [label="fails unexpectedly"];
  "RED: test result?" -> "GREEN: minimal code to pass" [label="fails as expected"];
 
  "GREEN: minimal code to pass" -> "REFACTOR: clean up, keep tests green" [label="new test passes, existing tests still pass"];
  "REFACTOR: clean up, keep tests green" -> "More behaviours in this task?" [label="all tests still green"];
  "More behaviours in this task?" -> "TDD enabled?" [label="yes — one behaviour at a time"];
  "More behaviours in this task?" -> "Post-fix summary" [label="no"];
 
  "Post-fix summary" -> "Follow-up genuinely warranted?";
  "Follow-up genuinely warranted?" -> "Suggest the matching paad skill" [label="security-sensitive / UI / harder than expected"];
  "Follow-up genuinely warranted?" -> "Say nothing further" [label="no — trivial fix"];
}

Arguments

/vibe accepts optional $ARGUMENTS:

• /vibe — ask the user what needs fixing
• /vibe fix the login timeout bug — start working on the described task immediately
• /vibe src/components/Modal.tsx add close on escape key — task with a file hint

When arguments are provided, treat them as the task description. Still ask clarifying questions if the task is unclear.

Step 1: Understand the Task

If no $ARGUMENTS provided, ask: "What needs fixing or changing?"

Once you have a task description:

• If the task is unclear, ask one clarifying question at a time
• Focus on: what should change, what should stay the same, edge cases
• Don't over-question simple tasks. "Fix the typo in the header" doesn't need a requirements session.

Step 2: Pre-flight Checks

Before writing any code, check these. If any raise concerns, discuss with the user before proceeding.

Test infrastructure

Does this project have a test framework and runner? Look for:

• Test directories (test/, tests/, spec/, __tests__/)
• Test config files (jest.config, vitest.config, pytest.ini, .rspec, phpunit.xml, Cargo.toml with [dev-dependencies], etc.)
• Existing test files

If no test infrastructure exists: tell the user. Ask: "There's no test setup in this project. Want me to set up a basic test framework first, or proceed without TDD?" If they choose to proceed without TDD, still follow GREEN and REFACTOR steps but skip RED.

Existing tests in the affected area

Does the code being changed already have tests? If yes, note them — they'll inform your RED step and catch regressions. If no, that's fine but worth noting.

Scope check

How many files and modules does this change likely touch?

• 1-3 files, same module: good vibe territory. Proceed.
• 4+ files or crosses module boundaries: warn the user: "This looks like it touches [N] files across [modules]. It might be bigger than a vibe task. Want to proceed, or would a more structured approach be better?"

Architecture smell

If the task is conceptually simple (e.g., "only admin users can download finance reports") but investigation reveals it requires a lot of work to implement, stop. Investigate whether there are deeper architectural issues making the work harder than it should be. Discuss findings with the user before proceeding.

Reusable components

If the task involves common functionality — toast notifications, modals, form validation, error handling, data formatting, API calls, permission checks, logging, etc. — search the codebase first for:

• Existing components or utilities that already do this
• Partial implementations someone started but didn't finish
• Patterns used elsewhere in the codebase for the same kind of thing

If found: tell the user what you found and recommend using/extending the existing code rather than building from scratch.

Step 3: Implement (Red/Green/Refactor)

This is mandatory. Follow it strictly.

RED — Write one failing test

Write a single test that defines the expected behavior for the change.

Run it. It should fail. If it doesn't:

• If the test passes: stop. The feature or fix may already exist, or your test may not be testing what you think. Tell the user what happened and ask how to proceed.
• If the test fails in an unexpected way: stop. The failure mode may reveal an unknown issue. Tell the user what you expected vs what happened and ask how to proceed.

Only proceed to GREEN when the test fails in the expected way.

When an existing test already encodes the old behaviour. Common on a requirement change rather than a bug fix: a test asserts the value you are about to change. That test is the old requirement written down, not a regression signal — update it to the new expectation and run it before touching the source. That is a valid RED. Don't add a second test asserting the same behaviour.

Two things this does not license:

• Changing a test after the source, to make a red suite go green. Order is the entire difference: before the fix it is a specification, after it is whatever makes the failure go away.
• Skipping RED because an existing test "already covers" the branch. It asserts the old value, so it goes red whether your change is right or wrong.

If you cannot tell whether a failing test encodes a superseded requirement or a real regression, stop and ask.

GREEN — Write minimal code to pass

Write the simplest code that makes the failing test pass. Resist the urge to:

• Add error handling for cases not covered by the test
• Build abstractions "while you're in there"
• Fix adjacent code that isn't broken
• Add features beyond what was asked

Run the test. It should pass. Run all existing tests in the affected area too — make sure nothing broke.

REFACTOR — Improve while keeping tests green

Now clean up. This is the step AI skips unless told to, and it's where real quality comes from. Look for:

• Duplicated logic that should be extracted into a shared function
• Hard-coded values that belong in config or constants
• Inconsistent patterns where your new code doesn't match the conventions around it
• Naming that could be clearer
• Dead code your change made obsolete

Run all tests after refactoring. Everything must stay green.

Repeat if needed

If the task involves multiple behaviors, repeat the red/green/refactor cycle for each. One test at a time, one behavior at a time.

When You're About to Skip a Step

Every excuse below was produced by an agent working a real timed task under this skill, not invented for illustration. They are persuasive because they are almost right — each one contains a true observation attached to a wrong conclusion. If you catch yourself composing one of these, that is the signal to do the step, not to explain why you didn't.