open-press

# open-press framework — agent contract

This repo is the **open-press** framework: core engine/workbench packages, CLI scaffolder, bundled skills, docs, landing site, and a tracked dogfood workspace.

**You are an agent contributing to open-press itself.** Framework code lives under packages/apps/skills; the root `press/` is the public dogfood workspace used to verify the framework with real output.

> **If you find `memory/AGENTS.md` at the workspace root, you're in a downstream workspace** (an open-press project, not the framework repo itself). Read `memory/AGENTS.md` first for project-specific context. Downstream workspaces consume `@open-press/core` from npm; document work should normally stay in `press/`, `openpress/settings.json`, and local skills.

## What you may edit

- `packages/core/` — runtime primitives, engine, render pipeline, workbench source, tests.
- `packages/cli/` — scaffolder and template sync code.
- `apps/web/` — landing site.
- `skills/` — independent agent skills. Some skills include `starter/` files that agents can read, copy, and adapt.
- `press/` — tracked dogfood workspace. Hosts `press/userstory/` (the OpenPress User Story Book) plus minimal `social` and `slide` Press for multi-Press verification. Use it to validate real content, style, PDF, deploy, and gallery routing.
- `docs/` — user-facing docs, migration notes, active specs, and implementation plans.
- Root config: `vite.config.ts` / `tsconfig.json` / `index.html` / `package.json` / `openpress/settings.json` / `README.md` / `.gitignore`.

## What you may not edit

- `packages/core/document/` — legacy local scratch path. Do not recreate it; root `press/` is the dogfood workspace.
- `node_modules/`, `public/openpress/`, `dist-react/`, `.deploy/`, `.openpress/`, `.turbo/cache/` — generated/cache output. The only writable exception is the ephemeral `.openpress/review/current.json` handoff owned by `openpress-collaborate`; replace or remove it, never treat it as authored delivery source.

The full source-vs-generated path table is owned by `skills/openpress/SKILL.md` > Source Boundary. Other skills link to that table rather than redefining it.

## Commit message prefixes

- `[core] ...` — framework code (`packages/core/`, `packages/cli/`, `apps/web/`)
- `[doc] ...` — dogfood content (`press/`, tracked) and top-level docs
- `[skill] ...` — skill files under `skills/`
- `[spec] ...` — design specs / docs
- `[test] ...` — test changes only

## Branch ownership

- **Framework code (`packages/core/`, `packages/cli/`, `apps/web`)** — keep generic. No hardcoded project content, brand, or paths. All workspace-specific values flow through `openpress/settings.json` or `<Workspace>` / `<Press>` JSX props.
- **Starter-bearing skills (`skills/<name>/starter/`)** — independent skills that include usable starter files. Keep them working, but do not make the CLI responsible for fetching them.
- **Built-in chart types** — `bar`, `line`, `donut` only. Adding a new built-in is a framework-level decision; ad-hoc chart variants belong as per-Press components in `press/<slug>/components/<name>/`.

## Workflow for local validation

`skills/openpress/SKILL.md` is the routing entry point. Read it first to find the right specialist (collaborate, create-pages, create-slide, diagram, deploy, apply-comments). Use `skills/openpress-collaborate/SKILL.md` for authored-content analysis and changes. Use `skills/openpress-apply-comments/SKILL.md` directly when the task is to resolve pending `@openpress-comment` markers without a Change Preview.

Use the tracked root `press/` to validate framework changes. It should exercise real authoring, preview, PDF, and deploy flows:

```bash
# Validate the full pipeline:
npm run build            # validates + renders every Press into dist-react/ + public/openpress/<slug>/
npm run dev:workspace    # http://127.0.0.1:5173/workspace
npm run openpress:pdf
npm test
```

After framework changes:

```bash
npm run skills:link      # sync framework skills/ (SSOT) to .agents/skills/ & .claude/skills/
npm run typecheck
npm test
```

### Landing site verification

`apps/web/` is a marketing landing site. Validate it with `pnpm --filter web build` and visual review in the browser. Do not add automated tests for landing-page copy, section order, layout, responsive presentation, or motion; those details are intentionally design-review concerns. Product behavior in `packages/core/` remains covered by automated tests.

## Boundaries (engine philosophy)

- **Engine stays dumb**: no opinions about content, brand, voice, visual register.
- **Skills carry opinions**: create skills, starter-bearing skills, and portable language/genre skills.
- **User owns intent**: agents ask before adding material business numbers, legal claims, public commitments, or publishing to a public URL.
- **Validation protects delivery, not taste**: structural checks pass before render; do not police placeholder text or aesthetic choices in `validate`.