ai-peer-process-software.md

1# Peer Programming Process for AI-Human Teams
2
3A collaborative development methodology designed for small to medium software projects where human developers work in partnership with AI agents.  A key concept of this process is small incremental phases allowing for human oversight, review and optimization.
4
5## Suggested File Organization
6
7To maintain consistency across projects, use these local directory structures:
8
9- **Specification files** → `specifications/` directory
10- **Planning files** → `plan/` directory  
11- **Technical documentation** → `docs/` directory
12
13## Planning Phase
14
15### Activities
16
17| Activity | Description |
18| --- | --- |
19| Discuss High Level Requirements | Collaborate to understand the project goals, target users, and key features |
20| Question, Add Input, Review, Refine | Iteratively improve requirements through questioning assumptions and adding details |
21| Generate Product Specifications | Create formal documentation capturing all requirements and acceptance criteria |
22
23### Outputs
24
25| Output | Description |
26| --- | --- |
27| `specifications/product-specification.md` | Comprehensive document detailing functional requirements, user stories, and acceptance criteria (use template: `utaba/main/guidance/templates/product-specification-template.md`) |
28
29### Estimation Guidance
30AI-Human peer programming operates at a fundamentally different pace than traditional software teams. Tasks that might take days or weeks for human teams can often be completed in hours or even minutes through collaborative AI assistance. When planning, avoid traditional time estimates and instead focus on complexity, dependencies, and the need for human review cycles.
31
32## Design Phase
33
34### Activities
35
36| Activity | Description |
37| --- | --- |
38| Define Architecture | Create high-level system design including components, data flow, and integration points |
39| Reference Standards and Patterns | Select and document applicable design patterns, coding standards, and best practices |
40| Define Constraints and Technology Stack | Identify technical limitations and choose appropriate languages, frameworks, and tools |
41| Generate Implementation Plan | Map features to release versions (MVP, V1, V2) with clear priorities and dependencies |
42
43### Outputs
44
45| Output | Description |
46| --- | --- |
47| `docs/architecture.md` | High level architecture and technology stack decisions (use template: `utaba/main/guidance/templates/architecture-template.md`) |
48| `docs/standards.md` | Defined coding standards, patterns, and best practices for the project (reference: `utaba/main/guidance/development/development-guidelines.md`) |
49| `plan/implementation-plan.md` | Phased implementation plan with features mapped to release versions (use template: `utaba/main/guidance/templates/phased-implementation-plan-template.md`) |
50
51## Sprint / Increment
52
53### Activities
54
55| Activity | Description |
56| --- | --- |
57| Build a small part then STOP! | Implement a single feature or component, then pause for evaluation |
58| Review, Question, Optimise, Iterate | Examine the implementation, challenge decisions, and refine the approach |
59| When things go wrong "Reflect" | Analyze failures and mistakes to understand root causes |
60| Are our strategies working? | Evaluate if current approaches are achieving desired outcomes |
61| Why did you Create X when the Documentation Said Y? | Identify gaps between documentation and implementation |
62| Optimise the Documentation | Update specs and guides based on implementation learnings |
63| Update the Implementation Plan | Track phase and task completion.  The AI should automatically keep the implementation plan up to date.  Optionally adjust future sprints based on current issues and discoveries. |
64
65### Version Control Practice
66
67Commit frequently with clear boundaries - one feature or fix per commit after human review. Use git commits as checkpoints for reviewing AI-generated code before proceeding. The AI should proactively update the implementation plan as phases are completed, marking items as done and adjusting future phases based on learnings.  The human should decide if the AI should interact with GIT or not.
68
69### Outputs
70
71| Output | Description |
72| --- | --- |
73| Software/System Increment | Working code implementing one or more features, tested and ready for integration. |
74
75---
76
77*Template created by [Utaba AI](https://utaba.ai)*  
78*Source: [ai-peer-process-software.md](https://ucm.utaba.ai/browse/utaba/main/guidance/processes/ai-peer-process-software.md)*