CascadingDev/docs/AUTOMATION.md

# CascadingDev Automation System

## Overview

The CascadingDev automation system processes discussion files during git commits to maintain structured summaries. It operates in two phases:

**Phase 1 (Basic)**: Always runs, no dependencies
- Parses `VOTE:` lines from discussions
- Tracks latest vote per participant
- Updates summary `.sum.md` files automatically

**Phase 2 (AI-Enhanced)**: Optional, requires Claude API
- Extracts questions, action items, and decisions using AI
- Tracks @mentions and awaiting replies
- Processes only incremental changes (git diff)
- Maintains timeline and structured summaries

## Architecture

```
automation/
├── workflow.py      # Main orchestrator, called by pre-commit hook
├── agents.py        # Claude-powered extraction agents
├── summary.py       # Summary file formatter and updater
└── __init__.py
```

## Phase 1: Vote Tracking (Always Enabled)

### How It Works

1. **Pre-commit hook** triggers `automation/workflow.py --status`
2. Finds all staged `.discussion.md` files
3. Parses entire file for `VOTE:` lines
4. Maintains latest vote per participant
5. Updates corresponding `.sum.md` file's VOTES section
6. Auto-stages updated summaries

### Vote Format

```markdown
- ParticipantName: Any comment text. VOTE: READY|CHANGES|REJECT
```

**Rules:**
- Only the **latest** vote per participant counts
- Case-insensitive vote tokens (vote:, VOTE:, Vote:)
- Three valid values: READY, CHANGES, REJECT
- Must follow participant bullet format: `- Name: ...`

### Example

**Discussion file:**
```markdown
- Alice: I like this approach. VOTE: READY
- Bob: We need tests first. VOTE: CHANGES
- Alice: Good point, updated the plan. VOTE: CHANGES
```

**Resulting summary:**
```markdown
<!-- SUMMARY:VOTES START -->
## Votes (latest per participant)
READY: 0 • CHANGES: 2 • REJECT: 0
- Alice: CHANGES
- Bob: CHANGES
<!-- SUMMARY:VOTES END -->
```

## Phase 2: AI-Enhanced Processing (Optional)

### Requirements

Phase 2 supports multiple AI providers via CLI commands or direct API:

**Option 1: CLI-based (Recommended)**
```bash
# Uses whatever AI CLI tool you have installed
# Default: claude -p "prompt"

# Configure via git config (persistent)
git config cascadingdev.aiprovider "claude-cli"
git config cascadingdev.aicommand "claude -p '{prompt}'"

# Or via environment variables (session)
export CDEV_AI_PROVIDER="claude-cli"
export CDEV_AI_COMMAND="claude -p '{prompt}'"
```

**Option 2: Direct API (Alternative)**
```bash
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
```

If no AI provider is configured or responding, Phase 2 features are silently skipped and only Phase 1 (votes) runs.

### Features

#### 1. @Mention Tracking

Extracts `@Name` and `@all` mentions from discussions to track who's waiting for replies.

**Format:**
```markdown
- Alice: @Bob what do you think about OAuth2?
- Carol: @all please review by Friday
```

**Summary section:**
```markdown
<!-- SUMMARY:AWAITING START -->
## Awaiting Replies

### @Bob
- @Alice: What do you think about OAuth2?

### @all
- @Carol: Please review by Friday
<!-- SUMMARY:AWAITING END -->
```

#### 2. Question Tracking

Identifies questions and tracks their answers.

**Markers (optional but recommended):**
```markdown
- Alice: Q: Should we use OAuth2 or JWT?
- Bob: A: I'd recommend OAuth2 for third-party auth.
```

**Also detects:**
- Lines ending with `?`
- `Question:` prefix
- `Re:` replies (indicate partial answers)

**Summary section:**
```markdown
<!-- SUMMARY:OPEN_QUESTIONS START -->
## Open Questions
- @Alice: Should we cache API responses?

### Partially Answered:
- @Bob: What about rate limiting?
  - Partial answer: We'll use token bucket algorithm
<!-- SUMMARY:OPEN_QUESTIONS END -->
```

#### 3. Action Item Management

Tracks tasks from creation → assignment → completion.

**Markers (optional but recommended):**
```markdown
- Alice: TODO: Research OAuth2 libraries
- Bob: I'll handle the JWT implementation.
- Alice: DONE: Completed library research, recommending authlib.
- Dave: ACTION: Review security implications
```

**Summary section:**
```markdown
<!-- SUMMARY:ACTION_ITEMS START -->
## Action Items

### TODO (unassigned):
- [ ] Document the authentication flow (suggested by @Carol)

### In Progress:
- [ ] Implement JWT token validation (@Bob)

### Completed:
- [x] Research OAuth2 libraries (@Alice)
<!-- SUMMARY:ACTION_ITEMS END -->
```

#### 4. Decision Logging (ADR-Style)

Captures architectural decisions with rationale.

**Markers (optional but recommended):**
```markdown
- Alice: DECISION: Use OAuth2 + JWT hybrid approach.
  Rationale: OAuth2 for robust third-party auth, JWT for stateless sessions.
```

**Also detects:**
- "We decided to..."
- "Going with X because..."
- Vote consensus (multiple READY votes)

**Summary section:**
```markdown
<!-- SUMMARY:DECISIONS START -->
## Decisions (ADR-style)

### Decision 1: Use OAuth2 + JWT hybrid approach
- **Proposed by:** @Alice
- **Supported by:** @Bob, @Carol
- **Rationale:** OAuth2 for robust third-party auth, JWT for stateless sessions
- **Alternatives considered:**
  - Pure JWT authentication
  - Session-based auth with cookies
<!-- SUMMARY:DECISIONS END -->
```

## Conversation Guidelines (Optional)

Using these markers helps the AI extract information more accurately, but natural language also works:

```markdown
# Suggested Markers

Q: <question>          # Mark questions explicitly
A: <answer>            # Mark answers explicitly
Re: <response>         # Partial answers or follow-ups

TODO: <action>         # New unassigned task
ACTION: <action>       # Task with implied ownership
DONE: <completion>     # Mark task complete

DECISION: <choice>     # Architectural decision
Rationale: <why>       # Explain reasoning

VOTE: READY|CHANGES|REJECT  # REQUIRED for voting

@Name                  # Mention someone specifically
@all                   # Mention everyone
```

## Implementation Details

### Incremental Processing

The system only processes **new content** added since the last commit:

1. Uses `git diff HEAD <file>` to get changes
2. Extracts only lines starting with `+` (added lines)
3. Feeds incremental content to AI agents
4. Updates summary sections non-destructively

### Marker Block System

Summary files use HTML comment markers for non-destructive updates:

```markdown
<!-- SUMMARY:SECTION_NAME START -->
## Section Header
<content>
<!-- SUMMARY:SECTION_NAME END -->
```

**Sections:**
- `VOTES` - Vote counts and participants
- `DECISIONS` - ADR-style decisions
- `OPEN_QUESTIONS` - Unanswered questions
- `AWAITING` - Unresolved @mentions
- `ACTION_ITEMS` - TODO → ASSIGNED → DONE
- `TIMELINE` - Chronological updates (future)
- `LINKS` - Related PRs/commits (future)

### Error Handling

The workflow is **non-blocking**:
- Always exits 0 (never blocks commits)
- Prints warnings to stderr for missing dependencies
- Falls back to Phase 1 (votes only) if API key missing
- Continues on individual agent failures

### Testing

```bash
# Run all tests
pytest tests/

# Test vote parsing
pytest tests/test_workflow.py -v

# Manual test in a project
cd /path/to/cascadingdev-project
echo "- Test: Comment with vote. VOTE: READY" >> Docs/features/test/discussions/test.discussion.md
git add Docs/features/test/discussions/test.discussion.md
git commit -m "Test workflow"  # Triggers automation
```

## Configuration

### AI Provider Options

**1. Claude CLI (Default)**
```bash
# No configuration needed if you have 'claude' command available
# The system defaults to: claude -p '{prompt}'

# To customize:
git config cascadingdev.aicommand "claude -p '{prompt}'"
```

**2. Gemini CLI**
```bash
git config cascadingdev.aiprovider "gemini-cli"
git config cascadingdev.aicommand "gemini '{prompt}'"
```

**3. OpenAI Codex CLI**
```bash
git config cascadingdev.aiprovider "codex-cli"
git config cascadingdev.aicommand "codex '{prompt}'"
```

**4. Direct API (Anthropic)**
```bash
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
# CLI commands will fallback to API if available
```

**5. Custom AI Command**
```bash
# Use any command that reads a prompt and returns JSON
git config cascadingdev.aicommand "my-ai-tool --prompt '{prompt}' --format json"
```

### Disabling AI Features

Simply don't configure any AI provider. The system will:
- Log a warning: `[agents] warning: No AI provider configured, skipping AI processing`
- Continue with Phase 1 (vote tracking only)
- Still extract @mentions (doesn't require AI)

## Future Enhancements

🚧 **Phase 3 (Planned):**
- Timeline auto-population from git commits
- Link tracking (related PRs, commits)
- Multi-file decision tracking
- Slack/Discord notification integration
- Summary diffs between commits
- Natural language summary generation

## Troubleshooting

### "agents module not available"

**Cause:** Import path issue when workflow.py runs from pre-commit hook.

**Solution:** Already fixed in workflow.py with dual import style:
```python
try:
    from automation import agents
except ImportError:
    import agents  # Fallback for different execution contexts
```

### "No AI provider configured"

**Cause:** No AI CLI command or API key configured.

**Solution:** Choose one:
```bash
# Option 1: Use Claude CLI (default)
git config cascadingdev.aicommand "claude -p '{prompt}'"

# Option 2: Use Gemini CLI
git config cascadingdev.aiprovider "gemini-cli"
git config cascadingdev.aicommand "gemini '{prompt}'"

# Option 3: Use Anthropic API
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
```

Or accept Phase 1 only (votes only, still useful)

### "AI command failed with code X"

**Cause:** AI CLI command returned error.

**Solution:**
1. Test command manually: `claude -p "test prompt"`
2. Check command is in PATH: `which claude`
3. Verify command syntax in config: `git config cascadingdev.aicommand`
4. Check stderr output in warning message for details

### Summary sections not updating

**Cause:** Markers might be malformed or missing.

**Solution:**
1. Check summary file has proper markers (see "Marker Block System")
2. Regenerate from template if needed
3. File should be created automatically by pre-commit hook

### Votes not being detected

**Cause:** Format doesn't match parser expectations.

**Solution:** Ensure format is:
```markdown
- ParticipantName: Comment text. VOTE: READY
```

Common issues:
- Missing `- ` bullet
- Missing `: ` after name
- Typo in vote value (must be READY, CHANGES, or REJECT)
- Multiple participants on one line (not supported)

## See Also

- [DESIGN.md](DESIGN.md) - Overall system architecture
- [CLAUDE.md](../CLAUDE.md) - Guide for AI assistants
- [USER_GUIDE.md](../assets/templates/USER_GUIDE.md) - User-facing documentation