五层架构重构:skill 机读化 + 门-状态耦合 + 归属强制 + 双编排形态#2
Open
Jinchen-Yang wants to merge 4 commits into
Open
Conversation
Diagnose current skill system across five layers (execution, validation, multi-agent, file-control, user-interaction) and propose making the four weak layers structured/enforced while keeping the solid execution layer. Covers machine-readable skill frontmatter (lane/needs/reads/writes/gate/ signoff/allowed-tools), gate->state coupling, ownership enforcement, and two orchestration modes (3-machine git vs single-operator subagents) sharing one DAG and one set of gates. Includes phased migration path. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CNFvi9VAv3UgvhmqgqBiv2
…e→state, enforced ownership, dual orchestration) P1 capability metadata: add machine-readable frontmatter to all 11 skills (lane/needs/reads/writes/gate/signoff/allowed-tools); demote prose lane/needs to a frontmatter pointer line. P2 gate→state coupling: shared tools/gatelib.py; pinmux_check/power_budget/ gen_protocol gain --report writing design/gates/<gate>.yaml; generic tools/gate_report.py (e.g. compile); board.py done now verifies required gate==PASS and signoff==approved (exit 3, --force leaves a trace); tools/gate_check.py shares the same gatelib.check_spec verdict. P3 file-ownership enforcement: .github/CODEOWNERS, tools/check_ownership.py (blocks out-of-lane writes by .elec-lane), .githooks/pre-commit (ownership + pinmap/protocol contract gates), bootstrap.sh sets core.hooksPath. P4 structured sign-off: manual-gate skills now take AskUserQuestion approval then tools/signoff.py approve writing design/signoffs.yaml. P5 single-operator orchestration: new /elec-orchestrate fans out subagents in one session, sharing the same DAG/gates/signoffs as the team-mode /elec-design; mode selected via .elec-mode. selftest.sh extended to 11 steps (gate→state, --report+gate_check, ownership); all green. Docs synced: CLAUDE.md, STATUS.md, ARCHITECTURE.md (marked landed). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CNFvi9VAv3UgvhmqgqBiv2
Jinchen-Yang
changed the title
…oard robustness - gitignore: add .elec-mode (per-machine orchestration mode, must not be committed) - ownership: treat design/gates/ and design/signoffs.yaml as SHARED coordination state (any lane may write its own gate report / sign-off) — resolves the conflict where firmware-scaffold (控制 lane) must write design/gates/compile.yaml while design/ is otherwise 硬件/lead-owned. CLAUDE.md table updated to match. - pre-commit: protocol gate now BLOCKS when contracts/protocol.h/.py are out of sync with protocol.yaml (asks to git add the regenerated pair) instead of silently mutating the working tree. - board.py: status now surfaces gate/signoff requirements (consistent with list); iter_tasks() ignores non-task yaml so a stray file can't crash the board. - selftest: step 11 also asserts the gates/ shared carve-out; 11 steps green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CNFvi9VAv3UgvhmqgqBiv2
…consistency, CLI guards) Independent multi-angle review of the branch surfaced real issues; fixes: - gate freshness (校验层 hole): gate reports now store target_sha (content hash of the checked file); gatelib.check_spec rejects a PASS whose target changed since the report was written — a stale/unrelated PASS can no longer satisfy board.py done. compile gate (dir target) is exempt as before. - bootstrap.sh: pip install no longer aborts the script under set -e (offline / PEP668), so git-hook install + lane reminder always run — enforcement is not silently skipped when pip hiccups. - pre-commit protocol gate: non-destructive. gen_protocol.py gains --out-dir; the hook generates into a temp dir and compares against the STAGED blob (git show :path) instead of clobbering the working tree and relying on a side effect. Verified end-to-end (sync passes, stale .h/.py blocks). - lane consistency: interconnect/power-design/test-checklist were lane:any but write to lead/硬件-owned dirs (contracts/, design/) — a non-lead lane would be blocked by the ownership hook. Set lane:lead to match board.py owner; note that the reasoning stays model-agnostic (correctness via gates). - CLI robustness: trailing value-flags (--by/--lane/--note/--detail) no longer raise IndexError across board.py/signoff.py/gate_report.py/gate tools. selftest 11 steps green; targeted tests for stale-gate, --out-dir, and hook sync/stale all pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CNFvi9VAv3UgvhmqgqBiv2
Jinchen-Yang
marked this pull request as ready for review
June 30, 2026 01:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
这是什么
回应"这套 skill 系统分层逻辑不对、没设计好多 agent 交互层/文件层控制/执行层/用户交互层/校验层"的批评。把当前"活在散文和约定里"的四层从约定升级为结构化 + 强制(执行层本就扎实,保留)。
ARCHITECTURE.md是设计文档,P1–P5 已全部实装,sh tools/selftest.sh11 步全绿。五层落地
tools/无 LLM 确定性脚本;门脚本加--report与机读报告gatelib.py共享判据;pinmux/power/protocol --report写design/gates/<gate>.yaml;gate_report.py(如 compile);board.py done校验门 PASS+签字 approved,未过 exit 3(--force留痕);gate_check.py与 done 同源/elec-design(3 机 git 协同)+ 新增/elec-orchestrate(单人单会话子代理 fan-out);.elec-mode切换.github/CODEOWNERS+tools/check_ownership.py(按.elec-lane拦越界)+.githooks/pre-commit(归属+pinmap/protocol 契约门);bootstrap.sh设core.hooksPathtools/signoff.py approve写design/signoffs.yaml,跳门=过门的隐患被堵能力机读化(P1)
11 个
SKILL.mdfrontmatter 加lane/needs/reads/writes/gate/signoff/allowed-tools,正文 lane/needs 散文降为指向 frontmatter 的一行——兑现 CLAUDE.md "frontmatter 标 lane/needs" 的承诺,编排器可机读路由。新增/改动文件
tools/gatelib.pygate_check.pygate_report.pysignoff.pycheck_ownership.py.claude/skills/elec-orchestrate/SKILL.md、.github/CODEOWNERS、.githooks/pre-commit、design/gates/board.py(DAG 加 gate/signoff + done 校验)、pinmux_check/power_budget/gen_protocol(--report)、bootstrap.sh、selftest.sh(扩到 11 步)、11 个 SKILL.md、CLAUDE.md/STATUS.md/ARCHITECTURE.md自测
sh tools/selftest.sh→ 11 步全绿,含新增:门-状态耦合(未签被拒/签后放行)、--report+gate_check(门 PASS 但缺签字正确拒绝)、目录归属(越界拒/合规放)。决策记录
ARCHITECTURE.md§9(字段名/Agent vs Workflow/hook 接入/校验位置)🤖 Generated with Claude Code