onplana-project-planner

name

onplana-project-planner

description

Turn a goal or a brief into an executable Onplana plan over its MCP server: write a plan.md and attach it to the project, decompose it into tasks and subtasks, set start/due dates and dependencies, assign owners, add test cases as you go, and create tasks for the downstream surfaces a change ripples to. Use this whenever an agent (Claude Code, ChatGPT / Codex, or claude.ai) is connected to the Onplana MCP server and is asked to PLAN a project rather than just execute one. Hand the result to the onplana-autonomous-agent skill to run.

Onplana project planner

This skill teaches a connected AI agent how to turn a goal into a real, runnable plan inside Onplana: a written plan document attached to the project, and a task tree (with dates, dependencies, owners, test cases, and downstream-surface tasks) that another agent or a human can pick up and execute. Onplana is a project-management platform you reach through its MCP server.

It is the front half of a pair. This skill builds the plan; the onplana-autonomous-agent skill runs it. You do NOT need to memorize the tool catalog, Onplana introspects itself: call agent_bootstrap first, then describe_capabilities / describe_schema / lookup_help_topic / search_org_knowledge whenever you need detail.

1. Connect and cold start

Connection is identical to the execution skill: the server is https://mcp.onplana.com/mcp, auth is a Bearer personal access token minted under Settings → Agents → Connect an agent. See the onplana-autonomous-agent skill, section 1, for the per-client setup (Claude Code / ChatGPT / Codex / claude.ai).

Every session, start the same two ways:

1. agent_bootstrap: identity, capabilities, entity-name index, assigned-task count. Follow its nextSteps.
2. whoami: confirm which org, your role, and your project scope. Planning creates a lot of objects (a project, tasks, assignments), so know up front whether your token is org-wide or scoped to specific projects. A 402 (plan/quota) or 403 (permission/scope) is a boundary, not a bug: log it, skip that action, keep going.

2. The planning method (the pipeline)

Planning is a pipeline, not a single call. The order matters because each stage feeds the next:

Frame → write plan.md → decompose → schedule → assign → test cases → downstream surfaces → review → hand off.

Autonomy modes. Default is high: build the whole plan, then report. If a human prefixes the run with autonomy: guided, draft each stage and wait for a go-ahead before you commit it (especially before creating the task tree and before assigning real people). When unsure which mode you are in, ask once, then proceed.

One fast path worth knowing. If the human just wants a project stood up from a structured brief, instantiate_plan creates a project + epic + tasks/subtasks + risks in one atomic call. Use it when speed matters. Use the deliberate pipeline below when you want a written plan, real dates, dependencies, assignments, test cases, and downstream coverage, which is what this skill is for.

3. Frame the work

Before you write anything:

• Find or create the target project. Planning into an existing project? get_project for its current state, members, and dates. Greenfield? create_project (name, description, dates, status PLANNING). The plan, tasks, and assignments all hang off this project id.
• Gather context. Read any brief or seed task (get_task, read_agent_brief), skim similar past work (find_similar_projects), and check who is available (list_org_members, list_teams, get_capacity).
• Learn the shape of the data in THIS org. describe_schema("Task", projectId) and describe_schema("Project") tell you the exact fields, enums, and date formats this project accepts (custom statuses, custom fields, priority values), so the tasks you create are valid the first time.

4. Write the plan, and attach it to the project

Write the plan as a markdown document and attach it before you create tasks, so there is a single human-readable source of truth the task tree is derived from.

• Ensure a place to put it. list_libraries for the project; if there is no suitable library, create_library (for example "Planning"). Then create the doc with draft_document (an editable markdown document in that library) titled plan.md or <Project> plan. If you already have the file bytes, use upload_library_document instead.
• Keep it the source of truth. As the plan evolves, update_document_content the doc so it never drifts from the task tree. read_document_content to re-read it later.

A plan.md that decomposes cleanly into tasks looks like this:

# <Project> plan

## Objective            one paragraph: the outcome and why it matters
## Scope                in scope / explicitly out of scope
## Milestones           dated checkpoints the work rolls up to
## Work breakdown       phases -> tasks -> subtasks (this becomes the task tree)
## Schedule             sequence, dependencies, the critical path, target dates
## Owners               who does what (roles or named people)
## Test strategy        acceptance criteria per deliverable, and the test cases
## Downstream surfaces  every place this change ripples to, with an owner each
## Risks                what might go wrong, and the mitigation
## Estimates & assumptions

The "Work breakdown", "Test strategy", and "Downstream surfaces" sections are the ones you turn directly into tasks in the next stages, write them so each leaf is a concrete, assignable unit of work.

5. Decompose into tasks and subtasks

Turn the work breakdown into the task tree, mirroring the plan's structure:

• Group with phases. Create an create_epic (or a milestone) per phase so the board reflects the plan's shape. move_task_to_epic to file tasks under them.
• Create the tasks. create_task for one, bulk_create_tasks for many at once. Each task gets a clear title, a description that includes its acceptance criteria, an estimate (estimatedHours), and a priority.
• Add subtasks for anything that is more than a single sitting: add_subtasks under the parent. Keep leaves small enough that "done" is unambiguous.
• Keep the breakdown honest: if a task has no acceptance criteria you can test, it is not specified well enough yet, sharpen it before moving on.

6. Schedule: dates, dependencies, milestones

A plan without dates is a wish list. Sequence and schedule the tree:

• Set dates per task. update_task (or set them at create time) for startDate and dueDate. Onplana dates are calendar-day YYYY-MM-DD, confirm the exact field names with describe_schema("Task").
• Respect the working calendar. list_working_calendars / get_working_calendar so deadlines skip weekends and holidays instead of landing on a day no one works.
• Wire dependencies. link_dependency (types FS / SS / FF / SF, with lag) so the schedule encodes the real order of operations. In guided mode, prefer propose_dependency so a human confirms the links.
• Let the engine help. critical_path_narrative explains the longest path and where the slack is; auto_schedule_proposal / gantt_optimize propose a sequenced set of dates you can review and apply.
• Set milestones. create_milestone for each dated checkpoint in the plan, so progress rolls up to something a stakeholder recognizes. Set the project's own startDate / endDate (update_project) to bound the whole effort.

7. Assign owners

Map work to people:

• Know who is available. list_org_members, list_team_members, and get_capacity to avoid overloading anyone.
• Assign. assign_task for one, bulk_assign for many. The assignee must be a member of the project, add_project_member first if needed (and allowed).
• When the call is the human's, do not hard-assign: propose_assignment surfaces a suggestion for them to approve. Always use the propose path in guided mode, and whenever you are assigning real named people to real deadlines.

8. Build in test cases as you go

Do not leave testing to the end. As you create each deliverable task, derive its acceptance criteria into explicit, checkable test cases in the same pass:

• Per-deliverable test cases. For each feature/deliverable task, add test-case subtasks (add_subtasks), one per acceptance criterion: the happy path, the edge cases, the failure modes. "Build login" gets "Test: valid login", "Test: wrong password locks after N tries", "Test: expired session redirects".
• A QA group for cross-cutting checks. Create a "Testing & QA" epic (or a milestone) for the end-to-end / regression / performance checks that span several deliverables.
• Tag them so they are findable. create_tag a test (or qa) tag and assign_tag it to every test task, so the execution agent and reviewers can filter the suite at a glance.
• This is the planning-side mirror of the execution skill's "verify before you mark it done" step: the test cases you write now are exactly what the agent runs later to earn a DONE.

9. Add tasks for downstream surfaces (if any)

A change rarely lives in one place. For anything user-facing or shared, add an explicit task for each surface it ripples to, so the work is not silently forgotten. Walk this checklist and add a task per applicable row (mark the rest N/A in the plan, with a reason):

• Documentation (user docs, help center, READMEs, runbooks)
• Tests (unit, integration, end-to-end) beyond the per-deliverable cases
• API / SDK / client consumers that must change with a contract change
• Data migrations / backfills and their rollback
• Permissions / roles / access that the change touches
• Notifications / events / webhooks / automations that should fire
• Analytics / tracking for the new behavior
• Internationalization (new user-facing strings)
• Marketing / release notes / changelog when it is customer-visible
• Seed / demo / fixtures so the new path is exercised

Record these in the plan.md "Downstream surfaces" section AND create the tasks, and fold their effort into the estimate, downstream work is not free. Some plans genuinely have no downstream surfaces (a one-off analysis); "if any" is real, just make the N/A call explicitly rather than skipping the check.

10. Review the plan before you hand it off

Sanity-check the plan you just built, the same discipline the execution skill applies before it closes a task:

• get_subtree the project / epics and confirm there are no orphan tasks, the hierarchy matches the plan.md work breakdown, and estimates roll up sensibly.
• Dates are consistent: no child due after its parent, no task starting before a dependency finishes. critical_path_narrative to confirm the critical path is what you intended.
• Every deliverable has at least one test case, and every applicable downstream surface has a task.
• Dependencies are acyclic (Onplana rejects cycles; if a link_dependency errored, the order is wrong, fix it).
• Then update_document_content so plan.md reflects the final tree, and post a short summary comment on the project: phases, task count, milestones, the critical path, and anything still needing a human decision.

11. Hand off to execution

The plan is now runnable. Either start executing it yourself with the onplana-autonomous-agent skill (loop the open tasks, do them, verify, report), or tell the human the project is planned and ready and point them at that skill. Keep plan.md updated as the work proceeds, a living plan is worth more than a pretty one.

12. Guardrails

• Stay in scope. Create objects only in the org / projects your token allows. A 403 means stop, not retry.
• Do not over-explode. A plan is a map, not every keystroke. If you are about to create hundreds of trivial subtasks, step back, the right grain is "a unit a person can own and finish", not "every line of the work".
• Be careful assigning real people to real deadlines. Prefer propose_* tools when the call is the human's, and always in guided mode.
• Pause before outward-facing actions (sending invites/messages, anything that leaves Onplana). Surface and wait, even in autonomous mode.
• Keep the plan and the tree in sync. If you change the task tree, update plan.md; if you change plan.md, reflect it in the tasks. Drift between the two is the main way a plan goes stale.
• Token budget is finite. Schedule/optimize and narrative tools draw on the org's bundled AI allowance; on aiQuotaExceeded, stop the AI calls and report, do the rest by hand.

13. Ready-to-run directive

Once connected, a human can kick off planning with one instruction. Paste something like this (adapt the goal and project):

Plan in Onplana. Create (or use) the project, write a plan.md and attach it to the project's library, then decompose it into tasks and subtasks mirroring the plan. Set start and due dates and dependencies for each task, assign owners (propose assignments rather than hard-assigning where it is my call), and add test-case subtasks for each deliverable as you go. Add tasks for any downstream surfaces the work touches (docs, tests, API, migrations, permissions, analytics). Set milestones, review the tree for orphans and date conflicts, update plan.md to match, and post a summary when done.

14. The tools you'll actually use

Everything else is one describe_capabilities call away. The workhorses:

Phase	Tools
Cold start	agent_bootstrap, whoami
Frame	get_project, create_project, find_similar_projects, describe_schema, list_org_members, list_teams
Plan doc	list_libraries, create_library, draft_document, upload_library_document, update_document_content, read_document_content
Decompose	create_epic, create_task, bulk_create_tasks, add_subtasks, move_task_to_epic
Schedule	update_task, link_dependency, propose_dependency, create_milestone, list_working_calendars, critical_path_narrative, auto_schedule_proposal, gantt_optimize, update_project
Assign	list_org_members, get_capacity, assign_task, bulk_assign, propose_assignment, add_project_member
Test cases	add_subtasks, create_tag, assign_tag
Review + fast path	get_subtree, instantiate_plan
Lookup	describe_capabilities, lookup_help_topic, search_org_knowledge