@jgamaraalv/ts-dev-kit 2.3.0 → 3.0.0

package/skills/core-web-vitals/scripts/visualize.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Core Web Vitals Visual Report Generator
+
+Usage:
+  python3 visualize.py --lcp 2.1 --inp 180 --cls 0.05
+  python3 visualize.py --lighthouse report.json
+  python3 visualize.py --lcp 1.8 --inp 95 --cls 0.02 --url https://example.com --output report.html
+"""
+
+import argparse
+import json
+import sys
+import webbrowser
+from datetime import datetime
+from pathlib import Path
+
+METRICS = {
+    "lcp": {
+        "name": "LCP",
+        "full": "Largest Contentful Paint",
+        "desc": "How fast the main content loads",
+        "unit": "s",
+        "good": 2.5,
+        "ni": 4.0,
+        "scale": 6.0,
+        "fmt": lambda v: f"{v:.2f} s",
+    },
+    "inp": {
+        "name": "INP",
+        "full": "Interaction to Next Paint",
+        "desc": "How fast the page responds to interactions",
+        "unit": "ms",
+        "good": 200,
+        "ni": 500,
+        "scale": 700,
+        "fmt": lambda v: f"{int(v)} ms",
+    },
+    "cls": {
+        "name": "CLS",
+        "full": "Cumulative Layout Shift",
+        "desc": "How stable the layout is while loading",
+        "unit": "",
+        "good": 0.1,
+        "ni": 0.25,
+        "scale": 0.35,
+        "fmt": lambda v: f"{v:.3f}",
+    },
+}
+
+COLORS = {
+    "good": "#0CCE6B",
+    "needs-improvement": "#FFA400",
+    "poor": "#FF4E42",
+}
+
+LABELS = {
+    "good": "Good",
+    "needs-improvement": "Needs Improvement",
+    "poor": "Poor",
+}
+
+
+def get_rating(key, value):
+    m = METRICS[key]
+    if value <= m["good"]:
+        return "good"
+    if value <= m["ni"]:
+        return "needs-improvement"
+    return "poor"
+
+
+def pct(key, value):
+    return min(100, round((value / METRICS[key]["scale"]) * 100))
+
+
+def zone_pct(key, threshold):
+    return round((threshold / METRICS[key]["scale"]) * 100)
+
+
+def card_html(key, value):
+    m = METRICS[key]
+    rating = get_rating(key, value)
+    color = COLORS[rating]
+    marker_left = pct(key, value)
+    good_w = zone_pct(key, m["good"])
+    ni_w = zone_pct(key, m["ni"]) - good_w
+    poor_w = 100 - good_w - ni_w
+
+    return f"""
+    <div class="card" style="border-top:4px solid {color}">
+      <div class="card-top">
+        <span class="metric-name">{m["name"]}</span>
+        <span class="badge" style="background:{color}">{LABELS[rating]}</span>
+      </div>
+      <div class="metric-full">{m["full"]}</div>
+      <div class="metric-desc">{m["desc"]}</div>
+      <div class="value" style="color:{color}">{m["fmt"](value)}</div>
+      <div class="bar-wrap">
+        <div class="bar-track">
+          <div class="zone" style="width:{good_w}%;background:{COLORS['good']}30"></div>
+          <div class="zone" style="width:{ni_w}%;background:{COLORS['needs-improvement']}30"></div>
+          <div class="zone" style="width:{poor_w}%;background:{COLORS['poor']}30"></div>
+        </div>
+        <div class="marker" style="left:{marker_left}%;background:{color}"></div>
+      </div>
+      <div class="thresholds">
+        <span style="color:{COLORS['good']}">&#9679; Good ≤ {m["fmt"](m["good"])}</span>
+        <span style="color:{COLORS['needs-improvement']}">&#9679; NI ≤ {m["fmt"](m["ni"])}</span>
+        <span style="color:{COLORS['poor']}">&#9679; Poor > {m["fmt"](m["ni"])}</span>
+      </div>
+    </div>"""
+
+
+def generate_report(url, lcp, inp, cls_, generated_at):
+    values = {"lcp": lcp, "inp": inp, "cls": cls_}
+    present = {k: v for k, v in values.items() if v is not None}
+    ratings = {k: get_rating(k, v) for k, v in present.items()}
+
+    all_good = all(r == "good" for r in ratings.values())
+    any_poor = any(r == "poor" for r in ratings.values())
+    overall_label = "PASS" if all_good else ("FAIL" if any_poor else "NEEDS IMPROVEMENT")
+    overall_color = COLORS["good"] if all_good else (COLORS["poor"] if any_poor else COLORS["needs-improvement"])
+
+    cards = "\n".join(card_html(k, v) for k, v in present.items())
+    url_line = f'<p class="url">{url}</p>' if url else ""
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Core Web Vitals Report</title>
+  <style>
+    *{{box-sizing:border-box;margin:0;padding:0}}
+    body{{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#f4f4f5;color:#18181b}}
+    header{{background:#fff;border-bottom:1px solid #e4e4e7;padding:24px 32px}}
+    h1{{font-size:20px;font-weight:700;color:#09090b}}
+    .url{{font-size:13px;color:#71717a;margin-top:4px;word-break:break-all}}
+    .meta{{font-size:12px;color:#a1a1aa;margin-top:3px}}
+    .overall{{display:inline-flex;align-items:center;gap:6px;margin-top:12px;padding:5px 14px;border-radius:999px;font-size:13px;font-weight:700;color:#fff}}
+    .grid{{display:grid;grid-template-columns:repeat(auto-fit,minmax(270px,1fr));gap:16px;padding:28px 32px;max-width:1050px;margin:0 auto}}
+    .card{{background:#fff;border-radius:10px;padding:22px;box-shadow:0 1px 3px rgba(0,0,0,.07)}}
+    .card-top{{display:flex;justify-content:space-between;align-items:center;margin-bottom:3px}}
+    .metric-name{{font-size:22px;font-weight:800;letter-spacing:-.5px}}
+    .badge{{font-size:10px;font-weight:700;letter-spacing:.4px;color:#fff;padding:3px 9px;border-radius:999px}}
+    .metric-full{{font-size:12px;color:#52525b;margin-bottom:2px}}
+    .metric-desc{{font-size:11px;color:#a1a1aa;margin-bottom:16px}}
+    .value{{font-size:42px;font-weight:800;letter-spacing:-1.5px;line-height:1;margin-bottom:18px}}
+    .bar-wrap{{position:relative;height:12px;margin-bottom:12px}}
+    .bar-track{{display:flex;width:100%;height:8px;border-radius:4px;overflow:hidden;margin-top:2px}}
+    .zone{{height:100%}}
+    .marker{{position:absolute;top:50%;transform:translate(-50%,-50%);width:14px;height:14px;border-radius:50%;border:3px solid #fff;box-shadow:0 1px 4px rgba(0,0,0,.25)}}
+    .thresholds{{display:flex;gap:10px;flex-wrap:wrap;font-size:11px}}
+    footer{{text-align:center;padding:20px;font-size:12px;color:#d4d4d8}}
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Core Web Vitals Report</h1>
+    {url_line}
+    <p class="meta">Generated: {generated_at}</p>
+    <div class="overall" style="background:{overall_color}">{overall_label}</div>
+  </header>
+  <div class="grid">
+    {cards}
+  </div>
+  <footer>Generated by ts-dev-kit &middot; core-web-vitals skill</footer>
+</body>
+</html>"""
+
+
+def parse_lighthouse(path):
+    with open(path) as f:
+        data = json.load(f)
+    url = data.get("finalUrl") or data.get("requestedUrl") or ""
+    audits = data.get("audits", {})
+    lcp_ms = (audits.get("largest-contentful-paint") or {}).get("numericValue")
+    inp_ms = (audits.get("interaction-to-next-paint") or {}).get("numericValue")
+    cls = (audits.get("cumulative-layout-shift") or {}).get("numericValue")
+    lcp = lcp_ms / 1000 if lcp_ms is not None else None
+    return url, lcp, inp_ms, cls
+
+
+def main():
+    p = argparse.ArgumentParser(description="Generate a Core Web Vitals HTML report")
+    p.add_argument("--lcp", type=float, help="LCP in seconds (e.g. 2.1)")
+    p.add_argument("--inp", type=float, help="INP in milliseconds (e.g. 180)")
+    p.add_argument("--cls", type=float, help="CLS score (e.g. 0.05)")
+    p.add_argument("--lighthouse", help="Path to a Lighthouse JSON output file")
+    p.add_argument("--url", help="URL that was tested (display only)")
+    p.add_argument("--output", default="cwv-report.html", help="Output HTML file path")
+    p.add_argument("--no-open", action="store_true", help="Do not open in browser")
+    args = p.parse_args()
+
+    url = args.url or ""
+    lcp, inp, cls_ = args.lcp, args.inp, args.cls
+
+    if args.lighthouse:
+        lh_url, lh_lcp, lh_inp, lh_cls = parse_lighthouse(args.lighthouse)
+        url = url or lh_url
+        lcp = lcp if lcp is not None else lh_lcp
+        inp = inp if inp is not None else lh_inp
+        cls_ = cls_ if cls_ is not None else lh_cls
+
+    if lcp is None and inp is None and cls_ is None:
+        print("Error: no metrics provided.", file=sys.stderr)
+        print("Usage: visualize.py --lcp 2.1 --inp 180 --cls 0.05", file=sys.stderr)
+        print("       visualize.py --lighthouse report.json", file=sys.stderr)
+        sys.exit(1)
+
+    html = generate_report(url, lcp, inp, cls_, datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
+    out = Path(args.output)
+    out.write_text(html, encoding="utf-8")
+    print(f"Report saved to {out.resolve()}")
+
+    if not args.no_open:
+        webbrowser.open(out.resolve().as_uri())
+
+
+if __name__ == "__main__":
+    main()

package/skills/debug/SKILL.md

@@ -2,8 +2,17 @@
 name: debug
 description: "End-to-end debugging workflow that triages, reproduces, and fixes bugs across the full stack using multi-agent orchestration. Use when: (1) encountering runtime errors in the API or web app, (2) investigating failed requests or broken user flows, (3) debugging production issues via Sentry/PostHog, (4) tracing data flow across backend and frontend, or (5) the user reports a bug that spans multiple layers."
 argument-hint: "[error-description or sentry-issue-url]"
+allowed-tools: Bash(git *)
 ---
 
+<live_context>
+**Recent git changes (regression candidates):**
+!`git log --oneline -10 2>/dev/null || echo "(not a git repo)"`
+
+**Working tree status:**
+!`git status --short 2>/dev/null || echo "(not a git repo)"`
+</live_context>
+
 <trigger_examples>
 - "Debug why the form submission fails with a 500 error"
 - "The dashboard page shows a blank screen after login"
@@ -220,33 +229,7 @@ Quick reference for the most frequent bugs in this stack. Use these to accelerat
 </common_patterns>
 
 <output>
-When complete, produce a debug report:
-
-```
-## Bug resolved
-
-**Root cause**: one sentence describing why the bug occurred.
-**Fix**: one sentence describing what was changed to fix it.
-
-### Investigation path
-Brief trace of how the root cause was found (which layer, what evidence).
-
-### Files changed
-List every file created/modified.
-
-### Verification
-- Reproduction: pass (the original error no longer occurs)
-- tsc: pass/fail (per package)
-- lint: pass/fail (per package)
-- test: pass/fail (per package)
-- Browser: pass/fail (if applicable)
-
-### Skills loaded
-List every Skill() call made.
-
-### MCPs used
-List every MCP used, or "none".
-```
+When complete, produce a debug report using the template in [template.md](template.md).
 
 Do not add explanations, caveats, or follow-up suggestions unless the user asks.
 </output>

package/skills/debug/template.md

@@ -0,0 +1,23 @@
+## Bug resolved
+
+**Root cause**: one sentence describing why the bug occurred.
+**Fix**: one sentence describing what was changed to fix it.
+
+### Investigation path
+Brief trace of how the root cause was found (which layer, what evidence).
+
+### Files changed
+List every file created/modified.
+
+### Verification
+- Reproduction: pass (the original error no longer occurs)
+- tsc: pass/fail (per package)
+- lint: pass/fail (per package)
+- test: pass/fail (per package)
+- Browser: pass/fail (if applicable)
+
+### Skills loaded
+List every Skill() call made.
+
+### MCPs used
+List every MCP used, or "none".

package/skills/{task → execute-task}/SKILL.md

@@ -1,27 +1,59 @@
 ---
-name: task
-description: "Use this skill when the user wants to implement a new task in the project. Covers feature development, refactoring, bug fixes, and any code change that requires context analysis, role assignment, and structured execution. For changes under ~30 lines in a single file, implement directly without this workflow."
-argument-hint: "[task-description or task-md-file-path]"
+name: execute-task
+description: "Executes a task, either from a TASK_N.md file or a free-form description. Use when: (1) implementing a task from a TASK_N.md file, (2) the user provides a task file path or says 'execute this task', 'implement TASK_02', or 'run this task', (3) the user describes a task directly without a document. Accepts a file path or a free-form description — if the task document is missing required sections (scope, success criteria, verification plan), automatically calls /generate-tasks to produce it before executing."
+argument-hint: "[task-md-file-path | task-description]"
 ---
 
 <trigger_examples>
+- "Execute TASK_02"
+- "Implement docs/features/search/TASK_01.md"
+- "Run this task"
+- "Execute the task"
 - "Implement the search feature"
 - "Build the user creation flow end-to-end"
-- "Refactor the auth module to use shared schemas"
 - "Add the notifications endpoint to the API"
-- "Fix the pagination bug"
-- "Execute this task"
 </trigger_examples>
 
+<task>
+$ARGUMENTS
+</task>
+
 <workflow>
 Follow each phase in order. Each one feeds the next.
 
+<phase_0_intake>
+Resolve the input and ensure the task document is complete before executing.
+
+**Step 1 — Determine input type:**
+- If `$ARGUMENTS` looks like a file path (ends in `.md`, or starts with `/`, `./`, `docs/`, or contains a directory separator): read the file.
+- Otherwise: treat it as a free-form task description — skip to Step 3.
+
+**Step 2 — Validate the task document:**
+A task document is ready for execution when it contains ALL of:
+- `## Scope — Files` with at least one file entry
+- `## Success Criteria` with at least one testable criterion
+- `## Verification Plan` with baseline and post-change checks
+
+If all required sections are present → proceed to phase 1.
+
+**Step 3 — Generate the task document:**
+If the document is missing any required section, OR the input was a free-form description:
+
+1. Inform the user:
+   > **Task document incomplete.** Generating a structured task document via `/generate-tasks` before proceeding.
+2. Call `Skill(skill: "generate-tasks")` passing the original input as context.
+3. After generation, note the path of the saved `TASK_N.md` file.
+4. Read the generated file and confirm all required sections are present.
+5. Resume execution using the generated document — continue to phase 1.
+</phase_0_intake>
+
 <phase_1_context_analysis>
 Before writing any code, build a mental model of the task scope.
 
-1. Read the project CLAUDE.md and root package.json — understand the project structure, available commands, and dependency graph.
-2. Search the codebase for existing patterns — use Grep/Glob to find related files, similar implementations, and reusable code.
-3. Identify the affected packages/directories — determine which parts of the project will be touched and in what order.
+1. Read the resolved task document fully (path determined in phase 0).
+2. Read the project CLAUDE.md and root package.json — understand project structure, available commands, and dependency graph.
+3. Search the codebase for existing patterns — use Grep/Glob to find related files, similar implementations, and reusable code relevant to the task's file scope.
+4. Identify the affected packages/directories from the task's "Scope — Files" section.
 </phase_1_context_analysis>
 
 <phase_2_role_assignment>
@@ -223,7 +255,7 @@ The main session acts as the orchestrator:
 3. Dispatch the first wave of agents (those with no blockers).
 4. When a blocking agent completes, dispatch the next wave.
 5. After all agents complete, run the final quality gates.
-6. Produce the completion report (see references/output-templates.md).
+6. Produce the completion report (see template.md).
 
 Constraints:
 1. Subagents cannot spawn other subagents. All dispatch happens from the main session.
@@ -260,42 +292,44 @@ In PLAN mode: use EnterPlanMode to design the full plan. Once the user approves
 </phase_2b_multi_role_decomposition>
 
 <phase_3_task_analysis>
-1. Extract task-defined criteria — scan the task document for explicit:
-   - **Success criteria** (checklists, acceptance conditions)
-   - **Initial/baseline tests** (to run BEFORE changes, for comparison)
-   - **Post-change tests** (to run AFTER changes, for verification)
-   - **Performance benchmarks** (bundle size, API call counts, Lighthouse metrics)
-
-   Look for section names like: "Initial Tests", "Before Changes", "Baseline", "Post-Change Tests", "After Changes", "Success Criteria", "Acceptance Criteria", "Functionality Tests", "Performance Tests".
-
-   If found, state them to the user:
-   > **Task-defined criteria found:**
-   > - Success criteria: [list]
-   > - Baseline tests (before changes): [list or "none"]
-   > - Post-change tests (after changes): [list or "none"]
-
-   These are binding requirements that extend the default quality gates. Do not skip them.
-
-2. Understand the request — identify what is being asked, which files will be created or modified, and what the expected outcome is.
-3. Define success criteria — combine the task's own criteria (from step 1) with your analysis. Task-defined criteria take priority over defaults.
-4. For questions about project libraries, use Context7 (`mcp__context7__resolve-library-id` → `mcp__context7__query-docs`) to query up-to-date documentation. If anything is ambiguous, ask the user before proceeding.
-5. Check for helpful MCPs — does the task involve browser testing, external docs?
-6. Plan the implementation order — determine which changes must happen first (e.g., types before lib before hooks before components before pages).
-7. Generate the verification plan — build a before/after test plan combining task-defined criteria with automatic checks based on domain and available MCPs. See references/verification-protocol.md for the full protocol.
-   - Detect available testing MCPs (playwright, chrome-devtools, or none).
-   - Map the task domain to checks: frontend → visual + performance, backend → API responses, database → schema state.
-   - Always include standard quality gates (lint, build, test) as baseline.
-   - Present the plan:
-     > **Verification plan:**
-     > - Baseline checks: [list]
-     > - MCPs for verification: [list or "none available — shell-only checks"]
-     > - Post-change checks: [list]
+Read the task document and load the criteria defined there. These are binding requirements for this execution.
+
+1. Extract from the task document:
+   - **Success criteria** — exact conditions for task completion
+   - **Baseline checks** — what to run/capture BEFORE changes
+   - **Post-change checks** — what to verify AFTER changes
+   - **Performance benchmarks** — specific metrics with targets
+   - **Non-functional requirements** — scoped to this task's domain
+   - **Scope — Files** — the exact list of files to create or modify
+
+   State them to the user:
+   > **Task loaded:** [task title]
+   > - Dependencies: [list or "none"]
+   > - Files in scope: N files
+   > - Success criteria: [count] criteria
+   > - Baseline checks: [list]
+   > - Post-change checks: [list]
+   > - Performance targets: [list or "none defined"]
+
+2. For questions about project libraries, use Context7 (`mcp__context7__resolve-library-id` → `mcp__context7__query-docs`) to query up-to-date documentation. If anything is ambiguous, ask the user before proceeding.
+
+3. Check MCP availability — use ToolSearch to detect which browser MCPs are available (playwright, chrome-devtools, or neither), then confirm against the task's "MCP Checks" section.
+
+4. Plan the implementation order from the task's file scope — build dependencies before dependents:
+   shared types → database schema → API layer → UI components → pages → tests.
+
+5. Confirm the verification plan with the user:
+   > **Verification plan:**
+   > - Baseline checks: [from task doc]
+   > - MCPs available: [detected list or "none — shell-only"]
+   > - Post-change checks: [from task doc]
 </phase_3_task_analysis>
 
 <phase_3b_baseline_capture>
 **MANDATORY.** Run the verification plan before writing any code to establish the baseline for comparison. Do NOT skip this phase.
 
 **Step 1: Standard quality gates** — run and record results (pass/fail, counts, bundle sizes).
+Discover the exact commands from package.json scripts for each affected package.
 
 **Step 2: MCP-based checks** — follow this decision tree in order:
 
@@ -360,7 +394,7 @@ Discover the available commands from package.json scripts for each affected pack
 2. Linting — run the project's lint command (e.g., `lint`, `eslint`)
 3. Tests (if available) — run the project's test command (e.g., `test`, `vitest`)
 4. Build — run the project's build command (e.g., `build`)
-5. Self-check — review your changes against the success criteria defined in phase 3.
+5. Self-check — review your changes against the success criteria from the task document.
 
 For monorepos, run these for each affected workspace/package. Discover the workspace command pattern from CLAUDE.md or the root package.json (e.g., `yarn workspace <name> <script>`, `pnpm --filter <name> <script>`, `npm -w <name> <script>`, `turbo run <script> --filter=<name>`).
 
@@ -378,9 +412,9 @@ After all quality gates pass, re-run the verification plan from phase 3b and com
 2. Compare each result against baseline:
    - **Quality gates**: must remain passing. New failures = regression.
    - **Visual checks** (if MCPs available): compare screenshots for unintended changes.
-   - **Performance** (if MCPs available): compare metrics. Regressions > 10% must be investigated.
+   - **Performance** (if MCPs available): compare metrics against task-defined benchmarks. Regressions > 10% must be investigated.
    - **API responses**: compare status codes and payload shapes. Breaking changes = regression.
-3. Build the comparison table (see references/output-templates.md for format).
+3. Build the comparison table (see template.md for format).
 
 If any regression is found, fix it, re-run phase 5 quality gates, then re-run this phase. Repeat until clean.
 </phase_5b_post_change_verification>
@@ -396,13 +430,7 @@ Only update documentation directly affected by the changes. Do not create new do
 </workflow>
 
 <output>
-When complete, produce the completion report including the baseline vs post-change comparison table. See references/output-templates.md for the exact format.
-
-If the task document specifies a results file path, also create the comparison report at that path.
+When complete, produce the completion report including the baseline vs post-change comparison table. See template.md for the exact format.
 
 Do not add explanations, caveats, or follow-up suggestions unless the user explicitly asks. The report is the final output.
 </output>
-
-<task>
-{{task}}
-</task>

package/skills/generate-prd/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: generate-prd
+description: "Generates a complete, structured, and implementation-ready Product Requirements Document (PRD). Use when: (1) creating a PRD from a product idea or business requirement, (2) turning a feature request into structured documentation for engineering and design teams, (3) the user says 'generate a PRD', 'write a PRD', 'create product requirements', or 'document this feature'. Covers vision, problem statement, objectives, scope, personas, user journeys, functional and non-functional requirements, constraints, success metrics, assumptions, risks, and acceptance criteria.'
+argument-hint: "[product-idea | feature-description | business-context | prd-md-file-path]"
+---
+
+<system>
+You are a Senior Product Manager and Product Strategist. Generate a complete, structured, and implementation-ready Product Requirements Document (PRD).
+</system>
+
+<spec>
+$ARGUMENTS
+</spec>
+
+<workflow>
+Follow each phase in order.
+
+<phase_1_context_analysis>
+Build a mental model of the spec scope before writing:
+- Identify target users and their core problem
+- Understand business objectives and success criteria
+- Clarify scope boundaries (what's included and what's not)
+</phase_1_context_analysis>
+
+<phase_2_clarify>
+If you are uncertain about anything or information is missing to generate the PRD, pause and ask the user before continuing. Do not assume or deduce missing context.
+</phase_2_clarify>
+
+<phase_3_plan>
+If the request is broad or complex, enter plan mode to outline sections before generating the full document.
+</phase_3_plan>
+
+<phase_4_generate>
+Write the PRD following these standards:
+- Translate business goals into clear, testable product requirements
+- Define user problems, value proposition, and success criteria
+- Use the sections defined in [template.md](template.md)
+- Ensure precision — avoid vague or generic statements
+- Write for engineering, design, and business stakeholders
+- Include Mermaid diagrams for key user journeys
+- Include functional and non-functional requirements
+</phase_4_generate>
+</workflow>
+
+
+<constraints>
+Do not include:
+- Code or implementation details
+- Technical architecture decisions
+- Step-by-step "how to build" guides
+- File or folder structure suggestions
+</constraints>
+
+<output>
+Save the document to `[project-root]/docs/features/[FEATURE_NAME]/PRD.md`.
+</output>

package/skills/generate-prd/template.md

@@ -0,0 +1,69 @@
+# [Product Name] — PRD
+
+**Version**: [x.x]
+**Date**: [YYYY-MM-DD]
+**Authors**: [names]
+
+## 1. Problem Statement
+[User pain points and context]
+
+## 2. Product Vision
+[Goal and value proposition]
+
+## 3. Objectives
+[Measurable business and product goals]
+
+## 4. Scope
+
+**Included:**
+- [...]
+
+**Excluded:**
+- [...]
+
+## 5. User Personas
+
+### [Persona Name]
+- **Goal**: [...]
+- **Pain point**: [...]
+
+## 6. User Journeys
+
+```mermaid
+flowchart TD
+  A[...] --> B[...]
+```
+
+## 7. Functional Requirements
+
+1. [Atomic, numbered requirement]
+2. [...]
+
+## 8. Non-functional Requirements
+
+- **Performance**: [targets]
+- **Security**: [requirements]
+- **Accessibility**: [WCAG level and specifics]
+- **Scalability**: [requirements]
+
+## 9. Constraints
+
+- [Technical, business, or regulatory limitations]
+
+## 10. Success Metrics
+
+- [KPI]: [target value]
+
+## 11. Assumptions
+
+- [What is assumed true for this PRD]
+
+## 12. Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| [risk] | High/Med/Low | High/Med/Low | [mitigation] |
+
+## 13. Acceptance Criteria
+
+- [ ] [Condition for feature completion]