v1.13.0 ·
A roadmap more than one person can write
The problem
AIDLC's idea backlog was built for one author capturing braindumps mid-session. It is a flat directory of markdown files with a three-value status field, no stable identifier, and conventions that live entirely in skill prose — no code reads or validates any of it. That design works for a single technical author talking to an agent in a terminal, and it fails as soon as a project has more than one.
Real projects have several people proposing work, with mixed technical depth, and no shared tool for writing a proposal down. A non-technical contributor cannot be asked to hand-author YAML frontmatter. A contributor who is not in the repository cannot be asked to run the CLI. And with more than one author, "somebody submitted this" and "we agreed to build this" become different states that a single flat directory cannot express — so submissions either get treated as commitments or get lost.
Three things change. Status becomes visible in the directory tree, so anyone can see what is agreed, what is running, and what shipped without opening a file. Every item gets an identifier that survives being renamed and moved, so a future system can import a backlog without guessing which file became which record. And the framework ships a portable authoring skill any contributor can load into whichever AI agent they already use, so the frontmatter is produced for them rather than by them.
This is a framework capability, not a fix for one project. Nothing in it is specific to a single repository, a single platform, or a single team.
How it could be solved
The first instinct was to keep one flat directory and add a status field with more values. It
was rejected for a reason that only shows up later: a field and a directory are two places to
record the same fact, and they drift. A file sitting in done/ with status: raw in its
frontmatter is a bug you cannot see by looking, because a wrong status is indistinguishable
from a right one. Making the directory the only answer means changing status is a git mv, and
the tree itself is the report.
Four status directories were the original plan — backlog, in progress, done, hold. That
survived until the actual requirement was written down: several people proposing work, not one.
With one column for un-started work, somebody else's proposal and something the team has
committed to look identical. So there are five, and the extra one is inbox/: submitted,
nobody has triaged it yet. It also lets backlog/ keep its ordinary industry meaning instead
of doubling as the container's name.
The harder question was how a non-technical contributor produces a correctly-formatted file at all. Three options. A CLI command was rejected first — someone with no checkout and no terminal cannot run it, and it would have added a command surface, a generated reference page, and a website assertion pinning the command set. A web form was rejected as a product in its own right. What shipped is a skill file the framework emits, stamped with the version of AIDLC installed in that project, which a contributor loads into whichever AI agent they already use. The agent does the formatting; the person describes the idea.
That last choice forced two smaller ones. The file could not go through the platform adapters, because every adapter re-serializes frontmatter from a fixed key set and would have silently dropped the version stamp — the one field the whole approach depends on. And the version could not be a literal in the source, because a literal is a bump site the release script can forget; it is substituted at install time instead, and a build check now fails on a hardcoded one.
The rejected option worth naming is the automatic one. Watching a folder for new files, or ingesting a document into an instance without a human deciding, was never on the table: no file-change event exists in the lifecycle, the design refuses daemons, and promotion is a judgement about whether work is worth doing. The framework files completed items on its own, because that is bookkeeping. It does not decide what to build.
How AIDLC solves it
AIDLC's idea inbox became a roadmap that more than one person can write to.
Status is now the directory an item sits in. Five directories — inbox, backlog, in progress, done, hold — replace a three-value frontmatter field, so anyone can see what is submitted, agreed, running, and shipped by looking at the tree. Nothing reads a status field any more and the roadmap skill forbids writing one, because two representations of one fact drift apart and a wrong status is indistinguishable from a right one.
Every item carries an identifier assigned once and never recomputed, prefixed so it cannot be confused with the filename. Dependencies reference identifiers rather than filenames, which matters now that items move between directories routinely. A history list records when an item entered each status and is explicitly advisory: a missing entry costs a date, never a status.
The portable authoring skill is what serves people outside the repository. It ships in the content package, is written into the project with the installed version stamped into its frontmatter, and is re-stamped on every update — so a contributor can tell whether the copy they hold is current. It names no AI vendor, because it is loaded into whichever agent the contributor already uses, and a check fails the build if a vendor name appears in it. Emitting it needed its own writer rather than a platform adapter: every adapter re-serializes frontmatter from a fixed key set and would have silently dropped the version.
Completion files itself. When an instance finishes, a lifecycle action moves the item that produced it into the shipped directory and appends the history entry. Without that the directories become decoration within a month, because a step someone has to remember does not happen.
Existing projects upgrade with no manual step. Two migrations run inside the pass that update already performs: one moves a legacy backlog into the new layout, the other removes the skill artifacts orphaned by the rename. The first is confirm-tier and uses git for tracked files, so every move is one command away from undone.