Stop hardcoding prompts inside your application logic.
Stop generating them blindly without governance.
Write them as typed, versioned, validated protocols.
// the problem
There are two broken approaches to prompts in production today. Neither scales. Neither is maintainable. Both make debugging a nightmare.
The prompt is buried inside Python functions, concatenated with f-strings, mixed with business logic. Change the behavior? Edit the code. Refactor the code? Break the behavior. Invisible coupling everywhere.
The prompt is thrown at the AI ad-hoc, with no validation, no output schema, no versioning. It works once and breaks randomly. Nobody knows why it changed. Nobody owns it.
// the solution
Protocol-Driven Development (PDD) treats every prompt as a typed, validated contract. Written in Markdown. Versioned in Git. Injected by an SDK that guarantees output schemas.
"If your Dockerfile defines what runs, your protocol.md defines how your model thinks. One governs the container. The other governs the cognition."proto.md manifesto
Dynamic values are declared as typed slots in the .md file. If your code tries to inject a slot that doesn't exist, the build fails.
The protocol defines hard rules the model must follow. The SDK enforces them before returning the response to your application.
If the model's output doesn't match the declared schema, the SDK throws. Not silently. Not eventually. Immediately.
Protocol changes are git commits. Behavior history is git log. Rollback is git revert. The model's cognition has a changelog.
// mvp status
The current MVP ships parser + validator + CLI + tests + quality workflow. Run protocol checks locally and enforce them on pull requests before deploy.
// why it matters
Slots are declared with types. Inject the wrong type or a missing slot and the build breaks. Same discipline as typed code.
Every protocol has a semver. Breaking changes to slots or schema are major bumps. Your app pins the version.
Output is validated against the declared schema before it reaches your application. No more surprise shapes in production.
Protocols can import and extend each other. Build a library of reusable cognitive contracts like Lego.
Declare the model in the protocol. Switch from Claude to GPT to Gemini by changing one line. Your code stays the same.
It's Markdown. Non-engineers can read, review, and understand what the AI is instructed to do. PRs are meaningful.
// get started
Four steps. No magic. Just structure you should have had from the start.
The MVP runs directly from the repository. Install runtime dependencies and use the local CLI.
$ pip install pyyaml jsonschema
Create a protocols/ directory and add a `.md` protocol with frontmatter, slots, constraints and schema.
$ cp protocols/valid_protocol.md protocols/my_first.md
Run `proto-lint` locally and in CI. If slots are mismatched or schema is missing, the pipeline fails with exit code 1.
$ python cli.py protocols
$ python -m unittest -v
Use GitHub Actions to run syntax checks, tests and CLI smoke checks on every push/PR to `main`.
$ git add .
$ git push origin main # quality-check.yml runs automatically
Your model's behavior deserves the same discipline as your code. Version it. Lint it. Own it.