docs(agents): fix stale references in architect.md and coordinator.md
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.
This commit is contained in:
1 parent
f93ac3792d
commit
ff07f92bdb
2 files changed
+11
-7
No files matched your search
@@ -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."
|
||||
|
||||
@@ -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}}. <brief summary>", 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
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user