Skip to content

DECISIONS.md

Latest commit

 

History

History
141 lines (98 loc) · 9.75 KB

DECISIONS.md

File metadata and controls

141 lines (98 loc) · 9.75 KB
Raw

Architectural Decisions

Numbered decisions (D-XXX) with rationale. Immutable once recorded — new decisions can supersede but never delete old ones.

D-001: English-Only Skills

  • Date: 2026-05-19
  • Decision: All skill content MUST be in English only.
  • Rationale: Skills are instructions FOR Claude, not for end users. Claude reads English and responds in the user's language. Bilingual skills double maintenance with zero functional benefit. Proven in ERPNext (28 skills) and Blender-Bonsai (73 skills).
  • Consequence: No translations needed. All descriptions, code comments, and documentation in English.

D-002: MIT License

  • Date: 2026-05-19
  • Decision: Project uses MIT License.
  • Rationale: Most permissive license, maximizes adoption. Consistent with OpenAEC Foundation standards.
  • Consequence: No commercial restrictions. Community-friendly.

D-003: SKILL.md Under 500 Lines

  • Date: 2026-05-19
  • Decision: SKILL.md files MUST be under 500 lines.
  • Rationale: Keeps main skill focused on decision trees and quick reference. Heavy content belongs in references/ directory. Proven optimal in ERPNext (180-427 lines per skill).
  • Consequence: Complex topics split between SKILL.md (quick reference + patterns) and references/ (complete API, examples, anti-patterns).

D-004: 7-Phase Research-First Methodology

  • Date: 2026-05-19
  • Decision: Follow the 7-phase research-first development methodology.
  • Rationale: Proven in ERPNext (28 skills), Blender-Bonsai (73 skills), and Tauri 2 (27 skills). Research prevents hallucination. Deterministic skills require deep understanding.
  • Consequence: No skill creation without prior deep research. Phases are sequential with defined exit criteria.

D-005: ROADMAP.md as Single Source of Truth

  • Date: 2026-05-19
  • Decision: ROADMAP.md is the ONLY place for project status.
  • Rationale: Multiple status locations cause drift and "which is current?" confusion. Single source of truth enables reliable session recovery.
  • Consequence: Never duplicate status in CLAUDE.md or other files. All status references point to ROADMAP.md.

D-006: WebFetch for Research Verification

  • Date: 2026-05-19
  • Decision: Use WebFetch to verify all code examples against latest official documentation.
  • Rationale: Technology APIs evolve. Training data may be stale. WebFetch ensures latest official docs are consulted, not outdated cached knowledge.
  • Consequence: All code examples must be verified against current official documentation before inclusion in skills.

D-007: GitHub Publication Under OpenAEC Foundation

  • Date: 2026-05-19
  • Decision: Publish all skill packages under the OpenAEC Foundation GitHub organization.
  • Rationale: Centralized, consistent branding. Community ownership. Discoverability.
  • Consequence: All repos follow OpenAEC naming conventions and include social preview banners with OpenAEC branding.

D-008: Edition 2024 as Baseline + Dedicated Skill

  • Date: 2026-05-19
  • Decision: All Rust code in skills targets edition 2024 (Rust 1.85+). A dedicated rust-syntax-edition-2024 skill documents the 13 language changes shipped in 1.85 that affect every skill's code examples.
  • Rationale: Phase 2 research showed edition 2024 changes are pervasive (RPIT lifetime capture, never-type fallback, unsafe extern mandatory, unsafe_op_in_unsafe_fn warn-by-default, expr fragment specifier widening). Without a dedicated skill, every other skill would need an edition-2024 sidebar.
  • Consequence: rust-syntax-edition-2024 is required reading dependency for every syntax/impl skill. All code examples explicitly use edition 2024 idioms.

D-009: Skill Granularity Preserves Cognitive Depth

  • Date: 2026-05-19
  • Decision: Preserve fine-grained skill split for cognitively complex topics (ownership/borrowing/lifetimes separate, declarative-macros separate from procedural-macros, async-await separate from async-tokio implementation). Merge only where topics are mechanically related and have shared mental model.
  • Rationale: Phase 2 research finding NDST 21 explicitly recommended preserving granularity in unsafe/async/lifetimes "rather than aggressively merging". Mega-skills exceed 500-line limit (D-003) and dilute trigger-keyword matching.
  • Consequence: Refined target is 44 skills (not aggressively reduced to 28). Mergers: traits+impl-blocks (orphan rule fits with trait impl), iterators+closures (closures predominantly used in iterator chains), language-model+versions (single ecosystem-identity skill), skill-router+quality-checklist (both meta-orchestration). Pinning content lives as a deep references file in rust-syntax-async-await, not its own skill.

D-010: Refinement Mergers and Splits

  • Date: 2026-05-19
  • Decision: Apply the following refinement actions to the raw masterplan:
    • MERGE C1 rust-core-language-model + C7 rust-core-versions to rust-core-language-versions (single ecosystem identity skill)
    • MERGE S4 rust-syntax-traits + S16 rust-syntax-impl-blocks to rust-syntax-traits (orphan rule fits with trait impl, blanket impls are trait impl topic)
    • MERGE S9 rust-syntax-iterators + S10 rust-syntax-closures to rust-syntax-iterators-closures (closures predominantly used in iterator chains, shared lifetime patterns)
    • MERGE A1 rust-agents-skill-router + A4 rust-agents-quality-checklist to rust-agents-orchestrator (both meta-orchestration, share decision tables)
    • ADD rust-syntax-edition-2024 (per D-008)
    • ENHANCE S11 rust-syntax-smart-pointers content scope to include Pin/Unpin overview; deep pinning reference goes under rust-syntax-async-await/references/pinning.md
    • ENHANCE S6 rust-syntax-trait-objects with trait upcasting (1.86) and precise capturing in trait definitions (1.87)
    • ENHANCE S12 rust-syntax-async-await with async closures (1.85) and AFIT/RPITIT (1.75) detail
    • ENHANCE S15 rust-syntax-unsafe with strict provenance APIs (1.84), unsafe_op_in_unsafe_fn warn-by-default in 2024, 8-superpowers enumeration
    • ENHANCE I1 rust-impl-cargo-project with [lints] table and MSRV-aware resolver (1.84)
    • ENHANCE I4 rust-impl-async-tokio with JoinSet structured concurrency
    • ENHANCE I12 rust-impl-ffi-bindgen with BorrowedFd/OwnedFd and unsafe extern
  • Rationale: Phase 2 research surfaced 20 Newly Discovered Sub-Topics. Each refinement action is grounded in a specific NDST or research finding. Net effect: raw 47 to refined 44 skills.
  • Consequence: Refined skill inventory of 44 skills across 5 categories. Batch plan: 15 batches.

D-011: Batch Cadence and Worker Respawn

  • Date: 2026-05-19
  • Decision: Phase 5 runs via tmux-orchestration with 3 skill-builder workers. Workers respawn between batches (kill-session + new spawn) for guaranteed clean context per batch.
  • Rationale: BOOTSTRAP-RUNBOOK L-007 (Tailwind 2026-05-19): claude REPL exits silently when token-budget exhausted (~5 skills per worker triggers limit). Respawn pattern is the proven mitigation; the stay idle in REPL mitigation is fragile.
  • Consequence: Per batch boundary, orchestrator runs tmux kill-session -t worker-N and re-spawns from VS Code task. State preservation via tmo task system (state/messages.jsonl) survives respawn.

D-013: In-Process Agent Dispatch instead of tmux-orchestration

  • Date: 2026-05-19
  • Decision: Phase 5 executes via in-process Agent tool calls (3-parallel per batch, opus model), not via tmux-orchestration worker sessions.
  • Rationale: Pre-flight check showed tmux + tmo installed but no worker REPLs running and no state/ directory initialized. Spawning detached claude REPLs in background tmux without a TTY is fragile. The Agent tool provides equivalent guarantees: 3 parallel skill-creations per batch, fresh subagent context per skill (eliminates L-007 context overflow risk that motivated D-011 worker respawn), and quality-gate validation by main session. This is the proven path in ERPNext (28 skills) and Tauri 2 (27 skills) packages.
  • Consequence: D-011 worker respawn is moot (each Agent call is already a fresh subagent context). Per-batch loop: 3 parallel Agent calls in single message, validation after, commit batch.

D-014: Phase 4 Topic-Research Skipped (Docker L-001 Pattern)

  • Date: 2026-05-19
  • Decision: Skip per-skill Phase 4 topic-research. Worker Agents read vooronderzoek-rust.md directly, augmented with WebFetch against SOURCES.md as needed.
  • Rationale: Docker L-001 skip-criteria: when vooronderzoek covers >40 doc-pages well-supported, dedicated topic-research adds marginal value. vooronderzoek-rust.md is 7587 words / 20 sections / 50+ WebFetch-verified sources, with every major topic given 300+ words. Doubling agent count for marginal depth gains is not justified.
  • Consequence: Skill-creation agents receive masterplan-prompt + vooronderzoek-rust.md section references + SOURCES.md URLs. Agents WebFetch any specific API surface they need beyond what vooronderzoek captured.

D-012: Phase 5 Stop After Completion

  • Date: 2026-05-19
  • Decision: After all batches complete + Phase 5 verify scripts green, STOP. Do not auto-proceed to Phase 6 (validation) or Phase 7 (publication). Wait for explicit user-go.
  • Rationale: User instruction this session. Phase 6/7 includes irreversible actions (GitHub release, social preview upload, repo settings) that warrant explicit confirmation. Local commits stay; no pushes happen during Phase 2-5 to preserve user's final-review prerogative.
  • Consequence: Final session deliverable is git log showing 15+ batch commits + Phase 1/2/3 commits, all local. User reviews diff, decides merge/push/Phase 6+7 path.