@massa-ai/cursor-plugin 1.26.0 → 1.29.0

package/skills/massa-ai/scripts/validate_design.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env bun
+/**
+ * validate_design.ts - deterministic closure-gate checks for a feature
+ * design.md (STO-9 top validator pack).
+ *
+ * Turns the spec-driven Design phase's "required sections + every flagged
+ * concern has a mitigation" rule into a checkable pass/fail run, instead of
+ * trusting the model to remember it. Same heuristic-markdown-inspection
+ * style as validate_spec.ts: Bun builtins only, zero dependencies, operates
+ * only on the design.md artifact.
+ *
+ * What it checks:
+ *   ERROR  - a required section is missing (Design Summary, Risks & Concerns,
+ *            Tech Decisions - heading-prefix match, case-insensitive)
+ *   ERROR  - a Risks & Concerns table row has an empty/placeholder Mitigation
+ *            cell (a bare "> None found" section with zero rows is valid -
+ *            it is a real, empty risk register, not an unfilled one)
+ *   WARN   - Risks & Concerns has no table rows and no "None found" marker
+ *            (ambiguous: unfilled template vs. genuinely empty)
+ *
+ * Usage:
+ *   bun skills/massa-ai/scripts/validate_design.ts [target] [--root DIR] [--strict]
+ *
+ *   target    Path to a design.md, a feature directory, or a project root.
+ *             Omitted -> auto-detect the single feature under <root>/.specs/features/.
+ *   --root    Project root that contains .specs/ (default: current dir).
+ *   --strict  Treat warnings as errors.
+ *
+ * Exit codes: 0 pass, 1 errors found (or warnings under --strict), 2 usage error.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+
+const REQUIRED_SECTIONS = ["Design Summary", "Risks & Concerns", "Tech Decisions"];
+const PLACEHOLDER_RE = /^\s*\[.+\]\s*$|^\s*<.+>\s*$|^\s*-?\s*$/;
+
+/** Mirrors os.path.join()'s "./" preservation — see validate_spec.ts for why. */
+function pyJoin(...parts: string[]): string {
+  let result = parts[0] ?? "";
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i]!;
+    if (part.startsWith("/")) {
+      result = part;
+    } else if (result === "" || result.endsWith("/")) {
+      result += part;
+    } else {
+      result += `/${part}`;
+    }
+  }
+  return result;
+}
+
+function isFile(p: string): boolean {
+  return existsSync(p) && statSync(p).isFile();
+}
+
+function isDir(p: string): boolean {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+
+function splitLines(text: string): string[] {
+  if (text === "") return [];
+  const result: string[] = [];
+  const lineBreakRe = /\r\n|\r|\n/g;
+  let start = 0;
+  let match: RegExpExecArray | null;
+  while ((match = lineBreakRe.exec(text)) !== null) {
+    result.push(text.slice(start, match.index));
+    start = match.index + match[0].length;
+  }
+  if (start < text.length) result.push(text.slice(start));
+  return result;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function autodetect(root: string): string | null {
+  const base = pyJoin(root, ".specs", "features");
+  if (!isDir(base)) return null;
+  const features = readdirSync(base)
+    .filter((d) => isFile(pyJoin(base, d, "design.md")))
+    .sort();
+  if (features.length === 1) return pyJoin(base, features[0]!, "design.md");
+  if (features.length === 0) return null;
+  const joined = features.map((f) => pyJoin(base, f, "design.md")).join("\n  ");
+  console.error(`validate_design: multiple features found; pass one explicitly:\n  ${joined}`);
+  process.exit(1);
+}
+
+function resolveDesign(target: string | null, root: string): string | null {
+  if (target) {
+    if (isFile(target)) return target;
+    if (isDir(target)) {
+      const cand = pyJoin(target, "design.md");
+      if (isFile(cand)) return cand;
+      return autodetect(target);
+    }
+    const cand = pyJoin(root, ".specs", "features", target, "design.md");
+    if (isFile(cand)) return cand;
+    return null;
+  }
+  return autodetect(root);
+}
+
+function splitRow(line: string): string[] {
+  const stripped = line.trim().replace(/^\|+/, "").replace(/\|+$/, "");
+  return stripped.split("|").map((c) => c.trim());
+}
+
+function isSeparator(line: string): boolean {
+  return /^\s*\|?[\s:|-]+\|?\s*$/.test(line) && line.includes("-");
+}
+
+/** Return [start, end) for the FIRST `#{1,3} <namePrefix>...` heading (prefix match, case-insensitive). */
+function sectionBoundsPrefix(lines: string[], namePrefix: string): [number, number] | null {
+  const headingRe = new RegExp(`^#{1,3}\\s+${escapeRegExp(namePrefix)}\\b`, "i");
+  let start: number | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    if (headingRe.test(lines[i]!.trim())) {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start === null) return null;
+  let end = lines.length;
+  const nextHeadingRe = /^#{1,3}\s+\S/;
+  for (let j = start; j < lines.length; j++) {
+    if (nextHeadingRe.test(lines[j]!)) {
+      end = j;
+      break;
+    }
+  }
+  return [start, end];
+}
+
+function check(designPath: string): { errors: string[]; warnings: string[] } {
+  const text = readFileSync(designPath, "utf-8");
+  const lines = splitLines(text);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // 1. Required sections.
+  const bounds = new Map<string, [number, number] | null>();
+  for (const name of REQUIRED_SECTIONS) {
+    const b = sectionBoundsPrefix(lines, name);
+    bounds.set(name, b);
+    if (b === null) {
+      errors.push(`missing required section: ## ${name}`);
+    }
+  }
+
+  // 2. Risks & Concerns: every table row needs a non-empty, non-placeholder
+  //    Mitigation cell. A bare "None found" marker with zero rows is valid.
+  const risksBounds = bounds.get("Risks & Concerns");
+  if (risksBounds) {
+    const [bs, be] = risksBounds;
+    const rows: string[] = [];
+    for (let i = bs; i < be; i++) {
+      if (lines[i]!.trim().startsWith("|")) rows.push(lines[i]!);
+    }
+    const bodyText = lines.slice(bs, be).join("\n").toLowerCase();
+    let data = rows.filter((r) => !isSeparator(r));
+    if (data.length) {
+      const headerCells = splitRow(data[0]!).map((c) => c.toLowerCase());
+      const mitigationIdx = headerCells.findIndex((c) => c.includes("mitigation"));
+      data = data.slice(1); // drop header row
+      for (const r of data) {
+        const cells = splitRow(r);
+        const idx = mitigationIdx >= 0 ? mitigationIdx : cells.length - 1;
+        const mitigation = cells[idx] ?? "";
+        const concern = cells[0] ?? "(unknown concern)";
+        if (!mitigation || PLACEHOLDER_RE.test(mitigation)) {
+          errors.push(`Risks & Concerns row '${concern.slice(0, 50)}' has an empty or unfilled Mitigation cell`);
+        }
+      }
+    } else if (!bodyText.includes("none found")) {
+      warnings.push("Risks & Concerns has no table rows and no 'None found' marker (ambiguous — confirm intentional)");
+    }
+  }
+
+  return { errors, warnings };
+}
+
+const USAGE = "usage: validate_design.ts [-h] [--root ROOT] [--strict] [target]";
+const HELP = `${USAGE}
+
+Closure-gate checks for a feature design.md.
+
+positional arguments:
+  target       Path to a design.md, a feature directory, or a project root
+
+options:
+  -h, --help   show this help message and exit
+  --root ROOT
+  --strict`;
+
+interface Args {
+  target: string | null;
+  root: string;
+  strict: boolean;
+}
+
+function printUsageError(msg: string): void {
+  process.stderr.write(`${USAGE}\nvalidate_design.ts: error: ${msg}\n`);
+}
+
+function parseArgs(argv: string[]): Args | null {
+  let root = ".";
+  let strict = false;
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--root") {
+      if (i + 1 >= argv.length) {
+        printUsageError("argument --root: expected one argument");
+        return null;
+      }
+      root = argv[++i]!;
+    } else if (a.startsWith("--root=")) {
+      root = a.slice("--root=".length);
+    } else if (a === "--strict") {
+      strict = true;
+    } else if (a === "-h" || a === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    } else if (a.startsWith("-") && a !== "-") {
+      printUsageError(`unrecognized arguments: ${a}`);
+      return null;
+    } else {
+      positionals.push(a);
+    }
+  }
+  if (positionals.length > 1) {
+    printUsageError(`unrecognized arguments: ${positionals.slice(1).join(" ")}`);
+    return null;
+  }
+  return { target: positionals[0] ?? null, root, strict };
+}
+
+function main(argv: string[]): number {
+  const args = parseArgs(argv);
+  if (args === null) return 2;
+
+  const design = resolveDesign(args.target, args.root);
+  if (!design) {
+    console.error("validate_design: could not locate a design.md. Pass a path or run from the project root.");
+    return 2;
+  }
+
+  const { errors, warnings } = check(design);
+  for (const w of warnings) console.log(`  WARN  ${w}`);
+  for (const e of errors) console.log(`  ERROR ${e}`);
+  const fail = errors.length > 0 || (warnings.length > 0 && args.strict);
+  console.log(`\nvalidate_design: ${errors.length} error(s), ${warnings.length} warning(s) in ${design}`);
+  return fail ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { check };

package/skills/massa-ai/scripts/validate_skill.ts

@@ -0,0 +1,364 @@
+#!/usr/bin/env bun
+/**
+ * Validate a skill folder against Skill Architect requirements.
+ *
+ * Usage:
+ *   bun scripts/validate_skill.ts <path-to-skill-folder>
+ *   bun scripts/validate_skill.ts <path-to-skill-folder> --format json
+ *   bun scripts/validate_skill.ts <path-to-skill-folder> --json-out /tmp/skill-report.json
+ *
+ * Exit codes:
+ *   0 = pass (warnings allowed)
+ *   1 = fail (at least one error)
+ *
+ * Token-efficient workflow: run once with --json-out, then reuse the saved
+ * JSON for feedback/review without re-running validation.
+ *
+ * TypeScript port of the former validate_skill.py (Skill Architect,
+ * Useful-Agent-Skills). Frontmatter is parsed with Bun's built-in real YAML
+ * parser (`Bun.YAML.parse`) — same precedent as
+ * scripts/__tests__/workflow-bun-cache.test.ts — so the Python version's
+ * PyYAML/stdlib fallback split is gone.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import path from "path";
+
+type Severity = "error" | "warning";
+
+interface Check {
+  name: string;
+  passed: boolean;
+  message: string;
+  severity: Severity;
+}
+
+interface Results {
+  path: string;
+  checks: Check[];
+  passed: number;
+  failed: number;
+  warnings: number;
+  parser_mode: string;
+  next_steps: string[];
+  summary?: string;
+}
+
+const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+
+export function validateSkill(skillPath: string): Results {
+  const results: Results = {
+    path: skillPath,
+    checks: [],
+    passed: 0,
+    failed: 0,
+    warnings: 0,
+    parser_mode: "unknown",
+    next_steps: [],
+  };
+
+  const addCheck = (name: string, passed: boolean, message: string, severity: Severity = "error") => {
+    results.checks.push({ name, passed, message, severity });
+    if (passed) results.passed += 1;
+    else if (severity === "warning") results.warnings += 1;
+    else results.failed += 1;
+  };
+
+  // --- Check 1: Folder exists ---
+  if (!existsSync(skillPath) || !statSync(skillPath).isDirectory()) {
+    addCheck("folder_exists", false, `Path is not a directory: ${skillPath}`);
+    results.summary = "FAIL — folder not found";
+    return results;
+  }
+  addCheck("folder_exists", true, "Skill folder exists");
+
+  // --- Check 2: Folder name is kebab-case ---
+  const folderName = path.basename(path.normalize(skillPath));
+  const isKebab = KEBAB_RE.test(folderName);
+  addCheck("folder_kebab_case", isKebab, `Folder name '${folderName}' ${isKebab ? "is" : "is NOT"} kebab-case`);
+
+  // --- Check 3: SKILL.md exists (exact casing) ---
+  const entries = readdirSync(skillPath);
+  const hasSkillMd = entries.includes("SKILL.md");
+  addCheck("skill_md_exists", hasSkillMd, hasSkillMd ? "SKILL.md exists" : "SKILL.md not found (case-sensitive)");
+
+  const wrongCasings = entries.filter((e) => e.toLowerCase() === "skill.md" && e !== "SKILL.md");
+  if (wrongCasings.length > 0) {
+    addCheck("skill_md_casing", false, `Found wrong casing: ${wrongCasings[0]} (must be exactly SKILL.md)`);
+  }
+
+  if (!hasSkillMd) {
+    results.summary = "FAIL — SKILL.md not found";
+    return results;
+  }
+
+  // --- Check 4: No README.md ---
+  const hasReadme = entries.some((e) => e.toLowerCase() === "readme.md");
+  addCheck(
+    "no_readme",
+    !hasReadme,
+    hasReadme ? "README.md found — remove it (skills are for agents, not humans)" : "No README.md in skill folder",
+  );
+
+  // --- Check 5: Parse frontmatter ---
+  const content = readFileSync(path.join(skillPath, "SKILL.md"), "utf8");
+  const fmMatch = FRONTMATTER_RE.exec(content);
+  if (!fmMatch) {
+    addCheck("frontmatter_delimiters", false, "Missing or malformed --- delimiters in frontmatter");
+    results.summary = "FAIL — frontmatter parse error";
+    return results;
+  }
+  addCheck("frontmatter_delimiters", true, "YAML frontmatter delimiters present");
+
+  let fm: Record<string, unknown>;
+  try {
+    const parsed = Bun.YAML.parse(fmMatch[1]);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("Frontmatter is not a YAML mapping");
+    }
+    fm = parsed as Record<string, unknown>;
+    results.parser_mode = "bun-yaml";
+    addCheck("frontmatter_valid_yaml", true, "Frontmatter is valid YAML (parsed with Bun.YAML)");
+  } catch (e) {
+    addCheck("frontmatter_valid_yaml", false, `YAML parse error: ${e instanceof Error ? e.message : String(e)}`);
+    results.summary = "FAIL — YAML parse error";
+    return results;
+  }
+
+  // --- Check 6: name field ---
+  const name = fm.name;
+  if (!name) {
+    addCheck("name_present", false, "Missing 'name' field in frontmatter");
+  } else {
+    addCheck("name_present", true, `name: ${name}`);
+    const isNameKebab = KEBAB_RE.test(String(name));
+    addCheck("name_kebab_case", isNameKebab, `name '${name}' ${isNameKebab ? "is" : "is NOT"} kebab-case`);
+
+    const nameLower = String(name).toLowerCase();
+    const hasReserved = nameLower.includes("claude") || nameLower.includes("anthropic");
+    addCheck(
+      "name_not_reserved",
+      !hasReserved,
+      hasReserved ? "Name contains 'claude' or 'anthropic' (reserved)" : "Name does not use reserved terms",
+    );
+
+    const namesMatch = String(name) === folderName;
+    addCheck(
+      "name_matches_folder",
+      namesMatch,
+      namesMatch
+        ? `name '${name}' matches folder '${folderName}'`
+        : `name '${name}' does NOT match folder '${folderName}'`,
+      "warning",
+    );
+  }
+
+  // --- Check 7: description field ---
+  const desc = fm.description;
+  if (!desc) {
+    addCheck("description_present", false, "Missing 'description' field in frontmatter");
+  } else {
+    const descStr = String(desc).trim();
+    addCheck("description_present", true, `description present (${descStr.length} chars)`);
+
+    addCheck("description_length", descStr.length <= 1024, `Description length: ${descStr.length}/1024 chars`);
+
+    const hasXml = descStr.includes("<") || descStr.includes(">");
+    addCheck(
+      "description_no_xml",
+      !hasXml,
+      hasXml ? "XML angle brackets found in description (forbidden)" : "No XML brackets in description",
+    );
+
+    const triggerKeywords = ["use when", "use for", "use this", "trigger", "ask for", "asks to", "says", "mentions"];
+    const descLower = descStr.toLowerCase();
+    const hasTriggers = triggerKeywords.some((kw) => descLower.includes(kw));
+    addCheck(
+      "description_has_triggers",
+      hasTriggers,
+      hasTriggers
+        ? "Description includes trigger guidance"
+        : "Missing trigger phrases — add 'Use when...' guidance (mandatory per CONTRIBUTING.md)",
+    );
+
+    const negativeKeywords = ["do not use", "don't use", "not for", "not intended for"];
+    const hasNegativeScope = negativeKeywords.some((kw) => descLower.includes(kw));
+    addCheck(
+      "description_has_negative_scope",
+      hasNegativeScope,
+      hasNegativeScope
+        ? "Description includes negative scope"
+        : "Missing negative scope — add 'Do NOT use for...' guidance (mandatory per CONTRIBUTING.md)",
+    );
+  }
+
+  // --- Check 7b: metadata field ---
+  const metadata = fm.metadata;
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    addCheck(
+      "metadata_present",
+      false,
+      "Missing 'metadata' field in frontmatter (expected metadata.version and metadata.author)",
+      "warning",
+    );
+  } else {
+    addCheck("metadata_present", true, "metadata field present");
+    const meta = metadata as Record<string, unknown>;
+
+    const metaVersion = meta.version;
+    addCheck(
+      "metadata_version",
+      Boolean(metaVersion),
+      metaVersion ? `metadata.version: ${metaVersion}` : "Missing metadata.version",
+      "warning",
+    );
+
+    const metaAuthor = meta.author;
+    addCheck(
+      "metadata_author",
+      Boolean(metaAuthor),
+      metaAuthor ? `metadata.author: ${metaAuthor}` : "Missing metadata.author",
+      "warning",
+    );
+  }
+
+  // --- Check 8: Body content ---
+  const body = content.slice(fmMatch[0].length);
+  const lineCount = body.trim().split("\n").length;
+  addCheck(
+    "body_line_count",
+    lineCount <= 500,
+    `SKILL.md body: ${lineCount} lines ${lineCount <= 500 ? "(good)" : "(consider moving content to references/)"}`,
+    lineCount > 500 ? "warning" : "error",
+  );
+
+  const hasExamples = /(example|user says|result:)/i.test(body);
+  addCheck(
+    "body_has_examples",
+    hasExamples,
+    hasExamples ? "Instructions include examples" : "Consider adding usage examples",
+    "warning",
+  );
+
+  const hasErrorHandling = /(error|fail|troubleshoot|issue|problem|if.*fails)/i.test(body);
+  addCheck(
+    "body_has_error_handling",
+    hasErrorHandling,
+    hasErrorHandling ? "Instructions include error handling" : "Consider adding error handling guidance",
+    "warning",
+  );
+
+  // --- Check 9: Optional files ---
+  const refsDir = path.join(skillPath, "references");
+  if (entries.includes("references") && existsSync(refsDir) && statSync(refsDir).isDirectory()) {
+    for (const ref of readdirSync(refsDir)) {
+      const refMentioned = body.includes(ref) || body.includes(`references/${ref}`);
+      addCheck(
+        `ref_linked_${ref}`,
+        refMentioned,
+        refMentioned
+          ? `references/${ref} is referenced in SKILL.md`
+          : `references/${ref} exists but is not referenced in SKILL.md`,
+        "warning",
+      );
+    }
+  }
+
+  // --- Summary ---
+  if (results.failed === 0) {
+    results.summary =
+      `PASS — ${results.passed} checks passed` + (results.warnings > 0 ? `, ${results.warnings} warnings` : "");
+  } else {
+    results.summary = `FAIL — ${results.failed} errors, ${results.warnings} warnings`;
+    results.next_steps = results.checks
+      .filter((c) => !c.passed && c.severity === "error")
+      .map((c) => `Fix check '${c.name}': ${c.message}`);
+  }
+
+  return results;
+}
+
+function printReport(results: Results, verbose: boolean): void {
+  const bar = "=".repeat(60);
+  const line = "─".repeat(60);
+  console.log(`\n${bar}`);
+  console.log("  Skill Validation Report");
+  console.log(`  Path: ${results.path}`);
+  console.log(`  Parser: ${results.parser_mode}`);
+  console.log(`${bar}\n`);
+
+  for (const check of results.checks) {
+    if (check.passed && !verbose) continue;
+    const icon = check.passed ? "✅" : check.severity === "warning" ? "⚠️" : "❌";
+    console.log(`  ${icon} ${check.name}: ${check.message}`);
+  }
+
+  console.log(`\n${line}`);
+  console.log(`  ${results.summary}`);
+  console.log(`  Passed: ${results.passed} | Failed: ${results.failed} | Warnings: ${results.warnings}`);
+  console.log(`${line}\n`);
+
+  if (results.next_steps.length > 0) {
+    console.log("  Next steps:");
+    results.next_steps.forEach((step, i) => console.log(`    ${i + 1}. ${step}`));
+    console.log("");
+  }
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  let skillPath: string | undefined;
+  let format: "human" | "json" | "both" = "human";
+  let verbose = false;
+  let prettyJson = false;
+  let jsonOut: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--format") {
+      const v = args[++i];
+      if (v !== "human" && v !== "json" && v !== "both") {
+        console.error(`Invalid --format: ${v} (choose human|json|both)`);
+        process.exit(2);
+      }
+      format = v;
+    } else if (a === "--verbose") verbose = true;
+    else if (a === "--pretty-json") prettyJson = true;
+    else if (a === "--json-out") jsonOut = args[++i];
+    else if (a === "-h" || a === "--help") {
+      console.log(
+        "Usage: bun scripts/validate_skill.ts <path> [--format human|json|both] [--verbose] [--pretty-json] [--json-out FILE]\n" +
+          "Tip: use --json-out FILE to save full results and avoid re-running for later feedback.",
+      );
+      process.exit(0);
+    } else if (!a.startsWith("-") && skillPath === undefined) skillPath = a;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      process.exit(2);
+    }
+  }
+
+  if (!skillPath) {
+    console.error("Missing required argument: path to the skill folder");
+    process.exit(2);
+  }
+
+  const results = validateSkill(skillPath);
+  const reportJson = JSON.stringify(results, null, prettyJson ? 2 : undefined);
+
+  if (format === "human" || format === "both") {
+    printReport(results, verbose);
+    if (!jsonOut) console.log("  Tip: add --json-out FILE to reuse this report without re-running.\n");
+  }
+  if (format === "json" || format === "both") {
+    if (format === "both") console.log("--- JSON Report ---");
+    console.log(reportJson);
+  }
+  if (jsonOut) {
+    writeFileSync(jsonOut, reportJson);
+    if (format === "human" || format === "both") console.log(`  JSON report saved to: ${jsonOut}`);
+  }
+
+  process.exit(results.failed === 0 ? 0 : 1);
+}

package/skills/massa-ai/workflows/adr.md

@@ -1,8 +1,16 @@
+---
+name: adr
+description: "Use this workflow to record a finalized or being-finalized architecture decision; route open options to rfc and implementation planning to tdd."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 📜 ADR (Architecture Decision Record)
 
-Use this workflow to record a finalized or being-finalized architecture decision. Do not use it to decide among open options; route undecided proposals to `workflows/rfc.md`. Do not use it for implementation planning; route that to `workflows/tdd.md`.
+Record a finalized or being-finalized architecture decision. Not for deciding among open options — route undecided proposals to `workflows/rfc.md`. Not for implementation planning — route that to `workflows/tdd.md`.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
 1. Resolve/reuse `projectId` and `workflowSessionId`: `adr-[entity]`.
 2. Load shared references:
@@ -13,21 +21,21 @@ Before the first substantive read, load `references/project-context.md` and run
 4. Gather source context using `references/adr-authoring.md`:
    - Use explicitly provided Markdown files and prompt context first.
    - Use ADR templates, PRDs, and RFCs from Markdown or Atlassian MCP when provided.
-   - Use optional complementary-stack ADRs from Markdown or Atlassian MCP as cross-stack context only when they affect contracts, constraints, dependencies, risks, or links.
-   - Use optional same-stack example ADRs from Markdown or Atlassian MCP as format/style references only; do not treat their decision context as facts for the new ADR.
-   - Use Figma MCP for UI/UX context only when provided and relevant; otherwise use PRD/RFC/NotebookLM context, or ignore UI/UX when absent.
-   - When supplied Figma links, nodes, desktop selections, or screenshots materially affect the decision, use `workflows/design.md` as optional child context for mobile UI implications only; the ADR still owns the decision record. Screenshots are context-only unless paired with structured Figma evidence.
+   - Use optional complementary-stack ADRs (Markdown or Atlassian MCP) as cross-stack context only when they affect contracts, constraints, dependencies, risks, or links.
+   - Use optional same-stack example ADRs (Markdown or Atlassian MCP) as format/style references only — not as facts for the new ADR.
+   - Use Figma MCP for UI/UX context only when provided and relevant; otherwise fall back to PRD/RFC/NotebookLM context, or skip UI/UX when absent.
+   - When Figma links, nodes, desktop selections, or screenshots materially affect the decision, use `workflows/design.md` as optional child context for mobile UI implications only; the ADR still owns the decision record. Screenshots are context-only unless paired with structured Figma evidence.
    - Use NotebookLM only when the user provides one or more notebook IDs; query each relevant notebook separately, preserve attribution, and do not assume a default notebook.
    - Corroborate with massa-ai search, current repo docs, existing ADRs, and code when the decision depends on current project reality.
 5. Run the ADR readiness gate from `references/adr-authoring.md`:
    - If a needed PRD, RFC, template, decision detail, or source fact is absent, ask for the missing context instead of inventing it.
    - If an RFC is needed but absent and the user does not know the missing context, assume the decision is not made and route to `workflows/rfc.md`.
    - Require a source-backed or user-confirmed title, date, status, context, decision, consequences, links, and supersession status before drafting.
-6. Draft the ADR using the project's provided template when available; otherwise use the format selected through the `references/adr-authoring.md` fallback questions. Keep claims tied to source confidence: confirmed, user-provided, recalled, inferred, or unresolved.
+6. Draft the ADR using the project's template when available; otherwise use the format selected via `references/adr-authoring.md`'s fallback questions. Tie claims to source confidence: confirmed, user-provided, recalled, inferred, or unresolved.
 7. Save the generated ADR using the selected output target:
    - Default: write to the project's standard ADR directory in Default mode. In Plan Mode, propose the path and content without writing.
    - Confluence: when requested and a parent page link is provided, write a child page through Atlassian MCP and report the resulting page link.
    - Fallback: if Confluence was requested without a parent link or Atlassian MCP is unavailable, ask for the parent link or permission to write local Markdown under `.adr/`.
    - Use sequential numbering from the selected local ADR directory when writing Markdown.
-8. At completion, persist the decision via `remember` as a scored `decision` memory with `memory:semantic`, explicitly linking the ADR file path and source context used.
+8. At completion, persist the decision via `remember` as a scored `decision` memory (`memory:semantic`), linking the ADR file path and source context used.
 9. Complete the Evidence Gate from `references/evidence-gate.md`.