@rasensio/aidlc-content 0.6.0 → 0.7.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": "0.7.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/00-overview.md

@@ -52,6 +52,39 @@ 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. Report the instance name, phases, and state path, then begin the initial phase with its skill.
+
 ## 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/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)