Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (46 loc) · 4.43 KB

AGENTS.md

File metadata and controls

66 lines (46 loc) · 4.43 KB
Raw

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/, gitignored so rarely committed)
  • [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:

# 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:

npm run typecheck
npm test

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.