A Claude Code plugin that gives any project persistent, cross-session
project management. Start every session with claude @proma
and Claude works as your project manager for the entire session.
Features
ProMa handles the operational overhead so you can focus on building. Each session starts exactly where the last one ended.
Define milestones with verifiable exit criteria. Track progress across sessions. Close with human sign-off — no milestone goes dark.
Agent queue (TASK) for autonomous work. Human queue (IN) for decisions. Nobody idles — the right item goes to the right actor.
Every non-trivial choice becomes an ADR. No more "why did we do this?" three weeks later. History is always one grep away.
Automatic archival, staleness detection, self-healing. Your project state stays clean and consistent without any manual maintenance.
Boot once, PM forever. ProMa injects its protocol into your project's constitution so every new session inherits the full context.
No databases. No external services. Git-friendly files you can read, diff, version, and understand without any tooling dependency.
claude @promaAfter the one-time setup, every future session starts with a single command: claude @proma. Claude instantly loads your full project context — epics, tasks, decisions, blockers — and picks up exactly where you left off. No boot sequence. No re-explaining. Just open your terminal and get back to work.
How It Works
claude @proma.No config files. No external accounts. No infra to provision. Do the first-time setup once — every session after is a single command.
Clone the repo, then point Claude Code at the plugin directory. That's the entire install. After this, you'll never need to think about setup again.
Run /proma:init with your project name and a one-line description. ProMa creates the full proma/ directory, seeds your first epic, first task, and first inbox item.
ProMa always starts by grounding itself. Open proma/INBOX.md and fill in IN-001. This seeds all future work.
Reads your answer, injects the PM protocol into CLAUDE.md, picks the first task, and starts managing. Every future session loads this context automatically.
A focused command set for every PM action. Nothing you don't need — no sprawl.
| Command | What it does |
|---|---|
| /proma:task create | Add a new task to the backlog |
| /proma:epic create | Define a new milestone with exit criteria |
| /proma:inbox list | See pending human decisions |
| /proma:adr create | Document an architectural decision |
| /proma:tick | Run the daily sweep — archive, lint, heal |
| /proma:status | See the full project dashboard |
claude @promaThat's it. One command loads ProMa, reads your project state, checks for stale inbox items, picks the next task, and starts managing. No boot sequence. No re-explaining. ProMa remembers everything — sessions, decisions, blockers — so you don't have to.
Real-World Example
Here's how a small team uses ProMa to build an app from scratch — from the very first idea to a shipped product.
/proma:init "BakeryApp" "Online ordering for my bakery"ProMa creates a project folder and immediately asks her the first question: "What are your goals? What does the first milestone look like?"
IN-001 filed → waiting for Sarah's answerShe opens the inbox file and types: "I want customers to see my menu, pick items, choose a pickup time, and pay. First milestone: just show the menu with prices. No payment yet."
She runs /proma:boot. ProMa reads her answer, creates EPIC-02 — Menu Display with three exit criteria, breaks it into five tasks, and picks the first one to start working on.
While building the menu page, ProMa realizes there are two ways to organize menu items: by category (Cakes, Cookies, Bread) or by popularity. Instead of guessing, it files an inbox item asking Sarah.
IN-002 filed → "How should the menu be organized?"ProMa doesn't wait around — it picks the next unblocked task and keeps working on other parts while Sarah thinks.
When Sarah opens Claude Code, the daily sweep runs. It reports: 3 tasks done, 1 task blocked (waiting on her menu layout decision), IN-002 is now yellow (unanswered for 2 days). Sarah answers it: "By category please!"
ProMa unblocks the task, documents the choice as ADR-001 — Menu organized by category, and keeps going.
ADR-001 createdAll exit criteria for EPIC-02 are met. ProMa files a sign-off request: "Menu display is done — shows all items with photos, prices, and categories. Ready for your review."
Sarah reviews, approves, and ProMa automatically archives the completed tasks and advances to EPIC-03 — Shopping Cart & Checkout.
EPIC-02 closed → EPIC-03 activated/proma:statusThe dashboard shows: 1 epic complete, 1 in progress, 6 tasks done, 1 decision recorded, 0 stale inbox items. The project is on track — and everything is documented in plain text files she can read anytime.
Architecture
The KEEL protocol uses a flat directory of markdown files. No moving parts. No sync conflicts. No lock-in.
State Directory
ID Scheme
Behavioral Rules
ProMa enforces a strict operating contract. These rules prevent the most common ways agentic project management goes wrong.
No task without scope
Every TASK must belong to an open EPIC. No orphaned work items, no scope creep disguised as "misc" tasks.
Force ADRs on ambiguity
When a non-trivial choice arises, open an ADR before proceeding. Decisions are documented, not assumed.
Cut scope, don't push harder
When a milestone is at risk, reduce scope and document the cut. Never silently extend timelines or hide blockers.
Escalate stale inbox items
Human decisions age: yellow at 3 days, red at 7. Unresolved blockers surface visibly — they can't be buried.
Sync views atomically
TODO.md and PROGRESS.md are always re-rendered together. No stale views — what you read is always current.
Batch human asks
Multiple questions are consolidated into a single inbox item. No interruption storm — decisions arrive in batches.
Get Started
Install once, then start every session with claude @proma. Your PM loads instantly — no re-explaining, no lost context, no dropped balls.
Start every session with
Loads your entire project context in seconds