Client-Grade Project Management, Solo: GitHub Issues as the Source of Truth

Solo projects usually manage themselves in one of two ways: a TODO file nobody else can read, or a heavyweight tool nobody keeps updated. For Social OS Debugger — our civic-tech simulation of how societies break and recover — we wanted a third option: project management a client or collaborator could audit without asking us anything.

Everything ended up on plain GitHub. Here is the shape of it, and what it costs to maintain.

Start from user stories, not features

The product plan is a markdown file of user stories with acceptance criteria, grouped into phases with explicit priorities (P0/P1/P2). One example:

US-03 (P0) As a user, after my town collapses I want to try “if I could go back and change one thing” — and see my intervention change the future. Acceptance: rewind on page 1 → re-run → on survival, one extra line appears on the result card.

The acceptance line is the important part. It is what turns “done?” from a feeling into a check. It is also what makes delegation possible — to a contractor, or to an AI.

There is a North Star metric at the top of the file (cumulative “towns protected”), so every story can be argued against one number.

GitHub Issues as the outward view

The planning file is for working context; GitHub Issues are the same history, published. A small idempotent script backfilled the project’s history — 99 issues, three milestones (one per phase), a handful of labels (area:app / infra / testing / content / docs) — so the “plan → execute → done” trail reads directly on GitHub.

Two rules keep it from becoming double bookkeeping:

1. Issue bodies are 1–3 lines. The issue is a signpost, not the document.
2. Commits close issues. Every completing commit ends with Closes #N, so GitHub links the code to the plan automatically. No status meetings with yourself.

The label that matters: process:ai-subagent

A growing share of tasks on this project are delegated to AI subagents. That is exactly the kind of thing that goes wrong silently, so delegation gets governance:

• Each delegated task is an issue with a written spec and acceptance criteria before the agent starts.
• The main session (a human-supervised one) reviews, verifies against the acceptance criteria, and commits. The agent never merges its own work.
• The issue carries the process:ai-subagent label, so anyone can filter and see precisely which parts of the codebase were AI-delegated, and check the verification trail.

In an era where AI does more of the work, we think the honest position is not “no AI” or “AI did it” — it is a visible record of who did what, and who checked it.

What this costs, honestly

A few minutes per task to write the issue, and the discipline to write acceptance criteria before starting. That’s it — the expensive-looking parts (backfill, linking, board) are scripts and conventions, not ongoing labor. The payoff is that the project’s management is as inspectable as its code: milestones show the phasing, labels show the delegation, closed issues show the throughput.

---

Social OS Debugger is open source — repository · live demo (free, no login, ~60 seconds). The same planning discipline runs our care apps — see what we’re building — and our client work: if you need a technical PM who manages this way, that’s hire-veai.com.