Phase Timeline
Seven phases from scaffold to full multi-provider support.
Phase Details
What each phase delivers.
Scaffold & CLI-Routed Hooks (1 / 1.5 / 1.75)
Plugin manifest, hooks.json with 4 events, bash wrapper for SubQ detection, explicit --event flags, multi-provider repo structure. Replaced bun-invoked TypeScript with CLI-routed shell commands.
Hook Ingestion
Monorepo packages: packages/hooks for normalization and handler logic, packages/contracts for envelope and decision types. Server RPC surface for receiving forwarded events.
PreCompact & Handoff
Noise filtering for PreCompact (preserve critical context, discard tool-call noise). Structured handoff extraction for Stop. Session-end observation recording. Deferred post-launch—context-pack optimization is the launch priority.
Skill Generator
Canonical SkillDefinition TypeScript objects in apps/cli/src/skills/definitions/. Generator emits provider-specific SKILL.md files: subq skills generate --provider claude|codex|gemini|all.
Integration Tests
End-to-end hook firing, skill invocation, degradation behavior, cross-provider parity. README finalization.
Setup & Doctor
subq setup --claude|--codex|--gemini wires hooks, generates skills, bootstraps guidance files. subq doctor verifies installation health across all providers.
Daemon & Desktop
macOS app for running the conversation daemon, collecting agent traces, displaying analytics (tokens saved, skills created, sessions analyzed), and handling skill approval notifications.
Architecture Evolution
Three architectural pivots. Each one stripped a layer of complexity.
Each pivot removed a dependency. v1 required Python. v2 required bun. v3 requires nothing—the plugin is pure JSON declaring shell commands.
The v3 architecture inverts the plugin's role. Instead of containing hook logic, it declares which lifecycle events trigger which subq hooks commands. All executable code lives in the SubQ CLI monorepo, shared across providers. The plugin is a wiring diagram, not a runtime.