AI Workflow
Master the four AI spaces and automation features that make BackMark the perfect tool for AI collaboration.
The Four AI Spaces
BackMark provides four dedicated spaces where your AI assistant can work autonomously while maintaining complete transparency and documentation.
1. ai_plan
Purpose: Implementation strategy and architecture
When: Before starting work
Content: Steps, files, dependencies, technical approach
2. ai_notes
Purpose: Real-time development log
When: During implementation
Content: Progress, decisions, issues, solutions (timestamped)
3. ai_documentation
Purpose: End-user and developer docs
When: As features are built
Content: API docs, usage examples, configuration
4. ai_review
Purpose: Self-review and quality checks
When: Before marking complete
Content: Completeness checklist, metrics, questions
📋 ai_plan - Implementation Planning
What Goes in ai_plan?
- ✅ Implementation steps - Ordered list of what to build
- ✅ Files to create/modify - Complete file list with purpose
- ✅ Dependencies - Libraries, tools, services needed
- ✅ Technical approach - Architecture decisions and patterns
- ✅ Potential challenges - Known risks and mitigation strategies
Command:
backmark task ai-plan <task-id> "Plan content in Markdown"Example:
$ backmark task ai-plan 42 "## Implementation Steps
1. **Setup Fuse.js library**
- Install: \`npm install fuse.js\`
- Configure search options (threshold, keys)
2. **Create search utility**
- File: src/utils/fuzzy-search.js
- Wrapper around Fuse.js with project-specific config
3. **Integrate into task list command**
- Modify: src/commands/task/list.js
- Add --search flag
4. **Add tests**
- File: tests/fuzzy-search.test.js
- Test accuracy, performance, edge cases
## Files to Create/Modify
- \`src/utils/fuzzy-search.js\` (new) - Search utility
- \`src/commands/task/list.js\` (modify) - Integration
- \`tests/fuzzy-search.test.js\` (new) - Tests
- \`package.json\` (modify) - Add dependency
## Dependencies
- fuse.js@^7.0.0
## Technical Approach
Using Fuse.js for fuzzy search because:
- Mature, well-tested library
- Configurable threshold
- Works with complex objects
- No additional dependencies
Search will index: title, description, labels, assignees
## Potential Challenges
- Performance with 1000+ tasks → Mitigate with LokiJS indexing
- Search relevance tuning → Start with threshold 0.3, adjust based on usage"
✓ Added AI plan to task #42
📝 ai_notes - Development Log
What Goes in ai_notes?
- ✅ Timestamped entries - When each step was completed
- ✅ Progress updates - What was accomplished
- ✅ Decisions made - Choices and reasoning
- ✅ Problems encountered - Issues that arose
- ✅ Solutions applied - How problems were resolved
- ✅ Deviations from plan - Changes to original approach
Command:
backmark task ai-note <task-id> "Note content with timestamp"Example:
$ backmark task ai-note 42 "**2024-11-06 10:00** - Installed fuse.js
Successfully added to package.json and ran npm install.
Version: 7.0.0
**2024-11-06 10:30** - Created fuzzy-search utility
Implemented in src/utils/fuzzy-search.js
Configuration: threshold 0.3, searches title/description/labels
**2024-11-06 11:00** - Integrated into task list
Added --search flag to task list command
Works as expected in manual testing
**2024-11-06 11:30** - Issue: Performance degradation
Search taking ~500ms with 500+ tasks
Solution: Added caching layer, now ~20ms average
**2024-11-06 12:00** - Tests complete
Added 8 test cases, all passing
Coverage: 95% of search utility"
✓ Added AI note to task #42
Pro Tip: Always include timestamps for better context recovery.
📚 ai_documentation - User Documentation
What Goes in ai_documentation?
- ✅ API documentation - Function signatures, parameters, returns
- ✅ Usage examples - Real code examples
- ✅ Configuration options - Available settings
- ✅ Integration guides - How to use with existing code
- ✅ Troubleshooting - Common issues and solutions
Command:
backmark task ai-doc <task-id> "Documentation in Markdown"Example:
$ backmark task ai-doc 42 "## Fuzzy Search Feature
### Usage
Search tasks by any keyword:
\`\`\`bash
backmark task list --search \"authentication\"
\`\`\`
### How it Works
Fuzzy search indexes:
- Task title
- Task description
- Labels
- Assignees
### Configuration
Adjust search threshold in config.yml:
\`\`\`yaml
search:
threshold: 0.3 # Lower = stricter (0.0-1.0)
maxResults: 50
\`\`\`
### Examples
\`\`\`bash
# Find all auth-related tasks
backmark task list --search \"auth\"
# Combine with filters
backmark task list --search \"api\" --status \"In Progress\"
\`\`\`
### Performance
- Average query time: ~20ms
- Handles 1000+ tasks efficiently
- Results cached automatically"
✓ Added AI documentation to task #42
✅ ai_review - Self-Review
What Goes in ai_review?
- ✅ Completeness checklist - All requirements met
- ✅ Tests performed - What was tested and results
- ✅ Quality metrics - Coverage, performance, etc.
- ✅ Code quality - Standards followed, refactorings done
- ✅ Documentation status - What docs were created
- ✅ Known limitations - Current constraints
- ✅ Questions for human - Items needing validation
Command:
backmark task ai-review <task-id> "Review content"Example:
$ backmark task ai-review 42 "## Self Review
### Completeness Checklist
✅ Fuse.js integration complete
✅ Search command working
✅ Tests written and passing
✅ Documentation complete
✅ Performance optimized
### Tests Performed
- Unit tests: 8/8 passing
- Integration tests: 3/3 passing
- Manual testing: Verified with 500+ task dataset
- Edge cases: Empty queries, special characters - all handled
### Quality Metrics
- Test coverage: 95%
- Average search time: 20ms
- Memory usage: +2MB (acceptable)
- No new dependencies beyond fuse.js
### Code Quality
- ESLint: No warnings
- TypeScript: No type errors
- Followed project conventions
- Added JSDoc comments
### Documentation
✅ API documentation complete
✅ Usage examples provided
✅ Configuration documented
✅ Troubleshooting section added
### Known Limitations
- Search threshold not auto-tuned (manual config)
- Multi-language support not implemented (future enhancement)
### Questions for Human Review
1. Is the default threshold of 0.3 appropriate?
2. Should we add search result highlighting?
3. Any additional fields to index (e.g., milestone)?
### Recommendation
Task is ready for completion. All acceptance criteria met."
✓ Added AI review to task #42
🤖 AI Automation Features
BackMark includes intelligent automation to streamline your workflow:
ai-breakdown
Automatically decompose complex tasks into logical subtasks with dependencies.
backmark task ai-breakdown 42Analyzes task description and creates subtasks based on implementation patterns, technical keywords, and common workflows.
ai-estimate
Estimate task complexity, duration, and risks using heuristic analysis.
backmark task ai-estimate 42Provides complexity rating (low/medium/high/critical), estimated duration, risk factors, and confidence level.
ai-review-ready
Validate task is ready to be marked complete with 8-point checklist.
backmark task ai-review-ready 42Checks subtasks, dependencies, blockers, acceptance criteria, AI review, and more before allowing completion.
👀 Viewing AI Content
View All AI Sections at Once
backmark task view <task-id> --ai-allThis displays:
- Task metadata (title, status, priority, etc.)
- Task description
- AI Plan section
- AI Notes section
- AI Documentation section
- AI Review section
- Acceptance criteria
- Changelog
View Specific Sections
# Just the plan
backmark task view 42 --ai-plan
# Just the notes
backmark task view 42 --ai-notes
# Just the docs
backmark task view 42 --ai-doc
# Just the review
backmark task view 42 --ai-reviewEdit Task Files Directly
Since tasks are Markdown files, you can edit them directly:
# Open in your editor
vim backlog/tasks/42.md
code backlog/tasks/42.md
nano backlog/tasks/42.mdChanges are reflected immediately!
🎯 Best Practices
For AI Planning:
- ✅ Be specific about implementation steps
- ✅ List all files that will be touched
- ✅ Identify dependencies early
- ✅ Consider edge cases and risks
- ✅ Update plan if approach changes
For AI Notes:
- ✅ Always include timestamps
- ✅ Document decisions with reasoning
- ✅ Log problems AND solutions
- ✅ Note deviations from plan
- ✅ Keep entries concise but complete
For AI Documentation:
- ✅ Write for future readers
- ✅ Include real code examples
- ✅ Document configuration options
- ✅ Add troubleshooting tips
- ✅ Keep it up-to-date
For AI Review:
- ✅ Be honest about limitations
- ✅ Report actual test results
- ✅ Ask questions when uncertain
- ✅ Suggest improvements
- ✅ Provide clear recommendation