feat: initial commit

AGENTS.md

@@ -0,0 +1,82 @@
+# 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.