admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Detailed design §23: pin reference paths to verified checkout names

Browse Source 
Q2 calibration: replaced <version>/<v> placeholders with the actual pinned
directory names now present under <repo-root>/reference/ (repo root is
AirCoding/, parent of AirPlan/ — clarified so subagents resolve paths
correctly). Added a verified directory listing block and fixed a misplaced
"behavioral" reuse-mode bullet that had drifted below the location note.

All eight cited reference paths verified non-empty on disk.

Documentation only.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
AirCoding
2026-06-01 18:04:05 +08:00
parent e9305a45a7
commit 0b15670a0c
1 changed files with 21 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
AirPlan/docs/architecture/system-detailed-design.md
View File

@@ -2369,25 +2369,34 @@ invariants.
- `npm-dep` — consume directly as a dependency; do not re-implement.
- `fork/adapt` — copy and adapt source into our package; keep our own boundaries.
- `pattern` — reference structure/patterns; implement independently.
**Reference source location:** local reference checkouts live at `<repo-root>/reference/<name>-<version>/`
where `<repo-root>` is the git root (`AirCoding/`, the parent of `AirPlan/`). This `reference/`
tree is **not committed** (working-copy only). Implementers (including isolated subagents) must
verify the referenced checkout exists and is non-empty before relying on it; if absent, clone the
upstream repo to that path. Paths in the table below are relative to `<repo-root>`.
- `behavioral` — match observable behavior/quality; no code lineage.
**Reference source location:** local reference checkouts live under the working-copy `reference/`
tree at the **git root** — i.e. `<repo-root>/reference/`, where `<repo-root>` is `AirCoding/`, the
parent of `AirPlan/` (which holds this design). Paths in the table below are relative to
`<repo-root>`, not to `AirPlan/`. This `reference/` tree is **git-ignored / not committed**
(working-copy only, ~0.5 GB). Implementers (including isolated subagents) must verify the referenced
checkout exists and is non-empty before relying on it; if absent, clone the upstream repo to that
path. Current pinned directory names (verified present):
```text
reference/opencode-1.15.5/ reference/openai-codex/
reference/hermes-agent-2026.5.16/ reference/anthropic-skills/
reference/asciinema-3.2.0/ reference/atuin-18.16.1/
reference/claude-hud-0.0.12/ reference/claude-code-cli/ (Claude Code 2.1.88, behavioral ref only)
```
| DD component | Reference project (baselineV1 §2) | Reuse mode | Notes / local path |
|---|---|---|---|
| §13.2 TUI (`TuiApp`, components) | OpenTUI (`@opentui/solid` `@opentui/core` `@opentui/keymap`) | `npm-dep` | D-002/D-048: direct dependency; do not build a renderer. Theme/dialog/toast/keymap/layout/spinner/border/markdown/code/diff rendering adapted from OpenCode UI patterns. |
| §13.2 TUI interaction layout | OpenCode TUI | `pattern` | D-048: reference visual/interaction patterns; **do not** reuse OpenCode SDK/sync/session business state. |
| §12 Provider (`ProviderManager`, `ProviderAdapter`, converters) | `@opencode-ai/llm` | `fork/adapt` | D-002 list: provider/model abstraction may be forked/adapted; output stays Anthropic-canonical (D-046). |
| §8.4 + §9.4 Execution discipline (read-before-edit, exact edit, verify-before-complete) | Claude Code CLI | `behavioral` | baselineV1 §2: quality benchmark only — edit safety, patch granularity, conflict handling, verification discipline. No code lineage. |
| §13.2 TUI interaction layout | OpenCode TUI (`reference/opencode-1.15.5/`) | `pattern` | D-048: reference visual/interaction patterns; **do not** reuse OpenCode SDK/sync/session business state. |
| §12 Provider (`ProviderManager`, `ProviderAdapter`, converters) | `@opencode-ai/llm` (`reference/opencode-1.15.5/`) | `fork/adapt` | D-002 list: provider/model abstraction may be forked/adapted; output stays Anthropic-canonical (D-046). |
| §8.4 + §9.4 Execution discipline (read-before-edit, exact edit, verify-before-complete) | Claude Code CLI (`reference/claude-code-cli/`) | `behavioral` | baselineV1 §2: quality benchmark only — edit safety, patch granularity, conflict handling, verification discipline. No code lineage. |
| §9.4 `fs.edit`/`fs.patch` + §15 patch/test execution loop | OpenAI Codex (`reference/openai-codex/`) | `pattern` | baselineV1 §2: shell/patch/test direct-execution loop, tool orchestration, wider tool surface. |
| §11.3 + §14 Knowledge / ExperienceMiner / Curator | Hermes Agent (`reference/hermes-agent-<version>/`) | `pattern` | D-024: Nudge Engine interval trigger (~10 turns/tool-calls), Curator dedup daemon, skill self-patch. |
| §11.3 + §14 Knowledge / ExperienceMiner / Curator | Hermes Agent (`reference/hermes-agent-2026.5.16/`) | `pattern` | D-024: Nudge Engine interval trigger (~10 turns/tool-calls), Curator dedup daemon, skill self-patch. |
| §11.3 + runtime-semantics §11 Skills (`SKILL.md`, `scripts/`/`references/`/`assets/`) | Anthropic Claude Skills (`reference/anthropic-skills/`) | `pattern` | D-058: SKILL.md frontmatter + directory layout + trigger/retrieval descriptions; SkillGenerator output format. |
| §16.2 Logging / HUD + future PTY capture | asciinema / Atuin / claude-hud (`reference/asciinema-<v>/`, `reference/atuin-<v>/`, `reference/claude-hud-<v>/`) | `pattern` | baselineV1 §2: PTY capture, command metadata/history indexing, HUD/statusline layout. |
| §3 Message format (Anthropic canonical content blocks) | Claude Code message model | `behavioral` | D-016: Text/Thinking/ToolUse/ToolResult blocks; canonical internal format. |
| §16.2 Logging / HUD + future PTY capture | asciinema / Atuin / claude-hud (`reference/asciinema-3.2.0/`, `reference/atuin-18.16.1/`, `reference/claude-hud-0.0.12/`) | `pattern` | baselineV1 §2: PTY capture, command metadata/history indexing, HUD/statusline layout. |
| §3 Message format (Anthropic canonical content blocks) | Claude Code message model (`reference/claude-code-cli/`) | `behavioral` | D-016: Text/Thinking/ToolUse/ToolResult blocks; canonical internal format. |
**Rules for reference reuse:**