Backlog Manager

Responsibilities

The BacklogManager module keeps a structured backlog on disk, supports updates to task descriptions and options, approves a task by writing a resolution, and moves completed work into history.

• Load and create backlog files for a given backlog path.
• Manage tasks by adding new tasks or updating existing ones.
• Approve tasks by recording a resolution and clearing pending options.
• Archive work by moving resolved tasks into history.

Backlog File Shape

Each backlog file contains tasks plus a history archive:

{
  "tasks": [
    {
      "description": "Write onboarding email",
      "options": ["Option A", "Option B"],
      "resolution": ""
    }
  ],
  "history": [
    {
      "description": "Draft release notes",
      "options": [],
      "resolution": "Published on the product blog."
    }
  ]
}

Public API

loadBacklog(filePath)

Loads the backlog file and returns tasks, history, and file metadata.

• Parameters: filePath - Absolute or relative path to a backlog file.
• Returns: { tasks, history, meta } where meta includes mtime and size.

createBacklog(filePath)

Creates an empty backlog file on disk.

• Parameters: filePath
• Returns: Promise that resolves after file creation.

getTask(filePath, taskIndex)

Fetches a specific task by 1-based index.

• Parameters: filePath, taskIndex (1-based)
• Returns: Task object or null if missing.

addTask(filePath, initialContent)

Adds a new task with empty options and resolution.

• Parameters: filePath, initialContent (string)
• Returns: New task index (1-based).

addTasksFromText(filePath, text)

Splits a numbered list into multiple tasks.

• Parameters: filePath, text (numbered list)
• Returns: Array of created task indices.

addOptionsFromText(filePath, taskIndex, text)

Parses a numbered list and appends each option to a task.

• Parameters: filePath, taskIndex, text
• Returns: Updated task or null if missing.

approveTask(filePath, taskIndex, resolution)

Stores the chosen resolution and clears any pending options.

• Parameters: filePath, taskIndex, resolution (string)
• Returns: Updated task or null if missing.

getApprovedTasks(filePath)

Returns tasks with a non-empty resolution.

• Parameters: filePath
• Returns: Array of approved tasks with their 1-based index.

getNewTasks(filePath)

Returns tasks that are in the backlog, including empty-resolution tasks.

• Parameters: filePath
• Returns: Array of tasks with their 1-based index.

updateTask(filePath, taskIndex, updates)

Applies partial updates to a task and normalises option/resolution values.

• Parameters: filePath, taskIndex, updates
• Returns: Promise that resolves after saving.

markDone(filePath, taskIndex)

Moves a task into history with a resolution fallback.

• Parameters: filePath, taskIndex
• Returns: The new history entry or null.

saveBacklog(filePath, data)

Saves a fully formed backlog payload to disk.

• Parameters: filePath, data
• Returns: Promise that resolves after saving.

flush(filePath)

Forces a flush of the backlog file using the backing IO helper.

• Parameters: filePath
• Returns: Promise that resolves after the flush.

Usage Example

import {
  createBacklog,
  addTask,
  addOptionsFromText,
  approveTask,
  markDone
} from 'achillesAgentLib/BacklogManager';

await createBacklog('./docs_backlog.backlog');
const index = await addTask('./docs_backlog.backlog', 'Draft new onboarding guide');
await addOptionsFromText('./docs_backlog.backlog', index, '1) Publish this week\n2) Hold for review');
await approveTask('./docs_backlog.backlog', index, 'Publish this week');
await markDone('./docs_backlog.backlog', index);

Related Guides

• Orchestration Skills for managing multi-step workflows.
• Agent Runtime for execution context and session handling.
• LightSOPLang for script-based planning.