vibe-coding-toolkit: a Claude Code workflow extracted from one production fintech project

The problem it names: prompt-and-hope is not a workflow

The README opens with a claim about failure, not about capability. Programming with an AI assistant looks easy until you notice that pasting a large prompt and hoping is luck rather than process. The author lists the specific symptoms he kept hitting: sessions that lost the thread, agents that built more than what was asked, lint warnings nobody ever drove to zero, and expensive lessons relearned in every new session because nothing was written down. Each item in the toolkit, the README says, exists because it already prevented one of those at least once. Nothing was added because it looked interesting. The audience is stated plainly: developers at any level who already use or are testing Claude Code or Codex and want structure instead of trial and error. One disclosure matters more than the rest. The practices come from a private production fintech project under NDA, so the source code cannot be shown. What is published is the method already extracted and generalized. That explains why this repository's own history is short: it is where the method is documented, not where it was built. Anyone evaluating it should hold that distinction, because it means there is no public commit trail connecting these documents to the production incidents they claim to prevent.

Superpowers is the load-bearing piece, and the rest is support

The README does not present its contents as equal. It puts one item first with an explicit importance callout: Superpowers, described as a plugin that enforces discipline so an agent explores the intent of a request and plans before writing code, rather than acting on the first plausible reading of an open-ended instruction. The instruction attached to it is unusually direct. If you configure only one thing from this repository, make it this, and read docs/tools/01-superpowers.md before anything else. That ranking is a design statement about where the value sits. A planning gate addresses the failure mode where an agent commits to an interpretation and then produces a large volume of code built on a wrong assumption. Catching that before generation is cheaper than reviewing it after. The README frames the other two highlighted documents as the chassis to Superpowers' engine: subagent orchestration and the ESLint/Biome quality gates. Note that Superpowers is installed from Anthropic's official plugin marketplace, not from this repository. This project supplies the surrounding method, the documentation and the templates, and points at a third-party plugin for the core behavior. That is worth knowing before you judge the repository on its own code.

Subagent waves, and where the coordination actually lives

The second highlighted document covers orchestration of subagents in parallel waves. The claim in the README is specific and structural: the protocol eliminates file collisions and commit contention in the structure of the workflow rather than relying on discipline. The author adds that nothing comparable appeared in other collections he surveyed while assembling this repository, which is a claim about his search, not a verified property of the ecosystem. The distinction between structural and disciplinary enforcement is the interesting part. If two agents edit the same file in the same wave, a rule telling them not to is a convention that holds until it does not. A protocol that assigns files or partitions work before the wave starts removes the possibility. The README does not reproduce the protocol itself; it lives in docs/tools/02-subagent-orchestration.md, which is not included in the material available here. So the mechanism can be described at the level of intent but not at the level of detail. Whether the partitioning is by directory, by module ownership, or by something else is not stated in the README. Treat the collision-elimination claim as the author's characterization until you read the document.

Getting it running: four commands and a template copy

The README gives a short starting sequence and is candid about what it is not. There is no installer that detects your stack and writes the configuration for you. The first commands are npm install -g @anthropic-ai/claude-code, then /plugin marketplace add anthropics/claude-plugins-official, then /plugin install superpowers@claude-plugins-official, then cp templates/CLAUDE.md.template CLAUDE.md. The README describes the result as Claude Code installed, the most important tool in the toolkit active, and the project instruction template in the right place. Everything else, subagent orchestration, quality gates and cross-session memory, is walked through in docs/02-playbook-onboarding.md, which the README recommends as the entry point rather than reading the repository in order. There is also a narrower path for people who want none of the toolkit except the lint rules. Paste a prompt into any agent that can read a URL, instructing it to fetch docs/prompts/08-eslint-quality-gates-install.md and execute it with MAX_LINES=350. That prompt downloads three pre-written rules, adapts the configuration to your project structure, and returns the list of files over the ceiling. The README is explicit that it does not fix anything: measuring and fixing are separate jobs. A companion prompt, 09-file-size-refactor.md, does the fixing, splitting large files by responsibility (business logic, UI component, data access) rather than by line count, one file per commit, with tests and type checking between each.

The 350-line ceiling is a real constraint, not a style preference

Most lint configurations you inherit are a list of rules someone copied. This one is built around a single numeric ceiling that the README repeats twice: 350 lines per file. The install prompt takes MAX_LINES as a parameter, which means the number is a decision you make rather than a default baked into the rules. That is the right shape for this kind of gate, because the correct ceiling depends on the codebase. But the refactor prompt reveals the harder constraint. Splitting a 900-line file by line count produces three files that are each still doing three jobs, and the next change reopens all three. The README's answer is to cut by responsibility, one file per commit, with tests and type checking running between each commit. That is slow and it is deliberate: a commit that breaks the build is isolated to one file, and the test run between commits is what catches it. The cost is real. A large refactor becomes a long sequence of small commits, and if your test suite is slow or flaky, the sequence becomes painful enough that people stop doing it. The second half of the quality gate story is architectural: the README mentions enforcing architecture boundaries through lint, which turns a design rule into a build failure instead of a code review comment. That is the part worth copying even if you ignore the line ceiling entirely.

What is missing, and what that means for adoption

The repository has no releases. The README states that the history here is short by design, because the method was built elsewhere and documented here. There are no published benchmarks, no before-and-after measurements of agent output quality, and no reported adoption numbers. The README's evidence for its claims is the author's production experience, described as battle-tested, with the source project unavailable under NDA. That is a legitimate position for a methodology repository and an unsatisfying one for an engineer who wants to know whether the subagent wave protocol actually reduces collisions in a codebase with different conventions. The primary language listed is JavaScript, which fits the ESLint and Biome material but says nothing about the plugin and prompt documents, which are language-agnostic. One practical gap: the README mentions cross-session memory as part of the full setup and defers it to the Playbook, so anyone adopting the toolkit piecemeal should expect to assemble that part themselves. There is also a documentation-language question. The README is written in Portuguese, with the exception of the install prompt, which is written for an agent to execute. If your team does not read Portuguese, the Playbook and the tool documents become the bottleneck, and the README does not indicate whether translations exist.

How this differs from a general prompt library

The obvious alternative is a curated prompt collection or a rules file such as a CLAUDE.md or AGENTS.md you write yourself. The difference is in what gets enforced and where. A prompt library gives you text to paste and leaves compliance to you. This toolkit's quality gates move the rules into ESLint and Biome, so a file over 350 lines fails the build and an architecture boundary violation fails the build. The rules stop depending on whether someone remembers them. That is a genuine step up in enforcement, and it is also the reason the toolkit is harder to adopt: lint configuration is project-specific, and the install prompt exists precisely because a generic config will not match your directory layout. The subagent orchestration document is the other differentiator, since prompt collections rarely address what happens when multiple agents run at once. Against a full agent framework, the trade-off runs the other way. A framework owns the runtime and can enforce sequencing in code; this repository supplies documents and configuration that your agent reads. The enforcement is as strong as your build pipeline and as weak as your agent's willingness to follow instructions. For a team already using Claude Code, that is probably enough. For a team that needs guarantees rather than conventions, it is not.

Licence, maintenance and what to check before you commit

The repository is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the permissive default and it imposes no copyleft obligation on your own code. It does not settle anything about the third-party pieces you install alongside it: Superpowers comes from Anthropic's official plugin marketplace and carries its own terms, and the README does not state them. Check that separately rather than assuming MIT covers the whole setup. This is not legal advice; if the distinction matters to your organisation, have someone qualified read both licences. On maintenance, the material supports only a limited assessment. The last push to the default branch is 2026-09-03, the repository is not archived, and no releases have been published. With no version tags, there is no changelog to diff and no way to pin a known-good state of the documents. If you adopt the prompts, copy them into your repository rather than fetching them from a raw URL at run time, because the URL points at the main branch and the content behind it can change without notice. Start by reading docs/tools/01-superpowers.md, as the README instructs, then run the 08 prompt with MAX_LINES=350 to see the size of the problem in your own tree before you decide how much of the rest to take.

Editorial conclusion

Adopt it if you already run Claude Code or Codex on a real codebase and want a documented session protocol instead of ad hoc prompting, and start with docs/tools/01-superpowers.md as the README instructs. Skip it if you want a single installer that detects your stack, or if you need published benchmarks before changing your workflow: there are none, and the README states the practices come from a private fintech project under NDA whose code cannot be shown. Before committing, run the one-line ESLint prompt with MAX_LINES=350 and count how many files in your repository exceed that ceiling.

Official sources

1. Issues
2. License: MIT
3. README
4. soumatheusgomes/vibe-coding-toolkit on GitHub