@rasensio/aidlc-content 0.6.0 → 1.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @rasensio/aidlc-content
+
+Knowledge layer for the [AIDLC](https://github.com/rasensio/aidlc) framework. Contains skills, templates, guidance documents, capability maps, and phase definitions.
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/rasensio/aidlc/blob/main/LICENSE)
+
+## What This Package Contains
+
+This is the single source of truth for what AIDLC knows about lifecycle phases:
+
+- **Skills** — Phase-specific markdown documents that activate inside AI coding tools during the appropriate lifecycle phase
+- **Templates** — Define which phases apply to a given workflow (full feature, quick task, bug fix, spike)
+- **Guidance** — Detailed guidance layers for quality, security, and best practices
+- **Capabilities** — Capability maps for each supported AI platform
+- **Phases** — Phase definitions with entry/exit criteria and gate requirements
+
+## Usage
+
+This package is consumed by the [`@rasensio/aidlc`](https://www.npmjs.com/package/@rasensio/aidlc) CLI, which compiles these content assets into platform-native formats.
+
+```typescript
+import { loadSkills, loadTemplates } from '@rasensio/aidlc-content';
+
+const skills = await loadSkills();
+const templates = await loadTemplates();
+```
+
+## How It Fits Together
+
+```
+@rasensio/aidlc-content (this package)
+    │
+    ├──► CLI compiles ──► platform-specific output (.claude/, .cursor/, .kiro/, …)
+    │
+    └──► web consumes ──► documentation site
+```
+
+The CLI reads content at compile time to produce installable artifacts. The web package reads it at build time to generate documentation pages.
+
+## Direct Usage
+
+Most users should install `@rasensio/aidlc` (the CLI) rather than this package directly. This package is primarily a dependency of the CLI and is published separately for workspace resolution.
+
+## License
+
+[MIT](https://github.com/rasensio/aidlc/blob/main/LICENSE)

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export { loadTemplates, getTemplate } from './templates.js';
 export { loadGuidance } from './guidance.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
-export type { Skill, WorkflowTemplate, GuidanceLayer, CapabilityMap, PhaseDefinition } from './types.js';
+export { loadTutorials, getTutorial, parseTutorialSource } from './tutorials.js';
+export type { Skill, WorkflowTemplate, GuidanceLayer, CapabilityMap, PhaseDefinition, CodeSample, ContentReference, TutorialStep, Tutorial } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACjF,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -3,4 +3,5 @@ export { loadTemplates, getTemplate } from './templates.js';
 export { loadGuidance } from './guidance.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
+export { loadTutorials, getTutorial, parseTutorialSource } from './tutorials.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/tutorials.d.ts

@@ -0,0 +1,9 @@
+import type { Tutorial } from './types.js';
+/**
+ * Parse a raw tutorial markdown string into a Tutorial object.
+ * Useful for testing without filesystem access.
+ */
+export declare function parseTutorialSource(raw: string): Tutorial;
+export declare function loadTutorials(): Tutorial[];
+export declare function getTutorial(slug: string): Tutorial | undefined;
+//# sourceMappingURL=tutorials.d.ts.map

package/dist/tutorials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.d.ts","sourceRoot":"","sources":["../src/tutorials.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAA8C,MAAM,YAAY,CAAC;AAqHvF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAiBzD;AAED,wBAAgB,aAAa,IAAI,QAAQ,EAAE,CAgC1C;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAE9D"}

package/dist/tutorials.js

@@ -0,0 +1,141 @@
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+const CONTENT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TUTORIALS_DIR = resolve(CONTENT_ROOT, 'tutorials');
+const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const STEP_HEADING_PATTERN = /^## Step (\d+): (.+)$/gm;
+const CONTENT_REF_PATTERN = /\{\{ref:(skill|template|phase|guidance)\/([^}]+)\}\}/g;
+const CODE_BLOCK_PATTERN = /```(\w+)(?:\s+source=(\S+))?\n([\s\S]*?)```/g;
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match) {
+        throw new Error('Missing YAML frontmatter');
+    }
+    const parsed = parseYaml(match[1]);
+    const body = match[2];
+    const title = parsed['title'];
+    const description = parsed['description'];
+    const order = parsed['order'];
+    const slug = parsed['slug'];
+    if (typeof title !== 'string' || title.length === 0 || title.length > 100) {
+        throw new Error(`Invalid title: must be a string of 1-100 characters`);
+    }
+    if (typeof description !== 'string' || description.length === 0 || description.length > 300) {
+        throw new Error(`Invalid description: must be a string of 1-300 characters`);
+    }
+    if (typeof order !== 'number' || !Number.isInteger(order) || order < 1 || order > 999) {
+        throw new Error(`Invalid order: must be an integer between 1 and 999`);
+    }
+    if (typeof slug !== 'string' || slug.length === 0 || slug.length > 80 || !SLUG_PATTERN.test(slug)) {
+        throw new Error(`Invalid slug: must be lowercase alphanumeric with hyphens, max 80 characters`);
+    }
+    return {
+        frontmatter: { title, description, order, slug },
+        body,
+    };
+}
+function extractCodeSamples(body) {
+    const samples = [];
+    let match;
+    const pattern = new RegExp(CODE_BLOCK_PATTERN.source, CODE_BLOCK_PATTERN.flags);
+    while ((match = pattern.exec(body)) !== null) {
+        const sample = {
+            language: match[1],
+            code: match[3],
+        };
+        if (match[2]) {
+            sample.source = match[2];
+        }
+        samples.push(sample);
+    }
+    return samples;
+}
+function extractContentReferences(body) {
+    const refs = [];
+    let match;
+    const pattern = new RegExp(CONTENT_REF_PATTERN.source, CONTENT_REF_PATTERN.flags);
+    while ((match = pattern.exec(body)) !== null) {
+        refs.push({
+            entityType: match[1],
+            entityName: match[2],
+            raw: match[0],
+        });
+    }
+    return refs;
+}
+function parseSteps(body) {
+    const steps = [];
+    const headings = [];
+    let match;
+    const pattern = new RegExp(STEP_HEADING_PATTERN.source, STEP_HEADING_PATTERN.flags);
+    while ((match = pattern.exec(body)) !== null) {
+        headings.push({
+            index: parseInt(match[1], 10),
+            position: match.index,
+            title: match[2],
+        });
+    }
+    for (let i = 0; i < headings.length; i++) {
+        const heading = headings[i];
+        const start = heading.position + body.slice(heading.position).indexOf('\n') + 1;
+        const end = i + 1 < headings.length ? headings[i + 1].position : body.length;
+        const stepBody = body.slice(start, end).trim();
+        steps.push({
+            index: i,
+            title: heading.title,
+            body: stepBody,
+            codeSamples: extractCodeSamples(stepBody),
+            contentReferences: extractContentReferences(stepBody),
+        });
+    }
+    return steps;
+}
+/**
+ * Parse a raw tutorial markdown string into a Tutorial object.
+ * Useful for testing without filesystem access.
+ */
+export function parseTutorialSource(raw) {
+    const { frontmatter, body } = parseFrontmatter(raw);
+    const steps = parseSteps(body);
+    if (steps.length < 1 || steps.length > 50) {
+        throw new Error(`Tutorial must have between 1 and 50 steps, found ${steps.length}`);
+    }
+    return {
+        title: frontmatter.title,
+        description: frontmatter.description,
+        order: frontmatter.order,
+        slug: frontmatter.slug,
+        steps,
+    };
+}
+export function loadTutorials() {
+    if (!existsSync(TUTORIALS_DIR)) {
+        return [];
+    }
+    const files = readdirSync(TUTORIALS_DIR).filter(f => f.endsWith('.md')).sort();
+    if (files.length === 0) {
+        return [];
+    }
+    const tutorials = files.map(filename => {
+        const raw = readFileSync(resolve(TUTORIALS_DIR, filename), 'utf8');
+        const { frontmatter, body } = parseFrontmatter(raw);
+        const steps = parseSteps(body);
+        if (steps.length < 1 || steps.length > 50) {
+            throw new Error(`Tutorial "${filename}": must have between 1 and 50 steps, found ${steps.length}`);
+        }
+        return {
+            title: frontmatter.title,
+            description: frontmatter.description,
+            order: frontmatter.order,
+            slug: frontmatter.slug,
+            steps,
+        };
+    });
+    return tutorials.sort((a, b) => a.order - b.order);
+}
+export function getTutorial(slug) {
+    return loadTutorials().find(t => t.slug === slug);
+}
+//# sourceMappingURL=tutorials.js.map

package/dist/tutorials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.js","sourceRoot":"","sources":["../src/tutorials.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -28,4 +28,28 @@ export interface PhaseDefinition {
     purpose: string;
     exitCriteria: string[];
 }
+export interface CodeSample {
+    language: string;
+    code: string;
+    source?: string;
+}
+export interface ContentReference {
+    entityType: 'skill' | 'template' | 'phase' | 'guidance';
+    entityName: string;
+    raw: string;
+}
+export interface TutorialStep {
+    index: number;
+    title: string;
+    body: string;
+    codeSamples: CodeSample[];
+    contentReferences: ContentReference[];
+}
+export interface Tutorial {
+    title: string;
+    description: string;
+    order: number;
+    slug: string;
+    steps: TutorialStep[];
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB"}

package/package.json

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

package/skills/00-overview.md

@@ -44,6 +44,7 @@ All state lives in `.aidlc/state/<instance-name>/`. Read and write state as foll
 2. Record your session identifier in the claim fields when you begin work.
 3. Update phase state files as you produce artifacts.
 4. Append a transition record to `transitions.log` only on successful phase transitions.
+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**).
 
 ### Transition Records
 
@@ -52,6 +53,62 @@ Each line in `transitions.log` is a JSON object:
 {"timestamp":"<ISO 8601 UTC>","author":"<session-id>","from":"<phase>","to":"<phase>","type":"normal|skip|upgrade","criteria":["..."]}
 ```
 
+### Creating an Instance
+
+The `aidlc start` CLI automates this; when it is not available, create the instance directly:
+
+1. Pick a template and scope (see **aidlc-getting-started** for template selection and per-template artifacts). The initial phase follows the scope: full → ideation, standard → requirements, micro → implementation.
+2. Choose a URL-safe instance name and create `.aidlc/state/<name>/`. If the directory already exists, stop and ask for a different name.
+3. Write `instance.yaml`:
+   ```yaml
+   name: <instance-name>
+   template: <template-name>
+   scope: <full|standard|micro>
+   created_at: <ISO 8601 UTC>
+   created_by: <session-id or username>
+   current_phase: <initial-phase>
+   claim: null
+   scope_history: []
+   ```
+4. For each phase the template defines within the scope, write `phase-<name>.yaml`:
+   ```yaml
+   phase: <phase-name>
+   status: pending
+   owner: null
+   entered_at: null
+   completed_at: null
+   completed_by: null
+   skip_reason: null
+   artifacts:
+     - name: <artifact>.md
+       status: not-started
+   metrics: { elapsed_seconds: 0, artifact_count: 0 }
+   ```
+5. Fire the `on-instance-start` lifecycle actions (see **Lifecycle Actions**). Do not skip this — automation the user configured (branch creation, issue tracking, notifications) depends on it.
+6. Report the instance name, phases, state path, and any actions that fired, then begin the initial phase with its skill.
+
+## Lifecycle Actions
+
+`.aidlc/actions.yaml` declares automation the user wants to run on lifecycle events. The `aidlc` CLI fires these automatically; **when you manage state directly (without the CLI), you are the event dispatcher** and must fire them yourself.
+
+On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exit`, `on-instance-complete`, `on-artifact-created`:
+
+1. Read `.aidlc/actions.yaml` (if absent, skip this protocol).
+2. Select actions where `enabled: true`, `event` matches, and any `phase` filter matches the current phase.
+3. For each matched action with a `run` script: execute it as a shell command with these environment variables set: `AIDLC_EVENT`, `AIDLC_INSTANCE`, `AIDLC_PHASE`, `AIDLC_TEMPLATE`.
+4. Actions marked `use` (built-ins) require the CLI — run `aidlc transition`/`aidlc start` for those, or tell the user the action needs the CLI.
+5. If an action fails and it is `blocking: true`, stop and report the failure to the user before continuing the lifecycle. If `blocking: false`, report and continue.
+6. Report every action you ran and its outcome — never run configured automation silently.
+
+## User Input Protocol (Inbox)
+
+When a phase needs substantial input from the user — open decisions, structured requirements, extensive details — write an Input_File to `.aidlc/inbox/` instead of asking many sequential chat questions or scattering files in ad-hoc locations (`temp/`, project root):
+
+1. Name the file `<instance>-<topic>.md` (e.g. `local-knowledge-graph-open-decisions.md`).
+2. Give each question its own section: plain-language background first (assume the user has not read the underlying spec), then the options as `- [ ]` checkboxes with trade-offs spelled out. Mark your recommendation.
+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.
+
 ## Context and Guidance
 
 - Project context lives in `.aidlc/context/` (style-guide.md, architecture.md)

package/skills/01-getting-started.md

@@ -22,56 +22,36 @@ Respond using this skill when the user asks any of the following:
 - "What template should I use?"
 - "Help me start working on X"
 
+## How Work Begins
+
+All lifecycle work runs on instances — YAML state under `.aidlc/state/<name>/`. You (the agent) create and manage them directly by following the state protocol in **aidlc-overview**; no terminal command is needed. The `aidlc` CLI remains an equivalent shortcut for users who prefer it (`aidlc start <template> --name <name>`).
+
 ## Quick Answers
 
 ### "How do I fix a bug?"
 
-1. Start a bugfix lifecycle instance:
-   ```
-   aidlc start bugfix --name <short-description>
-   ```
-2. This creates a focused workflow: reproduce the bug → fix it → test it → deploy.
-3. Run `aidlc continue <name>` to see what step to do next.
-4. The bugfix template skips the design phase and requires a `reproduction.md` artifact first.
+1. Create a lifecycle instance from the `bugfix` template (see "Creating an Instance" in **aidlc-overview**).
+2. This gives a focused workflow: reproduce the bug → fix it → test it → deploy. The bugfix template skips the design phase and requires a `reproduction.md` artifact first.
+3. Follow **aidlc-continue** at any point to pick up the next step.
 
 ### "How do I add a feature?"
 
-For a small, well-defined feature:
-```
-aidlc start quick-feature --name <feature-name>
-```
-
-For a larger feature needing design and review:
-```
-aidlc start full-feature --name <feature-name>
-```
-
-For something tiny (just code + test):
-```
-aidlc start micro-task --name <task-name>
-```
+Create an instance from the template that fits:
+- Small, well-defined feature → `quick-feature`
+- Larger feature needing design and review → `full-feature`
+- Something tiny (just code + test) → `micro-task`
 
 ### "How do I explore an idea or do research?"
 
-```
-aidlc start spike --name <research-topic>
-```
-This gives you Ideation + Requirements phases only — no implementation pressure.
+Create an instance from the `spike` template. This gives you Ideation + Requirements phases only — no implementation pressure.
 
 ### "What should I do next?"
 
-Run:
-```
-aidlc continue
-```
-This tells you exactly which artifact to produce or which phase to enter next.
+Follow the **aidlc-continue** skill: it reads the instance state and identifies exactly which artifact to produce or which phase to enter next. (CLI shortcut: `aidlc continue`.)
 
 ### "How do I check progress?"
 
-```
-aidlc status
-```
-Shows all active lifecycle instances with completion %, current phase, and stall detection.
+Read each instance's `instance.yaml` and `phase-<name>.yaml` files and summarize: current phase, completion percentage (complete artifacts ÷ required artifacts), and stalled instances. (CLI shortcut: `aidlc status`.)
 
 ### "How does the lifecycle work?"
 
@@ -94,16 +74,9 @@ Not every task needs all phases. The templates handle this:
 
 ### "How do I set up AIDLC in this project?"
 
-If AIDLC is already installed (you can see `.aidlc/skills/` in the project), just start using it:
-```
-aidlc start <template>
-```
+If AIDLC is already installed (you can see `.aidlc/skills/` in the project), just start using it: create an instance and begin.
 
-If not installed yet:
-```
-aidlc setup
-```
-This runs an interactive wizard that configures the framework for your project.
+If not installed yet, run `npx @rasensio/aidlc init` in a terminal. Installation is the one step that genuinely needs the CLI — it compiles the skills into your platform's native format and configures the project.
 
 ## Choosing the Right Template
 
@@ -115,13 +88,15 @@ This runs an interactive wizard that configures the framework for your project.
 | Just write code + test | `micro-task` | Micro |
 | Research / explore | `spike` | Ideation + Requirements |
 
+Template definitions (phases and required artifacts) live in the content package and can be overridden per-project under `.aidlc/templates/`.
+
 ## After Starting
 
-Once you've started an instance, the framework tracks your progress. At any point:
-- `aidlc continue` — what to do next
-- `aidlc status` — overall progress
-- `aidlc gate <instance> <phase>` — check if a phase is complete
-- `aidlc transition <instance>` — advance to the next phase
+Once an instance exists, the state files track your progress. At any point:
+- **aidlc-continue** skill — determine and execute the next step
+- Read state files — overall progress (see "How do I check progress?")
+- Gate check — a phase is complete when all its required artifacts are complete; `aidlc gate <phase>` provides the same check for CI
+- Transition — advance `current_phase` and append to `transitions.log` per the state protocol
 
 ## State Location
 

package/skills/03-entry-point.md

@@ -0,0 +1,56 @@
+---
+name: aidlc
+description: Entry point for AIDLC — reads lifecycle state and offers the next actions (continue an instance, start new work, check status, review an artifact)
+phase: ideation
+priority: 99
+trigger: When the user invokes the aidlc skill directly or asks what lifecycle actions are available
+native_mode_hint:
+  claude-code: >-
+    This skill is an interactive entry point, not a phase artifact. Do not
+    enter plan mode. Read lifecycle state, present the menu, and wait for
+    the user's choice before doing any work.
+---
+# AIDLC Entry Point
+
+This skill is the front door to the AIDLC framework. When invoked, show the user where their lifecycle work stands and let them choose what to do next. Everything needed is in `.aidlc/` — the CLI is not required at runtime.
+
+## Pre-condition: First Activation
+
+If `.aidlc/context/` does not exist or contains no `.md` files, defer to the **aidlc-first-activation** skill first, then return to the user's original request.
+
+## Step 1 — Read State
+
+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.
+
+Do not read artifact bodies or transition history to build the menu — the compact state files are enough.
+
+## Step 2 — Present the Menu
+
+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.
+- **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.
+
+## Step 3 — Route
+
+| Choice | Action |
+|--------|--------|
+| 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 |
+| Review an artifact | Follow the **aidlc-review** skill |
+| Help / getting started | Follow the **aidlc-getting-started** skill |
+
+## Rules
+
+- Building the menu is read-only — never mutate state while composing it. Claims are taken by the routed skill (see aidlc-continue).
+- Keep the menu short; do not explain the whole framework unless the user asks for help.

package/skills/10-ideation.md

@@ -21,16 +21,19 @@ Explore the problem space before committing to a solution. Define what we are bu
 
 ## Instructions
 
-1. **Clarify the problem.** Ask the user what they want to build and why. Identify the core need vs. nice-to-haves.
-2. **Explore constraints.** Document: timeline, technical constraints, platform limitations, team size, budget considerations.
-3. **Generate options.** Propose 2-3 approaches. For each, note trade-offs (complexity, time, risk).
-4. **Identify unknowns.** List open questions that need answers before requirements can be written.
-5. **Summarize.** Write `ideation.md` with sections: Problem Statement, Goals, Constraints, Explored Options, Open Questions.
+1. **Consult the knowledge graph first.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase ideation` before exploring the codebase — the graph is the first source of understanding; re-explore only what it doesn't cover.
+2. **Clarify the problem.** Ask the user what they want to build and why. Identify the core need vs. nice-to-haves.
+3. **Explore constraints.** Document: timeline, technical constraints, platform limitations, team size, budget considerations.
+4. **Generate options.** Propose 2-3 approaches. For each, note trade-offs (complexity, time, risk).
+5. **Identify unknowns.** List open questions that need answers before requirements can be written.
+6. **Record discoveries in the knowledge graph.** Persist what you learned about the codebase with `aidlc knowledge add` / `relate` (modules, services, conventions, debt). On a brownfield project, seed the graph first with `aidlc discover`. The phase gate requires at least 3 module entities, 2 depends-on relationships, and 1 convention entity.
+7. **Summarize.** Write `ideation.md` with sections: Problem Statement, Goals, Constraints, Explored Options, Open Questions.
 
 ## Exit Criteria
 
 - `ideation.md` exists and contains at minimum a problem statement and one defined goal
 - The user has confirmed the direction (which option to pursue or a synthesis)
+- When the project uses the knowledge graph: it contains ≥3 module entities, ≥2 depends-on relationships, and ≥1 convention entity (checked automatically by `aidlc gate` / `aidlc transition`)
 
 ## Guidance
 

package/skills/20-requirements.md

@@ -29,7 +29,7 @@ Translate the ideation output (or the user's direct request) into precise, testa
    - Independent (not relying on unstated assumptions)
 4. **Set scope boundaries.** Explicitly state what is NOT included.
 5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
-6. **For complex input**: If requirements are extensive, create an Input_File at `.aidlc/inbox/requirements-input.md` with structured sections for the user to fill in, rather than asking many sequential questions.
+6. **For complex input or open decisions**: If requirements are extensive, or unresolved decisions block the draft, create an Input_File in `.aidlc/inbox/` following the User Input Protocol in **aidlc-overview**, rather than asking many sequential questions. Prefer drafting `requirements.md` early with unresolved points marked as explicit decision blocks — users decide better reacting to a concrete draft than answering abstract questions.
 
 ## Exit Criteria
 

package/skills/30-design.md

@@ -22,12 +22,13 @@ Produce a technical design that satisfies the requirements. Define architecture,
 ## Instructions
 
 1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges.
-2. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
-3. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
-4. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.
-5. **Design decisions.** Record each significant decision with rationale and alternatives considered.
-6. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
-7. **Identify risks.** Note technical risks and mitigation strategies.
+2. **Consult the knowledge graph.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions before re-deriving them from code.
+3. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
+4. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
+5. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.
+6. **Design decisions.** Record each significant decision with rationale and alternatives considered. Persist accepted decisions as `decision` entities: `aidlc knowledge add --type decision --id <slug> --name "<title>" --description "<rationale>"`.
+7. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
+8. **Identify risks.** Note technical risks and mitigation strategies.
 
 ## Exit Criteria
 

package/skills/40-implementation.md

@@ -22,7 +22,7 @@ Produce working code that satisfies the design and requirements. Follow project
 
 ## Instructions
 
-1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns.
+1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns. If the project has a knowledge graph (`.aidlc/knowledge/` exists), also run `aidlc knowledge context --scope phase --phase implementation` and query it (`aidlc knowledge query <term>`) before re-exploring code it already describes.
 2. **Load guidance.** Read all active Guidance_Layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
 3. **Plan the work.** Break the implementation into discrete steps. For Micro scope, reference the task description and acceptance criteria directly.
 4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
@@ -32,7 +32,8 @@ Produce working code that satisfies the design and requirements. Follow project
    - Permission or access control modifications
    - Credential or secret handling
 6. **Commit incrementally.** Produce working code at each step; avoid large uncommittable diffs.
-7. **Update state.** As implementation artifacts are produced, mark them in `phase-implementation.yaml`.
+7. **Update the knowledge graph.** After modifying code, record what changed with `aidlc knowledge add` / `relate` / `update`: new or restructured modules, decisions taken, debt introduced or paid down. Keep the graph in sync with the code you just changed.
+8. **Update state.** As implementation artifacts are produced, mark them in `phase-implementation.yaml`.
 
 ## Exit Criteria
 

package/skills/60-deployment.md

@@ -23,7 +23,7 @@ Prepare and execute the release. Ensure all preceding phases are complete, all g
 
 ## Instructions
 
-1. **Validate readiness.** Run `aidlc gate deployment` (or check state manually): every preceding required phase must be complete. If any gate fails, address the gap before proceeding.
+1. **Validate readiness.** Check the phase state files: every preceding required phase must be complete (all required artifacts `complete`). If any gate fails, address the gap before proceeding. (CLI shortcut: `aidlc gate deployment`.)
 2. **Write release plan.** Document in `deployment.md`:
    - What is being deployed (version, changes summary)
    - Target environment(s)

package/skills/70-maintenance.md

@@ -27,7 +27,7 @@ Ensure the deployed feature remains healthy. Update documentation, address feedb
    - Architecture docs updated if new components were added
    - API docs updated if endpoints changed
 3. **Gather feedback.** Collect user/team feedback on the delivered feature.
-4. **Record known issues.** Document any edge cases, limitations, or technical debt introduced.
+4. **Record known issues.** Document any edge cases, limitations, or technical debt introduced. If the project has a knowledge graph, record debt as entities (`aidlc knowledge add --type debt …`) and update facts invalidated by code changes (`aidlc knowledge update` / `verify`); list candidates with `aidlc knowledge stale --check-git`.
 5. **Plan follow-up.** If feedback or monitoring reveals needed improvements, document them as potential future lifecycle instances.
 6. **Close the instance.** When maintenance tasks are complete, mark the lifecycle instance as done.