archgen-skill 0.0.1 → 0.0.3

package/vendor/skills/archgen/SKILL.md

@@ -34,7 +34,8 @@ Do NOT load for plain bug fixes or one-line edits that need no planning.
 1. **Everything you generate goes inside `.archgen/<project-slug>/`** at the
    target repo root. NEVER write generated artifacts anywhere else. The only
    files you may touch outside `.archgen/` are source-code edits performed by
-   worker sub-agents for approved tasks.
+   worker sub-agents for approved tasks and the `AGENTS.md` features registry,
+   maintained exclusively via `scripts/update-agents.mjs`.
 2. **Two gates before execution**: (a) the VERIFIER sub-agent must return
    APPROVE on plan+tasks, then (b) the USER must approve. Never skip either.
 3. **Right-size every generation.** Classify scope BEFORE creating files:
@@ -98,9 +99,13 @@ Pick ONE mode from the user's intent and follow its section below:
    Use templates from references/artifact-templates.md. Every task needs:
    id, title, depends_on (prerequisite ids), file_ownership (disjoint globs!),
    acceptance criteria, and status left unset (resolver derives readiness).
-4. **Self-check:** run
+   If `<slug>` already exists under `.archgen/`, pick `<slug>-2`, `<slug>-3`, …
+   — NEVER overwrite or merge into an existing feature folder.
+4. **Self-check + registry:** run
    `node <skill>/scripts/validate.mjs .archgen/<slug>/tasks.yaml`
-   Fix until exit 0.
+   Fix until exit 0. Then refresh the AGENTS.md features registry:
+   `node <skill>/scripts/update-agents.mjs <repo-root> --slug <slug> --status planned`.
+   Re-run it after ANY later artifact update so AGENTS.md never goes stale.
 5. **VERIFIER GATE.** Dispatch a verifier sub-agent (brief in
    references/orchestration.md §verifier). It must also run
    `node <skill>/scripts/verify-plan.mjs .archgen/<slug>/tasks.yaml --plan .archgen/<slug>/plans`
@@ -145,6 +150,8 @@ Run from the target repo root where `.archgen/<slug>/` exists.
      `set-status.mjs <id> done` on success (or `failed` on failure) and commit.
 4. After the wave settles: re-run next-tasks. Failed tasks are NOT retried
    automatically — surface them, propose a fix task, [wait for user].
+   Refresh the registry so AGENTS.md tracks the new statuses:
+   `node <skill>/scripts/update-agents.mjs <repo-root>`.
 5. Repeat until no actionable tasks remain.
 6. Final report: tasks done/failed/blocked, commits produced, suggested
    follow-ups. Update `.archgen/<slug>/plans/*.md` checkboxes if present.
@@ -197,6 +204,8 @@ When a task domain matches an entry in `assets/skill-registry.json`
 ## Things you must NOT do
 
 - Do NOT write artifacts outside `.archgen/<slug>/`.
+- Do NOT reuse or overwrite an existing `.archgen/<slug>/` folder — suffix
+  `-2`, `-3`, … instead (multi-feature repos must stay isolated).
 - Do NOT skip the verifier gate or the user gate — ever, even for SMALL scopes.
 - Do NOT implement features yourself; dispatch workers.
 - Do NOT put two same-wave tasks on overlapping file_ownership globs.
@@ -225,6 +234,8 @@ When a task domain matches an entry in `assets/skill-registry.json`
 scripts/next-tasks.mjs  <tasks.yaml>                       # waves JSON
 scripts/validate.mjs    <tasks.yaml> [--plan <dir>]        # exit 0/1
 scripts/set-status.mjs  <tasks.yaml> <id> <status> [--force]
+scripts/update-agents.mjs <projectRoot> [--slug <s>] [--status <s>] [--prune]
+                        # AGENTS.md features registry
 scripts/impact.mjs      <tasks.yaml> <id-or-artifactPath>  # ripple JSON
 scripts/verify-plan.mjs <tasks.yaml> --plan <dir>          # APPROVE|ISSUES
 ```

package/vendor/skills/archgen/references/platforms.md

@@ -23,6 +23,23 @@ confirmed. The orchestrator loads ONLY the row matching Step-0 detection.
 Universal fallback: `.agents/skills/` project + `~/.agents/skills/` user works
 across most harnesses. Primary distribution: `npx skills add <repo>` (75+ agents).
 
+## archgen installed layout
+
+`install.sh` / `npx archgen-skill install` maintain ONE canonical store plus
+thin bridges — the skill is never copied twice:
+
+| Path | Role |
+|---|---|
+| `.agents/skills/archgen/` | Canonical store — `SKILL.md`, `scripts/`, `references/`, `assets/` |
+| `.claude/skills/archgen` | Optional symlink → canonical store, for Claude Code discovery |
+| `CLAUDE.md` | One-line `@AGENTS.md` bridge only — no content of its own |
+| `AGENTS.md` | The hub every harness reads; hosts the features registry between `<!-- archgen:features:start -->` and `<!-- archgen:features:end -->` |
+
+The registry table (`| Feature | Status | Updated |`, one row per
+`.archgen/<slug>/`) is machine-maintained by `scripts/update-agents.mjs` after
+every generate/plan/wave run — never hand-edit it; edit `.archgen/` state and
+re-run the script instead.
+
 ## MCP configuration
 
 Four different top-level keys exist — NEVER assume `mcpServers`:

package/vendor/skills/archgen/scripts/update-agents.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// update-agents.mjs — keeps the AGENTS.md features registry in sync with .archgen/.
+// Usage: node update-agents.mjs <projectRoot> [--slug <s>] [--status <s>] [--prune]
+// Scans .archgen/*/tasks.yaml and rewrites the table between the
+// <!-- archgen:features:start --> / <!-- archgen:features:end --> markers in
+// <projectRoot>/AGENTS.md, 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 by default (--prune is accepted as the explicit
+// no-op spelling of the same behavior). Writes atomically via temp + rename.
+// Exit codes: 0 ok · 2 no .archgen/ dir · 4 usage/IO/marker errors.
+import { existsSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseYaml } from './lib/yaml.mjs';
+
+const START_MARKER = '<!-- archgen:features:start -->';
+const END_MARKER = '<!-- archgen:features:end -->';
+const HEADER = '| Feature | Status | Updated |';
+const SEPARATOR = '| --- | --- | --- |';
+const DISPLAY_STATUSES = ['planned', 'in progress', 'done', 'blocked', 'unknown'];
+// Task-level statuses set-status.mjs 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']);
+
+// ---- arguments ------------------------------------------------------------
+const [projectRoot, ...flags] = process.argv.slice(2);
+let slug = null;
+let status = null;
+let pruneFlag = false; // pruning is always on; the flag just makes it explicit
+for (let i = 0; i < flags.length; i++) {
+  const arg = flags[i];
+  if (arg === '--slug' || arg === '--status') {
+    const value = flags[++i];
+    if (value === undefined) { console.error(`${arg} requires a value`); process.exit(4); }
+    if (arg === '--slug') slug = value;
+    else status = value;
+  } else if (arg === '--prune') {
+    pruneFlag = true;
+  } else {
+    console.error(`unknown argument '${arg}'`);
+    process.exit(4);
+  }
+}
+if (!projectRoot) {
+  console.error('usage: update-agents.mjs <projectRoot> [--slug <s>] [--status <s>] [--prune]');
+  process.exit(4);
+}
+if ((slug === null) !== (status === null)) {
+  console.error('--slug and --status must be passed together');
+  process.exit(4);
+}
+if (status !== null && !DISPLAY_STATUSES.includes(status)) {
+  console.error(`invalid status '${status}' (allowed: ${DISPLAY_STATUSES.join('|')})`);
+  process.exit(4);
+}
+if (slug !== null && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug)) {
+  console.error(`invalid slug '${slug}' (start alphanumeric; then letters, digits, '.', '_', '-')`);
+  process.exit(4);
+}
+
+// ---- scan .archgen/*/tasks.yaml -------------------------------------------
+const archgenDir = join(projectRoot, '.archgen');
+if (!existsSync(archgenDir)) {
+  console.error(`no .archgen/ directory under ${projectRoot} — nothing to register (generate a plan first)`);
+  process.exit(2);
+}
+
+/** 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
+ * done -> done; all pending/ready -> planned; everything else (any running,
+ * or a done/pending/failed mix) -> in progress.
+ */
+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(); // SKILL.md leaves status unset until wave resolution
+    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 === 'done')) return 'done';
+  if (statuses.every((s) => s === 'pending' || s === 'ready')) return 'planned';
+  return 'in progress';
+}
+
+/** @type {Map<string, {feature: string, status: string, updated: string}>} */
+const rows = new Map();
+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) });
+}
+
+// ---- upsert override (--slug/--status, 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));
+
+// ---- render -----------------------------------------------------------------
+function renderTable(eol) {
+  const lines = [HEADER, SEPARATOR, ...ordered.map((r) => `| ${r.feature} | ${r.status} | ${r.updated} |`)];
+  return lines.join(eol) + eol;
+}
+
+/** 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;
+}
+
+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) {
+    console.error(`${agentsPath}: found ${START_MARKER} but no ${END_MARKER} — repair the markers by hand`);
+    process.exit(4);
+  }
+  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++;
+}
+
+const tmp = `${agentsPath}.tmp-${process.pid}-${Date.now()}`;
+writeFileSync(tmp, out);
+renameSync(tmp, agentsPath); // atomic on POSIX: readers observe old-or-new, never partial
+
+console.log(banner);
+for (const n of notes) console.log(n);
+if (unchanged) console.log(`unchanged: ${unchanged}`);
+console.log(`registry: ${ordered.length} feature${ordered.length === 1 ? '' : 's'}`);