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

Raw Blame History

name	description	layer	cc_feature	source	concept	last_verified	ngram_overlap_score	review_status
subagents-pattern	When subagents earn their cost and how to compose them — swarm, pipeline, and guard patterns.	pattern	subagents	https://docs.claude.com/en/docs/claude-code/sub-agents	subagent-composition	2026-04-18	null	approved

Subagents — Pattern

When to delegate

Delegation earns its cost when at least one of these holds:

Context isolation — the subtask needs to read 50+ files or run many greps, and the parent conversation does not need the raw results. Summaries survive; raw output stays in the subagent.
Parallelism — multiple independent subtasks can run at once, compressing wall-clock time.
Specialization — the subagent has a tailored system prompt that changes its behavior meaningfully (e.g., adversarial reviewer).
Tool scoping — the subtask should run with fewer tools than the parent (principle of least privilege).

If none of these apply, inline the work. A subagent call costs a full model turn; do not pay it for routine reads.

Common patterns

Pattern A: Exploration swarm

Parent launches 4-8 specialized subagents in parallel, each with a narrow brief (architecture, dependencies, risks, tests, ...). Each returns a summary. Parent synthesizes.

Used by: ultraplan-local Phase 2 exploration.

Cost shape: N × Sonnet call, wall-clock ≈ slowest subagent.

Pattern B: Adversarial review

Parent writes an artifact (plan, design note). Launches a reviewer subagent with a system prompt that demands problems, never praise. Reviewer returns findings. Parent revises.

Used by: plan-critic, scope-guardian, architecture-critic.

Cost shape: 1 × Sonnet call per review pass.

Pattern C: Background orchestrator

Parent kicks off a long-running orchestrator subagent with run_in_background: true, then continues. Orchestrator runs its own subagents, synthesizes, writes output to disk. Parent is notified on completion.

Used by: planning-orchestrator, research-orchestrator.

Cost shape: 1 × Opus orchestrator + N × Sonnet workers. Overlaps with other user work.

Pattern D: Guard subagent

A hook delegates an "is this safe?" question to a subagent when the answer needs judgment. The subagent returns a verdict; the hook enforces it.

Cost shape: 1 × Sonnet call per hook invocation. Use sparingly — adds seconds of latency per tool call.

Pitfalls

Delegate-understanding anti-pattern — do not write "based on your findings, fix the bug" to a subagent. The subagent is not inside your head; it cannot see what you synthesized. Pass concrete context.
Prompt-on-top-of-prompt drift — if the parent's prompt to a subagent contradicts the subagent's own system prompt, the subagent follows its system prompt. Do not try to re-style a reviewer into a cheerleader by prompting harder.
Silent failure — a subagent that returns "done" without evidence may have done nothing. Trust but verify: check for the concrete artifacts the subagent was asked to produce.
Orchestration explosion — a three-level-deep subagent tree costs exponentially. Flatten wherever the inner levels don't need their own context isolation.
Token budget fights — parent and all active subagents share the harness's overall budget. Cap subagent output length ("report in under 200 words") when the summary is what matters.

Composition with other features

Subagents + hooks: hooks fire during subagent tool calls too. A subagent with only Read tools is already constrained; hooks add defense in depth.
Subagents + worktrees: an isolation: "worktree" subagent works in an isolated copy of the repo, so its writes never clash with the parent's writes.
Subagents + background: run heavy exploration in background while the user continues other work.

3.8 KiB Raw Blame History Unescape Escape