wow-pi/AGENTS.md

Repository Guidelines

Project Overview

wow-pi is a Bun + TypeScript pi extension package that ports selected wow-omp features to original pi. It provides two runtime modules: Markdown context injection and environment variable injection.

Architecture & Data Flow

• Root package.json declares a private workspace and pi extension entry at packages/wow-pi/src/index.ts.
• packages/wow-pi/src/index.ts imports wow-contexts and wow-inject for side-effect module registration, then calls each registered module with pi's ExtensionAPI.
• packages/wow-core owns shared infrastructure: config loading, module registry, logger, UI rendering, path utilities, and ${protocol:value} reference resolution.
• packages/wow-contexts registers /wow:contexts:list, /wow:contexts:reload, /wow:init, then injects configured Markdown files into before_agent_start system prompts.
• packages/wow-inject loads .env files and inject.env values during setup and session_start, writing resolved values into process.env.

Key Directories

• packages/wow-pi/: pi extension entry package and bundled dist/ output.
• packages/wow-core/: shared config, registry, logger, UI, utilities, and ref resolver.
• packages/wow-contexts/: context scanning/building, command handlers, and init prompt.
• packages/wow-inject/: .env parser and environment injection module.
• scripts/: build and install/uninstall orchestration scripts.
• docs/contexts/: subsystem reference cards loaded by wow contexts.

Development Commands

• bun install: install workspace dependencies.
• bun run check: run TypeScript type checking with tsc --noEmit.
• bun run build: debug bundle for packages/wow-pi using Bun with --target node.
• bun run build:release: minified release bundle.
• bun run script:install: debug build and copy packages/wow-pi/dist to ~/.pi/agent/extensions/wow-pi.
• bun run script:install:release: release build and install with WOW_RELEASE=1.
• bun run script:uninstall: remove installed ~/.pi/agent/extensions/wow-pi.
• pi -e /path/to/wow-pi: load this extension once from source for manual testing.

Code Conventions & Common Patterns

• Use TypeScript ESM with strict type checking and Bun runtime types.
• Keep feature modules self-registering: import side effects call registerModule({ name, register }).
• Keep shared behavior in wow-core; feature packages should depend on wow-core, not each other.
• Use getWowSettingSync(key, cwd) for module config and call resetWowConfigCache() when config should be re-read.
• Use registerWowCommand(pi, name, options) so commands are namespaced as /wow:<name>.
• Use showInfo, showWarn, or show for command UI notifications.
• Avoid relying on source changes after install; installed pi code comes from copied packages/wow-pi/dist.

Important Files

• package.json: workspace scripts, pi manifest, peer dependencies.
• packages/wow-pi/src/index.ts: extension bootstrap and module registration loop.
• packages/wow-core/src/config.ts: JSON/YAML config loading and merge rules.
• packages/wow-core/src/registry.ts: module registration contract.
• packages/wow-contexts/src/index.ts: before_agent_start context injection.
• packages/wow-contexts/src/commands.ts: /wow:* command handlers.
• packages/wow-contexts/src/init-prompt.ts: /wow:init prompt template.
• packages/wow-inject/src/env.ts: environment injection flow.
• scripts/build.ts: debug/release build orchestrator.
• scripts/install.ts: hard-copy install/uninstall logic.
• wow.example.yaml: example global/project wow configuration.

Runtime/Tooling Preferences

• Use Bun for package management, scripts, and bundling.
• Build bundles with --target node; pi loads extensions through Node/Jiti, and --target bun can emit import.meta.require, which fails under pi.
• Externalize pi host packages in the bundle: @earendil-works/pi-coding-agent, @earendil-works/pi-ai, @earendil-works/pi-tui, and typebox.
• Config files are ~/.pi/agent/wow.{json,yaml,yml} and <project>/.pi/wow.{json,yaml,yml}; project config extends global config.
• Logs write to ~/.pi/agent/wow/logs/wow.YYYY-MM-DD.log with best-effort rotation.
• pi-subagents may be installed in the user environment; /wow:init explicitly asks for read-only scout/context-builder fanout when available.

Testing & QA

• There are no unit tests or test framework dependencies currently.
• bun run check is the primary validation command and only runs TypeScript.
• Build validation should include bun run build and bun run build:release when touching bundling or dependencies.
• Install validation should include bun run script:install and a pi smoke command such as PI_CODING_AGENT_DIR="$HOME/.pi/agent" pi --help.
• For extension behavior, manually verify /wow:contexts:list, /wow:contexts:reload, and /wow:init in pi.

Module Contexts (docs/contexts/)

• docs/contexts/wow-pi.md: extension entry and module orchestration.
• docs/contexts/wow-core.md: shared config, registry, logger, UI, and utilities.
• docs/contexts/wow-contexts.md: Markdown context scanning, injection, and commands.
• docs/contexts/wow-inject.md: .env loading and ref-based environment injection.
• docs/contexts/build-and-install.md: bundle, install, release, and validation flow.