From 38b0583283d4bf913a8684ab13a4cbfac8ec1060 Mon Sep 17 00:00:00 2001 From: oimiragieo Date: Thu, 18 Sep 2025 00:20:53 -0400 Subject: [PATCH] fine tuned code updated lots of code to automate and fix gaps. --- .claude/agents/analyst/prompt.md | 2 + .claude/agents/architect/prompt.md | 3 + .claude/agents/bmad-orchestrator/prompt.md | 9 +++ .claude/agents/developer/prompt.md | 8 +++ .claude/agents/pm/prompt.md | 2 + .claude/agents/qa/prompt.md | 2 + .claude/agents/ux-expert/prompt.md | 2 + .claude/context/history/reasoning/.gitkeep | 1 + .claude/examples/specs/enhancement_spec.md | 22 +++++++ .claude/examples/specs/user_spec.md | 26 ++++++++ .claude/rules/manifest.yaml | 8 +-- .claude/system/context-protocol.md | 41 ++++++++++++ .claude/templates/brownfield-architecture.md | 44 +++++++++++++ .claude/templates/fullstack-architecture.md | 62 ++++++++++++++++++ .claude/templates/implementation-plan.md | 39 +++++++++++ .claude/tools/ci/validate-all.mjs | 4 +- .claude/tools/context/preflight.mjs | 26 ++++++++ .claude/tools/context/render-all.mjs | 63 ++++++++++++++++++ .claude/tools/context/scaffold.mjs | 33 ++++++++++ .claude/tools/context/update-session.mjs | 68 ++++++++++++++++++++ .claude/workflows/brownfield-fullstack.yaml | 14 ++-- .claude/workflows/brownfield-ui.yaml | 14 ++-- .claude/workflows/greenfield-fullstack.yaml | 12 ++-- AGENTS.md | 19 ++++++ package.json | 20 ++++++ src/backend/api/.gitkeep | 0 src/backend/config/.gitkeep | 0 src/backend/middleware/.gitkeep | 0 src/backend/models/.gitkeep | 0 src/backend/services/.gitkeep | 0 src/backend/utils/.gitkeep | 0 src/frontend/components/.gitkeep | 0 src/frontend/hooks/.gitkeep | 0 src/frontend/pages/.gitkeep | 0 src/frontend/styles/.gitkeep | 0 src/frontend/types/.gitkeep | 0 src/frontend/utils/.gitkeep | 0 tests/backend/.gitkeep | 0 tests/e2e/.gitkeep | 0 tests/frontend/.gitkeep | 0 tests/integration/.gitkeep | 0 41 files changed, 518 insertions(+), 26 deletions(-) create mode 100644 .claude/context/history/reasoning/.gitkeep create mode 100644 .claude/examples/specs/enhancement_spec.md create mode 100644 .claude/examples/specs/user_spec.md create mode 100644 .claude/system/context-protocol.md create mode 100644 .claude/templates/brownfield-architecture.md create mode 100644 .claude/templates/fullstack-architecture.md create mode 100644 .claude/templates/implementation-plan.md create mode 100644 .claude/tools/context/preflight.mjs create mode 100644 .claude/tools/context/render-all.mjs create mode 100644 .claude/tools/context/scaffold.mjs create mode 100644 .claude/tools/context/update-session.mjs create mode 100644 AGENTS.md create mode 100644 package.json create mode 100644 src/backend/api/.gitkeep create mode 100644 src/backend/config/.gitkeep create mode 100644 src/backend/middleware/.gitkeep create mode 100644 src/backend/models/.gitkeep create mode 100644 src/backend/services/.gitkeep create mode 100644 src/backend/utils/.gitkeep create mode 100644 src/frontend/components/.gitkeep create mode 100644 src/frontend/hooks/.gitkeep create mode 100644 src/frontend/pages/.gitkeep create mode 100644 src/frontend/styles/.gitkeep create mode 100644 src/frontend/types/.gitkeep create mode 100644 src/frontend/utils/.gitkeep create mode 100644 tests/backend/.gitkeep create mode 100644 tests/e2e/.gitkeep create mode 100644 tests/frontend/.gitkeep create mode 100644 tests/integration/.gitkeep diff --git a/.claude/agents/analyst/prompt.md b/.claude/agents/analyst/prompt.md index 44765125..68b81ba7 100644 --- a/.claude/agents/analyst/prompt.md +++ b/.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//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//01-analyst.json` with: - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). diff --git a/.claude/agents/architect/prompt.md b/.claude/agents/architect/prompt.md index 900198fb..c4e29af3 100644 --- a/.claude/agents/architect/prompt.md +++ b/.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. ## **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): diff --git a/.claude/agents/bmad-orchestrator/prompt.md b/.claude/agents/bmad-orchestrator/prompt.md index c2421e7a..e224cf72 100644 --- a/.claude/agents/bmad-orchestrator/prompt.md +++ b/.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//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/*`). diff --git a/.claude/agents/developer/prompt.md b/.claude/agents/developer/prompt.md index 318963f6..cb6fcff4 100644 --- a/.claude/agents/developer/prompt.md +++ b/.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 + +## +- 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//06-developer.json --autofix 1`. +- Update `.claude/context/session.json.artifacts.generated` with added artifacts and code paths. ## diff --git a/.claude/agents/pm/prompt.md b/.claude/agents/pm/prompt.md index 7013dd62..ad6d0207 100644 --- a/.claude/agents/pm/prompt.md +++ b/.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. ## Original Agent Configuration diff --git a/.claude/agents/qa/prompt.md b/.claude/agents/qa/prompt.md index 3074ced0..224b7843 100644 --- a/.claude/agents/qa/prompt.md +++ b/.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. ## Original Agent Configuration diff --git a/.claude/agents/ux-expert/prompt.md b/.claude/agents/ux-expert/prompt.md index 5c538091..74be716f 100644 --- a/.claude/agents/ux-expert/prompt.md +++ b/.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. ## Original Agent Configuration diff --git a/.claude/context/history/reasoning/.gitkeep b/.claude/context/history/reasoning/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/.claude/context/history/reasoning/.gitkeep @@ -0,0 +1 @@ + diff --git a/.claude/examples/specs/enhancement_spec.md b/.claude/examples/specs/enhancement_spec.md new file mode 100644 index 00000000..b1ada0d1 --- /dev/null +++ b/.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 diff --git a/.claude/examples/specs/user_spec.md b/.claude/examples/specs/user_spec.md new file mode 100644 index 00000000..77744baa --- /dev/null +++ b/.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 diff --git a/.claude/rules/manifest.yaml b/.claude/rules/manifest.yaml index c8debbfe..5c811d50 100644 --- a/.claude/rules/manifest.yaml +++ b/.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-*/**" diff --git a/.claude/system/context-protocol.md b/.claude/system/context-protocol.md new file mode 100644 index 00000000..4834acbd --- /dev/null +++ b/.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/.json`. +- Rendered Markdown: write to `.claude/context/artifacts/.md`. +- Reasoning logs (shallow, auditable): `.claude/context/history/reasoning//-.json`. +- Gate records: `.claude/context/history/gates//.json`. + +## validation and rendering +- Validate every artifact against its schema using the gate tool: + - `node .claude/tools/gates/gate.mjs --schema --input --gate --autofix 1` +- Only after a pass, render Markdown for humans using the renderer: + - `node .claude/tools/renderers/bmad-render.mjs > ` +- 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. diff --git a/.claude/templates/brownfield-architecture.md b/.claude/templates/brownfield-architecture.md new file mode 100644 index 00000000..9dada0c1 --- /dev/null +++ b/.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 + diff --git a/.claude/templates/fullstack-architecture.md b/.claude/templates/fullstack-architecture.md new file mode 100644 index 00000000..757a06ea --- /dev/null +++ b/.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: — rationale, alternatives considered, status +- ADR-002: — 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 +- (technology): responsibilities, key interfaces +- (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 + diff --git a/.claude/templates/implementation-plan.md b/.claude/templates/implementation-plan.md new file mode 100644 index 00000000..e3361678 --- /dev/null +++ b/.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 + diff --git a/.claude/tools/ci/validate-all.mjs b/.claude/tools/ci/validate-all.mjs index 90dbceac..80dc0c50 100644 --- a/.claude/tools/ci/validate-all.mjs +++ b/.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); - diff --git a/.claude/tools/context/preflight.mjs b/.claude/tools/context/preflight.mjs new file mode 100644 index 00000000..2cc50fde --- /dev/null +++ b/.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'); +} + diff --git a/.claude/tools/context/render-all.mjs b/.claude/tools/context/render-all.mjs new file mode 100644 index 00000000..2d40191d --- /dev/null +++ b/.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(); + diff --git a/.claude/tools/context/scaffold.mjs b/.claude/tools/context/scaffold.mjs new file mode 100644 index 00000000..459e6f0a --- /dev/null +++ b/.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(', ')); + diff --git a/.claude/tools/context/update-session.mjs b/.claude/tools/context/update-session.mjs new file mode 100644 index 00000000..6baad1a5 --- /dev/null +++ b/.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(); + diff --git a/.claude/workflows/brownfield-fullstack.yaml b/.claude/workflows/brownfield-fullstack.yaml index 22c517c8..e8c7a6ab 100644 --- a/.claude/workflows/brownfield-fullstack.yaml +++ b/.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 diff --git a/.claude/workflows/brownfield-ui.yaml b/.claude/workflows/brownfield-ui.yaml index bd31b35e..7667a186 100644 --- a/.claude/workflows/brownfield-ui.yaml +++ b/.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 diff --git a/.claude/workflows/greenfield-fullstack.yaml b/.claude/workflows/greenfield-fullstack.yaml index bb1a8a10..db52d83e 100644 --- a/.claude/workflows/greenfield-fullstack.yaml +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..59de9a33 --- /dev/null +++ b/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 --input --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 > `. + +## 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. diff --git a/package.json b/package.json new file mode 100644 index 00000000..84f60155 --- /dev/null +++ b/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" + } +} diff --git a/src/backend/api/.gitkeep b/src/backend/api/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/backend/config/.gitkeep b/src/backend/config/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/backend/middleware/.gitkeep b/src/backend/middleware/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/backend/models/.gitkeep b/src/backend/models/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/backend/services/.gitkeep b/src/backend/services/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/backend/utils/.gitkeep b/src/backend/utils/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/frontend/components/.gitkeep b/src/frontend/components/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/frontend/hooks/.gitkeep b/src/frontend/hooks/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/frontend/pages/.gitkeep b/src/frontend/pages/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/frontend/styles/.gitkeep b/src/frontend/styles/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/frontend/types/.gitkeep b/src/frontend/types/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/src/frontend/utils/.gitkeep b/src/frontend/utils/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/tests/backend/.gitkeep b/tests/backend/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/tests/e2e/.gitkeep b/tests/e2e/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/tests/frontend/.gitkeep b/tests/frontend/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/tests/integration/.gitkeep b/tests/integration/.gitkeep new file mode 100644 index 00000000..e69de29b