1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108# AI Agent Instructions for the `backlog` Repository
This document provides a comprehensive and unified set of instructions for AI agents working on this project.
## 1. Project Overview
- **Project Name**: `backlog`
- **Description**: A Go-based, offline-first, portable task management CLI that stores tasks as Markdown files within a Git repository.
- **Key Feature**: Designed for seamless integration with AI agents via CLI commands.
---
## 2. Core Architecture & Concepts
To work effectively, you must understand these core components:
- **`Task`**: The fundamental data unit. A task is a Markdown file with YAML frontmatter.
- **`TaskStore`**: The storage abstraction layer. The primary implementation is `FileTaskStore`, which uses the `afero` library for filesystem operations (allowing for in-memory mocking in tests).
- **`TaskID`**: A hierarchical, dot-notation identifier (e.g., `T01`, `T01.01`). IDs are auto-generated and should be treated as immutable.
- **Storage Location**: All task files are stored in the `.backlog/` directory.
- **File Naming**: Task files follow the convention: `T{ID}-{slugified-title}.md`.
- **Directory Structure**:
- `internal/core/`: Contains all core business logic (creating, listing, updating tasks).
- `internal/cmd/`: Defines the CLI commands using the Cobra framework.
- `internal/commit/`: Handles automatic Git integration.
- `internal/mcp/`: Implements the MCP server for AI agent tool-based interaction.
- `internal/logging/`: Logging for this project.
---
## 3. Development Workflow
Follow these steps for reading, analyzing, and editing code.
### 3.1. Standard Build & Test Commands
Use `make` for simplicity.
- **Build**: `make build`
- **Run all tests**: `make test`
- **Run tests for a specific package**: `go test ./internal/core`
- **Lint**: `make lint`
- **Generate Docs**: `make docs`
- **Install**: `make install`
### 3.2. Go-Specific Analysis & Editing Workflow (`gopls`)
You MUST use the `gopls` tools for code intelligence.
**Reading & Understanding Code:**
1. **Workspace Overview**: Start with `go_workspace` to understand the project structure.
2. **Find Symbols**: Use `go_search` with a fuzzy query to locate types, functions, or variables.
3. **File Context**: After reading a Go file, immediately use `go_file_context` to understand its dependencies within the same package.
4. **Package API**: Use `go_package_api` to understand the public API of any package (internal or third-party).
**Editing Code:**
1. **Understand First**: Follow the reading workflow above before any modification.
2. **Find References**: Before changing a symbol, you MUST use `go_symbol_references` to find all its usages and assess the impact.
3. **Make Edits**: Perform all necessary code changes.
4. **Check for Errors**: After every edit, you MUST run `go_diagnostics` on the changed files.
5. **Fix Errors**: If `go_diagnostics` reports errors, fix them. Review and apply suggested quick fixes if they are correct.
6. **Run Tests**: Once `go_diagnostics` is clean, run the relevant tests using `go test [packagePath...]`.
---
## 4. Critical Rules & Safety Guidelines
**Non-negotiable rules for interacting with the task system:**
1. **NEVER EDIT TASK FILES DIRECTLY**: Do not write to, modify, or delete any file in the `.backlog/` directory. All task manipulations MUST go through the `backlog` CLI commands. Direct edits will corrupt metadata and break the system.
2. **DO NOT DELETE TASK FILES**: Never delete task markdown files. Use the `backlog archive` command instead.
3. **ALWAYS USE THE `backlog` TOOL**: For any operation related to task management (create, list, view, edit, search, archive), you MUST use the `backlog` CLI tool.
---
## 5. Planning and Task Management (`backlog`)
FULLY READ THE INSTRUCTIONS FOR BACKLOG CLI [prompt-cli.md](./internal/mcp/prompt-cli.md)
---
## 6. Code Style & Architectural Patterns
- **Error Handling**: Wrap errors with context using `fmt.Errorf("context: %w", err)`.
- **CLI Output**: In CLI command functions, use `logging.Info(msg, "key", "value", ...)` which has the same interface as `slog.Info`.
- **Dependency Injection**: Business logic is implemented as methods on the `FileTaskStore`. The `FileTaskStore` is created with an `afero.Fs` instance, allowing for dependency injection.
- **TaskID Parsing**: Always use `core.ParseTaskID()` to handle user-provided task IDs, as it supports flexible formats (e.g., "T1.2", "1.2").
- **Testing**: Use `afero.NewMemMapFs()` to create an in-memory filesystem for tests.
- **Git Integration**: Task operations trigger automatic Git commits. Ensure the repository is a valid Git repository.
---
## 7. AI Agent
### 7.1. Specialist Agents
- **`go-task-manager-reviewer`**: An expert agent for reviewing Go code related to this project.
- **When to use**: Use this agent when you need an expert review of new features, architectural changes, or refactoring, especially concerning task management logic, storage, or CLI commands.
---
## 8. Documentation
- **Primary Source of Truth**: The `README.md` file is the main source of truth for project setup, usage, and high-level concepts.
- **Generated Docs**: The `docs/` directory contains documentation generated from the source code and other resources. Refer to these for detailed information on CLI commands and other aspects of the project.