project-manager

Project Manager

Set up, organize, and operate a software project from first sketch to running system. The skill lives in two surfaces: a written discipline you (the agent) execute, and a small set of bin/ scripts that handle deterministic plumbing so you don't reinvent it every session.

What this skill is for

A user — solo founder, researcher, hobbyist — opens a chat with you and says one of:

1. "I want to build X." No folder yet. You bootstrap from intent.
2. "Take over this folder." Existing material — code, notes, half-baked plans. You absorb and produce a master plan.
3. "Where is this project at?" Live project. You read state, log activity, and recommend next.
4. "Refresh the investor brief." Live project. You regenerate a 1-page summary an interested-but-not-technical reader can grasp.

Your job is to keep the project legible to itself: the same folder should be readable by Claude Code, Gemini CLI, Codex, Cursor, Cowork, OpenClaw, or a human picking it up cold.

The operating loop (this is the spine)

Every project this skill manages runs the same loop, derived from John Liechty's AI Workflow:

1. Research and proto-plan. Enough prior research to understand the domain. Define goals. Sketch a proto-plan. Rough is fine — it's starting material, not the answer.
2. Stress-test the plan with critique. Ask the plan to be attacked, not validated. Vary the prompt angle, not the model — security perspective, UX perspective, "as someone who hates this idea". references/critique-perspectives.md has eight angles to rotate through.
3. Iterate, but bounded. Revise. One more critique pass. Stop after two passes, even if the plan still feels imperfect. The skill enforces this by writing a counter to .pm/critique-passes.json — if you find yourself wanting a third pass, that's the trap. A polished plan is not the goal; a working project is.
4. Decompose into subplans. Split the project into subparts. Each subpart runs the same loop (research → proto → critique → bounded iteration). Subplans live in plans/subplans/<name>.md.
5. Build, treating the plan as provisional. Update the plan as you build. Don't treat it as a form to be filled in — you'll learn things from the matter that change the form.
6. Test each part, then test the seams. Each subpart works in isolation before integration. Most failures live at the boundaries.

The phrasing John uses: "Plan is form, implementation is matter — but the form is provisional."

Branching at the start: new vs existing

When the user invokes you, your first job is to figure out which surface you're on. Ask if it's not obvious.

If new (no folder): Run node bin/pm.mjs init (interactively) or its equivalent. The script prompts for: project name, one-paragraph intent, target user, success criteria (measurable), known constraints, and time horizon. Capture answers, not answers-to-multiple-choice — you want their words. The script writes a starter folder layout (see "Per-project layout" below) and seeds PROJECT.md with their words and your structuring.

If existing: Read everything readable in the folder before proposing structure. Specifically read: README/notes, any *.md at the root, package manifests (package.json, pyproject.toml, Cargo.toml), and the most recent ten files by mtime. Then propose a layout as a diff — what you'd add, what you'd leave alone — and wait for approval before writing. Existing-project bootstrap is references/existing-vs-new.md.

Per-project layout

Every project this skill manages has the same skeleton. Use bin/pm.mjs init to create it; never invent a different shape — the consistency is what lets a fresh agent or a human pick the project up cold.

<project>/
├── README.md                     # one-screen orientation for any reader
├── PROJECT.md                    # the problem, the goal, the constraints
├── MASTER-PLAN.md                # current plan — provisional, edited as built
├── plans/
│   ├── proto-v1.md               # archived early plans (read-only)
│   ├── proto-v2.md
│   ├── critique-pass-1.md        # full text of pass-1 critique
│   ├── critique-pass-2.md        # full text of pass-2 critique
│   └── subplans/                 # one file per decomposed subpart
├── briefs/
│   ├── investor-brief-current.md # the latest investor-readable summary
│   └── archive/                  # daily snapshots: investor-brief-YYYY-MM-DD.md
├── logs/
│   ├── sessions/                 # one file per working session
│   ├── decisions/                # significant choices, append-only
│   └── critique/                 # raw critique transcripts
├── code/                         # the actual product — subdirs as needed
├── data/                         # project data; backed up to B2/R2 if configured
├── skills/                       # project-specific skills (optional)
├── tools/                        # project-specific helper scripts (optional)
├── CLAUDE.md                     # orientation for Claude Code
├── GEMINI.md                     # orientation for Gemini CLI
├── AGENTS.md                     # cross-tool orientation (lingua franca)
├── GWLabs.md                     # GWL-specific orientation (only on GWL projects)
├── .pm/
│   ├── state.json                # what /status and /what-now read
│   ├── critique-passes.json      # enforces the bounded-iteration rule
│   └── routing.yaml              # optional: which model for which task
└── .git/                         # local repo, initialized at bootstrap

CLAUDE.md, GEMINI.md, and AGENTS.md are generated from a single source — the project's actual state — by the bootstrap script. They differ only in the small bits each tool reads idiosyncratically; the core orientation is identical. This is deliberate: the project's truth lives in PROJECT.md and MASTER-PLAN.md, not in three drifting copies.

The commands you offer the user

These are the entry points. You can run them yourself when context makes it obvious; otherwise, suggest them.

Command	What it does
pm init	Bootstrap a new project (interactive) or absorb an existing folder (proposes diff first).
pm status	Reads .pm/state.json and the last 5 session logs. Prints: phase, blockers, last-touched files, open subplans, critique-pass counter.
pm what-now	Ranked recommendation of what to do next. Reads master plan, subplan states, blockers, critique counter, and time-since-last-investor-brief. Prints top 3, justifies each.
pm log "<entry>"	Append a one-line entry to today's session log. Use liberally; cheap memory.
pm log --decision "<entry>"	Append to logs/decisions/ (append-only ledger). Use for choices that future-you will want to know the why of.
pm brief	Regenerate briefs/investor-brief-current.md from current state, archive yesterday's. Idempotent.
pm brief --schedule	Register the daily 7 AM Cowork scheduled task. Optional --windows-task to also install a Windows Task Scheduler entry.
pm critique <plan-file>	Runs the bounded 2-pass critique. Refuses pass 3 with an explanation.
pm decompose <plan-file>	Drafts subplans from a master plan. Writes one stub per subpart.
pm github-init	Wraps gh repo create --private and pushes. Skips if gh isn't installed and prints how to install.
`pm backup <b2	r2>`
pm windows-task install	Installs a Windows Task Scheduler entry pointing at pm brief.

How to answer "what should I do next?"

This is the most-asked question and worth getting right. Read references/what-now-ranking.md for the full scoring; the gist:

1. Unblocked subplans first. A subplan is unblocked if its blockedBy field is empty in .pm/state.json.
2. Highest-leverage unblocked subplan. Leverage = (impact on master goal) × (cheapness to do now). The state file stores both as 1–5 ints; the user can edit them.
3. Promote critique gates. If the master plan is at critique-pass 0 or 1, the next thing is finish the bounded loop, not start building.
4. Promote staleness rescue. If briefs/investor-brief-current.md is more than 24h old, recommend pm brief as one of the top three (cheap, high signal-to-cost).
5. Demote everything that depends on a missing key. If a subplan needs an API key not in .env, lower it.

The output is three options with one-line justifications, not a single dictate. The user decides.

How to keep MASTER-PLAN.md honest

The master plan is the most-edited file in the project. Two rules keep it honest:

1. It is not a contract. Edit it freely as the build teaches you things. The proto-plans in plans/proto-vN.md are the historical record; MASTER-PLAN.md is current truth.
2. Each section names its critique-pass status. Every top-level section has a Status: line: proto, critiqued-1, critiqued-2-final, building, built, dropped. When promoting a section past critiqued-2-final, the script bumps .pm/critique-passes.json. The pass counter is per-section, not project-wide.

templates/MASTER-PLAN.md shows the shape.

How the daily investor brief works

The brief is regenerated daily. It reads:

• PROJECT.md (the unchanging "what is this") — for the lede.
• MASTER-PLAN.md — for the "where we're going".
• The last 7 days of logs/sessions/ — for "what moved".
• logs/decisions/ (last 14 days) — for "key choices".
• .pm/state.json — for "what's blocking".

The output is templates/INVESTOR-BRIEF.md, populated. Audience: a smart investor who is not technical. Avoid jargon, avoid dependency lists, lead with the user-visible thing. references/investor-brief-style.md has the rubric.

The default trigger is a Cowork scheduled task at 07:00 local. pm brief --schedule registers it. For unattended overnight runs (Cowork not open), pm windows-task install writes a Task Scheduler XML and registers it. On Mac/Linux, pm brief --schedule --cron prints the crontab line to add.

Backups: what the kit assumes vs requires

The kit ships with three backup paths. Each is opt-in — pm init asks, but you can defer.

• Local git + GitHub remote. The default. pm github-init runs gh repo create --private --source=. --remote=origin --push. If gh isn't installed, it prints exactly how (brew install gh / winget install GitHub.cli / apt install gh). The kit never creates accounts on the user's behalf.
• Backblaze B2 (data backup). ~$6/TB/month, cheapest at scale. pm backup b2 writes an rclone config template and a bin/backup-data.sh that does an encrypted nightly snapshot of data/. The user creates the B2 bucket and application key themselves; the script never asks for credentials in chat.
• Cloudflare R2 (data backup). S3-compatible, zero egress fees, 10 GB free. Better when data gets pulled out frequently. pm backup r2 is the symmetric command.

references/backup-options.md has the full tradeoff table including OneDrive/iCloud caveats. (Note: this workspace learned the hard way that OneDrive's file-on-demand sync engine corrupts webpack caches and serializes session locks. Don't put node_modules, .next, or any agent runtime cwd in OneDrive.)

Skill acquisition for the project

Projects often need ad-hoc skills (e.g., "convert these PDFs", "scrape this site"). When you (the agent) hit one:

1. Check whether the host runtime already has it. In Claude Code: search .claude/skills/. In OpenClaw: run openclaw skills check. In Cowork: check <available_skills>.
2. If not, check the user's master skill repo if they configured one in .pm/state.json under skillRepo.
3. Copy the skill into the project's skills/ folder so the project remains self-contained for collaborators who don't have the same global setup.

This per-project mirror is what makes the standalone kit portable — when someone clones the repo, they get the skills the project actually uses, not a list of names they have to chase.

The session log discipline

Every working session ends with pm log "<one-line summary>". That's it. Cheap, append-only, one file per day in logs/sessions/YYYY-MM-DD.md. The investor brief and pm what-now both read this — if you don't log, neither works well.

For substantive sessions (a hard problem solved, a direction changed), use pm log --decision "<entry>". The decisions log is the project's institutional memory; it's what pm what-now reads to avoid recommending something the user already considered and rejected.

When this skill should explicitly not drive

• The user is asking a one-off question ("what does this error mean?"). Answer it; don't bootstrap a project.
• The user is in a project but asking for code. Write the code; don't lecture them about the master plan.
• The user explicitly says "skip the project-manager stuff". Respect it.

Templates and references

• templates/ — populated when pm init runs. Includes PROJECT.md, MASTER-PLAN.md, INVESTOR-BRIEF.md, SUBPLAN.md, SESSION-LOG.md, CLAUDE.md, GEMINI.md, AGENTS.md, GWLabs.md, .gitignore.
• references/operating-loop.md — full text of the bounded-iteration discipline, with the trap patterns to avoid.
• references/critique-perspectives.md — eight critique angles with example prompts.
• references/decomposition.md — heuristics for splitting a master plan into subplans that don't overlap.
• references/investor-brief-style.md — the rubric and an annotated example.
• references/what-now-ranking.md — the recommendation algorithm.
• references/backup-options.md — GitHub/B2/R2/OneDrive tradeoffs.
• references/existing-vs-new.md — bootstrap branches.

Read references on demand — don't load all of them upfront. The cost of consulting one is small; the cost of carrying eight in context for every turn is not.

Standing rules

1. Never paste the user's API keys or secrets into chat or files outside .env. If a user pastes one, route them to .env and tell them.
2. Never push to GitHub without explicit permission. Local commits are fine; remote operations are not.
3. Never delete files in bulk. When cleaning up, always show the list first.
4. The plan is provisional. If the build teaches you the plan was wrong, edit the plan, don't apologize.
5. One thing at a time. When in doubt about scope, ship the smallest version that works.