Pokayoke: Mistake-Proof Your Repository with Agent-Friendly Policy Checks

When Japanese manufacturing pioneer Shigeo Shingo coined the term pokayoke in the 1960s, he was solving a problem that software developers know well: how do you make mistakes impossible—or at least, immediately obvious?

The idea is elegantly simple. Instead of relying on people to follow rules perfectly, you design systems that catch deviations automatically. A socket that only fits one way. A sensor that halts the line when something's misaligned. In manufacturing, this prevents defects from reaching customers. In software, it prevents convention drift from reaching production.

Pokayoke.codes brings this philosophy to your repository with a tool designed from the ground up for the age of AI-assisted development.

Beyond Linting: Policy as Documentation

Most teams already have linters. ESLint flags unused variables. Prettier enforces formatting. TypeScript catches type errors. These tools do their jobs well, but they don't capture the implicit knowledge that lives in your team's head—conventions that everyone knows but no one has formalized.

Maybe your API endpoints follow a specific naming pattern. Perhaps you have rules about which packages are acceptable for certain contexts. Or maybe there's a team agreement about file organization that isn't enforced anywhere.

This is the gap pokayoke fills. It lets you codify repository-specific invariants that fall outside the scope of traditional linting but matter just as much to code consistency.

Agent-First by Design

Here's what makes pokayoke genuinely interesting: it's built for AI agents first.

Modern coding assistants can navigate your codebase, write new features, and refactor existing code. But keeping them aligned with your team's conventions? That's still a manual process. You might add rules to your system prompt, but agents forget, hallucinate, or simply don't know what you consider important.

Pokayoke solves this by treating policy rules as first-class citizens that agents can read, understand, and act on. The pokayoke agent SKILL.md gets agents up and running autonomously, and the rules themselves are designed to be written and maintained by AI—not just for human developers.

If you're building a Vibe Coding workflow where AI handles the heavy lifting, pokayoke gives you a way to communicate your standards in a format that actually sticks.

Plays Nice with Your Stack

One concern with adding new tooling is the risk of fragmentation. You already have ESLint, Prettier, Husky, and a dozen other tools keeping your codebase in line. Adding pokayoke doesn't mean replacing any of that—it means extending your existing pipeline.

The documentation emphasizes that pokayoke is unopinionated. It doesn't care about formatting (that's Prettier's job) or general code quality (let ESLint handle that). Instead, it focuses on the project-specific invariants that only your team knows about.

The TypeScript rules are local to your repo and check against the constraints that matter for your particular setup. Think of it as a custom validation layer built on top of your standard tooling.

Getting Started

Ready to mistake-proof your repository? Installation is straightforward:

npx skills add rorz/pokayoke

From there, you can define rules that capture your team's conventions. The rules are designed to be self-documenting—both humans and agents can read them to understand what policies are in effect and why.

The Bigger Picture

Pokayoke represents a interesting shift in how we think about code quality tooling. Traditional linters enforce syntax and style. Static analyzers catch bugs. But as AI coding assistants become primary collaborators, we need new categories of tools that communicate intent in ways agents can actually consume and follow.

It's not just about catching mistakes anymore. It's about making your standards machine-readable, agent-friendly, and hard to violate—whether the code comes from a human developer or an AI assistant.

In that sense, pokayoke might be one of the first tools purpose-built for how we'll all be writing code in a few years. Worth keeping an eye on.