Epic: Monorepo Package-Aware Commands

[acreeger]

Summary

Add monorepo awareness to iloom so that AI agents can declare which packages they're working on, and il commands (test, lint, compile, build, dev-server) automatically scope themselves to those packages.

Context

iloom currently treats every project as a single unit. In monorepos (pnpm workspaces, yarn/npm workspaces), this means validation runs against ALL packages even when changes are isolated, dev servers can't target specific packages, and agents have no structured way to communicate which packages are relevant.

Design

The AI agent (swarm orchestrator or issue implementer) is the intelligence layer. It explores the monorepo, reads the issue, and writes two metadata fields via MCP tools:

• packagesToRun: string[] — which package to launch a dev server for (MCP accepts singular, stored as array for future compat)
• packagesToValidate: string[] — which packages to scope test/lint/compile/build to

A new "monorepo" capability (alongside "web" and "cli") gates all monorepo behavior. It's detected during il init and stored in package.iloom.json.

A dedicated iloom-monorepo-package-detector agent runs:

• Non-swarm mode: before implementation, to set both metadata fields
• Swarm mode: after swarm completion, called by the orchestrator for final validation setup

All il commands read from metadata. Auto-fix agents receive --append-system-prompt instructing them to use il commands. A user-prompt-submit hook reminds agents to update metadata when touching new packages.

The dev server command, when both web and monorepo capabilities are present, watches the metadata file and launches once packagesToRun is set.

Acceptance Criteria

• Agents can set monorepo package metadata via MCP tools
• il test, il lint, il compile, il build scope to declared packages when metadata is set
• il dev-server launches the correct package's dev server based on metadata
• il init detects monorepos and sets the "monorepo" capability
• A dedicated detection agent runs at the right lifecycle points (before impl in non-swarm, after completion in swarm)
• Non-monorepo projects are completely unaffected
• Works with pnpm, yarn, and npm workspace package managers

Scope Boundaries

• v1 supports JavaScript/TypeScript monorepos only (pnpm + yarn/npm workspaces)
• Non-JS workspace extensions (Rust, Go, Python) are tracked separately
• Dev server supports one package at a time (reads packagesToRun[0])
• No programmatic monorepo detection utility — the AI agent handles all detection intelligence

[acreeger]

Child Issues Created

Issue	Title	Wave	Dependencies
#939	Add monorepo package metadata fields and MCP tools	1	None
#940	Add monorepo capability and init-time detection	1	None
#941	Verify wave 1: metadata schema and monorepo capability	V1	#939, #940
#942	Scope il test/lint/compile/build to monorepo packages from metadata	2	#941
#943	Create monorepo package detection agent and prompt integration	2	#941
#944	Dev server watches metadata for monorepo package target	2	#941
#945	Verify final integration and update documentation	VF	#942, #943, #944

Related: #946 — Extend monorepo support to non-JS workspaces (Rust, Go, Python) — standalone follow-up

Dependency Graph

graph TD
    939[Metadata + MCP tools]
    940[Monorepo capability + init]
    941[Verify wave 1]
    942[Scoped il commands]
    943[Detection agent + prompts]
    944[Dev server watches metadata]
    945[Verify final + docs]

    939 --> 941
    940 --> 941
    941 --> 942
    941 --> 943
    941 --> 944
    942 --> 945
    943 --> 945
    944 --> 945

    click 939 "https://github.com/iloom-ai/iloom-cli/issues/939"
    click 940 "https://github.com/iloom-ai/iloom-cli/issues/940"
    click 941 "https://github.com/iloom-ai/iloom-cli/issues/941"
    click 942 "https://github.com/iloom-ai/iloom-cli/issues/942"
    click 943 "https://github.com/iloom-ai/iloom-cli/issues/943"
    click 944 "https://github.com/iloom-ai/iloom-cli/issues/944"
    click 945 "https://github.com/iloom-ai/iloom-cli/issues/945"

Loading

[acreeger]

Architectural Decision Record

Decision: Agent-driven monorepo detection over programmatic utilities

Context: We considered three approaches for monorepo package awareness:

1. Programmatic MonorepoDetector + AffectedPackageResolver utilities
2. Package manager delegation (pnpm --filter "...[base]")
3. Agent-driven detection via MCP tools

Decision: Agent-driven (#3). The AI agent explores the monorepo, understands the issue context, and writes two metadata fields via MCP tools. All il commands read from metadata.

Rationale:

• No runtime overhead for non-monorepo projects (no detection code runs unless agent calls MCP)
• Package-manager agnostic — avoids coupling to pnpm's filter syntax, works with yarn/npm
• Language agnostic — the same architecture extends to Rust/Go/Python workspaces (Extend monorepo support to non-JS workspaces (Rust, Go, Python) #946) without code changes to the detection layer
• The agent already needs to understand the codebase — leveraging that intelligence is simpler than building parallel programmatic detection
• Two distinct metadata fields (packagesToRun vs packagesToValidate) serve different purposes at different times

Decision: Monorepo capability as a gate

Context: Should monorepo behavior be auto-detected on every command or gated by a capability flag?

Decision: Gate via "monorepo" capability set during il init. Monorepo-specific behavior (detection agent, metadata watching, scoped commands) only activates when this capability is present.

Rationale: Zero overhead for non-monorepo projects. Explicit opt-in via init rather than implicit detection on every command invocation.

Decision: Dev server watches metadata file

Context: The dev server launches before the detection agent runs, so packagesToRun isn't available yet.

Decision: When both web and monorepo capabilities are present, il dev-server watches the metadata file (via fs.watch or polling fallback) and launches once packagesToRun is populated.

Rationale: Decouples worktree creation from dev server launch. The dev server reacts to the detection agent's decision rather than requiring it upfront. Avoids blocking il start on agent completion.

Decision: Detection agent lifecycle varies by mode

Context: In non-swarm mode, package detection should happen before implementation. In swarm mode, individual child agents shouldn't each run detection.

Decision:

• Non-swarm: detection agent runs before implementation
• Swarm: orchestrator receives IS_MONOREPO boolean; calls detection agent after swarm completion for final validation/dev-server setup
• User-prompt-submit hook reminds agents to update metadata when touching new packages

Key trade-offs

• Agent intelligence over programmatic accuracy: Detection depends on LLM reasoning rather than deterministic file parsing. Mitigated by the hook reminder and the fact that stale metadata gracefully degrades (skipped packages, not crashes).
• Single dev server (v1): packagesToRun stored as array for future compat, but dev server reads [0] only. Multi-service orchestration deferred.
• JS-only (v1): pnpm/yarn/npm workspaces only. Non-JS workspace extensions tracked in Extend monorepo support to non-JS workspaces (Rust, Go, Python) #946.