jamminrebel/pom-omp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0164fcbddb00a32ba8bec52b79d0f3233a2e477b
pom-omp/AGENTS.md

21 KiB
Raw Blame History

Repository Guidelines

Project Overview

  • identity: @jamminrebel/pom-omp 2.0.0, MIT, ESM — POM 2 "Produce Magnum Opus", an Oh My Pi (OMP) extension.
  • purpose: turn OMP's native models, tools, task agents, IRC, todo, sessions, approvals, compaction and TUI into an evidence-gated production operating system for long-form creative work (README.md:3).
  • governs, never replaces: OMP performs execution; POM adds stage contracts, canonical artifacts, prompt provenance, deterministic validation, Git checkpoints, and an Obsidian/Quartz-compatible vault (README.md:5, POM.yml:6-9, docs/ARCHITECTURE.md:3-27).
  • ships: 9 stages (0..8), 7 pom_* tools, 14 task agents, 13 prompt fragments, 3 rules, 2 themes, native task+IRC Hive planning, optional Swarm DAGs, verified ZIP delivery (README.md:9-20).
  • operator loop: /pom new "Title" -> /pom run next -> /pom hive stage -> /pom evidence -> /pom check stage -> model calls pom_stage action=pass only after a PASS report -> /pom export final (README.md:44-56). /pom opens the command center; Alt+P is the shortcut.
  • this file is the repository contributor guide. Generated POM projects get their own AGENTS.md written by bootstrapProject (src/persistence.ts:241-307) — different file, different audience.

Architecture & Data Flow

  • flow: /pom command -> parser -> stage machine -> persistence + git + router -> prompt-stack injection -> OMP model turn -> pom_* tools -> validators -> exporter.
  • entry point: default export pomExtension(pi: ExtensionAPI) in src/index.ts; sets label POM · Produce Magnum Opus, builds the runtime, then registers in this order: registerPomTools, registerPomRenderers, registerPomEvents, registerPomCommand (src/index.ts:13-49). Keep registration centralized there.
  • runtime boundary: src/runtime.ts PomRuntime = get, set, restore, getConfig, refreshConfig, telemetry.
    • set clones state, stamps updatedAt, appends a session branch entry of type pom-state, writes 00_admin/project_state.json, and syncs generated knowledge files when state.initialized (src/index.ts:25-31). Never persist state around it.
    • restore precedence: session branch via restoreLatest -> <cwd>/00_admin/project_state.json -> fresh uninitialized state (src/index.ts:33-42).
  • command layer: src/command.ts registers pom plus shortcut alt+p and owns all verbs (new, run, hive, swarm, evidence, check, vault, export, status, prompt, tools, theme, settings, doctor, help). src/parser.ts tokenizes quotes/escapes, defaults the verb to dashboard, and parses --flag[=value] into a Map.
  • stage run: runStage = startStage(gotoStage(...)) -> runtime.set -> enterStageBranch -> routeStage -> updateChrome -> pi.sendUserMessage(await renderStagePrompt(...), { deliverAs: "followUp" }) (src/command.ts:94-105).
  • routing: src/router.ts applies the stage tool profile when autoToolProfiles, resolves spec.modelRole via ctx.models.resolve, calls pi.setModel, and sets thinking xhigh for every stage except stage 7 (high).
  • domain: src/domain.ts holds POM_VERSION / POM_SCHEMA_VERSION (both "2.0.0"), STAGES: readonly StageSpec[], ArtifactRecord, EvidenceRecord, StageBlocker, StageRunState, HiveTask, HiveMission, PomState, PomConfig, DEFAULT_CONFIG.
    • stages: 0 init, 1 genre, 2 voice, 3 store, 4 bible, 5 outline, 6 chapters, 7 draft, 8 delivery. Each StageSpec owns id, slug, name, icon, toolProfile, modelRole, agents, artifacts, acceptance, todos.
  • state machine: src/state.ts, clone-then-mutate.
    • gotoStage rejects incomplete prerequisites; startStage rejects complete stages and unresolved blockers; passStage requires an active run, a validation report path, zero unresolved blockers, and evidence for every acceptance criterion (src/state.ts:97-188).
    • recordEvidence checks the criterion belongs to the active stage, demands a non-empty summary plus >=1 path, de-duplicates normalized paths, replaces prior evidence for that criterion (src/state.ts:144-168).
    • canonical state path: <projectRoot>/00_admin/project_state.json via statePath.
  • persistence: src/persistence.ts serializes writes per absolute path (writeQueues), writes a temp file then rename, and appends a trailing newline to JSON.
    • manifest 00_admin/artifact_manifest.json: entries need safe unique relative paths, stage 0..8, semver version, valid status, SHA-256, positive bytes, parseable updatedAt, valid rights status.
    • registerArtifact: secureExistingPath -> reject empty file -> relativeProjectPath -> SHA-256 -> manifest save -> artifact.registered in 00_admin/artifact_events.jsonl -> knowledge sync (src/persistence.ts:123-163).
    • bootstrapProject creates 00_admin, 01_planning, 02_story_bible, 03_manuscript/chapters, 04_images/{references,generated}, 05_research, 06_ledgers, 07_exports, .omp/prompts, content, and refuses a non-empty unrecognized directory that has no 00_admin/project_state.json (src/persistence.ts:216-239).
  • events: src/events.ts.
    • resources_discover advertises bundled ../skills, ../prompts, ../themes via fileURLToPath(new URL(...)); it does not advertise agents/ or rules/.
    • before_agent_start injects the composed prompt stack into event.systemPrompt and returns a hidden pom:event message.
    • native task / irc are observed only: tool_call / tool_result update Hive mission status plus telemetry and append durable native.task.started, native.task.finished, native.irc.send, native.irc.result ledger events.
  • prompts: src/prompts.ts loads bundled ../prompts plus project .omp/prompts; id = markdown basename; project fragments override bundled by id; every fragment is SHA-256 stamped in an HTML comment (id/source/hash); a stack is immutable law -> personality-${state.mode} -> requested ids, and each use is logged to the prompt ledger.
  • delegation: src/studio.ts builds HiveMission ids s${spec.id}-${randomUUID().slice(0,8)}, caps agents at maxStudioAgents, and converts a mission into one native task batch whose shared context tells agents to coordinate over native IRC and never pass the stage. src/swarm.ts optionally writes 00_admin/swarms/<missionId>.yaml (specialists plus an integrator) through secureFuturePath.
  • validation: src/validators.ts validatePom(state, scope, opts); scopes quick, stage, canon, continuity, knowledge, files, delivery, all; report schema "1.0.0"; passed is true only when no check has status fail; reports land in 00_admin/validation/stage-<n>-<scope>-<stamp>.json when initialized.
  • delivery: src/exporter.ts writes 00_admin/SHA256SUMS.txt, a delivery report under 07_exports, then 07_exports/<projectSlug>-<kind>.zip, verifies it and writes <base>.verification.json. src/zip.ts (yazl create, yauzl read, crc-32) rejects encryption, compression methods other than 0/8, duplicate members, unsafe names, empty archives, size drift and CRC mismatch, and returns the archive SHA-256.
  • terminal: src/ui.ts writes statuses pom-stage, pom-progress, pom-gate, pom-hive and widget pom-hud; src/visual.ts renders the HUD with width-safe truncation and caches unchanged frames; src/renderers.ts renders custom message types pom:event, pom:validation, pom:hive, pom:milestone and adds a thinking lane when enabled and view is not minimal/compact.
  • git: src/git.ts shells execFile("git", ["-C", root, ...]), initializes when needed, uses branches pom/stage-<id>-<slug>, and checkpoints with git add -A + git commit unless gitMode disables it.

Key Directories

  • src/: extension source, 25 modules, no build step (OMP loads TypeScript directly).
  • tests/: 8 *.test.ts files on node:test, importing production code.
  • scripts/: verify.mjs (structural gates), release-manifest.mjs (RELEASE.json generate/check), smoke.ts (runtime smoke), install.sh / install.ps1.
  • agents/: 14 pom-*.md specialist task-agent definitions.
  • prompts/: 13 prompt fragments; ids are basenames; personality-*.md map to PomMode.
  • rules/: 3 scoped production rules (pom-artifact-integrity, pom-continuity, pom-rights).
  • skills/pom/: SKILL.md plus references/ (core-law.jml, workflow.md, tool-routing.md, todo-blueprints.md, artifacts.md, agent-studios.md, commands.md, qa.md, ui.md).
  • themes/: pom-nocturne.json (dark), pom-parchment.json (light).
  • config/: shipped templates — config.yml (OMP host settings), pom.json (POM defaults), APPEND_SYSTEM.md, mcp.json.example.
  • docs/: ARCHITECTURE.md, SETTINGS.md, TOOL_MATRIX.md, INVENTORY.md, AUDIT.md, DESIGN_REVIEW.md, OFFICIAL_SOURCES.md, POM_ARCHITECTURE.mmd.

Development Commands

  • setup: npm install
  • typecheck: npm run check -> tsc --noEmit (tsconfig includes src/**/*.ts only; tests are not typechecked)
  • tests: npm test -> node --import tsx --test tests/*.test.ts
    • one file: node --import tsx --test tests/state.test.ts
    • one case: node --import tsx --test --test-name-pattern="<regex>" tests/state.test.ts
  • runtime smoke: npm run smoke -> node --import tsx scripts/smoke.ts
  • structural gates: node scripts/verify.mjs
  • release manifest: npm run release:manifest (write), npm run release:check (fail if stale)
  • full gate: npm run verify = check -> test -> smoke -> scripts/verify.mjs -> release:check -> npm pack --dry-run
  • host install: npm run link (omp plugin link .), then restart OMP or /reload-plugins, then /pom theme install
  • host check: npm run doctor (omp plugin doctor; needs Bun + OMP installed)

Code Conventions & Common Patterns

  • imports:
    • relative source imports are extensionless: ./state, ./domain, ./tool-profiles — never .ts / .js, despite allowImportingTsExtensions: true.
    • Node builtins use the node: prefix; OMP SDK types come in as import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent".
  • errors: throw Error for precondition, schema, config, manifest and path violations (assertState, loadPomConfig, secureExistingPath); represent observable tool failures as isError: true results, not throws.
  • tools: defined in src/tools.ts; ids are exactly pom_state, pom_stage, pom_artifact, pom_validate, pom_prompt, pom_hive, pom_export.
    • schemas use const { z } = pi.zod with inline z.object / z.enum; one targeted @ts-expect-error covers OMP 16.4.x + Zod v4 instantiation depth (src/tools.ts:58-61) — keep it narrow.
    • every result goes through textResult(text, details?, isError = false) -> { content: [{ type: "text", text }], details, isError }.
    • mutators declare approval: "write"; pom_validate and pom_prompt declare approval: "read".
    • every execute handler returns textResult("Cancelled", undefined, true) when signal?.aborted.
  • state: clone with structuredClone before nested mutation, then persist through runtime.set.
  • async: async/await everywhere for FS, OMP hooks, tools, config and validation; no callback style.
  • naming: kebab-case multiword filenames (tool-profiles.ts); camelCase functions, PascalCase types; POM-owned identifiers keep the pom / pom_ / pom- prefix per surface (tool ids pom_*, statuses pom-*, message types pom:*, agents pom-*).
  • tool profiles: src/tool-profiles.ts appends POM tools to host tools for non-auto profiles, always keeps read, and stores the baseline in a WeakMap keyed by pi — use resetToolBaselineForTests() rather than assuming a fresh baseline.
  • config: src/config.ts merges built-in DEFAULT_CONFIG -> ~/.omp/agent/pom.json -> <project>/.omp/pom.json, validates booleans/enums/bounded integers and throws Invalid POM setting ...; writes go temp-file-then-rename.
    • keys and defaults: autoToolProfiles true, autoModelRouting true, dashboardWidget true, stopGuard true, defaultMode "autopilot", defaultView "cinematic", defaultMotion "subtle", defaultToolProfile "auto", maxStudioAgents 6, projectRootMode "child", destructiveProjectCommands "block", gitMode "branch-per-stage", hudPlacement "aboveEditor", showThinkingLane true (src/domain.ts:471-486, docs/SETTINGS.md:31-46).
    • OMP host settings belong in <project>/.omp/config.yml; the shipped template is config/config.yml and bootstrapProject writes the same values (theme pom-nocturne/pom-parchment, task.maxConcurrency: 8, compaction.strategy: snapcompact, defaultThinkingLevel: high).
  • asset shapes:
    • agents: frontmatter name: pom-<kebab>, non-empty description, tools: list that includes yield, plus model, thinkingLevel, read-summarize; enforced by scripts/verify.mjs:58-64.
    • rules: frontmatter description plus globs array.
    • skill: skills/pom/SKILL.md frontmatter name: pom, description, alwaysApply: false.
    • prompts: frontmatter optional — personality fragments carry description, operational fragments start with prose; the loader accepts any .md.
    • themes: keep $schema, name (must equal filename stem), vars, colors, export; /pom theme install copies themes/*.json into getCustomThemesDir() from @oh-my-pi/pi-utils.
  • POM.yml is the human-facing project/release manifest (boundaries, stages, gate, commands, tools, delegation, terminal, knowledge, integrity, resources, release) — not a runtime schema; nothing loads it at runtime.

Important Files

  • src/index.ts: extension entry, runtime construction, registration order.
  • src/domain.ts: schema versions, STAGES, artifact/evidence/blocker/hive/state/config types, DEFAULT_CONFIG.
  • src/state.ts: stage lifecycle invariants, evidence rules, canonical state path.
  • src/persistence.ts: workspace layout, atomic writes, manifest/ledger/knowledge persistence, bootstrap.
  • src/tools.ts: the 7 pom_* tool contracts, approvals, result shape.
  • src/events.ts: OMP event surface, resource discovery, prompt injection, native task/IRC observation.
  • src/validators.ts: deterministic checks and report contract.
  • src/paths.ts: canonicalRoot, secureExistingPath, secureFuturePath, relativeProjectPath, assertSafeArchivePath.
  • scripts/verify.mjs: structural release gates (see Testing & QA).
  • scripts/release-manifest.mjs: RELEASE.json generation and --check staleness semantics.
  • package.json: OMP entry omp.extensions: ["./src/index.ts"], scripts, peer window, ship list.
  • tsconfig.json: target ES2022, module ESNext, moduleResolution Bundler, strict, noEmit, skipLibCheck, allowImportingTsExtensions.

Runtime/Tooling Preferences

  • package manager: npm, authoritative package-lock.json (lockfileVersion 3). Do not introduce bun/pnpm/yarn lockfiles.
  • local scripts run on Node + tsx + tsc; engines.bun >= 1.3.14 describes the OMP host, and npm run doctor is the only Bun+OMP gate.
  • no build step and no dist/: OMP loads src/index.ts directly.
  • SDK window: @oh-my-pi/pi-coding-agent, pi-tui, pi-utils are peers at >=16.4.6 <17. Do not use APIs that require OMP 17.x.
  • runtime dependencies are deliberately three: crc-32, yauzl, yazl (ZIP integrity). Add a dependency only when the host SDK and Node builtins genuinely cannot do the job.
  • .gitignore covers node_modules/, *.tgz, *.zip, coverage/, dist/, .DS_Store, *.log.

Testing & QA

  • framework: Node's built-in runner, import test from "node:test" + import assert from "node:assert/strict", flat test("...") calls, no describe.
  • tests import production code directly with extensionless specifiers (../src/state); never copy implementation into a test.
  • filesystem tests isolate with mkdtemp(join(tmpdir(), ...)) and clean up in finally via rm({ recursive: true, force: true }).
  • test-file names do not map 1:1 to modules: tests/command.test.ts exercises src/parser.ts, tests/events.test.ts exercises src/policy.ts.
  • covered by unit tests: parser, policy, paths, state, domain, persistence, studio, swarm, validators, zip. Not directly covered: src/tools.ts, src/visual.ts — add tests there when changing behavior.
  • scripts/smoke.ts is the end-to-end guard: bootstrap a temp project with projectRootMode: "cwd", assert generated .omp/config.yml and content/production-board.md content, then assert validatePom(state, "quick", { writeReport: false }).passed === true.
  • scripts/verify.mjs enforces, and will fail a change that breaks any of these:
    • required files exist, including src/index.ts, src/events.ts, src/tools.ts, src/visual.ts, skills/pom/SKILL.md, config/APPEND_SYSTEM.md, prompts/stage-run.md, both themes, scripts/smoke.ts.
    • RELEASE.json.version === package.json.version; release inventory stages/customTools/behavioralTests = 9/7/9; pkg.omp.extensions deep-equals ["./src/index.ts"]; pkg.version === "2.0.0"; every package.json.files entry exists.
    • exactly one registerCommand("pom" and one registerShortcut("alt+p" in src/command.ts; exactly nine id: 0..8 stage ids in src/domain.ts; exactly seven name: "pom_*" tools in src/tools.ts.
    • src/tools.ts contains none of allowArgs, formatApprovalDetails, concurrency: "exclusive", ExtensionAPI = any; src/omp-shim.d.ts and src/node-shim.d.ts must not exist.
    • asset counts 14 agents / 13 prompts / 3 rules / 2 themes, agent frontmatter shape, theme names and required color keys (read from the installed @oh-my-pi/pi-coding-agent theme schema, so npm install is a prerequisite), and the nine required directories.
  • after changing any shipped file (anything in package.json.files plus package.json), run npm run release:manifest; npm run release:check compares rendered bytes and fails with "RELEASE.json is stale".
  • run npm run verify before packaging or linking. Host-level acceptance stays npm run doctor plus an interactive OMP session: /pom overlay, HUD, statuses, cards, /pom theme install, and a smoke project taken through stage 0 validation plus a checkpoint archive.

Governance Invariants

Preserve these when changing runtime behavior (source: the shipped contributor guide, rules/*.md, skills/pom/references/core-law.jml).

  • do not duplicate host primitives: task, IRC, todo, sessions, approvals, compaction, memory, model execution, TUI. Observe and route them; never build a parallel system.
  • stage completion requires active execution, complete evidence, zero open blockers, and a passing validation report. Never mark a stage complete by direct state mutation.
  • truth hierarchy: system + explicit user requirements > canonical project files and 00_admin/project_state.json > manifest / evidence / ledgers > live OMP execution > vault projection > memory. The vault is a navigable projection, not a source of truth.
  • keep canonical state and artifacts under the project root; reject traversal and symlink escape through src/paths.ts helpers (lexical plus realpath containment) — do not substitute plain join/resolve checks.
  • never fake tool use, files, citations, images, counts, hashes, checks, ZIP tests, or completion. Partial, missing and blocked states stay disclosed as PARTIAL / BLOCKED.
  • artifact claims need real non-empty regular files with measured bytes, SHA-256, category, stage, semver version, status, rights, source and notes recorded in the manifest.
  • delivery claims need a fresh archive with safe member names, no duplicates/encryption/unsupported methods, central-directory parsing, decompression, size and CRC-32 checks, an archive hash, and an external verification report.
  • continuity: story changes must preserve or explicitly revise canon, timeline, knowledge, relationships, props, injuries, rules, mysteries, setups and payoffs; contradictions require explicit canon selection, dependency mapping, revision logging and revalidation.
  • rights: no living-author imitation, fabricated quotations, unauthorized asset redistribution, invented private-identity facts, or unsupported rights claims.
  • use OMP renderers and UI hooks (setWidget, setStatus, setWorkingMessage, message cards) instead of printing raw terminal control sequences.
  • delegation: one widest safe native task batch per independent wave, each task carrying objective, owned files and acceptance conditions; keep IRC terse with the CLAIM / QUERY / ANSWER / ALERT / HANDOFF / DONE vocabulary; durable findings go into project files or ledgers, not chat.
  • tool routing: native tool first — read for files/directories/archives/static URLs, glob for bounded discovery, grep for bounded regex, AST/LSP for symbol work, browser only for authenticated/interactive/JS-only pages, ask only after exhausting sources.

Known Discrepancies

Verified inconsistencies in the current tree — do not "fix" them silently as part of unrelated work, and do not describe them as working.

  • pom_stage accepts an inspect action in its schema with no dedicated branch; it falls through to the sync/refresh path and returns summary state. Decision: keep as summary fallback; if dedicated inspect behavior is needed, add a branch and update schema/tests.
  • resources_discover advertises only skills, prompts and themes; agents/ and rules/ are shipped but not advertised through that event. Decision: agents and rules are packaging-only resources; add them to resources_discover if/when agent-facing discovery is required.
  • docs/INVENTORY.md claims "9 behavioral tests across 8 test files"; the tree contains 8 test files with 9 test declarations. scripts/verify.mjs asserts the manifest number (9) without distinguishing file count from declaration count.