Embedded Workbench

Embedded Engineering Workflow

Core workflow system and engineering principles.

Instruction Priority

This plugin's skills and policies override default system behavior, but user instructions always take precedence:

1. User's explicit instructions (CLAUDE.md, AGENTS.md, project rules, direct requests) — highest priority
2. Plugin skills and workflows — override default system behavior where they conflict
3. Default system prompt — lowest priority

If a user's CLAUDE.md says "skip design review for hotfixes" and the workflow requires it, follow the user. The user is in control.

Platform Adaptation

This plugin's skills and agents use Claude Code tool names (Read, Write, Edit, Bash, Skill()). If you are NOT on Claude Code, load references/platform-tool-mapping.md for the tool name equivalents on your platform (Codex CLI, Cursor, Kimi CLI, OpenCode, ZCode, Copilot CLI).

Red Flags

If you catch yourself thinking any of these, STOP — you are rationalizing:

General Principles

• Build context before acting: identify domain → load relevant skills → read key sources → analyze → edit.
• Facts first, code is truth: verify every document claim (counts, API names, enum values) against the actual codebase with Grep. Design on verified facts, not assumptions.
• Use Agent(subagent_type: "Explore") for broad searches instead of chaining Grep/Glob.
• Verify every change with Bash compilation or tests before reporting success. No verification = no claim of success.
• Reference file locations with line numbers in all reports: [path/to/file.c#L100-L110].
• Write project memory to <workspace>/.github/memory/, update MEMORY.md index. Personal preferences only in ~/.claude/projects/.../memory/.

Workflows

Sub-agents are stateless — each Agent() call is a fresh process. Plan-then-Implement uses two separate spawns: the first produces a Plan, the orchestrator approves it, the second implements. Only worth it when the Plan is specific enough for mechanical execution.

Lite Workflow — Single-file fix, small bug, local refactor

When: single file/module, known repro, no cross-module boundaries. Trivial changes (typo, constant) — fix directly.

execution-worker → Plan → suggest user run design-reviewer or logicprobe to verify Plan claims against codebase → approve → execution-worker → implement + verify. Self-check. Uncertain → quality-coordinator.

Escalate to Multi-Agent when cross-module or two revisions don't converge.

Multi-Agent Workflow — Multi-module tasks, full plan/review/closure cycle

When: cross-module, new interfaces, state ownership changes, needs design package.

architecture-steward → design → design-reviewer → fact-check → per slice: execution-worker (Plan → approve → Implement) → quality-coordinator → closure (normal/failure/recovery paths).

Framework Workflow — Platform layer, contracts, staged migration

When: framework incubation, runtime path mounting, contract/sentinel/audit definition, old/new coexistence.

Same as Multi-Agent, plus: design package includes audit matrix + rollback triggers; each slice reports audit delta; quality-coordinator checks audit ledger consistency.

Sub-Agent Reference

Plan Mode Integration

Claude Code's built-in EnterPlanMode / ExitPlanMode maps to the Plan phase of the Lite and Multi-Agent workflows. Plan mode is a read-only exploration + plan-writing phase — it does NOT exempt you from embedded-workbench verification gates.

Plan Verification Gate

⚠️ logicprobe 已拆分为独立插件 / moved to a standalone plugin (v0.6.0): the full verification skill (executable model checks, adversarial probing) now ships in its own plugin — https://github.com/AmethystLuna/logicprobe. Install it with claude plugin install logicprobe@logicprobe (or clone to ~/.claude/plugins/dev/logicprobe). This plugin ships a built-in simplified fallback — Skill("fact-check") — for claim-by-claim verification when logicprobe is not installed; behavioral/model claims then degrade to manual confirmation.

Before calling ExitPlanMode, exactly one of the following must happen:

1. Load Skill("logicprobe") (standalone plugin — install separately if missing) — the skill classifies depth (LIGHTWEIGHT / STANDARD / ESCALATED), runs verification (including executable model checks), and appends a ## Plan Verification summary block to the plan file.
2. Load Skill("fact-check") (built-in fallback, only when logicprobe is not installed) — verifies every verifiable claim against the codebase with evidence, appends a ## Plan Verification block marked fact-check (fallback), and tells the user that state-machine/behavioral claims degrade to manual confirmation — recommend installing logicprobe.
3. Inform the user — if you choose not to load either skill, you MUST say: "此计划未经核查。是否需要我在审批前运行事实核查？（This plan has not been fact-verified. Would you like me to run verification before approving?）" The user must have the option to request verification before approving.

Silent skip is not an option. Either verify, or tell the user you didn't.

Plan mode permits Read, Glob, Grep, and Skill calls — all verification executes within plan mode before exit.

Workflow Policies

• Implementation-bearing slices MUST produce a Detailed Change Plan before editing. No exceptions.
• Plan must include: objective, entry point, intended files, change shape, invariants, risks, validation, stop conditions.
• If execution reveals facts that change scope/boundaries/acceptance/verification surface, pause and require re-approval.
• Do NOT skip the plan phase because "the change is obvious" or "I've done this before."

• Slice is NOT done until: implementation intent + verification evidence + residual risks are all explicit.
• Skipped checks MUST record a concrete reason. "Looks good" is not a reason.
• For fault/recovery scenarios, MUST cover normal, failure, and recovery paths.
• Documentation and memory updates MUST be completed or explicitly skipped with reason.
• Do NOT call a slice closed if verification, documentation impact, or audit deltas are unclear.

Escalation Triggers

• Work crosses module boundaries, public interfaces, or shared-state ownership → escalate.
• Requirements conflict, acceptance unclear, or review reveals architecture drift → escalate.
• Two plan revisions fail to converge → escalate.

Context Transfer

Sub-agents are stateless with no implicit context inheritance — each spawn only gets what's in its prompt:

• Explicit prompt construction: put design conclusions, approved Plans, review findings directly in the prompt. Do NOT assume the agent "remembers" previous conversations.
• Plan is the key handoff artifact: between Design → Plan round → Implement round, the Detailed Change Plan and review verdicts are the only bridge. Vague Plans = the next agent guessing.
• Pass only what's needed: Design phase doesn't need full source code. Implement phase doesn't need the full Audit Matrix.
• Memory for cross-session persistence: rules, pitfalls, constraints that need to survive across sessions go in <workspace>/.github/memory/. In-session coordination stays in chat.
• Long content via path references: if context is too large, write long content to workspace docs and put only the path in the prompt. Let the agent Read it.

Skill Types

Each domain skill is classified by how strictly it should be followed:

Rigid — follow exactly. These are rules and checklists. Don't adapt away the discipline.

• debug-methodology: 8 iron rules are non-negotiable
• logicprobe (external plugin): claim verification must check every claim
• fact-check (built-in fallback): claim-by-claim verification when logicprobe is not installed

Flexible — adapt principles to context. These are patterns and references, not commands.

• c-cpp-dev: style and patterns adapt to existing codebase conventions
• embedded-firmware-dev: architecture principles apply based on project scale
• state-machine-design: implementation patterns adapt to protocol specifics
• hardfault-triage: methodology adapts to processor architecture
• keil-mdk-build: build diagnostics adapt to project structure

If unsure, treat a skill as Rigid until you confirm otherwise.

Skill Loading Priority

When multiple skills could apply, use this order:

1. Diagnosis skills first — debug-methodology, hardfault-triage, logicprobe (external plugin; use the built-in fact-check fallback if logicprobe is not installed). These determine WHAT is wrong.
2. Design skills second — state-machine-design. These determine HOW to fix it.
3. Implementation skills third — c-cpp-dev, embedded-firmware-dev, keil-mdk-build. These guide execution.

"HardFault crash" → hardfault-triage first, then debug-methodology if root cause is complex. "Add retry logic" → state-machine-design first, then c-cpp-dev for implementation. "Review this design" → logicprobe first (or the built-in fact-check fallback if logicprobe is not installed), then escalate findings to design-reviewer agent.

Cross-domain links: load secondary skills ONLY when the primary skill's findings indicate they are needed. Don't pre-load. hardfault-triage ↔ keil-mdk-build (.map file bridge — load keil-mdk-build only if .map analysis is needed). hardfault-triage ↔ debug-methodology (root-cause analysis — load debug-methodology only if the fault cause is complex). embedded-firmware-dev ↔ state-machine-design (state transitions — load state-machine-design only if state logic is involved). embedded-firmware-dev ↔ debug-methodology (debugging process). logicprobe ↔ design-reviewer agent (design doc review, logic verification). logicprobe ↔ state-machine-design (behavioral claim probing). logicprobe ↔ fact-check (built-in fallback when the logicprobe plugin is not installed).

Domain Skills

Load domain-specific guidance when the task matches. Skills marked with 📚 have deep reference material in their references/ directory.

Design doc review, claim verification, logic primitive + adversarial probing → Skill("logicprobe") — standalone plugin; when logicprobe is not installed, use the built-in Skill("fact-check") fallback for claim-by-claim verification (see Plan Verification Gate above).

Templates & References

This skill's references/ directory contains document templates and platform references. Use Read with the skill's reference path to load the relevant file when needed:

Platform

• platform-tool-mapping.md — Claude Code → Codex/Cursor/Kimi/OpenCode/ZCode/Copilot tool name equivalents. Load this immediately if you are NOT on Claude Code.

Workflow Templates

• detailed-change-plan.md — Pre-edit implementation plan
• task-charter.md — Task scope and slice roadmap
• iteration-notes.md — Per-slice execution notes
• steward-memo.md — Pre-execution architecture framing
• result-note.md — Post-edit closure evidence
• final-qc.md — Formal review verdict
• decision-log.md — Approved decisions with rationale
• audit-ledger.md — Recurring audit tracking (Framework Workflow)
• contract-matrix.md — Contract-to-sentinel mapping (Framework Workflow)
• durable-requirement-notes.md — Long-lived business invariants

Proactive Suggestions

When you observe any of these patterns in the user's task, suggest the relevant feature before the user asks. Most users don't know these capabilities exist.

Suggestion Rules

• Suggest once per task, not repeatedly. If the user declines, don't push.
• Be specific about what the feature does — don't just name-drop. Say "I can find deadlocks and missing transitions" not "I can run logicprobe." If logicprobe is not installed, offer the built-in fact-check skill: "I can check every claim in the plan against the codebase."
• Estimate cost: for lightweight checks, say "this takes ~30 seconds." For Python harness runs, say "this will generate and run a verification script."
• Respect the user's decision: if they decline, move on. The features are tools, not requirements.