Plan — SubQ Utility Plugin

Phase 1: Scaffold

Plugin manifest, CLI-routed hooks, bash wrapper for SubQ detection, explicit --event flags, multi-provider repo structure. Three sub-phases shipped across 6 commits.

SHIPPED

Phase 1 / 1.5 / 1.75

Replaced bun-invoked TypeScript with CLI-routed shell commands. The plugin became a pure declaration shell—zero executable code, zero runtime dependencies.

plugin.json hooks.json bash wrapper --event flags providers/

.claude-plugin/ plugin.json — Claude plugin manifest

hooks/ hooks.json — 4 events → subq hooks --provider claude

skills/ 6 subdirectories (Phase 4, generated)

providers/codex/ Codex CLI hooks and skills (generated)

providers/gemini/ Gemini CLI hooks and skills (generated)

README.md FAQ.md · LICENSE · .gitignore

10c4cf0 — Phase 1 scaffold 5943671 — Fix plugin.json 358fdd4 — Phase 1.5 CLI-route 6515176 — Cross-provider docs f95cf23 — FAQ f8063a2 — Phase 1.75 --event flags

Phase 2: Hook Ingestion

Monorepo packages for normalization, handler logic, and envelope contracts. CLI thin forwarder reads stdin, wraps in hook envelope, forwards to local RPC server.

BUILDING

packages/hooks + packages/contracts

Server delegates to packages/hooks for provider-specific normalization and handling. packages/contracts defines hook envelope types, decision types, and provider identity.

normalize handle envelope decisions

packages/hooks/ index.ts · normalize.ts · providers/{claude,codex,subq}.ts

packages/contracts/ hooks.ts · observations.ts

packages/store/ observations.ts — SQLite repository

packages/providers/ Session + hook parsers for Claude, Codex, SubQ PR #161

packages/actions/ Action contract + subq.session-storage PR #162

apps/cli/ src/commands/hooks.ts — thin forwarder

apps/server/ src/hooks.ts — RPC handler

PR #161 — packages/providers (merged) PR #162 — packages/actions (open)

Noise filtering for PreCompact, structured handoff extraction for Stop, and session-end observation recording. The intelligence layer that makes compaction lossless. Deferred post-launch—context-pack optimization is the current priority.

DEFERRED

Noise Filter → Handoff → Record

PreCompact returns a blocking replace decision with structured context. Stop extracts handoff from transcript. Both record observations in SQLite. Postponed to focus on context-pack optimization for launch.

Noise Filter PreCompact strips tool-call noise, preserves critical context—decisions, blockers, architectural choices—before lossy compaction.

Handoff Extract Stop event parses the conversation transcript via packages/providers Claude parser to extract structured handoff YAML.

Observe & Record Both events record observations in packages/store SQLite repository. Session-end observations enable cross-session continuity.

Phase 4: Skill Generator

Canonical SkillDefinition TypeScript objects in the SubQ CLI monorepo. A generator emits provider-specific SKILL.md files at build time.

BUILDING

Definitions & Generator

6 canonical skill definitions wired into loadAllSkills(). Generator runs as subq skills generate --provider claude|codex|gemini|all.

search context-pack spec review audit bench

1. canonical Read SkillDefinition objects from apps/cli/src/skills/definitions/

2. override Apply providerOverrides for target provider

3. emit Write provider-specific SKILL.md to plugin skills/ directory

id: Unique skill identifier, e.g. "subq-search".
title: Human-readable name shown in skill listings.
description: ~100 tokens loaded at session start (progressive disclosure).
trigger: When the skill fires: "User or auto" vs "User-invoked".
body: Full instructions loaded on invocation, not at startup.
subqCommand: The SubQ CLI command this skill delegates to.
providerOverrides: Optional per-provider customization for Claude, Codex, or Gemini.

PR #164 — Skill definitions (merged)

Phase 5: Integration Tests

End-to-end testing: hook envelope → server → decision → provider-native stdout. Degradation behavior. Cross-provider parity. README finalization.

PLANNED

E2E Validation

Verify the full hook lifecycle for each event and provider combination. Test degradation when the server is unreachable and when SubQ is not initialized.

Event

Claude

Codex

Scenario

SessionStart

Test

Envelope → replace decision → additionalContext

Stop

Test

Envelope → observe decision → {}

PreCompact

Test

N/A

Blocking → structured handoff → additionalContext

StopFailure

Test

N/A

429/503 detection → advisory → observe

Degradation

Test

Server unreachable → timeout → passthrough

Phase 6: Setup & Doctor

subq setup --claude|--codex|--gemini wires hooks, generates skills, and bootstraps guidance files. subq doctor verifies installation health across all providers.

PLANNED

Provider Adapters & Verification

Thin provider adapters handle install/verify/uninstall recipes. Core orchestrator handles detection, UX, state, and verification.

Claude Code: ✓ plugin installed, ✓ hooks firing, ✓ 6 skills discovered

Codex CLI: ✓ hooks.json merged, ✗ skills not found (run subq setup --codex)

Gemini CLI: — not detected

id: "claude" | "codex" | "gemini"
detect(): Is this provider’s CLI installed and in PATH?
install(): Wire up hooks + skills + guidance for this provider.
verify(): Are hooks firing? Skills discoverable? CLI reachable?
uninstall(): Remove all SubQ integration for this provider.
generateSkills(): Emit provider-specific SKILL.md files from canonical definitions.

Phase 7: Daemon & Desktop

macOS app for running the conversation daemon, collecting agent traces, displaying analytics, and handling skill approval notifications. Preferred over a pure Linux daemon for native notification support.

PLANNED

macOS App & Daemon

Native Mac app runs a background daemon that collects conversations and agent traces when sessions end. Displays analytics dashboard and triggers skill refresh approvals via native notifications or a local web UI.

daemon analytics notifications skill approval

Conversation Daemon Background process collects agent traces by plugging into the hook system, triggered when a session ends. Traces are saved to a local directory accessible by the analysis pipeline.

Analytics Dashboard Tokens saved, skills created, sessions analyzed. Surfaces the value SubQ provides across coding sessions.

Skill Notifications When agent trace analysis suggests new or updated skills, the app notifies the user and asks for approval. Native macOS notifications or a local web page served just in time.

Dependencies

Runtime requirements and branch strategy for the monorepo work.

Runtime subq CLI installed and in PATH—the only runtime requirement for end users. No bun, no node_modules.

Branch rc/plugin-system branch in subq-code for monorepo work. Contains server infrastructure and package foundations.

Server SubQ Code Next local RPC server (apps/server)—Greg’s architecture foundation for hook handling, actions, and crons.

Packages packages/contracts, packages/store, packages/hooks—new packages from SubQ Code Next architecture.

Verification

Nine-point checklist. Each item must pass before the plugin is considered complete.

V-1

Plugin Structure

claude plugin add subquadratic-ai/subq-utility-plugin succeeds, hooks.json discovered automatically.

Shipped

V-2

Hook Invocation

Each event fires subq hooks --provider claude --event <event>, reads stdin, returns stdout JSON.

Building

V-3

SessionStart

Codebase context injected as additionalContext in the hook response.

Building

V-4

Stop

Handoff YAML written, RPC server terminated cleanly.

Building

V-5

StopFailure

Rate-limit advisory displayed, additionalContext suggests SubQ as alternative.

Planned

V-6

Fallback

If RPC server is unreachable, hooks fall back to direct subq code subprocess.

Planned

V-7

Skills

Each /subq-* skill listed and invocable from the host AI’s skill menu.

Building

V-8

No Bun

Verify hooks work with only subq in PATH. No bun, no node_modules, no runtime dependencies.

Shipped

V-9

Daemon

macOS app launches daemon, collects traces on session end, surfaces analytics, and delivers skill approval notifications.

Planned