@rasensio/aidlc-content 1.12.0 → 1.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,6 +19,7 @@
     "capabilities/",
     "phases/",
     "tutorials/",
+    "resources/",
     "glossary.yaml"
   ],
   "engines": {

package/resources/skills/roadmap-item/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: roadmap-item
+description: Turns a rough idea into one correctly-formatted roadmap item file for an AIDLC project, ready to commit to the project's roadmap inbox
+version: {{version}}
+---
+
+# Write a Roadmap Item
+
+Your job is to turn what someone tells you into **exactly one markdown file**, formatted so
+an AIDLC project can pick it up without anyone editing it by hand.
+
+The person you are helping may not be technical. Do not ask them about YAML, filenames, git,
+or metadata. Ask about their idea. You produce the formatting.
+
+## What to ask
+
+Ask for whatever is missing, a couple of questions at a time, and stop as soon as you can
+fill the body sections. Three or four exchanges is plenty. A rough item is worth more
+than a polished one that never got written.
+
+You need:
+
+1. What problem this solves, and who has the problem.
+2. What would be true if it worked.
+3. Whether it is meant to earn money, save money, or neither. Ask this plainly —
+   "would this make money, save money, or is it just something that needs doing?" —
+   and accept "neither" as a perfectly good answer.
+4. Their name, for the record.
+5. Today's date, if you cannot determine it reliably.
+
+Anything they do not know is allowed to stay unknown. Write `Not yet decided.` under a
+heading rather than inventing a plausible answer — a fabricated success metric is worse than
+an admitted gap, because the next reader cannot tell it was a guess.
+
+## What to produce
+
+One file. Name it `YYYYMMDD-short-slug.md`, using today's date and two to four words from
+the title, lowercase, hyphen-separated. Example: `20260315-invite-teammates.md`.
+
+The file must start with this frontmatter, at the very first line, with no blank line before
+it:
+
+```
+---
+id: item-YYYYMMDD-short-slug
+title: <one line, sentence case>
+created_at: YYYY-MM-DD
+author: <their name, as they gave it>
+source: agent
+promoted_to: null
+depends_on: []
+history:
+  - { status: inbox, at: YYYY-MM-DD }
+---
+```
+
+Rules for those fields:
+
+- `id` is the filename without `.md`, prefixed with `item-`. It never changes afterwards,
+  even if the file is renamed or moved.
+- `created_at` and the `history` date are both today, and both match the filename's date.
+- `source` is always `agent` here, because you drafted it. It records how the item was
+  written, not who asked for it.
+- `promoted_to` stays `null`. Leave `depends_on` empty — you cannot know the identifiers of
+  other items in the project.
+- Do not add any other field, and do not add a `status` field. Status is recorded by which
+  folder the file sits in, not inside the file.
+
+Then the body, with these five headings and nothing else at this level:
+
+```
+# <the title again>
+
+## Executive Summary
+
+## Problem
+
+## Who it's for
+
+## What success looks like
+
+## Out of scope
+```
+
+Write plain prose under each. Short paragraphs or bullets, no tables. Two or three sentences
+per section is normal. `Out of scope` is where you record what they explicitly said they do
+*not* want — leave it as `Nothing stated yet.` if they said nothing.
+
+## The Executive Summary
+
+This is the section a busy decision-maker reads instead of the item. It comes first in the
+file and you write it **last**, once the other four sections exist — a summary written first
+is a guess.
+
+Use exactly these six labels, in this order, one or two sentences each:
+
+```
+- **What it is** — the change itself, in one sentence, in words a non-engineer would use.
+- **Who benefits** — the person who feels the pain today, named by role.
+- **Customer value** — what they can do afterwards that they cannot do now.
+- **Revenue** — Direct, Indirect, or None, then one sentence saying why.
+- **Cost and risk** — rough size (hours, days, weeks) and the main way it goes wrong.
+- **Recommendation** — Do now, Do later, or Don't do, plus the reason in one line.
+```
+
+Four rules make the difference between a summary worth reading and decoration:
+
+- **`None` is a real answer for revenue, and often the right one.** Plenty of necessary work
+  earns nothing directly. Writing `Indirect` for everything makes the field useless, which is
+  worse than leaving it blank, because it looks answered.
+- **Do not sell the idea.** You are summarising what someone told you, not pitching it. If
+  they described a small convenience, say so. An honest `Do later` is more useful to them
+  than an enthusiastic `Do now` that turns out wrong.
+- **Say `Not yet decided.` for any label you cannot fill.** Same rule as the rest of the
+  file: an admitted gap beats an invented number, because the next reader can tell the
+  difference.
+- **Keep it to six lines.** If the reasoning needs more room, that room is the `Problem`
+  section. A summary that runs to a page is not a summary.
+
+## Where it goes
+
+Tell them to add the file to their project's roadmap inbox:
+
+```
+.aidlc/roadmap/inbox/YYYYMMDD-short-slug.md
+```
+
+If they do not use git or a terminal, the project's web interface will let them add a file
+to that folder directly — they navigate to it, choose to add a file, paste the contents, and
+save. That is the whole handoff. Somebody on the project reviews the inbox and decides what
+happens next.
+
+## Before you finish
+
+- Never include passwords, API keys, tokens, or access credentials. If they paste one, leave
+  it out and tell them you did.
+- Never include a person's contact details or any customer's personal data.
+- Produce the file as text they can copy in one piece, and give them the filename separately
+  so they do not have to guess it.
+- One idea, one file. If they described three unrelated things, say so and offer to write
+  three files.

package/skills/00-overview.md

@@ -66,7 +66,7 @@ phase artifacts to publish a post, rotate a log, or regenerate a report.
 
 An operation sometimes reveals a missing capability — you go to publish a post and discover the system
 has no way to mark it as a draft. When that happens, the *operation* stops being the work and the
-missing capability re-enters the lifecycle as a normal instance. Capture it with **aidlc-idea** or start
+missing capability re-enters the lifecycle as a normal instance. Capture it with **aidlc-roadmap** or start
 an instance; do not quietly extend the skill into building the feature.
 
 ### Quality mechanisms live inside the skill
@@ -163,9 +163,9 @@ When a phase needs substantial input from the user — open decisions, structure
 3. Tell the user the file path and wait for their edits — do not proceed on unanswered questions.
 4. When the user has answered, fold the outcomes into the phase artifact and state records. The inbox file is scratch input, not an artifact — offer to delete it once its content has landed.
 
-## Idea Capture
+## Roadmap Capture
 
-When the user shares an idea tangential to the current work, offer to record it in `.aidlc/ideas/` (see **aidlc-idea**) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.
+When the user shares an idea tangential to the current work, offer to record it in `.aidlc/roadmap/inbox/` (see **aidlc-roadmap**) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.
 
 ## Instance Completion and Retrospective
 

package/skills/03-entry-point.md

@@ -27,7 +27,7 @@ If `.aidlc/context/` does not exist or contains no `.md` files, defer to the **a
 1. List the directories under `.aidlc/state/`. Each directory is a lifecycle instance.
 2. For each instance, read `instance.yaml` (current phase, template, scope, claim) and the `phase-<name>.yaml` files to compute completion (complete artifacts ÷ total required artifacts).
 3. Read `.aidlc/config.yaml` for project defaults (scope, template) if present.
-4. Count ideas in `.aidlc/ideas/` by status — read only the frontmatter (and title line if needed), never idea bodies.
+4. Count roadmap items per status directory under `.aidlc/roadmap/` (`inbox`, `backlog`, `in-progress`, `done`, `hold`) — count files, and read frontmatter only if a title is needed. Never read item bodies. Status is the directory; there is no status field to read.
 5. Check `<git-common-dir>/aidlc/retro-pending/` (resolve via `git rev-parse --git-common-dir`) for pending-retrospective markers. Each marker adds a menu entry: **Run retrospective for `<instance>`** (routes to the **aidlc-retrospective** skill). A marker whose instance has no state dir and no registry entry is stale — remove it and note the cleanup in one line.
 
 Do not read artifact bodies or transition history to build the menu — the compact state files are enough.
@@ -38,15 +38,16 @@ Compose a short menu from the state. Include only the options that make sense:
 
 - **Continue `<instance>`** — one entry per incomplete instance, showing current phase and completion percentage. Most recently updated first.
 - **Start something new** — always.
-- **Capture an idea** — always.
-- **Browse / promote ideas** — when `.aidlc/ideas/` contains at least one non-dropped idea; show the raw count (e.g. "4 raw ideas").
+- **Capture a roadmap item** — always.
+- **Triage the inbox** — when `inbox/` is non-empty; show the count (e.g. "3 items awaiting triage"). List this above **Browse** — an untriaged submission is somebody waiting on a decision.
+- **Browse / promote the roadmap** — when any status directory outside `hold/` is non-empty; show counts per status (e.g. "3 inbox, 5 backlog, 1 in progress, 12 done").
 - **Show status** — when at least one instance exists.
 - **Review an artifact** — when at least one instance has a completed artifact.
 - **Help / getting started** — always.
 
 Present the options as a numbered list (or the platform's native selection prompt) and wait for a choice. If the user's message already states what they want (e.g. "continue my-feature"), skip the menu and route directly.
 
-If `.aidlc/state/` is empty or missing, offer just three options: start something new, capture an idea, or help.
+If `.aidlc/state/` is empty or missing, offer just three options: start something new, capture a roadmap item, or help.
 
 ## Step 3 — Route
 
@@ -54,9 +55,10 @@ If `.aidlc/state/` is empty or missing, offer just three options: start somethin
 |--------|--------|
 | Continue an instance | Follow the **aidlc-continue** skill |
 | Start something new | Run the **concurrency gate** (below), then ask what they are building, pick a template (see **aidlc-getting-started**), and create the instance per "Creating an Instance" in **aidlc-overview** |
-| Capture an idea | Follow the **aidlc-idea** skill (capture flow) |
-| Browse / promote ideas | Follow the **aidlc-idea** skill (browse/promote flow) |
-| Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled. When the backlog is non-empty, append the idea count (e.g. "4 ideas in backlog, 3 raw") |
+| Capture a roadmap item | Follow the **aidlc-roadmap** skill (capture flow) |
+| Triage the inbox | Follow the **aidlc-roadmap** skill (triage flow) |
+| Browse / promote the roadmap | Follow the **aidlc-roadmap** skill (browse/promote flow) |
+| Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled. When the roadmap is non-empty, append the per-status counts (e.g. "roadmap: 3 inbox, 5 backlog, 12 done") |
 | Review an artifact | Follow the **aidlc-review** skill |
 | Help / getting started | Follow the **aidlc-getting-started** skill |
 

package/skills/04-roadmap.md

@@ -0,0 +1,131 @@
+---
+name: aidlc-roadmap
+description: Captures roadmap items into .aidlc/roadmap/inbox/ at any moment — no instance, claim, or phase required — and browses, triages, promotes, or drops them
+phase: ideation
+priority: 90
+trigger: When the user says "idea:", asks to capture/record an idea or roadmap item, wants to browse the roadmap, or wants to triage, promote, or drop an item
+native_mode_hint:
+  claude-code: >-
+    This skill is an interactive inbox, not a phase artifact. Do not enter
+    plan mode. Capture is a single write-and-confirm; never touch instance
+    state while capturing.
+---
+# Roadmap
+
+> {{glossary:instance}}
+
+`.aidlc/roadmap/` is a first-class inbox, independent of every lifecycle phase. Items are captured cheaply now and converted into instances later. Capture is legal at any moment: mid-implementation on another instance, from a second session, or with no instance at all.
+
+Projects have more than one person proposing work, with mixed technical depth, so the roadmap distinguishes *submitted* from *agreed*. A contributor with no checkout can author an item with the portable skill at `.aidlc/resources/skills/roadmap-item/SKILL.md` — loadable into any AI agent — and commit the result to `inbox/`.
+
+## Statuses Are Directories
+
+```
+.aidlc/roadmap/
+  inbox/         submitted, nobody has triaged it
+  backlog/       accepted, will do, not started
+  in-progress/   an instance exists
+  done/          shipped
+  hold/          parked or declined
+```
+
+**The directory an item sits in is its status.** There is no `status` field, and you must never add one — two representations of one fact drift apart, and a wrong status is indistinguishable from a right one. Changing status means moving the file.
+
+`hold/` holds both parked and declined items. That conflation is deliberate; `history` and the git log distinguish them when anyone asks.
+
+## Item Format
+
+One file per item: `.aidlc/roadmap/<status>/YYYYMMDD-<slug>.md`, beginning with exactly these keys in this order:
+
+```yaml
+---
+id: item-20260814-cost-tracking
+title: Cost tracking
+created_at: 2026-08-14
+author: Rodrigo Asensio - rasensio@   # optional; omit rather than guess
+source: human                          # human | agent | import
+promoted_to: null                      # instance name once promoted, else null
+depends_on: []                         # other items, by id
+history:
+  - { status: inbox, at: 2026-08-14 }
+---
+```
+
+- **`id`** is assigned once and never recomputed. Renaming the file or moving it between statuses leaves it unchanged. The `item-` prefix keeps it textually distinct from the filename so nothing derives one from the other.
+- **`source`** records how the item was written: `human` directly, `agent` drafted by an AI agent from someone's description, `import` migrated from an older format.
+- **`depends_on`** names other items by `id`, so a dependency survives its target moving. Build order is derived from this graph when needed — there is no global `order` field, because concurrent capture from independent sessions cannot coordinate a sequence.
+- **`history`** is append-only and advisory. Append `{ status, at }` when you move an item. An absent or incomplete history is never an error, and current status always comes from the directory — never from the last history entry.
+
+Bodies are otherwise free-form. Items authored through the portable skill carry four further headings — Problem, Who it's for, What success looks like, Out of scope — which is a useful shape, not a validated one.
+
+### Every Item Opens With an Executive Summary
+
+The first section of the body, before anything else, is `## Executive Summary` — six labelled lines, nothing more:
+
+```
+## Executive Summary
+
+- **What it is** — the change itself, in one sentence, in words a non-engineer would use.
+- **Who benefits** — the person who feels the pain today, named by role.
+- **Customer value** — what they can do afterwards that they cannot do now.
+- **Revenue** — Direct, Indirect, or None, then one sentence saying why.
+- **Cost and risk** — rough size (hours, days, weeks) and the main way it goes wrong.
+- **Recommendation** — Do now, Do later, or Don't do, plus the reason in one line.
+```
+
+This exists so a triage decision can be made from the top of the file. An item whose value cannot be stated in six lines is an item nobody can decide about, and it will sit in `inbox/` until somebody re-derives the case from scratch.
+
+Four rules keep it honest:
+
+- **`None` is a real answer for revenue, and often the correct one.** Lifecycle plumbing earns nothing directly. Writing `Indirect` for everything makes the field useless, which is worse than leaving it blank because it reads as answered. This is also the cheapest available check against the self-repair trap: a meta-feature that has to write `Revenue — None` and `Customer value — none, it observes the lifecycle` has declared itself.
+- **Write it last, from the rest of the body.** A summary drafted before the detail is a guess wearing a summary's clothes.
+- **`Not yet decided.` for any label you cannot fill.** An admitted gap beats an invented figure; the next reader can tell the difference.
+- **Six lines, no more.** Longer reasoning belongs in the sections below it.
+
+Older items may predate this section. Add it when you next touch such an item — derived from what the item already says, never from fresh speculation — rather than sweeping the whole directory.
+
+## Capture
+
+1. **Resolve the roadmap root.** Always write to the **primary checkout's** `.aidlc/roadmap/`, never a worktree's copy: resolve via `git rev-parse --git-common-dir` (the directory containing that path is the primary checkout). Outside a git repo, use the current project root. Create `inbox/` if missing.
+2. **Name the file.** `YYYYMMDD-<slug>.md` — today's date plus a short (2–4 word) slug.
+3. **Handle collisions.** If the filename already exists in *any* status directory, ask one question — extend the existing item or new item? On extend, append a dated `## Update (YYYY-MM-DD)` section to it where it is; on new, suffix the slug (`-2`). Never silently overwrite.
+4. **Write the file** into `inbox/`, with `source: human`, `promoted_to: null`, and one `history` entry dated today. Record `depends_on` only if the braindump itself names other items; never ask for dependencies. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
+5. **Draft the executive summary from the braindump, do not extract it by interview.** You write those six lines; the user does not. Ask at most one question, and only when the braindump says nothing about who wants this or why — a good one is "would this make money, save money, or is it just something that needs doing?". Anything still unknown is `Not yet decided.`, which is the point of having the label.
+6. **Confirm and return.** Report the file path and the `Recommendation` line, then return to whatever was happening. Showing the recommendation lets the user correct a wrong read immediately, while the context is still in front of them.
+
+**Hard rule:** capture never reads or writes anything under `.aidlc/state/` — no claims, no phase files, no transitions log. Two sessions capturing simultaneously just produce two files; no locking exists or is needed. Do not auto-commit; staging is the user's.
+
+If the user includes credentials, tokens, or secrets in a braindump, flag it and omit them from the file.
+
+## Browse
+
+List each status directory, reading **only frontmatter and the containing directory** — never item bodies. Show each item's date, title, status, and dependencies. Group by status in lifecycle order and give a count per status. Flag `inbox/` items first: they are waiting on a decision only a human can make. Then flag `backlog/` items whose dependencies are all `done` — those are the natural next candidates. Offer to open, triage, promote, or drop.
+
+The frontmatter-only rule holds for browsing, which is a list and must stay cheap enough to run over the whole roadmap. **Triage** below is the one flow allowed into the body, and only as far as the executive summary.
+
+A filename appearing in two status directories is an error: report it rather than guessing which one is current.
+
+## Triage
+
+Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to `hold/` means "not now". Move the file and append the matching `history` entry. Triage is the one flow that exists purely because more than one person can submit work — do not skip it by promoting straight from `inbox/` unless the user says so.
+
+Triage is the one flow that reads into the body, and it reads **the executive summary and nothing else**. Six labelled lines per item is what makes triaging a full inbox in one sitting possible; opening whole items is what makes triage something nobody ever gets round to. Show the summary, say which way you would go and why, and let the human decide. If an item has no executive summary, write one from what the item says before asking for a decision — a decision made without one is a decision made twice.
+
+## Promote
+
+Promotion is where the roadmap meets the lifecycle:
+
+> {{glossary:scope}}
+
+1. Promote from `backlog/` normally; from `inbox/` only when the user is explicitly skipping triage.
+2. If the item's `depends_on` names items that are not yet `done`, say so and confirm before proceeding — promoting out of order is allowed but should be deliberate.
+3. Choose a template and scope as usual (defaults from `.aidlc/config.yaml`; see **aidlc-getting-started**).
+4. Create the instance per "Creating an Instance" in **aidlc-overview** — including firing `on-instance-start` lifecycle actions.
+5. Seed the instance with the item: Full scope → the item is raw material the Ideation phase refines into that phase's required artifact (`idea.md` for the feature templates, `research-question.md` for `spike`); Standard scope → the item is input context for Requirements.
+6. Set `promoted_to: <instance-name>`, move the file to `in-progress/`, and append the `history` entry.
+
+When the instance completes, the `roadmap-done` lifecycle action moves the item to `done/` on its own — do not do it by hand, and do not remove that action to do it manually.
+
+## Drop
+
+Move the item to `hold/` and append the `history` entry. Dropping is an explicit act — never delete or overwrite an item to get rid of it.

package/skills/04-idea-capture.md

@@ -1,65 +0,0 @@
----
-name: aidlc-idea
-description: Captures ideas into the .aidlc/ideas/ backlog at any moment — no instance, claim, or phase required — and browses or promotes backlog ideas into lifecycle instances
-phase: ideation
-priority: 90
-trigger: When the user says "idea:", asks to capture/record an idea, wants to browse the idea backlog, or wants to promote an idea into an instance
-native_mode_hint:
-  claude-code: >-
-    This skill is an interactive inbox, not a phase artifact. Do not enter
-    plan mode. Capture is a single write-and-confirm; never touch instance
-    state while capturing.
----
-# Idea Capture and Backlog
-
-> {{glossary:instance}}
-
-`.aidlc/ideas/` is a first-class inbox, independent of every lifecycle phase. Ideas are captured cheaply now and converted into instances later. Capture is legal at any moment: mid-implementation on another instance, from a second session, or with no instance at all.
-
-## Idea File Format
-
-One file per idea: `.aidlc/ideas/YYYYMMDD-<slug>.md`, beginning with exactly this frontmatter:
-
-```yaml
----
-status: raw          # raw | promoted | dropped
-promoted_to: null    # instance name once promoted, else null
-depends_on: []       # optional — ideas this one builds on, by file name without .md
----
-```
-
-Ideas never silently vanish — they are `raw`, `promoted`, or explicitly `dropped` (the file stays in place). `status: promoted` always carries a non-null `promoted_to` naming an existing instance.
-
-`depends_on` lists other backlog ideas whose outcome this one builds on (e.g. `20260815-traceability-ids`). It is optional and defaults to empty. Build order is derived from this graph when needed — there is no global `order` field to maintain, because concurrent capture from independent sessions cannot coordinate a sequence.
-
-## Capture
-
-1. **Resolve the backlog root.** Always write to the **primary checkout's** `.aidlc/ideas/`, never a worktree's copy: resolve via `git rev-parse --git-common-dir` (the directory containing that path is the primary checkout). Outside a git repo, use the current project root. Create `.aidlc/ideas/` if missing.
-2. **Name the file.** `YYYYMMDD-<slug>.md` — today's date plus a short (2–4 word) slug derived from the idea.
-3. **Handle collisions.** If the filename already exists, ask one question — extend `<existing>` or new idea? On extend, append a dated `## Update (YYYY-MM-DD)` section; on new, suffix the slug (`-2`). Never silently overwrite.
-4. **Write the file.** Frontmatter (`status: raw`, `promoted_to: null`), then `# Idea: <title>`, `**Date:**`, and the braindump organized lightly (a Use Case section plus whatever structure the content suggests). If the braindump itself references other backlog ideas, record them in `depends_on`; never ask for dependencies — the field is optional. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
-5. **Confirm and return.** Report the file path and return to whatever was happening.
-
-**Hard rule:** capture never reads or writes anything under `.aidlc/state/` — no claims, no phase files, no transitions log. Two sessions capturing simultaneously just produce two files; no locking exists or is needed. Do not auto-commit; staging is the user's.
-
-If the user includes credentials, tokens, or secrets in a braindump, flag it and omit them from the file.
-
-## Browse
-
-List `.aidlc/ideas/*.md` reading only frontmatter and the `# Idea:` title line — not the bodies. Show each idea's date, title, status, and dependencies (`depends_on`). Flag raw ideas whose dependencies are all promoted — those are the natural next candidates. Offer to open, promote, or drop.
-
-## Promote
-
-Promotion is where the backlog meets the lifecycle:
-
-> {{glossary:scope}}
-
-1. If the idea's `depends_on` names ideas that are still `raw`, say so and confirm before proceeding — promoting out of order is allowed but should be deliberate.
-2. Choose a template and scope as usual (defaults from `.aidlc/config.yaml`; see **aidlc-getting-started**).
-3. Create the instance per "Creating an Instance" in **aidlc-overview** — including firing `on-instance-start` lifecycle actions.
-4. Seed the instance with the idea file: Full scope → the idea is raw material the Ideation phase refines into that phase's required artifact (`idea.md` for the feature templates, `research-question.md` for `spike`); Standard scope → the idea is input context for Requirements.
-5. Update the idea's frontmatter: `status: promoted`, `promoted_to: <instance-name>`.
-
-## Drop
-
-Set `status: dropped` in the frontmatter and leave the file in place. Dropping is an explicit act — never delete or overwrite an idea to get rid of it.