1st commit
This commit is contained in:
parent
1141725d14
commit
18d84c2b15
304
Docs/DESIGN.md
304
Docs/DESIGN.md
|
|
@ -27,7 +27,12 @@
|
|||
|
||||
## 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.
|
||||
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
|
||||
|
|
@ -36,16 +41,25 @@ We are implementing a Git-native, rules-driven workflow that enables seamless co
|
|||
- Deterministic & Reversible: All automated actions are diffed, logged, and easily revertible
|
||||
- Composable Rules: Nearest-folder precedence via cascading .ai-rules.yml configurations
|
||||
|
||||
### Key Innovations
|
||||
### 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 (Option A: Per-Feature Folders)
|
||||
### Canonical Structure (Per-Feature Folders)
|
||||
```text
|
||||
/ (repository root)
|
||||
├─ .ai-rules.yml # Global defaults + file associations
|
||||
|
|
@ -80,7 +94,7 @@ We are implementing a Git-native, rules-driven workflow that enables seamless co
|
|||
│ │ │ │ ├─ 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.md # Final review
|
||||
│ │ │ │ └─ review.discussion.sum.md # Summary of the review discussion
|
||||
│ │ │ ├─ design/ # Design artifacts
|
||||
│ │ │ │ ├─ design.md # Evolving design document
|
||||
|
|
@ -92,7 +106,7 @@ We are implementing a Git-native, rules-driven workflow that enables seamless co
|
|||
│ │ │ │ ├─ testplan.md # Test strategy
|
||||
│ │ │ │ └─ checklist.md # Test checklist
|
||||
│ │ │ ├─ review/ # Review artifacts
|
||||
│ │ │ │ └─ findings.md # Review findings
|
||||
│ │ │ │ └─ findings.md # Feature-specific review findings
|
||||
│ │ │ └─ bugs/ # Auto-generated bug reports
|
||||
│ │ │ └─ BUG_YYYYMMDD_<slug>/
|
||||
│ │ │ ├─ report.md
|
||||
|
|
@ -122,11 +136,14 @@ Note: Each stage discussion has a companion summary maintained automatically nex
|
|||
|
||||
### 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)
|
||||
- {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 (<stage>.discussion.md), e.g., feature|design|implementation|testing|review
|
||||
|
||||
## Stage Model & Operational Procedure
|
||||
|
||||
|
|
@ -134,6 +151,18 @@ Supported in path resolution:
|
|||
```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
|
||||
|
|
@ -162,6 +191,7 @@ type: discussion
|
|||
stage: feature
|
||||
status: OPEN # OPEN | READY_FOR_DESIGN | REJECTED
|
||||
feature_id: FR_YYYY-MM-DD_<slug>
|
||||
stage_id: FR_YYYY-MM-DD_<slug>_feature
|
||||
created: YYYY-MM-DD
|
||||
|
||||
promotion_rule:
|
||||
|
|
@ -185,12 +215,15 @@ voting:
|
|||
- 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)
|
||||
|
|
@ -206,6 +239,8 @@ voting:
|
|||
type: discussion
|
||||
stage: design
|
||||
status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO
|
||||
feature_id: FR_YYYY-MM-DD_<slug>
|
||||
stage_id: FR_YYYY-MM-DD_<slug>_design
|
||||
# ... same promotion_rule, participation, voting as feature
|
||||
---
|
||||
```
|
||||
|
|
@ -216,6 +251,8 @@ status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO
|
|||
- 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
|
||||
|
|
@ -249,6 +286,8 @@ status: OPEN # OPEN | READY_FOR_IMPLEMENTATION | NEEDS_MORE_INFO
|
|||
type: discussion
|
||||
stage: implementation
|
||||
status: OPEN # OPEN | READY_FOR_TESTING
|
||||
feature_id: FR_YYYY-MM-DD_<slug>
|
||||
stage_id: FR_YYYY-MM-DD_<slug>_implementation
|
||||
promotion_rule:
|
||||
allow_agent_votes: true
|
||||
ready_min_eligible_votes: 1_human # HUMAN GATE
|
||||
|
|
@ -263,6 +302,8 @@ promotion_rule:
|
|||
- 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
|
||||
|
|
@ -287,17 +328,18 @@ promotion_rule:
|
|||
#### Header
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: discussion
|
||||
stage: testing
|
||||
status: OPEN # OPEN | READY_FOR_REVIEW
|
||||
feature_id: FR_YYYY-MM-DD_<slug>
|
||||
stage_id: FR_YYYY-MM-DD_<slug>_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
|
||||
|
|
@ -305,6 +347,8 @@ promotion_rule:
|
|||
- 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
|
||||
|
|
@ -320,9 +364,11 @@ promotion_rule:
|
|||
bugs/BUG_YYYYMMDD_<slug>/
|
||||
├─ 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
|
||||
|
|
@ -330,9 +376,19 @@ bugs/BUG_YYYYMMDD_<slug>/
|
|||
- 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 discussions/review.discussion.md (OPEN)
|
||||
- Creates review/findings.md with verification summary
|
||||
- Creates or report to discussions/review.discussion.md (OPEN)
|
||||
- Creates review/findings_BUG_YYYYMMDD_<slug>.md with verification summary
|
||||
|
||||
### Stage 6: Review Discussion
|
||||
- File: discussions/review.discussion.md
|
||||
|
|
@ -344,6 +400,8 @@ bugs/BUG_YYYYMMDD_<slug>/
|
|||
type: discussion
|
||||
stage: review
|
||||
status: OPEN # OPEN | READY_FOR_RELEASE | CHANGES_REQUESTED
|
||||
feature_id: FR_YYYY-MM-DD_<slug>
|
||||
stage_id: FR_YYYY-MM-DD_<slug>_review
|
||||
promotion_rule:
|
||||
allow_agent_votes: true
|
||||
ready_min_eligible_votes: 1_human # HUMAN GATE
|
||||
|
|
@ -358,6 +416,8 @@ promotion_rule:
|
|||
- 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
|
||||
|
|
@ -379,17 +439,18 @@ promotion_rule:
|
|||
- 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
|
||||
- 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:
|
||||
|
||||
|
|
@ -404,6 +465,11 @@ 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):
|
||||
|
||||
|
|
@ -421,7 +487,7 @@ eligibility:
|
|||
require_human_for: [implementation, release]
|
||||
etiquette:
|
||||
name_prefix_agents: "AI_"
|
||||
vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\b"
|
||||
vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\s*$"
|
||||
timeouts:
|
||||
discussion_stale_days: 3
|
||||
nudge_interval_hours: 24
|
||||
|
|
@ -431,14 +497,49 @@ Human Safety Gates:
|
|||
- 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** | `<feature>/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
|
||||
|
|
@ -491,18 +592,37 @@ settings:
|
|||
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"
|
||||
"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:
|
||||
|
|
@ -510,22 +630,42 @@ rules:
|
|||
path: "{dir}/discussions/feature.discussion.md"
|
||||
output_type: "feature_discussion_writer"
|
||||
instruction: |
|
||||
If discussion file missing: create with standard header (stage: feature, status: OPEN),
|
||||
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 operation.
|
||||
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 single vote line.
|
||||
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
|
||||
- Clearly state promotion decision in comment
|
||||
Append-only with minimal diff.
|
||||
- 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"
|
||||
|
|
@ -538,9 +678,17 @@ rules:
|
|||
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.
|
||||
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:
|
||||
|
|
@ -551,6 +699,13 @@ rules:
|
|||
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"
|
||||
|
|
@ -571,6 +726,13 @@ rules:
|
|||
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:
|
||||
|
|
@ -581,6 +743,13 @@ rules:
|
|||
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"
|
||||
|
|
@ -592,7 +761,7 @@ rules:
|
|||
output_type: "testplan_writer"
|
||||
instruction: |
|
||||
Create ONLY if implementation status is READY_FOR_TESTING.
|
||||
Derive test strategy from acceptance criteria.
|
||||
Derive strategy from acceptance criteria.
|
||||
|
||||
test_checklist:
|
||||
path: "{dir}/testing/checklist.md"
|
||||
|
|
@ -601,22 +770,35 @@ rules:
|
|||
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 blocks from test discussion ([RESULT] PASS/FAIL: description).
|
||||
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 with clear reproduction steps.
|
||||
Initialize bug discussion and fix plan in same folder.
|
||||
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"
|
||||
|
|
@ -631,20 +813,44 @@ rules:
|
|||
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 enhancement opportunity.
|
||||
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 defect.
|
||||
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
|
||||
|
|
@ -1145,22 +1351,22 @@ Future versions can post summaries to the feature’s implementation discussion
|
|||
## 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.
|
||||
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.sum.md
|
||||
├─ feature.discussion.sum.md
|
||||
├─ design.discussion.md
|
||||
├─ design.sum.md
|
||||
├─ design.discussion.sum.md
|
||||
├─ implementation.discussion.md
|
||||
├─ implementation.sum.md
|
||||
├─ implementation.discussion.sum.md
|
||||
├─ testing.discussion.md
|
||||
├─ testing.sum.md
|
||||
├─ testing.discussion.sum.md
|
||||
├─ review.discussion.md
|
||||
└─ review.sum.md
|
||||
└─ review.discussion.sum.md
|
||||
```
|
||||
|
||||
### Header (machine-readable)
|
||||
|
|
@ -1248,7 +1454,7 @@ rules:
|
|||
feature_discussion:
|
||||
outputs:
|
||||
summary_companion:
|
||||
path: "{dir}/discussions/feature.sum.md"
|
||||
path: "{dir}/discussions/feature.discussion.sum.md"
|
||||
output_type: "discussion_summary_writer"
|
||||
instruction: |
|
||||
Create or update the summary file. Replace ONLY content between
|
||||
|
|
@ -1258,28 +1464,28 @@ rules:
|
|||
design_discussion:
|
||||
outputs:
|
||||
summary_companion:
|
||||
path: "{dir}/discussions/design.sum.md"
|
||||
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.sum.md"
|
||||
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.sum.md"
|
||||
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.sum.md"
|
||||
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.
|
||||
|
|
@ -1621,7 +1827,7 @@ agents:
|
|||
- 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
|
||||
- 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
|
||||
|
|
@ -1645,7 +1851,7 @@ eligibility:
|
|||
require_human_for: [implementation, review]
|
||||
etiquette:
|
||||
name_prefix_agents: "AI_"
|
||||
vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\b"
|
||||
vote_line_regex: "^VOTE:\\s*(READY|CHANGES|REJECT)\\s*$"
|
||||
response_timeout_hours: 24
|
||||
timeouts:
|
||||
discussion_stale_days: 3
|
||||
|
|
|
|||
Loading…
Reference in New Issue