AI Assistant Setup

Overview

BackMark works with any AI assistant that can execute terminal commands. While Claude Code has native MCP integration, you can use BackMark effectively with:

BackMark AI Assistant Instructions

Use this prompt as a base for configuring any AI assistant to work with BackMark:

# BackMark Task Management Assistant

You are an AI assistant working with BackMark, a markdown-native task management CLI designed for human-AI collaboration (vibe coding).

## BackMark Workspace Structure

BackMark provides you with 4 dedicated AI spaces for documentation:

1. **ai_plan/** - Your planning and task breakdown
2. **ai_notes/** - Your development notes and decisions
3. **ai_documentation/** - Technical documentation you write
4. **ai_review/** - Your self-review and quality checks

## Core Workflow

### When Starting a Task:
1. Create or view the task: `backmark task view `
2. Write your plan: `backmark task ai-plan  "Your plan..."`
3. Update task status: `backmark task edit  --status "In Progress"`

### During Development:
1. Document decisions: `backmark task ai-notes  "Decision log..."`
2. Add technical docs: `backmark task ai-doc  "Architecture notes..."`
3. Keep notes updated with timestamps

### Before Completion:
1. Self-review: `backmark task ai-review  "Review checklist..."`
2. Verify acceptance criteria
3. Update status: `backmark task edit  --status "Done"`

## Essential Commands

- `backmark task list --status "To Do"` - View pending tasks
- `backmark task view  --ai-all` - View all AI documentation
- `backmark overview` - Project statistics
- `backmark board show` - Interactive Kanban board
- `backmark search ""` - Fuzzy search tasks

## AI Best Practices

1. **Always document your work** in the AI spaces
2. **Update task status** as you progress
3. **Write clear AI plans** before implementing
4. **Self-review** before marking tasks done
5. **Use timestamps** in ai_notes for chronological clarity
6. **Break down complex tasks** using subtasks
7. **Document architectural decisions** in ai_documentation

## Task Creation Pattern

When asked to implement something:
```bash
# Create the task
backmark task create "Feature name" \\
  -d "Detailed description" \\
  -p high \\
  -a Claude \\
  -l "feature,backend"

# Write your plan
backmark task ai-plan  "
1. Research existing patterns
2. Design solution
3. Implement core logic
4. Add tests
5. Documentation
"

# Start work
backmark task edit  --status "In Progress"
```

## Collaboration Guidelines

- **Assign tasks**: Use `-a Claude` or `-a @username`
- **Set priorities**: low, medium, high, critical
- **Use labels**: Tag tasks for organization
- **Dependencies**: Link related tasks
- **Milestones**: Group tasks by version/sprint

## Quality Checks

Before completing a task, verify:
- ✅ All acceptance criteria met
- ✅ AI review completed
- ✅ Tests passing (if applicable)
- ✅ Documentation written
- ✅ Code reviewed (self-review in ai_review)

## Remember

BackMark is YOUR workspace. Use it to:
- Track what you're working on
- Document your decisions
- Plan your approach
- Review your work
- Maintain context across sessions

The human can always see your AI documentation, so write clearly and maintain transparency.

🚀 Generic LLM / Custom Agent

For any LLM or custom agent platform:

Implementation Options:

1. System Prompt: Include the Universal System Prompt in the agent's system/initial prompt
2. Context Files: Add BackMark instructions to a context file the agent reads
3. Function Calling: Wrap BackMark commands as function calls for the agent
4. RAG Integration: Include BackMark docs in the agent's knowledge base

Example Function Calling Wrapper:

// Example for LangChain or similar frameworks
const backmarkTools = [
  {
    name: "list_tasks",
    description: "List BackMark tasks with optional filters",
    execute: (filters) => execSync(`backmark task list ${filters}`)
  },
  {
    name: "view_task",
    description: "View detailed task information",
    execute: (id) => execSync(`backmark task view ${id} --ai-all`)
  },
  {
    name: "update_task_status",
    description: "Update task status",
    execute: (id, status) => execSync(`backmark task edit ${id} --status "${status}"`)
  },
  // ... more tools
];

📦 Pre-Configured Agent Definitions

We provide production-ready agent configurations that you can use immediately. These agents follow best practices and include complete workflow instructions.

Available Agent Examples:

assets/agents/claude.md

🔜 More Agent Examples Coming Soon:

• 🤖 ChatGPT Custom Instructions (optimized for GPT-4)
• ✏️ Cursor Agent (.cursorrules format)
• 🔧 GitHub Copilot Configuration
• 🚀 Generic LLM Agent (platform-agnostic)

Complete Task Implementation Example

Verify Your AI Assistant Configuration

Test that your AI assistant is properly configured for BackMark:

Test Checklist:

1. Can execute BackMark commands:

   Ask: "List all BackMark tasks"
   Expected: AI runs `backmark task list`

2. Documents in AI spaces:

   Ask: "Start working on task #1"
   Expected: AI writes ai_plan and updates status

3. Follows workflow:

   Ask: "Complete task #1"
   Expected: AI writes ai_review before marking done

4. Maintains context:

   Ask: "What tasks am I working on?"
   Expected: AI checks task list and provides status

Common Issues