# 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:

```markdown
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:

```yaml
---
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.