Added clear implementation status tracking to DESIGN.md to show what's
currently working vs. what's planned.
Changes:
- Updated document version to v2.1
- Added "Implementation Status (2025-11-01)" section at top
- Created DESIGN.md.old backup for easy comparison
- Categorized features into: Implemented, In Progress, Planned
Current Status:
✅ Implemented: Stages 1-2, cascading rules, AI patch generation, voting
🚧 In Progress: Stage 3 (Design Discussion Gate) - being implemented now
📋 Planned: Stages 4-7, moderator protocol, bug sub-cycles
The three-stage workflow (Feature → Design → Implementation) was always
documented correctly in DESIGN.md. The current implementation just skips
the Design stage, which we're now fixing.
This status section will be updated as each milestone is completed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changed temp file location from /tmp to .git/ai-agents-temp/ to resolve
Claude CLI permission errors when reading discussion content.
Problem:
- agents.py created temp files in /tmp/tmp*.md
- Asked Claude CLI to read these files
- Claude CLI couldn't access /tmp without explicit permission grant
- Error: "I don't have permission to read that file"
- Fell back to basic pattern matching (degraded functionality)
Solution:
- Create temp files in .git/ai-agents-temp/ directory
- Claude CLI has permission to read files in the project directory
- Use PID for unique filenames to avoid conflicts
- Cleanup still handled by finally block
Benefits:
- No user configuration needed
- Claude CLI can now read discussion files
- AI agents work properly for structured extraction
- Temp files automatically gitignored (.git/ directory)
- Easy debugging (files visible in project)
The finally block at line 154-158 still cleans up temp files after use.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changed approach from disabling outputs to properly handling AI's decision
not to generate changes (e.g., gated outputs, conditional rules).
Changes:
1. patcher.py - Allow empty diffs
- sanitize_unified_patch() returns empty string instead of raising error
- generate_output() returns early for empty patches (silent skip)
- Common case: implementation_gate_writer when status != READY_FOR_IMPLEMENTATION
- AI can now return explanatory text without a diff (no error)
2. features.ai-rules.yml - Override README rule
- Add README.md → "readme_skip" association
- Creates empty rule to disable README updates in Docs/features/
- Prevents unnecessary AI calls during feature discussions
- README automation still works in root directory
3. root.ai-rules.yml - Restore default README rule
- Removed "enabled: false" flag (back to default enabled)
- Features directory overrides this with empty rule
Benefits:
- implementation_gate now calls AI but AI returns empty diff (as designed)
- No more "[runner] error generating ...implementation.discussion.md"
- No more "[runner] error generating README.md"
- Clean separation: AI decides vs. config disables
- Instructions to AI are still executed, AI just chooses no changes
Testing:
Setup completes cleanly with no [runner] errors. The automation
runs and AI correctly returns no diff for implementation file
when status is OPEN.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Disabled two outputs that were causing errors during first commit:
1. implementation_gate (features.ai-rules.yml)
- Was trying to generate implementation.discussion.md on every request.md commit
- Should only run when feature status = READY_FOR_IMPLEMENTATION
- Error: "Sanitized patch missing diff header"
- Fix: Set enabled: false by default
- Users can enable in project .ai-rules.yml when needed
2. readme normalizer (root.ai-rules.yml)
- Was trying to update README.md whenever policies.yml was staged
- Caused errors during initial commit
- Error: "Sanitized patch missing diff header"
- Fix: Set enabled: false by default
- Users can enable when they want AI to maintain README
Benefits:
- Clean setup with no [runner] errors
- Faster first commit (fewer AI calls)
- Users can enable features incrementally as needed
- Only essential automation runs by default (feature discussions)
Remaining warnings are expected:
- [agents] warnings: Claude CLI permission prompts (normal behavior)
- [summary] warnings: Template markers not found (handled gracefully)
Testing:
Setup now completes cleanly with only feature.discussion.md generated.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changed setup_project.py to only create request.md during setup, allowing
the pre-commit hook automation to generate discussion and summary files.
Problem (before):
- setup_project.py created request.md, feature.discussion.md, and .sum.md
- git commit staged ALL files and triggered pre-commit hook
- runner.py saw request.md and tried to generate feature.discussion.md
- But feature.discussion.md was already in the index → race condition
- workflow.py also tried to update .sum.md → more conflicts
Solution (now):
- setup_project.py creates ONLY request.md
- discussions/ directory is created but empty
- First commit triggers automation:
- runner.py sees request.md → generates feature.discussion.md (AI)
- ensure_summary in pre-commit hook → creates .sum.md from template
- workflow.py → updates .sum.md with vote data
- No more conflicts between setup and automation
Benefits:
1. No race condition - each file has one source of truth
2. Actually exercises the automation system on first commit
3. Generated files always match current automation rules
4. Simpler setup code (67 lines removed)
Testing:
The automation will now properly run on first commit instead of conflicting
with pre-seeded files.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Detect Claude API 500 Overloaded errors
- Continue processing other files on error instead of aborting
- Log errors to stderr for visibility
This allows commits to succeed even if some AI requests fail due to rate limiting.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Helps debugging by preserving raw AI output when markers are missing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Claude CLI returns exit code 1 even when successfully generating output.
Check for stdout content before failing on non-zero exit codes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix missing space after colon in features.ai-rules.yml
- Add tools/mock_ai.sh for testing automation without real AI
- Ensures installer has valid YAML templates
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add automation/README.md with:
- Quick start instructions for Phase 1 and Phase 2
- Configuration examples for all supported providers
- How it works explanation
- Vote format and optional markers
- Testing and troubleshooting sections
Provides a concise reference for users without needing to read full AUTOMATION.md.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major refactoring to support flexible AI provider configuration instead of
requiring direct API access. Users can now use whatever AI CLI tool they have
installed (claude, gemini, codex, etc.) without API keys.
## Changes to automation/agents.py
**New Functions:**
- `get_ai_config()` - Reads config from env vars or git config
- Environment: CDEV_AI_PROVIDER, CDEV_AI_COMMAND (highest priority)
- Git config: cascadingdev.aiprovider, cascadingdev.aicommand
- Default: claude-cli with "claude -p '{prompt}'"
- `call_ai_cli()` - Execute AI via CLI command
- Passes content via temp file to avoid shell escaping
- Supports {prompt} placeholder in command template
- 60s timeout with error handling
- Parses JSON from response (with/without code blocks)
- `call_ai_api()` - Direct API access (renamed from call_claude)
- Unchanged functionality
- Now used as fallback option
- `call_ai()` - Unified AI caller
- Try CLI first (if configured)
- Fall back to API (if ANTHROPIC_API_KEY set)
- Graceful failure with warnings
**Updated Functions:**
- `normalize_discussion()` - calls call_ai() instead of call_claude()
- `track_questions()` - calls call_ai() instead of call_claude()
- `track_action_items()` - calls call_ai() instead of call_claude()
- `track_decisions()` - calls call_ai() instead of call_claude()
**Configuration Precedence:**
1. Environment variables (session-scoped)
2. Git config (repo-scoped)
3. Defaults (claude-cli)
## Changes to docs/AUTOMATION.md
**Updated Sections:**
- "Requirements" - Now lists CLI as Option 1 (recommended), API as Option 2
- "Configuration" - Complete rewrite with 5 provider examples:
1. Claude CLI (default)
2. Gemini CLI
3. OpenAI Codex CLI
4. Direct API (Anthropic)
5. Custom AI command
- "Troubleshooting" - Added "AI command failed" section, updated error messages
**New Configuration Examples:**
```bash
# Claude Code (default)
git config cascadingdev.aicommand "claude -p '{prompt}'"
# Gemini
git config cascadingdev.aiprovider "gemini-cli"
git config cascadingdev.aicommand "gemini '{prompt}'"
# Custom
git config cascadingdev.aicommand "my-ai-tool --prompt '{prompt}' --format json"
```
## Benefits
1. **No API Key Required**: Use existing CLI tools (claude, gemini, etc.)
2. **Flexible Configuration**: Git config (persistent) or env vars (session)
3. **Provider Agnostic**: Works with any CLI that returns JSON
4. **Backward Compatible**: Still supports direct API if ANTHROPIC_API_KEY set
5. **User-Friendly**: Defaults to "claude -p" if available
## Testing
- ✅ get_ai_config() tests:
- Default: claude-cli with "claude -p '{prompt}'"
- Git config override: gemini-cli with "gemini '{prompt}'"
- Env var override: codex-cli with "codex '{prompt}'"
- ✅ extract_mentions() still works (no AI required)
- ✅ All 6 workflow tests pass
## Impact
Users with Claude Code installed can now use the automation without any
configuration - it just works! Same for users with gemini or codex CLIs.
Only requires git config setup if using non-default command.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Integration fixes to make workflow.py available in user projects:
1. Bundle automation/ directory in installer
- Add automation/ to build_installer.py copy process
- Ensures workflow.py is available in generated projects
- Pre-commit hook can now actually call workflow.py
2. Update pre-commit hook comment
- Change from "planned feature...does not yet exist"
- Update to "provides non-blocking vote status reporting"
- Accurately describes current implementation
Verified:
- automation/workflow.py present in install bundle
- workflow.py executes successfully from bundle
- Pre-commit hook comment matches reality
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major documentation improvements:
1. Add CLAUDE.md
- Comprehensive guide for AI assistants working in this repo
- Repository architecture and directory structure
- Common development commands and workflows
- Build system explanation
- Key concepts and design philosophy
2. Restructure DESIGN.md
- Clarify three directory contexts: CascadingDev Repo, Install Bundle, User Project
- Add clear section headers and visual separation
- Mark future/unimplemented features with 🚧 emoji
- Document undocumented wins: META system and Ramble providers
- Add comprehensive Ramble documentation (mock and claude providers)
- Document template META system with code examples
3. Fix setup_project.py
- Correct error message path (was scripts/hooks/pre-commit, now assets/hooks/pre-commit)
These changes address confusion between tooling source, distribution bundle, and
generated user projects while highlighting sophisticated features like the
self-describing template system and multi-provider Ramble GUI.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
rob