Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (52 loc) · 4.33 KB

AGENTS.md

File metadata and controls

75 lines (52 loc) · 4.33 KB
Raw

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

  • Mentions planning or proposals (words like proposal, spec, change, plan)
  • Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
  • Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

  • How to create and apply change proposals
  • Spec format and conventions
  • Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

ECMA-376 conformance

safe-docx targets a defined subset of ECMA-376 5th edition. Spec conformance is a foundational property of this repo, not a side concern, so the machinery lives at the repo root rather than under openspec/.

When editing OOXML behavior, lead conformance claims with a @conformance ECMA-376 edition <N>, Part <N> § <SECTION> JSDoc tag and demote internal #NNN issue references to @see. Tests use testAllure.conformance({ spec, edition, part, section }). The lint npm run check:conformance-citations enforces both.

Workflow Conventions

Follow all conventions in CONTRIBUTING.md. The rules below are mandatory for AI agents:

Branch Naming

  • ALWAYS create a branch before committing. Never commit directly to main.
  • Issue work: {issue}-{short-description}-{YYYYMMDD} (e.g., 42-add-redline-support-20260221)
  • Minor fixes: tweak-{description} (e.g., tweak-fix-typo-in-readme)

Commits

  • Use conventional commit format: type(scope): imperative description
  • Valid types: feat, fix, refactor, test, docs, chore, ci, perf, style
  • Scope to the package: feat(docx-primitives):, fix(safe-docx):, refactor(docx-comparison):
  • Body MUST explain WHY, not just what. Longer is better.
  • Reference the issue: Fixes: #N or Ref: #N

Pull Requests

  • Keep PRs small and focused — one concern per PR.
  • NEVER force push after a review has started.
  • Include screenshots for any visual changes.

Pre-submit

  • All CI checks must pass locally before pushing: npm run build && npm run lint:workspaces && npm run test:run && npm run check:spec-coverage && npm run check:conformance-citations && npm run check:conformance-doc

Test Fixtures

Before adding OOXML / DOCX test fixtures, check packages/docx-core/src/testing/ first.

  • Field XML primitives and complete-field constants (<w:fldChar>, <w:instrText>, NUMPAGES / PAGE / PAGEREF sequences, fragmented modification patterns, whole-field <w:ins>/<w:del> wrappers): use packages/docx-core/src/testing/ooxml-fixtures.ts. Add new constants and helpers there rather than inline in a test file.
  • Minimal DOCX package from raw body XML: use buildDocxFromBodyXml(bodyXml) from ooxml-fixtures.ts. Do not copy-paste a local JSZip builder unless the test needs a deliberately different package shape (e.g., to test how the engine handles a missing _rels/.rels).
  • Paragraph-array DOCX with optional footnote/comment/bookmark scaffolding: use buildSyntheticDocx from packages/docx-core/src/integration/synthetic-docx-fixture.ts.

Inline OOXML literals are acceptable for scenario fixtures that are the subject of a test (e.g., a deliberately malformed standalone-<w:fldChar> regression guard). They are not acceptable for re-deriving shapes that already live in the fixtures module — that produces the kind of cross-file drift issue #221 was filed to fix.

Skills

A skill is a set of local instructions stored in a SKILL.md file.

Available skills

  • docx-editing: Surgically edit existing (brownfield) .docx files with formatting preservation and tracked changes via the Safe-DOCX MCP server. Use when reading, searching, editing, commenting on, or comparing Word documents. (From-scratch generation lives in the @usejunior/docx-core library API, not in this MCP server.) (file: skills/docx-editing/SKILL.md)