Epic: Per-repository customization via ILOOM.md

[NoahCardoza]

Fixes #734

Epic: Per-repository customization via ILOOM.md

Issue details

Summary

Introduce a repo-root ILOOM.md file that is read at command start and injected directly into the system prompt of every iloom agent and every top-level prompt template. This gives repo maintainers a freeform way to steer iloom's behavior — review priorities, coding conventions, theming/MCP preferences, LaunchDarkly/feature-flag expectations, etc. — without changing iloom itself.

Supersedes the original "custom sub-agents via settings" proposal in favor of @acreeger's simpler ILOOM.md suggestion from the comments.

Goals

• Repo-level ILOOM.md at repo root, mirroring the CLAUDE.md convention
• Content flows into every iloom-authored system prompt — top-level workflow prompts AND every agent under templates/agents/
• Silent no-op when the file is absent. No CLI flag, no settings toggle
• Structured so per-agent extensions (e.g. the original "custom reviewer subagents" idea) are a trivial add later, without reworking the plumbing

Non-goals

• Per-agent overrides (future work — design leaves the door open via an extensible PromptExtensions module)
• A CLI flag or settings toggle to disable it
• Injection into the generated workspace CLAUDE.md template (templates/prompts/CLAUDE.md) — that file is what iloom writes into workspaces, not a system prompt
• Reading any file other than ./ILOOM.md at the repo root

Approach

1. New src/lib/PromptExtensions.ts module exposes loadPromptExtensions(repoRoot) returning a structured object. Today: { ilommMd: string }. Future fields (per-agent overrides, injectable tool allowlists, etc.) land here without changing callers.
2. Every command that builds TemplateVariables calls the loader and assigns ILOOM_MD_CONTENT on the variable set.
3. Every top-level prompt template and every agent template under templates/agents/ gets a uniform {{#if ILOOM_MD_CONTENT}}…{{/if}} injection block, placed outside any SWARM_MODE/DRAFT_PR_MODE conditionals.
4. Fire-and-forget telemetry event iloom_md.loaded with { present, size_bucket } so we can see adoption without leaking content.

Shared contracts

// src/lib/PromptExtensions.ts
export interface PromptExtensions {
  ilommMd: string
  // Future: perAgentOverrides?: Record<string, string>
  // Future: injectedTools, etc.
}
export async function loadPromptExtensions(repoRoot: string): Promise<PromptExtensions>

// src/lib/PromptTemplateManager.ts — TemplateVariables interface gains:
ILOOM_MD_CONTENT: string   // always present; "" when ILOOM.md is absent

• Loader reads ${repoRoot}/ILOOM.md. On ENOENT or any other read error: returns "", debug-log only, never throws.

• Loader fires iloom_md.loaded telemetry once per process (module-level flag), with size_bucket: empty (0B), small (<1024B), medium (<10240B), large (≥10240B).

• Template injection block, identical across every target template, placed outside all mode conditionals:

  {{#if ILOOM_MD_CONTENT}}
  
  ## Repository Guidance (from ILOOM.md)
  
  The repository maintainers have provided the following guidance via ILOOM.md. Apply it throughout your work.
  
  {{ILOOM_MD_CONTENT}}
  
  {{/if}}

  Handlebars is configured with noEscape: true and does not re-parse substituted values, so literal {{…}} inside a user's ILOOM.md renders as-is.

Scope

• Read-path: ./ILOOM.md at repo root (no .iloom/ILOOM.md, no settings-configurable path)
• Write-path: none — file is authored by humans
• Injection sites:
  • Prompt templates under templates/prompts/: issue-prompt.txt, pr-prompt.txt, regular-prompt.txt, plan-prompt.txt, swarm-orchestrator-prompt.txt, init-prompt.txt, session-summary-prompt.txt
  • Excluded: templates/prompts/CLAUDE.md (generated-workspace template, not a system prompt)
  • Agent templates: all 9 under templates/agents/
• Wire-through sites: src/commands/ignite.ts, src/commands/init.ts, src/commands/feedback.ts, src/lib/SwarmSetupService.ts, src/lib/IssueEnhancementService.ts

Task overview

#	Title	Dependencies	Complexity
1	Add PromptExtensions loader + ILOOM_MD_CONTENT template variable + telemetry event	None (produces shared contract)	Simple
2	Wire PromptExtensions loader through all command entry points	Shared contract from #1	Simple
3	Inject ILOOM.md guidance block into top-level prompt templates	Shared contract from #1	Simple
4	Inject ILOOM.md guidance block into agent templates	Shared contract from #1	Simple
5	Document ILOOM.md	Shared contract from #1	Simple
6	Verify ILOOM.md integration end-to-end	Hard-blocked by #1–#5	Simple

Only #6 has a hard blocking dependency. Wave-1 children use compile-time shared contracts (not blocking dependencies) so they can be implemented in parallel; compile errors on isolated branches are expected and resolve on merge.

---

This PR was created automatically by iloom.

[NoahCardoza]

Implementation Complete

Summary

Implemented the 6-task ILOOM.md epic in a single PR: repo-root ILOOM.md is now loaded by a new PromptExtensions module, threaded through every command that builds TemplateVariables, and injected (via a standard {{#if ILOOM_MD_CONTENT}} block) into all 7 top-level prompt templates and all 9 agent templates. Silent no-op when the file is absent. Fire-and-forget telemetry (iloom_md.loaded, size-bucketed) emits once per process. Docs in README.md and docs/iloom-commands.md describe the feature.

Changes Made

• src/lib/PromptExtensions.ts (new): loadPromptExtensions(repoRoot) reads ${repoRoot}/ILOOM.md, returns { ilommMd } trimmed of trailing whitespace, never throws (ENOENT + any error → { ilommMd: "" } + debug log), fires iloom_md.loaded telemetry once per process
• src/lib/PromptExtensions.test.ts (new): 9 unit tests (presence, absence, empty, unreadable, size buckets, telemetry-once, trimming)
• src/lib/PromptExtensions.integration.test.ts (new): renders issue-prompt.txt via real PromptTemplateManager, asserts the guidance block appears only when ILOOM_MD_CONTENT is non-empty
• src/lib/PromptTemplateManager.ts: ILOOM_MD_CONTENT: string added to TemplateVariables
• src/types/telemetry.ts: IlommMdLoadedProperties + iloom_md.loaded event added
• Wire-through (9 sites): src/commands/ignite.ts, init.ts, plan.ts, feedback.ts, src/lib/ClaudeService.ts, IssueEnhancementService.ts, SessionSummaryService.ts, SwarmSetupService.ts (each of these calls loadPromptExtensions and populates ILOOM_MD_CONTENT)
• Test updates: ClaudeService.test.ts, SessionSummaryService.test.ts updated to include ILOOM_MD_CONTENT: '' in expected variable sets
• Template injection (16 files):
  • 7 prompts: templates/prompts/{issue,pr,regular,plan,swarm-orchestrator,init,session-summary}-prompt.txt
  • 9 agents: every templates/agents/*.md (block placed after YAML frontmatter, before main instruction body; hardcoded Agent 1–5 sub-prompts in iloom-code-reviewer.md left untouched)
• Docs: new "ILOOM.md — Repository Guidance" section in docs/iloom-commands.md (TOC updated), one-sentence mention in README.md Configuration section pointing to that doc. .iloom/README.md does not exist — skipped.

Validation Results

• ✅ pnpm build: success
• ✅ pnpm compile: clean (no type errors)
• ✅ pnpm lint: clean
• ✅ pnpm test: ILOOM.md-touched files pass 140/140 (PromptExtensions.test, PromptExtensions.integration.test, PromptTemplateManager.test, ClaudeService.test, SessionSummaryService.test)
• ℹ️ The repo has 69 pre-existing test failures on a clean tree (verified via git stash), all unrelated to this change — a mergeBehavior.mode enum mismatch ('draft-pr' vs 'local' | 'github-pr' | 'github-draft-pr') from prior work. Not introduced here.
• ✅ Static: grep -l '{{ILOOM_MD_CONTENT}}' templates/prompts/*.txt templates/agents/*.md → exactly 16 files
• ✅ Static: all 5 plan-required wire-through sites (ignite.ts, init.ts, feedback.ts, SwarmSetupService.ts, IssueEnhancementService.ts) import loadPromptExtensions
• ✅ Integration smoke: rendered prompt contains the "Repository Guidance (from ILOOM.md)" section only when content is non-empty

[acreeger]

@NoahCardoza I'm wondering if there are prompt injection risks we need to think about - what do you/Claude think?