Postplan

Private HTML plans, specs, and handovers for Kiara.

Use it

Install the agent skill once:

npx skills add meetkiara/postplan --skill postplan -g

Authenticate the CLI once per machine:

npx --yes @meetkiara/postplan auth login

This opens Postplan in your browser. Sign in, create a key, and paste it back into the terminal. No npm account or npm login is needed.

Publish from any repository:

npx --yes @meetkiara/postplan upload plan.html --description "Implementation plan"

Fetch a private document for an agent:

npx --yes @meetkiara/postplan fetch 'https://postplan.getorange.app/d/abc123def456' > /tmp/postplan.html

Credentials are stored globally in ~/.postplan/credentials.json with mode 0600. Headless jobs can set POSTPLAN_API_KEY instead.

How to use it effectively

Share a plan or spec

Ask a person or agent to create a self-contained HTML document, then publish it:

npx --yes @meetkiara/postplan upload plan.html --description "Payments migration plan"

Send the returned private URL to the team. Uploading the same local file again updates the same draft and preserves its version history. Use --new when you intentionally want a separate document.

A useful agent instruction is:

Create a clear implementation plan as self-contained HTML, publish it with Postplan, and return the Postplan URL.

Hand work to another person or agent

Put the current state, decisions, completed work, verification, risks, and next steps in one handover document. The next agent can consume it with the installed Postplan skill, or directly from the CLI:

npx --yes @meetkiara/postplan fetch '<postplan-url>' > /tmp/handover.html

A useful follow-up instruction is:

Read this Postplan handover, verify its current state in the repository, and continue from the listed next step: <postplan-url>

Review and comment

Open a plan in the browser, select any text, and choose Comment. Use Comment on the plan for feedback about the whole document. Anyone on the team can reply, resolve, or reopen a thread; only the author can edit or delete their comment. Comments stay attached to their quoted text across versions and are marked when a new version no longer contains it.

Agents work the same threads from the CLI:

npx --yes @meetkiara/postplan comments '<postplan-url>'           # open threads
npx --yes @meetkiara/postplan comments reply <thread-id> "Answer"
npx --yes @meetkiara/postplan comments resolve <thread-id> --note "Fixed in v3"

A useful instruction is:

Address the open comments on this Postplan plan, upload the revision, and resolve the threads it fixes: <postplan-url>

Use it from a headless VM or CI

Create a named key from https://postplan.getorange.app/cli/auth on any browser, then provide it to the machine as a secret:

export POSTPLAN_API_KEY='pp_...'
npx --yes @meetkiara/postplan whoami

For a persistent headless-machine setup, run npx --yes @meetkiara/postplan auth set "$POSTPLAN_API_KEY" once. Browser opening is automatically skipped over SSH; POSTPLAN_NO_BROWSER=1 can force the same fallback anywhere.

Access model

• Shoo provides Google sign-in.
• Postplan accepts verified @meetkiara.ai identities and exact external emails configured as a comma-separated POSTPLAN_EXTERNAL_EMAILS list.
• All enabled team members can read all documents.
• Pins are personal to each team member and do not change anyone else's dashboard.
• Owners can update, archive, and restore their documents. Configured admins can archive or restore any document.
• Every API key is named, hashed, and revocable.
• Disabling an account invalidates its browser session and API keys.
• Stored HTML is private and streamed through the application.
• Plans may run any JavaScript. The browser viewer loads them in a sandboxed frame with an opaque origin, so plan scripts cannot read Postplan cookies or call its API; comment writes made with the session cookie must be same-origin.

Development

Requires Node.js 20+, PostgreSQL, and S3-compatible object storage.

npm install
npm test
npm start

Runtime variables:

DATABASE_URL
POSTPLAN_PUBLIC_BASE_URL
POSTPLAN_SESSION_SECRET
POSTPLAN_ADMIN_EMAILS
POSTPLAN_EXTERNAL_EMAILS
SHOO_BASE_URL
AWS_ENDPOINT_URL
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_S3_BUCKET_NAME
AWS_DEFAULT_REGION

The CLI defaults to https://postplan.getorange.app. POSTPLAN_API_URL is available only for local testing and staging.

License

MIT. This repository reuses the published [email protected] source and retains its license.