CascadingDev/CONTRIBUTING.md

Contributing to CascadingDev

First off, thank you for considering contributing! It's people like you that make CascadingDev such a great tool.

This document provides a guide for contributors on how to participate in the development process, particularly around the voting and automated status promotion system.

The Voting System

The core of the collaborative process in CascadingDev revolves around a simple voting system within discussion files. This system is used to gauge consensus and drive the automated workflow.

Vote Types

There are three types of votes you can cast:

• VOTE: READY: You are satisfied with the current state of the discussion and believe it's ready to move to the next stage.
• VOTE: CHANGES: You believe changes are needed before the discussion can proceed. You should accompany this vote with comments outlining the required changes.
• VOTE: REJECT: You believe the proposal should be rejected. This is a strong vote that can halt a discussion's progress.

How to Vote

To cast a vote, add your name and comment to the relevant discussion file (e.g., feature.discussion.md). The format is as follows:

Name: Your Name

Your comment about the proposal.

VOTE: READY

The system only considers the latest vote from each participant.

Automated Status Promotion

CascadingDev uses the votes from participants to automatically promote the status of a discussion. This is controlled by a promotion_rule defined in the YAML front matter of the discussion file.

The promotion_rule

Here is an example of a promotion_rule in a feature.discussion.md file:

---
type: feature-discussion
stage: feature
status: OPEN
promotion_rule:
  allow_agent_votes: false
  ready_min_eligible_votes: 2
  reject_min_eligible_votes: 1
  ready_status: "READY_FOR_DESIGN"
  reject_status: "FEATURE_REJECTED"
---

Name: Alice
I think this is a great idea.
VOTE: READY

---

Name: Bob
I agree, let's move forward.
VOTE: READY

Parameters

• allow_agent_votes (boolean, optional): If true, votes from participants with names starting with AI_ will be counted. Defaults to false.
• ready_min_eligible_votes (integer | "all", optional): The number of READY votes required to promote the status. If set to "all", all eligible voters must vote READY. Defaults to 2.
• reject_min_eligible_votes (integer | "all", optional): The number of REJECT votes required to reject the discussion. Defaults to 1.
• ready_status (string, optional): The status to set when the ready threshold is met. This is typically the next stage in the lifecycle (e.g., READY_FOR_DESIGN).
• reject_status (string, optional): The status to set when the reject threshold is met (e.g., FEATURE_REJECTED).

Lifecycle of a Discussion

The automated status promotion creates a lifecycle for discussions:

1. A feature discussion starts with status: OPEN. When enough READY votes are cast, its status is promoted to READY_FOR_DESIGN.
2. This triggers the creation of a design discussion.
3. The design discussion goes through the same voting process. When it's ready, its status is promoted to READY_FOR_IMPLEMENTATION.
4. This, in turn, can trigger the AI to start writing code.

This automated, vote-driven workflow is at the heart of what makes CascadingDev a powerful tool for collaborative, AI-assisted development.