# 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. > *Git-Native Philosophy: Every conversation, decision, and generated artifact lives in the same version-controlled environment as the source code. There are no external databases, dashboards, or SaaS dependencies required for the core workflow. ### Objective: Establish a reproducible, self-documenting workflow where 90% of documentation, status artifacts and code changes are generated automatically from development discussions, while maintaining human oversight for all promotion gates and releases. ### 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 ### Innovative Features - 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 ### System Overview: The architecture consists of a lightweight Bash pre-commit hook for artifact generation, a Python orchestrator for state evaluation and policy enforcement, and optional adapters for model and API integrations (Claude, Gitea, etc.). Together they form a layered, rule-driven automation stack. ```text Human → Git Commit → Pre-commit Hook → AI Generator → Markdown Artifact ↑ ↓ Orchestrator ← Discussion Summaries ← AI Moderator ``` ## Repository Layout ### Canonical Structure (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_/ # 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 # Feature-specific review findings │ │ │ └─ bugs/ # Auto-generated bug reports │ │ │ └─ BUG_YYYYMMDD_/ │ │ │ ├─ 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_/ - Discussion Files: {stage}.discussion.md in discussions/ subfolder - Discussion summary: {stage}.discussion.sum.md in discussions/ subfolder - Bug Reports: bugs/BUG_YYYYMMDD_/ with standardized contents - Source Files: Maintain existing patterns in src/ ### Template Variables Supported in path resolution: - {basename} — filename with extension (e.g., design.discussion.md) - {name} — filename without extension (e.g., design.discussion) - {ext} — file extension without dot (e.g., md) - {date} — current date in YYYY-MM-DD - {rel} — repository-relative path to the source file - {dir} — directory containing the source file - {feature_id} — nearest FR_* folder name (e.g., FR_2025-10-21_initial-feature-request) - {stage} — stage inferred from discussion filename (.discussion.md), e.g., feature|design|implementation|testing|review ## Stage Model & Operational Procedure ### Complete Stage Lifecycle ```text Request → Feature Discussion → Design Discussion → Implementation Discussion → Testing Discussion → Review Discussion → Release ``` ### Stage Overview | Stage | Primary File | Promotion Trigger | Human Gate | Key Artifacts Created | |:------|:-------------|:------------------|:-----------|:----------------------| | 1 Request | request.md | Created from template | – | feature.discussion.md, feature.discussion.sum.md | | 2 Feature Discussion | discussions/feature.discussion.md | Votes → READY_FOR_DESIGN | – | design.discussion.md, design/design.md | | 3 Design Discussion | discussions/design.discussion.md | Votes → READY_FOR_IMPLEMENTATION | – | implementation.discussion.md, implementation/plan.md, implementation/tasks.md | | 4 Implementation Discussion | discussions/implementation.discussion.md | All required tasks complete → READY_FOR_TESTING | ✅ ≥1 human READY | testing.discussion.md, testing/testplan.md, testing/checklist.md | | 5 Testing Discussion | discussions/testing.discussion.md | All tests pass → READY_FOR_REVIEW | – | review.discussion.md, review/findings.md | | 6 Review Discussion | discussions/review.discussion.md | Human READY → READY_FOR_RELEASE | ✅ ≥1 human READY | Release notes, follow-up FRs/Bugs | | 7 Release | – | Tag & changelog generated | ✅ maintainer | Changelog, version bump, rollback notes | ### 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_ stage_id: FR_YYYY-MM-DD__feature 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 _Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._ #### 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 > **Automation boundary:** All actions occur within the same Git commit and are never auto-committed by the orchestrator. #### 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 feature_id: FR_YYYY-MM-DD_ stage_id: FR_YYYY-MM-DD__design # ... 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 _Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._ #### 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 feature_id: FR_YYYY-MM-DD_ stage_id: FR_YYYY-MM-DD__implementation 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 _Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._ #### 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 feature_id: FR_YYYY-MM-DD_ stage_id: FR_YYYY-MM-DD__testing 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 _Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._ #### 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_/ ├─ report.md # Steps, expected/actual, environment ├─ discussion.md # Bug discussion (OPEN) ├─ discussion.sum.md # Summary of Bug discussion └─ fix/ ├─ plan.md # Fix implementation plan └─ tasks.md # Fix tasks checklist └─ src/ ``` #### Bug Resolution Flow - Bug follows mini Implementation→Testing cycle - On bug closure, return to main testing discussion - Bug results integrated into main test checklist _The bug sub-cycle mirrors Stages 4–6 (Implementation → Testing → Review) and inherits the same promotion and voting policies._ #### Automated Actions on commit - Appends AI comment with vote to discussion.md - Moderates discussion - establishes fix objectives from plan.md - delegates fix tasks from tasks.md - Maintains discussions/discussion.sum.md - Creates/maintains fix/src/* files if any are produced during the discussion. #### Promotion Actions - Creates or report to discussions/review.discussion.md (OPEN) - Creates review/findings_BUG_YYYYMMDD_.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 feature_id: FR_YYYY-MM-DD_ stage_id: FR_YYYY-MM-DD__review 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 _Promotion decisions obey thresholds in `process/policies.yml` (`voting.quorum`). The orchestrator re-evaluates eligibility before any status change._ #### 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 _State machine summary:_ All stage transitions are governed by the orchestrator and thresholds defined in `process/policies.yml`. Human gates remain mandatory for Implementation and Release. ## 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 - Trailing spaces are ignored; the vote must be the final non-empty line 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) ``` **Update Rules** - Latest vote per participant supersedes all prior votes in the same stage. - If a comment has multiple “VOTE:” lines, only the **last** valid line counts. - Empty or malformed vote lines are ignored (no implicit abstain). ### 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)\\s*$" 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 ### Promotion Evaluation Algorithm 1. Parse latest vote per participant (apply `vote_line_regex` to final non-empty line). 2. Filter by eligibility (humans/agents per stage policy). 3. Check human-gate requirement (if configured for the stage). 4. Evaluate quorum thresholds from `voting.quorum[stage]`: - `ready: all` → all eligible voters are `READY` (or no `CHANGES/REJECT`) - `ready: 1_human` → at least one human `READY` - `reject: all` → if any `REJECT`, fail promotion 5. If thresholds met → flip `status` to the target (e.g., `READY_FOR_DESIGN`) **within the same commit** and generate next artifacts. 6. If not met → append moderator summary and keep status unchanged. Eligibility Definition - Eligible voter: any participant (human or agent) who posted in the current stage discussion and conforms to eligibility.* policy. - Human gate: stages listed in eligibility.require_human_for require ≥ 1 human READY regardless of agent votes. ### 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 - Staleness & Nudges: If a stage has no new comments within `discussion_stale_days`, the AI_Moderator posts a nudge every `nudge_interval_hours` with missing votes and open questions. ### Tie-breaks & Deadlocks - If votes include both `READY` and `CHANGES/REJECT` beyond the promotion timeout (`promotion_timeout_days`), the AI_Moderator escalates: 1) Summarize blocking points and owners, 2) Request explicit human decision, 3) If still unresolved after one more nudge window, maintain status and open a follow-up item in the summary’s **ACTION_ITEMS**. ## Cascading Rules System The Cascading Rules System defines how automation instructions are discovered and applied for any file committed in the repository. The nearest `.ai-rules.yml` file to a changed file determines how it will be processed. Rules can exist at three scopes: | Scope | Typical Path | Purpose | |:------|:-------------|:---------| | **Global** | `/.ai-rules.yml` | Default behavior for all files (e.g., code, diagrams) | | **Feature-Scoped** | `Docs/features/.ai-rules.yml` | Rules specific to feature discussions and artifacts | | **Local / Experimental** | `/local/.ai-rules.yml` (optional) | Overrides for prototypes or nested modules | Rule lookup always starts in the source file’s directory and walks upward until it finds a `.ai-rules.yml`, then merges settings from outer scopes, where **nearest directory wins**. ### 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" ``` ### Validation & Schema Each `.ai-rules.yml` must pass a lightweight YAML schema check before execution: - `version` key is required (integer or semver) - `file_associations` maps glob patterns → rule names - Each rule under `rules:` must include at least one of: - `description`, `outputs:` with `path`, `output_type`, and `instruction` - Unknown keys are ignored but logged as warnings. Schema validation prevents mis-typed keys from silently breaking automation. ### Feature-Scoped Rules (Docs/features/.ai-rules.yml) ```yaml version: 1 file_associations: "request.md": "feature_request" # discussions "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" # summaries (companions) "feature.discussion.sum.md": "discussion_summary" "design.discussion.sum.md": "discussion_summary" "implementation.discussion.sum.md": "discussion_summary" "testing.discussion.sum.md": "discussion_summary" "review.discussion.sum.md": "discussion_summary" rules: feature_request: outputs: feature_discussion: path: "{dir}/discussions/feature.discussion.md" output_type: "feature_discussion_writer" instruction: | If missing: create with standard header (stage: feature, status: OPEN), add Summary and Participation sections, then append initial AI comment with vote. If exists: no op. # Also create the companion summary file if missing (blank sections with markers) feature_summary_init: path: "{dir}/discussions/feature.discussion.sum.md" output_type: "discussion_summary_init" instruction: | If missing, create companion summary with stable markers: DECISIONS, OPEN_QUESTIONS, AWAITING, ACTION_ITEMS, VOTES, TIMELINE, LINKS. If exists, do not modify. feature_discussion: outputs: # 1) Append the new AI comment to the discussion (append-only) self_append: path: "{dir}/discussions/feature.discussion.md" output_type: "feature_discussion_writer" instruction: | Append concise comment signed with AI name, ending with a single vote line. Evaluate votes against header thresholds. If READY threshold met: - Flip status to READY_FOR_DESIGN (or FEATURE_REJECTED) Clearly state promotion decision. Append-only with minimal diff. # 2) Update the companion summary (marker-bounded sections only) summary_companion: path: "{dir}/discussions/feature.discussion.sum.md" output_type: "discussion_summary_writer" instruction: | Create or update the summary file. Replace ONLY content between markers: DECISIONS, OPEN_QUESTIONS, AWAITING, ACTION_ITEMS, VOTES, TIMELINE, LINKS. Inputs: the entire feature.discussion.md and current header. Keep diffs minimal. # 3) Promotion artifacts when READY_FOR_DESIGN 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 from request.md and feature discussion. Include: Context, Options, Decision, Risks, Acceptance Criteria. # Ensure design summary exists once design discussion begins design_summary_init: path: "{dir}/discussions/design.discussion.sum.md" output_type: "discussion_summary_init" instruction: | If missing, create companion summary with standard markers. If exists, do not modify unless via discussion_summary_writer. 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. # Always keep the design summary in sync (marker-bounded) summary_companion: path: "{dir}/discussions/design.discussion.sum.md" output_type: "discussion_summary_writer" instruction: | Update only the marker-bounded sections from the discussion content. 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. # Ensure implementation summary exists at the moment implementation starts impl_summary_init: path: "{dir}/discussions/implementation.discussion.sum.md" output_type: "discussion_summary_init" instruction: | If missing, create companion summary with standard markers. 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. summary_companion: path: "{dir}/discussions/implementation.discussion.sum.md" output_type: "discussion_summary_writer" instruction: | Update only the marker-bounded sections from the discussion content. Include unchecked items from ../implementation/tasks.md in ACTION_ITEMS. 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 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_summary_init: path: "{dir}/discussions/testing.discussion.sum.md" output_type: "discussion_summary_init" instruction: | If missing, create companion summary with standard markers. test_discussion: outputs: checklist_update: path: "{dir}/testing/checklist.md" output_type: "testchecklist_maintainer" instruction: | Parse [RESULT] PASS/FAIL blocks from test discussion. Update checklist accordingly with evidence links. On test failure, create appropriate bug report. summary_companion: path: "{dir}/discussions/testing.discussion.sum.md" output_type: "discussion_summary_writer" instruction: | Update marker-bounded sections from the discussion content. Surface FAILs in OPEN_QUESTIONS or AWAITING with owners. bug_report: path: "{dir}/bugs/BUG_{date}_auto/report.md" output_type: "bug_report_writer" instruction: | Create bug report ONLY when test failure has clear reproduction steps. Initialize bug discussion and fix plan in the 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_summary_init: path: "{dir}/discussions/review.discussion.sum.md" output_type: "discussion_summary_init" instruction: | If missing, create companion summary with standard markers. review_discussion: outputs: summary_companion: path: "{dir}/discussions/review.discussion.sum.md" output_type: "discussion_summary_writer" instruction: | Update marker-bounded sections from the discussion content. Decisions should include READY_FOR_RELEASE with date and follow-ups. followup_feature: path: "../../FR_{date}_followup/request.md" output_type: "feature_request_writer" instruction: | Create follow-up feature request ONLY when review identifies an enhancement. followup_bug: path: "{dir}/bugs/BUG_{date}_review/report.md" output_type: "bug_report_writer" instruction: | Create bug report ONLY when review identifies a defect. Seed discussion and fix plan. # Generic writer invoked when a *.discussion.sum.md file itself is staged/edited discussion_summary: outputs: normalize: path: "{dir}/{basename}.sum.md" output_type: "discussion_summary_normalizer" instruction: | Ensure standard header exists and marker blocks are present. Do not rewrite content outside markers. ``` 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 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' <<>> 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 <<>> 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 │ │ │ ├─ 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}.discussion.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.discussion.sum.md ├─ design.discussion.md ├─ design.discussion.sum.md ├─ implementation.discussion.md ├─ implementation.discussion.sum.md ├─ testing.discussion.md ├─ testing.discussion.sum.md ├─ review.discussion.md └─ review.discussion.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_ updated: YYYY-MM-DDTHH:MM:SSZ policy: allow_agent_votes: true require_human_for: [implementation, review] --- ``` ### Stable section markers (for tiny diffs) ```markdown # Summary — ## Decisions (ADR-style) - (none yet) ## Open Questions - (none yet) ## Awaiting Replies - (none yet) ## Action Items - (none yet) ## Votes (latest per participant) READY: 0 • CHANGES: 0 • REJECT: 0 - (no votes yet) ## Timeline (most recent first) - : ## Links - Related PRs: – - Commits: – - Design/Plan: ../design/design.md ``` ### 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/.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.discussion.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.discussion.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.discussion.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.discussion.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.discussion.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 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: **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}, {name}, {ext}, {date}, {rel}, {dir}, {feature_id}, {stage}) 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)\\s*$" 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