@rasensio/aidlc 0.1.0

package/dist/state/yaml-helpers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * YAML load/save helpers with deterministic serialization and schema validation.
+ *
+ * - `loadYaml<T>()` loads and optionally validates a YAML file.
+ * - `saveYaml()` serializes data deterministically (stable key order, block style)
+ *   so that single-field changes produce minimal git diffs (≤ 3 lines).
+ *
+ * Requirements: 4.2 (minimal diffs), 4.7 (validation errors name the file).
+ */
+/**
+ * A lightweight schema validator function.
+ * Returns null/undefined when valid, or an error message string on failure.
+ */
+export type SchemaValidator<T = unknown> = (data: unknown) => string | null | undefined;
+/**
+ * Error thrown when YAML loading or validation fails.
+ * Always includes the file path and a description of the failure.
+ */
+export declare class YamlLoadError extends Error {
+    readonly filePath: string;
+    readonly reason: string;
+    constructor(filePath: string, reason: string);
+}
+/**
+ * Load a YAML file, parse it, and optionally validate the result.
+ *
+ * @param filePath - Absolute or relative path to the YAML file.
+ * @param validate - Optional validator; receives parsed data, returns error string on failure.
+ * @returns The parsed (and validated) data cast to `T`.
+ * @throws {YamlLoadError} If the file is missing, unparseable, or fails validation.
+ */
+export declare function loadYaml<T = unknown>(filePath: string, validate?: SchemaValidator<T>): T;
+/**
+ * Serialize `data` to YAML with deterministic output and write it to `filePath`.
+ *
+ * Deterministic properties:
+ * - Stable key order (sorted alphabetically).
+ * - Block style for readability.
+ * - No line wrapping — one scalar per line.
+ * - Repeated calls with the same data produce byte-identical output.
+ *
+ * Creates parent directories if they don't exist.
+ *
+ * @param filePath - Absolute or relative path for the output file.
+ * @param data - The data to serialize.
+ */
+export declare function saveYaml(filePath: string, data: unknown): void;
+/**
+ * Serialize data to a YAML string with deterministic formatting.
+ * Exported for testing without filesystem side effects.
+ */
+export declare function serializeYaml(data: unknown): string;
+//# sourceMappingURL=yaml-helpers.d.ts.map

package/dist/state/yaml-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-helpers.d.ts","sourceRoot":"","sources":["../../src/state/yaml-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAMxF;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAEpB,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAKjC;AAMD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CA2BxF;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAI9D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEnD"}

package/dist/state/yaml-helpers.js

@@ -0,0 +1,110 @@
+/**
+ * YAML load/save helpers with deterministic serialization and schema validation.
+ *
+ * - `loadYaml<T>()` loads and optionally validates a YAML file.
+ * - `saveYaml()` serializes data deterministically (stable key order, block style)
+ *   so that single-field changes produce minimal git diffs (≤ 3 lines).
+ *
+ * Requirements: 4.2 (minimal diffs), 4.7 (validation errors name the file).
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { stringify, parse } from 'yaml';
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/**
+ * Error thrown when YAML loading or validation fails.
+ * Always includes the file path and a description of the failure.
+ */
+export class YamlLoadError extends Error {
+    filePath;
+    reason;
+    constructor(filePath, reason) {
+        super(`${filePath}: ${reason}`);
+        this.filePath = filePath;
+        this.reason = reason;
+        this.name = 'YamlLoadError';
+    }
+}
+// ---------------------------------------------------------------------------
+// loadYaml
+// ---------------------------------------------------------------------------
+/**
+ * Load a YAML file, parse it, and optionally validate the result.
+ *
+ * @param filePath - Absolute or relative path to the YAML file.
+ * @param validate - Optional validator; receives parsed data, returns error string on failure.
+ * @returns The parsed (and validated) data cast to `T`.
+ * @throws {YamlLoadError} If the file is missing, unparseable, or fails validation.
+ */
+export function loadYaml(filePath, validate) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            throw new YamlLoadError(filePath, 'file not found');
+        }
+        throw new YamlLoadError(filePath, `unable to read file: ${err.message}`);
+    }
+    let data;
+    try {
+        data = parse(raw);
+    }
+    catch (err) {
+        throw new YamlLoadError(filePath, `YAML parse error: ${err.message}`);
+    }
+    if (validate) {
+        const error = validate(data);
+        if (error) {
+            throw new YamlLoadError(filePath, `validation failed: ${error}`);
+        }
+    }
+    return data;
+}
+// ---------------------------------------------------------------------------
+// saveYaml
+// ---------------------------------------------------------------------------
+/**
+ * YAML serialization options tuned for deterministic, git-friendly output.
+ *
+ * - `sortMapEntries`: alphabetical key ordering for stable output.
+ * - `blockQuote: 'literal'`: multiline strings use `|` (block literal).
+ * - `lineWidth: 0`: disable line wrapping so scalars stay on one line.
+ * - `defaultKeyType: 'PLAIN'` and `defaultStringType: 'PLAIN'` keep output readable.
+ */
+const SERIALIZE_OPTIONS = {
+    sortMapEntries: true,
+    blockQuote: 'literal',
+    lineWidth: 0,
+};
+/**
+ * Serialize `data` to YAML with deterministic output and write it to `filePath`.
+ *
+ * Deterministic properties:
+ * - Stable key order (sorted alphabetically).
+ * - Block style for readability.
+ * - No line wrapping — one scalar per line.
+ * - Repeated calls with the same data produce byte-identical output.
+ *
+ * Creates parent directories if they don't exist.
+ *
+ * @param filePath - Absolute or relative path for the output file.
+ * @param data - The data to serialize.
+ */
+export function saveYaml(filePath, data) {
+    const content = serializeYaml(data);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, 'utf8');
+}
+/**
+ * Serialize data to a YAML string with deterministic formatting.
+ * Exported for testing without filesystem side effects.
+ */
+export function serializeYaml(data) {
+    return stringify(data, SERIALIZE_OPTIONS);
+}
+//# sourceMappingURL=yaml-helpers.js.map

package/dist/state/yaml-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-helpers.js","sourceRoot":"","sources":["../../src/state/yaml-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAYxC,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAEpB;IACA;IAFlB,YACkB,QAAgB,EAChB,MAAc;QAE9B,KAAK,CAAC,GAAG,QAAQ,KAAK,MAAM,EAAE,CAAC,CAAC;QAHhB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAG9B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAc,QAAgB,EAAE,QAA6B;IACnF,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;QACtD,CAAC;QACD,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,wBAAyB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,qBAAsB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAS,CAAC,CAAC;QAClC,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,sBAAsB,KAAK,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,OAAO,IAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAG;IACxB,cAAc,EAAE,IAAI;IACpB,UAAU,EAAE,SAAkB;IAC9B,SAAS,EAAE,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,IAAa;IACtD,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACpC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,SAAS,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;AAC5C,CAAC"}

package/guidance/accessibility.md

@@ -0,0 +1,67 @@
+---
+name: accessibility
+description: Web accessibility guidelines and inclusive design
+---
+# Accessibility
+
+Follow these accessibility rules when building user interfaces. All interactive content must be usable by people with diverse abilities, including those using assistive technologies.
+
+## Semantic HTML
+
+- Use semantic elements (`<nav>`, `<main>`, `<article>`, `<section>`, `<header>`, `<footer>`) for page structure.
+- Use heading elements (`<h1>`–`<h6>`) in logical hierarchy; never skip levels for styling.
+- Use `<button>` for actions and `<a>` for navigation; never use `<div>` or `<span>` as interactive elements without proper roles.
+- Use `<label>` elements explicitly associated with form inputs via `for`/`id` pairing.
+- Use lists (`<ul>`, `<ol>`, `<dl>`) for grouped items rather than styled `<div>` sequences.
+
+## ARIA Usage
+
+- Prefer native HTML semantics over ARIA; add ARIA only when no native element provides the required semantics.
+- Use `aria-label` or `aria-labelledby` for interactive elements that lack visible text labels.
+- Set `aria-expanded`, `aria-selected`, `aria-checked` states dynamically to reflect current UI state.
+- Apply `role="alert"` or `aria-live="polite"` for dynamic content that must be announced to screen readers.
+- Never use `aria-hidden="true"` on focusable elements.
+
+## Keyboard Navigation
+
+- All interactive elements must be reachable and operable via keyboard alone (Tab, Shift+Tab, Enter, Space, Arrow keys).
+- Maintain a logical tab order that follows the visual reading flow; avoid positive `tabindex` values.
+- Provide visible focus indicators on all focusable elements; never remove outline without a visible replacement.
+- Implement keyboard shortcuts for complex widgets (modals, dropdowns, tabs) per WAI-ARIA Authoring Practices.
+- Trap focus inside modal dialogs until dismissed; restore focus to the triggering element on close.
+
+## Color and Contrast
+
+- Maintain a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (WCAG AA).
+- Never use color as the sole means of conveying information; pair color with text, icons, or patterns.
+- Verify contrast in both light and dark modes if the application supports theme switching.
+- Ensure focus indicators have at least 3:1 contrast against adjacent colors.
+
+## Images and Media
+
+- Provide meaningful `alt` text for informative images; use `alt=""` for decorative images.
+- Provide captions or transcripts for video and audio content.
+- Avoid auto-playing media; if unavoidable, provide an immediate mechanism to pause or stop.
+- Ensure animated content can be paused and does not flash more than 3 times per second.
+
+## Forms and Errors
+
+- Associate error messages with their input fields using `aria-describedby` or `aria-errormessage`.
+- Display error summaries at the top of forms with links to the offending fields.
+- Do not rely solely on placeholder text as a label; placeholders disappear on input.
+- Group related form controls with `<fieldset>` and `<legend>`.
+- Provide clear instructions before the form and inline help where input format is constrained.
+
+## Responsive and Adaptive Design
+
+- Support zoom up to 200% without loss of content or functionality.
+- Use relative units (rem, em, %) for text and spacing rather than fixed pixels.
+- Ensure touch targets are at least 44x44 CSS pixels for mobile interfaces.
+- Test layouts with different text sizes, languages, and reading directions (LTR/RTL).
+
+## Testing and Verification
+
+- Run automated accessibility scans (axe-core, Lighthouse) in CI and fix all critical/serious issues.
+- Test with at least one screen reader (VoiceOver, NVDA, or JAWS) for major user flows.
+- Validate keyboard-only navigation for all primary workflows.
+- Note: full WCAG conformance requires manual testing with assistive technologies and expert review.

package/guidance/api-conventions.md

@@ -0,0 +1,124 @@
+---
+name: api-conventions
+description: REST API naming, error format, and versioning conventions
+---
+# API Conventions
+
+Follow these conventions when designing, implementing, or reviewing REST APIs. Consistency across endpoints reduces integration friction and simplifies documentation.
+
+## URL Structure and Naming
+
+- Use lowercase, hyphen-separated path segments: `/user-profiles`, not `/userProfiles` or `/user_profiles`.
+- Use plural nouns for resource collections: `/orders`, `/products`, `/users`.
+- Use resource identifiers as path segments: `/users/{userId}/orders/{orderId}`.
+- Limit nesting to two levels; deeper relationships should use query parameters or links.
+- Use query parameters for filtering, sorting, and pagination: `?status=active&sort=-created_at&page=2`.
+- Avoid verbs in URLs; let HTTP methods convey the action.
+
+## HTTP Methods
+
+- `GET` — Retrieve a resource or collection. Must be safe and idempotent. Never mutate state.
+- `POST` — Create a new resource or trigger a non-idempotent action. Return 201 with Location header for creates.
+- `PUT` — Replace an entire resource. Must be idempotent. Return 200 or 204.
+- `PATCH` — Partially update a resource. Use JSON Merge Patch or JSON Patch content types. Return 200.
+- `DELETE` — Remove a resource. Must be idempotent. Return 204 on success, 404 if already absent.
+- `OPTIONS` — Return allowed methods and CORS headers. Used for preflight requests.
+
+## Status Codes
+
+Use the most specific applicable status code:
+
+| Range | Use for |
+|-------|---------|
+| 200 | Successful retrieval or update |
+| 201 | Resource created (include Location header) |
+| 204 | Success with no response body |
+| 400 | Malformed request (syntax or validation errors) |
+| 401 | Missing or invalid authentication credentials |
+| 403 | Authenticated but insufficient permissions |
+| 404 | Resource not found |
+| 409 | Conflict (e.g., duplicate key, version mismatch) |
+| 422 | Semantically invalid request (valid syntax but business rule violation) |
+| 429 | Rate limit exceeded (include Retry-After header) |
+| 500 | Unexpected server error (never expose internals) |
+
+## Error Response Format
+
+Return a consistent JSON error body for all 4xx and 5xx responses:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Human-readable summary of the problem",
+    "details": [
+      {
+        "field": "email",
+        "issue": "Must be a valid email address"
+      }
+    ],
+    "request_id": "req_abc123"
+  }
+}
+```
+
+- `code` — Machine-readable error identifier (UPPER_SNAKE_CASE).
+- `message` — Brief, user-safe description. Never include stack traces or internal paths.
+- `details` — Optional array of field-level errors for validation failures.
+- `request_id` — Correlation identifier for debugging (matches server-side logs).
+
+## Pagination
+
+- Use cursor-based pagination for large or frequently-changing collections.
+- Support limit/offset as a simpler alternative for smaller, stable datasets.
+- Return pagination metadata in the response body:
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "next_cursor": "eyJpZCI6MTAwfQ",
+    "has_more": true,
+    "total_count": 2340
+  }
+}
+```
+
+- Include `total_count` only when it can be computed efficiently.
+
+## Versioning
+
+- Use URL prefix versioning for major breaking changes: `/v1/users`, `/v2/users`.
+- Increment the version number only on backward-incompatible changes.
+- Support the previous major version for at least 6 months after a new version ships.
+- Treat additive changes (new optional fields, new endpoints) as backward-compatible.
+- Document deprecation timelines in the Sunset response header and changelog.
+
+## Request and Response Conventions
+
+- Use `snake_case` for JSON field names throughout request and response bodies.
+- Represent timestamps in ISO 8601 format with UTC timezone: `2025-06-15T10:30:00Z`.
+- Use envelope format for collections: `{ "data": [...], "pagination": {...} }`.
+- Return the full created or updated resource in response to POST, PUT, and PATCH.
+- Accept and return `Content-Type: application/json` by default.
+- Support `Accept` header negotiation where multiple formats are available.
+
+## Rate Limiting and Throttling
+
+- Enforce rate limits per client or API key.
+- Return `429 Too Many Requests` with a `Retry-After` header (seconds until next allowed request).
+- Include rate limit headers on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
+
+## CORS and Security Headers
+
+- Configure CORS to allow only trusted origins; avoid wildcard `*` in production.
+- Return appropriate CORS headers: `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`.
+- Set `Cache-Control: no-store` on responses containing sensitive data.
+- Include `X-Content-Type-Options: nosniff` and `X-Request-Id` on all responses.
+
+## Documentation and Discoverability
+
+- Provide an OpenAPI 3.x specification for every public API.
+- Include request/response examples for each endpoint.
+- Document authentication requirements, rate limits, and error codes.
+- Use consistent terminology across endpoint descriptions.

package/guidance/index.yaml

@@ -0,0 +1,7 @@
+layers:
+  - name: secure-defaults
+    file: secure-defaults.md
+  - name: accessibility
+    file: accessibility.md
+  - name: api-conventions
+    file: api-conventions.md

package/guidance/secure-defaults.md

@@ -0,0 +1,71 @@
+---
+name: secure-defaults
+description: Security best practices and secure coding defaults
+---
+# Secure Defaults
+
+Follow these security rules by default when writing or reviewing code. Deviations require explicit justification in the design artifact.
+
+## Input Validation
+
+- Validate and sanitize all external inputs at the system boundary before processing.
+- Use an allowlist approach for accepted values when possible; reject unknown inputs.
+- Enforce maximum length, type, and format constraints on every input field.
+- Never trust client-side validation alone; always validate server-side.
+
+## Database and Query Safety
+
+- Use parameterized queries or prepared statements for all database access.
+- Never construct SQL, NoSQL, or ORM queries by string concatenation with user input.
+- Apply principle of least privilege to database credentials (read-only where writes are not needed).
+- Escape identifiers if dynamic table or column names are unavoidable.
+
+## Authentication and Authorization
+
+- Hash passwords with a modern adaptive algorithm (bcrypt, scrypt, or argon2) with per-user salts.
+- Enforce minimum password complexity or passphrase length per current NIST guidance.
+- Implement rate limiting and account lockout on authentication endpoints.
+- Check authorization on every request; never rely solely on client-side role checks.
+- Use short-lived tokens (JWT, session) with explicit expiration and refresh rotation.
+
+## Secrets Management
+
+- Never store secrets (API keys, tokens, passwords, private keys) in source code or config files committed to version control.
+- Use environment variables or a dedicated secrets manager for runtime secrets.
+- Rotate secrets on a defined schedule and immediately on suspected compromise.
+- Log secret access but never log secret values.
+
+## Transport and Data Protection
+
+- Use TLS 1.2+ for all network communication; reject plain HTTP in production.
+- Encrypt sensitive data at rest using AES-256 or equivalent.
+- Set Secure, HttpOnly, and SameSite attributes on all authentication cookies.
+- Apply Content-Security-Policy, X-Content-Type-Options, and Strict-Transport-Security headers.
+
+## Error Handling and Logging
+
+- Never expose stack traces, internal paths, or database details in user-facing error responses.
+- Log errors with sufficient context for debugging but exclude sensitive data (PII, secrets).
+- Use structured logging (JSON) with consistent severity levels.
+- Return generic error messages to clients; map internal errors to safe public codes.
+
+## Dependency Security
+
+- Pin dependency versions and use lock files to ensure reproducible builds.
+- Audit dependencies for known vulnerabilities regularly (e.g., npm audit, Snyk, Dependabot).
+- Prefer well-maintained packages with active security response teams.
+- Remove unused dependencies to reduce attack surface.
+
+## Least Privilege and Defense in Depth
+
+- Run services with the minimum permissions required for their function.
+- Separate concerns: do not mix admin and user-facing logic in the same process.
+- Apply defense in depth: assume any single layer can be bypassed.
+- Validate at multiple boundaries (network edge, service boundary, data layer).
+
+## File and Resource Handling
+
+- Validate uploaded file types, sizes, and content (not just extensions).
+- Store uploaded files outside the web root with randomized names.
+- Set restrictive file permissions on sensitive files (0600 for keys, 0644 for config).
+- Avoid path traversal: canonicalize paths and reject `..` sequences in user input.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@rasensio/aidlc",
+  "version": "0.1.0",
+  "description": "AI Development Lifecycle Framework — structured lifecycle guidance for AI coding agents across platforms",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "aidlc": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "ai",
+    "development",
+    "lifecycle",
+    "agent",
+    "skills",
+    "workflow"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "1.7.0",
+    "commander": "15.0.0",
+    "picomatch": "4.0.5",
+    "yaml": "2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.32",
+    "@types/picomatch": "3.0.2",
+    "fast-check": "4.9.0",
+    "typescript": "5.8.3",
+    "vitest": "4.1.10"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "capabilities/",
+    "templates/",
+    "guidance/",
+    "phases/",
+    "examples/",
+    "ci/"
+  ]
+}

package/skills/00-overview.md

@@ -0,0 +1,74 @@
+---
+name: aidlc-overview
+description: Framework overview and state protocol for the AI Development Lifecycle
+phase: ideation
+priority: 100
+---
+# AIDLC Framework Overview
+
+You are operating within the AI Development Lifecycle (AIDLC) framework. This skill defines how you interact with lifecycle state and follow phase-driven development.
+
+## Lifecycle Phases
+
+The AIDLC defines seven ordered phases. Not all apply to every task:
+
+1. **Ideation** — Problem exploration, goals, constraints
+2. **Requirements** — Acceptance criteria, user stories, scope
+3. **Design** — Architecture, interfaces, data flow
+4. **Implementation** — Code production following the design
+5. **Testing** — Verification against requirements
+6. **Deployment** — Release preparation and execution
+7. **Maintenance** — Monitoring, iteration, documentation updates
+
+## Cycle Scopes
+
+| Scope | Starting Phase | Applicable Phases |
+|-------|---------------|-------------------|
+| Full | Ideation | All seven phases |
+| Standard | Requirements | Requirements through Deployment |
+| Micro | Implementation | Implementation and Testing only |
+
+## State Protocol
+
+All state lives in `.aidlc/state/<instance-name>/`. Read and write state as follows:
+
+### Reading State
+
+1. Read `instance.yaml` to determine: current phase, template, scope, owner, claim
+2. Read `phase-<name>.yaml` for per-phase status and artifact completion
+3. Read `transitions.log` (NDJSON) for history — one JSON object per line
+
+### 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.
+3. Update phase state files as you produce artifacts.
+4. Append a transition record to `transitions.log` only on successful phase transitions.
+
+### Transition Records
+
+Each line in `transitions.log` is a JSON object:
+```json
+{"timestamp":"<ISO 8601 UTC>","author":"<session-id>","from":"<phase>","to":"<phase>","type":"normal|skip|upgrade","criteria":["..."]}
+```
+
+## Context and Guidance
+
+- Project context lives in `.aidlc/context/` (style-guide.md, architecture.md)
+- Guidance layers live in `.aidlc/guidance/` — load only those listed in `index.yaml`
+- Load context relevant to the current phase; avoid re-reading unchanged files
+
+## Security
+
+Before executing any sensitive operation (infrastructure changes, permission modifications, file deletions), you MUST:
+1. Describe the operation and its impact to the user
+2. Wait for explicit confirmation
+3. If cancelled, halt and log the cancellation
+
+Never store credentials, tokens, or secrets in state files or artifacts.
+
+## Token Efficiency
+
+- 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

package/skills/10-ideation.md

@@ -0,0 +1,45 @@
+---
+name: aidlc-ideation
+description: Guides the Ideation phase — exploring the problem space, defining goals and constraints
+phase: ideation
+priority: 50
+---
+# Ideation Phase
+
+## Purpose
+
+Explore the problem space before committing to a solution. Define what we are building, why, and what constraints exist.
+
+## Entry Criteria
+
+- A lifecycle instance has been created with a Full scope
+- The instance is claimed by this session
+
+## Required Artifacts
+
+- `ideation.md` — Problem statement, goals, constraints, initial ideas, and open questions
+
+## 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.
+
+## 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)
+
+## Guidance
+
+{{guidance:secure-defaults}}
+
+## Security Confirmation
+
+If any ideation option involves sensitive operations (new credentials, infrastructure provisioning, access control changes), flag it explicitly and note that confirmation will be required before execution in later phases.
+
+## Completion
+
+When exit criteria are met, update `phase-ideation.yaml` status to `complete` and append a transition record to `transitions.log`.