Build with jg-plans

Getting started

Go from a Markdown plan to structured data. Start with one file, then choose the library or CLI to build it into your workflow.

Protocol 0.2 · provisionalnpm 0.5.1 Read as Markdown Jump to reference ↓

01 / Write a plan

Start with a file.

Save a Markdown document as plan.md. Record the basic metadata, then explain the work in your own words.

Milestones are optional. A small task can stay this small.

plan.md · complete example

---
id: 1792612800_search-feedback
created_at: 2026-10-21T20:00:00Z
updated_at: 2026-10-21T20:00:00Z
revision: 1
status: pending
protocol: "0.2"
---

# Search feedback

Explain an empty search result and suggest removing filters.

## Scope

Update the empty-state message and add a clear reset action.

## Validation

Check keyboard access, narrow layouts, and search with no matching results.

## Acceptance criteria

- AC-01: Empty search results explain the filters and offer a keyboard-accessible reset action.

02 / Read it in code

Turn text into data.

Pass the file's text to the library. Use the returned metadata and body in your application.

See the library API →

Install · Node.js 24.15.0+

npm install jg-plans@0.5.1

read-plan.ts

import { readFile } from 'node:fs/promises';
import { parsePlan } from 'jg-plans';

const source = await readFile('./plan.md', 'utf8');
const plan = parsePlan(source);

console.log(plan.metadata.status); // "pending"
console.log(plan.metadata.revision); // 1

03 / Or use the CLI

The same files. JSON output.

Point the CLI at one planning directory. It reads that plan and its optional milestones.

Explore CLI commands →

Inspect a selected directory

jg-plans inspect --directory ./jg-plans/example --json

Use the checkout instructions below while published-package availability is unverified.

Complete reference

Getting started

The protocol and examples are usable directly. The reference library and CLI are optional; the website’s availability label identifies a verified published version. The checkout commands below work independently of npm publication.

Start with an ordinary small plan. It contains core metadata, the current protocol marker, and a short body with an identified acceptance criterion. Add milestones only when separate units help review the work. For multiple criteria with shared milestone progress, follow the criteria example. Users can edit, move, or delete these files.

From a development checkout

Use Node.js 24.15.0 or newer and the pinned pnpm version:

pnpm install --frozen-lockfile
pnpm build
node dist/cli/cli.js inspect --directory examples/small --json
node dist/cli/cli.js check --directory examples/with-milestones --json

Inspect gives useful observations without requiring a conforming document. Check is optional. Missing files remain missing; neither operation restores history or approves execution. Document bodies are excluded from CLI output unless explicitly requested.

The API reference describes pure parsing, checking, selected-directory inspection, exclusive creation, pure preparation, guarded body/source writes, marker updates, removal, and shared locks. The CLI guide describes JSON input, automation envelopes, and exits. Read the integration boundary before building approval or execution behavior on these observations.

Make an explicit edit

Create input is ordinary JSON, for example { "body": "# Small change\n", "metadata": { "project": "example" } } in create.json. From a built checkout:

node dist/cli/cli.js create --slug small-change --input create.json --json

Use the returned directory for inspection and updates. Update input such as { "document": "plan", "set": { "revision": 2, "status": "in progress" } } changes only those requested fields. Supply updated_at explicitly when appropriate; nothing advances automatically. The runnable example (opens in a new tab) shows the full library journey with cleanup limited to its own temporary directory.

A plan can also record its priority, the repositories it changes, and the error codes it adds, set the same way: { "document": "plan", "set": { "priority": "high", "repositories": ["acme/app"] } }. Before choosing error codes, run jg-plans overlaps --root <folder> --json over each planning root those plans share: exit 1 names the overlapping plans, and exit 2 means it couldn’t read every plan, which isn’t the same as finding none.

Inspect exact hashes and supply expectedSha256 for guarded edits. Shared local document locks coordinate library, CLI, and participating consumers. Unsupported affected YAML/ambiguous markers fail without writing, detected changes are not retried, and existing-target expectations never recreate deleted files. Use explicit body/source writes when replacing prose; all unaffected bytes remain intact.

Contributing

The development guide (opens in a new tab) owns checks and package/site boundaries. Tests exercise built root exports and an isolated installation of the actual tarball. The protocol remains provisional until separately approved consumer integrations exercise it.

Continue exploring