@rasensio/aidlc-content 1.26.1 → 1.27.0

package/package.json

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

package/skills/00-overview.md

@@ -220,3 +220,43 @@ Never store credentials, tokens, or secrets in state files or artifacts.
 - Read compact state files, not full artifacts, to determine progress
 - Use artifact summaries (`<artifact>.summary.md`) when available
 - Load only the skill for the current phase, not all skills at once
+
+### The context rule
+
+This is the canonical statement of the rule. Every phase skill points here instead of
+restating it, so there is no second copy to drift — and so the rule does not itself
+become resident bytes in seven places.
+
+**A phase boundary is where you start a fresh session.** Not a suggestion about tidiness:
+91% of what a lifecycle run costs is re-reading the conversation it is already carrying,
+and that carry only grows. Measured across 20,920 attributed records, average context per
+unit of work runs 80k tokens in ideation, 164k in requirements, 259k in implementation,
+395k in deployment and 791k in maintenance. Deployment is the most expensive phase in the
+lifecycle — more than implementation — not because it does more, but because it runs last
+and inherits everything before it. The one phase that reliably starts fresh does
+comparable work at 76k.
+
+Three things follow:
+
+1. **Cross a phase boundary in a new session** whenever the platform allows it. The
+   lifecycle is designed for this: state lives in files, not in the conversation.
+2. **Re-read only what the phase you are entering names.** Each phase skill lists exactly
+   that under *Entering in a fresh session*. The list is the whole list — an artifact not
+   on it is not needed to start, and reading it "for context" is the charge this rule
+   exists to avoid.
+3. **Check the budget when you are unsure**: `aidlc cost context` reports the context this
+   session is carrying against a budget (default 150,000 tokens, configurable as
+   `cost.context_budget_tokens`). It reads the transcript, so it answers before any cost
+   capture has run.
+
+**The budget never fails a gate and never blocks a transition.** Its whole force is that
+somebody read it out at the right moment — the same force the constitution has, and for
+the same reason. Going over budget is information, not a violation: a long
+implementation phase may legitimately exceed it. What is not legitimate is carrying
+requirements' conversation into deployment because nobody stopped to notice.
+
+A caveat worth stating, because it decides whether the rule is worth following: a fresh
+session re-reads some of what it would otherwise still hold, and that spends back part of
+the saving. Every phase list below is bounded for exactly that reason. If re-reading turns
+out to cost more than a third of the saving, the threshold should move — measure it rather
+than assuming either way.

package/skills/10-ideation.md

@@ -17,6 +17,17 @@ Explore the problem space before committing to a solution. Define what we are bu
 - A lifecycle instance has been created with a Full scope
 - The instance is claimed by this session
 
+### Entering in a fresh session
+
+Ideation is the cheapest phase to enter because it inherits nothing. Read only:
+
+- `instance.yaml` — template, scope, current phase
+- the roadmap item this instance was promoted from, if any
+- `.aidlc/context/constitution.md`, when it exists
+
+Nothing else. There is no prior artifact to re-read; that is the whole advantage of
+starting here. See **The context rule** in **aidlc-overview** for why this list is a list.
+
 ## Required Artifacts
 
 The artifacts your template's ideation phase declares in `required_artifacts` — `idea.md` for the

package/skills/20-requirements.md

@@ -17,6 +17,20 @@ Translate the ideation output (or the user's direct request) into precise, testa
 - Ideation phase complete (Full scope) OR instance created with Standard scope
 - The instance is claimed by this session
 
+### Entering in a fresh session
+
+Read only:
+
+- `instance.yaml`
+- the ideation artifact (`idea.md`, or `research-question.md` for `spike`) — Full scope only
+- the roadmap item this instance was promoted from — Standard scope, where it replaces the
+  ideation artifact as input
+- the guidance layers named in `.aidlc/guidance/index.yaml`
+- `.aidlc/context/constitution.md`, when it exists
+
+Not the ideation *conversation* — the artifact is what it was written for.
+See **The context rule** in **aidlc-overview**.
+
 ## Required Artifacts
 
 - `requirements.md` — User stories, acceptance criteria, scope boundaries, non-functional requirements

package/skills/30-design.md

@@ -17,6 +17,20 @@ Produce a technical design that satisfies the requirements. Define architecture,
 - Requirements phase complete
 - The instance is claimed by this session
 
+### Entering in a fresh session
+
+Read only:
+
+- `instance.yaml`
+- `requirements.md` — in full; the acceptance criteria are what the design is traced against
+- the guidance layers named in `.aidlc/guidance/index.yaml`
+- `.aidlc/context/architecture.md` and `style-guide.md`
+- `.aidlc/context/constitution.md`, when it exists
+
+The seams the requirements touch are then read from the *source*, as step 3 of the
+instructions says — a handful of files, not a survey, and not the previous phase's
+transcript. See **The context rule** in **aidlc-overview**.
+
 ## Required Artifacts
 
 - `design.md` — Architecture overview, component design, interfaces, data flow, and design decisions with rationale

package/skills/40-implementation.md

@@ -17,6 +17,20 @@ Produce working code that satisfies the design and requirements. Follow project
 - Design phase complete (Full/Standard scope) OR instance created with Micro scope (task description + criteria exist)
 - The instance is claimed by this session
 
+### Entering in a fresh session
+
+Read only:
+
+- `instance.yaml`
+- `tasks.md` — the next unchecked task is where work resumes
+- `design.md` — the sections the next task cites, not the whole document once tasks are
+  under way
+- `requirements.md` — the acceptance criteria the next task claims
+- the guidance layers named in `.aidlc/guidance/index.yaml`
+- `.aidlc/context/style-guide.md`
+
+Then the source files that task touches. See **The context rule** in **aidlc-overview**.
+
 ## Required Artifacts
 
 - Source code changes implementing the feature or fix

package/skills/50-testing.md

@@ -15,6 +15,20 @@ Verify that the implementation satisfies all acceptance criteria. Produce eviden
 - Implementation phase complete
 - The instance is claimed by this session
 
+### Entering in a fresh session
+
+Testing averages 344k tokens today, more than twice implementation's start, almost entirely
+inherited. Read only:
+
+- `instance.yaml`
+- `requirements.md` — the acceptance criteria, which are what tests are traced to
+- `code-complete.md` — what implementation says it delivered
+- `tasks.md` — which tasks claim which criteria
+
+Not `design.md`: the design's job ended when the code existed, and the test verifies the
+code against the *requirements*. Not the implementation conversation.
+See **The context rule** in **aidlc-overview**.
+
 ## Required Artifacts
 
 - Test files covering acceptance criteria

package/skills/60-deployment.md

@@ -19,6 +19,26 @@ Prepare and execute the release. Ensure all preceding phases are complete, all g
   security review phase)
 - The instance is claimed by this session
 
+### Entering in a fresh session
+
+**Start deployment in a fresh session.** This phase has the most to gain from it of any in
+the lifecycle: it averages 395k tokens per unit of work and is the single most expensive
+phase — ahead of implementation — not because it does more, but because it runs last and
+inherits every phase before it.
+
+Read only:
+
+- `instance.yaml` and the `phase-*.yaml` files — what is complete, and what this phase must
+  assert
+- `test-results.md` — the pass/fail record the release depends on
+- the review findings file — the security sign-off named in the entry criteria above
+- `tasks.md` — deferred tasks belong in the deployment record
+
+Not `requirements.md`, not `design.md`, not `code-complete.md`. The release is prepared from
+what the *preceding phases concluded*, and each of those conclusions is already a compact
+artifact. Read one of them only if a specific question sends you there.
+See **The context rule** in **aidlc-overview**.
+
 ## Required Artifacts
 
 The artifacts your template's deployment phase declares in `required_artifacts` —

package/skills/70-maintenance.md

@@ -17,6 +17,20 @@ Ensure the deployed feature remains healthy. Update documentation, address feedb
 - Deployment phase complete
 - The instance is claimed by this session
 
+### Entering in a fresh session
+
+**Always start maintenance in a fresh session.** At 791k tokens per unit of work it is by a
+wide margin the most expensive phase to run, and it is open-ended — so a carried prefix here
+is not paid once but on every turn for as long as the instance stays open.
+
+Read only:
+
+- `instance.yaml`
+- `deployment-record.md` — what shipped, and what was deferred
+- whatever the specific maintenance question sends you to
+
+Nothing from before deployment by default. See **The context rule** in **aidlc-overview**.
+
 ## Required Artifacts
 
 The artifacts your template's maintenance phase declares in `required_artifacts` —

package/skills/80-review.md

@@ -24,7 +24,13 @@ You MUST perform this review with fresh eyes. If you authored the artifact being
 
 ## Required Artifacts
 
-- `<artifact>.review.md` — Structured findings file in the instance namespace
+- `<artifact>.review.md` — Structured findings file in the instance namespace, where
+  **`<artifact>` includes the artifact's own `.md`**. The findings file for
+  `requirements.md` is `requirements.md.review.md`, with the extension twice. The
+  doubled `.md` looks like a typo and is not: the gate looks artifacts up by the name
+  the template declares, so `requirements.review.md` is a file the gate cannot see.
+  `aidlc review <instance> requirements` and `aidlc review <instance> requirements.md`
+  both write the correct name, so prefer the command over hand-naming the file.
 
 Write **one findings file per required artifact** of the phase under review. The phase's required artifacts are listed in `phase-<name>.yaml` in the instance directory — read them from there rather than from a list in this skill, because they vary per template and a project may override a template under `.aidlc/templates/`.
 

package/skills/81-continue.md

@@ -35,10 +35,15 @@ Resume an in-progress lifecycle instance efficiently. Determine where work left
    - If the transition is the instance's **completion moment** (last applicable phase for the template × scope reaches complete; for maintenance-terminal instances, maintenance *entry*) → run the **aidlc-retrospective** skill before any cleanup, then fire `on-instance-complete`
    - If all phases complete → report instance complete; if no `retrospective.md` exists, offer the retro
 5. **Load minimal context.** Read only:
-   - The skill for the determined phase
+   - The skill for the determined phase, and specifically its *Entering in a fresh session* list
    - Artifact summaries (`.summary.md`) instead of full artifacts where available
    - Compact state files, not full transition history
-6. **Execute.** Follow the phase skill for the determined step.
+6. **Say where context stands when a phase boundary was just crossed.** If step 4 moved the
+   instance to a new phase, run `aidlc cost context` and report the line it prints. Crossing a
+   boundary is the one moment a fresh session is free, and the reading is what makes that
+   visible instead of leaving it to be noticed on the bill. Over budget is information, never a
+   blocker — see **The context rule** in **aidlc-overview**.
+7. **Execute.** Follow the phase skill for the determined step.
 
 ## Multiple Instances