Production Apps

[!todo]

• upgrade this Process for Production Apps, like $MART DEBT App, later
• consolidate processes from multiple AIs below …

---

From Gemini Pro 2.5 =>

Phase 1: Discovery & Definition

AI-Assisted Brainstorming & Goal Definition:

• Use multiple diverse AI models (creative, analytical, domain-specific if available) alongside human ideation to explore the problem space, potential solutions, target audience, and core value proposition.
• Output: Project_Brief.md (High-level overview, problem, goal, audience, key differentiators).

AI-Generated Requirements Gathering & Feature Listing:

• Prompt AI(s) to elaborate on the brief, generating user stories, functional requirements, and non-functional requirements (performance, security, scalability).
• Human review and refinement are critical here to ensure alignment and feasibility.
• Output: Project_Description.md (Detailed features, user stories, functional & non-functional requirements).

Phase 2: Planning & Design

AI-Assisted Architecture & Tech Stack Selection:

• Provide the Project_Description.md to AI(s) knowledgeable about software architecture patterns and technologies.
• Prompt for suitable architectures (e.g., microservices, monolithic, serverless) and tech stack options (languages, frameworks, databases, cloud services).
• Human makes the final decision based on AI recommendations, team expertise, and project constraints.
• Output: Architecture_Design.md (Chosen architecture, tech stack, high-level component diagram, key technology decisions).

AI-Assisted UI/UX Design (Optional but Recommended):

• Use AI tools to generate wireframes, mockups, or even basic interactive prototypes based on user stories.
• Human designers refine and finalize the user experience and visual design.
• Output: UI_UX_Specification.md (Wireframes, mockups, style guide references, user flow diagrams).

AI-Generated Data Modeling & API Design:

• Based on requirements and architecture, prompt AI to design database schemas, define API endpoints (e.g., OpenAPI spec), and outline data flow.
• Human review and refinement are essential for consistency and correctness.
• Output: Data_Model_API_Spec.md (DB schemas, API contracts).

AI-Generated Detailed Project Plan & Task Breakdown:

• Feed Project_Description.md, Architecture_Design.md, UI_UX_Specification.md, and Data_Model_API_Spec.md into an AI.
• Prompt it to generate a hierarchical task list (Work Breakdown Structure - WBS).
• Crucially: Implement a robust Unique Task Identification System (e.g., hierarchical numbering 1.1.2, feature-based slugs feat-login-backend-auth, or UUIDs) from the start. This is vital for referencing, dependency tracking, and parallel execution management.
• Define Dependencies between tasks explicitly.
• Identify tasks suitable for Parallel Execution.
• Human review focuses on task granularity (small, testable units), logical flow, dependencies, and potential bottlenecks.
• Output: Project_Plan.md (Hierarchical tasks with IDs, dependencies, estimated effort/complexity [AI-assisted], parallel potential flagged).

Phase 3: Development & Integration (Iterative Loop)

Environment Setup & Tooling Configuration:

• Use AI to generate configuration files (Dockerfiles, package.json, requirements.txt, CI/CD pipeline templates). Human verifies and sets up the actual environments.
• Output: Configuration files checked into Git, potentially Environment_Setup.md.

AI Agent Task Execution (Managed):

• Assign Task: Assign a specific, granular task (using its Unique ID) to an AI development agent.
• Provide Context: Ensure the agent has access to relevant master files (Project_Description.md, Architecture_Design.md, Data_Model_API_Spec.md, specific task description from Project_Plan.md, and potentially snippets of existing relevant code). Context management is key! Consider using vector databases or specific context-aware frameworks.
• Develop: AI agent generates code, configuration, or other required artifacts for the task.
• Unit Test: AI agent generates and runs unit tests for the code it produced.

Integrate Basic Monitoring/Logging:

• AI incorporates basic logging and potentially integrates error tracking SDKs (like Sentry) as part of the task, where applicable.

Code Review (AI + Human):

• Use AI code analysis tools and perform human review, focusing on logic, security, performance, and adherence to standards.

Version Control:

• AI (or human oversight) commits the solution to a dedicated feature branch in Git (e.g., git checkout -b task/1.2.3-implement-login-api).
• Commit messages should reference the Task ID.
• Log progress in DevLog.md (can be automated/assisted by AI).

Integration & Testing:

• Once a feature branch passes review and automated checks (CI pipeline), merge it into a main development branch (develop or main).
• Run Integration Tests automatically upon merges to ensure components work together. AI can help generate these tests based on API specs and component interactions.
• Perform End-to-End (E2E) Testing periodically or automatically, potentially using AI-driven testing tools.

Continuous Feedback Loop:

• Deploy to a staging environment frequently.
• Gather User Feedback (or stakeholder feedback) on integrated features, even during active development. Use this feedback to refine tasks in the Project_Plan.md or add new ones.

Phase 4: Deployment & Post-Development

Final Testing & Quality Assurance:

• Comprehensive E2E testing, performance testing, security vulnerability scanning (AI tools can assist).
• User Acceptance Testing (UAT).

AI-Assisted Documentation Generation & Refinement:

• Use AI to generate initial user docs, API documentation (from code/specs), and improve code comments. Human review and refinement are essential.
• Output: User_Manual.md, API_Documentation.md, updated code comments.

Deployment:

• Execute Deployment_Plan.md (which could be AI-assisted in creation). Use CI/CD pipelines.

Post-Deployment Monitoring & Maintenance:

• Monitor application performance, errors (Sentry), and logs.
• Use AI tools for anomaly detection or log analysis (AIOps).
• Plan for ongoing maintenance, bug fixes, and feature updates (returning to Phase 1/2 for larger changes).

Project Retrospective (AI-Assisted Analysis):

• Analyze DevLog.md, commit history, bug reports, and performance data. AI can help identify patterns, bottlenecks in the process, or areas where estimates were off.
• Refine the meta-process itself based on learnings.

Other Useful Master Files & Main Sections:

Project_Brief.md

• Problem Statement: What user/business problem are we solving?
• Proposed Solution: High-level concept of the app/website.
• Goals/Objectives: What are the measurable success criteria? (e.g., user acquisition, conversion rate, task completion time).
• Target Audience: Who are the primary users?
• Key Differentiators: What makes this unique?

Architecture_Design.md

• Overview: High-level summary of the chosen architecture.
• Architectural Goals & Constraints: Non-functional requirements driving decisions (scalability, maintainability, cost, security).
• Chosen Architecture Pattern: (e.g., Microservices, Monolith, Serverless, MVC). Justification.
• Component Diagram: Visual representation of major system components and their interactions.
• Technology Stack: List of primary languages, frameworks, databases, libraries, cloud services, APIs. Justification for key choices.
• Data Management Strategy: How data flows, where it’s stored, consistency models.
• Deployment Strategy Overview: High-level plan (e.g., Cloud provider, containerization, CI/CD).
• Security Considerations: High-level approach to authentication, authorization, data protection.

UI_UX_Specification.md (Can be a link to Figma/Sketch files + markdown)

• User Personas: Descriptions of typical users.
• User Flow Diagrams: Visual paths users take through the application.
• Wireframes: Low-fidelity layout structures.
• Mockups/Prototypes: High-fidelity visual designs (often links to design tools).
• Style Guide / Design System: Rules for colors, typography, spacing, component appearance (link or embedded rules).
• Accessibility Guidelines: Specific WCAG level or guidelines to adhere to.

Data_Model_API_Spec.md

• Database Schema: Diagrams (e.g., ERD), table definitions, field types, constraints, relationships.
• API Specification: (Often a separate OpenAPI/Swagger JSON/YAML file linked here)
  • Base URL(s)
  • Authentication/Authorization Methods
  • Endpoints (Path, Method - GET/POST/PUT/DELETE)
  • Request Parameters (Path, Query, Header, Body)
  • Request/Response Body Schemas (JSON structures)
  • Status Codes and Error Handling
• State Management Design (for Frontend): Structure of client-side state, chosen library/pattern (Redux, Zustand, Context API), key state slices.

Test_Plan.md

• Testing Scope & Objectives: What is/isn’t being tested? What are the quality goals?
• Testing Types: Unit, Integration, E2E, Performance, Security, Usability, Accessibility. Who is responsible? How automated?
• Testing Tools & Frameworks: Jest, Cypress, Playwright, Selenium, K6, ZAP, etc.
• Test Environments: Dev, Staging, Production (and their configurations).
• Test Data Management: How test data is generated/managed.
• Entry/Exit Criteria: Conditions for starting/stopping test cycles.
• Defect Tracking Process: How bugs are reported, prioritized, and tracked.

Deployment_Plan.md

• Deployment Environments: Details of Dev, Staging, Production infrastructure.
• CI/CD Pipeline Configuration: Tools (Jenkins, GitLab CI, GitHub Actions), stages (build, test, deploy).
• Deployment Steps: Sequence of actions for deploying code.
• Rollback Procedure: Steps to revert to a previous stable version.
• Environment Variables & Secrets Management: How configuration differs per environment and how secrets are handled.
• Post-Deployment Verification Checks: Steps to ensure the deployment was successful.

Environment_Setup.md (or just config files in Git)

• Prerequisites: Required software (Node.js version, Python version, Docker, etc.).
• Installation Steps: How to get the project running locally.
• Key Configuration Files: Explanation of .env, docker-compose.yml, etc.
• Running the Application: Commands to start dev servers, linters, etc.
• Running Tests: Commands to execute different test suites.

DevLog.md / CHANGELOG.md

• DevLog.md (Chronological):
  • Timestamped entries of significant actions, decisions, experiments, issues encountered, task progress (linked to Task IDs). Can be partially automated from Git commits.
• CHANGELOG.md (Version-Based): User-facing summary of changes for each release (New Features, Bug Fixes, Changes). Often follows Keep a Changelog format.

These master files act as the “single source of truth” and provide essential context for both human developers and AI agents, especially crucial for enabling effective parallel development and maintaining consistency across the project.

---

From ChatGPT(?) =>

Purpose

A Meta-Process for AI-Powered Development of Production Apps

This document defines a structured, repeatable process to leverage AI agentic development tools for building production apps efficiently. It enables modular, parallel development powered by multiple AI systems working in concert.

Goals

• Accelerate development with AI-assisted brainstorming, planning, coding, and testing.
• Maintain project clarity and traceability with well-defined artifacts.
• Enable independent, parallel development by multiple agents.
• Ensure high-quality outcomes through iterative testing and optimization.

Master Files & Artifacts

The following documents serve as the foundation of every project:

File Name	Purpose	Main Sections
Project_Description.md	Human-readable project overview	Overview, Goals, Personas, Features, Constraints
Project_Plan.md	Hierarchical task roadmap	Milestones, Tasks, Dependencies, Priority
Task_Index.yaml	All tasks indexed with status	TaskID, Title, Status, Assignee, Notes
DevLog.md	Developer + AI activity log	Date, Author, Task ID, Summary, Outcome
AI_Insights.md	AI-generated ideas and decisions	Topic, Insight, Decision, Follow-up
DataSchemas.md	Data structure definitions	Models, Validation Rules, Relationships
APIDesign.md	API contract documentation	Route, Method, Params, Responses
UIComponents.md	Design system reference	Component, Props, State, Events
ChangeLog.md	Version history of master files	Version, Date, Summary, Impact
Testing.md	Testing strategies and case index	Unit Tests, Integration, E2E, Tools

Meta Process Steps

1: Brainstorm & Describe

• Use a multi-agent AI system to brainstorm app/website concepts.
• Develop the Project_Description.md file collaboratively with AI.

2: Plan & Decompose

• Generate Project_Plan.md with hierarchical tasks and milestones.
• Assign unique task identifiers (Task_Index.yaml) to enable tracking and referencing.
• Break down tasks into testable, independently buildable components.

3: Prepare for Parallel AI Development

• Define shared contracts and components:
  • DataSchemas.md
  • APIDesign.md
  • UIComponents.md
• Ask AI how to optimize for parallel execution and minimal conflicts.

4: AI-Led Development & Logging

For each task:

• Use task-aware AI to develop solution code.
• Include appropriate tests.
• Integrate with error tracking (e.g., Sentry) and performance monitoring.
• Commit code to GIT (use branches for task-specific work).
• Log work in DevLog.md.
• Request real-time user feedback as appropriate.

5: Integration & Testing

• Conduct end-to-end testing as modules integrate.
• Use AI to suggest optimizations and refactors.

6: Post-Development Cleanup

• Final QA, error monitoring, and doc review.
• Purge unused assets, dead code, and temporary files.
• Archive AI insights and finalize ChangeLog.md.

AI Agent Roles

Role	Description
🧠 Planner	Converts idea into structured project plan
🛠️ Builder	Writes modular, testable code
🧪 Tester	Generates and runs tests, benchmarks
🔍 Optimizer	Refines for performance/readability
📚 DocWriter	Auto-documents code and APIs
🧭 Meta Advisor	Enhances this development process

Tooling Recommendations

• GIT: Branching per task
• Markdown/YAML: Master files and structure
• Sentry or similar: Error tracking
• VSCode + AI Plugins: Active dev environment
• Obsidian / Notion: Knowledge management (optional)

Version & Change Management

• Track all edits in ChangeLog.md
• Use semantic versioning (e.g., v1.0.0 → v1.1.0 → v1.1.1)
• Include authorship (AI or human) for major insights or revisions

End-to-End Flow Summary

1. Brainstorm → Project_Description.md
2. Plan → Project_Plan.md
3. Break out tasks → Task_Index.yaml
4. Define schemas, APIs, UI → Shared files
5. Parallel dev → code + tests + commit + log
6. Integration → test + optimize
7. Finalize → cleanup + monitor + document

Appendix (Optional Templates)

• AI prompt templates
• Task template markdown
• Git branch naming conventions
• User feedback form
• Code quality checklist

---

🔄 This document is meant to evolve with experience. After each project, review and ask: "How can this meta-process improve?"