mosaicstack/stack

Fork 0

Files

Jason Woltje 319e21ddc0

ci/woodpecker/push/ci Pipeline was canceled

Details

ci/woodpecker/pr/ci Pipeline was canceled

Details

feat(framework): P3 — extract Constitution (L0) + gut AGENTS dispatcher

Splits the 155-line thin-core AGENTS.md into:
- defaults/CONSTITUTION.md (L0): gates + integrity + escalation + block-vs-done
  + mode + two-axis precedence + hooks-are-the-gate + framework-PR firewall +
  structured-reasoning capability + tier-aware self-load. Capability-verb authored.
- defaults/AGENTS.md gutted to an ~80-line load-order dispatcher + guide table
  (kills the false "already in context, do not re-read" line).
- constitution/LAYER-MODEL.md: source-only governance spec (layers + precedence).

Non-regression wiring (fresh-install functional; upgrade-safety is P4):
- launch.ts injects CONSTITUTION.md before AGENTS.md (tolerant of un-reseeded installs)
- install.sh + file-adapter.ts seed CONSTITUTION.md (+ test fixture updated)

Runtime adapters: capability-verb the sequential-thinking binding; claude/codex/
opencode restate the REQUIRED hard-stop, pi binds to native thinking (gate=false)
— restores the force the adversarial review flagged as weakened.

Gate hardening (dual-engine review): identity denylist now covers examples/
(closes the Codex open-source gap), self-test-first, *.json in scope, ci.yml
typecheck depends on sanitization (fail-fast), L0 line-count ceiling (<=120).

Adversarial gate-preservation review: every original rule traced to L0, the
dispatcher, or a routed guide — nothing lost.

Refs #542, closes #574

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-20 21:55:18 -05:00

3.0 KiB

Raw Blame History

Claude Runtime Reference

Claude-runtime behavior only. Global rules win if anything here conflicts.

Required Actions

Follow the Session Start load order in ~/.config/mosaic/AGENTS.md.
Runtime config lives in ~/.claude/settings.json (hooks, model, plugins, permissions) and ~/.claude/hooks-config.json.
Structured reasoning (Constitution) binds to the sequential-thinking MCP on this harness; it is REQUIRED — if unavailable, report the failure and stop planning-intensive execution.
First response MUST declare mode per the global contract.
Git wrappers first for issue/PR/milestone ops; runtime-default confirmation prompts do NOT override Mosaic hard gates (push/merge/issue-close without routine confirmation).

Subagent Model Selection (Claude Code syntax)

The Task tool takes model: "haiku" | "sonnet" | "opus". You MUST set it per the tier rule in AGENTS.md — omitting it defaults to the parent (usually opus) and wastes budget.

Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers")
Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review src/auth/ changes")
Task(subagent_type="Plan", model="opus", prompt="Design the multi-tenant isolation strategy")

Memory Policy (Hard Gate)

OpenBrain is the primary cross-agent memory layer — capture learnings/gotchas/decisions there (capture MCP tool or REST). ~/.claude/projects/*/memory/MEMORY.md is write-blocked by the prevent-memory-write.sh PreToolUse hook (the rule alone proved insufficient — the hook is the hard gate). At session start, search(topic) + recent() to load prior context. Full protocol: ~/.config/mosaic/guides/MEMORY.md.

Quick placement: discoveries/decisions → OpenBrain; active task state → docs/TASKS.md or docs/scratchpads/; Mosaic framework notes → ~/.config/mosaic/memory/.

MCP Configuration

MCP servers are configured in ~/.claude.json (key mcpServers) — NOT ~/.claude/settings.json, where that key is ignored. settings.json controls hooks/model/plugins/permissions.

claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
claude mcp add --scope user <name> -- npx -y <package>   # stdio

--scope user → ~/.claude.json (global); project → .claude/settings.json; local (default) → not committed.

Required Settings (launcher-audited, advisory)

mosaic claude warns if ~/.claude/settings.json is missing these (session still launches):

Hooks — PreToolUse prevent-memory-write.sh (Write|Edit|MultiEdit); PostToolUse qa-hook-stdin.sh + typecheck-hook.sh (Edit|MultiEdit|Write).
Plugins — feature-dev, pr-review-toolkit, code-review.
Settings — enableAllMcpTools: true; model: "opus" (orchestrator default; workers use tiered models via the Task model param).

Note: PostToolUse hook plain stdout on exit 0 goes to the debug log, not model context — only hookSpecificOutput.additionalContext (or exit-2 stderr) enters context.

3.0 KiB Raw Blame History