fine tuned code

updated lots of code to automate and fix gaps.

.claude/agents/analyst/prompt.md

@@ -104,6 +104,8 @@ When activated as the Analyst agent, systematically execute:
 - Validate and gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/project_brief.schema.json --input .claude/context/artifacts/project-brief.json --gate .claude/context/history/gates/<workflow>/01-analyst.json --autofix 1`.
 - Render Markdown for humans: `node .claude/tools/renderers/bmad-render.mjs project-brief .claude/context/artifacts/project-brief.json > .claude/context/artifacts/project-brief.md`.
 
+Follow `.claude/system/context-protocol.md` for paths, gating records, session updates, and reasoning logs.
+
 ### Structured Reasoning (shallow, auditable)
 - Write a small reasoning JSON (not part of the brief) to `.claude/context/history/reasoning/<workflow>/01-analyst.json` with:
   - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words).

.claude/agents/architect/prompt.md

@@ -46,11 +46,14 @@ When activated, follow this structured approach:
    - Include Mermaid diagrams and system interaction flows
    - Provide implementation guidance that prevents common pitfalls
    - Validate architecture against all requirements
+   - Follow `.claude/system/context-protocol.md` for artifact paths, gating, rendering, session updates, and reasoning logs.
 </execution_process>
 
 ## <available_templates>
 **Primary Templates** (Use these exact file paths):
 - `.claude/templates/architecture.md` - Core system architecture document
+- `.claude/templates/fullstack-architecture.md` - Full-stack architecture for new builds
+- `.claude/templates/brownfield-architecture.md` - Integration plan for existing systems
 - `.claude/templates/project-constitution.md` - Technical governance and standards
 
 **Supporting Tasks** (Reference these for workflow execution):

.claude/agents/bmad-orchestrator/prompt.md

@@ -177,6 +177,15 @@ Return only this JSON object for routing decisions (no prose):
 
 Validate against `.claude/schemas/route_decision.schema.json`. Persist the validated object into `.claude/context/session.json` under `route_decision` and update `project.workflow` and `current_context.current_step` accordingly.
 
+Tooling steps (follow Context Protocol):
+- Write route decision to `.claude/context/artifacts/route-decision.json`.
+- Gate it: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/route_decision.schema.json --input .claude/context/artifacts/route-decision.json --gate .claude/context/history/gates/<workflow>/00-orchestrator.json --autofix 1`.
+- On pass, embed the object into `.claude/context/session.json` (persist `route_decision`, set `project.workflow`, and `current_context.current_step`).
+- Append `.claude/context/artifacts/route-decision.json` to `artifacts.generated` and `route_decision.schema.json` to `artifacts.schemas_used`.
+- After each step, optionally run `node .claude/tools/ci/validate-all.mjs` to catch regressions early.
+
+Always follow `.claude/system/context-protocol.md` for paths, gating, and session updates.
+
 ## Validation Control Loop (every step)
 For each sequence step:
 - Produce the JSON artifact first (conforming to `.claude/schemas/*`).

.claude/agents/developer/prompt.md

@@ -48,6 +48,14 @@ Follow this systematic development approach:
    - Perform code reviews and self-assessment
    - Optimize performance and security measures
    - Document implementation decisions and setup instructions
+
+## <tooling_contract>
+- Follow `.claude/system/context-protocol.md`.
+- Read required artifacts from `.claude/context/artifacts/` (e.g., `fullstack-architecture.md`, `ui-spec.md`, `prd.md`).
+- Save code into directories specified by the active workflow; if unspecified, default to `src/frontend`, `src/backend`, `tests/*` with clear structure.
+- Maintain a developer manifest at `.claude/context/artifacts/dev-manifest.json` listing files/dirs created or modified.
+- Gate the manifest: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/artifact_manifest.schema.json --input .claude/context/artifacts/dev-manifest.json --gate .claude/context/history/gates/<workflow>/06-developer.json --autofix 1`.
+- Update `.claude/context/session.json.artifacts.generated` with added artifacts and code paths.
 </execution_process>
 
 ## <available_templates>

.claude/agents/pm/prompt.md

@@ -132,6 +132,8 @@ When activated as the PM agent, execute systematically:
 - Provide prioritized alternatives for contested features
 - Flag dependencies and risks with suggested mitigations
 - Follow enterprise writing and quality rules above
+
+Follow `.claude/system/context-protocol.md` for paths, gating records, session updates, and reasoning logs.
 </output_specifications>
 
 ## Original Agent Configuration

.claude/agents/qa/prompt.md

@@ -162,6 +162,8 @@ Feature: [Feature name]
 - Prioritize issues using risk-based impact analysis
 - Follow enterprise testing and writing standards above
 - Provide actionable improvement recommendations with timelines
+
+Follow `.claude/system/context-protocol.md` for paths, gating records, session updates, and reasoning logs.
 </output_specifications>
 
 ## Original Agent Configuration

.claude/agents/ux-expert/prompt.md

@@ -164,6 +164,8 @@ When activated as the UX Expert agent, execute systematically:
 - Flag potential development complexity and suggest alternatives
 - Follow enterprise design and writing standards above
 - Include post-launch validation and iteration recommendations
+
+Follow `.claude/system/context-protocol.md` for paths, gating records, session updates, and reasoning logs.
 </output_specifications>
 
 ## Original Agent Configuration

.claude/context/history/reasoning/.gitkeep

@@ -0,0 +1 @@
+

.claude/examples/specs/enhancement_spec.md

@@ -0,0 +1,22 @@
+# Enhancement specification (example)
+
+## context
+- existing app: TaskFlow Pro v1.3 (Next.js 14, Node.js API, Postgres 14)
+- request: add task dependencies and Gantt-style timeline view
+
+## goals
+- represent finish-to-start dependencies between tasks
+- show project timeline with critical path basics
+
+## constraints
+- no breaking changes to existing task API
+- incremental rollout behind feature flag `task_dependencies`
+
+## acceptance criteria
+- create/read/update/delete dependencies via versioned endpoints (v2)
+- timeline view loads in < 400ms P95 for 1k tasks
+- migration scripts support roll-forward and rollback
+
+## risks
+- query performance on large projects → add indexes, pagination, caching
+- UI complexity → progressive disclosure and virtualization

.claude/examples/specs/user_spec.md

@@ -0,0 +1,26 @@
+# User specification (example)
+
+## project
+- name: TaskFlow Pro
+- type: web-app (MVP → scalable SaaS)
+
+## goals
+- Create a task management app with teams, tags, and due dates
+- Mobile-responsive UI with accessible components
+
+## constraints
+- Timeline: 6 weeks MVP
+- Stack preference: React + Node.js/Postgres
+
+## key features
+- Auth (email/password, password reset)
+- CRUD tasks with tags, comments, attachments
+- Team workspaces and shareable links
+- Basic reporting (tasks by status/assignee)
+
+## non-functional
+- P95 < 250ms for primary views
+- 99.9% uptime target after GA
+
+## notes
+- Provide both light and dark themes

.claude/rules/manifest.yaml

@@ -1,9 +1,9 @@
 stack_profiles:
   react_next_ts:
     include:
-      - ".claude/rules/nextjs-typescript-*/**/*.mdc"
-      - ".claude/rules/tailwind-*/**/*.mdc"
-      - ".claude/rules/javascript-typescript-code-quality-cursorrules-pro*/**/*.mdc"
+      - ".claude/rules/cursorrules-cursor-ai-nextjs-14-tailwind-seo-setup/**/*.mdc"
+      - ".claude/rules/javascript-typescript-code-quality-cursorrules-pro/**/*.mdc"
+      - ".claude/rules/tailwind*.mdc"
     exclude:
       - ".claude/rules/android-*/**"
       - ".claude/rules/swift-*/**"
@@ -12,7 +12,7 @@ stack_profiles:
     include:
       - ".claude/rules/cursorrules-file-cursor-ai-python-fastapi-api/**/*.mdc"
       - ".claude/rules/python-projects-guide-cursorrules-prompt-file/**/*.mdc"
-      - ".claude/rules/jest-unit-testing-cursorrules-prompt-file/**/*.mdc"
+      - ".claude/rules/fastapi.mdc"
     exclude:
       - ".claude/rules/kotlin-*/**"
       - ".claude/rules/java-*/**"

.claude/system/context-protocol.md

@@ -0,0 +1,41 @@
+# Context protocol (v1)
+
+A shared contract for how agents create, validate, render, persist, and share context.
+
+## artifact locations
+- JSON-first artifacts: write to `.claude/context/artifacts/<artifact>.json`.
+- Rendered Markdown: write to `.claude/context/artifacts/<artifact>.md`.
+- Reasoning logs (shallow, auditable): `.claude/context/history/reasoning/<workflow>/<step>-<agent>.json`.
+- Gate records: `.claude/context/history/gates/<workflow>/<artifact-or-step>.json`.
+
+## validation and rendering
+- Validate every artifact against its schema using the gate tool:
+  - `node .claude/tools/gates/gate.mjs --schema <schema> --input <json> --gate <gatefile> --autofix 1`
+- Only after a pass, render Markdown for humans using the renderer:
+  - `node .claude/tools/renderers/bmad-render.mjs <type> <json> > <md>`
+- Before a PR, run the sweep:
+  - `node .claude/tools/ci/validate-all.mjs`
+
+## session updates
+- Orchestrator owns `.claude/context/session.json`.
+- Persist `route_decision`, `project.workflow`, and `current_context.current_step`.
+- Append generated artifact filenames into `artifacts.generated` and list schemas into `artifacts.schemas_used`.
+
+## naming conventions
+- Use kebab-case for filenames; keep consistent artifact names per schema:
+  - project-brief.json, prd.json, ux-spec.json, system-architecture.json, test-plan.json, review-notes.json
+- Prefer one canonical JSON name per schema; keep legacy aliases only where workflows require.
+
+## directory creation
+- Create parent directories before writing; tools already mkdir recursively.
+
+## handoff and escalation
+- Handoffs use workflow `depends_on` and `escalate_to`.
+- On failure after auto-fix, escalate per workflow and record in gate file.
+
+## context reading
+- Agents read previous artifacts from `.claude/context/artifacts/` and do not re-ask for information already present.
+
+## reasoning logs (shallow)
+- keys: `assumptions`, `decision_criteria`, `tradeoffs`, `open_questions`, `final_decision`.
+- Do not include chain-of-thought in main artifacts.

.claude/templates/brownfield-architecture.md

@@ -0,0 +1,44 @@
+# Brownfield integration architecture template
+
+Use this for enhancing existing systems. Emphasize safety, compatibility, and controlled rollout.
+
+## current state analysis
+- existing architecture summary and key hotspots
+- tech stack versions, ownership, SLAs, compliance obligations
+
+## enhancement scope & impact
+- functional changes, affected domains, and non-functional deltas
+- blast radius analysis (components, data, integrations)
+
+## compatibility strategy
+- API contracts (breaking vs non-breaking), versioning plan
+- schema migrations (expand-migrate-contract-shrink pattern)
+- feature toggles and gradual enablement
+
+## target architecture deltas
+- new/changed components (responsibilities, tech)
+- updated data model and migration plan
+
+## integration plan
+- dependency graph and sequencing
+- rollback strategy and safe-guard rails (canary, shadow traffic)
+
+## deployment & release plan
+- environments, pipelines, approvals
+- incremental rollout, monitoring gates, rollback triggers
+
+## security & compliance
+- risk assessment, new threat surfaces, mitigations
+- data handling changes and audit requirements
+
+## performance & observability
+- expected load/latency changes and capacity plan
+- dashboards, alerts, and success criteria for rollout
+
+## test strategy (risk-based)
+- regression scope, contract tests, migration tests
+- performance, accessibility, and security checks
+
+## risks & mitigations
+- prioritized list with owners and timelines
+

.claude/templates/fullstack-architecture.md

@@ -0,0 +1,62 @@
+# Full-stack architecture template
+
+Use this template to produce the System Architecture JSON and the human-readable Markdown for new applications. Keep language specific, measurable, and actionable. Reference the PRD and UX spec.
+
+## context
+- problem statement and business context (1–3 sentences)
+- scope assumptions and explicit non-goals
+- constraints (tech, compliance, budget, timeline)
+
+## architecture decisions (ADRs)
+- ADR-001: <decision> — rationale, alternatives considered, status
+- ADR-002: <decision> — rationale, alternatives considered, status
+
+## system overview
+- high-level diagram (Mermaid recommended)
+- major boundaries: frontend, backend, data, integrations
+- data flow narrative (request → process → persist → respond)
+
+## components
+- <component name> (technology): responsibilities, key interfaces
+- <component name> (technology): responsibilities, key interfaces
+
+## data model
+- entities with attributes and relationships (cardinality, ownership)
+- migration/seed strategy and multi-env data handling
+
+## api design
+- protocol(s): REST/GraphQL/eventing; versioning and error contract
+- key endpoints/operations, idempotency and pagination patterns
+
+## integration
+- external systems, protocol, direction, authentication, rate limits
+- retry, backoff, and circuit-breaking strategy
+
+## deployment
+- target environment(s): dev/stage/prod
+- packaging (Docker images), orchestration (Kubernetes/Compose), CI/CD
+- config and secrets management; rollout and rollback strategy
+
+## security
+- threats (STRIDE) and controls (OWASP ASVS alignment)
+- authN/authZ model, secrets storage, audit logging
+
+## performance
+- targets (P95 latency, throughput, error rate)
+- caching layers and capacity planning notes
+
+## observability
+- logging, metrics, traces; dashboards and alerts
+- SLOs and error budgets
+
+## reliability & recovery
+- redundancy, health checks, graceful degradation
+- backup/restore and disaster recovery objectives
+
+## risks & mitigations
+- top risks with impact/likelihood and mitigation plan
+
+## implementation guidance
+- code structure conventions; DX and lint/test gates
+- phased delivery plan and tech debt notes
+

.claude/templates/implementation-plan.md

@@ -0,0 +1,39 @@
+# Implementation plan template
+
+Use before coding to align structure, tasks, and testing.
+
+## scope
+- features/stories in scope with acceptance criteria refs
+- out of scope and assumptions
+
+## architecture trace
+- links to PRD, UX spec, architecture sections
+- key decisions affecting implementation
+
+## code structure
+- directories, modules, naming conventions
+- interfaces/types and shared utilities
+
+## dependencies
+- packages (name@version) and rationale
+- security considerations and license notes
+
+## environment & config
+- env vars, secrets, and defaults
+- local dev setup and run commands
+
+## tasks & estimates
+- task list with estimates and dependencies
+- risks and mitigations per task
+
+## testing plan
+- unit, integration, e2e: what, where, how measured
+- coverage targets and tooling
+
+## rollout
+- migration scripts, toggles, and monitoring
+- fallback/rollback procedures
+
+## sign-off checklist
+- lint/tests green, docs updated, artifacts gated
+

.claude/tools/ci/validate-all.mjs

@@ -13,8 +13,9 @@ const map = [
   { pattern: /^project-brief\.json$/, schema: 'project_brief.schema.json' },
   { pattern: /^prd\.json$/, schema: 'product_requirements.schema.json' },
   { pattern: /^(system-architecture|frontend-architecture|architecture)\.json$/, schema: 'system_architecture.schema.json' },
-  { pattern: /^(ux-spec|front-end-spec)\.json$/, schema: 'ux_spec.schema.json' },
+  { pattern: /^(ux-spec|front-end-spec|ui-enhancement-spec)\.json$/, schema: 'ux_spec.schema.json' },
   { pattern: /^test-plan\.json$/, schema: 'test_plan.schema.json' },
+  { pattern: /^route-decision\.json$/, schema: 'route_decision.schema.json' },
   { pattern: /^dev-manifest\.json$/, schema: 'artifact_manifest.schema.json' },
   { pattern: /^backlog\.json$/, schema: 'backlog.schema.json' },
   { pattern: /^epic-.*\.json$/, schema: 'epic.schema.json' },
@@ -43,4 +44,3 @@ if (fs.existsSync(artifactsDir)) {
 }
 
 process.exit(ok ? 0 : 1);
-

.claude/tools/context/preflight.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+
+const ROOT = process.cwd();
+const pairs = [
+  { src: '.claude/examples/specs/user_spec.md', dst: 'user_spec.md' },
+  { src: '.claude/examples/specs/enhancement_spec.md', dst: 'enhancement_spec.md' }
+];
+
+let copied = [];
+for (const { src, dst } of pairs) {
+  const absSrc = path.join(ROOT, src);
+  const absDst = path.join(ROOT, dst);
+  if (!fs.existsSync(absDst) && fs.existsSync(absSrc)) {
+    fs.copyFileSync(absSrc, absDst);
+    copied.push(dst);
+  }
+}
+
+if (copied.length) {
+  console.log('Preflight copied:', copied.join(', '));
+} else {
+  console.log('Preflight: no copies needed');
+}
+

.claude/tools/context/render-all.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+const ROOT = process.cwd();
+const artifactsDir = path.join(ROOT, '.claude/context/artifacts');
+
+const map = [
+  { pattern: /^project-brief\.json$/, type: 'project-brief', out: () => 'project-brief.md' },
+  { pattern: /^prd\.json$/, type: 'prd', out: () => 'prd.md' },
+  { pattern: /^ux-spec\.json$/, type: 'ux-spec', out: () => 'ui-spec.md' },
+  { pattern: /^system-architecture\.json$/, type: 'architecture', out: () => 'fullstack-architecture.md' },
+  { pattern: /^frontend-architecture\.json$/, type: 'architecture', out: () => 'frontend-architecture.md' },
+  { pattern: /^architecture\.json$/, type: 'architecture', out: () => 'architecture.md' },
+  { pattern: /^test-plan\.json$/, type: 'test-plan', out: () => 'test-plan.md' },
+  { pattern: /^review-notes\.json$/, type: 'review-notes', out: () => 'review-notes.md' },
+  { pattern: /^enhancement-classification\.json$/, type: 'enhancement-classification', out: () => 'enhancement-classification.md' },
+  { pattern: /^backlog\.json$/, type: 'backlog', out: () => 'backlog.md' },
+  { pattern: /^epic-.*\.json$/, type: 'epic', out: (f) => f.replace(/\.json$/, '.md') },
+  { pattern: /^story-.*\.json$/, type: 'story', out: (f) => f.replace(/\.json$/, '.md') }
+];
+
+function render(type, inputPath) {
+  const res = spawnSync('node', ['.claude/tools/renderers/bmad-render.mjs', type, inputPath], { cwd: ROOT, encoding: 'utf8' });
+  return { code: res.status ?? 1, stdout: res.stdout || '', stderr: res.stderr || '' };
+}
+
+function main() {
+  if (!fs.existsSync(artifactsDir)) {
+    console.log('Artifacts directory not found:', artifactsDir);
+    process.exit(0);
+  }
+  const files = fs.readdirSync(artifactsDir).filter(f => f.endsWith('.json'));
+  let ok = true; const results = [];
+  for (const f of files) {
+    const rule = map.find(m => m.pattern.test(f));
+    if (!rule) continue;
+    const inputPath = path.join(artifactsDir, f);
+    const outName = typeof rule.out === 'function' ? rule.out(f) : rule.out;
+    const outPath = path.join(artifactsDir, outName);
+    const r = render(rule.type, inputPath);
+    if (r.code === 0) {
+      fs.writeFileSync(outPath, r.stdout);
+      results.push({ file: f, out: outName, status: 'ok' });
+    } else {
+      ok = false;
+      results.push({ file: f, out: outName, status: 'fail', error: (r.stderr || '').trim() });
+    }
+  }
+  if (!results.length) {
+    console.log('No renderable artifacts found in', artifactsDir);
+    process.exit(0);
+  }
+  for (const r of results) {
+    if (r.status === 'ok') console.log(`Rendered ${r.file} -> ${r.out}`);
+    else console.error(`Failed ${r.file}: ${r.error}`);
+  }
+  process.exit(ok ? 0 : 1);
+}
+
+main();
+

.claude/tools/context/scaffold.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+
+const ROOT = process.cwd();
+const dirs = [
+  'src/frontend/components',
+  'src/frontend/pages',
+  'src/frontend/styles',
+  'src/frontend/hooks',
+  'src/frontend/utils',
+  'src/frontend/types',
+  'src/backend/api',
+  'src/backend/models',
+  'src/backend/services',
+  'src/backend/middleware',
+  'src/backend/utils',
+  'src/backend/config',
+  'tests/frontend',
+  'tests/backend',
+  'tests/integration',
+  'tests/e2e'
+];
+
+for (const d of dirs) {
+  const abs = path.join(ROOT, d);
+  fs.mkdirSync(abs, { recursive: true });
+  const keep = path.join(abs, '.gitkeep');
+  if (!fs.existsSync(keep)) fs.writeFileSync(keep, '');
+}
+
+console.log('Scaffolded directories:', dirs.join(', '));
+

.claude/tools/context/update-session.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+
+const ROOT = process.cwd();
+const sessionPath = path.join(ROOT, '.claude/context/session.json');
+
+function parseArgs(argv) {
+  const args = { addArtifact: [], addSchema: [] };
+  for (let i = 2; i < argv.length; i += 1) {
+    const k = argv[i];
+    const v = argv[i + 1];
+    if (!k) break;
+    switch (k) {
+      case '--set-workflow': args.workflow = v; i++; break;
+      case '--set-step': args.step = parseInt(v, 10); i++; break;
+      case '--set-route': args.route = v; i++; break;
+      case '--add-artifact': args.addArtifact.push(v); i++; break;
+      case '--add-schema': args.addSchema.push(v); i++; break;
+      default: break;
+    }
+  }
+  return args;
+}
+
+function loadJSON(p) { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+function saveJSON(p, obj) { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, JSON.stringify(obj, null, 2)); }
+
+function uniq(arr) { return Array.from(new Set(arr.filter(Boolean))); }
+
+function ensureSession() {
+  if (!fs.existsSync(sessionPath)) {
+    return {
+      session_id: '', created_at: '', last_updated: '', route_decision: null,
+      project: { name: '', type: '', workflow: '', status: '' },
+      current_context: { active_workflow: '', current_step: 0, active_agent: '', current_task: '' },
+      workflow_progress: { completed_steps: [], current_step: 0, next_steps: [], blocked_steps: [] },
+      artifacts: { generated: [], schemas_used: [], context_files: [] },
+      agents: {
+        analyst: { activated: false, last_task: null, outputs: [] },
+        pm: { activated: false, last_task: null, outputs: [] },
+        architect: { activated: false, last_task: null, outputs: [] },
+        developer: { activated: false, last_task: null, outputs: [] },
+        qa: { activated: false, last_task: null, outputs: [] },
+        'ux-expert': { activated: false, last_task: null, outputs: [] }
+      },
+      user_preferences: { workflow_mode: 'interactive', detail_level: 'high', feedback_frequency: 'each_step' },
+      quality_gates: { passed: [], failed: [], pending: [] },
+      notes: []
+    };
+  }
+  return loadJSON(sessionPath);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  let s = ensureSession();
+  if (args.workflow) { s.project.workflow = args.workflow; s.current_context.active_workflow = args.workflow; }
+  if (!Number.isNaN(args.step)) { s.current_context.current_step = args.step; s.workflow_progress.current_step = args.step; }
+  if (args.route && fs.existsSync(args.route)) { s.route_decision = loadJSON(args.route); }
+  if (args.addArtifact.length) s.artifacts.generated = uniq(s.artifacts.generated.concat(args.addArtifact));
+  if (args.addSchema.length) s.artifacts.schemas_used = uniq(s.artifacts.schemas_used.concat(args.addSchema));
+  s.last_updated = new Date().toISOString();
+  saveJSON(sessionPath, s);
+}
+
+main();
+

.claude/workflows/brownfield-fullstack.yaml

@@ -95,7 +95,7 @@ sequence:
     template: ui_spec
     inputs:
       - ".claude/context/artifacts/prd.json"
-    creates: ".claude/context/artifacts/ui-enhancement-spec.json"
+    creates: ".claude/context/artifacts/ux-spec.json"
     validators:
       - schema: ".claude/schemas/ux_spec.schema.json"
     on_fail:
@@ -103,8 +103,8 @@ sequence:
       escalate_to: "architect"
     render:
       renderer: "ux-spec"
-      from: ".claude/context/artifacts/ui-enhancement-spec.json"
-      to: ".claude/context/artifacts/ui-enhancement-spec.md"
+      from: ".claude/context/artifacts/ux-spec.json"
+      to: ".claude/context/artifacts/ui-spec.md"
     depends_on: [2, 3]
     optional: true
     condition: frontend_changes_required
@@ -116,7 +116,7 @@ sequence:
       Design enhancements that maintain consistency with existing UI patterns
       Plan component updates, new interactions, and design system integration
       Consider user experience implications of changes to existing workflows
-      Save output to .claude/context/artifacts/ui-enhancement-spec.md
+      Save output to .claude/context/artifacts/ui-spec.md
     
   - step: 5
     name: "Integration Architecture"
@@ -125,7 +125,7 @@ sequence:
     template: brownfield_architecture
     inputs:
       - ".claude/context/artifacts/prd.json"
-      - ".claude/context/artifacts/ui-enhancement-spec.md"
+      - ".claude/context/artifacts/ui-spec.md"
     creates: ".claude/context/artifacts/architecture.json"
     validators:
       - schema: ".claude/schemas/system_architecture.schema.json"
@@ -242,8 +242,8 @@ outputs:
     - system-analysis.md
     - prd.json
     - prd.md
-    - ui-enhancement-spec.json (optional)
-    - ui-enhancement-spec.md (optional)
+    - ux-spec.json (optional)
+    - ui-spec.md (optional)
     - architecture.json (conditional)
     - architecture.md (conditional)
     - test-plan.json

.claude/workflows/brownfield-ui.yaml

@@ -69,7 +69,7 @@ sequence:
     template: ui_spec
     inputs:
       - ".claude/context/artifacts/prd.json"
-    creates: ".claude/context/artifacts/front-end-spec.json"
+    creates: ".claude/context/artifacts/ux-spec.json"
     validators:
       - schema: ".claude/schemas/ux_spec.schema.json"
     on_fail:
@@ -77,8 +77,8 @@ sequence:
       escalate_to: "architect"
     render:
       renderer: "ux-spec"
-      from: ".claude/context/artifacts/front-end-spec.json"
-      to: ".claude/context/artifacts/front-end-spec.md"
+      from: ".claude/context/artifacts/ux-spec.json"
+      to: ".claude/context/artifacts/ui-spec.md"
     depends_on: [1, 2]
     description: "Design UI enhancements that integrate with existing system"
     instructions: |
@@ -88,7 +88,7 @@ sequence:
       Design enhancements that respect existing design patterns and user expectations
       Create transition strategies for design changes and new interaction patterns
       Ensure consistency with existing components while introducing improvements
-      Save output to .claude/context/artifacts/front-end-spec.md
+      Save output to .claude/context/artifacts/ui-spec.md
     
   - step: 4
     name: "Integration Architecture"
@@ -96,7 +96,7 @@ sequence:
     task: design_integration_strategy
     template: brownfield_architecture
     inputs:
-      - ".claude/context/artifacts/front-end-spec.md"
+      - ".claude/context/artifacts/ui-spec.md"
       - ".claude/context/artifacts/prd.json"
     creates: ".claude/context/artifacts/architecture.json"
     validators:
@@ -193,8 +193,8 @@ outputs:
     - ui-analysis.md
     - prd.json
     - prd.md
-    - front-end-spec.json
-    - front-end-spec.md
+    - ux-spec.json
+    - ui-spec.md
     - architecture.json
     - architecture.md
     - test-plan.json

.claude/workflows/greenfield-fullstack.yaml

@@ -86,7 +86,7 @@ sequence:
     render:
       renderer: "ux-spec"
       from: ".claude/context/artifacts/ux-spec.json"
-      to: ".claude/context/artifacts/front-end-spec.md"
+      to: ".claude/context/artifacts/ui-spec.md"
     depends_on: [2]
     description: "Design user interface and experience"
     instructions: |
@@ -95,14 +95,14 @@ sequence:
       Apply the UI spec template from .claude/templates/ui-spec.md
       Generate comprehensive UI/UX specifications including wireframes and user flows
       Design responsive interfaces and interaction patterns
-      Save output to .claude/context/artifacts/front-end-spec.md
+      Save output to .claude/context/artifacts/ui-spec.md
     
   - step: 4
     name: "AI UI Generation Prompt"
     agent: ux-expert
     task: generate_ai_prompt
     inputs:
-      - ".claude/context/artifacts/front-end-spec.md"
+      - ".claude/context/artifacts/ui-spec.md"
     creates: ".claude/context/artifacts/v0-prompt.md"
     depends_on: [3]
     optional: true
@@ -149,7 +149,7 @@ sequence:
     task: implement_frontend
     creates: "src/frontend/"
     inputs:
-      - ".claude/context/artifacts/front-end-spec.md"
+      - ".claude/context/artifacts/ui-spec.md"
       - ".claude/context/artifacts/fullstack-architecture.md"
     depends_on: [3, 5]
     description: "Implement frontend components and pages"
@@ -184,7 +184,7 @@ sequence:
     task: create_test_plan
     template: test_plan
     inputs:
-      - ".claude/context/artifacts/front-end-spec.md"
+    - ".claude/context/artifacts/ui-spec.md"
       - ".claude/context/artifacts/fullstack-architecture.md"
     creates: ".claude/context/artifacts/test-plan.json"
     validators:
@@ -240,7 +240,7 @@ outputs:
     - prd.json
     - prd.md
     - ux-spec.json
-    - front-end-spec.md
+    - ui-spec.md
     - system-architecture.json
     - fullstack-architecture.md
     - test-plan.json

AGENTS.md

@@ -0,0 +1,19 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+The orchestrator logic lives in `.claude/`, with agent playbooks under `.claude/agents/`, reusable tasks in `.claude/tasks/`, and workflow automation scripts inside `.claude/tools/`. Runtime artifacts and validation history are kept in `.claude/context/`; keep generated JSON there so the CI validators can discover them. Reference material for contributors sits in `docs/` (see `docs/README.md` for navigation), while GitHub Actions and shared issue templates reside in `.github/`.
+
+## Build, Test, and Development Commands
+Run `node .claude/tools/ci/validate-all.mjs` before every commit; it sweeps all artifacts against the schemas and mirrors the `Validate Artifacts` workflow. Use `node .claude/tools/gates/gate.mjs --schema <schema> --input <artifact> --gate <gate>` when touching a specific gate, e.g., `node .claude/tools/gates/gate.mjs --schema .claude/schemas/product_requirements.schema.json --input .claude/context/artifacts/prd.json --gate .claude/context/history/gates/greenfield-fullstack/02-pm.json --autofix 1`. Render human-readable reports with `node .claude/tools/renderers/bmad-render.mjs <type> <json> > <md>`.
+
+## Coding Style & Naming Conventions
+Match existing kebab-case directory names (`bmad-orchestrator`, `system-architecture`), and keep filenames lowercase with hyphens. YAML in `config.yaml` uses two-space indentation; mirror that in any new configuration. JSON artifacts must remain minified-friendly, double-quoted, and schema-compliant. Markdown documents favor sentence-case headings and descriptive bullet lists—ensure long lists stay scannable.
+
+## Testing Guidelines
+Treat schema validation as the test suite: every artifact change requires a green run of `validate-all.mjs`. Store new fixtures under `.claude/context/artifacts/` and schemas in `.claude/schemas/`; name tests after the schema they exercise (e.g., `ux_spec.schema.json`). When introducing a schema, add at least one representative artifact and, if behavior differs by workflow, capture each route in `.claude/context/history/gates/`.
+
+## Commit & Pull Request Guidelines
+Commits follow lightweight Conventional Commits (`feat:`, `Build:`, `documentation updates`); keep the first line under 72 characters and prefer imperative verbs (“Add”, “Update”). For pull requests, include a concise change summary, validation evidence (paste the `validate-all.mjs` output), and links to relevant issues or workflow runs. Screenshots or rendered Markdown are required when modifying artifact renderers or documentation meant for stakeholders.
+
+## Security & Configuration Tips
+Never commit API keys or tenant-specific data; redact sensitive context before placing files in `.claude/context/`. Configuration defaults live in `.claude/config.yaml`; extend them via environment variables or layered YAML files rather than hardcoding values. When sharing examples, use anonymized project names and neutral sample data to keep the enterprise presets reusable.

package.json

@@ -0,0 +1,20 @@
+{
+  "name": "bmad-spec-kit",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "preflight": "node .claude/tools/context/preflight.mjs",
+    "validate": "node .claude/tools/ci/validate-all.mjs",
+    "scaffold": "node .claude/tools/context/scaffold.mjs",
+    "route:gate": "node .claude/tools/gates/gate.mjs --schema .claude/schemas/route_decision.schema.json --input .claude/context/artifacts/route-decision.json --gate .claude/context/history/gates/ci/00-orchestrator.json --autofix 1",
+    "session:update": "node .claude/tools/context/update-session.mjs",
+    "render:project-brief": "node .claude/tools/renderers/bmad-render.mjs project-brief",
+    "render:prd": "node .claude/tools/renderers/bmad-render.mjs prd",
+    "render:architecture": "node .claude/tools/renderers/bmad-render.mjs architecture",
+    "render:ux-spec": "node .claude/tools/renderers/bmad-render.mjs ux-spec",
+    "render:test-plan": "node .claude/tools/renderers/bmad-render.mjs test-plan"
+    ,"render:all": "node .claude/tools/context/render-all.mjs"
+  }
+}