feat(framework): superpowers enforcement, typecheck hook, file-ownership rules
- Add PostToolUse typecheck hook (typecheck-hook.sh) that runs tsc --noEmit after TS/TSX edits for immediate type error feedback - Add Superpowers Enforcement section to AGENTS.md requiring active use of skills, hooks, MCP tools, and plugins — not just passive availability - Add self-evolution captures (framework-improvement, tooling-gap, friction) - Add file-ownership/partitioning rules to ORCHESTRATOR.md preventing parallel worker file collisions - Add settings audit to launch.ts that validates ~/.claude/settings.json has required hooks and plugins at mosaic claude launch time - Document required Claude Code settings in RUNTIME.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -151,11 +151,68 @@ When delegating work to subagents, you MUST select the cheapest model capable of
|
||||
|
||||
**Runtime-specific syntax**: See the runtime reference for how to specify model tier when spawning subagents (e.g., Claude Code Task tool `model` parameter).
|
||||
|
||||
## Superpowers Enforcement (Hard Rule)
|
||||
|
||||
Mosaic provides capabilities beyond basic code editing: **skills**, **hooks**, **MCP tools**, and **plugins**. These are not optional extras — they are force multipliers that agents MUST actively use when applicable. Under-utilization of superpowers is a framework violation.
|
||||
|
||||
### Skills
|
||||
|
||||
Skills are domain-specific instruction sets in `~/.config/mosaic/skills/` that encode best practices, patterns, and guardrails. They are loaded into agents via the runtime's skill mechanism (e.g., Claude Code slash commands, Pi `--skill` flag).
|
||||
|
||||
**Rules:**
|
||||
|
||||
1. Before starting implementation, scan available skills (`ls ~/.config/mosaic/skills/`) and load any that match the task domain.
|
||||
2. When a skill exists for the technology being used (e.g., `nestjs-best-practices` for NestJS work), you MUST load it.
|
||||
3. When spawning workers, include skill loading in the kickstart prompt.
|
||||
4. If you complete a task without loading a relevant available skill, that is a quality gap.
|
||||
|
||||
### Hooks
|
||||
|
||||
Hooks provide automated quality gates (lint, format, typecheck) that fire on file edits. They are configured in the runtime settings and run automatically.
|
||||
|
||||
**Rules:**
|
||||
|
||||
1. Do NOT bypass or suppress hook output. If a hook reports errors, fix them before proceeding.
|
||||
2. Hook failures are immediate feedback — treat them like failing tests.
|
||||
3. If a hook is consistently failing on valid code, report it as a framework issue rather than working around it.
|
||||
|
||||
### MCP Tools
|
||||
|
||||
MCP servers extend agent capabilities with external integrations (sequential-thinking, web search, memory, browser automation, etc.). Available MCP tools are listed at session start.
|
||||
|
||||
**Rules:**
|
||||
|
||||
1. **sequential-thinking** is REQUIRED for planning, architecture, and multi-step reasoning. Use it — do not skip structured thinking for complex decisions.
|
||||
2. **OpenBrain** (`capture`, `search`, `recent`) is the cross-agent memory layer. Capture discoveries and search for prior context at session start.
|
||||
3. When a task involves web research, browser testing, or external data, use the available MCP tools (web-search, chrome-devtools, web-reader) rather than asking the user to look things up.
|
||||
4. Check available MCP tools at session start and use them proactively throughout the session.
|
||||
|
||||
### Plugins (Runtime-Specific)
|
||||
|
||||
Runtime plugins (e.g., Claude Code's `feature-dev`, `pr-review-toolkit`, `code-review`) provide specialized agent capabilities like code review, architecture analysis, and test coverage analysis.
|
||||
|
||||
**Rules:**
|
||||
|
||||
1. After completing a significant code change, use code review plugins proactively — do not wait for the user to ask.
|
||||
2. Before creating a PR, use PR review plugins to catch issues early.
|
||||
3. When designing architecture, use planning/architecture plugins for structured analysis.
|
||||
|
||||
### Self-Evolution
|
||||
|
||||
The Mosaic framework should improve over time based on usage patterns:
|
||||
|
||||
1. When you discover a recurring pattern that should be codified, capture it to OpenBrain with `type: "framework-improvement"`.
|
||||
2. When a hook, skill, or tool is missing for a common task, capture the gap to OpenBrain with `type: "tooling-gap"`.
|
||||
3. When a framework rule causes friction without adding value, capture the observation to OpenBrain with `type: "framework-friction"`.
|
||||
|
||||
These captures feed the framework's continuous improvement cycle.
|
||||
|
||||
## Skills Policy
|
||||
|
||||
- Use only the minimum required skills for the active task.
|
||||
- Load skills that match the active task domain before starting implementation.
|
||||
- Do not load unrelated skills.
|
||||
- Follow skill trigger rules from the active runtime instruction layer.
|
||||
- Actively check `~/.config/mosaic/skills/` for applicable skills rather than passively waiting for them to be mentioned.
|
||||
|
||||
## Session Closure Requirement
|
||||
|
||||
|
||||
@@ -102,3 +102,30 @@ claude mcp add --scope user <name> -- npx -y <package>
|
||||
`--scope local` = default, local-only (not committed).
|
||||
|
||||
Do NOT add `mcpServers` to `~/.claude/settings.json` — that key is ignored for MCP loading.
|
||||
|
||||
## Required Claude Code Settings (Enforced by Launcher)
|
||||
|
||||
The `mosaic claude` launcher validates that `~/.claude/settings.json` contains the required Mosaic configuration. Missing or outdated settings trigger a warning at launch.
|
||||
|
||||
**Required hooks:**
|
||||
|
||||
| Event | Matcher | Script | Purpose |
|
||||
| ----------- | ------------------------ | ------------------------- | ---------------------------------------------- |
|
||||
| PreToolUse | `Write\|Edit\|MultiEdit` | `prevent-memory-write.sh` | Block writes to `~/.claude/projects/*/memory/` |
|
||||
| PostToolUse | `Edit\|MultiEdit\|Write` | `qa-hook-stdin.sh` | QA report generation after code edits |
|
||||
| PostToolUse | `Edit\|MultiEdit\|Write` | `typecheck-hook.sh` | Inline TypeScript type checking |
|
||||
|
||||
**Required plugins:**
|
||||
|
||||
| Plugin | Purpose |
|
||||
| ------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `feature-dev` | Subagent architecture: code-reviewer, code-architect, code-explorer |
|
||||
| `pr-review-toolkit` | PR review: code-simplifier, comment-analyzer, test-analyzer, silent-failure-hunter, type-design-analyzer |
|
||||
| `code-review` | Standalone code review capabilities |
|
||||
|
||||
**Required settings:**
|
||||
|
||||
- `enableAllMcpTools: true` — Allow all configured MCP tools without per-tool approval
|
||||
- `model: "opus"` — Default to opus for orchestrator-level sessions (workers use tiered models via Task tool)
|
||||
|
||||
If `mosaic claude` detects missing hooks or plugins, it will print a warning with the exact settings to add. The session will still launch — enforcement is advisory, not blocking — but agents operating without these settings are running degraded.
|
||||
|
||||
@@ -23,6 +23,16 @@
|
||||
"timeout": 60
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "~/.config/mosaic/tools/qa/typecheck-hook.sh",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
63
packages/mosaic/framework/tools/qa/typecheck-hook.sh
Executable file
63
packages/mosaic/framework/tools/qa/typecheck-hook.sh
Executable file
@@ -0,0 +1,63 @@
|
||||
#!/bin/bash
|
||||
# Lightweight PostToolUse typecheck hook for TypeScript files.
|
||||
# Runs tsc --noEmit on the nearest tsconfig after TS/TSX edits.
|
||||
# Returns non-zero with diagnostic output so the agent sees type errors immediately.
|
||||
# Location: ~/.config/mosaic/tools/qa/typecheck-hook.sh
|
||||
|
||||
set -eo pipefail
|
||||
|
||||
# Read JSON from stdin (Claude Code PostToolUse payload)
|
||||
JSON_INPUT=$(cat)
|
||||
|
||||
# Extract file path
|
||||
if command -v jq &>/dev/null; then
|
||||
FILE_PATH=$(echo "$JSON_INPUT" | jq -r '.tool_input.file_path // .tool_response.filePath // .file_path // empty' 2>/dev/null || echo "")
|
||||
else
|
||||
FILE_PATH=$(echo "$JSON_INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([^"]*\)"$/\1/' | head -1)
|
||||
fi
|
||||
|
||||
# Only check TypeScript files
|
||||
if ! [[ "$FILE_PATH" =~ \.(ts|tsx)$ ]]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Must be a real file
|
||||
if [ ! -f "$FILE_PATH" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Find nearest tsconfig.json by walking up from the file
|
||||
DIR=$(dirname "$FILE_PATH")
|
||||
TSCONFIG=""
|
||||
while [ "$DIR" != "/" ] && [ "$DIR" != "." ]; do
|
||||
if [ -f "$DIR/tsconfig.json" ]; then
|
||||
TSCONFIG="$DIR/tsconfig.json"
|
||||
break
|
||||
fi
|
||||
DIR=$(dirname "$DIR")
|
||||
done
|
||||
|
||||
if [ -z "$TSCONFIG" ]; then
|
||||
# No tsconfig found — skip silently
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Run tsc --noEmit from the tsconfig directory
|
||||
# Use --pretty for readable output, limit to 10 errors to keep output short
|
||||
TSCONFIG_DIR=$(dirname "$TSCONFIG")
|
||||
cd "$TSCONFIG_DIR"
|
||||
|
||||
# Run typecheck — capture output and exit code
|
||||
OUTPUT=$(npx tsc --noEmit --pretty --maxNodeModuleJsDepth 0 2>&1) || STATUS=$?
|
||||
|
||||
if [ "${STATUS:-0}" -ne 0 ]; then
|
||||
# Filter output to only show errors related to the edited file (if possible)
|
||||
BASENAME=$(basename "$FILE_PATH")
|
||||
RELEVANT=$(echo "$OUTPUT" | grep -A2 "$BASENAME" 2>/dev/null || echo "$OUTPUT" | head -20)
|
||||
|
||||
echo "TypeScript type errors detected after editing $FILE_PATH:"
|
||||
echo "$RELEVANT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
exit 0
|
||||
Reference in New Issue
Block a user