pl8

Markdown template-based project and document management for AI agents.

pl8 is Linear/Jira + Confluence rebuilt for agents. Markdown is the storage format — human-readable, grep-able, git-friendly. Templates are the contract — example documents that agents follow by pattern matching. The CLI is the runtime. Validation is agent-driven.

Why

When AI agents manage projects across sessions, structures drift. Every new project requires boilerplate instructions explaining how to organize things. Without schema enforcement, quality degrades over time.

pl8 solves this with a simple insight: consistency is the key to quality, and consistency plus quality produces velocity. Templates define what documents look like. Agents follow the pattern. The CLI handles everything else.

Quick Start

Tell your agent that you use pl8 for project and document management, then have it run:

npx pl8

The naked command outputs everything the agent needs to know — templates, commands, workflows, frontmatter rules, and migration instructions. That's the entire onboarding.

How It Works

Templates Are Examples

A template is an example document — it shows what a filled-in document looks like. Agents see the template, understand the pattern, and produce documents that follow it. No schema language, no field types, no enum definitions. The example is the spec.

---
name: pl8.milestone
version: 1
belongs_to:
  - pl8.project
---

# {title}

## Status

Status: todo | in-progress | done | blocked

## Description

{description — what this milestone delivers and why it matters}

## Tasks

- [ ] 1. {task-description}
- [ ] 2. {task-description}
- [ ] 3. {task-description}

CLI-as-Contract

Agents interact with pl8 exclusively through CLI commands. They never need to know where files live or how they're persisted. The checkout/save workflow decouples agents from backends — the same commands work whether storage is the local filesystem, R2, or a database.

LLMs as an SDK

pl8 doesn't implement a schema engine, a content parser, or a validation rules system. It provides the scaffolding — storage, retrieval, relationships, templates — and delegates intelligence to the agent that's already running. Pattern matching, structural comparison, and content validation are agent capabilities, not CLI features.

CLI Reference

Workspace

npx pl8 init                           # Initialize workspace
npx pl8 status                         # Workspace dashboard

Documents

npx pl8 create <template> --title="…"  # Create document from template
npx pl8 find [<query>] [--template=…]  # Find documents by content or metadata
npx pl8 get <id>                       # Read a document
npx pl8 view <id>                      # Open rendered preview in browser
npx pl8 edit <id>                      # Check out for editing (starts live preview)
npx pl8 save <id>                      # Validate, persist, stop preview
npx pl8 discard <id>                   # Discard checkout, stop preview
npx pl8 validate [<id>|--all]          # Agent-driven validation
npx pl8 migrate                        # Migrate outdated documents to current templates

Templates

npx pl8 template create <name>         # Create template for editing
npx pl8 template edit <name>           # Edit existing template
npx pl8 template save <name>           # Finalize and register template
npx pl8 template list                  # List registered templates

Preview Servers

npx pl8 server list                    # List running preview servers
npx pl8 server stop [<id>]             # Stop servers (all if no ID given)

Archive

npx pl8 archive <id>                   # Archive a document
npx pl8 unarchive <id>                 # Restore an archived document
npx pl8 archive list                   # List archived documents
npx pl8 archive empty [--yes]          # Permanently delete all archived

Built-in Templates

Available immediately after pl8 init:

| Template | Purpose | Belongs To | | --------------- | ---------------------------------------------------- | ------------------------------ | | pl8.project | Top-level container — title, status, overview, notes | — | | pl8.milestone | Phase or deliverable with task checklist | pl8.project | | pl8.freeform | Minimal tracked document, no structural expectations | pl8.project, pl8.milestone |

Editing Workflow

The checkout/save cycle keeps agents decoupled from storage:

# 1. Check out a document (starts a live preview server)
npx pl8 edit billing-refactor-a3f9c12
# → Checked out to .pl8/tmp/billing-refactor-a3f9c12.md
# → Preview server running at http://localhost:53098

# 2. Agent edits the file at that path using normal file-editing tools
#    The preview auto-refreshes every second in the browser

# 3. Save changes (validates frontmatter, persists, stops preview, cleans up tmp)
npx pl8 save billing-refactor-a3f9c12

# Or discard if changes aren't needed (also stops preview)
npx pl8 discard billing-refactor-a3f9c12

Live Preview

A live preview server renders documents as HTML in the browser with auto-refresh every second. Only one preview server can run at a time.

Viewing — npx pl8 view <id> opens a read-only preview of any document. Stop it when done with npx pl8 server stop.

Editing — npx pl8 edit <id> starts a preview alongside the checkout. The server is stopped automatically by save or discard.

If a server is already running, view and edit will refuse to start another. Stop the existing server first with npx pl8 server stop.

The preview URL is printed to stdout. The server binds to all interfaces so it is reachable from remote machines (e.g. via Tailscale). Remote users should substitute localhost with the machine's hostname or IP.

Custom Templates

npx pl8 template create design-review
# → Creates tmp file at .pl8/tmp/design-review.md
# → Edit the file with your template content
# → When satisfied: npx pl8 template save design-review

Template names use dot-notation namespacing. pl8.* and pl8-* are reserved for built-ins and enforced by the CLI. Local templates need no namespace.

Relationships

Unidirectional — the child references its parent. A milestone's frontmatter points to its project. Parents never track their children, eliminating write contention when multiple agents create children concurrently.

---
id: api-redesign-c4f8a23
template: pl8.milestone
version: 1
created: 2025-06-15T10:30:00Z
updated: 2025-06-15T14:22:00Z
belongs_to:
  - billing-refactor-a3f9c12
---

Template Versioning

Templates carry an auto-incrementing integer version. Built-in templates start at version 1. When a custom template is saved over an existing one, its version is bumped automatically. Documents store the template version they were created from.

When templates evolve, run pl8 migrate to find outdated documents and get agent-driven migration instructions. The agent updates document structure to match the current template, preserving user content and asking for clarification when changes are ambiguous.

IDs

Human-readable slugs with a 7-character hash suffix for collision resistance, derived from the title and creation timestamp.

billing-refactor-a3f9c12

Validation

Mechanical — system frontmatter is validated automatically on save (ID format, template reference, timestamps, relationship integrity).

Agent-driven — the validate command outputs a document alongside its template and prompts the agent to identify structural divergence, fix what it can, and flag ambiguities for the user.

Directory Structure

my-workspace/
  .pl8/
    config.json
    templates/          # Custom templates
    tmp/                # Checked-out documents
    archive/            # Archived documents
  projects/             # pl8.project documents
    billing-refactor-a3f9c12.md
  milestones/           # pl8.milestone documents
    api-redesign-c4f8a23.md

Programmatic API

Install pl8 as a dependency to use it as a library:

npm install pl8

import {
  createDocument,
  findDocuments,
  initWorkspace,
  resolveTemplate,
  validateDocumentFrontmatter,
} from 'pl8';

License

MIT