Issue-based workflow for AI-assisted development across sessions and branches
✨ Issue-Based Workflow - Each task gets its own folder with complete context 🎯 Bounded File Sizes - Global files stay small, execution details in issues 🚫 No Merge Conflicts - Issue folders are branch-specific 🤖 Multi-Agent Support - Single config for Claude/Gemini/Qwen ✅ Quality Gates - Built-in QA workflow
See MIGRATION-GUIDE.md for step-by-step instructions.
When working with AI agents across multiple sessions:
- ❌ Context is lost between sessions
- ❌ Planning files grow unbounded
- ❌ Feature branches conflict on shared planning docs
- ❌ No structured way to track features/bugs
Planning Framework v2.0 uses an issue-based workflow:
- ✅ Each task in its own issue folder
- ✅ Complete context (prompt, analysis, plan, progress)
- ✅ Global files stay minimal (roadmap only)
- ✅ Zero merge conflicts (branch-specific issues)
- ✅ Multi-agent support (Claude Code, Gemini CLI, Qwen Code)
# 1. Clone planning framework
git clone https://github.com/[your-org]/planning-framework
cd planning-framework
# 2. Run interactive setup
./scripts/setup-planning-v2.sh
# Follow prompts: project name, issue types, QA requirements
# 3. Commit the framework
git add .
git commit -m "Setup Planning Framework v2.0"
# 4. Create first issue
# Ask your AI agent: "Create an issue to [add feature]"# Migrate from v1.0 to v2.0
./scripts/migrate-v1-to-v2.sh
# Backs up v1.0, creates v2.0 structure, generates reportSee QUICKSTART.md for complete 5-minute guide.
USER REQUEST → CREATE ISSUE → ANALYZE → PLAN → IMPLEMENT → QA → CLOSE
your-project/
├── PLANNING.md # Framework config
├── .qa-workflow.md # QA requirements
│
├── docs/
│ ├── issues/
│ │ ├── open/ # Active work
│ │ │ └── 20240127-feat-add-auth/
│ │ │ ├── prompt.md # Original request
│ │ │ ├── analysis.md # Understanding
│ │ │ ├── implementation-plan.md # Tasks
│ │ │ └── session-log.md # Progress
│ │ │
│ │ └── closed/ # Completed (archived)
│ │
│ └── planning/
│ ├── implementation-plan.md # Roadmap (stays small!)
│ ├── session-log.md # Timeline
│ └── decisions.md # Decisions
Session Start:
- Read
PLANNING.md- Framework instructions - Read issue files - Context for current task
- Read global
decisions.md- Architectural choices
During Work:
- Focus on ONE issue per session
- Update progress in
session-log.md - Check off tasks in
implementation-plan.md
Before Closing:
- Run QA workflow (
.qa-workflow.md) - Get user confirmation
- Merge and archive issue
Format: YYYYMMDD-{type}-{slug}
Example: 20240127-feat-add-authentication
- Date ensures uniqueness across branches
- Type visible at glance (feat/bug/improve)
- Slug provides readability
One branch per issue: issue/YYYYMMDD-{type}-{slug}
- 1:1 mapping with issue folder
- Clean isolation, no conflicts
implementation-plan.md - Roadmap + active issues session-log.md - One-line entries when issues close decisions.md - Architectural decisions
Details live in issue folders, not global files.
.qa-workflow.md defines gates before closing:
- Linting/formatting
- Tests (existing + new)
- Documentation
- Security review
- 📖 Complete Guide - Full documentation
- ⚡ Quick Start - 5-minute setup
- 🔄 Migration Guide - v1.0 → v2.0
- 📁 Templates - All templates
Works with:
- Claude Code - Anthropic's CLI tool
- Gemini CLI - Google's CLI tool
- Qwen Code - Qwen's CLI tool
- Any AI agent - Generic instructions
Single PLANNING.md for all agents.
Session logs track which agent did what:
[Claude Code] ✓ [issue-id](link) - Description
[Gemini CLI] 2024-01-28: Ad-hoc work
Setup:
./scripts/setup-planning-v2.sh # Interactive setupMigration:
./scripts/migrate-v1-to-v2.sh # Migrate from v1.0Helpers:
./scripts/create-issue.sh # Manual issue creation
./scripts/close-issue.sh # Issue closure automationAll scripts:
- Interactive prompts
- Colorized output
- Error handling
- Comprehensive help
✅ Zero context loss - Pick up exactly where you left off ✅ Clear progress - Visual tracking with checkboxes ✅ Isolated work - Issues don't interfere with each other ✅ No conflicts - Branch-specific planning files
✅ Focused context - Read only relevant issue ✅ Clear workflow - 6-phase lifecycle ✅ Consistent behavior - Follows documented patterns ✅ Reduced tokens - Small files, not 1000s of lines
✅ Parallel development - No merge conflicts ✅ Issue tracking - Built-in feature/bug management ✅ Quality gates - QA workflow before merging ✅ Decision history - Architectural choices documented
Planning Framework v2.0 was built using itself (dogfooding):
- Issue:
20240127-feat-implement-v2 - 6 phases: Bootstrap, Templates, Scripts, Documentation, Self-Migration, Testing
- 51 tasks: Tracked in implementation-plan.md
- Progress: Updated after each session
- Result: Working v2.0 framework! 🎉
Default: feat, bug, improve
Add more in PLANNING.md:
- `refactor` - Code restructuring
- `docs` - Documentation only
- `test` - Testing improvements
- `chore` - Maintenance tasksCustomize .qa-workflow.md:
### Project-Specific
- [ ] Performance: API response < 100ms
- [ ] Security: No SQL injection risks
- [ ] Accessibility: WCAG AA compliant- Multi-session projects (days/weeks/months)
- AI-assisted development
- Multiple feature branches
- Complex projects with many decisions
- Team collaboration
- Single-session prototypes
- Trivial scripts (<100 LOC)
- Well-defined, simple tasks
| Feature | v1.0 | v2.0 |
|---|---|---|
| Work tracking | Global files | Issue folders |
| File growth | Unbounded | Bounded (roadmap only) |
| Merge conflicts | Yes (planning docs) | No (branch-specific) |
| Multi-agent | Separate configs | Single PLANNING.md |
| Issue tracking | Manual | Built-in workflow |
| QA gates | None | .qa-workflow.md |
Contributions welcome! Areas:
- ✨ Additional templates
- 🔧 Platform-specific improvements
- 📚 Integration examples
- 🎨 Domain-specific variations
- 📖 Real-world examples
See CONTRIBUTING.md for guidelines.
- 📖 Documentation: FRAMEWORK.md
- ⚡ Quick Help: QUICKSTART.md
- 🔄 Migration: MIGRATION-GUIDE.md
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
MIT License - Use freely in any project. See LICENSE for details.
Created by: Human + Claude collaboration Inspired by: Need for better context preservation in AI-assisted development Built with: Planning Framework v2.0 (dogfooding!)
-
v2.0.0 (2024-01-27) - Issue-Based Workflow
- 🎯 Issue-based workflow (each task in its own folder)
- 📏 Bounded file sizes (global files stay small)
- 🚫 No merge conflicts (branch-specific issues)
- 🤖 Multi-agent support (single PLANNING.md)
- ✅ Built-in QA workflow
- 🔧 Automation scripts (setup, migration, helpers)
- 📖 Comprehensive documentation
- See CHANGELOG.md for details
-
v1.1.0 (2024-11-12) - Time Estimation Removal
- Remove time estimation fields
- Update templates and documentation
-
v1.0.0 (2024-11-05) - Initial Release
- Core templates (PRD, Implementation Plan, Session Log, Decisions)
- Setup scripts
- CLAUDE.md integration
Star this repo if it helps your project! ⭐
Planning Framework v2.0 - Build better with AI assistance 🚀