I Built a Project Manager That Manages Reality, Not Cards

Most project-management software makes you manage the software.

Move cards. Update fields. Change statuses. Repair dependencies. Rebuild the report. Then explain what the board was supposed to mean.

Adding a chat box does not fix that. If the user still has to translate reality into tool operations, the interface changed but the work did not.

I built Project Manager to reverse that relationship. You describe the outcome, what happened, what must remain true, and what decision you face. The skill translates that meaning into coordinated project state.

“The vendor API will not be available until September 15. The launch date cannot move. Show me the credible options.”

That is not a request to edit one task. It may affect dependencies, schedules, risks, scope, evidence, and the next decision. Project Manager traces those consequences together instead of forcing the user to perform a sequence of disconnected UI operations.

Natural language should describe reality

The core design decision is simple: the product language is the language of the project.

You can say:

• “Security approved the production design, but the monitoring rehearsal is incomplete.”
• “We only have two developers this week. Protect the work that matters most to launch.”
• “The pilot now covers two regions instead of five. The date and onboarding scope cannot move.”
• “Vendor B won because Vendor A cannot satisfy the security requirement. Carry that decision through the plan.”

Project Manager decides which internal operations are required. One statement may update work, dependencies, schedules, risks, decisions, evidence, and reporting.

The point is not to eliminate structure. The point is to stop making the user operate that structure manually.

A project is a folder, not an app account

Project truth lives in a durable, versionable Markdown folder. The minimum project has three files:

PROJECT.md   # objective and success criteria
TASKS.md     # work, dependencies, blockers, and ownership
STATUS.md    # generated current-state summary

Optional files appear only when the project needs milestones, risks, decisions, sources, traceability, change history, handoffs, or reports.

PROJECT.md and TASKS.md are authoritative. STATUS.md is derived. Git, issue trackers, source code, and storage systems can provide context, but none silently becomes project truth.

This matters because a project should remain inspectable without a vendor UI, portable between agent hosts, and reviewable through ordinary diffs.

“Done” is a claim that needs evidence

Task trackers often reward optimistic status changes. Project Manager does the opposite.

A closed issue, a commit, a file, or a confident message is not automatically proof that acceptance criteria were met. Completion advances only when the evidence supports it.

Under the hood, governed work follows a stricter lifecycle:

planned → ready → in_progress → implemented → verification → verified → done

The ordinary view stays simple—Planned, Ready, Active, Done—but the audit trail remains available. Human work can use lightweight approval where appropriate. Agent, external, and controlled work uses immutable task contracts and validated evidence manifests.

That boundary solves a growing problem: an agent saying “finished” is not the same as a verified result.

Blocking is not a status

Projects become misleading when different conditions collapse into one column.

Project Manager keeps these separate:

• Blocked work still matters but cannot advance until an obstacle clears.
• Deferred work is intentionally paused and may return.
• Cancelled work is terminal and does not satisfy dependencies.
• Incomplete dependencies are facts about the plan, not generic blocker labels.

The distinction is not academic. If cancelled work still satisfies downstream dependencies, or deferred work looks completed in a report, the project record stops being trustworthy.

Unknown stays unknown

Project-management software is very good at displaying false precision: percentage complete, confident dates, and green dashboards with weak evidence underneath.

Project Manager does not invent owners, capacity, forecasts, dates, or success coverage. If the plan cannot support an on-track judgment, the answer is not a polished guess. It is the missing fact and the decision required.

Pushback is part of the product. The skill should challenge:

• a target date with no schedule evidence;
• completion with no acceptance evidence;
• work marked ready while a dependency is unfinished;
• a plan that does not cover its success criteria; and
• a requested combination of scope, capacity, and date that cannot all hold.

A useful project manager exposes the conflict. It does not decorate it.

One record for humans and agents

Project Manager coordinates work; it does not pretend to execute every task itself.

People, agents, external systems, and the RPD software workflow can all execute work. They meet at the same boundary: a task contract defines the expected result, and an evidence manifest proves what happened.

This keeps delegation from fragmenting the project. Different executors can do the work while the project retains one coherent definition of readiness, acceptance, and completion.

Studio is a view, not a second source of truth

Conversation is the primary interface, but sometimes you need to inspect the plan visually. Project Manager Studio provides Kanban and Timeline views over the same Markdown state.

Kanban shows planned, ready, active, done, deferred, and cancelled work. Timeline shows schedules, dependencies, blockers, and date conflicts.

The important constraint is that Studio never becomes another database to synchronize. It projects the project record and protects execution history from casual edits.

Try it

In your AI agent app, ask:

Install the project-manager skill from yysun/project-manager.

Then start with the outcome instead of the board configuration:

We need to launch the new website by October 15 without interrupting the current site. Rollback must be proven before launch. Establish the project, work out what needs to be true, challenge anything vague, and surface the decisions I need to make.

From there, keep describing reality: what changed, what evidence exists, what constraint moved, and what decision is needed.

The repository, documentation, and source are available on GitHub.

Project management should not mean babysitting project-management software. It should mean keeping the plan honest as reality changes.