Pudo Code System

Table of Contents

• The Problem
• The Solution: PUDO
• The MCP Server
• The 4 Phases
• Architecture Overview
• Install Into a Project
• Quick Start
• PUDO Modes
• Quality Gates
• Examples
• Prompt Library
• AI Integrations
• Repository Structure
• Measurement Targets
• Philosophy
• Onboarding Paths
• When Not To Use PUDO
• Contributing
• Support & Funding
• License

The Problem

You open your editor. You type a vague request to your AI assistant. It generates something. You paste it in. It half-works. You ask for a fix. It breaks something else. Repeat for 3 hours.

This is chaos coding. It feels productive, but it's not.

The issue isn't the AI — it's the lack of structure. Without a clear methodology, AI-assisted development becomes a random walk through your codebase.

The Solution: PUDO

PUDO is an AI Agent Operating Layer that installs into any repository. It gives you:

• Installable agent rules for Cursor, Claude, Codex, Copilot, Gemini, OpenCode, and Kiro
• Measurable quality gates to prevent shipping unverified AI output
• Token-budgeted prompts that get better results from every AI assistant
• Workflow templates for every task size, from a 5-minute fix to a multi-week feature
• Benchmark evidence to measure whether the method is actually working

PUDO is not a new AI model. It's the operating layer that makes your existing AI tools more reliable.

Recent research on configuring agentic coding tools identifies repository-level context files as the dominant mechanism and notes AGENTS.md emerging as an interoperable standard across tools. PUDO starts from that repo-level layer and adds executable checks, quality gates, handoff, and measurement. (arXiv:2602.14690)

The MCP Server

The PUDO MCP server turns the operating layer into tools that compatible coding agents can call directly. Instead of relying on an agent to remember documentation, the agent calls PUDO tools to generate rules, validate output, run quality gates, and maintain session continuity.

The alpha server uses local stdio, restricts reads to one configured repository root, requires explicit approval for writes, and exposes no shell or network execution.

# Via npx (no install needed)
npx @dongduong2001/mcp-server@alpha

# Or install globally
npm install -g @dongduong2001/mcp-server@alpha
pudo-mcp-server

See PUDO MCP Server, Agent Tool Security, and the MCP Security Checklist.

The 4 Phases

Key insight: PUDO is a cycle, not a pipeline. You revisit phases as you learn more. A discovery in Develop might send you back to Plan. That's expected and by design.

Architecture Overview

PUDO has three product surfaces that work together:

┌──────────────────────────────────────────────────────────────┐
│                    Your Repository                           │
│                                                              │
│  ┌─────────────────┐    ┌──────────────────┐                │
│  │  Agent Config   │    │  Quality Layer   │                │
│  │                 │    │                  │                │
│  │  AGENTS.md      │    │  quality-gates   │                │
│  │  CLAUDE.md      │    │  qc-checklists   │                │
│  │  GEMINI.md      │    │  anti-hallucin.  │                │
│  │  .cursor/rules  │    │  token-budget    │                │
│  │  copilot-inst.  │    │  ai-output-rev.  │                │
│  └────────┬────────┘    └────────┬─────────┘               │
│           │                      │                          │
│           ▼                      ▼                          │
│  ┌──────────────────────────────────────────────────┐       │
│  │              CLI  (npx pudo-code-system)          │       │
│  │                                                  │       │
│  │  init · check · score · score --strict · doctor  │       │
│  └──────────────────────┬───────────────────────────┘       │
│                         │                                   │
└─────────────────────────┼───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│            MCP Server  (stdio, local, sandboxed)            │
│                                                             │
│  generateAgentRules  ·  createContextPack                   │
│  runQualityGate      ·  scoreRepoReadiness                  │
│  initProject         ·  updateSessionHandoff                │
│  validateAgentRules  ·  doctor                              │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌────────────────────────────────────────────┐
│        AI Coding Agents                    │
│                                            │
│  Cursor  Claude  Codex  Copilot            │
│  Gemini  OpenCode  Kiro                    │
└────────────────────────────────────────────┘

Agent Config files tell every AI assistant how to behave in your repo. Quality Layer provides checklists, gates, and anti-patterns to validate AI output. CLI gives you executable workflow commands that produce machine-readable results. MCP Server exposes all of the above as callable tools for compatible agents.

Install Into a Project

Use the init command to generate agent rules, PR templates, quality checklists, and a session handoff file in any repository:

npx pudo-code-system init

Non-interactive setup:

npx pudo-code-system init \
  --yes \
  --tools=cursor,claude,codex,copilot,gemini,opencode,kiro \
  --project=nextjs \
  --strictness=standard

Generated files include: AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/pudo-core.mdc, .github/copilot-instructions.md, opencode/opencode.md, kiro/system-prompt.md, .github/pull_request_template.md, .pudo/config.json, and .pudo/session.md.

Executable workflow commands:

npx pudo-code-system check              # validate installed config files
npx pudo-code-system score              # score repo readiness (0-100)
npx pudo-code-system score --json       # machine-readable JSON output
npx pudo-code-system score --strict     # fail if score is below threshold
npx pudo-code-system doctor             # diagnose workflow gaps

score evaluates instruction specificity, context quality, workflow evidence, AI/MCP safety, tests, CI, benchmarks, and release traceability. Its JSON output follows schemas/pudo-score.schema.json.

Quick Start

1. Plan

Before writing any code, define what you're building:

I need to build [FEATURE].
The success criteria are [CRITERIA].
The constraints are [CONSTRAINTS].
Create an implementation plan before writing any code.

2. Understand

Research before you build:

Before implementing, analyze the existing codebase:
- What patterns are already established?
- What dependencies are involved?
- What could break?

3. Develop

Build with structure:

Implement the plan. Track progress with a task checklist.
Write tests alongside the implementation.
Flag any deviations from the plan.

4. Optimize

Don't ship the first draft:

Review the implementation:
- Are there performance improvements?
- Is the code consistent with existing patterns?
- Write a walkthrough summarizing what changed and why.

5. Repeat

Every task, every feature, every bug fix — Plan → Understand → Develop → Optimize.

PUDO Modes

Use the smallest mode that safely fits the task. See PUDO Modes for the full guide.

Quality Gates

Each phase ends with a gate. Do not move forward until the gate passes, or until the risk is explicitly accepted.

See Quality Gates, QC Checklists, AI Output Review, Anti-Hallucination Rules, Token Budget Rules, Context Engineering, and the Edge Case Catalogue.

Examples

See PUDO applied to real-world scenarios:

Prompt Library

PUDO ships with 21 ready-to-use prompts across 4 phases. Copy-paste into any AI assistant. Each phase folder includes a README.md explaining how to extend the prompts for your team.

AI Integrations

PUDO is designed to be the default operating layer for AI coding agents, working across all major tools.

Repository Structure

pudo-code-system/
├── AGENTS.md                   # Shared agent rules (Codex, cross-tool)
├── CLAUDE.md                   # Claude Code memory bridge
├── GEMINI.md                   # Gemini agent instructions
│
├── docs/                       # Documentation
│   ├── README.md               # Documentation index
│   ├── philosophy.md           # Why PUDO exists and its design principles
│   ├── workflow.md             # Deep-dive into each phase
│   ├── pudo-modes.md           # Lite / Standard / Enterprise guide
│   ├── getting-started.md      # First steps for new users
│   ├── architecture.md         # System diagram and component overview
│   ├── context-engineering.md  # How to bound AI context effectively
│   ├── mcp.md                  # MCP server setup and usage
│   ├── agent-skill-contract.md # Agent capability contracts
│   ├── team-adoption-guide.md  # Multi-phase team rollout guide
│   └── faq.md                  # Frequently asked questions
│
├── prompts/                    # 21 ready-to-use AI prompts
│   ├── plan/                   # Scoping, architecture, risk
│   ├── understand/             # Codebase analysis, patterns
│   ├── develop/                # Implementation, testing
│   └── optimize/               # Performance, review, refactor
│
├── skills/                     # Domain-specific PUDO variants
│   ├── plan/                   # Architecture & planning
│   ├── code/                   # Software engineering
│   ├── debug/                  # Troubleshooting
│   ├── devops/                 # CI/CD, infra tools
│   ├── test/                   # Test engineering
│   ├── frontend/               # Frontend patterns
│   ├── backend/                # Backend patterns
│   └── mobile/                 # Mobile development
│
├── quality/                    # Quality enforcement
│   ├── quality-gates.md        # Phase gate checklists
│   ├── qc-checklists.md        # Product, eng, security checklists
│   ├── ai-output-review.md     # Reviewing AI-generated code
│   ├── anti-hallucination.md   # Preventing AI errors
│   ├── token-budget.md         # Context window management
│   ├── mcp-security-checklist.md
│   ├── agent-tool-security.md
│   └── edge-cases/             # Edge case catalogue
│
├── examples/                   # Real-world PUDO walkthroughs
│   ├── 01-landing-page/
│   ├── 02-api-integration/
│   ├── 03-debug-production/
│   ├── 04-quality-gate-failure/
│   └── 05-before-after-token-waste/
│
├── templates/                  # Stack-specific project scaffolds
│   ├── nextjs/
│   ├── react-vite/
│   ├── node-express/
│   ├── python-fastapi/
│   └── ...
│
├── benchmarks/                 # Measurement framework
│   ├── README.md               # How to benchmark
│   ├── metrics-sheet.csv       # Template for recording results
│   ├── token-waste-calculator.md
│   └── results/                # Measured case studies
│
├── schemas/                    # JSON schemas for machine-readable output
│   ├── pudo-score.schema.json
│   ├── pudo-metrics.schema.json
│   └── pudo-run-trace.schema.json
│
├── packages/
│   └── pudo-mcp-server/        # MCP server (TypeScript)
│       ├── src/server.ts
│       ├── tools/              # 8 callable MCP tools
│       └── tests/
│
├── bin/
│   └── pudo.js                 # CLI entry point
│
├── .pudo/                      # PUDO operating-kit state
│   ├── config.json
│   ├── session.md              # Session handoff file
│   └── checklists/
│
├── .github/
│   ├── workflows/              # CI: CLI install test, PUDO check
│   ├── ISSUE_TEMPLATE/         # Bug report, feature request
│   ├── pull_request_template.md
│   └── CODEOWNERS
│
└── cursor/, claude/, codex/,   # Tool-specific config dirs
    kiro/, opencode/, antigravity/

Measurement Targets

These numbers are directional targets to validate with your own benchmark data, not proven PUDO-wide guarantees. Current public evidence is one measured case study — do not cite this table as a benchmark claim until you have your own data. Gains depend on task size, repo quality, and how consistently you follow PUDO.

Measure your own results with the Benchmark Kit. Track tokens, AI turns, failed attempts, unnecessary file reads, time to verified implementation, bugs found after AI output, and PR review comments. See the sample measured case in benchmarks/results/stripe-webhook-2026-05.

Philosophy

PUDO isn't just a checklist — it's a mindset. Read the full philosophy to understand the principles behind the method.

TL;DR:

• Anti-chaos — Structure beats improvisation at scale
• Iterative — It's a cycle, not a waterfall
• AI-native — Designed for human+AI pair programming
• Phase integrity — Each phase has clear entry and exit criteria

Onboarding Paths

See Team Adoption Guide for a multi-phase team rollout plan.

When Not To Use PUDO

PUDO may be overkill for one-line fixes, throwaway prototypes, pure exploration, and non-critical scripts. Use the full cycle when correctness, maintainability, security, or team handoff matters.

Current Limitations

• PUDO does not guarantee AI output is correct.
• Human review is still required.
• Security-sensitive changes still need dedicated security review.
• Examples are illustrative, not universal.
• The method requires discipline; skipping gates turns it back into ad hoc prompting.

Who Is This For?

• Developers using AI assistants (ChatGPT, Claude, Gemini, Copilot, etc.) who want better results
• Team leads looking for a shared methodology for AI-assisted development
• Students learning to code with AI the right way from day one

Contributing

PUDO grows with the community. See CONTRIBUTING.md for how to add prompts, submit walkthroughs, improve docs, and report issues.

Questions? Open a Discussion or check SUPPORT.md.

Support & Funding

If you find PUDO helpful, consider supporting the project:

• GitHub Sponsors
• Patreon
• Ko-fi
• Buy Me a Coffee

License

MIT — Use it, fork it, make it yours.