PROJECT.md

A format specification for declarative agentic engineering, a new paradigm for human+agent engineering.

Write your project as Markdown. An agent keeps the code in sync.

A tree of Markdown files mirrors your codebase 1:1. You describe what each file should do; the projectmd CLI runs your coding agent to compile those descriptions into code, and to keep both sides consistent as either one changes. Works for any generated artifact: web, game, infra, firmware, prose.

Full spec: docs/spec.md (draft v0.1)

How it works

1. A PROJECT.md at the repo root declares the two trees:

   version: "0.1.0"
   name: "Acme"
   description: "..."
   codebase: "."         # your real code
   project: "./project"  # the Markdown mirror

2. Each Markdown file in the mirror describes one file in the codebase. project/src/main.md maps to src/main.py:

   # Functionality
   Print "Hello, world!" using python's `print` function.

   No frontmatter needed. The file mapping lives in agent-managed INDEX.yaml files, not in your nodes.

3. projectmd sync diffs against the last sync point (tracked in .projectmd/sync, so it survives clones) and acts per file:

   • Spec changed: the agent regenerates the code.
   • Code changed: the agent updates the spec to match.
   • Both changed: the agent reconciles, after you confirm.
   • Unchanged: untouched.

Commands

Command	What it does
projectmd init	Create PROJECT.md and scaffold a new project
projectmd migrate	Generate the Markdown mirror from existing code
projectmd sync	Reconcile mirror and codebase (--dry-run, --yes)
projectmd status	Show what sync would do, without acting