Skip to content

Dev Knowledge

Updated: 2026-06-05

Durable development process and patterns. Written for AI retrieval.

Development Process

Every project follows this sequence. Do not skip or invert steps.

Phase Output Gate
Market research Is there demand? Who are competitors? Intake: build, research, revise, or drop
MVP definition Smallest thing that proves value One-sentence MVP scope agreed
Architecture Stack, data model, API design, key decisions spec.md reviewed and approved
Development Working code for the approved round Build stayed inside approved scope
Testing Acceptance results, simple security checks, defect report Critical/high issues resolved
Release Deployed and accessible Human release approval
Review What worked, what did not, what changed decisions.md and lessons updated

Project Folder Structure

Each project lives in wiki/dev/[project-name]/:

brief.md        one-paragraph problem statement + target user
spec.md         MVP, stack, data model, API design, UI/security risks, acceptance criteria
decisions.md    what was tried, what was abandoned, why
status.md       current phase, blockers, next steps
defects.md      acceptance and security test findings

Dev Agent Roles

Agent Trigger Reads Writes
Planner plan: [project] dev/_knowledge.md, existing specs, Agile Gates, UI Guidelines, Secure Coding and Testing dev/[project]/spec.md
Implementer build: [task] Approved dev/[project]/spec.md and approved round Code in the repo
Tester test: [task] dev/[project]/spec.md, Secure Coding and Testing, UI Guidelines if UI-facing dev/[project]/defects.md

Required plan: Output

Planner must include:

  • MVP scope
  • Target user and primary workflow
  • Acceptance criteria
  • UI risks and required UI states when the work has a UI
  • Security risks and required security checks
  • Estimate band: S, M, L, or XL
  • Proposed token budget
  • Out-of-scope items

Required build: Output

Implementer must include:

  • Approved spec or round reference
  • Changed files
  • What was completed
  • Known limits or follow-up tasks
  • Confirmation that scope did not expand

If the task no longer fits the approved round, stop and propose a split.

Required test: Output

Tester must include:

  • Acceptance results
  • Simple security test results
  • UI screenshot review results for UI-facing work
  • Defects by severity
  • Untested areas
  • Release recommendation: ship, hold, or revise

Stack Defaults

  • Web apps: Python + FastAPI backend, plain HTML/JS or React frontend
  • Games: Phaser.js for browser 2D, or Unity/Godot for native
  • Websites: Static HTML + CSS, or MkDocs for doc-style sites
  • Hosting: Railway for apps, Cloudflare Pages for static sites
  • Database: SQLite for prototypes, Postgres for production

Code Standards

  • Readable by humans and AI agents; clear naming and no magic constants
  • Every repo has a README.md with setup and run instructions
  • Decisions go in decisions.md, not hidden in comments
  • Tests cover all acceptance criteria in the spec
  • Secrets, credentials, and client data follow Secure Coding and Testing
  • UI work follows UI Guidelines

Mistakes To Avoid

  • Building before the MVP is defined; this creates scope creep
  • Skipping decisions.md; the next agent or human will repeat the same mistakes
  • Treating testing as only happy-path behavior
  • Shipping UI without empty/loading/error states
  • Starting XL work without splitting it into smaller rounds
  • Over-engineering v1; the goal is the simplest thing that works