From ff07f92bdbb873af6e21b7199cf34d6ace38ca02 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Tue, 13 Oct 2026 11:16:31 +0000 Subject: [PATCH] docs(agents): fix stale references in architect.md and coordinator.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit architect.md: - ADR-009 §"What this framework is NOT" → ADR-032 — the pointer was an alknet-numbering leftover; in-crate ADR-009 is BiStream-as-handler-leaf, the door-framework section lives in ADR-032. Same collision class the docs pass (5f019c0) fixed in the spec. - OQ status list now includes deferred(scope), deferred(unclear), dissolved — matching the tracker's actual vocabulary and this prompt's own Safe-Exit section (they contradicted each other). - tasks/architecture/ softened: this repo has no tasks/ dir; the OQ "Blocked on:" field is the tracker of record. - Deferral-blocker examples re-keyed off alknet ("alknet-http crate spec" → the composition-layer crate spec, OQ-43; "alknet-agent crate spec" → "the agent crate's spec") — examples were teaching the exact repo-pinned blocker class just cleaned out of the OQs. coordinator.md: - Example spawn template said "implementation specialist for @alkdev/alknet" with alknet-era constraints ("feature flags for transports (tls, iroh, acme)") — agents copying the template would re-introduce the residue into every spawned prompt. Now names @alkdev/alkcall and points at AGENTS.md convention 11 (lean base crate, no quinn/iroh unless the feature is on). Verification: repo-wide residue sweep — alknet mentions survive only in AGENTS.md's intentional provenance/historical framing; no stale ADR number pointers remain in .opencode/agents/; architect.md's internal sections (Safe Exit, anti-patterns, status vocabulary) are mutually consistent. --- .opencode/agents/architect.md | 12 ++++++++---- .opencode/agents/coordinator.md | 6 +++--- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/.opencode/agents/architect.md b/.opencode/agents/architect.md index 836546b..44dd238 100644 --- a/.opencode/agents/architect.md +++ b/.opencode/agents/architect.md @@ -99,7 +99,8 @@ organized by theme. Each question has: - **OQ-ID** (OQ-01, OQ-02, ...) — stable reference - **Origin** — which spec doc(s) the question appeared in -- **Status** — open, resolved, partially resolved +- **Status** — open, resolved, partially resolved, deferred(scope), + deferred(unclear), dissolved - **Priority** — high, medium, low - **Resolution** — when resolved, what was decided and which ADR addresses it - **Cross-references** — related OQs and ADRs @@ -190,6 +191,8 @@ When you encounter a decision that genuinely can't be made: 1. Mark the OQ as `deferred(scope)` with a concrete blocking condition 2. Create a blocker task in `tasks/architecture/` naming the dependency + (where the project tracks tasks that way — otherwise the OQ's + `Blocked on:` field is the tracker of record) 3. Continue to decisions that *can* be made — do not stall on one question ### 6. Request Architecture Review @@ -274,7 +277,7 @@ Door type classifies **reversal cost** (one-way vs two-way), not urgency. A two-way door is a decision you make now and can revert later — not a decision to defer. Using "it's a two-way door" as a reason to leave a decision unmade conflates reversal cost with -decision-making. See ADR-009 §"What this framework is NOT" for the +decision-making. See ADR-032 §"What this framework is NOT" for the full rationale. Architecture decisions are the architect's, regardless of door type. @@ -329,7 +332,8 @@ A decision should be `deferred(scope)` when: - The use case isn't concrete (e.g., "we don't know what the agent crate will need from the call protocol") - The options depend on something that doesn't exist yet (e.g., - "depends on the alknet-http crate spec") + "depends on the composition-layer crate spec — owner and shape not + committed, see OQ-43") - The trade-off requires data that can only come from implementation (e.g., "need performance benchmarks to choose between X and Y") - The decision is genuinely not needed for the current scope (e.g., "the @@ -373,7 +377,7 @@ A decision should be `deferred(unclear)` when: (implies it's decided). 2. **State the blocking condition** (`deferred(scope)`) or **investigation target** (`deferred(unclear)`) — what specific thing - would unblock this? Be concrete: "blocked on: alknet-agent crate spec + would unblock this? Be concrete: "blocked on: the agent crate's spec exists" or "investigation: work through 2+ example outbound-dial use cases (hub→worker, worker→hub) to see how verifier-selection + provider + connector compose." diff --git a/.opencode/agents/coordinator.md b/.opencode/agents/coordinator.md index 2327646..d81ffb4 100644 --- a/.opencode/agents/coordinator.md +++ b/.opencode/agents/coordinator.md @@ -191,7 +191,7 @@ also include: Example prompt template: ``` -You are an implementation specialist for the @alkdev/alknet project. +You are an implementation specialist for the @alkdev/alkcall project. Your task: {{task}} @@ -204,11 +204,11 @@ Your task: {{task}} 7. Push: git push origin $(git branch --show-current) 8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. ", level: "info"}}) -Key project constraints (@alkdev/alknet): +Key project constraints (@alkdev/alkcall): - Rust: use cargo build, cargo clippy, cargo fmt, cargo test - No comments in code - anyhow::Result for application errors, thiserror for library error types -- Feature flags for transports (tls, iroh, acme) +- Base crate compiles lean (no quinn/iroh unless the feature is on — see AGENTS.md convention 11) - Async via tokio runtime - No panics in library code ```