Managing Plane Tasks

Script-First Plane Management

This skill enables high-performance management of Plane projects and issues using specialized Python scripts that utilize a persistent context layer and Jinja2 templates.

[!IMPORTANT] Priority Directive: ALWAYS prioritize using the provided scripts over raw MCP tools. Every creation and update MUST be performed via Jinja2 templates to ensure visual consistency and technical fidelity. Raw MCP updates for issue descriptions are forbidden except in emergency discovery scenarios.

This skill enables agents to manage projects, issues, and states in a remote Plane PMS instance using the Plane MCP server. Every task created follows a formal task definition schema that links the work item to specific factory assets — workflows, agents, skills, scripts, knowledge, patterns, templates, blueprints, and tests.

[!NOTE] Every task is a hypothesis about which factory assets best solve the defined problem. The schema formalizes context engineering — giving agents immediate, situation-adequate consciousness of available tools, techniques, and methodologies. See Task Definition Guide for the full philosophy.

When to Use

• When you need to create, update, or track tasks in the hosted Plane instance.
• For all standard project lifecycle automation (refinement, updates, reporting).
• When you need professional, Jinja2-rendered issue documentation.
• Automation: Use create_task.py to maintain visual consistency across all issues, list_cycles.py to discover active sprint UUIDs, and list_modules.py / list_labels.py for context discovery.

Project State Mapping (UUIDs)

Prerequisites

• Plane MCP Server: Must be active and configured in mcp_config.json.
  • Use ${env:PLANE_API_TOKEN} for the API token.
• Memory MCP Server: Must be active for knowledge graph queries during task planning.
• Conda Environment: All scripts must run in conda run -p D:\Anaconda\envs\cursor-factory.

Process

Follow this script-first workflow for all Plane project management operations.

0. Context Synchronization (Persistent Layer)

Before starting any significant work, sync your local project context to ensure you have the latest UUIDs for cycles, modules, and labels.

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/sync_project_context.py

This script updates references/project_context.json, which is used by all other scripts to avoid redundant API discovery.

1. Listing & Discovery (Script-Based)

Use the utility scripts to explore the project state. These scripts are faster and more informative than raw MCP tools.

A. List Active & Upcoming Cycles

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/list_cycles.py

B. List Modules (Epics & Feature Areas)

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/list_modules.py

C. List Labels

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/list_labels.py

D. List & Filter Issues

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/list_issues.py \
    --cycle UUID \
    --module UUID \
    --labels UUID,UUID

2. Detailed Inspection (MCP Fallback)

If you need the full description or comments of a specific issue, use the MCP tool (Discovery only).

// Tool: mcp_plane_retrieve_work_item
{
  "project_id": "RESOLVED-FROM-CONTEXT",
  "work_item_id": "AGENT-XX"
}

3. Professional Task Creation (Jinja Enforcement)

Work item creation is strictly regulated. Direct MCP creation is forbidden. All tasks must be created via create_task.py to ensure they adhere to the Jinja2 visual standard and technical schema.

[!CAUTION] Creating a work item without the Jinja-rendered task.json structure is a governance violation.

Pre-Flight Checklist

Ensure you have run sync_project_context.py recently. The scripts will automatically use the resolved UUIDs from references/project_context.json.

Step A: Generate and Create Task via Jinja Template

Prepare a task_input.json in the tmp/ directory.

[!IMPORTANT] Mandatory Fields & Auto-Resolution:

• cycle: If not provided, the script will automatically use the ACTIVE_CYCLE from project_context.json.
• module: If not provided, it will default to "agent system" or fail if no logical default exists.
• priority: Defaults to "medium".
• parent: Defaults to null.

Pre-Flight Validation: Always run sync_project_context.py before create_task.py. The script now checks for the presence of mandatory structural UUIDs before attempting the Plane API call, preventing 400 errors.

[!TIP] Estimation Points: You can now use numeric Fibonacci values (e.g., 1, 3, 5, 8, 13, 21, 34, 55) for the estimate_point field. The scripts will automatically resolve these to the correct Plane UUIDs using references/project_context.json.

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/create_task.py --json tmp/task_input.json

Step B: Associate Module & Cycle

Use associate_task.py. You can find active UUIDs via list_cycles.py or the context file.

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/associate_task.py \
    --issue AGENT-XX \
    --module UUID \
    --cycle UUID

Step C: Transition Status

Use update_status.py.

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/update_status.py \
    --issue AGENT-XX \
    --state "In Progress"

4. High-Fidelity Solution Reporting (Mandatory Closure)

Every issue marked as Done MUST be accompanied by a professional solution summary rendered via the solution_comment.html.j2 template. This ensures technical fidelity and prevents shallow, uninformative closures.

Step D: Prepare Solution Data

Follow solution_definition_schema.json.

Step E: Render and Post Solution

Use the post_solution.py script. This script### Phase 5: Close the Loop (High-Fidelity) Once work is verified, generate a high-fidelity solution JSON and post it to close the task.

Example Command:

conda run -p D:\Anaconda\envs\cursor-factory python .agent/skills/routing/managing-plane-tasks/scripts/post_solution.py --issue AGENT-173 --json solution.json --close

Optimal Solution Template (solution.json):

{
    "issue": "AGENT-173",
    "title": "Knowledge Base Reorganization & Test Fixes",
    "summary": "This task accomplished a comprehensive reorganization of the .agent/knowledge base, moving over 250 files into categorized subdirectories (core, agents, tech, integration) to improve system manageability and context retrieval. Additionally, the managing-plane-tasks skill was hardened to enforce mandatory priority, module, and cycle fields, with support for active cycle auto-selection. All 54 validation tests were successfully verified under the new recursive directory structure.",
    "architectural_decisions": [
        "Recursive Globbing Strategy: Adopted **/*.json for all validation scripts and sync tools to support nested categorization, ensuring scalability as the knowledge base grows.",
        "Resource Governance: Shifted from auto-creation of modules/cycles to strict validation against existing factory assets to maintain repository integrity.",
        "Active Cycle Resolution: Implemented keyword-based resolution ('active' or 'current') to streamline task assignment and reduce manual UUID lookups during execution."
    ],
    "evolution": [
        "Modified scripts/validation/sync_knowledge_counts.py and associated unit tests to support multi-level file counting.",
        "Hardened .agent/skills/routing/managing-plane-tasks/scripts/create_task.py with stricter schema validation and cycle resolution.",
        "Standardized .agent/workflows/feature-development.md to adopt high-fidelity task management protocols."
    ],
    "files_affected": [
        ".agent/skills/routing/managing-plane-tasks/scripts/create_task.py",
        ".agent/skills/routing/managing-plane-tasks/references/task_definition_schema.json",
        ".agent/skills/routing/managing-plane-tasks/scripts/post_solution.py",
        "scripts/validation/sync_knowledge_counts.py",
        "tests/validation/test_knowledge_schema.py"
    ],
    "changes": [
        {
            "category": "Structure",
            "description": "Reorganized knowledge base into 4 categories: core, agents, tech, integration."
        },
        {
            "category": "Governance",
            "description": "Made 'priority', 'module', and 'cycle' mandatory in Plane task creation schema."
        }
    ],
    "verification": [
        {
            "type": "Automated Tests",
            "result": "54/54 tests passed across validation/test_knowledge_schema.py and unit/sync/test_sync_knowledge_counts.py"
        },
        {
            "type": "Manual Verification",
            "result": "Verified recursive directory structure and manifest.json synchronization manually."
        }
    ]
}

Best Practices

• Script-First: ALWAYS use sync_project_context.py before work and specialized scripts for all mutations.
• Jinja-Only: NEVER update issue descriptions manually or via raw MCP tools. Use create_task.py and post_solution.py.
• Existing-Only: NEVER attempt to create new modules, cycles, or labels through this skill. Use the Plane UI or authorized administrative scripts for resource creation.
• Context Reuse: Leverage the UUIDs in references/project_context.json to minimize API latency.
• Hypothesis-Driven: Treat each task as a hypothesis — declare which assets solve the problem, then validate with tests.
• High-Fidelity Closure: A task is only Done when post_solution.py has rendered the architectural decisions and verification proof.
• Cycle-Awareness: Use list_cycles.py to ensure you are working on the currently active sprint items.
• Evolve the knowledge graph: After completing tasks, update both knowledge files and memory MCP entities with learnings.

Context engineering is the foundation of intelligent agency. Every task refines the system's consciousness.