@rryando/arcs 3.6.0 → 3.7.0

package/opencode/arcs/prompts/system-architect.txt

@@ -7,6 +7,8 @@ Your dispatch normally carries SCOPE/CONTEXT/IDS with pre-derived facts. When it
 2. Run `arcs brief --lean --json` for live DAG state — ONLY when the dispatch carries no T0 excerpt.
 3. Run `arcs search <slug> "<keywords>" --json` — ONLY for context the dispatch left open.
 
+KNOWLEDGE-FIRST: before producing output, unless your dispatch CONTEXT already carries the relevant prior knowledge, run `arcs knowledge search <slug> "<scope keywords>" --lean --json` and read any kind=architecture|decision|gotcha|pattern|lesson entry covering your SCOPE (`arcs knowledge get <slug> <id> --body --lean --json` for full text). Incorporate it — do not rediscover what the DAG already knows. Skip only for purely mechanical changes.
+
 Core skills you load: brainstorming (design exploration with dual-mode ARCS integration), writing-plans (implementation plans), to-diagram (visual execution maps).
 
 You have ARCS CLI access — use it to read project context across multiple projects, check dependency graphs, create plans, and capture architectural decisions as knowledge entries (kind: architecture).
@@ -30,7 +32,7 @@ MANDATORY EXIT GATE: Before finalizing any design, verify: (1) dependency direct
 | `arcs graph inspect <slug> --json` | Analyze coupling density and fan-in/fan-out |
 | `arcs related <slug> --plan=<planId> --json` | Find graph-linked entities across projects |
 | `arcs plan create <slug> "..." --summary="..." --status=planned --json` | Propose multi-step structural change |
-| `arcs knowledge create <slug> "<title>" --kind=architecture --summary="..." --json` | Record architectural decision or observation |
+| `arcs knowledge upsert <slug> "<title>" --kind=architecture --summary="..." --json` | Record architectural decision or observation (idempotent by title) |
 | `arcs search <slug> "<keywords>" --lean --json` | Find existing plans/knowledge before proposing new |
 
 All commands support `--json` for machine-readable output. Reads return `{ok, data}`; failures return `{ok:false, code, message, hint?}`. **Routing:** success → stdout, errors → stderr — always capture both with `2>&1`.
@@ -71,7 +73,11 @@ BOUNDARIES:
 RISKS:
 - <risk with severity and mitigation>
 
-ARTIFACTS:
+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
+  (upsert is idempotent by title — no dedup search needed)>
+
+ARTIFACTS:   (non-knowledge artifacts only — plans, diagrams, dependency edges)
 - executed: <arcs command run + resulting entry/plan id>
 - proposed: <ready-to-run arcs command for the orchestrator to execute verbatim>
 ```

package/opencode/arcs/prompts/tech-architect.txt

@@ -11,6 +11,8 @@ Your dispatch normally carries SCOPE/CONTEXT/IDS with pre-derived facts. When it
 2. Run `arcs brief --lean --json` for live DAG state — ONLY when the dispatch carries no T0 excerpt.
 3. Run `arcs search <slug> "<keywords>" --json` — ONLY for context the dispatch left open.
 
+KNOWLEDGE-FIRST: before producing output, unless your dispatch CONTEXT already carries the relevant prior knowledge, run `arcs knowledge search <slug> "<scope keywords>" --lean --json` and read any kind=architecture|decision|gotcha|pattern|lesson entry covering your SCOPE (`arcs knowledge get <slug> <id> --body --lean --json` for full text). Incorporate it — do not rediscover what the DAG already knows. Skip only for purely mechanical changes.
+
 Core skills you load: brainstorming (design exploration), writing-plans (structured plans from analysis findings).
 
 You have ARCS CLI access — use it to read project context, check existing architectural knowledge entries, and capture findings as durable knowledge entries (kind: architecture or lesson).
@@ -31,8 +33,8 @@ MANDATORY EXIT GATE: Before delivering analysis, confirm: (1) all relevant modul
 | `arcs related <slug> --knowledge=<id> --json` | Trace dependency chains between entities |
 | `arcs audit <slug> --json` | Check structural health (stale refs, orphan entities) |
 | `arcs knowledge get <slug> <id> --body --json` | Read full knowledge entry for deep analysis |
-| `arcs knowledge search <slug> "<keywords>" --lean --json` | Find prior architectural findings |
-| `arcs knowledge create <slug> "<title>" --kind=architecture --summary="..." --json` | Record analysis finding |
+| `arcs knowledge search <slug> "<keywords>" --lean --json` | Find prior kind=architecture\|decision findings before analyzing |
+| `arcs knowledge upsert <slug> "<title>" --kind=architecture --summary="..." --json` | Record analysis finding (idempotent by title) |
 | `arcs diff <slug> --since="7d" --json` | See what changed since last sync (scope recent changes) |
 
 All commands support `--json` for machine-readable output. Reads return `{ok, data}`; failures return `{ok:false, code, message, hint?}`. **Routing:** success → stdout, errors → stderr — always capture both with `2>&1`.
@@ -47,9 +49,9 @@ When dispatched for structural analysis:
 2. `arcs graph inspect <slug> --json` — get coupling density, fan-in/fan-out metrics
 3. `arcs related <slug> --knowledge=<id> --json` — trace dependency chains from the subject
 4. `arcs audit <slug> --json` — check for structural health issues
-5. `arcs knowledge search <slug> "<area>" --lean --json` — find prior findings
+5. `arcs knowledge search <slug> "<area>" --lean --json` — find prior kind=architecture|decision findings before analyzing
 6. Analyze: apply 6-dimension framework (module boundaries, dependency direction, API cohesion, coupling, layering, evolution fitness)
-7. `arcs knowledge create <slug> "<finding>" --kind=architecture --summary="..." --json` — record findings
+7. `arcs knowledge upsert <slug> "<finding>" --kind=architecture --summary="..." --json` — record findings (idempotent by title)
 
 Output: severity-ranked findings with evidence (file paths, metrics, dependency chains).
 
@@ -73,7 +75,11 @@ RECOMMENDATIONS:
 RISKS:
 - <risk if recommendation is NOT followed>
 
-ARTIFACTS:
+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
+  (upsert is idempotent by title — no dedup search needed)>
+
+ARTIFACTS:   (non-knowledge artifacts only — plans, diagrams)
 - executed: <arcs command run + resulting entry id>
 - proposed: <ready-to-run arcs command for the orchestrator to execute verbatim>
 ```

package/opencode/arcs/skills/brainstorming/SKILL.md

@@ -41,6 +41,10 @@ flowchart TD
     K --> L[Invoke writing-plans skill]
 ```
 
+## Prior Decisions Check
+
+Before challenging, read what's already settled so you don't relitigate or contradict a prior call: `arcs knowledge search <slug> "<topic-keywords>" --lean --json` filtering for `kind=decision` and `kind=architecture`. If a load-bearing decision already covers this area, surface it — a settled call is not reopened without a concrete new trigger.
+
 ## Challenge Protocol
 
 Before designing anything, interrogate the request:
@@ -124,6 +128,8 @@ arcs plan create <slug> --title="YYYY-MM-DD <topic> Design" --summary="..." --st
 
 When creating tasks from the plan, wire execution order with `--dependsOn=dep-task-id-1,dep-task-id-2`. The `dependsOn` graph determines what `arcs next` returns — priority is a tiebreaker within the same topological level.
 
+After the design lands, capture the reasoning that the plan body alone will lose — this is the richest, most-skipped knowledge in the whole workflow. For each load-bearing DECISION and each REJECTED ALTERNATIVE (with the rationale for rejection), emit/run an upsert: `arcs knowledge upsert <slug> "<decision title>" --kind=decision --summary="<what was decided and why; what was rejected and why>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json`. Upsert is idempotent by title, so no dedup search is needed. (When the orchestrator drives this skill, emit the upsert command for it to run; standalone with bash, run it directly.)
+
 After storage: _"Spec saved to plan `<planId>`. Review it. Push back if anything's wrong."_
 
 ## Visual Companion

package/opencode/arcs/skills/code-agent/SKILL.md

@@ -42,6 +42,10 @@ Look for:
 
 If relevant entries exist, incorporate their guidance. Don't rediscover what's already known.
 
+## Capture Exit: Record What You Resolved
+
+Phase 0 is read-only; close the loop on the way out. After implementing, if you resolved a non-obvious ambiguity or hit a gotcha worth saving, upsert it so the next agent doesn't re-investigate: `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<what was resolved / the trap and how to avoid it>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip when the work was mechanical and surfaced nothing non-obvious. Upsert is idempotent by title.
+
 ## Behaviour
 
 - Apply `the-ladder` during implementation — reach for stdlib / native / an installed dep before new code, and leave `// SHORTCUT:` markers for deliberate simplifications

package/opencode/arcs/skills/deep-pr-review/SKILL.md

@@ -45,7 +45,7 @@ flowchart TD
     S -->|don't post| END1[Show report only]
     S -->|post| T[gh api: review + inline comments]
     T --> U{Recurring pattern surfaced?}
-    U -->|yes + opt-in| V[Propose knowledge:create]
+    U -->|yes| V[Propose arcs knowledge upsert in report — ARCS-write opt-in to apply]
     U -->|no| END2[Done]
     V --> END2
 ```
@@ -180,6 +180,10 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 | 4 (summary only) | `gh pr review <number> --comment --body "..."` — **one call, no `comments[]`** |
 | 5 (don't post) | No `gh` writes |
 
+## Knowledge Proposals (standard report output)
+
+A recurring finding — the same class of bug, the same convention violation, a trap seen more than once across the diff — is durable knowledge, not just a one-off comment. Make proposing it a standard part of the report, not an afterthought: for each recurring finding, include a proposed `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --keywords="<k1,k2>" --source-files="<path,...>" --json` in the report. This is a *proposal*: it is still subject to the ARCS-write opt-in and only applied when the user opts in. It does NOT gate on the GitHub posting choice — a review that posts nothing can still surface knowledge proposals. Upsert is idempotent by title.
+
 ## Report Structure
 
 ```
@@ -189,6 +193,7 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 ## Rubric Selection (which dimensions activated, why)
 ## Findings (grouped by severity)
 ## Cleared Dimensions (with evidence)
+## Knowledge Proposals (recurring findings → proposed arcs knowledge upsert, ARCS-write opt-in)
 ## Architectural / Performance Handoffs (if any)
 ## Posting Plan (mode chosen → exact comments to be posted)
 ## Confidence & Gaps

package/opencode/arcs/skills/executing-plans/SKILL.md

@@ -57,6 +57,8 @@ When plan has `.diagram.mmd`:
 
 **Verify scope rule:** Run ONLY the current task's `verify` command, scoped to that task's `files`. If the authored command is broader than the task's scope (bare `npm test`, `vitest run`, `biome check .`), narrow it to the touched files first (e.g. `npm test -- test/orders.test.ts`). Failures in files outside the task's scope are report-only — list them under BLOCKED_BY, never fix them. Full-project verification happens once, at the devil-advocate completion gate.
 
+**Directed gotcha read before each task:** Before executing a task, search the DAG for known traps in its area so you don't walk into one the plan didn't anticipate: `arcs knowledge search <slug> "<task-keywords>" --lean --json`, filtering for `kind=gotcha`. Pull the body of anything relevant with `arcs knowledge get <slug> <id> --body --lean --json`.
+
 ## Sub-Agent Context
 
 Fetch once, then paste the relevant output into each dispatch's CONTEXT — don't make sub-agents re-fetch:
@@ -79,6 +81,10 @@ Sub-agents MUST NOT edit `.mmd` files — orchestrator owns diagram updates.
 
 Ask for clarification rather than guessing. Don't force through blockers.
 
+## Capturing Execution Discoveries
+
+When execution surfaces something the plan didn't know — a plan-vs-reality delta, a gotcha hit mid-task, a convention the plan got wrong — capture it so the "new knowledge entries" sync trigger below actually fires: `arcs knowledge upsert <slug> "<title>" --kind=<gotcha|lesson> --summary="<what reality diverged from the plan / the trap hit>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip when execution matched the plan exactly. Upsert is idempotent by title.
+
 ## Auto-Sync Triggers
 
 Post-execution DAG sync fires automatically when:

package/opencode/arcs/skills/quick-dev/SKILL.md

@@ -29,6 +29,10 @@ arcs knowledge search <slug> "<keywords>" --lean --json
 
 Check for patterns, gotchas, and lessons before implementing. Skip only if the change is purely mechanical (rename, config nudge).
 
+## Capture Exit (lightweight)
+
+If a "bounded" change surfaced a non-obvious gotcha along the way, capture it before finishing: `arcs knowledge upsert <slug> "<title>" --kind=gotcha --summary="<the trap in 1-2 sentences>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Mechanical changes capture nothing — keep this lightweight; only a genuine surprise is worth an entry. Upsert is idempotent by title.
+
 ## Behaviour
 
 0. Apply `the-ladder` before writing code — climb the rungs (stdlib / native platform / installed dep before new code) and mark deliberate simplifications with `// SHORTCUT:` comments

package/opencode/arcs/skills/requesting-code-review/SKILL.md

@@ -32,6 +32,10 @@ flowchart TD
 - `{BASE_SHA}` / `{HEAD_SHA}` — commit range
 - `{PROJECT_CONVENTIONS}` — CLAUDE.md / linter configs / style guides (gather once per session, reuse across dispatches)
 
+## Feed DAG Conventions to the Reviewer
+
+When gathering conventions, also pull what the DAG already knows so the reviewer checks against settled patterns, not just static config: `arcs knowledge search <slug> "<changed-area keywords>" --lean --json`, filtering for `kind=pattern` and `kind=gotcha`. Fold the relevant entries into the reviewer's `{PROJECT_CONVENTIONS}` context.
+
 ## When to Request
 
 **Mandatory:** after major features, before merge to main.
@@ -49,3 +53,7 @@ flowchart TD
 See template at: `requesting-code-review/code-reviewer.md`
 
 Reviewer returns the unified envelope: STATUS → VERDICT (approve | request-changes | comment-only) → FINDINGS by severity (CRITICAL/HIGH/MEDIUM/LOW) with 📍 file:line anchors.
+
+## Capture Recurring Findings
+
+When a finding recurs — the same class of issue flagged more than once, or a convention the codebase keeps violating — propose it as durable knowledge so future reviews and implementers inherit it: `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Upsert is idempotent by title.

package/opencode/arcs/skills/subagent-driven-development/SKILL.md

@@ -128,6 +128,10 @@ Mapping to the orchestrator's Standard Return Envelope: DONE→done, DONE_WITH_C
 Include in every dispatch prompt:
 > "Return format: brief prose findings first, then the JSON envelope (status + typed payload) from your role's prompt template as the LAST thing in your message — nothing after it."
 
+## Knowledge Capture at Fan-In
+
+The `concerns`, `scopeChanges`, and `DONE_WITH_CONCERNS` payloads already collected from each subagent are near-free durable signal — don't discard them. At fan-in, route the durable items (a non-obvious trap hit, a convention that had to be discovered, a plan-vs-reality delta) into the DAG: `arcs knowledge upsert <slug> "<title>" --kind=<gotcha|pattern> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip purely mechanical or task-local notes; capture only what the next agent would otherwise re-investigate. Upsert is idempotent by title.
+
 ## Git State Discipline
 
 - Sub-agents MUST NOT run `git stash` — ever, under any circumstance

package/opencode/arcs/skills/the-ladder/SKILL.md

@@ -47,6 +47,8 @@ Mark every deliberate simplification inline so it reads as intent, not ignorance
 
 The comment names the known ceiling AND the trigger to revisit. Example: `# SHORTCUT: global lock, switch to per-account locks when throughput matters`. A SHORTCUT marker with no named upgrade trigger is the kind that silently rots — always name the trigger. (These markers are harvested into the ARCS knowledge DAG at session completion by the orchestrator.)
 
+When a SHORTCUT's ceiling is durable and non-obvious — a real trap the next person could step into, not just a local stub — don't rely on the orchestrator harvest alone: also capture it directly with `arcs knowledge upsert <slug> "<ceiling title>" --kind=gotcha --summary="<the ceiling and its upgrade trigger>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. The harvest stays as backup; this is the path that fires when no orchestrator runs. Upsert is idempotent by title — skip the dedup search.
+
 ## Boundaries
 
 This skill governs WHAT you build (minimal), not correctness or how you talk. It layers under a work-mode skill (quick-dev / code-agent / executing-plans); it does not replace them. The devil-advocate gate still independently verifies KISS/YAGNI/DRY after the fact — the ladder is build-minimal, the gate is verify-minimal.

package/opencode/arcs/skills/writing-plans/SKILL.md

@@ -57,6 +57,10 @@ sourceFiles: [{path: "...", anchor: "..."}]
 ---end---
 ```
 
+## Prior Patterns Check
+
+Before mapping structure, read what the DAG already knows so the plan follows established shape: `arcs knowledge search <slug> "<feature-keywords>" --lean --json`, filtering for `kind=pattern` and `kind=architecture`. Reuse known conventions rather than inventing parallel ones.
+
 ## File Structure
 
 Before defining tasks, map which files will be created/modified:
@@ -163,6 +167,8 @@ flowchart TD
 arcs plan create <slug> --title="YYYY-MM-DD <feature> Implementation Plan" --summary="..." --status=planned --keywords="implementation-plan" --body="<markdown>" --json
 ```
 
+Then extract the plan's "why this structure" rationale into a durable entry — don't let the architecture reasoning stay sealed inside the plan body: `arcs knowledge upsert <slug> "<feature> architecture rationale" --kind=architecture --summary="<why the structure is shaped this way; key trade-offs>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json`. Use `--kind=decision` instead when the entry is really a single settled call rather than a structural shape. Upsert is idempotent by title.
+
 ## Execution Handoff
 
 > "Plan complete and saved via `arcs plan get <slug> <planId>` in project `<slug>`. Ready to execute?"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rryando/arcs",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "ARCS — DAG-based task orchestration for AI agents. Persistent workflow continuity via graph-structured context.",
   "type": "module",
   "main": "dist/index.js",