AI Development on the Rails

ai dev-tools open-source

Introduction

I’ve spent the last few months head-down building with agentic AI. It’s been amazing, but if I’m honest, it’s also been incredibly frustrating.

We all know the pitch: AI coding assistants speed up development. But anyone using them heavily quickly runs into the same wall—getting them to produce secure, architecturally sound, and consistent code at scale is a massive headache.

Without the right structure, AI agents act like brilliant but reckless junior developers. They churn out code fast, but they’ll happily ignore your design patterns, hallucinate a non-existent API, or weave in subtle security flaws.

To function like senior engineers, they need actual guardrails.

I got tired of constantly correcting the same mistakes in my own workflows, so I built a system to fix it. I call it Agent Protocols, and today I’m open-sourcing the repository.

At its core, Agent Protocols is a structured, production-ready framework of instructions, personas, skills, and SDLC workflows. It treats your AI’s instructions as version-controlled code, giving your agents a shared foundation to maintain professional standards across all your projects.

Key Concepts: How It Works Under the Hood

Agent Protocols is distributed as a clean, portable .agents/ bundle via Git submodule, making it easy to drop into any repository. Once initialized, it acts as the “brain” and boundary system for your AI assistant.

Here is what that looks like in practice:

1. The System Core (instructions.md)

This is the mandatory system prompt that binds everything together. By pointing your AI tool’s custom instructions (like .cursorrules) to this file, you enforce a strict “Context First, Plan First” philosophy. It forces the agent to read your project’s architecture docs before proposing a solution, and requires it to fetch live documentation to prevent library hallucinations.

2. Role-Specific Personas (personas/)

Not every task requires a full-stack cowboy. Personas constrain agent behavior to a specific role. Tell your agent to “Act as an Architect,” and it loads constraints focused entirely on system design, database schemas, and API contracts. Need pipeline optimizations? The “SRE” persona steps in to focus strictly on CI/CD, caching, and infrastructure resilience.

3. Tech-Stack Guardrails (skills/)

Skills are modular, stack-specific guardrails that prevent common AI mistakes from ever making it into your files. For example:

  • cloudflare-hono-architect: Prevents the AI from accidentally using Node.js modules in edge Workers.
  • sqlite-drizzle-expert: Enforces specific dialect rules for Turso and Drizzle ORM.
  • ui-accessibility-engineer: Guarantees that generated Tailwind components strictly comply with WCAG 2.1 AA accessibility standards.

When your agent detects a relevant task, it automatically loads these guardrails before writing a single line of code.

4. Automated SDLC Workflows & Audits (workflows/)

Prompting an AI to “plan a sprint” or “audit my codebase” usually results in wildly inconsistent outputs. Agent Protocols solves this by offering reusable, single-command workflows.

By running /plan-sprint, the framework sequences a pipeline: it generates a strict Product Requirements Document (PRD), translates that into a Tech Spec, and synthesizes both into an actionable Sprint Playbook—complete with assigned chat sessions for your agents to execute.

Need to check your app’s health? Single-command audits like /security-audit provide rigorous codebase reviews outputted to standardized report files, bringing CI/CD-style linting directly to your AI interactions.

Conclusion

If you’re building with AI and struggling with structural decay or having to repeat yourself, I built this for you.

You can dive into the repository’s README for a comprehensive setup guide. Contributions, forks, and pull requests for new domain-specific skills are absolutely welcome.

Check it out on GitHub and let me know what you think.