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
|
- **OQ-ID** (OQ-01, OQ-02, ...) — stable reference
|
||||||
- **Origin** — which spec doc(s) the question appeared in
|
- **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
|
- **Priority** — high, medium, low
|
||||||
- **Resolution** — when resolved, what was decided and which ADR addresses it
|
- **Resolution** — when resolved, what was decided and which ADR addresses it
|
||||||
- **Cross-references** — related OQs and ADRs
|
- **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
|
1. Mark the OQ as `deferred(scope)` with a concrete blocking condition
|
||||||
2. Create a blocker task in `tasks/architecture/` naming the dependency
|
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
|
3. Continue to decisions that *can* be made — do not stall on one question
|
||||||
|
|
||||||
### 6. Request Architecture Review
|
### 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
|
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
|
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
|
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.
|
full rationale.
|
||||||
|
|
||||||
Architecture decisions are the architect's, regardless of door type.
|
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
|
- The use case isn't concrete (e.g., "we don't know what the agent crate
|
||||||
will need from the call protocol")
|
will need from the call protocol")
|
||||||
- The options depend on something that doesn't exist yet (e.g.,
|
- 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
|
- The trade-off requires data that can only come from implementation
|
||||||
(e.g., "need performance benchmarks to choose between X and Y")
|
(e.g., "need performance benchmarks to choose between X and Y")
|
||||||
- The decision is genuinely not needed for the current scope (e.g., "the
|
- 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).
|
(implies it's decided).
|
||||||
2. **State the blocking condition** (`deferred(scope)`) or
|
2. **State the blocking condition** (`deferred(scope)`) or
|
||||||
**investigation target** (`deferred(unclear)`) — what specific thing
|
**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
|
exists" or "investigation: work through 2+ example outbound-dial use
|
||||||
cases (hub→worker, worker→hub) to see how verifier-selection +
|
cases (hub→worker, worker→hub) to see how verifier-selection +
|
||||||
provider + connector compose."
|
provider + connector compose."
|
||||||
|
|||||||
@@ -191,7 +191,7 @@ also include:
|
|||||||
Example prompt template:
|
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}}
|
Your task: {{task}}
|
||||||
|
|
||||||
@@ -204,11 +204,11 @@ Your task: {{task}}
|
|||||||
7. Push: git push origin $(git branch --show-current)
|
7. Push: git push origin $(git branch --show-current)
|
||||||
8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}})
|
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
|
- Rust: use cargo build, cargo clippy, cargo fmt, cargo test
|
||||||
- No comments in code
|
- No comments in code
|
||||||
- anyhow::Result for application errors, thiserror for library error types
|
- 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
|
- Async via tokio runtime
|
||||||
- No panics in library code
|
- No panics in library code
|
||||||
```
|
```
|
||||||
|
|||||||
Reference in new issue
Block a user