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.2 KiB

Raw Blame History

name	description	layer	cc_feature	source	concept	last_verified	ngram_overlap_score	review_status
hooks-reference	CC hooks API — event types, payload shapes, exit codes, and where hooks run.	reference	hooks	https://docs.claude.com/en/docs/claude-code/hooks	hooks-api-surface	2026-04-18	null	approved

Hooks — Reference

Hooks are shell commands or scripts that the Claude Code harness runs in response to events. They give the harness — not Claude — the final say on whether a tool call, prompt, or session action proceeds. Claude cannot bypass a hook by prompting itself; the hook runs outside the model's control loop.

Event types

UserPromptSubmit — fires when the user sends a prompt. Runs before Claude processes it. Common use: inject extra context, reject disallowed prompts.
PreToolUse — fires before a tool call. Can deny the call. Common use: block destructive commands, require confirmation.
PostToolUse — fires after a tool call completes. Sees the result. Common use: log side effects, redact output, trigger follow-up work.
Stop — fires when the agent finishes a turn. Common use: commit reminders, session summaries.
Notification — fires when Claude wants to show the user a notification (e.g., long-running task).
SessionStart — fires when a session begins. Common use: print repo state, inject context.

Payload shape

Hooks receive a JSON payload on stdin. Common fields:

session_id — the current session identifier.
transcript_path — path to the conversation transcript.
cwd — current working directory.
tool_name (PreToolUse, PostToolUse) — which tool is running.
tool_input (PreToolUse) — the arguments to the tool.
tool_response (PostToolUse) — the tool's result.
prompt (UserPromptSubmit) — the submitted text.

Exact field availability depends on event type. Read the payload JSON rather than assuming a schema.

Exit codes and control

Hooks communicate back via exit code and stdout JSON:

Exit 0, no stdout → proceed normally.
Exit 0, stdout JSON with decision field → harness honors the decision (e.g., {"decision": "block", "reason": "..."}).
Exit non-zero → harness treats as a denial or error, depending on event and hook type.

Some hook types support structured output beyond deny/allow (e.g., adding context to the prompt). Details differ per event.

Where hooks live

Project hooks: .claude/settings.json hooks field, paths relative to project.
User hooks: ~/.claude/settings.json (global).
Plugin hooks: packaged with a plugin, activated when the plugin is enabled.

Hooks run in the harness process's shell, not in Claude's tool-use sandbox. They can spawn subprocesses, read environment variables, and touch the filesystem.

Implications for architecture

Hooks are the mechanism for deterministic policy (things that must always or never happen, regardless of what Claude decides).
Hooks are load-bearing for security: prompt-injection-resistant defenses live here, not in prompts.
Hooks add latency to every tool call they gate — keep them fast.
Hook output is part of the context window; verbose hooks burn tokens quickly.

3.2 KiB Raw Blame History