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 isFileTaskStore, which uses theaferolibrary 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:
- Workspace Overview: Start with
go_workspaceto understand the project structure. - Find Symbols: Use
go_searchwith a fuzzy query to locate types, functions, or variables. - File Context: After reading a Go file, immediately use
go_file_contextto understand its dependencies within the same package. - Package API: Use
go_package_apito understand the public API of any package (internal or third-party).
Editing Code:
- Understand First: Follow the reading workflow above before any modification.
- Find References: Before changing a symbol, you MUST use
go_symbol_referencesto find all its usages and assess the impact. - Make Edits: Perform all necessary code changes.
- Check for Errors: After every edit, you MUST run
go_diagnosticson the changed files. - Fix Errors: If
go_diagnosticsreports errors, fix them. Review and apply suggested quick fixes if they are correct. - Run Tests: Once
go_diagnosticsis clean, run the relevant tests usinggo test [packagePath...].
4. Critical Rules & Safety Guidelines
Non-negotiable rules for interacting with the task system:
- NEVER EDIT TASK FILES DIRECTLY: Do not write to, modify, or delete any file in the
.backlog/directory. All task manipulations MUST go through thebacklogCLI commands. Direct edits will corrupt metadata and break the system. - DO NOT DELETE TASK FILES: Never delete task markdown files. Use the
backlog archivecommand instead. - ALWAYS USE THE
backlogTOOL: For any operation related to task management (create, list, view, edit, search, archive), you MUST use thebacklogCLI tool.
5. Planning and Task Management (backlog)
FULLY READ THE INSTRUCTIONS FOR BACKLOG CLI 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 asslog.Info. - Dependency Injection: Business logic is implemented as methods on the
FileTaskStore. TheFileTaskStoreis created with anafero.Fsinstance, 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.mdfile 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.