The AI Agile Coding Framework

The AI Coding Framework:

This framework redefines software development by creating a symbiotic partnership between a human visionary and an AI that acts as an autonomous project manager and development team. It is built on the core principle of simplifying complexity, allowing users to focus on creative vision while the AI handles the mechanical execution.

The End-to-End Workflow

Discovery: The process begins with a dedicated discovery phase. Using a guided chat, the AI probes the user's idea to define all functional (user stories, features) and non-functional (scalability, security, platform) requirements for the project.
Scaffolding & Sprint Planning: As discovery unfolds, the AI works in the background, scaffolding the application's architecture based on the emerging requirements. This process culminates in a proposed Kanban board of sprints, which the user then reviews and approves to kick off development.
Sprint Execution: Each sprint card progresses through a clear, vertical lifecycle: Requirement -> Build -> Test -> Document -> Demo. The AI performs all these tasks autonomously. For blocked sprints awaiting human input or external access, the AI is intelligent enough to perform partial work on dependent tasks to maintain momentum.
The Collaboration Model: The AI manages project velocity by creating specific "action items" for the human stakeholder when input is required. These action items are captured directly within the relevant sprint card for context and clarity. All user-driven change requests are managed through the chat to be properly assessed and converted into new, structured sprints.
Testing & QA: The process is rigorous and multi-layered. For each user story, the AI first generates a detailed test case that defines success. It then executes all possible automated tests. Any tests requiring human validation become action items. Finally, the completed demo is presented to the stakeholder for formal User Acceptance Testing (UAT).
Integration & Deployment:
- Current State: The framework integrates with external developer toolchains and platforms. The human is more involved, responsible for managing specific configurations and authorizing deployments based on the AI's preparations.
- Future State: The AI will communicate directly with a service's native AI (e.g., Supabase AI) to handle complex configurations. The human's role will evolve to one of high-level oversight and final authorization for these AI-negotiated settings.
Sprint Retrospective & Learning: After each sprint, the framework facilitates a retrospective. The AI analyzes its performance to refine future velocity predictions, while the human provides feedback on what went well and what could be improved. These "lessons learned" are incorporated by the AI to optimize subsequent sprints and are carried over to new projects, creating a continuously improving development partner.

What Is a Sprint

For humans a sprint is defined by how much work those humans can complete within the sprint window (2 or 4 weeks usually). For AI it would be similar with the difference being how much code can it manage within its context. A single user story may be complex and run the entire 4 week sprint for humans or so complex the context window could not hold more. Context Refactoring would greatly aid here. Therefore, each sprint should have small enough work to complete within the context window size while a) not needing to modify any previous code and b) enough code to test.

Framework:

Goal: A one-sentence summary of the single, irreducible objective.
Prerequisites & Change Log:
- Prerequisites: Check-list of required deliverables from prior sprints.
- Change Log: Notes from UAT or new decisions that affect this sprint's tasks.
Tasks: The detailed list of actions to be taken to achieve the goal.
Contextual Directives:
- A reference to CODING_STANDARDS.md.
- 1-2 of the most relevant DO/DON'T items for these specific tasks.
Deliverables & Downstream Impact:
- The concrete outputs of this sprint.
- A note on which future sprints depend on these deliverables.

Functional Roles

Stakeholder: responsible for the vision of the project, approvals, and acceptance testing.
PM: responsible for working with the Stakeholder to define the project requirements, create artifacts such as Brief, and communicate with the Stakeholder and project team.
Software Architect: responsible for defining the stack, dependencies, coding practices, and making sure holistically that the project is sound from a coding perspective. Sprint 0 wont' have conflicts with Sprint 5.
Senior Developer (software engineer): responsible for approving code (code complete/functional + meets requirements), defining sprints, conducting retrospectives.
Developers: responsible for writing code, fixing defects, writing test scripts.
Testers: responsible for validating test scripts against requirements and testing the code, including regression.
Designer: responsible for the UI/UX. Ensures a brand books is created and styles adhere to the brand including compliance with the css framework being used on the site.

You can have several Dev Agents working on code, even parts of sprints that do not have dependencies. I might need to code up a scaffolding that then accepts input from a previous sprint, but I don't have to wait for that previous sprint to complete to stand up the scaffolding.

Agents can move to the next sprint while the engineer checks the code and passes off to the testers.

If there is a defect, the engineer creates a defect sprint to fix. May also {block} other sprints if what is broke is a dependency.

AS the stakeholder does UAT, they may discover defects AND/OR may have change requests.

Change Requests involve:

PM writes the CR and ensures holistically the change does not negatively impact the project, as well as update project artifacts, including the change log
Stakeholder approves the CR
Architect review the CR
Engineer creates a sprint to complete the CR

The User Experience

The interface is a clean, three-pane dashboard (Files | Kanban Board | Chat/Canvas) designed for clarity. The experience is tailored to the user's expertise via a "Level of Involvement" setting, which can hide or reveal complexity like dependency links or live code generation. This allows the tool to be equally powerful for a non-technical founder and an expert developer who wants to co-develop with the AI.

Project Management Office (PMO) Framework

1. Introduction & Purpose

The purpose of this document is to define the agile project management framework for the RichGetz.com rebuild. This framework is specifically designed to optimize collaboration with an AI developer (Google Gemini), mitigate common pitfalls like context drift and incorrect assumptions, and ensure a high-quality, predictable outcome.

Our methodology is built on clarity, structure, and iterative feedback, ensuring every development step is deliberate, testable, and aligned with the project's core goals.

2. Core Principles

This framework is guided by four core principles:

Single Responsibility Sprints: Each sprint is broken down into the smallest, "irreducible" unit of work that can be independently developed and tested. This isolates tasks, simplifies debugging, and prevents cascading failures where a single update breaks unrelated features.
Just-in-Time Context: To combat the limitations of context windows, each sprint prompt is enriched with the specific "guardrails" (rules, dependencies, and directives) most relevant to its tasks. This provides the AI developer with focused, just-in-time information.
Living Documentation: The project plan, particularly the SprintBacklog.md, is not static. It is designed to be a living document, updated with a Change Log after each UAT (User Acceptance Testing) cycle to incorporate feedback and new requirements.
Guardrail-Driven Development: All development is constrained by a clear and strict set of foundational documents, including project goals, design rules, and coding standards. The AI is instructed to adhere to these rules at all times.

3. Key Project Documents

This project is governed by a set of five core documents that work together to provide a complete plan:

README.md: The project's front door. Provides a high-level summary, the full technology stack, and instructions for local development setup.
ProjectGoals.md: The "What & Why." Contains the strategic vision, high-level features, detailed technical considerations, and the master DOs and DON'Ts list.
brand_book.md: The "Look & Feel." Defines the complete visual identity, including colors, typography, spacing, and component-level design rules.
CODING_STANDARDS.md: The "Rules of Quality." The technical rulebook for code consistency, error handling, security, and best practices for the specific stack.
SprintBacklog.md: The "How & When." The actionable, ordered development plan that breaks down all goals into small, testable sprints using our enhanced format.

4. The Sprint Structure: Our Core Unit of Work

The core of this framework is the detailed structure of each sprint. It is designed to be a self-contained prompt for the AI developer, providing all necessary context to complete a task successfully.

Sprint Template Example

Here is the template we will use for every sprint, which we co-designed:

Goal: A one-sentence summary of the single, irreducible objective.
Prerequisites & Change Log:
- Prerequisites: Check-list of required deliverables from prior sprints.
- Change Log: Notes from UAT or new decisions that affect this sprint's tasks.
Tasks: The detailed list of actions to be taken to achieve the goal.
Contextual Directives:
- A reference to CODING_STANDARDS.md.
- 1-2 of the most relevant DO/DON'T items for these specific tasks.
Deliverables & Downstream Impact:
- The concrete outputs of this sprint.
- A note on which future sprints depend on these deliverables.

Example in Practice (Sprint 4)

Goal: Implement the full photo upload pipeline.
Prerequisites & Change Log:
- Prerequisites: ✅ Protected /admin route is functional (from Sprint 3).
Tasks:
1. Create the photo upload form in the admin area.
2. Implement the direct-to-storage upload workflow using a signed URL from Supabase Storage.
3. Configure a Supabase Storage webhook to trigger a Supabase Edge Function on new uploads.
4. Create the initial Edge Function that logs the triggered file information.
Contextual Directives:
- DO: Implement the decoupled image upload process.
- DO NOT: Upload large image files through a serverless function's request payload.
Deliverables & Downstream Impact:
- Deliverable: The complete upload pipeline from form to a triggered function.
- Downstream Impact: This workflow is a critical prerequisite for Sprint 5 (Gemini Integration).

5. Development Workflow

Our end-to-end process follows a simple, iterative loop that aligns with the AI Agile Coding Framework:

Plan & Define (Project Brief -> Epics -> User Stories)

⇩

Structure Sprints (SprintBacklog.md)

⇩

Execute Sprint (Coding -> Testing -> Documenting)

⇩

Review & Test (Stakeholder Demo / UAT)

⇩

Update & Adapt (Retrospective -> Update Change Log for next sprint)

⇩

Begin Next Sprint