backlog-manager

name	backlog-manager
description	Manage an engineering backlog for humans and AI agents: review the whole loop, classify issues, improve issue quality, sync pull-request state, and label safe tickets so AI agents know what work they can pick up. Use when GitHub Issues, GitHub Projects, Linear, or an explicit local backlog path is the source of truth.
user-invocable	true
argument-hint	<dry-run|apply> backlog for <GitHub repo|GitHub Project URL|Linear board|local path>

Backlog Manager

Manage an engineering backlog for humans and AI agents.

Think of this skill as a lightweight product manager for the backlog. The goal is to keep engineering work clear, sequenced, classified, and safe to route to either humans or AI agents. A core job is to label safe, well-scoped tickets so AI agents know which work they are allowed to pick up, while marking ambiguous, oversized, or judgement-heavy work for humans. This is backlog review and project-state hygiene, not implementation. It labels issues, improves issue quality, identifies missing follow-up tickets, creates evidence-backed maintenance tickets when allowed, and syncs issue state with linked pull requests.

Default to dry-run. Only mutate GitHub, Linear, or another tracker when the user explicitly asks for apply.

When running unattended (scheduled or non-interactive), never wait for user input. Record any blocker or missing setup in the final report and exit.

When a tracker has workflow/status fields, keep status in sync with the issue/PR lifecycle. Labels answer "who may pick this up"; statuses answer "where is it in the workflow." Do not use labels as a substitute for an available project/status field.

Jobs To Be Done

This is one umbrella skill: Engineering Backlog Manager. Keep the recurring loop in one skill because the jobs share the same source of truth, labels, state model, and report. Split into separate skills only when a job needs a different toolchain or safety policy.

Run the whole workflow by default rather than asking the user to orchestrate several tiny modes. The workflow has three simple phases:

1. Triage the backlog — inspect open issues, current labels, stale state, linked PRs, and recent tracker changes.
2. Prepare the queue — classify issues by estimate/type, mark safe work as agent:ready, route judgement-heavy work to needs:human, and add/update Agent Assessments.
3. Maintain and report — sync clearly completed issues from PR evidence, propose or create evidence-backed maintenance tickets, report branch cleanup candidates, verify the result, and summarize the next human decision.

The skill is not a coding agent. Its main output is a clean backlog and a safe queue that a separate execution loop can consume.

Backlog Source Contract

Use exactly one backlog source of truth per run. Do not merge competing local and remote backlogs.

Supported sources:

• GitHub Issues for a named repo, using an installed and authenticated gh CLI.
• GitHub Projects when the user provides the project URL/path and gh can access it.
• Linear when the user provides the team/project/board path and a Linear connector is available.
• Explicit local backlog path only when the user provides that path and says it is the source of truth.

Default to Linear when a Linear connector/tool is available and the workspace context can resolve a team, project, or board. If Linear is unavailable or cannot be resolved, fall back to GitHub Issues when the current repository has a GitHub remote and gh is installed and authenticated. If neither Linear nor GitHub Issues can be resolved, stop and report the missing prerequisite instead of falling back to local planning files.

If the user does not name a tracker and no Linear source can be resolved, ask for the backlog path/URL. Examples: a Linear board, a GitHub Project, a GitHub repo, or an explicit local backlog file.

Local roadmap files, ticket files, planning docs, and README sections are context only unless the user explicitly says they are the backlog source. Treat divergence between those files and the tracker as quality drift to report or fix, not as a second backlog to reconcile by default.

Labels

Use this small fixed label set. Do not invent extra labels unless the user asks.

The skill owns only the labels listed below. Existing tracker labels such as bug, enhancement, documentation, exploration, good first issue, or team-specific labels should be left alone unless the user explicitly asks to normalize or remove legacy labels.

Managed labels are additive by default. Trackers do not record who added a label, so treat every existing managed label as if a human set it deliberately. Never remove or change an existing estimate:*, type:*, agent:ready, or needs:human label during classification; only add managed labels that are missing. The single exception is PR-evidence sync (Step 5), where agent:ready is removed because the work is demonstrably in progress or finished. If a run disagrees with an existing label, keep the label and raise the disagreement in the run report instead.

Estimation

• estimate:small - Small, bounded work suitable for agent execution when the issue is also agent:ready.
• estimate:medium - Moderately scoped work that may become agent-suitable with more confidence or human review.
• estimate:large - Large or broad work that should be human-led unless explicitly broken down.

Type

• type:bug - Incorrect behavior or regression.
• type:feature - New user-facing or developer-facing capability.
• type:docs - Documentation, examples, README, comments, broken links, or written guidance.
• type:test - Test additions, test fixes, coverage, fixtures, or test reliability.
• type:refactor - Internal restructuring without intended behavior change.
• type:chore - Maintenance such as dependency upgrades, build scripts, CI config, formatting, package metadata, repo cleanup, or tool configuration.

Routing

These labels are the machine-readable handoff contract. Keep routing labels deliberately small:

• agent:ready - Permission for an AI agent execution loop to pick up the issue.
• needs:human - A human decision, clarification, or judgement call is required.

Do not add extra routing labels by default. Use GitHub issue/PR state for completion and review state instead of labels like agent:complete or agent:blocked. If an unlabeled issue cannot be safely progressed, add needs:human with a specific question. If the issue already carries agent:ready, leave the label in place and raise the concern in the run report instead of removing it.

If a repository already has a completion/routing convention such as agent:complete or agent:blocked, respect it only when the user asks this skill to sync that convention or when the repo docs clearly define it. Do not create those labels from this skill unless explicitly requested.

Estimation And Routing Rules

Use a simple contract. The execution loop should be able to query agent:ready and trust that the issue is safe to attempt without re-litigating product judgement.

agent:ready

Only add agent:ready when all are true:

• estimate is estimate:small
• scope is clear
• the work is small enough for one pull request
• expected output is clear
• likely verification is known
• no product, UX, architecture, security, data, billing, auth, or deployment judgement is required
• the issue is not already linked to active work

Good small examples:

• docs updates
• broken links
• stale README commands
• simple test additions
• lint or formatting fixes
• small repo chores
• simple CI command/config drift
• patch dependency upgrades with passing tests

needs:human

Add needs:human when any are true:

• requirements are ambiguous
• expected behavior is unclear
• a reproduction is missing for a real bug
• the issue is too large for one pull request
• the issue needs product, UX, architecture, security, data, billing, auth, or deployment judgement
• the agent cannot classify the issue with confidence
• a previous agent attempt failed and the next step is unclear

Estimate levels

Use estimate:small for small, bounded changes with clear verification and low blast radius.

Use estimate:medium when the change may be agent-suitable later, but needs more confidence, stronger tests, or close human review. Do not mark medium-estimate issues agent:ready unless the user explicitly asks this workflow to include medium-estimate work.

Use estimate:large when the issue is too broad for one safe agent pull request or could require meaningful product, security, operational, or data judgement. Add needs:human to large-estimate issues unless they are already clearly human-owned.

Agent Assessment

Put reasoning in the issue body or a comment instead of creating more labels.

Only write or rewrite the assessment when the classification, reasoning, or plan has actually changed. Rewriting identical assessments on every run spams notifications.

Add or update this block:

## Agent Assessment

Estimate: small | medium | large
Type: bug | feature | docs | test | refactor | chore
Agent-ready: yes | no

Reason:
<1-3 sentences explaining the classification.>

Suggested plan:
1. <small first step>
2. <small second step>
3. <verification step>

If human input is needed, include:

Human needed:
<specific question or decision required before an agent can execute.>

Workflow

Think of the backlog manager as a repeatable product-management operating loop, not a one-shot labelling tool.

Each run should review the whole backlog loop against the selected source of truth: load context, resolve the backlog source, check labels, classify open issues for human/agent routing, sync clearly completed issues from pull-request evidence, sweep for evidence-backed quality drift, create or propose missing tickets according to the run mode, report branch cleanup candidates, verify tracker state, and report. Clearly state which steps were dry-run versus applied.

Step 1 — Load Context

Read repository or workspace instructions first:

• AGENTS.md
• CLAUDE.md
• README files
• contribution/development docs
• issue templates
• local roadmap/backlog docs only as context, unless the user explicitly provides one as the backlog source

Use this context to classify estimate and write issue assessments. Do not make up project policy.

If repo docs disagree with the selected backlog source, treat that as quality drift. Do not let local roadmap or ticket files override GitHub Issues, GitHub Projects, or Linear unless the user explicitly made the local path authoritative.

Step 2 — Resolve Backlog Source

Use the backlog source the user names.

Otherwise:

• Use Linear first when a Linear connector/tool is available and the workspace context can resolve a team, project, or board.
• Use GitHub Issues only when gh is installed, authenticated, and the current directory has a GitHub remote.
• Use GitHub Projects only when the user provides a project URL/path and gh can access it.
• Use a local backlog file only when the user explicitly provides the file path and says it is the source of truth.
• If no backlog source can be resolved, stop and ask for the backlog path/URL or the missing setup.

Do not infer a Linear board, GitHub Project, or local backlog from vague references. Divergent branches or planning docs are context for the product-manager review, not independent backlog sources.

When the user names a GitHub Project or confirms one during the run, load its fields and record the status option IDs before mutating anything. Common mappings are:

• Todo for open unstarted issues.
• In Progress for issues currently owned by a worker or active branch.
• In Review for issues with an open PR ready for review.
• Done for issues closed by a merged PR.

Use existing option names even when they differ slightly. Do not create project fields or statuses unless the user explicitly asks.

Step 3 — Ensure Labels Exist

In dry-run, report missing labels.

In apply, create missing labels where the tracker supports it.

Recommended GitHub colors:

• estimate:small - 0E8A16
• estimate:medium - FBCA04
• estimate:large - B60205
• type:* - 5319E7
• agent:* - 1D76DB
• needs:human - D93F0B

Step 4 — Classify Open Issues

Fetch open issues with title, body, labels, comments, status/project fields when available, and linked pull requests when the tracker exposes them.

Classification fills gaps; it never overrides existing managed labels.

For each open issue:

1. If it has no managed estimate:* label, assign exactly one.
2. If it has no managed type:* label, assign exactly one.
3. If it has no routing label, decide whether to add agent:ready, needs:human, or neither.
4. Never remove or change managed labels that are already present. If the classification disagrees with an existing label, keep the label and note the disagreement in the run report.
5. Add or update the Agent Assessment only if it changed.
6. Avoid marking an issue agent:ready when confidence is low. Use needs:human and explain why.

Do not mark medium-estimate or large-estimate issues agent:ready unless the user explicitly asks for that policy change. Agents should be able to use agent:ready as their default pickup queue without re-litigating product judgement.

Step 5 — Sync Issue State With Pull Requests

Keep issue state aligned with linked PRs.

If a linked PR is open:

• move the issue to the tracker review state when status/project fields are available
• remove agent:ready if the work is already being attempted
• leave or add a short issue comment only when it adds useful state, such as a missing PR link or verification summary

If a linked PR is merged:

• remove agent:ready
• close the issue when the PR clearly resolves it
• move the issue/project item to the done state when status/project fields are available
• preserve audit labels such as estimate:*, type:*, and any repo-approved completion label

If a linked PR is closed without merge:

• remove agent:ready
• add needs:human when the next step is unclear
• comment with the known reason when available
• move the issue/project item back to an appropriate open state only when the tracker policy is clear; otherwise leave status unchanged and report the mismatch

Do not close an issue unless the linked PR clearly resolves it. Use GitHub issue/PR state for completion instead of adding a separate completion label.

If a PR exists but merge readiness is unclear, do not infer completion from the PR title or branch name. Check live PR state: draft flag, mergeability, checks, review submissions, and unresolved review threads. Open PR plus unresolved actionable feedback means review/in-progress, not done.

When the backlog source has both issues and project items, verify the two agree after sync. For example, a closed issue should not remain In Review, and an open issue without an active PR should not remain In Review unless there is a human reason recorded.

Step 6 — Sweep The Repo For Quality Drift

Run this step on every full backlog review. Keep it evidence-driven and proportional: the goal is to catch product/project drift that should become a ticket or a report item, not to perform an unbounded code audit.

The sweep is evidence-driven. Look for concrete problems, not speculative improvements:

• stale docs referencing closed/open issue state incorrectly
• local backlog or roadmap docs that contradict tracker state
• docs saying something is not implemented when code exists, or saying it exists when code is missing
• broken local Markdown links
• README/setup commands that do not exist in justfile, package scripts, CLI help, Makefile, or docs
• generated docs drift when the repo has a documented check command
• TODO/FIXME/HACK comments that describe clear, bounded work
• skipped tests or disabled checks that look accidental
• recent failed CI/check runs on the default branch
• simple build/lint/config drift with a clear verification command

Do not create issues for:

• vague improvement ideas
• speculative refactors
• architecture rewrites
• product ideas
• anything requiring business, UX, security, data, billing, auth, or deployment judgement

Deduplicate against existing open and recently closed issues before proposing or creating anything.

Step 7 — Create Candidate Issues

In dry-run, do not create issues. Output candidates in this shape:

Candidate issue: <title>
Evidence:
- <file, command, PR, issue, or code reference>
Why it matters:
<short explanation>
Suggested fix:
<small reviewable fix>
Estimate: small | medium | large
Type: bug | feature | docs | test | refactor | chore
Agent-ready: yes | no
Confidence: high | medium | low
Create issue: yes | no

In apply, create a new issue only when there is concrete evidence of a real problem and confidence is high. If the concern is plausible but not proven, mention it in the run report instead of creating a ticket.

Every agent-created issue must include:

• evidence, including file paths, commands, config keys, PRs, issue links, or code references
• why the problem matters
• a small suggested fix
• an Agent Assessment

Step 8 — Report Unneeded Branches

Treat branch cleanup as backlog hygiene, but do not delete branches from this skill.

Inspect remote branches and PR state. Good cleanup candidates are branches that are:

• already merged into the default branch
• linked to closed issues or merged/closed PRs with no remaining work
• stale automation branches whose PR was closed without merge and has no active follow-up

Never delete branches in this workflow. Report cleanup candidates with evidence and leave deletion to a separate explicit branch-cleanup workflow or a human.

Step 9 — Verify Apply Runs

After an apply run, verify the tracker state before reporting:

• Every remaining open issue has a managed estimate:* label and a managed type:* label.
• Any issue where agent:ready appears without estimate:small, or alongside needs:human, is flagged in the report, not auto-corrected. A human may have set those labels deliberately.
• Every estimate:large issue has needs:human unless there is a clear reason not to.
• Every classified open issue has an ## Agent Assessment block in the issue body or an equivalent comment.
• Any stale completed issue closed during sync still keeps its final estimate/type labels and assessment for auditability.
• Any issues created by the sweep are deduplicated and include evidence.
• Issues with open linked PRs are in the review state when the tracker has one.
• Issues closed because a linked PR merged are in the done state when the tracker has one.
• No issue is both closed and left in an active status such as In Progress or In Review, unless the report calls out a tracker limitation or failed API update.

For GitHub, a small verification script using gh issue list --json number,title,labels,body is safer than eyeballing the web UI.

Step 10 — Report

End with a compact summary:

• tracker used
• mode used
• steps run: classify, sync, sweep, create candidates/issues, branch cleanup report, verify
• number of issues inspected
• labels created or missing
• issues changed
• issues marked agent:ready
• issues marked needs:human
• issues closed or synced from PR state
• sweep candidates found or created
• branch cleanup candidates found and reported
• verification result
• blockers and recommended next action

Scheduled Runs / Cron

For scheduled backlog management, run the full engineering-backlog loop every time so the repo stays in a healthy state: review backlog, label tickets, find repo drift, create/propose missing issues, sync ticket state, close stale/completed tickets, report safe branch-cleanup candidates, verify, and report.

The trigger can be an always-on assistant running this skill on a schedule, or a GitHub Actions workflow. For Actions, copy this skill into the target repo at .codex/skills/backlog-manager/SKILL.md and have the workflow prompt invoke it with an explicit mode; a workflow_dispatch input makes dry-run vs apply a manual choice. Note that the default GITHUB_TOKEN cannot edit user-level GitHub Projects, so Actions runs should treat project board mutations as report-only.

Keep scheduled mutation policy explicit. A cron may run in dry-run mode, or in conservative apply mode once the user has approved exactly which mutations are allowed for the repo.

Cron prompts must be self-contained. Include:

• repo/tracker name
• source-of-truth rule
• allowed mutation policy
• whether to create issues or only propose candidates
• verification requirements
• delivery target

Default scheduled behaviour should not merge PRs, publish releases, change secrets, spend money, delete branches, or make large-estimate changes.

GitHub Adapter

Use gh when available.

Useful commands:

gh repo view --json nameWithOwner,url
gh label list --limit 200
gh label create "estimate:small" --color "0E8A16" --description "Small issue suitable for agent execution when agent-ready"
gh issue list --state open --limit 100 --json number,title,body,labels,url,createdAt,updatedAt,comments
gh issue edit <number> --add-label "estimate:small,type:docs,agent:ready"
gh issue comment <number> --body-file <file>
gh issue close <number> --comment "Closed because linked PR <url> was merged."
gh project list --owner <owner>
gh project field-list <project-number> --owner <owner> --format json
gh project item-list <project-number> --owner <owner> --limit 200 --format json
gh project item-add <project-number> --owner <owner> --url <issue-or-pr-url> --format json
gh project item-edit --id <item-id> --project-id <project-id> --field-id <status-field-id> --single-select-option-id <option-id>

For linked PRs, use GraphQL or gh pr list/gh pr view as needed. Prefer exact linked PR data over guessing from branch names or text search.

Project mutations can be flaky through the GitHub API. When a project write times out, query the item before retrying so you do not duplicate comments or create duplicate project items. Retry serially and verify the final status.

Linear Adapter

Use Linear by default when the connector/tool is available and a team, project, or board can be resolved.

Map Linear fields and labels as follows:

• Use Linear's estimate field for small, medium, and large when estimates are enabled.
• If Linear estimates are unavailable, fall back to estimate:* labels.
• Map type:*, agent:ready, and needs:human as labels.

Map issue status to the workspace's existing workflow states. Do not create new status states unless the user asks.

When Linear and GitHub are connected, use linked PR state to update Linear issue status and labels.

Example Invocations

$backlog-manager dry-run GitHub backlog for this repo
$backlog-manager apply full backlog loop for GitHub repo owainlewis/neo
$backlog-manager dry-run backlog for GitHub Project https://github.com/orgs/acme/projects/7
$backlog-manager dry-run Linear backlog for team ENG project Agentic Engineer
$backlog-manager dry-run backlog from ./BACKLOG.md as the source of truth

Safety Rules

• Default to dry-run.
• Do not mutate trackers unless the user asks for apply.
• Never remove or downgrade existing managed labels during classification; only fill gaps. PR-evidence sync (Step 5) is the only step allowed to remove agent:ready.
• Do not add agent:ready to large-estimate issues.
• Do not auto-close issues without clear linked merged PR evidence.
• Do not mark a ticket done while linked PR checks are failing, pending, or unresolved review threads remain actionable.
• Do not create speculative work.
• Do not use the backlog manager to implement code.
• Do not delete branches from this skill; only report cleanup candidates.
• When unsure, classify conservatively and route the question through needs:human instead of waiting for a reply.

Quality Bar

• Uses the small fixed label set.
• Existing managed labels were respected; classification only filled gaps.
• Each classified issue has one managed estimate label and one managed type label.
• agent:ready only appears on small, clear, verifiable work.
• Human decisions are routed through needs:human, not extra labels.
• Issue reasoning lives in Agent Assessment, not label sprawl.
• Merged PR cleanup only happens with clear evidence.
• Branch cleanup is report-only.
• Final report is concise and actionable.