ai-design-context 0.4.0

package/starter-kit/docs/PRD.md

@@ -0,0 +1,32 @@
+# Product Requirements Document
+
+## Vision
+
+What product outcome should this create?
+
+## Goals
+
+- Goal 1.
+- Goal 2.
+
+## Scope
+
+### In Scope
+
+- Item.
+
+### Out Of Scope
+
+- Item.
+
+## Primary User
+
+Who is this for?
+
+## Core Action
+
+What action should be easiest to complete?
+
+## Success Criteria
+
+- Criterion.

package/starter-kit/docs/USER_FLOWS.md

@@ -0,0 +1,19 @@
+# User Flows
+
+Describe primary user journeys.
+
+## Primary Flow
+
+1. Entry point.
+2. Main action.
+3. Feedback.
+4. Completion.
+
+## Empty Flow
+
+- What happens before the user has data?
+
+## Error Flow
+
+- What can fail?
+- How does the user recover?

package/starter-kit/reviews/DESIGN_REVIEW.md

@@ -0,0 +1,49 @@
+# Design Review
+
+## Product Goal
+
+- Clear / unclear:
+
+## User Goal
+
+- Clear / unclear:
+
+## Rules Applied
+
+- Rule:
+- Evidence:
+
+## Patterns Applied
+
+- Pattern:
+- Evidence:
+
+## Mobile
+
+- Primary action reachable:
+- Layout works at 390px:
+
+## Accessibility
+
+- Labels:
+- Focus:
+- Contrast:
+- Touch targets:
+
+## States
+
+- Empty:
+- Loading:
+- Error:
+- Success:
+- Disabled:
+
+## Consistency
+
+- Uses existing components/tokens:
+- Avoids one-off UI:
+
+## Result
+
+- PASS / NEEDS WORK:
+- Required fixes:

package/starter-kit/templates/FEATURE_TEMPLATE.md

@@ -0,0 +1,36 @@
+# Feature
+
+## User Goal
+
+What should the user be able to do?
+
+## Product Goal
+
+What product outcome does this support?
+
+## Applicable Rules
+
+- Rule:
+- Why it applies:
+
+## Applicable Patterns
+
+- Pattern:
+- Why it applies:
+
+## Edge Cases
+
+- Case:
+- Expected behavior:
+
+## States
+
+- Empty:
+- Loading:
+- Error:
+- Success:
+- Disabled:
+
+## Acceptance Criteria
+
+- Criteria.

package/starter-kit/templates/TASK_TEMPLATE.md

@@ -0,0 +1,22 @@
+# Task
+
+## Context
+
+What is changing and why?
+
+## Design Reasoning
+
+- User goal:
+- Rules:
+- Patterns:
+
+## Implementation Notes
+
+- Files:
+- Constraints:
+
+## Validation
+
+- Review:
+- Benchmark:
+- Evidence:

package/templates/CHECKLIST_TEMPLATE.md

@@ -0,0 +1,43 @@
+---
+id: CHECK-00000
+alias: CHECK-ALIAS-000
+slug: checklist-slug
+title: Checklist title
+object_type: checklist
+status: draft
+version: 0.1.0
+category: design-qa
+tags: []
+created_at: 2026-06-25
+updated_at: 2026-06-25
+last_reviewed_at: 2026-06-25
+owner: ai-design-context
+maturity: seed
+risk_level: medium
+platform: []
+product_type: []
+surface: []
+applies_to: []
+does_not_apply_to: []
+relationships:
+  - type: related_to
+    target: RULE-00000
+---
+
+# Checklist Title
+
+## Scope
+
+Describe the artifact or flow this checklist evaluates.
+
+## Coverage
+
+- `RULE-00000` - Review question.
+
+## Evidence Boundary
+
+- State what must be directly observed or measured before it can pass.
+
+## Handoff
+
+- Name the review prompt, review object, or specialist skill that should consume the checklist.

package/templates/OBSERVATION_TEMPLATE.md

@@ -0,0 +1,41 @@
+---
+id: OBS-00000
+alias: OBS-ALIAS-000
+slug: observation-slug
+title: Observation title
+object_type: observation
+status: draft
+version: 0.1.0
+category: product
+tags: []
+created_at: 2026-06-25
+updated_at: 2026-06-25
+last_reviewed_at: 2026-06-25
+owner: ai-design-context
+maturity: seed
+risk_level: low
+platform: []
+product_type: []
+surface: []
+applies_to: []
+does_not_apply_to: []
+relationships: []
+---
+
+# Observation Title
+
+## Source
+
+Where did this observation come from?
+
+## Observed Behavior
+
+What happened?
+
+## Why It May Matter
+
+Why might this matter for AI-assisted product design?
+
+## Evidence
+
+- Link, screenshot, review note, or implementation note.

package/templates/PATTERN_TEMPLATE.md

@@ -0,0 +1,100 @@
+---
+id: PAT-00000
+alias: PATTERN-000
+slug: pattern-slug
+title: Pattern title
+object_type: pattern
+status: draft
+version: 0.1.0
+category: ux
+tags: []
+created_at: 2026-06-25
+updated_at: 2026-06-25
+last_reviewed_at: 2026-06-25
+owner: ai-design-context
+maturity: seed
+risk_level: medium
+platform: []
+product_type: []
+surface: []
+applies_to: []
+does_not_apply_to: []
+relationships:
+  - type: requires
+    target: RULE-00000
+  - type: derived_from
+    target: RESEARCH-00000
+---
+
+# Pattern Name
+
+## Purpose
+
+Describe the single design problem this pattern solves.
+
+## User Goal
+
+State the user's goal in one sentence.
+
+## Product Context
+
+Describe the product, screen, or workflow context where this pattern fits.
+
+## Use When
+
+- Use when...
+
+## Do Not Use When
+
+- Do not use when...
+
+## UX Rules
+
+- `RULE-00000` Rule name
+
+## Accessibility Rules
+
+- `RULE-00000` Rule name
+
+## Mobile Behavior
+
+Describe the touch-first behavior, including 390px assumptions when relevant.
+
+## Desktop Behavior
+
+Describe the desktop behavior, including keyboard, density, or multi-pane assumptions when relevant.
+
+## Empty State
+
+Describe the empty state.
+
+## Loading State
+
+Describe the loading state.
+
+## Error State
+
+Describe the error state and recovery path.
+
+## Required Rules
+
+- `RULE-00000` Rule name
+
+## Related Research
+
+- `RESEARCH-00000`
+
+## Related Patterns
+
+- Parent: none
+- Child: none
+- Alternative: none
+- Depends on: none
+
+## Examples
+
+- Example product situation.
+
+## Agent Checklist
+
+- Check...

package/templates/PROMPT_TEMPLATE.md

@@ -0,0 +1,46 @@
+---
+id: PROMPT-00000
+alias: PROMPT-ALIAS-000
+slug: prompt-slug
+title: Prompt title
+object_type: prompt
+status: draft
+version: 0.1.0
+category: generation
+tags: []
+created_at: 2026-06-25
+updated_at: 2026-06-25
+last_reviewed_at: 2026-06-25
+owner: ai-design-context
+maturity: seed
+risk_level: medium
+platform: []
+product_type: []
+surface: []
+applies_to: []
+does_not_apply_to: []
+relationships:
+  - type: requires
+    target: PAT-00000
+  - type: requires
+    target: RULE-00000
+---
+
+# Prompt Title
+
+## Required Patterns
+
+- `PAT-00000`
+
+## Required Rules
+
+- `RULE-00000`
+
+## Validation
+
+- Benchmark scenario:
+- Evidence folder:
+
+## Instruction
+
+Write the agent instruction here.

package/templates/PROTOTYPE_REVIEW.md

@@ -0,0 +1,50 @@
+# Prototype Review Template
+
+Use this template to review generated product output against AI Design Context.
+
+## Metadata
+
+- Scenario:
+- Model/tool:
+- Date:
+- Reviewer:
+- Compared against:
+
+## Inputs Reviewed
+
+- Product brief:
+- Prompt:
+- Generated output:
+- Relevant rules:
+- Relevant patterns:
+
+## Rubric Scores
+
+Use `docs/EVALUATION_RUBRIC.md`.
+
+| Category | Score | Evidence |
+| --- | --- | --- |
+| Product Thinking |  |  |
+| UX |  |  |
+| Information Architecture |  |  |
+| Navigation |  |  |
+| Accessibility |  |  |
+| Mobile-first |  |  |
+| Visual Hierarchy |  |  |
+| State Design |  |  |
+| Consistency |  |  |
+| Performance Awareness |  |  |
+| Simplicity |  |  |
+| Overall Product Quality |  |  |
+
+## Findings
+
+- Strongest result:
+- Weakest result:
+- Missing states:
+- Missing evidence:
+
+## Recommendation
+
+- PASS / NEEDS WORK:
+- Next change:

package/templates/REFERENCE_PROJECT_TEMPLATE.md

@@ -0,0 +1,49 @@
+---
+id: REF-00000
+alias: REF-ALIAS-000
+slug: reference-project-slug
+title: Reference project title
+object_type: reference_project
+status: draft
+version: 0.1.0
+category: consumer
+tags: []
+created_at: 2026-06-25
+updated_at: 2026-06-25
+last_reviewed_at: 2026-06-25
+owner: ai-design-context
+maturity: seed
+risk_level: medium
+platform: []
+product_type: []
+surface: []
+applies_to: []
+does_not_apply_to: []
+relationships:
+  - type: implements
+    target: PROMPT-00000
+  - type: validates
+    target: PAT-00000
+---
+
+# Reference Project Title
+
+## Product Context
+
+Describe the product context.
+
+## Patterns Used
+
+- `PAT-00000`
+
+## Rules Applied
+
+- `RULE-00000`
+
+## Research Influence
+
+- `RESEARCH-00000`
+
+## Validation Questions
+
+- Question.

package/templates/REVIEW_TEMPLATE.md

@@ -0,0 +1,55 @@
+---
+id: REVIEW-00000
+alias: REVIEW-ALIAS-000
+slug: review-slug
+title: Review title
+object_type: review
+status: draft
+version: 0.1.0
+category: quality-gate
+tags: []
+created_at: 2026-06-25
+updated_at: 2026-06-25
+last_reviewed_at: 2026-06-25
+owner: ai-design-context
+maturity: seed
+risk_level: medium
+platform: []
+product_type: []
+surface: []
+applies_to: []
+does_not_apply_to: []
+relationships:
+  - type: validates
+    target: REF-00000
+---
+
+# Review Title
+
+## Verdict
+
+PASS or NEEDS WORK.
+
+## Scope
+
+What object or product surface is being reviewed?
+
+## Evidence Reviewed
+
+- Artifact, benchmark output, screenshot, implementation, or evaluation note.
+
+## Findings
+
+- Finding.
+
+## Missing Layers
+
+- Observation, research, rule, pattern, prompt, reference project, or checklist gap.
+
+## Recommendations
+
+- Recommendation.
+
+## Handoff
+
+- Exact follow-up evidence, owner, or knowledge update required.

package/templates/RULE_TEMPLATE.md

@@ -0,0 +1,57 @@
+---
+id: RULE-00000
+alias: UX-000
+slug: rule-slug
+title: Rule title
+object_type: rule
+status: draft
+version: 0.1.0
+category: ux
+tags: []
+created_at: 2026-06-25
+updated_at: 2026-06-25
+last_reviewed_at: 2026-06-25
+owner: ai-design-context
+maturity: seed
+risk_level: medium
+platform: []
+product_type: []
+surface: []
+applies_to: []
+does_not_apply_to: []
+relationships:
+  - type: derived_from
+    target: RESEARCH-00000
+---
+
+# RULE-00000 Rule Title
+
+Status: Draft
+Category: UX
+Severity: Medium
+
+## Source Research
+
+- `research/products/example.md`
+
+## Why
+
+Explain the product problem this rule prevents.
+
+## Rule
+
+State the rule as a direct instruction an AI coding agent can follow.
+
+## Good Example
+
+- Describe observable good output.
+
+## Bad Example
+
+- Describe common agent failures.
+
+## Agent Checklist
+
+- Check whether the rule was applied.
+- Check whether the result still fits the product context.
+- Check whether the rule created any accessibility, performance, or implementation risk.

package/tools/cli.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runContext } from './context.mjs';
+import { initProject } from './init.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const usage = `AI Design Context
+
+Usage:
+  ai-design-context init
+  ai-design-context context --task <query> [--platform mobile] [--intent implement] [--format json]
+  ai-design-context context --review <object-id-or-phrase> [--intent qa]
+  ai-design-context context --object <object-id-or-slug>
+  ai-design-context --version
+
+init appends agent instructions and creates only missing starter-kit templates.
+context reads the knowledge graph shipped with this installed package.
+Requires Node.js 20 or later. See context --help for all retrieval options.`;
+
+const [command, ...args] = process.argv.slice(2);
+try {
+  if (!command || (['--help', '-h'].includes(command) && args.length === 0)) {
+    console.log(usage);
+  } else if (command === '--version' && args.length === 0) {
+    const { version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    console.log(version);
+  } else if (command === 'context') {
+    runContext(args, { root: packageRoot, readingPaths: true, command: 'ai-design-context context' });
+  } else if (command === 'init') {
+    if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+      console.log('Usage: ai-design-context init\nAppend agent instructions and create only missing product templates in the current directory.');
+    } else {
+      if (args.length > 0) throw new Error(`Unknown init argument: ${args[0]}`);
+      const result = initProject(process.cwd(), packageRoot);
+      console.log(result.instructionsAdded ? 'Added AI Design Context instructions to AGENTS.md.' : 'AI Design Context instructions already present; preserved the existing block.');
+      console.log(result.created.length ? `Created: ${result.created.join(', ')}` : 'No missing templates; existing files preserved.');
+    }
+  } else {
+    throw new Error(`Unknown command or argument: ${command}\n${usage}`);
+  }
+} catch (error) {
+  console.error(`AI Design Context: ${error.message}`);
+  process.exitCode = 1;
+}