diff --git a/automation/README.md b/automation/README.md
new file mode 100644
index 0000000..f6a8aad
--- /dev/null
+++ b/automation/README.md
@@ -0,0 +1,152 @@
+# CascadingDev Automation
+
+Automated discussion summarization with AI-powered extraction.
+
+## Quick Start
+
+**Phase 1 (Always Works):**
+```bash
+# Just commit! Vote tracking happens automatically
+git commit -m "Discussion updates"
+```
+
+**Phase 2 (AI-Enhanced):**
+```bash
+# Option 1: Use Claude CLI (default - no config needed)
+# Just have 'claude' command available in PATH
+
+# Option 2: Use different AI
+git config cascadingdev.aicommand "gemini '{prompt}'"
+
+# Option 3: Use API directly
+pip install anthropic
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+## What Gets Automated
+
+### Phase 1 (Basic)
+- ✅ Vote counting (READY/CHANGES/REJECT)
+- ✅ Latest vote per participant
+- ✅ Auto-update summary files
+
+### Phase 2 (AI-Powered)
+- ✅ @Mention tracking
+- ✅ Question identification (OPEN/PARTIAL/ANSWERED)
+- ✅ Action items (TODO → ASSIGNED → DONE)
+- ✅ Decision logging (ADR-style with rationale)
+
+## Configuration Examples
+
+### Claude Code (Default)
+```bash
+# No configuration needed if 'claude' command works
+claude -p "test"  # Verify command works
+
+# Or customize:
+git config cascadingdev.aicommand "claude -p '{prompt}'"
+```
+
+### Gemini CLI
+```bash
+git config cascadingdev.aiprovider "gemini-cli"
+git config cascadingdev.aicommand "gemini '{prompt}'"
+```
+
+### OpenAI Codex
+```bash
+git config cascadingdev.aiprovider "codex-cli"
+git config cascadingdev.aicommand "codex '{prompt}'"
+```
+
+### Custom AI Tool
+```bash
+# Use any command that accepts a prompt and returns JSON
+git config cascadingdev.aicommand "my-ai '{prompt}' --format json"
+```
+
+### Check Current Config
+```bash
+git config cascadingdev.aiprovider  # Defaults to: claude-cli
+git config cascadingdev.aicommand   # Defaults to: claude -p '{prompt}'
+```
+
+## File Structure
+
+```
+automation/
+├── workflow.py    # Main orchestrator (called by pre-commit hook)
+├── agents.py      # AI extraction agents
+├── summary.py     # Summary file formatter
+└── README.md      # This file
+```
+
+## How It Works
+
+1. **Pre-commit hook** triggers `workflow.py --status`
+2. **Finds staged** `.discussion.md` files
+3. **Phase 1**: Parses VOTE: lines → updates summary
+4. **Phase 2**: Calls AI agent → extracts questions/actions/decisions
+5. **Updates** corresponding `.sum.md` files
+6. **Auto-stages** updated summaries
+7. **Commit continues** (never blocks, always exits 0)
+
+## Vote Format
+
+```markdown
+- ParticipantName: Any comment. VOTE: READY|CHANGES|REJECT
+```
+
+**Rules:**
+- Latest vote per participant wins
+- Must follow `- Name: ...` bullet format
+- Case-insensitive: VOTE:, vote:, Vote:
+
+## Optional Markers (Help AI Extraction)
+
+```markdown
+Q: <question>              # Question
+A: <answer>                # Answer
+TODO: <task>               # Action item
+DONE: <completion>         # Completed task
+DECISION: <choice>         # Decision
+VOTE: READY|CHANGES|REJECT # Vote (REQUIRED)
+@Name, @all                # Mentions
+```
+
+## Testing
+
+```bash
+# Test vote parsing
+pytest tests/test_workflow.py -v
+
+# Manual test
+echo "- Test: Comment. VOTE: READY" >> Docs/features/test/discussions/test.discussion.md
+git add Docs/features/test/discussions/test.discussion.md
+git commit -m "Test"  # Automation runs
+```
+
+## Troubleshooting
+
+### No AI Processing
+```bash
+# Check if AI command works
+claude -p "Return JSON: {\"test\": true}"
+
+# Check git config
+git config --list | grep cascadingdev
+
+# Try environment variable
+CDEV_AI_COMMAND="claude -p '{prompt}'" git commit -m "test"
+```
+
+### Votes Not Updating
+- Ensure format: `- Name: text. VOTE: READY`
+- Check summary file has markers: `<!-- SUMMARY:VOTES START -->`
+- Look for warnings in commit output
+
+## Documentation
+
+- [AUTOMATION.md](../docs/AUTOMATION.md) - Complete system documentation
+- [DESIGN.md](../docs/DESIGN.md) - Overall architecture
+- [CLAUDE.md](../CLAUDE.md) - Guide for AI assistants