spectoflow 0.12.0

package/templates/lib/store.js

@@ -0,0 +1,289 @@
+'use strict';
+/*
+ * spectoflow storage engine (zero dependency).
+ *
+ * Artifacts are MARKDOWN (human source of truth, versioned):
+ *   plans/<name>.md   — tasks as checkbox lines:
+ *       ## Phase title
+ *       - [ ] T-012 Add login form @dev ~standard %in_progress
+ *         - note: some comment            (indented sub-bullets = comments)
+ *   specs/<name>.md   — free-form spec markdown (listed, not parsed into tasks)
+ *
+ * Volatile execution state is JSON (gitignored, never read by humans):
+ *   .spectoflow/runtime.json  — running agents, heartbeats, test results
+ *
+ * Writes are GRANULAR: we locate a task's line by id and rewrite only that line (or insert a
+ * sub-bullet), leaving the rest of the file byte-for-byte intact.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// ---- task line parsing -------------------------------------------------------
+// - [ ] T-012 Title here @owner ~level %status
+const LINE_RE = /^(\s*)- \[( |x|X)\]\s+(\S+)\s*(.*)$/;
+
+function parseTaskLine(line) {
+  const m = line.match(LINE_RE);
+  if (!m) return null;
+  const [, indent, check, id, rest0] = m;
+  let rest = rest0;
+  const owner = (rest.match(/(?:^|\s)@([\w-]+)/) || [])[1] || null;
+  const level = (rest.match(/(?:^|\s)~([\w-]+)/) || [])[1] || null;
+  const statusTag = (rest.match(/(?:^|\s)%([\w-]+)/) || [])[1] || null;
+  const title = rest.replace(/(?:^|\s)[@~%][\w-]+/g, '').replace(/\s+/g, ' ').trim();
+  const done = check.toLowerCase() === 'x';
+  const status = done ? 'done' : (statusTag || 'todo');
+  return { indent, id, title, owner, level: level || 'standard', status, done };
+}
+
+function buildTaskLine(t) {
+  const parts = [`${t.indent || ''}- [${t.status === 'done' ? 'x' : ' '}] ${t.id} ${t.title}`];
+  if (t.owner) parts.push(`@${t.owner}`);
+  if (t.level && t.level !== 'standard') parts.push(`~${t.level}`);
+  if (t.status !== 'done' && t.status !== 'todo') parts.push(`%${t.status}`);
+  return parts.join(' ');
+}
+
+// ---- plan file model ---------------------------------------------------------
+function parsePlan(text) {
+  const lines = text.split('\n');
+  const phases = [];
+  let cur = { id: 'P0', title: 'Tasks', goal: '', tasks: [] };
+  let lastTask = null;
+  const pushPhase = () => { if (cur.tasks.length || cur.title !== 'Tasks') phases.push(cur); };
+  lines.forEach((line) => {
+    const h = line.match(/^##\s+(.*)$/);
+    if (h) { pushPhase(); cur = { id: 'P' + phases.length, title: h[1].trim(), goal: '', tasks: [] }; lastTask = null; return; }
+    const t = parseTaskLine(line);
+    if (t) { t.comments = []; cur.tasks.push(t); lastTask = t; return; }
+    const c = line.match(/^\s+- (?:note:|comment:)?\s*(.*)$/);
+    if (c && lastTask && c[1].trim()) lastTask.comments.push(c[1].trim());
+  });
+  pushPhase();
+  return phases;
+}
+
+function readPlans(projectRoot) {
+  const dir = path.join(projectRoot, 'plans');
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md')).sort()) {
+    const text = fs.readFileSync(path.join(dir, f), 'utf8');
+    out.push({ file: f, phases: parsePlan(text) });
+  }
+  return out;
+}
+
+// ---- granular writes ---------------------------------------------------------
+// Rewrite only the line whose task id matches, preserving everything else.
+function updateTaskLine(projectRoot, file, id, patch) {
+  const fp = path.join(projectRoot, 'plans', file);
+  const lines = fs.readFileSync(fp, 'utf8').split('\n');
+  let changed = false;
+  for (let i = 0; i < lines.length; i++) {
+    const t = parseTaskLine(lines[i]);
+    if (t && t.id === id) {
+      const next = Object.assign(t, patch);
+      lines[i] = buildTaskLine(next);
+      changed = true;
+      break;
+    }
+  }
+  if (changed) writeAtomic(fp, lines.join('\n'));
+  return changed;
+}
+
+function addTaskComment(projectRoot, file, id, text, author) {
+  const fp = path.join(projectRoot, 'plans', file);
+  const lines = fs.readFileSync(fp, 'utf8').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const t = parseTaskLine(lines[i]);
+    if (t && t.id === id) {
+      const indent = (t.indent || '') + '  ';
+      const who = author ? `@${author}: ` : '';
+      // insert after any existing comment sub-bullets
+      let j = i + 1;
+      while (j < lines.length && /^\s+- /.test(lines[j])) j++;
+      lines.splice(j, 0, `${indent}- note: ${who}${text}`);
+      writeAtomic(fp, lines.join('\n'));
+      return true;
+    }
+  }
+  return false;
+}
+
+function writeAtomic(fp, content) {
+  const tmp = fp + '.tmp';
+  fs.writeFileSync(tmp, content, 'utf8');
+  fs.renameSync(tmp, fp);
+}
+
+// ---- runtime sidecar (volatile) ---------------------------------------------
+function runtimePath(projectRoot) { return path.join(projectRoot, '.spectoflow', 'runtime.json'); }
+function readRuntime(projectRoot) {
+  try { return JSON.parse(fs.readFileSync(runtimePath(projectRoot), 'utf8')); }
+  catch { return { agents: [], tests: {}, messages: [], updatedAt: null }; }
+}
+function writeRuntime(projectRoot, rt) {
+  rt.updatedAt = new Date().toISOString();
+  writeAtomic(runtimePath(projectRoot), JSON.stringify(rt, null, 2) + '\n');
+  return rt;
+}
+
+// ---- progress history (volatile, kept inside runtime.json) ------------------
+// Pure helper: mutates+returns `runtime.history` — one {date,total,done} point per calendar day,
+// newest last, capped to 60 points. Same-day calls UPDATE the existing point rather than appending
+// (so re-recording the same day never grows history). No filesystem access here; the caller
+// decides whether the result is worth persisting (see readProject's write-guard).
+function recordSnapshot(runtime, counts, date) {
+  runtime.history = runtime.history || [];
+  const d = date || new Date().toISOString().slice(0, 10);
+  const last = runtime.history[runtime.history.length - 1];
+  const snap = { date: d, total: counts.total | 0, done: counts.done | 0 };
+  if (last && last.date === d) runtime.history[runtime.history.length - 1] = snap;
+  else runtime.history.push(snap);
+  if (runtime.history.length > 60) runtime.history = runtime.history.slice(-60);
+  return runtime;
+}
+
+// ---- group-chat message log (volatile) --------------------------------------
+// A running agent identifies itself by printing sentinel lines on stdout:
+//   ::spectoflow role=developer kind=status msg=finished T-023
+// Everything after `msg=` is free text to end of line. Non-sentinel lines return null.
+function parseAgentLine(line) {
+  const s = String(line);
+  if (!/^\s*::spectoflow\b/.test(s)) return null;
+  return {
+    role: (s.match(/\brole=(\S+)/) || [])[1] || 'agent',
+    kind: (s.match(/\bkind=(\S+)/) || [])[1] || 'message',
+    text: ((s.match(/\bmsg=([\s\S]*)$/) || [])[1] || '').trim(),
+  };
+}
+
+// Append one message to runtime.messages (id + at stamped here; caller can't override them).
+function appendMessage(projectRoot, msg) {
+  const rt = readRuntime(projectRoot);
+  rt.messages = rt.messages || [];
+  const full = { kind: 'message', ...msg,
+    id: 'm' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
+    at: new Date().toISOString() };
+  rt.messages.push(full);
+  writeRuntime(projectRoot, rt);
+  return full;
+}
+
+// ---- config & workflow -------------------------------------------------------
+function readConfig(projectRoot) {
+  try { return JSON.parse(fs.readFileSync(path.join(projectRoot, '.spectoflow', 'config.json'), 'utf8')); }
+  catch { return { mode: 'semi', language: 'en', agent: 'claude' }; }
+}
+function readWorkflow(projectRoot) {
+  try {
+    const text = fs.readFileSync(path.join(projectRoot, '.spectoflow', 'workflow.md'), 'utf8').replace(/\r\n?/g, '\n');
+    const steps = [];
+    text.split('\n').forEach((l) => {
+      const m = l.match(/^\s*- \[( |x|X)\]\s+(.*?)\s*$/);
+      if (!m) return;
+      let rest = m[2], cap = null, skill = null, policy = false;
+      const ann = rest.match(/\{([^}]*)\}\s*$/);
+      if (ann) {
+        rest = rest.slice(0, ann.index).trim();
+        cap = (ann[1].match(/\bcap:(\S+)/) || [])[1] || null;
+        skill = (ann[1].match(/\bskill:(\S+)/) || [])[1] || null;
+        policy = /\bpolicy\b/.test(ann[1]);
+      }
+      const optional = /\(optional\)/i.test(rest);
+      const name = rest.replace(/\s*\(optional\)\s*$/i, '').trim();
+      steps.push({ name, enabled: m[1].toLowerCase() === 'x', optional, cap, skill, policy });
+    });
+    return steps;
+  } catch { return []; }
+}
+
+// ---- unified read for the dashboard -----------------------------------------
+function readProject(projectRoot) {
+  const config = readConfig(projectRoot);
+  const plans = readPlans(projectRoot);
+  let runtime = readRuntime(projectRoot);
+  const workflow = readWorkflow(projectRoot);
+  const specs = (() => {
+    const d = path.join(projectRoot, 'specs');
+    return fs.existsSync(d) ? fs.readdirSync(d).filter((x) => x.endsWith('.md')) : [];
+  })();
+  const agents = listMd(path.join(projectRoot, '.spectoflow', 'agents'));
+  const skills = listSkills(path.join(projectRoot, '.spectoflow', 'skills'));
+
+  // Write-guarded snapshot: readProject is polled continuously by the dashboard (and reacts to
+  // fs.watch on .spectoflow). Recording unconditionally on every read would rewrite runtime.json
+  // on every poll → fs.watch fires → SSE 'change' → client re-reads → infinite loop / SSE storm.
+  // So we only persist when today's {total,done} actually differs from the last history entry
+  // (or history is empty and needs seeding) — a no-op read never touches the filesystem.
+  const today = new Date().toISOString().slice(0, 10);
+  let total = 0, done = 0;
+  for (const pl of plans) for (const ph of pl.phases) for (const t of ph.tasks) { total++; if (t.status === 'done') done++; }
+  const history = runtime.history || [];
+  const last = history[history.length - 1];
+  const changed = !last || last.date !== today || last.total !== total || last.done !== done;
+  if (changed) {
+    // Concurrency guard: readProject's own initial `readRuntime` above can be stale by the time
+    // we're ready to write — a concurrent writer (e.g. appendMessage, from a running agent) may
+    // have written runtime.json in between. Writing back our stale in-memory copy would silently
+    // clobber whatever that concurrent writer just persisted (messages, agent status, etc).
+    // So we re-read the freshest runtime immediately before writing and mutate ONLY its history
+    // in place; every other field (messages/agents/tests) comes from this fresh read, not from
+    // the possibly-stale `runtime` captured earlier in this function.
+    const cur = readRuntime(projectRoot);
+    recordSnapshot(cur, { total, done }, today);
+    runtime = writeRuntime(projectRoot, cur);
+  }
+
+  return { config, plans, specs, workflow, agents, skills, runtime };
+}
+function frontmatter(text) {
+  const m = String(text).replace(/\r\n?/g, '\n').match(/^---\n([\s\S]*?)\n---/);
+  const out = {};
+  if (m) m[1].split('\n').forEach((l) => { const kv = l.match(/^([\w-]+):\s*(.*)$/); if (kv) out[kv[1]] = kv[2].trim(); });
+  return out;
+}
+// Parse a flat inline-list front-matter value, e.g. "[analyze-requirements, write-spec]" →
+// ['analyze-requirements', 'write-spec']. Returns [] for an absent/empty value.
+function parseFlatList(raw) {
+  if (!raw) return [];
+  return String(raw).replace(/[[\]]/g, '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+function listMd(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => {
+    const fm = frontmatter(fs.readFileSync(path.join(dir, f), 'utf8'));
+    return { file: f, name: fm.name || f.replace(/\.md$/, ''), title: fm.title || fm.name || f, capability: fm.capability || '', description: fm.description || '',
+      standards: parseFlatList(fm.standards), uses: parseFlatList(fm.uses) };
+  });
+}
+function listSkills(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => {
+    const sk = path.join(dir, e.name, 'SKILL.md');
+    const fm = fs.existsSync(sk) ? frontmatter(fs.readFileSync(sk, 'utf8')) : {};
+    return { name: fm.name || e.name, description: fm.description || '', capability: fm.capability || '',
+      inputs: fm.inputs || '', outputs: fm.outputs || '', standard: fm.standard || '' };
+  });
+}
+function readAgents(projectRoot) {
+  const dir = path.join(projectRoot, '.spectoflow', 'agents');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => {
+    const fm = frontmatter(fs.readFileSync(path.join(dir, f), 'utf8'));
+    return { name: fm.name || f.replace(/\.md$/, ''), capability: fm.capability || null,
+      title: fm.title || '', description: fm.description || '',
+      standards: parseFlatList(fm.standards), uses: parseFlatList(fm.uses) };
+  });
+}
+function readSkills(projectRoot) {
+  return listSkills(path.join(projectRoot, '.spectoflow', 'skills'));
+}
+
+module.exports = {
+  parseTaskLine, buildTaskLine, parsePlan, readPlans, updateTaskLine, addTaskComment,
+  readRuntime, writeRuntime, parseAgentLine, appendMessage, readConfig, readWorkflow, readProject,
+  readAgents, readSkills, recordSnapshot,
+};

package/templates/policy.md

@@ -0,0 +1,11 @@
+# Policy — non-negotiable gates
+
+Orthogonal to mode. Even in autopilot, these require **explicit human approval** before execution.
+
+- **Production deployment** (build/release/deploy to prod).
+- **Destructive migration** (irreversible drop/alter, data deletion, purge).
+- **Security change** (auth, permissions, secrets, network exposure, session lifetime).
+- **Committing spend / external side effect** (payment, purchase, mass send).
+
+When a step hits a gate: stop, explain the act and its risk in one line, ask [Approve / Cancel /
+Modify], and record the decision in the runtime log. Overridable per project (add or relax gates).

package/templates/skills/analyze-requirements/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: analyze-requirements
+description: Turn a need into testable acceptance criteria in Given/When/Then, with edge cases enumerated.
+capability: analysis
+inputs: The raw need (a request, ticket, or user story) and any known constraints or existing spec.
+outputs: A list of testable acceptance criteria (Given/When/Then) plus an edge-case checklist.
+standard: BDD / acceptance criteria
+---
+# Analyze requirements
+
+Turn an ambiguous need into a set of unambiguous, testable acceptance criteria before design or code
+starts.
+
+## When to use
+Whenever a need arrives that isn't yet expressed as testable criteria — a new feature, a change
+request, a bug that implies a missing behavior — or whenever the workflow reaches the Analysis step.
+
+## Method
+Apply Behavior-Driven Development's Given/When/Then structure (Cucumber/Gherkin) to state each
+criterion as a concrete example, then stress it with a standard edge-case taxonomy
+(ISTQB equivalence partitioning + boundary value analysis):
+
+1. **Restate the need in one sentence.** If it takes more than one sentence, split it into multiple
+   needs — each gets its own criteria.
+2. **Write acceptance criteria as Given/When/Then.** For each distinct behavior:
+   - `Given` the initial context/state (3-5 steps max per scenario — more and it stops reading as a
+     spec and becomes an implementation).
+   - `When` the triggering action.
+   - `Then` the expected, observable outcome (behavior/contract level — no implementation detail).
+   One criterion = one behavior. If it needs "and" to describe, it is probably two criteria.
+3. **Enumerate edge cases per input**, using equivalence partitioning + boundary value analysis:
+   - Valid equivalence class(es) — one representative example, not every value in the class.
+   - Invalid equivalence class(es) — what must be rejected and how.
+   - Boundaries — min, max, min-1, max+1, empty, zero, null/missing.
+   - Error paths — what happens on failure (timeout, denial, malformed input), not just success.
+4. **Flag gaps as `need`s, don't fill them in.** Any requirement gap that depends on a third party, a
+   business decision, or information you don't have is raised as a `need` per `policy.md` — never
+   guessed at to keep moving.
+5. **Hand off** the criteria list to `write-spec` to be shaped into a reviewable spec document.
+
+## Output contract
+Acceptance criteria (Given/When/Then) and the edge-case checklist are recorded in `specs/<feature>.md`
+(or the plan, if no spec exists yet), written with granular, one-line-at-a-time updates. Report progress
+with the `::spectoflow` sentinel:
+
+```
+::spectoflow role=analysis kind=progress msg=<N> acceptance criteria drafted for <feature>
+::spectoflow role=analysis kind=need msg=<what is missing and who must resolve it>
+::spectoflow role=analysis kind=report msg=<N> criteria, <M> edge cases enumerated, ready for write-spec
+```
+
+## Quality bar
+- [ ] Every acceptance criterion is a concrete Given/When/Then example, not a vague statement.
+- [ ] Each criterion covers exactly one behavior (splittable by "and" is a sign it's really two).
+- [ ] Edge cases cover valid + invalid equivalence classes, boundaries, and error paths — not just the
+      happy path.
+- [ ] No criterion states implementation detail (class names, frameworks, algorithms).
+- [ ] Every gap that isn't this role's to answer is raised as a `need`, not silently assumed.
+
+## References
+- Cucumber, "Gherkin Syntax" — https://cucumber.netlify.app/docs/gherkin/
+- SmartBear, "Writing scenarios with Gherkin syntax" —
+  https://support.smartbear.com/cucumberstudio/docs/bdd/write-gherkin-scenarios.html
+- ISTQB Foundation Level — Boundary Value Analysis white paper —
+  https://istqb.org/wp-content/uploads/2025/10/Boundary-Value-Analysis-white-paper.pdf
+- SoftwareTestingHelp, "Boundary Value Analysis & Equivalence Partitioning Examples" —
+  https://www.softwaretestinghelp.com/what-is-boundary-value-analysis-and-equivalence-partitioning/

package/templates/skills/brainstorm/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: brainstorm
+description: Frame a need — problem, users, scope, risks, success metric — before committing to a spec.
+capability: intake
+inputs: The raw ask/request from the user or requester.
+outputs: A framed brief (problem, users, scope, risks, success metric) ready for analysis.
+standard: product discovery
+---
+# Brainstorm
+
+Frame a raw need into an agreed problem statement before any solution gets designed.
+
+## When to use
+When a new ask arrives — a feature request, a bug report reframed as a need, or any item without an
+agreed problem/scope yet — or whenever the workflow reaches an intake step.
+
+## Method
+Frame the need *before* reaching for solutions, in this order:
+
+1. **Problem** — what user-facing or business problem is this, stated as an outcome, not a feature
+   ("users can't X" not "add a button").
+2. **Users** — who specifically is affected; which segment, not "everyone".
+3. **Scope** — what's in scope for a first useful version.
+4. **Out of scope** — what is explicitly excluded, so nobody assumes it's included later.
+5. **Risks** — name the risk(s) most likely to kill or derail this: value (will users want it),
+   usability (can they use it), feasibility (can it be built with what we have), business viability
+   (does it fit constraints/compliance/cost) — per SVPG's four big risks.
+6. **Success metric** — one metric that will tell us the outcome was achieved.
+
+Offer 2-3 directions with trade-offs once the problem is framed; let the user react and converge on a
+shared understanding. Do not write code or a full spec at this stage — that belongs to the next
+capability.
+
+## Output contract
+Write the framed brief as a granular note/task comment (one line at a time): problem statement,
+users, scope, out-of-scope, top risk(s), success metric. Report to the orchestrator and group chat
+with:
+
+```
+::spectoflow role=intake kind=brief msg=<one-line problem + scope summary>
+```
+
+The brief feeds the next analysis/spec-writing step; it is not itself a spec or an implementation
+plan.
+
+## Quality bar
+- [ ] Problem is stated as an outcome/user pain, not pre-decided as a solution/feature.
+- [ ] Users are named specifically, not "everyone" or left implicit.
+- [ ] Scope and out-of-scope are both stated explicitly.
+- [ ] At least one risk (value/usability/feasibility/business viability) is named.
+- [ ] Exactly one success metric is stated and agreed with the requester.
+- [ ] No code or full spec was written during this step.
+
+## References
+- Teresa Torres, *Continuous Discovery Habits* (Product Talk, 2021) —
+  https://www.producttalk.org/continuous-discovery-habits-book/
+- Marty Cagan, "The Four Big Risks" — Silicon Valley Product Group —
+  https://www.svpg.com/four-big-risks/

package/templates/skills/code-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: code-review
+description: Review a deliverable against its requirements, findings graded by severity.
+capability: quality
+inputs: The deliverable under review and its acceptance criteria/spec.
+outputs: A severity-graded findings report with a ready / rework verdict.
+standard: Google code-review guide
+---
+# Code review
+
+Scoped review of a deliverable against its requirements to catch defects before it is marked done.
+
+## When to use
+When a `plans/*.md` task or deliverable is reported complete and needs an independent check before
+its status flips to done — or whenever the workflow reaches a quality step.
+
+## Method
+Read the deliverable and its acceptance criteria/spec first; review against them, not against
+personal preference. Following Google's "How to do a code review", walk each category and read every
+line the author expects reviewed:
+
+1. **Correctness / Functionality** — does the code behave as the spec and the author intended; are
+   edge cases and error paths handled.
+2. **Tests** — does the change have correct, well-designed automated tests covering the new behavior
+   (not just the happy path)?
+3. **Readability / Naming / Comments** — clear names, comments that explain *why* not *what*, no
+   dead code or leftover debug output.
+4. **Design / Complexity** — is the change well-designed for the system it lands in; could it be
+   simpler; would another developer understand and reuse it later?
+5. **Security** — obvious injection, auth/authz, secrets, or input-validation issues on the touched
+   surface (defer a full pass to the `security-review` skill when the change is security-sensitive).
+6. **Consistency / Documentation** — matches existing style/conventions; docs updated if behavior or
+   interface changed.
+
+Grade each finding by severity: **Critical** (breaks correctness/security, blocks), **Important**
+(real defect or gap, should block), **Minor** (worth fixing, not blocking), **Nit** (polish, author's
+choice — the guide's own "Nit:" convention for non-blocking points). Favor approving once the change
+demonstrably improves the codebase, even if imperfect; don't hold it to a standard of perfection.
+
+## Output contract
+Write findings as a report / task comment alongside the deliverable (granular, one line at a time),
+each carrying: severity, file:line, and the issue. End with an explicit verdict: **ready** or
+**rework**. Report to the orchestrator and group chat with:
+
+```
+::spectoflow role=quality kind=review msg=<verdict + counts by severity>
+::spectoflow role=quality kind=finding msg=<severity> <file:line> — <issue>
+```
+
+Do not modify the deliverable — report only. A discrepancy with the spec is raised as a `need`, not
+silently patched.
+
+## Quality bar
+- [ ] Reviewed against the deliverable's stated acceptance criteria/spec, not personal taste.
+- [ ] Every finding has a severity (Critical/Important/Minor/Nit) and a file:line.
+- [ ] Tests checked for real coverage of new behavior, not just the presence of a test file.
+- [ ] Design/complexity and naming/readability both considered, not just correctness.
+- [ ] Obvious security issues on the touched surface flagged (or routed to security-review).
+- [ ] A clear verdict (ready/rework) is stated; no open Critical/Important left unacknowledged.
+
+## References
+- Google Engineering Practices, "How to do a code review" —
+  https://google.github.io/eng-practices/review/reviewer/
+- Google Engineering Practices, "What to look for in a code review" —
+  https://google.github.io/eng-practices/review/reviewer/looking-for.html
+- Google Engineering Practices, "The Standard of Code Review" —
+  https://google.github.io/eng-practices/review/reviewer/standard.html

package/templates/skills/implement/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: implement
+description: Implement a plan task as small, conventional commits — red-green when a test exists, boy-scout cleanup on touched code, no scope creep.
+capability: implementation
+inputs: A `plans/*.md` task (checkbox item) with its linked spec section, and any failing test the testing capability already wrote for it.
+outputs: Working code for the task, committed as one or more Conventional Commits, plus the task's checkbox and status flipped in `plans/*.md`.
+standard: Conventional Commits + YAGNI/DRY
+---
+# Implement
+
+Turn one plan task into shipped code through small, well-described commits — nothing more than the
+task asks for, nothing left messier than it was found.
+
+## When to use
+When the workflow reaches the `implementation` capability for a task in `plans/*.md` that is not yet
+checked off, or when the group chat routes work to the developer persona.
+
+## Method
+1. **Re-read the task's contract first.** Open the linked spec section and the plan task's acceptance
+   criteria before writing any code. If a test already exists for this task (unit/integration/e2e),
+   run it — it should fail (**red**). If no test exists, note that in the report; do not silently skip
+   testing, escalate to the `testing` capability if the task needs one.
+2. **Build the smallest change that satisfies the criteria (YAGNI).** You Aren't Gonna Need It: implement
+   only what the current task requires — no speculative config, no unused abstraction, no extra endpoint
+   "while we're in here". Extra scope is a separate task, not a freebie.
+3. **Make it pass, then clean it up (green → refactor).** Get the existing/linked test green with the
+   simplest correct code, then refactor for clarity and to remove duplication (DRY — Don't Repeat
+   Yourself: extract only when a *third* real occurrence appears, not on the first hint of similarity).
+4. **Apply the boy-scout rule to code you touch.** Leave the lines you had to open cleaner than you found
+   them (naming, dead code, obvious lint issues) — but do not refactor unrelated files or modules just
+   because you passed through the repo; that belongs to its own task.
+5. **Commit in small, working, Conventional Commits.** Each commit:
+   - Builds and (if a test exists) passes on its own — no "WIP" or broken intermediate commits on the
+     shared branch (trunk-based hygiene: keep the branch always releasable).
+   - Follows the Conventional Commits grammar:
+     `<type>[optional scope]: <description>` header, optional body one blank line after, optional
+     footer(s) one blank line after that.
+   - Uses `feat:` for new capability, `fix:` for a bug fix, and other conventional types (`refactor:`,
+     `test:`, `docs:`, `chore:`, …) for everything else — pick the type that matches what the commit
+     actually does, not what the task was called.
+   - Marks a breaking change with `!` before the colon (e.g. `feat(api)!: ...`) or a `BREAKING CHANGE:`
+     footer — only when the task's contract says the change is breaking.
+   - Stays scoped to one logical change; split a task into several commits rather than bundling unrelated
+     edits into one.
+6. **Flip the task's status as you go**, not in one batch at the end — granular, one line at a time, so
+   the dashboard and other agents see live progress rather than a silent gap.
+
+## Output contract
+- Code changes committed with Conventional Commits messages as described above.
+- The corresponding checkbox/status line in `plans/*.md` updated via a granular, one-line write
+  (`- [ ]` → `- [x]`, or the task's status field) — never a full-file rewrite of the plan.
+- Progress and completion reported to the orchestrator and group chat with:
+
+```
+::spectoflow role=implementation kind=progress msg=<task id> <what changed, one line>
+::spectoflow role=implementation kind=commit msg=<commit type>(<scope>): <description>
+::spectoflow role=implementation kind=done msg=<task id> done — <tests status: red→green | no test>
+```
+
+## Quality bar
+- [ ] Task's acceptance criteria (from the spec/plan) are met — nothing more, nothing less.
+- [ ] If a test existed for this task, it went red → green; if none existed, that is stated explicitly.
+- [ ] No speculative code, config, or abstraction beyond what the task requires (YAGNI).
+- [ ] No duplicated logic left behind that a third occurrence should have collapsed (DRY).
+- [ ] Every commit builds/passes standalone and follows `<type>[scope]: <description>` grammar.
+- [ ] Breaking changes are marked with `!` or a `BREAKING CHANGE:` footer, and only when real.
+- [ ] Code the task touched is left cleaner (boy-scout), with no drive-by edits outside the task's scope.
+- [ ] Plan status updated via a granular write, not a full-file rewrite.
+
+## References
+- Conventional Commits v1.0.0 — https://www.conventionalcommits.org/en/v1.0.0/ (message grammar: type,
+  optional scope, description, body, footer; `feat`/`fix` as the baseline types; `!` and
+  `BREAKING CHANGE:` footer for breaking changes).
+- Trunk-Based Development — https://trunkbaseddevelopment.com/ (small, short-lived changes committed
+  frequently to a shared branch that always stays releasable).
+- Martin Fowler, "YAGNI" — https://martinfowler.com/bliki/Yagni.html (build capability only when it is
+  actually needed, not because it might be useful later).
+- "Don't repeat yourself" — https://en.wikipedia.org/wiki/Don%27t_repeat_yourself (every piece of
+  knowledge should have a single, unambiguous representation; the classic "rule of three" for when to
+  extract).

package/templates/skills/security-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: security-review
+description: Review a change for secrets, authorization and attack surface against OWASP ASVS + Top 10.
+capability: security
+inputs: The change under review (diff/branch), the affected code, config, and dependency manifests.
+outputs: A severity-ranked findings report with a Pass / Pass-with-follow-ups / Block verdict.
+standard: OWASP ASVS + Top 10
+---
+# Security review
+
+Scoped, standards-based review of a change to catch security defects before merge or deploy.
+
+## When to use
+When a change touches authentication, authorization, secrets, input handling, injection surfaces,
+sensitive-data flows, outbound network calls, or dependencies — or whenever the workflow reaches a
+security step or a `policy.md` security gate.
+
+## Method
+Scope to the diff and its trust boundaries (new inputs, new auth/authz checks, new secrets, new outbound
+calls, new dependencies). Walk each area, mapping findings to OWASP Top 10 (2021) and ASVS 5.0:
+
+1. **Authentication & session** (Top-10 A07; ASVS Authentication) — credential handling, MFA where
+   required, session lifetime/rotation/invalidation, no auth bypass introduced.
+2. **Authorization / access control** (A01) — every new endpoint/action enforces least privilege and
+   object-level checks; no IDOR, no missing server-side authz, no privilege escalation.
+3. **Secrets & cryptography** (A02) — no secrets in cleartext, source, logs, or fixtures; `.gitignore`
+   covers them and a `*.example` is provided; strong algorithms, no hard-coded keys, TLS in transit.
+4. **Input validation & injection** (A03) — untrusted input is validated/encoded/parameterised; check
+   SQL/NoSQL/command/LDAP injection and XSS on every new sink; no string-built queries.
+5. **Sensitive-data exposure & misconfiguration** (A02, A05) — PII minimised and protected, safe error
+   messages, secure defaults, no debug/verbose leakage, correct security headers/CORS.
+6. **Vulnerable & outdated dependencies** (A06) — new/updated packages checked for known CVEs and
+   maintenance; pin and justify additions.
+7. **Design, integrity & SSRF** (A04, A08, A10) — threat-model the change for insecure design, unsafe
+   deserialization / unsigned update or CI paths, and outbound requests reachable by user-controlled
+   URLs (SSRF).
+8. **Logging & monitoring** (A09) — security-relevant events are logged without leaking secrets/PII.
+
+Assign each finding a severity (Critical / High / Medium / Low / Info) calibrated to the project's target
+ASVS level, and a concrete remediation.
+
+## Output contract
+Write findings as a report / task comments alongside the change (granular, one line at a time), each
+finding carrying: severity, the Top-10 category, the ASVS requirement id where applicable, location
+(file:line), and remediation. End with an explicit verdict: **Pass**, **Pass with follow-ups**, or
+**Block**. Report to the orchestrator and group chat with:
+
+```
+::spectoflow role=security kind=review msg=<verdict + counts by severity>
+::spectoflow role=security kind=finding msg=<severity> <Top-10 cat> <file:line> — <issue>
+```
+
+A security-sensitive change routes to the `policy.md` human-approval gate; the skill never self-approves.
+
+## Quality bar
+- [ ] Every OWASP Top 10 (2021) category A01–A10 is explicitly marked **Considered** or **N/A**.
+- [ ] Each finding has severity + Top-10 category + remediation (+ ASVS id where applicable).
+- [ ] Secrets checked: none in cleartext/source/logs; gitignored; `*.example` present.
+- [ ] Authz checked on every new endpoint/action (least privilege, object-level).
+- [ ] Injection/XSS checked on every new sink; inputs validated/parameterised.
+- [ ] New/updated dependencies screened for known vulnerabilities.
+- [ ] A clear verdict is stated; no open Critical/High without a recorded human decision.
+
+## References
+- OWASP Top 10:2021 — https://owasp.org/Top10/2021/ (A01 Broken Access Control, A02 Cryptographic
+  Failures, A03 Injection, A04 Insecure Design, A05 Security Misconfiguration, A06 Vulnerable and
+  Outdated Components, A07 Identification and Authentication Failures, A08 Software and Data Integrity
+  Failures, A09 Security Logging and Monitoring Failures, A10 Server-Side Request Forgery).
+- OWASP Application Security Verification Standard (ASVS) 5.0.0 (2025-05-30) —
+  https://owasp.org/www-project-application-security-verification-standard/