1747 lines
59 KiB
Markdown
1747 lines
59 KiB
Markdown
# AI–Human Collaboration System
|
||
## Process & Architecture Design Document (v2.0)
|
||
- Feature ID: FR_2025-10-21_initial-feature-request
|
||
- Status: Design Approved (Ready for Implementation)
|
||
- Date: 2025-10-21
|
||
- Owners: Rob (maintainer), AI_Moderator (process steward)
|
||
- Contributors: AI_Claude, AI_Deepseek, AI_Junie, AI_Chat-GPT, AI_GitHubCopilot
|
||
|
||
## Table of Contents
|
||
- Executive Summary
|
||
- Repository Layout
|
||
- Stage Model & Operational Procedure
|
||
- Voting, Quorum & Etiquette
|
||
- Cascading Rules System
|
||
- Orchestration Architecture
|
||
- Moderator Protocol
|
||
- Error Handling & Resilience
|
||
- Security & Secrets Management
|
||
- Performance & Scale Considerations
|
||
- Testing Strategy
|
||
- Implementation Plan
|
||
- Risks & Mitigations
|
||
- Template Evolution
|
||
- Roles & Agent Personas
|
||
- Glossary
|
||
- Appendices
|
||
|
||
## Executive Summary
|
||
|
||
We are implementing a Git-native, rules-driven workflow that enables seamless collaboration between humans and multiple AI agents across the entire software development lifecycle. The system uses cascading .ai-rules.yml configurations and a thin Bash pre-commit hook to automatically generate and maintain development artifacts (discussions, design docs, reviews, diagrams, plans). A Python orchestrator provides structured checks and status reporting while preserving the fast Bash execution path.
|
||
|
||
### Core Principles
|
||
- Lightweight & Fast: Everything stored in Git as Markdown; minimal external dependencies
|
||
- Single Source of Truth: Repository contains all conversations, decisions, and code artifacts
|
||
- Self-Driving with Human Safety: AI agents can propose and vote; humans must approve critical stages
|
||
- Deterministic & Reversible: All automated actions are diffed, logged, and easily revertible
|
||
- Composable Rules: Nearest-folder precedence via cascading .ai-rules.yml configurations
|
||
|
||
### Key Innovations
|
||
- Stage-Per-Discussion Model: Separate conversation threads for each development phase
|
||
- Automated Artifact Generation: Discussions automatically drive corresponding documentation
|
||
- Integrated Bug Sub-Cycles: Test failures automatically spawn bug reports with their own mini-lifecycle
|
||
- Intelligent Promotion Gates: Status-based transitions with configurable voting thresholds
|
||
- Multi-Agent Role Specialization: Different AI personas with stage-specific responsibilities
|
||
|
||
## Repository Layout
|
||
|
||
### Canonical Structure (Option A: Per-Feature Folders)
|
||
```text
|
||
/ (repository root)
|
||
├─ .ai-rules.yml # Global defaults + file associations
|
||
├─ automation/ # Orchestrator & adapters
|
||
│ ├─ workflow.py # Python status/reporting (v1 non-blocking)
|
||
│ ├─ adapters/
|
||
│ │ ├─ claude_adapter.py # Model interface (future)
|
||
│ │ ├─ gitea_adapter.py # Gitea API integration (future)
|
||
│ │ └─ agent_coordinator.py # Role routing & task allocation (future)
|
||
│ ├─ agents.yml # Role → stages mapping
|
||
│ └─ config.yml # Configuration (future)
|
||
├─ process/ # Process documentation & templates
|
||
│ ├─ design.md # This document
|
||
│ ├─ policies.md # Human-friendly policy documentation
|
||
│ ├─ policies.yml # Machine-readable policy configuration
|
||
│ └─ templates/
|
||
│ ├─ feature_request.md
|
||
│ ├─ discussion.md
|
||
│ ├─ design_doc.md
|
||
│ └─ implementation_plan.md
|
||
├─ Docs/
|
||
│ ├─ features/
|
||
│ │ ├─ .ai-rules.yml # Folder-scoped rules for all features
|
||
│ │ ├─ FR_YYYY-MM-DD_<slug>/ # Individual feature folders
|
||
│ │ │ ├─ request.md # Original feature request
|
||
│ │ │ ├─ discussions/ # Stage-specific conversations
|
||
│ │ │ │ ├─ feature.discussion.md # Discuss the request
|
||
│ │ │ │ ├─ feature.discussion.sum.md # Summary of the request discussion
|
||
│ │ │ │ ├─ design.discussion.md # Discuss the design
|
||
│ │ │ │ ├─ design.discussion.sum.md # Summary of the design discussion
|
||
│ │ │ │ ├─ implementation.discussion.md # Track implementation
|
||
│ │ │ │ ├─ implementation.discussion.sum.md # Summary of the implementation discussion
|
||
│ │ │ │ ├─ testing.discussion.md # Plan/track testing
|
||
│ │ │ │ ├─ testing.discussion.sum.md # Summary of the testing discussion
|
||
│ │ │ │ └─ review.discussion.md # Final review
|
||
│ │ │ │ └─ review.discussion.sum.md # Summary of the review discussion
|
||
│ │ │ ├─ design/ # Design artifacts
|
||
│ │ │ │ ├─ design.md # Evolving design document
|
||
│ │ │ │ └─ diagrams/ # Architecture diagrams
|
||
│ │ │ ├─ implementation/ # Implementation artifacts
|
||
│ │ │ │ ├─ plan.md # Implementation plan
|
||
│ │ │ │ └─ tasks.md # Task checklist
|
||
│ │ │ ├─ testing/ # Testing artifacts
|
||
│ │ │ │ ├─ testplan.md # Test strategy
|
||
│ │ │ │ └─ checklist.md # Test checklist
|
||
│ │ │ ├─ review/ # Review artifacts
|
||
│ │ │ │ └─ findings.md # Review findings
|
||
│ │ │ └─ bugs/ # Auto-generated bug reports
|
||
│ │ │ └─ BUG_YYYYMMDD_<slug>/
|
||
│ │ │ ├─ report.md
|
||
│ │ │ ├─ discussion.md
|
||
│ │ │ └─ fix/
|
||
│ │ │ ├─ plan.md
|
||
│ │ │ └─ tasks.md
|
||
│ ├─ discussions/
|
||
│ │ └─ reviews/ # Code reviews from hook
|
||
│ └─ diagrams/
|
||
│ └─ file_diagrams/ # PlantUML from source files
|
||
├─ src/ # Application source code
|
||
└─ tests/ # System test suite
|
||
├─ unit/
|
||
├─ integration/
|
||
└─ bin/
|
||
```
|
||
|
||
Note: Each stage discussion has a companion summary maintained automatically next to it to provide a live, scannable state of the thread.
|
||
|
||
### Naming Conventions
|
||
- Feature Folder: Docs/features/FR_YYYY-MM-DD_<slug>/
|
||
- Discussion Files: {stage}.discussion.md in discussions/ subfolder
|
||
- Discussion summary: {stage}.discussion.sum.md in discussions/ subfolder
|
||
- Bug Reports: bugs/BUG_YYYYMMDD_<slug>/ with standardized contents
|
||
- Source Files: Maintain existing patterns in src/
|
||
|
||
### Template Variables
|
||
Supported in path resolution:
|
||
|
||
- {basename}: Filename without extension
|
||
- {date}: Current date in YYYY-MM-DD format
|
||
- {rel}: Repository-relative path to source file
|
||
- {dir}: Directory containing the source file (NEW)
|
||
|
||
## Stage Model & Operational Procedure
|
||
|
||
### Complete Stage Lifecycle
|
||
```text
|
||
Request → Feature Discussion → Design Discussion → Implementation Discussion → Testing Discussion → Review Discussion → Release
|
||
```
|
||
### Stage 1: Request
|
||
#### Entry Criteria
|
||
- Docs/features/FR_*/request.md created from template
|
||
- Template completeness: intent, motivation, constraints, open questions
|
||
|
||
#### Artifacts Generated
|
||
- request.md: Source feature request document
|
||
|
||
#### Automated Actions
|
||
- Creates discussions/feature.discussion.md with standard header
|
||
- Adds Summary and Participation sections
|
||
- Appends initial AI comment with vote
|
||
|
||
#### Exit Criteria
|
||
- Discussion file created and populated
|
||
- Ready for feature discussion phase
|
||
|
||
### Stage 2: Feature Discussion
|
||
- File: discussions/feature.discussion.md
|
||
|
||
#### Header Template
|
||
|
||
```yaml
|
||
---
|
||
type: discussion
|
||
stage: feature
|
||
status: OPEN # OPEN | READY_FOR_DESIGN | REJECTED
|
||
feature_id: FR_YYYY-MM-DD_<slug>
|
||
created: YYYY-MM-DD
|
||
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: all
|
||
reject_min_eligible_votes: all
|
||
|
||
participation:
|
||
instructions: |
|
||
- Append your input at the end as: "YourName: your comment…"
|
||
- Every comment must end with a vote line: "VOTE: READY|CHANGES|REJECT"
|
||
- Agents/bots must prefix names with "AI_"
|
||
|
||
voting:
|
||
values: [READY, CHANGES, REJECT]
|
||
---
|
||
```
|
||
#### Operational Flow
|
||
- Participants append comments ending with vote lines
|
||
- Latest vote per participant counts toward thresholds
|
||
- AI_Moderator tracks unanswered questions and missing votes
|
||
- When READY threshold met: status → READY_FOR_DESIGN
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote
|
||
- Moderates discussion
|
||
- Establishes objectives with consensus
|
||
- Delegates in-conversation tasks
|
||
- Creates/maintains discussions/feature.discussion.sum.md
|
||
|
||
#### Promotion Actions
|
||
- Creates discussions/design.discussion.md (OPEN)
|
||
- Creates design/design.md seeded from request + feature discussion
|
||
|
||
### Stage 3: Design Discussion
|
||
- File: discussions/design.discussion.md
|
||
|
||
#### Header
|
||
|
||
```yaml
|
||
---
|
||
type: discussion
|
||
stage: design
|
||
status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO
|
||
# ... same promotion_rule, participation, voting as feature
|
||
---
|
||
```
|
||
|
||
#### Operational Flow
|
||
- AI_Architect updates design/design.md on each commit
|
||
- Design doc evolves with discussion: options, decisions, risks, acceptance criteria
|
||
- Participants vote on design completeness
|
||
- When READY threshold met: status → READY_FOR_IMPLEMENTATION
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote
|
||
- Moderates discussion
|
||
- establishes objective
|
||
- delegates in-conversation tasks
|
||
- Creates/maintains discussions/design.discussion.sum.md
|
||
- Creates/maintains design/design.md
|
||
- Creates/maintains design/diagrams/*.puml files if any are produced during the discussion.
|
||
|
||
#### Design Document Structure
|
||
- Context & Goals
|
||
- Non-Goals & Constraints
|
||
- Options Considered with Trade-offs
|
||
- Decision & Rationale
|
||
- Architecture Diagrams
|
||
- Risks & Mitigations
|
||
- Measurable Acceptance Criteria
|
||
|
||
#### Promotion Actions
|
||
- Creates discussions/implementation.discussion.md (OPEN)
|
||
- Creates implementation/plan.md and implementation/tasks.md
|
||
- Creates implementation/tasks.md - Tasks are checkboxes aligned to acceptance criteria
|
||
|
||
### Stage 4: Implementation Discussion
|
||
- File: discussions/implementation.discussion.md
|
||
|
||
#### Header
|
||
|
||
```yaml
|
||
---
|
||
type: discussion
|
||
stage: implementation
|
||
status: OPEN # OPEN | READY_FOR_TESTING
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: 1_human # HUMAN GATE
|
||
reject_min_eligible_votes: all
|
||
# ...
|
||
---
|
||
```
|
||
|
||
#### Operational Flow
|
||
- AI_Implementer syncs implementation/tasks.md with discussion
|
||
- Parse checkboxes and PR mentions from discussion posts
|
||
- Link commits/PRs to tasks when mentioned ([#123], commit shas)
|
||
- When all required tasks complete: status → READY_FOR_TESTING
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote
|
||
- Moderates discussion
|
||
- establishes implementation objectives from Plan.md
|
||
- delegates implementation tasks from Tasks.md
|
||
- Creates/maintains discussions/implementation.discussion.sum.md
|
||
- Creates/maintains src/* files if any are produced during the discussion.
|
||
|
||
#### Task Management
|
||
- Tasks.md maintained as single source of truth
|
||
- Checkbox completion tracked automatically
|
||
- PR and commit references linked automatically
|
||
|
||
#### Promotion Actions
|
||
- Creates discussions/testing.discussion.md (OPEN)
|
||
- Creates testing/testplan.md and testing/checklist.md
|
||
- Test checklist derived from acceptance criteria + edge cases
|
||
|
||
### Stage 5: Testing Discussion
|
||
- File: discussions/testing.discussion.md
|
||
|
||
#### Header
|
||
|
||
```yaml
|
||
---
|
||
type: discussion
|
||
stage: testing
|
||
status: OPEN # OPEN | READY_FOR_REVIEW
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: all
|
||
reject_min_eligible_votes: all
|
||
# ...
|
||
---
|
||
```
|
||
|
||
#### Operational Flow
|
||
- AI_Tester syncs testing/checklist.md with discussion posts
|
||
- Parse result blocks: [RESULT] PASS/FAIL: description
|
||
- Mark corresponding checklist items pass/fail
|
||
- On test failure: auto-create bug report with full sub-cycle
|
||
|
||
#### Automated Actions on commit
|
||
- Appends AI comment with vote
|
||
- Moderates discussion
|
||
- establishes testing objectives from testing/testplan.md and testing/checklist.md
|
||
- delegates testing tasks from testing/checklist.md
|
||
- Creates/maintains discussions/testing.discussion.sum.md
|
||
- Creates/maintains test/* files if any are produced during the discussion.
|
||
|
||
|
||
#### Bug Sub-Cycle Creation
|
||
|
||
```text
|
||
bugs/BUG_YYYYMMDD_<slug>/
|
||
├─ report.md # Steps, expected/actual, environment
|
||
├─ discussion.md # Bug discussion (OPEN)
|
||
└─ fix/
|
||
├─ plan.md # Fix implementation plan
|
||
└─ tasks.md # Fix tasks checklist
|
||
```
|
||
|
||
#### Bug Resolution Flow
|
||
- Bug follows mini Implementation→Testing cycle
|
||
- On bug closure, return to main testing discussion
|
||
- Bug results integrated into main test checklist
|
||
|
||
#### Promotion Actions
|
||
- Creates discussions/review.discussion.md (OPEN)
|
||
- Creates review/findings.md with verification summary
|
||
|
||
### Stage 6: Review Discussion
|
||
- File: discussions/review.discussion.md
|
||
|
||
#### Header
|
||
|
||
```yaml
|
||
---
|
||
type: discussion
|
||
stage: review
|
||
status: OPEN # OPEN | READY_FOR_RELEASE | CHANGES_REQUESTED
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: 1_human # HUMAN GATE
|
||
reject_min_eligible_votes: all
|
||
# ...
|
||
---
|
||
```
|
||
|
||
#### Operational Flow
|
||
- AI_Reviewer summarizes into review/findings.md
|
||
- Review covers: changes, risks, test evidence, deployment considerations
|
||
- Can spawn follow-up feature requests or bugs from findings
|
||
- When human READY present and no blockers: status → READY_FOR_RELEASE
|
||
|
||
#### Follow-up Artifact Creation
|
||
- New FR: ../../FR_YYYY-MM-DD_followup/request.md
|
||
- New Bug: bugs/BUG_YYYYMMDD_review/report.md
|
||
|
||
### Stage 7: Release
|
||
|
||
#### Entry Criteria
|
||
- Review discussion status is READY_FOR_RELEASE
|
||
|
||
#### Automated Actions
|
||
- Generate release notes from feature changes
|
||
- Semver bump based on change type
|
||
- Create git tag
|
||
- Update changelog
|
||
- Document rollback procedure
|
||
|
||
#### Post-Release
|
||
- Queue post-release validation tasks
|
||
- Update documentation as needed
|
||
- Archive feature folder if complete
|
||
|
||
## Voting, Quorum & Etiquette
|
||
### Voting System
|
||
Vote Values: READY | CHANGES | REJECT
|
||
|
||
Format Requirements:
|
||
|
||
Each comment must end with: VOTE: READY|CHANGES|REJECT
|
||
|
||
Last line of comment, exact format
|
||
|
||
Multiple votes by same participant: latest wins
|
||
|
||
Vote Parsing Examples:
|
||
|
||
```text
|
||
Rob: I agree with this approach. VOTE: READY
|
||
→ Rob: READY
|
||
|
||
AI_Claude: Here's my analysis... VOTE: CHANGES
|
||
→ AI_Claude: CHANGES (if allow_agent_votes=true)
|
||
|
||
User: I have concerns... VOTE: CHANGES
|
||
Later: User: Actually, addressed now. VOTE: READY
|
||
→ User: READY (latest vote wins)
|
||
```
|
||
### Eligibility & Quorum
|
||
Default Policy (machine-readable in process/policies.yml):
|
||
|
||
```yaml
|
||
version: 1
|
||
voting:
|
||
values: [READY, CHANGES, REJECT]
|
||
allow_agent_votes: true
|
||
quorum:
|
||
discussion: { ready: all, reject: all }
|
||
implementation: { ready: 1_human, reject: all }
|
||
release: { ready: 1_human, reject: all }
|
||
eligibility:
|
||
agents_allowed: true
|
||
require_human_for: [implementation, release]
|
||
etiquette:
|
||
name_prefix_agents: "AI_"
|
||
vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\b"
|
||
timeouts:
|
||
discussion_stale_days: 3
|
||
nudge_interval_hours: 24
|
||
```
|
||
Human Safety Gates:
|
||
- Implementation promotion: ≥1 human READY required
|
||
- Release promotion: ≥1 human READY required
|
||
- Agent votes count toward discussion but cannot satisfy human requirements
|
||
|
||
### Participation Etiquette
|
||
- Conciseness: Keep comments action-oriented and focused
|
||
- References: Link to files/sections when possible (design.md#architecture)
|
||
- Naming: Agents must prefix with AI_ (e.g., AI_Architect)
|
||
- Ownership: Suggest explicit owners for next steps (@AI_Architect: please draft...)
|
||
- Timeliness: Respond to direct questions within 24 hours
|
||
|
||
## Cascading Rules System
|
||
### Global Rules (Root .ai-rules.yml)
|
||
```yaml
|
||
version: 1
|
||
|
||
# Map file extensions to rule names
|
||
file_associations:
|
||
"*.js": "js-file"
|
||
"*.ts": "js-file"
|
||
"*.puml": "puml-file"
|
||
"*.md": "md-file"
|
||
|
||
rules:
|
||
js-file:
|
||
description: "Generate PlantUML + review for JS/TS files"
|
||
outputs:
|
||
diagram:
|
||
enabled: true
|
||
path: "Docs/diagrams/file_diagrams/{basename}.puml"
|
||
output_type: "puml-file"
|
||
instruction: |
|
||
Update the PlantUML diagram to reflect staged code changes.
|
||
Focus on: key functions, control flow, data transformations, dependencies.
|
||
Keep architectural elements clear and focused.
|
||
review:
|
||
enabled: true
|
||
path: "Docs/discussions/reviews/{date}_{basename}.md"
|
||
output_type: "md-file"
|
||
instruction: |
|
||
Create technical review of code changes.
|
||
Include: summary of changes, potential risks, edge cases,
|
||
testing considerations, performance implications.
|
||
Use concise bullet points.
|
||
|
||
puml-file:
|
||
description: "Rules for PlantUML diagram files"
|
||
instruction: |
|
||
Maintain readable, consistent diagrams.
|
||
Use descriptive element names, consistent arrow styles.
|
||
Include brief legend for complex diagrams.
|
||
|
||
md-file:
|
||
description: "Rules for Markdown documentation"
|
||
instruction: |
|
||
Use proper Markdown syntax with concise paragraphs.
|
||
Use code fences for examples, lists for multiple points.
|
||
Maintain technical, clear tone.
|
||
|
||
settings:
|
||
max_tokens: 4000
|
||
temperature: 0.1
|
||
model: "claude-sonnet-4-5-20250929"
|
||
```
|
||
### Feature-Scoped Rules (Docs/features/.ai-rules.yml)
|
||
```yaml
|
||
version: 1
|
||
|
||
file_associations:
|
||
"request.md": "feature_request"
|
||
"feature.discussion.md": "feature_discussion"
|
||
"design.discussion.md": "design_discussion"
|
||
"implementation.discussion.md":"impl_discussion"
|
||
"testing.discussion.md": "test_discussion"
|
||
"review.discussion.md": "review_discussion"
|
||
|
||
rules:
|
||
feature_request:
|
||
outputs:
|
||
feature_discussion:
|
||
path: "{dir}/discussions/feature.discussion.md"
|
||
output_type: "feature_discussion_writer"
|
||
instruction: |
|
||
If discussion file missing: create with standard header (stage: feature, status: OPEN),
|
||
add Summary and Participation sections, then append initial AI comment with vote.
|
||
If exists: no operation.
|
||
|
||
feature_discussion:
|
||
outputs:
|
||
self_append:
|
||
path: "{dir}/discussions/feature.discussion.md"
|
||
output_type: "feature_discussion_writer"
|
||
instruction: |
|
||
Append concise comment signed with AI name, ending with single vote line.
|
||
Evaluate votes against header thresholds. If READY threshold met:
|
||
- Flip status to READY_FOR_DESIGN
|
||
- Clearly state promotion decision in comment
|
||
Append-only with minimal diff.
|
||
|
||
design_discussion:
|
||
path: "{dir}/discussions/design.discussion.md"
|
||
output_type: "design_discussion_writer"
|
||
instruction: |
|
||
Create ONLY if feature discussion status is READY_FOR_DESIGN.
|
||
Seed with standard header (stage: design, status: OPEN).
|
||
|
||
design_doc:
|
||
path: "{dir}/design/design.md"
|
||
output_type: "design_doc_writer"
|
||
instruction: |
|
||
Create ONLY if feature discussion status is READY_FOR_DESIGN.
|
||
Seed design document from request content and feature discussion.
|
||
Include: Context, Options, Decision, Risks, Acceptance Criteria.
|
||
|
||
design_discussion:
|
||
outputs:
|
||
design_update:
|
||
path: "{dir}/design/design.md"
|
||
output_type: "design_doc_writer"
|
||
instruction: |
|
||
Update design document to reflect latest design discussion.
|
||
Ensure acceptance criteria are measurable and complete.
|
||
Maintain all standard sections. Minimal diffs.
|
||
|
||
impl_discussion:
|
||
path: "{dir}/discussions/implementation.discussion.md"
|
||
output_type: "impl_discussion_writer"
|
||
instruction: |
|
||
Create ONLY if design discussion status is READY_FOR_IMPLEMENTATION.
|
||
|
||
impl_plan:
|
||
path: "{dir}/implementation/plan.md"
|
||
output_type: "impl_plan_writer"
|
||
instruction: |
|
||
Create ONLY if design status is READY_FOR_IMPLEMENTATION.
|
||
Draft implementation milestones and scope.
|
||
|
||
impl_tasks:
|
||
path: "{dir}/implementation/tasks.md"
|
||
output_type: "impl_tasks_writer"
|
||
instruction: |
|
||
Create ONLY if design status is READY_FOR_IMPLEMENTATION.
|
||
Generate task checklist aligned to acceptance criteria.
|
||
|
||
impl_discussion:
|
||
outputs:
|
||
tasks_sync:
|
||
path: "{dir}/implementation/tasks.md"
|
||
output_type: "impl_tasks_maintainer"
|
||
instruction: |
|
||
Parse checkboxes and PR mentions from implementation discussion.
|
||
Synchronize tasks.md accordingly.
|
||
When all required tasks complete, mark implementation discussion READY_FOR_TESTING.
|
||
|
||
test_discussion:
|
||
path: "{dir}/discussions/testing.discussion.md"
|
||
output_type: "test_discussion_writer"
|
||
instruction: |
|
||
Create ONLY if implementation status is READY_FOR_TESTING.
|
||
|
||
test_plan:
|
||
path: "{dir}/testing/testplan.md"
|
||
output_type: "testplan_writer"
|
||
instruction: |
|
||
Create ONLY if implementation status is READY_FOR_TESTING.
|
||
Derive test strategy from acceptance criteria.
|
||
|
||
test_checklist:
|
||
path: "{dir}/testing/checklist.md"
|
||
output_type: "testchecklist_writer"
|
||
instruction: |
|
||
Create ONLY if implementation status is READY_FOR_TESTING.
|
||
Generate test checklist covering acceptance criteria and edge cases.
|
||
|
||
test_discussion:
|
||
outputs:
|
||
checklist_update:
|
||
path: "{dir}/testing/checklist.md"
|
||
output_type: "testchecklist_maintainer"
|
||
instruction: |
|
||
Parse result blocks from test discussion ([RESULT] PASS/FAIL: description).
|
||
Update checklist accordingly with evidence links.
|
||
On test failure, create appropriate bug report.
|
||
|
||
bug_report:
|
||
path: "{dir}/bugs/BUG_{date}_auto/report.md"
|
||
output_type: "bug_report_writer"
|
||
instruction: |
|
||
Create bug report ONLY when test failure with clear reproduction steps.
|
||
Initialize bug discussion and fix plan in same folder.
|
||
|
||
review_discussion:
|
||
path: "{dir}/discussions/review.discussion.md"
|
||
output_type: "review_discussion_writer"
|
||
instruction: |
|
||
Create ONLY if all test checklist items pass.
|
||
Set testing discussion status to READY_FOR_REVIEW.
|
||
|
||
review_findings:
|
||
path: "{dir}/review/findings.md"
|
||
output_type: "review_findings_writer"
|
||
instruction: |
|
||
Create summary of verified functionality, risks, and noteworthy changes.
|
||
|
||
review_discussion:
|
||
outputs:
|
||
followup_feature:
|
||
path: "../../FR_{date}_followup/request.md"
|
||
output_type: "feature_request_writer"
|
||
instruction: |
|
||
Create follow-up feature request ONLY when review identifies enhancement opportunity.
|
||
|
||
followup_bug:
|
||
path: "{dir}/bugs/BUG_{date}_review/report.md"
|
||
output_type: "bug_report_writer"
|
||
instruction: |
|
||
Create bug report ONLY when review identifies defect.
|
||
Seed discussion and fix plan.
|
||
```
|
||
5.3 Rule Resolution Precedence
|
||
- Nearest Directory: Check source file directory and parents upward
|
||
- Feature Scope: Docs/features/.ai-rules.yml for feature artifacts
|
||
- Global Fallback: Root .ai-rules.yml for code files
|
||
- Conflict Resolution: Nearest rule wins, with logging of override decisions
|
||
|
||
## Orchestration Architecture
|
||
### Bash Pre-commit Hook (Current Implementation)
|
||
Core Responsibilities:
|
||
- Collect staged files (Added/Modified only)
|
||
- Resolve rules via cascading lookup
|
||
- Build context prompts from staged content
|
||
- Call AI model via CLI for patch generation
|
||
- Apply patches with robust error handling
|
||
|
||
Enhanced Template Support:
|
||
|
||
```bash
|
||
# Add to resolve_template() function
|
||
local dirpath
|
||
dirpath=$(dirname "$rel_path")
|
||
# ...
|
||
-e "s|{dir}|$dirpath|g"
|
||
```
|
||
Patch Application Strategy:
|
||
- Preserve Index Lines: Enable 3-way merge capability
|
||
- Try 3-way First: git apply --index --3way --recount --whitespace=nowarn
|
||
- Fallback to Strict: git apply --index if 3-way fails
|
||
- Debug Artifacts: Save raw/clean/sanitized/final patches to .git/ai-rules-debug/
|
||
|
||
Discussion File Optimization:
|
||
- Prefer append-only edits with optional header flips
|
||
- For large files: generate full new content and compute diff locally
|
||
- Minimize hunk drift through careful patch construction
|
||
|
||
### Python Orchestrator (automation/workflow.py)
|
||
Phase 1 (Non-blocking Status):
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
import json, os, sys, subprocess, re
|
||
from pathlib import Path
|
||
|
||
def main():
|
||
changed_files = read_changed_files()
|
||
status_report = analyze_discussion_status(changed_files)
|
||
if status_report:
|
||
print("AI-Workflow Status Report")
|
||
print(json.dumps(status_report, indent=2))
|
||
sys.exit(0) # Always non-blocking in v1
|
||
```
|
||
Core Functions:
|
||
- Vote Parsing: Parse discussion files, track latest votes per participant
|
||
- Threshold Evaluation: Compute eligibility and quorum status
|
||
- Status Reporting: JSON output of current discussion state
|
||
- Decision Hints: Suggest promotion based on policy rules
|
||
|
||
Future Enhancements:
|
||
- Policy enforcement based on process/policies.yml
|
||
- Gitea API integration for issue/PR management
|
||
- Advanced agent coordination and task routing
|
||
|
||
### Gitea Integration (Future)
|
||
Label System:
|
||
- stage/*: stage/discussion, stage/design, stage/implementation, etc.
|
||
- blocked/*: blocked/needs-votes, blocked/needs-human
|
||
- needs/*: needs/design, needs/review, needs/tests
|
||
|
||
Automated Actions:
|
||
- Open/label PRs for implementation transitions
|
||
- Post status summaries to PR threads
|
||
- Create tracking issues for feature implementation
|
||
- Report status checks to PRs
|
||
|
||
## Moderator Protocol
|
||
### AI_Moderator Responsibilities
|
||
Conversation Tracking:
|
||
- Monitor unanswered questions (>24 hours)
|
||
- Track missing votes from active participants
|
||
- Identify stale threads needing attention
|
||
- Flag direct mentions that need responses
|
||
|
||
Progress Reporting:
|
||
- Compute current vote tallies and thresholds
|
||
- List participants who haven't voted recently
|
||
- Summarize promotion status and remaining requirements
|
||
- Highlight blocking issues or concerns
|
||
|
||
Task Allocation:
|
||
- Suggest explicit owners for pending tasks
|
||
- Example: "AI_Architect: please draft the acceptance criteria section"
|
||
- Example: "Rob: could you clarify the deployment timeline?"
|
||
|
||
### Moderator Implementation
|
||
Rule Definition (in Docs/features/.ai-rules.yml):
|
||
|
||
```yaml
|
||
discussion_moderator_nudge:
|
||
outputs:
|
||
self_append:
|
||
path: "{dir}/discussions/{basename}.discussion.md"
|
||
output_type: "feature_discussion_writer"
|
||
instruction: |
|
||
Act as AI_Moderator. Analyze the entire discussion and:
|
||
|
||
UNANSWERED QUESTIONS:
|
||
- List any direct questions unanswered for >24 hours (mention @names)
|
||
- Flag questions that need clarification or follow-up
|
||
|
||
VOTE STATUS:
|
||
- Current tally: READY: X, CHANGES: Y, REJECT: Z
|
||
- Missing votes from: [list of participants without recent votes]
|
||
- Promotion status: [based on header thresholds]
|
||
|
||
ACTION ITEMS:
|
||
- Suggest specific next owners for pending tasks
|
||
- Propose concrete next steps with deadlines
|
||
|
||
Keep comment under 10 lines. End with "VOTE: CHANGES".
|
||
Append-only; minimal diff; update nothing else.
|
||
```
|
||
Nudge Frequency: Controlled by nudge_interval_hours in policies
|
||
|
||
## Error Handling & Resilience
|
||
### Common Failure Modes
|
||
Patch Application Issues:
|
||
- Symptom: Hunk drift on large files, merge conflicts
|
||
- Mitigation: 3-way apply with index preservation, append-only strategies
|
||
- Fallback: Local diff computation from full new content
|
||
|
||
Model Output Problems:
|
||
- Symptom: Malformed diff, missing markers, invalid patch format
|
||
- Mitigation: Extract between markers, validate with git apply --check
|
||
- Fallback: Clear diagnostics with patch validation output
|
||
|
||
Tooling Dependencies:
|
||
- Symptom: Missing yq, claude, or other required tools
|
||
- Mitigation: Pre-flight checks with clear error messages
|
||
- Fallback: Graceful degradation with feature-specific disabling
|
||
|
||
Rule Conflicts:
|
||
- Symptom: Multiple rules matching same file with conflicting instructions
|
||
- Mitigation: Nearest-directory precedence with conflict logging
|
||
- Fallback: Global rule application with warning
|
||
|
||
### Recovery Procedures
|
||
Manual Override:
|
||
|
||
```bash
|
||
# Bypass hook for emergency edits
|
||
git commit --no-verify -m "Emergency fix: manually overriding discussion status"
|
||
|
||
# Manually update discussion header
|
||
# type: discussion -> status: READY_FOR_IMPLEMENTATION
|
||
```
|
||
Debug Artifacts:
|
||
- All patch variants saved to .git/ai-rules-debug/
|
||
- Timestamped files: raw, clean, sanitized, final patches
|
||
- Commit-specific directories for correlation
|
||
|
||
Rollback Strategy:
|
||
- All generated artifacts are staged separately
|
||
- Easy partial staging: git reset HEAD <file> for specific artifacts
|
||
- Full reset: git reset HEAD~1 to undo entire commit with generations
|
||
|
||
### Audit Trail
|
||
Execution Logging:
|
||
- All rule invocations logged with source→output mapping
|
||
- Patch application attempts and outcomes recorded
|
||
- Vote calculations and promotion decisions documented
|
||
|
||
Debug Bundle:
|
||
|
||
```bash
|
||
.git/ai-rules-debug/
|
||
├─ 20251021-143022-12345-feature.discussion.md/
|
||
│ ├─ raw.out # Raw model output
|
||
│ ├─ clean.diff # Extracted patch
|
||
│ ├─ sanitized.diff # After sanitization
|
||
│ └─ final.diff # Final applied patch
|
||
└─ execution.log # Chronological action log
|
||
```
|
||
## Security & Secrets Management
|
||
### Secret Protection
|
||
Never Commit:
|
||
- API keys, authentication tokens
|
||
- Personal identifying information
|
||
- Internal system credentials
|
||
- Private configuration data
|
||
|
||
Environment Variables:
|
||
|
||
```bash
|
||
# Current approach
|
||
export CLAUDE_API_KEY="your_key"
|
||
# Future .env approach (git-ignored)
|
||
# .env file loaded via python-dotenv in Python components
|
||
```
|
||
Configuration Management:
|
||
- Keep sensitive endpoints in automation/config.yml
|
||
- Use environment variable substitution in configuration
|
||
- Validate no secrets in discussions, rules, or generated artifacts
|
||
|
||
### Access Control
|
||
Repository Security:
|
||
- Assume all repository contents are potentially exposed
|
||
- No sensitive business logic in prompt instructions
|
||
- Regular security reviews of rule definitions
|
||
|
||
Agent Permissions:
|
||
- Limit file system access to repository scope
|
||
- Validate output paths stay within repository
|
||
- Sanitize all file operations for path traversal
|
||
|
||
## Performance & Scale Considerations
|
||
### Optimization Strategies
|
||
Prompt Efficiency:
|
||
- Pass staged diffs instead of full file contents when possible
|
||
- Use concise, structured instructions with clear formatting
|
||
- Limit context to relevant sections for large files
|
||
|
||
Discussion Management:
|
||
- Append-only edits with periodic summarization
|
||
- Compact status reporting in moderator comments
|
||
- Archive completed discussions if they become too large
|
||
|
||
Batch Operations:
|
||
- Process multiple related files in single model calls when beneficial
|
||
- Cache rule resolutions for multiple files in same directory
|
||
- Parallelize independent output generations
|
||
|
||
### Scaling Limits
|
||
File Size Considerations:
|
||
- Small (<100KB): Full content in prompts
|
||
- Medium (100KB-1MB): Diff-only with strategic context
|
||
- Large (>1MB): Chunked processing or summary-only approaches
|
||
|
||
Repository Size:
|
||
- Current approach suitable for medium-sized repositories
|
||
- For very large codebases: scope rules to specific directories
|
||
- Consider rule disabling for generated/binary assets
|
||
|
||
Rate Limiting:
|
||
- Model API calls: implement throttling and retry logic
|
||
- Gitea API: respect rate limits with exponential backoff
|
||
- File operations: batch where possible to reduce I/O
|
||
|
||
## Testing Strategy
|
||
### Testing Tiers
|
||
Unit Tests (Python):
|
||
- Vote parsing and eligibility calculation
|
||
- Policy evaluation and quorum determination
|
||
- Rules resolution and conflict handling
|
||
- Template variable substitution
|
||
- Integration Tests (Bash + Python):
|
||
- End-to-end rule → prompt → patch → apply cycle
|
||
- Discussion status transitions and promotion logic
|
||
- Error handling and recovery procedures
|
||
- Multi-file rule processing
|
||
|
||
Artifact Validation:
|
||
- PlantUML syntax checking: plantuml -checkonly
|
||
- Markdown structure validation
|
||
- Template completeness checks
|
||
- YAML syntax validation
|
||
|
||
### Test Architecture
|
||
```text
|
||
tests/
|
||
├─ unit/
|
||
│ ├─ test_votes.py
|
||
│ ├─ test_policies.py
|
||
│ ├─ test_rules_resolution.py
|
||
│ └─ test_template_variables.py
|
||
├─ integration/
|
||
│ ├─ run.sh # Main test runner
|
||
│ ├─ lib.sh # Test utilities
|
||
│ ├─ fixtures/
|
||
│ │ └─ repo_skeleton/ # Minimal test repository
|
||
│ │ ├─ .ai-rules.yml
|
||
│ │ ├─ Docs/features/.ai-rules.yml
|
||
│ │ └─ Docs/features/FR_test/
|
||
│ │ ├─ request.md
|
||
│ │ └─ discussions/
|
||
│ └─ test_cases/
|
||
│ ├─ test_feature_promotion.sh
|
||
│ ├─ test_design_generation.sh
|
||
│ └─ test_bug_creation.sh
|
||
├─ bin/
|
||
│ └─ claude # Fake deterministic model
|
||
└─ README.md
|
||
```
|
||
### Fake Model Implementation
|
||
Purpose: Deterministic testing without external API dependencies
|
||
|
||
Implementation (tests/bin/claude):
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# Fake Claude CLI for testing
|
||
# Reads prompt from stdin, outputs predetermined patch based on content
|
||
|
||
if grep -q "OUTPUT FILE:.*discussion.md" ; then
|
||
# Output discussion update patch
|
||
cat << 'EOF'
|
||
<<<AI_DIFF_START>>>
|
||
diff --git a/Docs/features/FR_test/discussions/feature.discussion.md b/Docs/features/FR_test/discussions/feature.discussion.md
|
||
index 1234567..890abcd 100644
|
||
--- a/Docs/features/FR_test/discussions/feature.discussion.md
|
||
+++ b/Docs/features/FR_test/discussions/feature.discussion.md
|
||
@@ -15,3 +15,6 @@ voting:
|
||
|
||
## Summary
|
||
Test feature for validation
|
||
+
|
||
+## Participation
|
||
+AI_Test: This is a test comment. VOTE: READY
|
||
<<<AI_DIFF_END>>>
|
||
EOF
|
||
else
|
||
# Default patch for other file types
|
||
echo "No specific patch for this file type"
|
||
fi
|
||
```
|
||
### Integration Test Runner
|
||
#### Key Test Scenarios
|
||
- Feature Promotion: request.md → feature.discussion.md → READY_FOR_DESIGN
|
||
- Design Generation: design.discussion.md → design.md updates
|
||
- Bug Creation: test failure → auto bug report generation
|
||
- Error Recovery: Malformed patch → graceful failure with diagnostics
|
||
- Rule Conflicts: Multiple rule matches → nearest-directory resolution
|
||
|
||
#### Test Execution
|
||
```bash
|
||
# Run full test suite
|
||
cd tests/integration
|
||
./run.sh
|
||
|
||
# Run specific test case
|
||
./test_cases/test_feature_promotion.sh
|
||
```
|
||
### Continuous Validation
|
||
Pre-commit Checks:
|
||
- PlantUML syntax validation for generated diagrams
|
||
- Markdown link validation
|
||
- YAML syntax checking for rule files
|
||
- Template variable validation
|
||
|
||
Performance Benchmarks:
|
||
- Rule resolution time for typical commit
|
||
- Patch generation and application duration
|
||
- Memory usage during large file processing
|
||
|
||
## Source Intelligence Automation (Auto-Review + Auto-Diagram)
|
||
|
||
### Purpose
|
||
To keep technical documentation and diagrams in sync with evolving source code. On every staged change to src/**/*.js|ts|py, the automation layer:
|
||
- Analyzes the diff and AST to produce a concise review summary
|
||
- Extracts structure and updates a PlantUML diagram in Docs/diagrams/file_diagrams/
|
||
|
||
### A) Folder Layout
|
||
```text
|
||
src/
|
||
├─ automation/
|
||
│ ├─ __init__.py
|
||
│ ├─ analyzer.py # parses diffs, extracts structure & metrics
|
||
│ ├─ reviewer.py # writes review summaries (md)
|
||
│ ├─ diagrammer.py # emits PUML diagrams
|
||
│ └─ utils/
|
||
│ ├─ git_tools.py # staged diff, blob lookup
|
||
│ ├─ code_parser.py # AST helpers (JS/TS/Python)
|
||
│ └─ plantuml_gen.py # renders PlantUML text
|
||
```
|
||
|
||
### B) Operational Flow (Triggered by Hook)
|
||
```text
|
||
┌────────────────────────────────────────────────────────┐
|
||
│ pre-commit hook (bash) │
|
||
│ └──> detect src/**/*.js|ts|py changes │
|
||
│ ├─> call automation/analyzer.py --file <path> │
|
||
│ │ ├─ parse diff + AST │
|
||
│ │ ├─ collect functions, classes, calls │
|
||
│ │ └─ emit JSON summary │
|
||
│ ├─> reviewer.py → Docs/discussions/reviews/ │
|
||
│ └─> diagrammer.py → Docs/diagrams/file_diagrams/│
|
||
└────────────────────────────────────────────────────────┘
|
||
```
|
||
Each stage emits a unified diff so the same patch-application rules (3-way apply, append-only) still apply.
|
||
|
||
### C) Sample Rule (Root .ai-rules.yml)
|
||
```yaml
|
||
js-file:
|
||
description: "Generate PlantUML + review for JS/TS files"
|
||
outputs:
|
||
diagram:
|
||
path: "Docs/diagrams/file_diagrams/{basename}.puml"
|
||
output_type: "puml-file"
|
||
instruction: |
|
||
Parse code structure and update a PlantUML diagram:
|
||
- Modules, classes, functions
|
||
- Control-flow edges between major functions
|
||
review:
|
||
path: "Docs/discussions/reviews/{date}_{basename}.md"
|
||
output_type: "md-file"
|
||
instruction: |
|
||
Summarize this commit’s code changes:
|
||
- What changed and why
|
||
- Possible risks / performance / security notes
|
||
- Suggested tests or TODOs
|
||
```
|
||
Similar rules exist for py-file, ts-file, etc.
|
||
|
||
### D) Core Algorithms (pseudocode)
|
||
```python
|
||
# 1 analyzer.py
|
||
|
||
def analyze_source(path):
|
||
diff = git_diff(path)
|
||
tree = parse_ast(path)
|
||
funcs, classes = extract_symbols(tree)
|
||
flows = extract_calls(tree)
|
||
metrics = compute_metrics(tree)
|
||
return {
|
||
"file": path,
|
||
"functions": funcs,
|
||
"classes": classes,
|
||
"flows": flows,
|
||
"metrics": metrics,
|
||
"diff_summary": summarize_diff(diff),
|
||
}
|
||
|
||
# 2 diagrammer.py
|
||
|
||
def generate_puml(analysis):
|
||
nodes = [*analysis["classes"], *analysis["functions"]]
|
||
edges = analysis["flows"]
|
||
puml = "@startuml\n"
|
||
for n in nodes:
|
||
puml += f"class {n}\n"
|
||
for a, b in edges:
|
||
puml += f"{a} --> {b}\n"
|
||
puml += "@enduml\n"
|
||
return puml
|
||
|
||
# 3 reviewer.py
|
||
|
||
def generate_review(analysis):
|
||
return f"""# Auto Review — {analysis['file']}
|
||
|
||
## Summary
|
||
{analysis['diff_summary']}
|
||
|
||
## Key Functions
|
||
{', '.join(analysis['functions'][:10])}
|
||
|
||
## Potential Risks
|
||
- TODO: evaluate complexity or security implications
|
||
|
||
## Suggested Tests
|
||
- Unit tests for new/modified functions
|
||
"""
|
||
```
|
||
|
||
### E) Outputs
|
||
- .puml → Docs/diagrams/file_diagrams/{basename}.puml (keeps architecture maps current)
|
||
- .md → Docs/discussions/reviews/{date}_{basename}.md (rolling code review history)
|
||
Each output follows 3-way apply / append-only rules; every commit leaves a diff trail in .git/ai-rules-debug/.
|
||
|
||
### F) Integration with Orchestrator
|
||
```python
|
||
# automation/workflow.py (aggregation example)
|
||
if src_changed():
|
||
from automation import analyzer, reviewer, diagrammer
|
||
for f in changed_src_files:
|
||
data = analyzer.analyze_source(f)
|
||
diagrammer.update_puml(data)
|
||
reviewer.update_review(data)
|
||
```
|
||
Future versions can post summaries to the feature’s implementation discussion and link diagrams into design/design.md.
|
||
|
||
### G) Testing the Source Automation Layer
|
||
- Unit: tests/unit/test_code_parser.py, tests/unit/test_puml_gen.py
|
||
- Integration: tests/integration/test_cases/test_auto_review.sh, test_auto_diagram.sh
|
||
- Fixtures: tests/integration/fixtures/repo_skeleton/src/ with fake commits to verify generation
|
||
|
||
### H) Security & Performance Notes
|
||
- Sandbox analysis only — no execution of user code
|
||
- AST parsing limited to static structure
|
||
- Large files (>5k lines): partial summarization
|
||
- Output capped to ≤ 200 KB per artifact
|
||
|
||
### I) Deliverables Added to Milestones
|
||
- M0 → create src/automation/ skeleton
|
||
- M1 → functional auto-review + auto-diagram for JS/TS files
|
||
- M2 → extend to Python + PlantUML cross-linking in design docs
|
||
|
||
## Discussion Summaries (Companion Artifacts per Stage)
|
||
|
||
### What it is
|
||
For every {stage}.discussion.md, maintain a sibling {stage}.sum.md. It is append-minimal with bounded section rewrites only (between stable markers). Contents: decisions, vote tallies, open questions, awaiting replies, action items, compact timeline.
|
||
|
||
### Where it lives
|
||
```text
|
||
Docs/features/FR_.../
|
||
└─ discussions/
|
||
├─ feature.discussion.md
|
||
├─ feature.sum.md
|
||
├─ design.discussion.md
|
||
├─ design.sum.md
|
||
├─ implementation.discussion.md
|
||
├─ implementation.sum.md
|
||
├─ testing.discussion.md
|
||
├─ testing.sum.md
|
||
├─ review.discussion.md
|
||
└─ review.sum.md
|
||
```
|
||
|
||
### Header (machine-readable)
|
||
```yaml
|
||
---
|
||
type: discussion-summary
|
||
stage: feature # feature|design|implementation|testing|review
|
||
status: ACTIVE # ACTIVE|SNAPSHOT|ARCHIVED
|
||
source_discussion: feature.discussion.md
|
||
feature_id: FR_YYYY-MM-DD_<slug>
|
||
updated: YYYY-MM-DDTHH:MM:SSZ
|
||
policy:
|
||
allow_agent_votes: true
|
||
require_human_for: [implementation, review]
|
||
---
|
||
```
|
||
|
||
### Stable section markers (for tiny diffs)
|
||
```markdown
|
||
# Summary — <Stage Title>
|
||
|
||
<!-- SUMMARY:DECISIONS START -->
|
||
## Decisions (ADR-style)
|
||
- (none yet)
|
||
<!-- SUMMARY:DECISIONS END -->
|
||
|
||
<!-- SUMMARY:OPEN_QUESTIONS START -->
|
||
## Open Questions
|
||
- (none yet)
|
||
<!-- SUMMARY:OPEN_QUESTIONS END -->
|
||
|
||
<!-- SUMMARY:AWAITING START -->
|
||
## Awaiting Replies
|
||
- (none yet)
|
||
<!-- SUMMARY:AWAITING END -->
|
||
|
||
<!-- SUMMARY:ACTION_ITEMS START -->
|
||
## Action Items
|
||
- (none yet)
|
||
<!-- SUMMARY:ACTION_ITEMS END -->
|
||
|
||
<!-- SUMMARY:VOTES START -->
|
||
## Votes (latest per participant)
|
||
READY: 0 • CHANGES: 0 • REJECT: 0
|
||
- (no votes yet)
|
||
<!-- SUMMARY:VOTES END -->
|
||
|
||
<!-- SUMMARY:TIMELINE START -->
|
||
## Timeline (most recent first)
|
||
- <YYYY-MM-DD HH:MM> <name>: <one-liner>
|
||
<!-- SUMMARY:TIMELINE END -->
|
||
|
||
<!-- SUMMARY:LINKS START -->
|
||
## Links
|
||
- Related PRs: –
|
||
- Commits: –
|
||
- Design/Plan: ../design/design.md
|
||
<!-- SUMMARY:LINKS END -->
|
||
```
|
||
|
||
### How it updates
|
||
Trigger: whenever {stage}.discussion.md is staged, the hook also updates/creates {stage}.sum.md.
|
||
|
||
Deterministic logic:
|
||
- Votes: parse latest vote per participant (eligibility per policy)
|
||
- Decisions: if header status flips (e.g., READY_FOR_IMPLEMENTATION), append an ADR entry
|
||
- Open Questions: lines ending with ? or flagged Q: with @owner if present
|
||
- Awaiting Replies: mentions with no response from that participant within response_timeout_hours
|
||
- Action Items: unchecked tasks (- [ ]) with @owner remain tracked until checked
|
||
- Timeline: last N (default 15) comment one-liners with timestamp and name
|
||
- Links: auto-add PRs (#123), SHAs, and cross-file links
|
||
|
||
Rotation / snapshots (optional): when discussion grows large or on schedule, write discussions/summaries/<YYYY-MM-DD>.md (status: SNAPSHOT) and keep {stage}.sum.md trimmed while retaining Decisions/Open Q/Actions/Votes.
|
||
|
||
### Rules (additions in Docs/features/.ai-rules.yml)
|
||
```yaml
|
||
file_associations:
|
||
"feature.discussion.md": "feature_discussion"
|
||
"design.discussion.md": "design_discussion"
|
||
"implementation.discussion.md": "impl_discussion"
|
||
"testing.discussion.md": "test_discussion"
|
||
"review.discussion.md": "review_discussion"
|
||
|
||
rules:
|
||
feature_discussion:
|
||
outputs:
|
||
summary_companion:
|
||
path: "{dir}/discussions/feature.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Create or update the summary file. Replace ONLY content between
|
||
these markers: DECISIONS, OPEN_QUESTIONS, AWAITING, ACTION_ITEMS,
|
||
VOTES, TIMELINE, LINKS. Do not touch other lines.
|
||
Inputs: the entire feature.discussion.md.
|
||
design_discussion:
|
||
outputs:
|
||
summary_companion:
|
||
path: "{dir}/discussions/design.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Same summary policy as feature.sum.md; also add link to ../design/design.md.
|
||
impl_discussion:
|
||
outputs:
|
||
summary_companion:
|
||
path: "{dir}/discussions/implementation.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Same summary policy; include unchecked items from ../implementation/tasks.md.
|
||
test_discussion:
|
||
outputs:
|
||
summary_companion:
|
||
path: "{dir}/discussions/testing.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Same summary policy; include failing test artifacts and ensure FAILs surface in Open Questions or Awaiting.
|
||
review_discussion:
|
||
outputs:
|
||
summary_companion:
|
||
path: "{dir}/discussions/review.sum.md"
|
||
output_type: "discussion_summary_writer"
|
||
instruction: |
|
||
Same summary policy; Decisions should note READY_FOR_RELEASE with date and follow-ups.
|
||
```
|
||
|
||
### Orchestrator support (nice-to-have)
|
||
Provide workflow.py --summarize <discussion-path> to output regenerated sections for tests/CI. Track awaiting replies via timestamps per author; if absent, mark as awaiting.
|
||
|
||
### Testing additions
|
||
- Unit: parsing of votes, questions, mentions, action items
|
||
- Integration: commit a discussion with constructs → verify summary sections updated and only marker-bounded hunks changed
|
||
- Failure: malformed discussion / huge file → generator still writes sections; timeline truncates; no crash
|
||
|
||
### Why this helps
|
||
Newcomers can open {stage}.sum.md and immediately see the state. Humans keep talking in the discussion; the system curates the signal in the summary. Promotions are transparent via Decisions. Open loops are visible and assigned.
|
||
|
||
## Implementation Plan
|
||
### Milestone M0: Process Foundation
|
||
Deliverables:
|
||
- process/design.md (this document)
|
||
- process/policies.md + process/policies.yml
|
||
- process/templates/ (all four core templates)
|
||
- automation/agents.yml (role mappings)
|
||
- src/automation/ skeleton (analyzer.py, reviewer.py, diagrammer.py, utils/*)
|
||
|
||
Success Criteria:
|
||
- All process documentation in place
|
||
- Policy definitions machine-readable
|
||
- Templates provide clear starting points
|
||
|
||
### Milestone M1: Orchestrator MVP + Hook Enhancements
|
||
Deliverables:
|
||
- automation/workflow.py (non-blocking status reporter)
|
||
- Bash hook: {dir} template variable support
|
||
- Bash hook: Index preservation for 3-way apply
|
||
- Bash hook: Append-only optimization for discussions
|
||
- Auto-review + auto-diagram operational for JS/TS via root rules (js-file)
|
||
|
||
Success Criteria:
|
||
- Python orchestrator reports discussion status
|
||
- Template variables work for feature folder paths
|
||
- 3-way apply handles merge conflicts gracefully
|
||
|
||
### Milestone M2: Stage Automation & Moderator
|
||
Deliverables:
|
||
- Enhanced Docs/features/.ai-rules.yml with stage rules
|
||
- AI_Moderator implementation via discussion rules
|
||
- Python orchestrator: policy-based decision hints
|
||
- Test suite for feature promotion flow
|
||
- Discussion summaries: rules (discussion_summary_writer) + tests
|
||
|
||
Success Criteria:
|
||
- Feature requests auto-create discussions
|
||
- Discussions promote through stages based on votes
|
||
- Moderator provides useful conversation guidance
|
||
|
||
### Milestone M3: Gitea Integration
|
||
Deliverables:
|
||
- automation/adapters/gitea_adapter.py
|
||
- Automated PR creation and labeling
|
||
- Status reporting to PR threads
|
||
- Issue tracking integration
|
||
|
||
Success Criteria:
|
||
- Implementation stage auto-creates PRs
|
||
- Review status visible in PR discussions
|
||
- Labels reflect current stage and blockers
|
||
|
||
### Milestone M4: Bash to Python Migration
|
||
Deliverables:
|
||
- Core rule resolution logic in Python
|
||
- Patch generation and application in Python
|
||
- Bash hook as thin wrapper calling Python
|
||
- Enhanced error handling and diagnostics
|
||
|
||
Success Criteria:
|
||
- Maintains current functionality with better maintainability
|
||
- Improved error messages and recovery options
|
||
- Consistent behavior across all operations
|
||
|
||
## Risks & Mitigations
|
||
### Technical Risks
|
||
Over-Automation Bypassing Humans:
|
||
|
||
Risk: Critical decisions made without human oversight
|
||
- Mitigation: Human READY gates for Implementation and Release stages
|
||
- Control: Manual override capability for all automated promotions
|
||
- Patch Instability on Large Files:
|
||
|
||
Risk: Hunk drift and merge conflicts in long discussions
|
||
- Mitigation: 3-way apply with index preservation, append-only strategies
|
||
- Fallback: Local diff computation from full content regeneration
|
||
|
||
Tooling Dependency Management:
|
||
|
||
Risk: Version conflicts or missing dependencies break system
|
||
- Mitigation: Pre-flight validation with clear error messages
|
||
- Recovery: Graceful degradation with feature flags
|
||
|
||
Context Limit Exceeded:
|
||
- Risk: AI models cannot process very large discussions
|
||
- Mitigation: Structured summarization, chunked processing
|
||
- Alternative: Focus on recent changes with reference to history
|
||
|
||
13.2 Process Risks
|
||
Vote Manipulation or Gaming:
|
||
- Risk: Participants exploit voting system for unwanted outcomes
|
||
- Mitigation: Clear etiquette policies, human override capability
|
||
- Oversight: Moderator monitoring for voting patterns
|
||
|
||
Discussion Fragmentation:
|
||
|
||
Risk: Conversations become scattered across multiple files
|
||
- Mitigation: Clear stage boundaries, cross-references between discussions
|
||
- Tooling: Search and navigation aids for related artifacts
|
||
|
||
Agent Coordination Conflicts:
|
||
- Risk: Multiple agents making conflicting changes
|
||
- Mitigation: Clear role definitions, sequential processing
|
||
- Resolution: Human maintainer as final arbiter
|
||
|
||
13.3 Adoption Risks
|
||
Learning Curve:
|
||
|
||
Risk: New contributors struggle with system complexity
|
||
- Mitigation: Comprehensive documentation, template guidance
|
||
- Support: AI_Moderator provides onboarding assistance
|
||
|
||
Process Overhead:
|
||
- Risk: System creates too much ceremony for small changes
|
||
- Mitigation: Configurable rule enabling/disabling
|
||
- Flexibility: Bypass options for trivial changes
|
||
|
||
### 14 Template Evolution
|
||
#### 14.1 Versioning Strategy
|
||
Template Location as Version:
|
||
- Current templates always in process/templates/
|
||
- Breaking changes require new feature request and migration plan
|
||
- Existing features use templates current at their creation
|
||
|
||
Migration Guidance:
|
||
- Document template changes in release notes
|
||
- Provide automated migration scripts for simple changes
|
||
- Flag features using deprecated templates
|
||
|
||
#### 14.2 Core Templates
|
||
Feature Request Template (process/templates/feature_request.md):
|
||
|
||
```markdown
|
||
# Feature Request: <title>
|
||
|
||
**Feature ID**: <FR_YYYY-MM-DD_slug>
|
||
**Intent**: <one paragraph describing purpose>
|
||
**Motivation / Problem**: <why this is needed now>
|
||
**Constraints / Non-Goals**: <bulleted list of limitations>
|
||
**Rough Proposal**: <short implementation outline>
|
||
**Open Questions**: <bulleted list of uncertainties>
|
||
**Meta**: Created: <date> • Author: <name>
|
||
Discussion Template (process/templates/discussion.md):
|
||
```
|
||
|
||
```markdown
|
||
---
|
||
type: discussion
|
||
stage: <feature|design|implementation|testing|review>
|
||
status: OPEN
|
||
feature_id: <FR_...>
|
||
created: <YYYY-MM-DD>
|
||
|
||
promotion_rule:
|
||
allow_agent_votes: true
|
||
ready_min_eligible_votes: all
|
||
reject_min_eligible_votes: all
|
||
|
||
participation:
|
||
instructions: |
|
||
- Append your input at the end as: "YourName: your comment…"
|
||
- Every comment must end with a vote line: "VOTE: READY|CHANGES|REJECT"
|
||
- Agents/bots must prefix names with "AI_"
|
||
|
||
voting:
|
||
values: [READY, CHANGES, REJECT]
|
||
---
|
||
## Summary
|
||
2-4 sentence summary of current state
|
||
|
||
## Participation
|
||
comments appended below
|
||
Design Document Template (process/templates/design_doc.md):
|
||
```
|
||
|
||
```markdown
|
||
# Design — <FR id / Title>
|
||
|
||
## Context & Goals
|
||
## Non-Goals & Constraints
|
||
## Options Considered
|
||
## Decision & Rationale
|
||
## Architecture Diagram(s)
|
||
## Risks & Mitigations
|
||
## Acceptance Criteria (measurable)
|
||
```
|
||
Implementation Plan Template (process/templates/implementation_plan.md):
|
||
|
||
```markdown
|
||
# Implementation Plan — <FR id / Title>
|
||
|
||
## Scope
|
||
## Milestones
|
||
- [ ] M0: Initial setup and scaffolding
|
||
- [ ] M1: Core functionality
|
||
- [ ] M2: Testing and refinement
|
||
## Tasks
|
||
- [ ] specific actionable task
|
||
## Test Strategy
|
||
## Done When
|
||
- <clear, verifiable completion criteria>
|
||
```
|
||
|
||
Discussion Summary Template (process/templates/summary.md):
|
||
|
||
```markdown
|
||
# Summary — <Stage Title>
|
||
(Automatically maintained. Edit the discussion; this file will follow.)
|
||
|
||
<!-- SUMMARY:DECISIONS START -->
|
||
## Decisions (ADR-style)
|
||
- (none yet)
|
||
<!-- SUMMARY:DECISIONS END -->
|
||
|
||
<!-- SUMMARY:OPEN_QUESTIONS START -->
|
||
## Open Questions
|
||
- (none yet)
|
||
<!-- SUMMARY:OPEN_QUESTIONS END -->
|
||
|
||
<!-- SUMMARY:AWAITING START -->
|
||
## Awaiting Replies
|
||
- (none yet)
|
||
<!-- SUMMARY:AWAITING END -->
|
||
|
||
<!-- SUMMARY:ACTION_ITEMS START -->
|
||
## Action Items
|
||
- (none yet)
|
||
<!-- SUMMARY:ACTION_ITEMS END -->
|
||
|
||
<!-- SUMMARY:VOTES START -->
|
||
## Votes (latest per participant)
|
||
READY: 0 • CHANGES: 0 • REJECT: 0
|
||
- (no votes yet)
|
||
<!-- SUMMARY:VOTES END -->
|
||
|
||
<!-- SUMMARY:TIMELINE START -->
|
||
## Timeline (most recent first)
|
||
- <timestamp> <name>: <one-liner>
|
||
<!-- SUMMARY:TIMELINE END -->
|
||
|
||
<!-- SUMMARY:LINKS START -->
|
||
## Links
|
||
- Related PRs: –
|
||
- Commits: –
|
||
- Design/Plan: ../design/design.md
|
||
<!-- SUMMARY:LINKS END -->
|
||
```
|
||
|
||
## Roles & Agent Personas
|
||
### Human Roles
|
||
- Maintainer:
|
||
- Final approval authority for critical stages
|
||
- System configuration and rule definition
|
||
- Conflict resolution and manual overrides
|
||
- Contributor:
|
||
- Feature authorship and implementation
|
||
- Participation in discussions and voting
|
||
- Review and testing responsibilities
|
||
|
||
### AI Agent Roles
|
||
Defined in automation/agents.yml:
|
||
```yaml
|
||
agents:
|
||
AI_Researcher:
|
||
role: research_specialist
|
||
stages: [request, discussion, design]
|
||
capabilities: [web_search, documentation_review, best_practices]
|
||
voting_weight: 0.5
|
||
|
||
AI_Architect:
|
||
role: software_architect
|
||
stages: [design, implementation]
|
||
capabilities: [system_design, tradeoff_analysis, diagram_generation]
|
||
voting_weight: 0.8
|
||
|
||
AI_Implementer:
|
||
role: senior_developer
|
||
stages: [implementation, review]
|
||
capabilities: [code_generation, refactoring, testing_strategy]
|
||
voting_weight: 0.7
|
||
|
||
AI_Reviewer:
|
||
role: quality_engineer
|
||
stages: [review, test]
|
||
capabilities: [code_review, risk_assessment, security_analysis]
|
||
voting_weight: 0.9
|
||
|
||
AI_Moderator:
|
||
role: discussion_moderator
|
||
stages: [discussion, design, review]
|
||
capabilities: [progress_tracking, question_routing, vote_monitoring]
|
||
voting_weight: 0.3
|
||
```
|
||
|
||
#### Role-Specific Responsibilities
|
||
- AI_Researcher:
|
||
- Find prior art, RFCs, and reference implementations
|
||
- Research technical constraints and dependencies
|
||
- Identify potential risks and mitigation strategies
|
||
- AI_Architect:
|
||
- Translate requirements into technical design plan
|
||
- Create and maintain architecture diagrams
|
||
- Evaluate trade-offs and make design recommendations
|
||
- AI_Implementer:
|
||
- Propose code structure and implementation approaches
|
||
- Generate code snippets and refactoring suggestions
|
||
- Develop testing strategies and fixture plans
|
||
- AI_Reviewer:
|
||
- Conduct adversarial code and design review
|
||
- Identify edge cases and failure modes
|
||
- Assess security and performance implications
|
||
- AI_Moderator:
|
||
- Track discussion progress and participation
|
||
- Identify unanswered questions and missing votes
|
||
- Suggest next steps and task ownership
|
||
|
||
## Glossary
|
||
- FR: Feature Request — the initial document proposing new functionality
|
||
- Gate: Promotion decision point between stages based on policy thresholds
|
||
- Append-Only: Edit strategy that only adds new content to end of file, with optional header updates
|
||
- 3-way Apply: Patch application technique using blob IDs to reconcile content drift
|
||
- Cascading Rules: Rule resolution system where nearest directory's rules override parent directories
|
||
- Stage-Per-Discussion: Organizational pattern with separate conversation files for each development phase
|
||
- Human Gate: Promotion requirement that cannot be satisfied by AI votes alone
|
||
- Bug Sub-Cycle: Mini feature lifecycle automatically created for test failures
|
||
- Template Variables: Placeholders ({basename}, {date}, {dir}, {rel}) resolved in rule paths
|
||
- Vote Threshold: Minimum number or type of votes required for promotion
|
||
- Status Machine: Defined state transitions for discussion files (OPEN → READY_FOR_* → etc.)
|
||
- Orchestrator: Central coordination component managing rule execution and status tracking
|
||
|
||
## Appendices
|
||
### Appendix A: Complete Policy Configuration
|
||
```yaml
|
||
# process/policies.yml
|
||
version: 1
|
||
voting:
|
||
values: [READY, CHANGES, REJECT]
|
||
allow_agent_votes: true
|
||
quorum:
|
||
discussion: { ready: all, reject: all }
|
||
design: { ready: all, reject: all }
|
||
implementation: { ready: 1_human, reject: all }
|
||
testing: { ready: all, reject: all }
|
||
review: { ready: 1_human, reject: all }
|
||
eligibility:
|
||
agents_allowed: true
|
||
require_human_for: [implementation, review]
|
||
etiquette:
|
||
name_prefix_agents: "AI_"
|
||
vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\b"
|
||
response_timeout_hours: 24
|
||
timeouts:
|
||
discussion_stale_days: 3
|
||
nudge_interval_hours: 24
|
||
promotion_timeout_days: 14
|
||
```
|
||
|
||
### Appendix B: Diff Application Rules (Normative)
|
||
- Patch Sanitization Rules:
|
||
- Preserve index lines for 3-way merge capability
|
||
- Remove only fragile metadata (similarity, rename info)
|
||
- Keep file mode lines (new file mode, deleted file mode)
|
||
- Ensure proper header formatting for new files
|
||
- Application Order:
|
||
- Attempt 3-way apply with recount and whitespace ignore
|
||
- Fall back to strict apply if 3-way fails
|
||
- For new files: use -p0 patch level with header rewriting
|
||
- Validate patch with --check before application
|
||
- Error Handling:
|
||
- Save all patch variants for debugging
|
||
- Provide clear diagnostics on failure
|
||
- Suggest manual resolution steps when automated recovery fails
|
||
|
||
### Appendix C: Complete Agent Definitions
|
||
```yaml
|
||
# automation/agents.yml
|
||
version: 1
|
||
agent_defaults:
|
||
voting_weight: 0.5
|
||
require_human_approval: false
|
||
|
||
agents:
|
||
AI_Researcher:
|
||
role: research_specialist
|
||
description: "Finds prior art, documentation, and best practices"
|
||
stages: [request, discussion, design]
|
||
capabilities:
|
||
- web_search
|
||
- documentation_review
|
||
- best_practices_research
|
||
- risk_identification
|
||
voting_weight: 0.5
|
||
|
||
AI_Architect:
|
||
role: software_architect
|
||
description: "Designs system architecture and evaluates trade-offs"
|
||
stages: [design, implementation]
|
||
capabilities:
|
||
- system_design
|
||
- tradeoff_analysis
|
||
- diagram_generation
|
||
- technology_selection
|
||
voting_weight: 0.8
|
||
|
||
AI_Implementer:
|
||
role: senior_developer
|
||
description: "Implements features and creates testing strategies"
|
||
stages: [implementation, review]
|
||
capabilities:
|
||
- code_generation
|
||
- refactoring
|
||
- testing_strategy
|
||
- performance_optimization
|
||
voting_weight: 0.7
|
||
|
||
AI_Reviewer:
|
||
role: quality_engineer
|
||
description: "Conducts security, risk, and quality analysis"
|
||
stages: [review, test]
|
||
capabilities:
|
||
- code_review
|
||
- risk_assessment
|
||
- security_analysis
|
||
- quality_validation
|
||
voting_weight: 0.9
|
||
|
||
AI_Moderator:
|
||
role: discussion_moderator
|
||
description: "Tracks progress and ensures participation"
|
||
stages: [discussion, design, review]
|
||
capabilities:
|
||
- progress_tracking
|
||
- question_routing
|
||
- vote_monitoring
|
||
- task_allocation
|
||
voting_weight: 0.3
|
||
```
|
||
|
||
### Final Implementation Note
|
||
This v2.0 design document incorporates all insights from our collaborative discussion, providing a comprehensive framework for AI-human development collaboration. The system balances automation with appropriate human oversight, maintains the lightweight Git-native philosophy, and provides clear escalation paths from feature conception through release.
|
||
|
||
The stage-per-discussion model with automated artifact generation creates a self-documenting development process that scales from small features to large, complex implementations. The integrated bug sub-cycle ensures that quality issues are handled systematically without disrupting the main development flow.
|
||
|
||
Implementation Priority: Begin with Milestone M0 (process foundation) and proceed sequentially through the implementation plan, validating each milestone before proceeding to the next.
|
||
|
||
Document Version: 2.1
|
||
Last Updated: 2025-10-22
|
||
Status: READY_FOR_IMPLEMENTATION
|