Repo-based project management

repo-based-project-management.md

Repo-based project management

Development Tracking from the Git Repository

The directory is .development/ — not .project/ — because the work this directory captures is the development of the repo's contents. A repo may contain many projects; "development" names the activity that applies regardless of how many projects live inside.

For software agents:

• Part 1 is run once per repo.
• Part 2 is the ongoing contract.
• Part 3 is the stewardship concept; adopt it once recurring maintenance work starts producing per-change ticket overhead.

Ask for clarification if there is any ambiguity.

Part 1: setting up the development tracking structure

In the git repo, do the following:

1. Create the directory structure:

   • .development/backlog/ — proposed work, not yet started
   • .development/active/ — work in progress (one ticket at a time is the common case; not a hard limit)
   • .development/done/ — completed work, moved from active
   • .development/stewardship/ — standing change requests (see Part 3)
   • .development/README.md — overview of the structure

   Optional but recommended once they earn their keep:

   • .development/adr/ — Architectural Decision Records
   • .development/prd/ — Product Requirements Documents
   • .development/design/ — Design docs (UX flows, schema sketches)
   • Top-level .development/VISION.md and .development/DESIGN.md for repo-wide guiding documents

2. Prompt the user for a project acronym. For example if the project name is "RailsStash" ask the user how to prefix sequential ticket IDs, in this case suggest "RS".

3. Copy the template into .development/backlog/ as <PREFIX>-0000-template.md (using the real ticket-ID format so it sorts alongside its siblings):

---
id: <PREFIX>-0000
title: Short imperative title
type: task                 # task | bug | spike | story | epic
status: backlog            # backlog | ready | in_progress | blocked | done

value: 3                   # 1–5 impact
effort: 2                  # 1–5 relative effort
fun_factor: 3              # 1–5 how much fun to implement
urgency: 2                 # 1–5 time pressure
risk: 1                    # 1–5 uncertainty / blast radius
score: null                # computed, not authoritative
llm_model: null            # minimum model tier that can execute this ticket:
                           # haiku | sonnet | opus | fable | human
                           # (delegation hint; null = not yet assessed)

owner: dave
created: 2026-05-18
updated: 2026-05-18
completed: null

parent: null
depends_on: []
area: null                 # feature | infrastructure | tooling | testing | stewardship | ui | housekeeping
component: null            # REQUIRED for backlog/done tickets; OMIT entirely for
                           # stewardship/* tickets (standing requests have no
                           # single component target). Project-specific allowed
                           # values — define them in your repo's AGENTS.md.
adr_refs: []               # ADR-0003, ADR-0007
links: []                  # PRs, issues, docs
labels: []
acceptance_test: false     # true if manual acceptance testing required before close
---

## Why

Sharp motivation. Business or technical driver.

## Outcome

Observable truth after completion.

## Acceptance Criteria

- [ ] Concrete, verifiable result
- [ ] Another concrete result

## Before Staging

- [ ] Run all CI tools (linters, type-checks, security scanners,
      unit + integration tests) per AGENTS.md

## Notes

Constraints, edge cases, relevant context.

## LLM Context

- Files likely affected:
- Invariants to preserve:
- Style constraints:
- Known traps:

4. Copy the following into .development/backlog/README.md:

# Backlog

This directory contains all backlog items for the project.

## Canonical Template

All entries MUST conform to:

    ./<PREFIX>-0000-template.md

No alternate formats are permitted.

## Creating a Backlog Item

1. Copy `<PREFIX>-0000-template.md`.
2. Create a new file in this directory.
3. Name the file:

       <PREFIX>-<DIGITS>-short-kebab-title.md

   Example:

       RS-0023-ci-hardening.md

4. Fill in all required YAML fields.
5. Do not remove sections from the template.
6. Keep entries self-contained and atomic where possible.

## Updating a Backlog Item

- Preserve the original structure.
- Update status and metadata in the YAML header.
- Add notes under the appropriate sections.
- Do not modify historical content unless correcting factual errors.

## Scope Rules

- One file per discrete unit of work.
- Epics may reference child items but must still conform to the template.
- Architectural decisions belong elsewhere (e.g., `../adr/`), not in
  this directory.

## Enforcement

Agents must read `AGENTS.md` at the repo root before interacting with
this directory. Humans are responsible for approving structural
changes.

5. Copy the following into .development/README.md:

# .development

This directory contains project management artifacts.

## Structure

- `backlog/` — Active backlog items (see `backlog/<PREFIX>-0000-template.md` for format)
- `active/` — Work currently in progress
- `done/` — Completed items moved from active
- `stewardship/` — Standing change requests for recurring maintenance
  (see `stewardship/README.md`)
- `adr/` — Architectural Decision Records (optional)
- `prd/` — Product Requirements Documents (optional)
- `design/` — Design docs (optional)

See `AGENTS.md` at the repo root for agent guidelines.

## Why manage the project in the repo?

### Pros

- **Colocation** — all details of the work live with the work itself.
- **Version-controlled history** — tickets, ADRs, and PRDs share the
  same Git history as the code they describe.
- **AI-agent friendly** — LLM agents can read, update, and close
  tickets in the same workflow that writes the code.
- **Zero external dependencies** — no SaaS subscription, no network
  requirement, no vendor lock-in.
- **Atomic commits** — code changes and the ticket that motivated
  them can land in the same commit.
- **Low ceremony** — plain Markdown files, easy to create and review
  in any editor or terminal.

### Cons

- **No built-in board view** — no drag-and-drop Kanban without
  building or hosting one.
- **Merge conflicts on tickets** — standard text merge conflicts
  apply when multiple contributors edit the same file.
- **Limited collaboration tooling** — no native comments, mentions,
  notifications, or assignment workflows.
- **Scales with repo size** — hundreds of ticket files can clutter
  the tree; `done/` and `active/` partition helps but doesn't fully
  solve discoverability.
- **No cross-repo visibility** — multi-repo project views require
  external aggregation.

Part 2: agent context

Agents should feel free to create a Project Manager sub-agent.

Copy the following into AGENTS.md in the repo root (note: plural, matching the cross-tool emerging convention):

# Agent context

## Development Tracking

This repository uses a structured backlog format for all work items.

Before creating, modifying, or reprioritizing any backlog entry, you
MUST read:

    .development/backlog/<PREFIX>-0000-template.md

All backlog items must conform exactly to that template.

If a proposed item does not fit the template, revise the proposal —
do not alter the template without explicit human approval.

When a unit of work defined by a ticket is complete, move the file
from `.development/active/` to `.development/done/` and set
`status: done` and `completed: <YYYY-MM-DD>` in the YAML header.

## Operating mode

This repository operates in **assistive mode** by default:

- Propose changes.
- Do not mutate backlog files without approval.
- Edit, commit, and push are three separate consent gates. Permission
  settings are a safety floor, not a signal of intent — explicit
  per-action approval still applies even when the tool is allow-listed.

Part 3: stewardship — standing change requests

The problem

Standard practice is one ticket per change, with ticket numbers advancing sequentially. This works well for discrete features and bug fixes, but code maintenance is different: dependency updates, documentation hygiene, backlog grooming, and annotation cleanup are recurring, identical-in-kind changes. Creating a new ticket for each instance adds overhead without adding signal.

The pattern

A stewardship ticket authorizes a category of recurring maintenance work. It acts as a permanent change request that can be referenced on any commit performing that type of maintenance, without creating a new ticket each time.

For example, a ticket titled Keep Ruby and gem dependencies current authorizes any bundle update commit. The ticket defines the acceptance criteria and guardrails; individual commits reference it by ID.

This satisfies change management requirements:

• Traceability — every commit references a ticket ID.
• Authorization — the standing request defines who owns the work and what the acceptance criteria are.
• Auditability — git log filtered by ticket ID shows the full history of that maintenance activity.
• Low overhead — no ticket-per-change ceremony for routine work.

What belongs in stewardship/

• Recurring work, not a one-time task.
• Identical in kind across instances (the what is the same; the when varies).
• Defined guardrails and acceptance criteria that apply to every instance.
• Never "done" in the traditional sense — they remain active as long as the codebase exists.

What does not belong in stewardship/

• One-time tasks, even if they relate to maintenance (use backlog/).
• Feature work, even if it improves maintainability (use backlog/).
• Completed discrete tasks (use done/).

Stewardship ticket frontmatter difference

The component field is omitted entirely (not nulled) for stewardship tickets, because standing requests have no single component target. All other template fields apply normally.

Referencing stewardship tickets in commits

Commit messages reference stewardship tickets the same way as any other ticket:

<PREFIX>-0019 Update nokogiri to 1.16.8 (CVE-2024-XXXXX)

The ticket ID connects the commit to the standing change request, providing the compliance trail without per-change ticket creation overhead.