create-byan-agent 2.9.4 → 2.9.5

package/install/templates/_byan/mcp/byan-mcp-server/lib/fd-state.js

@@ -0,0 +1,163 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PHASES = ['BRAINSTORM', 'PRUNE', 'DISPATCH', 'BUILD', 'VALIDATE', 'COMPLETED', 'ABORTED'];
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function statePath(projectRoot) {
+  return path.join(resolveRoot(projectRoot), '_byan-output', 'fd-state.json');
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readState(projectRoot) {
+  const p = statePath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state, projectRoot) {
+  const p = statePath(projectRoot);
+  ensureDir(p);
+  fs.writeFileSync(p, JSON.stringify(state, null, 2));
+  return p;
+}
+
+function slugify(s) {
+  return String(s || 'feature')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+    .slice(0, 40);
+}
+
+function stampId(now = new Date(), slug) {
+  const pad = (n) => String(n).padStart(2, '0');
+  const s =
+    now.getFullYear().toString() +
+    pad(now.getMonth() + 1) +
+    pad(now.getDate()) +
+    '-' +
+    pad(now.getHours()) +
+    pad(now.getMinutes()) +
+    pad(now.getSeconds());
+  return `${s}-${slugify(slug)}`;
+}
+
+export function start({ featureName, projectRoot, now = new Date(), force = false } = {}) {
+  const existing = readState(projectRoot);
+  if (existing && !['COMPLETED', 'ABORTED'].includes(existing.phase) && !force) {
+    throw new Error(
+      `FD already in progress (phase ${existing.phase}, fd_id ${existing.fd_id}). Abort or complete it first, or pass force=true.`
+    );
+  }
+
+  const state = {
+    fd_id: stampId(now, featureName),
+    feature_name: featureName || 'unnamed',
+    phase: 'BRAINSTORM',
+    started_at: now.toISOString(),
+    updated_at: now.toISOString(),
+    phase_history: [{ phase: 'BRAINSTORM', entered_at: now.toISOString() }],
+    raw_ideas: [],
+    backlog: [],
+    dispatch_table: [],
+    commits: [],
+    notes: [],
+  };
+  writeState(state, projectRoot);
+  return state;
+}
+
+export function status({ projectRoot } = {}) {
+  const state = readState(projectRoot);
+  if (!state) {
+    return { active: false, phase: null, fd_id: null };
+  }
+  return {
+    active: !['COMPLETED', 'ABORTED'].includes(state.phase),
+    ...state,
+  };
+}
+
+const BRAINSTORM_MIN_IDEAS = 10;
+
+export function advance({ to, note, projectRoot, now = new Date(), force = false } = {}) {
+  if (!PHASES.includes(to)) {
+    throw new Error(`Invalid target phase ${to}. Must be one of ${PHASES.join(', ')}`);
+  }
+  const state = readState(projectRoot);
+  if (!state) throw new Error('No active FD session. Call start() first.');
+  if (['COMPLETED', 'ABORTED'].includes(state.phase)) {
+    throw new Error(`Current FD session is ${state.phase} and cannot advance.`);
+  }
+
+  const order = PHASES.indexOf(state.phase);
+  const target = PHASES.indexOf(to);
+  if (target < order && !['ABORTED', 'COMPLETED'].includes(to)) {
+    throw new Error(
+      `Cannot move backwards from ${state.phase} to ${to}. Use abort() or fix the workflow.`
+    );
+  }
+
+  // BRAINSTORM exit gate : need >= BRAINSTORM_MIN_IDEAS raw ideas
+  if (
+    state.phase === 'BRAINSTORM' &&
+    to !== 'BRAINSTORM' &&
+    !['ABORTED'].includes(to) &&
+    !force
+  ) {
+    const n = Array.isArray(state.raw_ideas) ? state.raw_ideas.length : 0;
+    if (n < BRAINSTORM_MIN_IDEAS) {
+      throw new Error(
+        `BRAINSTORM requires at least ${BRAINSTORM_MIN_IDEAS} raw ideas before advancing (currently ${n}). Add more via update({ patch: { raw_ideas: [...] } }), or pass force=true to skip.`
+      );
+    }
+  }
+
+  state.phase = to;
+  state.updated_at = now.toISOString();
+  state.phase_history.push({ phase: to, entered_at: now.toISOString(), note: note || null });
+
+  writeState(state, projectRoot);
+  return state;
+}
+
+export function update({ patch = {}, projectRoot, now = new Date() } = {}) {
+  const state = readState(projectRoot);
+  if (!state) throw new Error('No active FD session.');
+
+  const allowed = ['raw_ideas', 'backlog', 'dispatch_table', 'commits', 'notes', 'feature_name'];
+  for (const key of Object.keys(patch)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`Field "${key}" is not patchable. Allowed: ${allowed.join(', ')}`);
+    }
+    state[key] = patch[key];
+  }
+  state.updated_at = now.toISOString();
+
+  writeState(state, projectRoot);
+  return state;
+}
+
+export function abort({ reason, projectRoot, now = new Date() } = {}) {
+  const state = readState(projectRoot);
+  if (!state) throw new Error('No FD session to abort.');
+  state.phase = 'ABORTED';
+  state.updated_at = now.toISOString();
+  state.phase_history.push({ phase: 'ABORTED', entered_at: now.toISOString(), note: reason || null });
+  writeState(state, projectRoot);
+  return state;
+}
+
+export const ALL_PHASES = PHASES;
+export const BRAINSTORM_MIN = BRAINSTORM_MIN_IDEAS;

package/install/templates/_byan/mcp/byan-mcp-server/lib/kanban.js

@@ -0,0 +1,226 @@
+/**
+ * Kanban + stand-up registry for BYAN party-mode sessions.
+ *
+ * Kanban : _byan-output/party-mode-sessions/<session_id>/kanban.json
+ *   columns : todo | doing | blocked | review | done
+ *   cards   : { id, title, assignee, priority, created_at, moved_at,
+ *               column, blocker_reason? }
+ *
+ * Stand-up : _byan-output/party-mode-sessions/<session_id>/standup.jsonl
+ *   entries : { agent, timestamp, did, blockers, next }
+ *
+ * Hermes watches stand-ups : an agent with 2+ consecutive "blocked"
+ * reports in the stand-up stream is flagged and their card is moved to
+ * `blocked` column in the kanban.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const COLUMNS = ['todo', 'doing', 'blocked', 'review', 'done'];
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function sessionDir(projectRoot, sessionId) {
+  return path.join(
+    resolveRoot(projectRoot),
+    '_byan-output',
+    'party-mode-sessions',
+    sanitize(sessionId)
+  );
+}
+
+function sanitize(id) {
+  return String(id || 'default').replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 80);
+}
+
+function kanbanPath(projectRoot, sessionId) {
+  return path.join(sessionDir(projectRoot, sessionId), 'kanban.json');
+}
+
+function standupPath(projectRoot, sessionId) {
+  return path.join(sessionDir(projectRoot, sessionId), 'standup.jsonl');
+}
+
+function readKanban(projectRoot, sessionId) {
+  const p = kanbanPath(projectRoot, sessionId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeKanban(projectRoot, sessionId, board) {
+  const p = kanbanPath(projectRoot, sessionId);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(board, null, 2));
+}
+
+function emptyBoard(sessionId, now) {
+  return {
+    session_id: sessionId,
+    created_at: now.toISOString(),
+    updated_at: now.toISOString(),
+    columns: COLUMNS.slice(),
+    cards: {},
+  };
+}
+
+export function createBoard({ sessionId, projectRoot, now = new Date() } = {}) {
+  if (!sessionId) throw new Error('sessionId is required');
+  const existing = readKanban(projectRoot, sessionId);
+  if (existing) return existing;
+  const board = emptyBoard(sessionId, now);
+  writeKanban(projectRoot, sessionId, board);
+  return board;
+}
+
+export function addCard({
+  sessionId,
+  card,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!sessionId) throw new Error('sessionId is required');
+  if (!card || !card.id || !card.title) throw new Error('card.id and card.title required');
+
+  const board = readKanban(projectRoot, sessionId) || emptyBoard(sessionId, now);
+  if (board.cards[card.id]) throw new Error(`card ${card.id} already exists`);
+
+  board.cards[card.id] = {
+    id: card.id,
+    title: card.title,
+    assignee: card.assignee || null,
+    priority: card.priority || 'P2',
+    column: card.column || 'todo',
+    created_at: now.toISOString(),
+    moved_at: now.toISOString(),
+    blocker_reason: null,
+  };
+  board.updated_at = now.toISOString();
+
+  writeKanban(projectRoot, sessionId, board);
+  return board.cards[card.id];
+}
+
+export function moveCard({
+  sessionId,
+  cardId,
+  toColumn,
+  blocker_reason,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!COLUMNS.includes(toColumn)) {
+    throw new Error(`toColumn must be one of ${COLUMNS.join(', ')}, got ${toColumn}`);
+  }
+  const board = readKanban(projectRoot, sessionId);
+  if (!board) throw new Error(`no kanban for session ${sessionId}`);
+  if (!board.cards[cardId]) throw new Error(`card ${cardId} not found`);
+
+  const card = board.cards[cardId];
+  card.column = toColumn;
+  card.moved_at = now.toISOString();
+  card.blocker_reason = toColumn === 'blocked' ? blocker_reason || 'unspecified' : null;
+  board.updated_at = now.toISOString();
+
+  writeKanban(projectRoot, sessionId, board);
+  return card;
+}
+
+export function assignCard({
+  sessionId,
+  cardId,
+  assignee,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!assignee) throw new Error('assignee is required');
+  const board = readKanban(projectRoot, sessionId);
+  if (!board || !board.cards[cardId]) throw new Error(`card ${cardId} not found`);
+  board.cards[cardId].assignee = assignee;
+  board.cards[cardId].moved_at = now.toISOString();
+  board.updated_at = now.toISOString();
+  writeKanban(projectRoot, sessionId, board);
+  return board.cards[cardId];
+}
+
+export function getBoard({ sessionId, projectRoot } = {}) {
+  if (!sessionId) throw new Error('sessionId is required');
+  return readKanban(projectRoot, sessionId);
+}
+
+export function postStandup({
+  sessionId,
+  agent,
+  did,
+  blockers = [],
+  next,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!sessionId) throw new Error('sessionId is required');
+  if (!agent) throw new Error('agent is required');
+
+  const entry = {
+    agent,
+    timestamp: now.toISOString(),
+    did: did || '',
+    blockers: Array.isArray(blockers) ? blockers : [],
+    next: next || '',
+  };
+
+  const p = standupPath(projectRoot, sessionId);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function readStandups({ sessionId, projectRoot, limit = 50 } = {}) {
+  const p = standupPath(projectRoot, sessionId);
+  if (!fs.existsSync(p)) return [];
+  const lines = fs.readFileSync(p, 'utf8').split('\n').filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // skip malformed
+    }
+  }
+  return out.slice(-limit);
+}
+
+/**
+ * Detect agents with >= minStreak consecutive blocked stand-ups.
+ * Returns array of { agent, streak, lastAt }.
+ */
+export function detectBlockedStreaks({ sessionId, minStreak = 2, projectRoot } = {}) {
+  const standups = readStandups({ sessionId, projectRoot, limit: 500 });
+  const streaks = {};
+  const agentLast = {};
+
+  for (const entry of standups) {
+    const isBlocked = Array.isArray(entry.blockers) && entry.blockers.length > 0;
+    if (isBlocked) {
+      streaks[entry.agent] = (streaks[entry.agent] || 0) + 1;
+    } else {
+      streaks[entry.agent] = 0;
+    }
+    agentLast[entry.agent] = entry.timestamp;
+  }
+
+  const flagged = [];
+  for (const [agent, n] of Object.entries(streaks)) {
+    if (n >= minStreak) {
+      flagged.push({ agent, streak: n, lastAt: agentLast[agent] });
+    }
+  }
+  return flagged;
+}
+
+export const KANBAN_COLUMNS = COLUMNS;

package/install/templates/_byan/mcp/byan-mcp-server/lib/peer-review.js

@@ -0,0 +1,187 @@
+/**
+ * Peer review registry for BYAN agents working in party-mode.
+ *
+ * Contract :
+ *   - An agent producing an artefact (commit, file change, spec) opens a
+ *     review request via requestReview(). The request is persisted at
+ *     _byan-output/reviews/<task_id>.json.
+ *   - Another agent (must be ≠ author) issues a verdict via
+ *     recordVerdict() with { verdict: approve | changes | block, comments,
+ *     must_fix }.
+ *   - listPending() returns all unresolved requests. pickReviewer()
+ *     returns an alternative agent from the roster distinct from the
+ *     author.
+ *
+ * Enforces the "reviewer must differ from author" invariant inside
+ * recordVerdict() and throws if violated.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_ROSTER = [
+  'bmad-bmm-architect',
+  'bmad-bmm-dev',
+  'bmad-bmm-quinn',
+  'bmad-bmm-pm',
+  'bmad-bmm-sm',
+  'bmad-bmm-analyst',
+  'bmad-bmm-ux-designer',
+  'bmad-bmm-tech-writer',
+  'bmad-tea-tea',
+  'bmad-compliance',
+];
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function reviewsDir(projectRoot) {
+  return path.join(resolveRoot(projectRoot), '_byan-output', 'reviews');
+}
+
+function reviewPath(projectRoot, taskId) {
+  return path.join(reviewsDir(projectRoot), `${sanitizeId(taskId)}.json`);
+}
+
+function sanitizeId(id) {
+  return String(id).replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 80);
+}
+
+function readReview(projectRoot, taskId) {
+  const p = reviewPath(projectRoot, taskId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeReview(projectRoot, review) {
+  fs.mkdirSync(reviewsDir(projectRoot), { recursive: true });
+  fs.writeFileSync(reviewPath(projectRoot, review.task_id), JSON.stringify(review, null, 2));
+}
+
+export function requestReview({
+  task_id,
+  author,
+  artifact_paths = [],
+  description = '',
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!task_id) throw new Error('task_id is required');
+  if (!author) throw new Error('author (agent name) is required');
+
+  const existing = readReview(projectRoot, task_id);
+  if (existing && existing.status === 'pending') {
+    throw new Error(`review for task ${task_id} already pending (author ${existing.author})`);
+  }
+
+  const review = {
+    task_id,
+    author,
+    artifact_paths: Array.isArray(artifact_paths) ? artifact_paths : [],
+    description: String(description || ''),
+    status: 'pending',
+    verdicts: [],
+    created_at: now.toISOString(),
+    updated_at: now.toISOString(),
+  };
+
+  writeReview(projectRoot, review);
+  return review;
+}
+
+export function recordVerdict({
+  task_id,
+  reviewer,
+  verdict,
+  comments = [],
+  must_fix = [],
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!task_id) throw new Error('task_id is required');
+  if (!reviewer) throw new Error('reviewer (agent name) is required');
+  if (!['approve', 'changes', 'block'].includes(verdict)) {
+    throw new Error(`verdict must be approve | changes | block, got ${verdict}`);
+  }
+
+  const review = readReview(projectRoot, task_id);
+  if (!review) throw new Error(`no review found for task ${task_id} — call requestReview first`);
+
+  if (review.author === reviewer) {
+    throw new Error(
+      `reviewer (${reviewer}) cannot be the same as author (${review.author}). Pick a different agent.`
+    );
+  }
+
+  review.verdicts.push({
+    reviewer,
+    verdict,
+    comments: Array.isArray(comments) ? comments : [],
+    must_fix: Array.isArray(must_fix) ? must_fix : [],
+    at: now.toISOString(),
+  });
+
+  if (verdict === 'approve') review.status = 'approved';
+  else if (verdict === 'block') review.status = 'blocked';
+  else review.status = 'changes_requested';
+
+  review.updated_at = now.toISOString();
+  writeReview(projectRoot, review);
+  return review;
+}
+
+export function getReview({ task_id, projectRoot } = {}) {
+  if (!task_id) throw new Error('task_id is required');
+  return readReview(projectRoot, task_id);
+}
+
+export function listPending({ projectRoot } = {}) {
+  const dir = reviewsDir(projectRoot);
+  if (!fs.existsSync(dir)) return [];
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const out = [];
+  for (const f of files) {
+    try {
+      const r = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      if (r.status === 'pending' || r.status === 'changes_requested') out.push(r);
+    } catch {
+      // skip malformed
+    }
+  }
+  out.sort((a, b) => (a.created_at > b.created_at ? -1 : 1));
+  return out;
+}
+
+export function pickReviewer({ author, preferredDomain, roster = DEFAULT_ROSTER } = {}) {
+  const domainPairs = {
+    dev: ['bmad-bmm-quinn', 'bmad-tea-tea'],
+    'bmm-dev': ['bmad-bmm-quinn', 'bmad-tea-tea'],
+    'bmad-bmm-dev': ['bmad-bmm-quinn', 'bmad-tea-tea'],
+    architect: ['bmad-tea-tea', 'bmad-bmm-quinn'],
+    'bmad-bmm-architect': ['bmad-tea-tea', 'bmad-bmm-quinn'],
+    pm: ['bmad-bmm-sm', 'bmad-bmm-analyst'],
+    'bmad-bmm-pm': ['bmad-bmm-sm', 'bmad-bmm-analyst'],
+    'ux-designer': ['bmad-bmm-pm', 'bmad-bmm-analyst'],
+    'bmad-bmm-ux-designer': ['bmad-bmm-pm', 'bmad-bmm-analyst'],
+  };
+
+  const keys = [preferredDomain, author].filter(Boolean);
+  for (const k of keys) {
+    const candidates = domainPairs[k] || [];
+    for (const c of candidates) {
+      if (c !== author) return c;
+    }
+  }
+
+  for (const r of roster) {
+    if (r !== author) return r;
+  }
+  return null;
+}
+
+export const DEFAULT_AGENT_ROSTER = DEFAULT_ROSTER;