Skip to content

architecture.md

Latest commit

 

History

History
43 lines (30 loc) · 3.03 KB

architecture.md

File metadata and controls

43 lines (30 loc) · 3.03 KB

Architecture Deep Dive

This document covers advanced architectural details. For general usage, see README.md.

Agentic Control Stack

This plugin implements a complete agentic control loop architecture. Each layer maps to specific plugin components:

Layer sd0x-dev-flow Implementation Key Files
Feedforward Gate /precommit hooks, pre-edit-guard.sh, lint:fix hooks/pre-edit-guard.sh, commands/precommit.md
Feedback Loop (MAPE) /verify → /codex-review-fast → fix → re-review rules/auto-loop.md
Hierarchical Loops Inner (hooks 30s) → Mid (review+precommit 10min) → Outer (PR review + rules) hooks/ → commands/ → rules/
Sensors audit.js, analyze.js, risk-analyze.js, skill-lint.js skills/*/scripts/*.js
Effectors Edit/Write tools, allowed-tools whitelist, diff budget commands/*.md frontmatter
Human Governance rules/ = Knowledge curation, ⚠️ Need Human sentinel = circuit breaker rules/auto-loop.md

Control Loop Pathology & Mitigation

Failure Mode Symptom Mitigation in sd0x-dev-flow
Oscillation Fix test1 breaks test2, revert loops 3-round limit on same issue → report blocker, request human
Local Minimum Tests pass via hacks (deleted assertions) Independent Codex review (never feed conclusions) as second sensor
Divergence Diff grows unbounded, unrelated changes allowed-tools whitelist limits effectors, git rules forbid direct push to main

Command Template Sandbox Rules

When writing ! backtick context checks in command templates, be aware of Claude Code sandbox restrictions:

Problem Solution
ls/find on home-dir paths blocked in ! context checks Use bash -c 'test -f "$HOME/..." && echo ok || echo missing' 2>/dev/null || echo "unknown (sandbox)"
allowed-tools pattern must match ! check commands If allowed-tools: Bash(bash:*), wrap all ! checks in bash -c '...'
${CLAUDE_PLUGIN_ROOT} unavailable in command .md Cannot narrow allowed-tools to specific script paths; keep Bash(bash:*) until #9354 resolved

Script Fallback Pattern

Verification commands (/precommit, /verify, /dep-audit) use a Try → Fallback pattern:

  1. Try: If a runner script exists in the project root (scripts/precommit-runner.js, etc.), use it for fast, deterministic execution.
  2. Fallback: If no script is found, Claude detects the project ecosystem (Node.js, Python, Rust, Go, Java) and runs the appropriate commands directly.

The fallback works out of the box with no setup required. Runner scripts are bundled in this plugin repo but cannot be auto-resolved from plugin commands due to a Claude Code limitation (${CLAUDE_PLUGIN_ROOT} is unavailable in command markdown).