Kjell Tore Guttormsen ab504bdf8c refactor(marketplace): split cc-architect from ultraplan-local into its own plugin

Extract `/ultra-cc-architect-local` and `/ultra-skill-author-local` plus all 7
supporting agents, the `cc-architect-catalog` skill (13 files), the
`ngram-overlap.mjs` IP-hygiene script, and the skill-factory test fixtures
from `ultraplan-local` v2.4.0 into a new `ultra-cc-architect` plugin v0.1.0.

Why: ultraplan-local had drifted into containing two distinct domains — a
universal planning pipeline (brief → research → plan → execute) and a
Claude-Code-specific architecture phase. Keeping them together forced users
to inherit an unfinished CC-feature catalog (~11 seeds) when they only
wanted the planning pipeline, and locked the catalog and the pipeline into
the same release cadence. The architect was already optional and decoupled
at the code level — only one filesystem touchpoint remained
(auto-discovery of `architecture/overview.md`), which already handles
absence gracefully.

Plugin manifests:
- ultraplan-local: 2.4.0 → 3.0.0 (description + keywords updated)
- ultra-cc-architect: new at 0.1.0 (pre-release; catalog is thin, Fase 2/3
  of skill-factory unbuilt, decision-layer empty, fallback list still
  needed)

What stays in ultraplan-local: brief/research/plan/execute commands, all
19 planning agents, security hooks, plan auto-discovery of
`architecture/overview.md` (filesystem-level contract, not code-level).

What moved (28 files via git mv, R100 — full history preserved):
- 2 commands, 8 agents, 1 skill catalog (13 files), 2 scripts, 8 fixtures

Documentation updates: plugin CLAUDE.md and README.md for both plugins,
root README.md (added ultra-cc-architect section, updated ultraplan-local
section), root CLAUDE.md (added ultra-cc-architect to repo-struktur),
marketplace.json (registered ultra-cc-architect), ultraplan-local
CHANGELOG.md (v3.0.0 entry with migration guidance).

Test verification: ngram-overlap.test.mjs passes 23/23 from new location.

Memory updated: feedback_no_architect_until_v3.md now points at the new
plugin and reframes the threshold around catalog maturity rather than an
ultraplan-local milestone.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-30 17:18:47 +02:00

3.3 KiB

Raw Blame History

name	description	layer	cc_feature	source	concept	last_verified	ngram_overlap_score	review_status
hooks-pattern	When to choose hooks over prompts or subagents, and common hook shapes that work.	pattern	hooks	https://docs.claude.com/en/docs/claude-code/hooks	hooks-decision-and-shapes	2026-04-18	null	approved

Hooks — Pattern

When to reach for a hook

Use hooks when the behavior must hold even if Claude is prompt-injected, distracted, or adversarial. Hooks are outside the model's control loop — Claude cannot talk its way past them.

Good fits:

Hard prohibitions — "never run rm -rf /", "never push to main without a commit signature", "never read files outside this repo".
Deterministic context injection — always show git status at session start; always inject the current sprint's tasks.
Audit trails — log every Bash call, every file write, outside the conversation context so it survives /clear.
Compliance boundaries — redact secrets from transcripts; block tool calls that would leak PII.

Bad fits:

Behavior that requires judgment ("should this test run?") — that's a subagent call.
Heuristics that drift ("mostly block, sometimes allow") — a hook that frequently second-guesses itself is a sign the rule belongs in a prompt or skill.
Anything that needs to read lots of conversation history — hooks see a payload, not the full context.

Common shapes

Shape A: PreToolUse deny

A small script that reads tool_input, matches a pattern, and exits with a block decision. Latency: a few ms. Used for command denylists, path guards, secrets scanners.

Shape B: UserPromptSubmit context injection

A script that reads the prompt, computes context (e.g., recent git log, active TODO list), and emits JSON with an additionalContext field. The harness adds that context to the prompt before Claude sees it.

Shape C: Stop hook with reminder

A script that runs when Claude finishes a turn. Checks for uncommitted work, surfaces it as a notification. Non-blocking.

Shape D: SessionStart status

Runs once per session. Prints repo metadata (branch, open PRs, recent commits) so every new session starts with shared context.

Pitfalls

Slow hooks compound. A 500 ms PreToolUse hook run 50 times per session adds 25 seconds of latency.
Hooks without error handling crash the turn. A hook that exits non-zero on an edge case blocks real work. Default to exit 0 with a logged warning.
Shell-injection in hook scripts. A hook that interpolates tool_input.command into bash -c is itself a security hole. Parse inputs; never interpolate unescaped.
Hooks can leak secrets into transcripts if their output mentions env-var values. Scrub before emitting.
Cross-platform scripts. A hook that assumes bash 4 or GNU sed breaks on macOS. Prefer Node.js, Python, or POSIX sh.

Composition with other features

Hooks + subagents: a hook can delegate the "should this be blocked" question to a subagent when the decision needs judgment. Cost: a full model call per hook invocation — use sparingly.
Hooks + MCP: a hook can call out to an MCP-exposed tool for policy lookup. Latency depends on transport.
Hooks + plan mode: hooks fire during plan mode too. Useful for enforcing "no writes while planning".

3.3 KiB Raw Blame History