Skip to main content

AI Developer Documentation

Instructions for AI coding assistants (Claude, Copilot, etc.) working on urbalurba-infrastructure.

Documents​

DocumentPurpose
WORKFLOW.mdEnd-to-end flow from idea to implemented feature (start here)
PLANS.mdPlan structure, templates, and how to write plans

Plans Folder​

Implementation plans are stored in plans/:

plans/
├── active/      # Currently being worked on (max 1-2 at a time)
├── backlog/     # Approved plans waiting for implementation
└── completed/   # Done - kept for reference

File Types​

TypeWhen to use
PLAN-*.mdSolution is clear, ready to implement
INVESTIGATE-*.mdNeeds research first, approach unclear

Quick Reference​

When user says "I want to add X" or "Fix Y":​

  1. Create PLAN-*.md in plans/backlog/
  2. Ask user to review the plan
  3. Wait for approval before implementing

When user approves a plan:​

  1. Ask: "Do you want to work on a feature branch? (recommended)"
  2. Create branch if yes
  3. Move plan to plans/active/
  4. Implement phase by phase
  5. Ask user to confirm after each phase

When implementation is complete:​

  1. Move plan to plans/completed/
  2. Create Pull Request if on feature branch

When creating new manifests or services:​

  1. Read the Adding a Service Guide — complete step-by-step walkthrough covering service definitions, playbooks, manifests, secrets, and testing
  2. Follow the manifest numbering conventions (see manifests/ folder)
  3. Use appropriate namespace for the service category
  4. Validate before committing: kubectl apply --dry-run=client -f manifests/xxx-new-service.yaml
  5. Test deployment: kubectl rollout status deployment/xxx -n namespace