project-backlog

Files (2)

• SKILL.md
• backlog-project-tree

SKILL.md (first lines)

# Project Backlog

## Overview

Use a project-local `backlog/` folder as the source of truth for backlog item status. Work with the Obsidian vault as plain Markdown files. Resolve the vault path directly from `OBSIDIAN_VAULT` or `VAULT`; if neither is set and the human did not provide a vault path, ask for it before reading or writing backlog files.

Lifecycle hook: if work starts, pauses, resumes, opens PR, or completes, update the matching backlog item.

## Folder Convention

Each project folder may contain:

```text
backlog/
  intake/
  next/
  ongoing/
  paused/
  done/
  canceled/
```

Before filing or moving backlog items, create the project `backlog/` directory and any missing status subdirectories from the project folder.

Copyable initializer:

```bash
mkdir -p backlog/{intake,next,ongoing,paused,done,canceled}
```

Status is canonical from the folder name. A backlog item must live in exactly one status folder.

| Folder | Meaning | Move here when |
|---|---|---|
| `intake/` | Raw ideas, requests, bugs, or feature notes not yet triaged | Capturing unsorted work |
| `next/` | Accepted, scoped, and ready for an agent or human to pick up | The item has enough context and success criteria |
| `ongoing/` | Actively assigned or being implemented | Work starts, including async subagent runs |
| `paused/` | Intentionally stopped but may resume | Blocked, waiting, deferred, or interrupted |
| `done/` | Completed and verified | The feature/fix is accepted, cleaned up, and no follow-up is needed |
| `canceled/` | Intentionally not doing | The item is rejected, obsolete, duplicated, or no longer wanted |

Do not create alternate status folders such as `todo/`, `active/`, `blocked/`, `archive/`, or `shipped/`. Use tags/properties for metadata only, not as competing status systems. If a note has a `status` property, keep it synchronized with the containing folder or remove it only with permission.

## Item Format

One Markdown note per item. Keep filenames short/stable, e.g. `add-search.md`. Folder = status; do not add a `status` property.

```markdown
---
tags: [backlog]
type: feature # feature | bug | chore | research
priority: P2 # P0 | P1 | P2 | P3
description: One concise sentence explaining the item.
created: 2026-06-19
updated: 2026-06-19
due:
agent_run:
---

# Title

## Request
## Context / Links
## Acceptance Criteria
- [ ]
## Activity Log
- 2026-06-19 — Created.
```

Preserve frontmatter, wikilinks, and Markdown when moving or editing notes.

## Async Agent Workflow

1. **Capture**: create or move new requests into `backlog/intake/`.
2. **Triage**: clarify scope, deduplicate, add acceptance criteria, then move to `next/`, `canceled/`, or leave in `intake/`.
3. **Assign**: before starting an async agent or human work session, move the item to `ongoing/` and add a brief activity-log entry with date, owner, and run/session identifier if useful.
4. **Track**: update the item with links to branches, PRs, review notes, blockers, and decisions. Do not mark a note done just because an agent reported completion.
5. **Finish**: after verification and cleanup, move completed feature/fix notes to `done/`. If work is blocked or intentionally stopped, move to `paused/`; if abandoned or rejected, move to `canceled/`.

## Housekeeping

On request, perform safe maintenance:

- ensure `backlog/` and all six status subdirectories exist before filing items;
- list duplicate or near-duplicate backlog items before merging them;
- identify stale `ongoing/` items with no recent activity;
- identify `paused/` items missing blocker/resume notes;
- move verified completed items from `ongoing/` or `paused/` to `done/`;
- move rejected, obsolete, or duplicate items to `canceled/`;
- normalize filenames only when links/backlinks can be preserved;
- ask before deleting files, bulk-moving notes, overwriting frontmatter, or changing wikilinks.

## Backlog Tree Helper

For a quick read-only snapshot by unique project folder name, run from this skill directory:

```bash
./backlog-project-tree "projectName"
```

Set the vault path with `OBSIDIAN_VAULT` or `VAULT`:

```bash
OBSIDIAN_VAULT=/path/to/vault ./backlog-project-tree "projectName"
# or
VAULT=/path/to/vault ./backlog-project-tree "projectName"
```

It prints Markdown files under `intake/`, `next/`, `ongoing/`, `paused/`, `done/`, and `canceled/`, with best-effort metadata (`type`, `priority`, `description`, `updated`, `due`, `agent_run`). It reports missing categories without creating, moving, or deleting anything.

## Backlog State Review

When asked for a backlog review, scan only the requested project unless told otherwise:

1. Confirm the project folder and vault path.
2. Count items in each status folder.
3. Summarize `intake/` triage candidates, `next/` ready work, stale `ongoing/`, and blocked `paused/` items.
4. Recommend specific moves or edits, grouped by status.
5. Ask for confirmation before applying bulk moves or destructive cleanup.

From bnema/pi-public, MIT.

More from bnema/pi-public