This guide gets you from zero to your first complete PUDO cycle in under 10 minutes.
You don’t need to install anything to start. The CLI runs via npx.
If you just want to try the methodology right now, skip the CLI and follow the 5-minute cycle below. PUDO is a thinking framework first — the CLI and MCP server automate and enforce it, but they’re not required.
Run once in your project root:
npx pudo-code-system init
The interactive wizard walks you through:
Non-interactive setup (fastest path for new repos):
npx pudo-code-system init \
--yes \
--tools=claude,cursor,codex \
--project=nextjs \
--strictness=standard
After init, verify the installation:
npx pudo-code-system check # validates all installed files
npx pudo-code-system score # scores repo readiness (aim for 80+)
npx pudo-code-system doctor # diagnoses any gaps
Commit the generated files:
git add .
git commit -m "chore: initialize PUDO operating layer"
Everyone on your team now has PUDO available when they open the repo in their AI tool.
Pick your next task. Work through these 4 steps before writing any code.
Write down — or paste into your AI assistant:
I need to [describe the task].
Before writing any code, create an implementation plan with:
- Scope: what is and isn't included
- Success criteria: how will I know it's done?
- Constraints: time, tech stack, backward compat
- Risks: what could go wrong?
Do not write code yet.
Review the plan. If something is vague, ask the AI to clarify. When the plan makes sense to you, move on.
Point the AI to the relevant existing code:
Before implementing, read [file or directory].
- What patterns does it follow?
- What would my change affect?
- Are there any conventions I should match?
You should be able to explain the relevant code structure to someone else before moving to Develop.
Now write the code. Prompt your AI:
Implement the plan using a task checklist.
Follow the existing patterns in [files].
Write tests alongside the implementation.
Flag any deviations from the plan.
Review each piece of generated code before accepting it. Don’t skip this.
Before calling it done:
Review the implementation:
- Is there anything to clean up?
- Does it follow the existing code style?
- Write a 3-sentence summary of what changed and why.
Run your project’s tests. If they pass, you’re done.
| Mode | When to Use |
|---|---|
| PUDO Lite | Typo fixes, one-liners, throwaway scripts. Run the 4 phases mentally — takes 30 seconds. |
| PUDO Standard | Most features and bug fixes. Write the plan, run the full cycle, leave a session note. |
| PUDO Enterprise | Production changes, security work, compliance. Add owner approval, rollback plan, monitoring check. |
See PUDO Modes for the full breakdown.
After completing a cycle:
npx pudo-code-system score — aim for 80 or above.pudo/session.md with what changed and why