archgen-skill 0.1.0 → 0.1.2

package/lib/node_modules/archgen-mcp/src/core/refs.mjs

@@ -0,0 +1,184 @@
+// refs.mjs — section-level serving of the reference documents.
+//
+// WHY A TOOL: an MCP server cannot inject file content into the agent's
+// context — the agent must READ it. So when the references moved out of the
+// skill directory, the SERVER became the courier: the agent asks for a
+// section and gets its text back.
+//
+// WHY SECTION-LEVEL: a whole reference is ~11 KB; one section is ~1-2 KB.
+// Serving sections is strictly better than the file read it replaces — less
+// context, no truncation risk, and better retrieval than grepping.
+//
+// SAME ENGINE, TWO ROOTS: `archgen_docs` indexes the USER's artifacts
+// (`.archgen/<slug>/`); this indexes archgen's OWN protocol documents. Both
+// use `parseMarkdown` / `buildSections` / `findSection` from `docs.mjs` — one
+// implementation of "read a section of a markdown file".
+//
+// The roots are:
+//   1. the package's own `assets/references/` — the canonical protocol docs;
+//   2. the INSTALLED skill's `references/` — worker-facing docs (e.g.
+//      code-standards.md) that must stay readable as plain files because
+//      worker sub-agents may have no MCP tools.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseMarkdown, buildSections, findSection } from './docs.mjs';
+import { notFound } from './errors.mjs';
+import { noSuchSection } from './guidance.mjs';
+
+/** The reference documents this server serves. */
+export const REF_TOPICS = [
+  'interview',
+  'orchestration',
+  'artifact-templates',
+  'platforms',
+  'mcp-and-skills',
+  'code-standards',
+];
+
+/**
+ * Resolve a topic to a file, searching the package assets first and the
+ * installed skill second.
+ *
+ * @param {string} topic
+ * @param {{assetsDir: string, skillDir: string|null}} opts
+ * @returns {{topic: string, path: string, root: 'server'|'skill'}|null}
+ */
+export function resolveTopic(topic, opts) {
+  const key = String(topic ?? '').toLowerCase();
+  if (!key) return null;
+  const candidates = [
+    { path: join(opts.assetsDir, `${key}.md`), root: 'server' },
+    ...(opts.skillDir ? [{ path: join(opts.skillDir, 'references', `${key}.md`), root: 'skill' }] : []),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c.path)) return { topic: key, path: c.path, root: c.root };
+  }
+  return null;
+}
+
+/**
+ * Index one reference topic: its title, purpose and section list.
+ *
+ * @param {string} topic
+ * @param {{assetsDir: string, skillDir: string|null}} opts
+ */
+export function indexTopic(topic, opts) {
+  const resolved = resolveTopic(topic, opts);
+  if (!resolved) throw notFound(`unknown reference '${topic}'`, { topic, known: REF_TOPICS });
+  const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
+  return {
+    topic: resolved.topic,
+    root: resolved.root,
+    title: doc.headings.find((h) => h.level === 1)?.text ?? resolved.topic,
+    sections: buildSections(doc).map((s) => ({
+      slug: s.slug,
+      title: s.title,
+      level: s.level,
+      line: s.line,
+      endLine: s.endLine,
+    })),
+  };
+}
+
+/**
+ * Read one section (or the whole topic).
+ *
+ * @param {string} topic
+ * @param {{assetsDir: string, skillDir: string|null, section?: string|null}} opts
+ */
+export function readTopic(topic, opts) {
+  const resolved = resolveTopic(topic, opts);
+  if (!resolved) throw notFound(`unknown reference '${topic}'`, { topic, known: REF_TOPICS });
+  const text = readFileSync(resolved.path, 'utf8');
+  const doc = parseMarkdown(text);
+
+  if (!opts.section) {
+    return {
+      topic: resolved.topic,
+      root: resolved.root,
+      section: null,
+      text: doc.lines.join('\n'),
+      lines: doc.lines.length,
+    };
+  }
+
+  const section = findSection(doc, opts.section);
+  if (!section) {
+    const available = buildSections(doc).map((s) => s.slug);
+    throw noSuchSection(resolved.topic, opts.section, available);
+  }
+  return {
+    topic: resolved.topic,
+    root: resolved.root,
+    section: section.slug,
+    title: section.title,
+    line: section.line,
+    endLine: section.endLine,
+    text: section.body,
+  };
+}
+
+/**
+ * Which sections mention a token?
+ *
+ * The retrieval lens for "where is this talked about?" — the same question
+ * `archgen_docs{action:'map'}` answers for the user's artifacts.
+ *
+ * @param {string} topic
+ * @param {string} token
+ * @param {{assetsDir: string, skillDir: string|null}} opts
+ */
+export function searchTopic(topic, token, opts) {
+  const resolved = resolveTopic(topic, opts);
+  if (!resolved) throw notFound(`unknown reference '${topic}'`, { topic, known: REF_TOPICS });
+  const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
+  const esc = String(token).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Whole-word: a hit must not be glued to word characters on either side.
+  const re = new RegExp(`(?<![A-Za-z0-9_])${esc}(?![A-Za-z0-9_])`, 'i');
+
+  const hits = [];
+  for (const section of buildSections(doc)) {
+    const bodyLines = doc.lines.slice(section.line - 1, section.endLine);
+    const matches = [];
+    for (let i = 0; i < bodyLines.length; i++) {
+      if (re.test(bodyLines[i])) {
+        matches.push({ line: section.line + i, text: bodyLines[i].trim().slice(0, 200) });
+      }
+    }
+    if (matches.length) {
+      hits.push({
+        section: section.slug,
+        title: section.title,
+        level: section.level,
+        line: section.line,
+        endLine: section.endLine,
+        occurrences: matches.length,
+        matches: matches.slice(0, 10),
+      });
+    }
+  }
+  return { topic: resolved.topic, root: resolved.root, token, sections: hits, sectionCount: hits.length };
+}
+
+/**
+ * Every topic the agent can load, with a one-line summary of when to load it.
+ * This is the DISCOVERY surface: the agent must know the topics exist without
+ * reading a file to find out.
+ *
+ * @param {{assetsDir: string, skillDir: string|null}} opts
+ */
+export function listTopics(opts) {
+  const out = [];
+  for (const topic of REF_TOPICS) {
+    const resolved = resolveTopic(topic, opts);
+    if (!resolved) continue;
+    const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
+    out.push({
+      topic,
+      root: resolved.root,
+      title: doc.headings.find((h) => h.level === 1)?.text ?? topic,
+      sections: buildSections(doc).length,
+    });
+  }
+  return out;
+}

package/lib/node_modules/archgen-mcp/src/core/registry-updater.mjs

@@ -0,0 +1,232 @@
+// registry-updater.mjs — keeps the AGENTS.md features registry in sync with .archgen/.
+//
+// Extracted verbatim from skill/scripts/update-agents.mjs (deleted in the
+// MCP-first cutover). The registry is machine-maintained: it is rewritten
+// between the <!-- archgen:features:start --> / <!-- archgen:features:end -->
+// markers, preserving every byte outside the block (BOM and CRLF line endings
+// included). A missing AGENTS.md gets a minimal scaffold; an existing file
+// without markers gets them appended. Rows whose feature folder disappeared
+// are pruned. Writes atomically via temp + rename.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseYaml } from './yaml.mjs';
+import { invalidInput } from './errors.mjs';
+import { writeFileAtomic } from './fs-safety.mjs';
+
+export const START_MARKER = '<!-- archgen:features:start -->';
+export const END_MARKER = '<!-- archgen:features:end -->';
+export const HEADER = '| Feature | Status | Updated |';
+export const SEPARATOR = '| --- | --- | --- |';
+export const DISPLAY_STATUSES = ['planned', 'in progress', 'done', 'blocked', 'unknown'];
+// Task-level statuses the status mutator may write; anything else in tasks.yaml
+// means the file is not a contract we can read -> row falls back to unknown.
+const TASK_STATUSES = new Set(['pending', 'ready', 'running', 'blocked', 'done', 'failed']);
+
+/** Date -> YYYY-MM-DD (local time, zero-padded). */
+function fmtDate(d) {
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return `${d.getFullYear()}-${mm}-${dd}`;
+}
+
+/**
+ * Derive the one-word registry status from a parsed tasks.yaml `tasks`
+ * sequence. Precedence: unreadable -> unknown; any blocked -> blocked; all
+ * failed -> blocked (dead work is never "in progress"); all done -> done;
+ * all pending/ready -> planned; everything else -> in progress.
+ * @param {unknown} tasks
+ * @returns {string}
+ */
+export function deriveStatus(tasks) {
+  if (!Array.isArray(tasks)) return 'unknown';
+  const statuses = [];
+  for (const t of tasks) {
+    if (t === null || typeof t !== 'object' || Array.isArray(t)) return 'unknown';
+    const s = String(t.status ?? 'pending').trim().toLowerCase();
+    if (!TASK_STATUSES.has(s)) return 'unknown';
+    statuses.push(s);
+  }
+  if (statuses.length === 0) return 'planned'; // scaffolded folder, no entries yet
+  if (statuses.includes('blocked')) return 'blocked';
+  if (statuses.every((s) => s === 'failed')) return 'blocked'; // all-failed feature: nothing progresses
+  if (statuses.every((s) => s === 'done')) return 'done';
+  if (statuses.every((s) => s === 'pending' || s === 'ready')) return 'planned';
+  return 'in progress';
+}
+
+/**
+ * Scan `<project>/.archgen/<slug>/tasks.yaml` and derive one registry row per feature.
+ * @param {string} projectRoot
+ * @returns {Map<string, {feature: string, status: string, updated: string}>}
+ */
+export function scanFeatures(projectRoot) {
+  const archgenDir = join(projectRoot, '.archgen');
+  const rows = new Map();
+  if (!existsSync(archgenDir)) return rows;
+  for (const ent of readdirSync(archgenDir, { withFileTypes: true })) {
+    if (!ent.isDirectory()) continue;
+    const tasksPath = join(archgenDir, ent.name, 'tasks.yaml');
+    if (!existsSync(tasksPath)) continue; // the scan target is exactly */tasks.yaml
+    let derived = 'unknown';
+    try {
+      const { data } = parseYaml(readFileSync(tasksPath, 'utf8'), { filename: tasksPath });
+      derived = deriveStatus(data?.tasks);
+    } catch {
+      derived = 'unknown'; // unparseable YAML is data about the feature, not a crash
+    }
+    rows.set(ent.name, { feature: ent.name, status: derived, updated: fmtDate(statSync(tasksPath).mtime) });
+  }
+  return rows;
+}
+
+/** Parse the CURRENT registry rows out of an existing AGENTS.md (or null). */
+function oldRowsFrom(raw) {
+  const si = raw.indexOf(START_MARKER);
+  if (si === -1) return null;
+  const ei = raw.indexOf(END_MARKER, si + START_MARKER.length);
+  if (ei === -1) return null;
+  const old = new Map();
+  for (const line of raw.slice(si + START_MARKER.length, ei).split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t.startsWith('|') || t === HEADER || t === SEPARATOR) continue;
+    const cells = t.split('|').slice(1, -1).map((c) => c.trim());
+    if (!cells[0]) continue;
+    old.set(cells[0], { status: cells[1] ?? '', updated: cells[2] ?? '' });
+  }
+  return old;
+}
+
+/**
+ * Refresh the AGENTS.md features registry.
+ *
+ * @param {string} projectRoot absolute project root
+ * @param {{slug?: string|null, status?: string|null}} [opts] slug+status upsert one row
+ * @returns {{updated: boolean, banner: string, notes: string[], rows: Array<{feature: string, status: string, updated: string}>, file: string}}
+ */
+export function updateRegistry(projectRoot, opts = {}) {
+  const slug = opts.slug ?? null;
+  const status = opts.status ?? null;
+
+  if ((slug === null) !== (status === null)) {
+    throw invalidInput('slug and status must be passed together', { slug, status });
+  }
+  if (status !== null && !DISPLAY_STATUSES.includes(status)) {
+    throw invalidInput(`invalid status '${status}' (allowed: ${DISPLAY_STATUSES.join('|')})`, { status });
+  }
+  if (slug !== null && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug)) {
+    throw invalidInput(`invalid slug '${slug}' (start alphanumeric; then letters, digits, '.', '_', '-')`, { slug });
+  }
+
+  const archgenDir = join(projectRoot, '.archgen');
+  if (!existsSync(archgenDir)) {
+    throw invalidInput(`no .archgen/ directory under ${projectRoot} — nothing to register (generate a plan first)`, {
+      projectRoot,
+    });
+  }
+
+  const rows = scanFeatures(projectRoot);
+
+  // Upsert override (run right after generating).
+  if (slug !== null) {
+    const existing = rows.get(slug);
+    if (existing) existing.status = status;
+    else rows.set(slug, { feature: slug, status, updated: fmtDate(new Date()) });
+  }
+
+  const ordered = [...rows.values()].sort((a, b) => (a.feature < b.feature ? -1 : a.feature > b.feature ? 1 : 0));
+
+  const renderTable = (eol) => {
+    const lines = [HEADER, SEPARATOR, ...ordered.map((r) => `| ${r.feature} | ${r.status} | ${r.updated} |`)];
+    return lines.join(eol) + eol;
+  };
+
+  const agentsPath = join(projectRoot, 'AGENTS.md');
+  let raw = null;
+  try {
+    raw = readFileSync(agentsPath, 'utf8');
+  } catch {
+    /* missing -> scaffold below */
+  }
+  const oldRows = raw === null ? new Map() : (oldRowsFrom(raw) ?? new Map());
+
+  let out;
+  let banner;
+  if (raw === null) {
+    // Missing AGENTS.md: minimal scaffold — H1, pointer paragraph, markers+table.
+    banner = `created ${agentsPath}`;
+    out =
+      '# Agent Guide\n' +
+      '\n' +
+      'This project uses the archgen skill at `.agents/skills/archgen/SKILL.md` for architecture generation and autonomous task execution.\n' +
+      '\n' +
+      START_MARKER +
+      '\n' +
+      renderTable('\n') +
+      END_MARKER +
+      '\n';
+  } else if (!raw.includes(START_MARKER)) {
+    // Existing user file: append newline + markers + table; prior bytes untouched.
+    banner = `appended features registry to ${agentsPath}`;
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    out = raw + eol + START_MARKER + eol + renderTable(eol) + END_MARKER + '\n';
+  } else {
+    // Markers present: replace ONLY the span between them; every outside byte
+    // (BOM, prose, trailing sections, CRLF endings) survives verbatim.
+    const si = raw.indexOf(START_MARKER);
+    const ei = raw.indexOf(END_MARKER, si + START_MARKER.length);
+    if (ei === -1) {
+      throw invalidInput(`${agentsPath}: found ${START_MARKER} but no ${END_MARKER} — repair the markers by hand`, {
+        file: agentsPath,
+      });
+    }
+    banner = `updated features registry in ${agentsPath}`;
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    out = raw.slice(0, si + START_MARKER.length) + eol + renderTable(eol) + raw.slice(ei);
+  }
+
+  // Human summary.
+  const notes = [];
+  for (const feature of oldRows.keys()) {
+    if (!rows.has(feature)) notes.push(`pruned: ${feature} (missing .archgen/${feature}/tasks.yaml)`);
+  }
+  let unchanged = 0;
+  for (const r of ordered) {
+    const prev = oldRows.get(r.feature);
+    if (!prev) notes.push(`added: ${r.feature} (${r.status})`);
+    else if (prev.status !== r.status) notes.push(`updated: ${r.feature} (${prev.status || '?'} -> ${r.status})`);
+    else if (prev.updated !== r.updated) notes.push(`updated: ${r.feature} (${r.updated})`);
+    else unchanged++;
+  }
+  if (unchanged) notes.push(`unchanged: ${unchanged}`);
+
+  writeFileAtomic(agentsPath, out);
+
+  return {
+    updated: true,
+    banner,
+    notes,
+    rows: ordered,
+    file: agentsPath,
+  };
+}
+
+/**
+ * Read the current registry rows without writing anything.
+ * @param {string} projectRoot
+ * @returns {{rows: Array<{feature: string, status: string, updated: string}>, hasMarkers: boolean}}
+ */
+export function showRegistry(projectRoot) {
+  const agentsPath = join(projectRoot, 'AGENTS.md');
+  let raw = null;
+  try {
+    raw = readFileSync(agentsPath, 'utf8');
+  } catch {
+    /* absent */
+  }
+  if (raw === null) return { rows: [], hasMarkers: false };
+  const old = oldRowsFrom(raw);
+  return {
+    rows: old ? [...old.entries()].map(([feature, v]) => ({ feature, status: v.status, updated: v.updated })) : [],
+    hasMarkers: raw.includes(START_MARKER) && raw.includes(END_MARKER),
+  };
+}

package/lib/node_modules/archgen-mcp/src/core/resume-snapshot.mjs

@@ -0,0 +1,120 @@
+// resume-snapshot.mjs — writes `.archgen/<slug>/.agent/resume.md`.
+//
+// WHY THIS IS A TOOL: the skill's Hard rule 6 used to ask the agent to
+// hand-write a ten-line resume snapshot after every wave. That is exactly
+// the kind of state the agent must NOT reconstruct from memory — a compaction
+// would silently corrupt it. Deriving it from tasks.yaml makes it
+// deterministic and re-derivable: the snapshot is a pure function of the
+// plan's current state.
+//
+// The file is the primary re-entry artifact after any context compaction.
+import { mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseYaml } from './yaml.mjs';
+import { invalidInput } from './errors.mjs';
+import { writeFileAtomic } from './fs-safety.mjs';
+
+/**
+ * Build the resume snapshot body from a parsed plan.
+ * @param {string} slug
+ * @param {any[]} tasks
+ * @param {any[]} waves resolved waves
+ * @returns {string}
+ */
+/**
+ * The wave execution resumes at, 1-based.
+ *
+ * When every wave is done there is no NEXT wave, so the resume point is the
+ * LAST wave — not one past the end of the list. The file and the tool
+ * response used two different formulas, so the snapshot could say "wave 3 of
+ * 2" while the response said wave 2.
+ */
+export function resumeWaveIndex(waves, statusOf) {
+  const active = waves.findIndex((w) => w.some((t) => statusOf(t) !== 'done'));
+  return active === -1 ? waves.length : active + 1;
+}
+
+export function renderResume(slug, tasks, waves) {
+  const byId = new Map(tasks.map((t) => [t?.id, t]));
+  const statusOf = (t) => String(t?.status ?? 'pending');
+
+  const done = tasks.filter((t) => statusOf(t) === 'done').map((t) => t.id);
+  const failed = tasks.filter((t) => statusOf(t) === 'failed').map((t) => t.id);
+  const blocked = tasks.filter((t) => statusOf(t) === 'blocked').map((t) => t.id);
+  const running = tasks.filter((t) => statusOf(t) === 'running').map((t) => t.id);
+
+  // The first wave that still has work in it is where execution resumes.
+  const activeWaveIndex = waves.findIndex((w) => w.some((t) => statusOf(t) !== 'done'));
+  const remaining = waves[activeWaveIndex] ?? [];
+
+  const lines = [];
+  lines.push(`# Resume — ${slug}`);
+  lines.push('');
+  lines.push(`- slug: ${slug}`);
+  lines.push(`- wave: ${resumeWaveIndex(waves, statusOf)} of ${waves.length}`);
+  lines.push(`- done: ${done.length ? done.join(', ') : 'none'}`);
+  lines.push(`- failed: ${failed.length ? failed.join(', ') : 'none'}`);
+  lines.push(`- blocked: ${blocked.length ? blocked.join(', ') : 'none'}`);
+  lines.push(`- running: ${running.length ? running.join(', ') : 'none'}`);
+  lines.push('- next: call archgen_tasks { action: "next" } — it resolves the frontier from tasks.yaml');
+  lines.push('');
+  lines.push('## Remaining tasks and the plan sections they own');
+  lines.push('');
+  if (remaining.length === 0) {
+    lines.push('_No remaining wave._');
+  } else {
+    for (const t of remaining) {
+      const owned = (byId.get(t.id)?.artifacts ?? []).filter((a) => typeof a === 'string' && a.endsWith('.md'));
+      const sections = owned.length ? owned.join(', ') : '_(no plan section declared)_';
+      lines.push(`- **${t.id}** — ${t.title ?? ''}`);
+      lines.push(`  - status: ${statusOf(t)}`);
+      lines.push(`  - owns: ${sections}`);
+      lines.push(`  - files: ${(byId.get(t.id)?.file_ownership ?? []).join(', ') || '—'}`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Write the resume snapshot for a slug.
+ *
+ * @param {string} slugDir absolute `.archgen/<slug>/` directory
+ * @param {any[][]} waves resolved waves
+ * @returns {{path: string, waveIndex: number, done: string[], failed: string[], blocked: string[], remaining: string[]}}
+ */
+export function writeResumeSnapshot(slugDir, waves) {
+  const tasksFile = join(slugDir, 'tasks.yaml');
+  let raw;
+  try {
+    raw = readFileSync(tasksFile, 'utf8');
+  } catch {
+    throw invalidInput(`cannot read ${tasksFile} (missing or unreadable)`, { file: tasksFile });
+  }
+  let data;
+  try {
+    ({ data } = parseYaml(raw, { filename: tasksFile }));
+  } catch (e) {
+    throw invalidInput(String(e?.message ?? e), { file: tasksFile });
+  }
+  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+  const slug = slugDir.split(/[\\/]/).filter(Boolean).pop() ?? 'unknown';
+
+  const body = renderResume(slug, tasks, waves);
+  const out = join(slugDir, '.agent', 'resume.md');
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileAtomic(out, body, { root: slugDir });
+
+  const statusOf = (t) => String(t?.status ?? 'pending');
+  const activeWaveIndex = waves.findIndex((w) => w.some((t) => statusOf(t) !== 'done'));
+  return {
+    path: out,
+    waveIndex: resumeWaveIndex(waves, statusOf),
+    done: tasks.filter((t) => statusOf(t) === 'done').map((t) => t.id),
+    failed: tasks.filter((t) => statusOf(t) === 'failed').map((t) => t.id),
+    blocked: tasks.filter((t) => statusOf(t) === 'blocked').map((t) => t.id),
+    remaining: (waves[activeWaveIndex] ?? []).map((t) => t.id),
+  };
+}
+
+