@rasensio/aidlc-content 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/00-overview.md

@@ -41,10 +41,11 @@ All state lives in `.aidlc/state/<instance-name>/`. Read and write state as foll
 ### Writing State
 
 1. **Before mutating state**, check for an existing Instance_Claim in `instance.yaml`. If another session holds the claim and it is not stale, warn and request override confirmation.
-2. Record your session identifier in the claim fields when you begin work.
+2. Claim with `aidlc claim <instance>` (release with `aidlc release <instance>`) — it updates `instance.yaml` and appends the claim event to `sessions.ndjson` in one step. Without the CLI, do both writes yourself: set the claim fields in `instance.yaml`, then append `{"event":"claim|release","session_id":"...","id_source":"agent","agent":"<platform>","timestamp":"<ISO 8601 UTC>"}` to `.aidlc/state/<instance>/sessions.ndjson`. Never rewrite that file — append only. If the CLI warns your claim is near timeout, run `aidlc claim --renew <instance>`.
 3. Update phase state files as you produce artifacts.
-4. Append a transition record to `transitions.log` only on successful phase transitions.
+4. Append a transition record to `transitions.log` only on successful phase transitions. When completing a phase, set `metrics.elapsed_seconds` in its `phase-<name>.yaml` from `entered_at` → `completed_at` — cost and time reports read it.
 5. After a successful phase transition, fire lifecycle actions: `on-phase-exit` for the phase you left, then `on-phase-enter` for the phase you entered (see **Lifecycle Actions**).
+6. **Cost fallback (once per session):** run `aidlc cost providers status`. If no metered provider is ACTIVE for your platform, then at each phase transition record usage via `aidlc cost record --manual --instance <name> --session - --fidelity estimated --units '<json>'` when your platform surfaces usage numbers to you (e.g. a per-turn credit trailer), else `--fidelity unknown` (no `--units`). Never invent numbers — an `unknown` interval marker lets `aidlc cost sync` attribute usage later.
 
 ### Transition Records
 
@@ -109,6 +110,10 @@ 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
+
+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.
+
 ## Context and Guidance
 
 - Project context lives in `.aidlc/context/` (style-guide.md, architecture.md)

package/skills/03-entry-point.md

@@ -23,6 +23,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.
 
 Do not read artifact bodies or transition history to build the menu — the compact state files are enough.
 
@@ -32,13 +33,15 @@ 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").
 - **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 two options: start something new, or help.
+If `.aidlc/state/` is empty or missing, offer just three options: start something new, capture an idea, or help.
 
 ## Step 3 — Route
 
@@ -46,7 +49,9 @@ If `.aidlc/state/` is empty or missing, offer just two options: start something
 |--------|--------|
 | Continue an instance | Follow the **aidlc-continue** skill |
 | Start something new | Ask what they are building, pick a template (see **aidlc-getting-started**), then create the instance per "Creating an Instance" in **aidlc-overview** |
-| Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled |
+| 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") |
 | Review an artifact | Follow the **aidlc-review** skill |
 | Help / getting started | Follow the **aidlc-getting-started** skill |
 

package/skills/04-idea-capture.md

@@ -0,0 +1,61 @@
+---
+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
+
+`.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:
+
+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 `ideation.md`; 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.

package/skills/81-continue.md

@@ -21,7 +21,7 @@ Resume an in-progress lifecycle instance efficiently. Determine where work left
    - Check `renewed_at` against the staleness timeout (default: 60 minutes)
    - If stale: warn and request override confirmation before taking over
    - If active: warn and do NOT proceed without explicit override
-3. **Claim the instance.** Record your session identifier and timestamp in the claim fields.
+3. **Claim the instance.** Prefer `aidlc claim <instance>` — it sets the claim fields and appends the claim event to `sessions.ndjson` (the durable session↔instance record cost attribution depends on). Without the CLI, do both: record your session identifier and timestamp in the claim fields, then append the claim event to `.aidlc/state/<instance>/sessions.ndjson` (append-only; see the state protocol in **aidlc-overview**). Release the same way when you stop (`aidlc release <instance>`).
 4. **Determine next step.** Apply this priority:
    - If current phase has incomplete required artifacts → produce the next artifact
    - If current phase is complete but not transitioned → evaluate transition (check gates)