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.