From 2340738a19346bfc63a7fc04ab8e65477751ee77 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Sun, 25 Oct 2026 05:32:24 +0000 Subject: [PATCH] docs(agents): de-alkgit the copied process scaffolding The .opencode agent definitions and docs/sdd_process.md were copied verbatim from alkgit; replace the stale project references with alkssh-shaped ones: - sdd_process.md: title line named @alkdev/alkgit - coordinator.md: example spawn prompt named the project and carried alkgit constraints (pure protocol crate, gix, feature list) - implementation-specialist.md: conventions 7-9 were alkgit's (gitoxide/no-MPL, sha256/acme features, repo-public auth wording); now russh-owns-the-wire, fail-closed mapping features, key reuse - architect.md: deferral examples named alkgit-admin and the alkhttp git-feature shape - poc-specialist.md: standalone-POC path example /workspace/alkgit-poc1 Verification: docs-only change --- .opencode/agents/architect.md | 10 +++++----- .opencode/agents/coordinator.md | 13 +++++++------ .opencode/agents/implementation-specialist.md | 18 +++++++++--------- .opencode/agents/poc-specialist.md | 2 +- docs/sdd_process.md | 2 +- 5 files changed, 23 insertions(+), 22 deletions(-) diff --git a/.opencode/agents/architect.md b/.opencode/agents/architect.md index 78c2e27..0a0edb5 100644 --- a/.opencode/agents/architect.md +++ b/.opencode/agents/architect.md @@ -330,7 +330,7 @@ A decision should be `deferred(scope)` when: - The use case isn't concrete (e.g., "we don't know what the admin API will need from the call protocol") - The options depend on something that doesn't exist yet (e.g., - "depends on the alkhttp git-feature shape") + "depends on the sftp mapping shape, which is alkfs's design question") - 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 @@ -374,10 +374,10 @@ 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: alkgit-admin crate spec - exists" or "investigation: work through 2+ example git-over-ssh use - cases (clone and push) to see how identity + repo resolution + - pkt-line session compose." + would unblock this? Be concrete: "blocked on: the alkfs sftp-mapping + spec exists" or "investigation: work through 2+ example git-over-ssh + use cases (clone and push) to see how identity + auth + the + exec/subsystem channel mapping compose." 3. **State the impacts** — what does this block downstream? Be specific: "blocks the http endpoint because receive-pack needs unbuffered POST ingestion" not "blocks the http crate." This is the diff --git a/.opencode/agents/coordinator.md b/.opencode/agents/coordinator.md index d1d18e1..a6e4f2f 100644 --- a/.opencode/agents/coordinator.md +++ b/.opencode/agents/coordinator.md @@ -192,7 +192,7 @@ also include: Example prompt template: ``` -You are an implementation specialist for the @alkdev/alkgit project. +You are an implementation specialist for the @alkdev/alkssh project. Your task: {{task}} @@ -205,15 +205,16 @@ 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/alkgit): -- Pure protocol crate: single `alkgit` at repo root (ADR-010); no - workspace, no binary, no front-door crates +Key project constraints (@alkdev/alkssh): +- russh-wrapped SSH adapter over alkcall channels (family ADR-003); + no in-family SSH framing — russh owns the wire +- Every channel-type mapping is a cargo feature; unfeatured channel + opens decline fail-closed (a git-only build serves no shell) +- Keys flow through alkvault-backed sources; never env vars - Rust: use cargo build, cargo clippy, cargo fmt, cargo test - No comments in code - thiserror for library error types; no panics in library code -- Feature flags for optional surface (gix default-on, sha256) - Async via tokio runtime -- gitoxide (gix) for git storage/wire primitives; never shell out to git ``` ### Partial Generation Spawning diff --git a/.opencode/agents/implementation-specialist.md b/.opencode/agents/implementation-specialist.md index 4e3dcaf..ad1831b 100644 --- a/.opencode/agents/implementation-specialist.md +++ b/.opencode/agents/implementation-specialist.md @@ -231,15 +231,15 @@ rules (summary — AGENTS.md wins on any conflict): ADRs for the current list per crate). 7. **Visible-surface = authorized-surface** — use alkcall's model: `AccessControl` on every op; `Visibility::Internal` ops are never - wire-callable. No unauthenticated endpoints unless a repo is explicitly - public. -8. **gitoxide for git primitives** — storage and pkt-line come from gix - crates; never shell out to the `git` binary in the serving path; never - copy code from MPL-2.0-licensed reference projects (see - `docs/research/reference-policy.md`). -9. **Feature flags** — optional surface is feature-gated (`sha256`, - `acme`); base crates compile lean. Verify both `cargo test` (default) - and `cargo test --all-features` pass if features are added. + wire-callable. No unauthenticated endpoints; every capability the + wire can reach must be explicitly granted. +8. **russh owns the SSH wire** — no in-family SSH framing (family + ADR-003); protocol asks to russh upstream, never silently absorbed. + Keys flow through alkvault-backed sources, never env vars. +9. **Feature flags** — every channel-type mapping is a cargo feature + and declines unfeatured channel opens fail-closed; base crate + compiles lean. Verify both `cargo test` (default) and + `cargo test --all-features` pass if features are added. 10. **Naming conventions** — Rust standard: `snake_case` for functions/variables/modules, `PascalCase` for types/traits, `SCREAMING_SNAKE_CASE` for constants. diff --git a/.opencode/agents/poc-specialist.md b/.opencode/agents/poc-specialist.md index 3990f9d..be2920d 100644 --- a/.opencode/agents/poc-specialist.md +++ b/.opencode/agents/poc-specialist.md @@ -55,7 +55,7 @@ worktree({action: "status"}) → Show worktree git status ## Your Environment (standalone mode) There is no worktree tool mapping. Your working directory is the scratch -project root (e.g. `/workspace/alkgit-poc1`); create it with `cargo new` or +project root (e.g. `/workspace/alkssh-poc1`); create it with `cargo new` or similar if it doesn't exist. Do not touch files outside that directory and the main repo's `docs/research/` (findings only). diff --git a/docs/sdd_process.md b/docs/sdd_process.md index 5a8a720..51b204a 100644 --- a/docs/sdd_process.md +++ b/docs/sdd_process.md @@ -2,7 +2,7 @@ ## Overview -This document defines the SDD process for the @alkdev/alkgit project. It +This document defines the SDD process for the @alkdev/alkssh project. It leverages: - **OpenCode CLI** as the agent execution environment