self-host-development-light

Self-Host Development Light

Keep all project management artifacts in the repo as plain markdown. No external tools, no heavy process. Three files and a plans directory are enough for a solo developer or a small team working with agents.

Setup (run once)

Create the .development/ directory and its initial files. Before doing any work, check whether setup has already been completed — if all four items below exist, skip to Ongoing usage.

1. Create the directory structure

.development/
├── backlog.md
├── planning.md
├── todo.md
├── roadmap.md     (optional — see Roadmap vs plans)
└── plans/
    └── .gitkeep

2. Initialize backlog.md

# Backlog

Items not yet scheduled. Add new work here. Move to `todo.md`
when it becomes active.

<!-- Newest items at the top. -->

3. Initialize planning.md

# Planning

High-level direction, priorities, and open questions. Update
this when the project's focus shifts or after significant
milestones.

## Current priorities

<!-- What matters most right now and why. -->

## Open questions

<!-- Decisions that need input before work can proceed. -->

## Recent decisions

<!-- Decided items, with brief rationale, newest first. -->

4. Initialize todo.md

# Todo

Work in progress. Keep this short — if it grows beyond a
handful of items, move deferred work back to `backlog.md`.

## Active

<!-- Items currently being worked on. -->

## Blocked

<!-- Items waiting on something. Note what they're waiting on. -->

5. Verify setup

Confirm all files exist and contain their templates. The .development/plans/ directory should be present with a .gitkeep. Commit the scaffold with a message like Scaffold .development for project management.

Ongoing usage

Orientation

At the start of each session, read all three files to orient:

1. todo.md — what's active and what's blocked
2. planning.md — current priorities and open questions
3. backlog.md — what's waiting

Present a short summary to the human before starting work. This pairs with the What's Next checklist in AGENTS.md.

Adding work

New items go into backlog.md at the top. Each item is a short description — one or two sentences. Add context if the item isn't self-explanatory, but keep it brief.

- **Terraform import for dave-skills repo** — Run terraform
  import for the existing repo and branch protection before
  first apply. See terraform/main.tf TODOs.

Starting work

Move the item from backlog.md to the Active section of todo.md. Don't copy — move. The item should exist in exactly one place.

Completing work

Remove the item from todo.md. If it's worth recording, add a one-line entry to the Recent decisions section of planning.md with the date and outcome.

Blocking and unblocking

Move blocked items to the Blocked section of todo.md with a note explaining what they're waiting on. When the blocker clears, move back to Active.

Saving plans

When a session produces a plan worth preserving — an implementation approach, an architecture sketch, a multi-step breakdown — save it as a file in .development/plans/ with a descriptive name:

.development/plans/terraform-s3-backend.md
.development/plans/oidc-role-remediation.md

Plans are reference material. They don't replace the three working files.

Roadmap vs plans

Roadmaps and plans are different artifacts — don't let the terms collide:

• roadmap.md carries project scope: direction, architecture, and milestones. One per project, living at .development/roadmap.md. It changes when the destination changes.
• plans/ carries task scope: a single implementation approach or multi-step breakdown. Many per project, cheap to save. A plan changes (or gets superseded) when the approach changes.

A roadmap is optional — not every project has one, and young projects often shouldn't yet. When one exists, backlog items should trace to it; when priorities in planning.md drift from it, update one or the other.

Updating planning.md

Revise planning.md when:

• Priorities shift
• A significant decision is made
• An open question gets resolved
• The project's direction changes after a milestone

Keep it current. Stale planning docs are worse than no planning docs.

Principles

• One source of truth per item. An item lives in exactly one file at a time.
• Short todo list. If todo.md grows past five or six active items, push lower-priority work back to the backlog.
• Backlog is append-only until groomed. Don't over-organize the backlog. Newest items go at the top. Groom periodically by removing items that are no longer relevant.
• Plans are cheap. Save any plan worth revisiting. The plans directory is a filing cabinet, not a commitment.
• Process follows the work. If this structure stops fitting, change it. The point is to support the work, not to maintain the process.