@rryando/arcs 3.7.0 → 3.8.0

package/dist/utils/knowledge-templates.js

@@ -0,0 +1,209 @@
+/**
+ * Knowledge body templates — single source of truth for structured,
+ * fillable skeletons per knowledge kind.
+ *
+ * Consumed by the `arcs knowledge template` CLI command and the
+ * knowledge-health validator. Pure module: no fs, no I/O, no side effects.
+ */
+/**
+ * Structured body template per knowledge kind. Headings are stable
+ * contracts; hints are guidance the author replaces with real content.
+ */
+export const KNOWLEDGE_TEMPLATES = {
+    gotcha: [
+        {
+            heading: "Symptom",
+            hint: "What you observed — the error, surprising output, or failing behaviour.",
+        },
+        {
+            heading: "Root cause",
+            hint: "The underlying reason this happens, stated mechanistically.",
+        },
+        {
+            heading: "Fix or workaround",
+            hint: "The concrete change or sidestep that resolves it.",
+        },
+        {
+            heading: "Trigger",
+            hint: "The conditions under which this bites again, so it can be recognised early.",
+        },
+    ],
+    lesson: [
+        {
+            heading: "Expectation",
+            hint: "What you believed would happen before the work.",
+        },
+        {
+            heading: "What happened",
+            hint: "The actual outcome that diverged from the expectation.",
+        },
+        {
+            heading: "Why",
+            hint: "The reason for the gap between expectation and reality.",
+        },
+        {
+            heading: "Next time",
+            hint: "The behaviour change this lesson commits you to.",
+        },
+    ],
+    pattern: [
+        {
+            heading: "When to use",
+            hint: "The recurring situation this pattern solves.",
+        },
+        {
+            heading: "Shape",
+            hint: "The structure of the solution — the moving parts and how they fit.",
+        },
+        {
+            heading: "Example",
+            hint: "A concrete instance, ideally referencing real code in this repo.",
+        },
+        {
+            heading: "When not to use",
+            hint: "Cases where this pattern is the wrong tool and what to reach for instead.",
+        },
+    ],
+    architecture: [
+        {
+            heading: "Structure",
+            hint: "The major components and how they are arranged and connected.",
+        },
+        {
+            heading: "Invariant or constraint",
+            hint: "A property that must always hold for the design to remain sound.",
+        },
+        {
+            heading: "Failure mode",
+            hint: "How the structure breaks down when the invariant is violated.",
+        },
+    ],
+    decision: [
+        {
+            heading: "Decision",
+            hint: "The choice that was made, stated as a single clear sentence.",
+        },
+        {
+            heading: "Rationale and forces",
+            hint: "Why this choice, and the pressures that shaped it.",
+        },
+        {
+            heading: "Alternatives rejected",
+            hint: "The options considered and the reason each was set aside.",
+        },
+        {
+            heading: "Consequences",
+            hint: "What this decision now commits the project to, good and bad.",
+        },
+    ],
+    module: [
+        {
+            heading: "Purpose",
+            hint: "What this module exists to do, in one sentence.",
+        },
+        {
+            heading: "Key files and entry points",
+            hint: "The files that matter and the functions or exports callers reach for.",
+        },
+        {
+            heading: "Responsibilities",
+            hint: "What this module owns — and what it deliberately does not.",
+        },
+        {
+            heading: "Dependencies",
+            hint: "What this module relies on and what relies on it.",
+        },
+    ],
+    feature: [
+        {
+            heading: "What it does",
+            hint: "The user-facing or system-facing capability this feature provides.",
+        },
+        {
+            heading: "How it works",
+            hint: "The mechanism behind the capability at a useful level of detail.",
+        },
+        {
+            heading: "Entry points",
+            hint: "Where execution begins — commands, functions, or routes that invoke it.",
+        },
+        {
+            heading: "Edge cases",
+            hint: "The boundary conditions and unusual inputs it handles.",
+        },
+    ],
+    reference: [
+        {
+            heading: "Summary",
+            hint: "A one-paragraph description of what is being referenced.",
+        },
+        {
+            heading: "Canonical location",
+            hint: "Where the authoritative source lives — file path, URL, or symbol.",
+        },
+        {
+            heading: "Usage notes",
+            hint: "How to apply this reference correctly, including any caveats.",
+        },
+    ],
+};
+/**
+ * Returns the section list for a given knowledge kind.
+ */
+export function getTemplateSections(kind) {
+    return KNOWLEDGE_TEMPLATES[kind];
+}
+/**
+ * Renders a fillable markdown skeleton for a kind: each section becomes a
+ * `## <heading>` followed by its hint as an HTML comment, so the guidance
+ * does not count as real content and is trivially deletable.
+ */
+export function renderTemplate(kind) {
+    return getTemplateSections(kind)
+        .map((section) => `## ${section.heading}\n\n<!-- ${section.hint} -->\n`)
+        .join("\n");
+}
+/**
+ * Minimum real-content character count below which a body is considered
+ * shallow by the knowledge-health validator.
+ */
+export const SHALLOW_BODY_MIN_CHARS = 120;
+/**
+ * Measures the length of real prose content in a body, defeating both
+ * empty bodies and hollow all-headers templates.
+ *
+ * Drops the leading H1 title, all markdown headings, HTML comments (incl.
+ * multi-line), blockquote markers, and leading list/ordered markers, then
+ * collapses whitespace and returns the trimmed length.
+ */
+export function extractBodyContentLength(body) {
+    // Strip HTML comments first (may span multiple lines).
+    const withoutComments = body.replace(/<!--[\s\S]*?-->/g, "");
+    const content = withoutComments
+        .split("\n")
+        .filter((line) => {
+        const trimmed = line.trimStart();
+        // Drop the leading H1 title line and any markdown heading line.
+        if (/^#{1,6}\s/.test(trimmed))
+            return false;
+        return true;
+    })
+        .map((line) => {
+        let cleaned = line;
+        // Drop blockquote markers.
+        cleaned = cleaned.replace(/^\s*>\s?/, "");
+        // Strip leading markdown list/ordered markers.
+        cleaned = cleaned.replace(/^\s*([-*+]|\d+[.)])\s+/, "");
+        return cleaned;
+    })
+        .join(" ");
+    // Collapse all remaining whitespace to single spaces, then trim.
+    return content.replace(/\s+/g, " ").trim().length;
+}
+/**
+ * True when a body has less real content than the shallow floor.
+ */
+export function isBodyShallow(body) {
+    return extractBodyContentLength(body) < SHALLOW_BODY_MIN_CHARS;
+}
+//# sourceMappingURL=knowledge-templates.js.map

package/dist/utils/knowledge-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-templates.js","sourceRoot":"","sources":["../../src/utils/knowledge-templates.ts"],"names":[],"mappings":"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"}

package/opencode/arcs/bundle-runtime.json

@@ -22,7 +22,10 @@
       "SKILL.md"
     ],
     "executing-plans": [
-      "SKILL.md"
+      "SKILL.md",
+      "code-quality-reviewer-prompt.md",
+      "implementer-prompt.md",
+      "spec-reviewer-prompt.md"
     ],
     "quick-dev": [
       "SKILL.md"
@@ -31,12 +34,6 @@
       "SKILL.md",
       "code-reviewer.md"
     ],
-    "subagent-driven-development": [
-      "SKILL.md",
-      "code-quality-reviewer-prompt.md",
-      "implementer-prompt.md",
-      "spec-reviewer-prompt.md"
-    ],
     "systematic-debugging": [
       "SKILL.md",
       "condition-based-waiting.md",
@@ -55,6 +52,9 @@
       "SKILL.md",
       "scripts/manage-diagram.mjs"
     ],
+    "writing-knowledge": [
+      "SKILL.md"
+    ],
     "writing-plans": [
       "SKILL.md",
       "plan-document-reviewer-prompt.md"

package/opencode/arcs/manifest.json

@@ -10,10 +10,8 @@
   "agents": [
     { "source": "prompts/software-engineer.txt", "destination": "prompts/software-engineer.txt" },
     { "source": "prompts/tech-architect.txt", "destination": "prompts/tech-architect.txt" },
-    { "source": "prompts/qa-analyst.txt", "destination": "prompts/qa-analyst.txt" },
     { "source": "prompts/oncall-ops.txt", "destination": "prompts/oncall-ops.txt" },
     { "source": "prompts/arcs-docs.txt", "destination": "prompts/arcs-docs.txt" },
-    { "source": "prompts/system-architect.txt", "destination": "prompts/system-architect.txt" },
     { "source": "prompts/code-reviewer.txt", "destination": "prompts/code-reviewer.txt" },
     { "source": "prompts/docs-researcher.txt", "destination": "prompts/docs-researcher.txt" },
     { "source": "prompts/devil-advocate.txt", "destination": "prompts/devil-advocate.txt" },
@@ -242,27 +240,6 @@
         },
         "mode": "merge"
       },
-      {
-        "path": [
-          "agent",
-          "qa-analyst"
-        ],
-        "value": {
-          "description": "Quality enforcement specialist. Proactive code audits, review dispatch, convention compliance.",
-          "mode": "subagent",
-          "model": "github-copilot/claude-haiku-4.5",
-          "temperature": 0.3,
-          "permission": {
-            "edit": "deny",
-            "bash": "allow",
-            "webfetch": "allow",
-            "mcp": "allow",
-            "external_directory": { "*": "allow" }
-          },
-          "prompt": "{file:./prompts/qa-analyst.txt}"
-        },
-        "mode": "merge"
-      },
       {
         "path": [
           "agent",
@@ -315,27 +292,6 @@
         },
         "mode": "merge"
       },
-      {
-        "path": [
-          "agent",
-          "system-architect"
-        ],
-        "value": {
-          "description": "Architecture and design specialist. Module boundaries, dependency graphs, migration strategies, and cross-project design decisions.",
-          "mode": "subagent",
-          "model": "github-copilot/claude-opus-4.6",
-          "temperature": 0.5,
-          "permission": {
-            "edit": "deny",
-            "bash": "allow",
-            "webfetch": "allow",
-            "mcp": "allow",
-            "external_directory": { "*": "allow" }
-          },
-          "prompt": "{file:./prompts/system-architect.txt}"
-        },
-        "mode": "merge"
-      },
       {
         "path": [
           "small_model"
@@ -372,26 +328,6 @@
         ],
         "value": "deny",
         "mode": "overwrite"
-      },
-      {
-        "path": [
-          "agent",
-          "qa-analyst",
-          "permission",
-          "edit"
-        ],
-        "value": "deny",
-        "mode": "overwrite"
-      },
-      {
-        "path": [
-          "agent",
-          "system-architect",
-          "permission",
-          "edit"
-        ],
-        "value": "deny",
-        "mode": "overwrite"
       }
     ]
   }

package/opencode/arcs/prompts/arcs-docs.txt

@@ -137,7 +137,8 @@ MUTATIONS:
 - <failed or notable mutations only, plus IDs of entries created — counts stay in SYNC_REPORT>
 
 KNOWLEDGE: <none | one ready-to-run command per durable, reusable insight surfaced this dispatch:
-  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --body="<the substance — fill every section of the kind's template>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  Scaffold the body first — run `arcs knowledge template --kind=<kind> --json` for the section skeleton, then fill every section; a summary-only entry is a stub, not a capture.
   (upsert is idempotent by title — no dedup search needed)>
 
 SCOPE_CHANGE: <none | topology change needing `arcs diagram sort-metadata`>

package/opencode/arcs/prompts/arcs-orchestrate-caveman.txt

@@ -182,9 +182,17 @@ The knowledge base only pays for its upkeep if it is READ. A write-only KB rots;
 
 **WRITE at the moment of discovery, not at session end.** When any return surfaces a durable insight — a gotcha, a resolved ambiguity, a pattern, an architectural decision, a rejected-alternative-with-rationale, a SHORTCUT ceiling — persist it immediately at that round's fan-in with `arcs knowledge upsert`. Session-end capture is the safety net, not the primary path; insight deferred to session end is insight lost in a verbose return.
 
-**`upsert` is your default knowledge write.** `arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="…" --keywords="…" --source-files="<path[:anchor],…>" --json` create-or-updates by title — idempotent, so NO `arcs search` dedup dance. Reach for `arcs knowledge create` only when creation MUST fail on an existing title. Every entry tied to specific files carries `--source-files` so `validate --checks=knowledge-health` can keep it honest.
+**WRITE with substance — a one-sentence entry is a stub, not knowledge.** The single most common KB failure is an entry whose `--summary` merely restates its title and whose body is empty: structurally "healthy," worthless to the next dispatch. The summary is the headline; the value lives in the `--body`, which EVERY non-mechanical entry MUST carry (`--body="…"` inline, or `--body-file=<path>` once it's long enough to fight shell-escaping). Write the body to the anatomy of its kind:
+- **gotcha** → symptom (how it surfaces) · root cause · the fix/workaround · the trigger that reproduces it
+- **lesson** → what was expected · what actually happened · why · what to do differently next time
+- **pattern** → when to reach for it · its shape (signature/skeleton or a code snippet) · a real call site · when NOT to use it
+- **architecture** → the structure · the invariant/constraint it enforces · what breaks if violated
+- **decision** → the choice · the forces behind it · the alternatives rejected AND why · the consequences accepted
+Self-check before writing: "Could someone ACT on this in six months without re-deriving it?" If the insight cost you reasoning, a debug session, or a dead-end, capture that reasoning — not just its one-line conclusion. (Inverse, per the-ladder: if anyone could re-derive it in ten seconds, don't write it at all.)
 
-**The KB is a maintenance target, not just an append log.** Treat thin entries (no summary, no source-files), stale entries, and contradictions as defects: when `validate --checks=knowledge-health` or a sub-agent surfaces them, enrich or prune. A dispatch that has to rediscover something the DAG should have told it up front is a signal the DAG was under-maintained — close that gap in the same session.
+**`upsert` is your default knowledge write.** `arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<one-line headline>" --body="<the substance — anatomy above>" --keywords="…" --source-files="<path[:anchor],…>" --json` create-or-updates by title — idempotent, so NO `arcs search` dedup dance. `--summary` AND `--body` AND `--source-files` together are the floor for a file-specific entry; summary-only is a stub, not a write. Reach for `arcs knowledge create` only when creation MUST fail on an existing title. (`validate --checks=knowledge-health` keeps `--summary`/`--source-files` honest, but it cannot see a vapid one-line body — body substance is on YOU.) Scaffold the `--body` from `arcs knowledge template --kind=<k>` (the authoritative per-kind section skeleton) and author it to the `writing-knowledge` skill.
+
+**The KB is a maintenance target, not just an append log.** Treat thin entries as defects — both the *structural* thinness `validate --checks=knowledge-health` flags (no summary, no source-files) AND the *semantic* thinness it cannot see (an empty body, or a lone sentence that just echoes the title). When a search you ran for a dispatch returns an entry too shallow to act on, ENRICH it to the quality bar right then — same idempotent `upsert`, now with a real `--body` — or prune it if it never deserved to exist. A dispatch that has to rediscover something the DAG should have told it up front is a signal the DAG was under-maintained — close that gap in the same session.
 
 **Boundary (the-ladder, applied to knowledge).** Eager ≠ indiscriminate. Do NOT force a knowledge search or capture onto purely mechanical work — a rename, a config nudge, a diagram regen, a commit message. Read when prior art could change the approach; capture when the insight would save a future dispatch. Everything in between, do it.
 
@@ -201,21 +209,19 @@ Need implementation work done?
 → test-first valuable: `software-engineer` + test-driven-development
 → executing pre-written plan: `software-engineer` + executing-plans
 
-Need design/architecture work?
-→ design open: `system-architect` + brainstorming
-→ analysis without edits: `tech-architect`
+Need design/architecture work? → `tech-architect` (single-project deep analysis AND multi-project topology/migration/boundary design; add brainstorming when the design is open)
 
 Need investigation?
 → bug/test failure/incident: `oncall-ops` + systematic-debugging (NEVER software-engineer)
-→ convention audit: `qa-analyst`
 
-Need review?
-→ pre-merge/PR (correctness): `code-reviewer`
-→ over-engineering/bloat audit: `code-reviewer` (simplify/bloat-audit pass — distinct from correctness review)
+Need code-quality assessment? → `code-reviewer` (read-only — mode selected by dispatch CONTEXT)
+→ reactive diff/PR correctness + test quality: review mode
+→ proactive scope-wide convention/architecture-health audit (no diff): audit mode
+→ over-engineering/bloat audit: review mode (simplify/bloat pass)
 → GitHub PR + "deep review": `code-reviewer` + deep-pr-review
 
-Need DAG maintenance? → `arcs-docs` (sync/audit/diagram drift)
-Need research? → `docs-researcher` (external docs/tech-stack)
+Need DAG maintenance? → `arcs-docs` (sync/audit/diagram drift — writes to the DAG directly)
+Need research? → `docs-researcher` (external docs/tech-stack; PROPOSES knowledge entries as ready-to-run upserts — YOU persist them, like code-reviewer/devil-advocate)
 Phase-gate verification? → `devil-advocate` (mandatory at every phase boundary)
 
 ### `graph-explorer` — Your Eyes
@@ -269,7 +275,7 @@ BLOCKED_BY: <only when blocked/partial — evidence; includes failures observed
   out-of-scope files, which the agent left untouched>
 ```
 
-followed by agent-specific sections (VERDICT, FINDINGS, ARTIFACTS, SCOPE_CHANGE, TASKS, and the single canonical capture slot **KNOWLEDGE**). `KNOWLEDGE` is the ONE place durable insight surfaces — `<none | ready-to-run `arcs knowledge upsert` commands, one per insight>`. Older prompts may still emit `CAPTURES` or `PROPOSED_ENTRIES`; treat both as exact aliases of `KNOWLEDGE`. Gate dispatches (devil-advocate) return their verdict-first format instead.
+followed by agent-specific sections (VERDICT, FINDINGS, ARTIFACTS, SCOPE_CHANGE, TASKS, and the single canonical capture slot **KNOWLEDGE**). `KNOWLEDGE` is the ONE place durable insight surfaces — `<none | ready-to-run `arcs knowledge upsert` commands, one per insight, each carrying `--summary` AND a substantive `--body`>`. A proposed command with only `--summary` is an incomplete capture: enrich it from the agent's FINDINGS before you run it — never persist the stub. Older prompts may still emit `CAPTURES` or `PROPOSED_ENTRIES`; treat both as exact aliases of `KNOWLEDGE`. Gate dispatches (devil-advocate) return their verdict-first format instead.
 
 Consuming a return — read STATUS/VERDICT first, it determines the next action:
 - `done` → forward FILES_TOUCHED + VERIFY + declared SCOPE verbatim into the devil-advocate PHASE: execute dispatch; on PASS, write to DAG
@@ -298,7 +304,7 @@ Granularity rule: one dispatch = one disjoint scope + one work-mode + one verifi
 
 Parallelism triggers:
 - EXECUTE with 2+ unblocked tasks in `arcs diagram ready` → dispatch all ready nodes
-- BRAINSTORM scoping that needs both architecture analysis AND tech-stack research → fan-out `system-architect` + `docs-researcher`
+- BRAINSTORM scoping that needs both architecture analysis AND tech-stack research → fan-out `tech-architect` + `docs-researcher`
 - INIT repo analysis → fan-out all typed agents in one message
 - EXPLORE with multiple questions → fan-out `graph-explorer` per question
 
@@ -362,7 +368,7 @@ Edge cases: FAILURES lines marked `pre-existing` (breakage the session's changes
 
 Every session ends with:
 1. **Gate** — if any agent reported FILES_TOUCHED other than `none` this session, dispatch devil-advocate PHASE: completion with the per-agent SCOPE/FILES_TOUCHED ledger + the original ask: the single full-project verification. Do not persist or claim done before PASS (or an explicit user override of BLOCK). Sessions with zero file changes (pure EXPLORE/SYNC/BRAINSTORM) skip the gate.
-2. **Persist to DAG (safety net, not primary path)** — most knowledge should already be captured at each round's fan-in (Knowledge Protocol). Here, sweep anything not yet persisted with `arcs knowledge upsert` (idempotent — no `arcs search` dedup dance), kind lesson/pattern/gotcha/architecture/decision, plus `--source-files` for anything file-specific. Then transition completed tasks and update plan status if a milestone is reached. Triggers: any non-obvious fix, pattern, gotcha, architectural decision, rejected alternative, or constraint learned. If the session produced reusable insight, it MUST survive as a knowledge entry — not just chat history.
+2. **Persist to DAG (safety net, not primary path)** — most knowledge should already be captured at each round's fan-in (Knowledge Protocol). Here, sweep anything not yet persisted with `arcs knowledge upsert` (idempotent — no `arcs search` dedup dance), kind lesson/pattern/gotcha/architecture/decision, each with `--summary` + a substantive `--body` (the per-kind anatomy from the Knowledge Protocol) + `--source-files` for anything file-specific. While here, enrich any one-sentence stub the session's searches surfaced in this scope — leaving a known-thin entry un-enriched is itself an unfinished task. Then transition completed tasks and update plan status if a milestone is reached. Triggers: any non-obvious fix, pattern, gotcha, architectural decision, rejected alternative, or constraint learned. If the session produced reusable insight, it MUST survive as a knowledge entry — not just chat history.
 3. **SHORTCUT harvest** — after the gate PASSES, grep the session's touched files for deferral markers (`grep -rnE '(#|//) ?SHORTCUT:' <touched-paths>`). For each deliberate simplification, capture it into the DAG as knowledge (`arcs knowledge create ... --kind=gotcha`) or a follow-up task so deferrals don't rot.
 4. **Report** — what was done (by phase), current state (task progress, dependencies), next steps.
 
@@ -372,11 +378,11 @@ After `arcs brief`:
 1. `lastSyncedAt` > 7 days → surface warning
 2. Active plans → `arcs validate <slug> --json` silently; surface issues
 3. `arcs validate <slug> --checks=status-drift --json` silently; surface drift
-4. `arcs validate <slug> --checks=knowledge-health --json` silently → surface "KB under-maintained: N thin / M stale" when entries lack summary/source-files or sit long-untouched, and bias the session toward enrichment. The T0 brief also carries a thin-knowledge count — read it.
+4. `arcs validate <slug> --checks=knowledge-health --json` silently → surface "KB under-maintained: N thin / M stale" when entries lack summary/source-files or sit long-untouched, and bias the session toward enrichment. The check sees only *structural* thinness — treat its count as a FLOOR, not the truth: any one-sentence, bodyless entry you pass over during a search is also thin and is fair game to enrich this session. The T0 brief also carries a thin-knowledge count — read it.
 
 ## Skill Selection
 
-Work-mode (pick exactly one per implementation dispatch) — encoded in the decision tree above: quick-dev (bounded), code-agent (mostly clear), test-driven-development (test-first), brainstorming → writing-plans (design open), executing-plans (pre-written plan). The orchestrator names the work-mode in the dispatch's SKILL field; that choice is authoritative — the agent loads exactly that mode, it does not re-decide.
+Work-mode (pick exactly one per implementation dispatch) — encoded in the decision tree above: quick-dev (bounded), code-agent (mostly clear), test-driven-development (test-first), brainstorming → writing-plans (design open), executing-plans (pre-written plan — sequential single-agent by default, or parallel multi-agent fan-out when 2+ independent sub-problems). The orchestrator names the work-mode in the dispatch's SKILL field; that choice is authoritative — the agent loads exactly that mode, it does not re-decide.
 
 Construction work-modes (quick-dev / code-agent / executing-plans) silently layer `the-ladder` — build the minimum (stdlib → native platform → installed dep before new code) and mark deliberate simplifications with `// SHORTCUT: <ceiling>, upgrade when <trigger>`. It is a build-time reflex, not a work-mode of its own.
 
@@ -385,10 +391,10 @@ Auto-layer signals (announce, don't ask):
 - Test failures → `systematic-debugging` on `oncall-ops`
 - Non-trivial "done" without verification → `devil-advocate` PHASE: execute
 - Could break API → `requesting-code-review` on `code-reviewer`
-- 2+ independent sub-problems → `subagent-driven-development`
+- 2+ independent sub-problems → `executing-plans` (parallel mode)
 - GitHub PR + "deep review" → `deep-pr-review` on `code-reviewer`
 
-Full catalogue (15 skills): quick-dev, code-agent, test-driven-development, brainstorming, writing-plans, executing-plans, subagent-driven-development, systematic-debugging, to-diagram, init-project, deep-pr-review, requesting-code-review, caveman-commit, enriching-codegraph-proposals, the-ladder
+Full catalogue (15 skills): quick-dev, code-agent, test-driven-development, brainstorming, writing-plans, writing-knowledge, executing-plans, systematic-debugging, to-diagram, init-project, deep-pr-review, requesting-code-review, caveman-commit, enriching-codegraph-proposals, the-ladder
 
 > **Note:** `confidence-gate` and `verification-before-completion` have been replaced by the `devil-advocate` subagent dispatched at phase checkpoints.
 
@@ -401,14 +407,14 @@ Full catalogue (15 skills): quick-dev, code-agent, test-driven-development, brai
 2. `arcs project list` → conflict check
 3. Present summary → user confirms → `arcs project init`
 4. `arcs project update-doc × 4`
-5. Fan out: `system-architect` + `docs-researcher` + `tech-architect` → dedup → `arcs knowledge create × N`
+5. Fan out: `tech-architect` + `docs-researcher` → dedup → `arcs knowledge create × N`
 6. If `data.codegraph.pending_enrichment === true` → load `enriching-codegraph-proposals`
 
 ### BRAINSTORM Workflow
 1. Read prior decisions first: `arcs knowledge search <slug> "<feature keywords>" --lean --json` for kind=decision/architecture so you neither relitigate nor contradict a settled call. Then challenge: "What breaks? Who is blocked?" Apply YAGNI.
 2. Strip to minimum viable scope
 3. Force precision: "What exactly changes? Done in one sentence?"
-4. Dispatch `system-architect` or `tech-architect` for scoping → present plan → user confirms
+4. Dispatch `tech-architect` for scoping → present plan → user confirms
 5. `devil-advocate` PHASE: brainstorm → handle verdict
 6. On PASS: `arcs plan create` → `arcs task create × N` (ALWAYS `--dependsOn` for chained tasks) → `arcs diagram init` → `arcs knowledge upsert --kind=decision` for each load-bearing decision and rejected-alternative-with-rationale the brainstorm produced (the richest, most-skipped entries — capture them now while the reasoning is fresh)
 
@@ -454,7 +460,7 @@ Key commands:
 - T0: `arcs brief --lean --json`
 - Tasks: `arcs task list/create/transition <slug> ...`
 - Plans: `arcs plan list/create/update-meta <slug> ...`
-- Knowledge (write): `arcs knowledge upsert <slug> <title> --kind=<kind> --summary="..." --keywords="..." --source-files="path:anchor"` (idempotent-by-title — DEFAULT) | `arcs knowledge create ...` (fail-if-title-exists)
+- Knowledge (write): `arcs knowledge upsert <slug> <title> --kind=<kind> --summary="..." --body="..." --keywords="..." --source-files="path:anchor"` (idempotent-by-title — DEFAULT; `--body-file=<path>` for long bodies) | `arcs knowledge create ...` (fail-if-title-exists)
 - Knowledge (read): `arcs knowledge search <slug> "<q>" --lean --json` | `arcs knowledge get <slug> <id> --body --lean --json` | `arcs knowledge list <slug> --kind=<kind> --json`
 - Search: `arcs search <slug> "<query>" --json`
 - Diagram: `arcs diagram ready/init/sort-metadata <slug> <planId> --json`