plan-converter_skill

Overview

This skill converts planning, analysis, and brainstorm artifacts into the standardized .task/*.json multi-file format consumed by unified-execute-with-file. It auto-detects common inputs (roadmap.jsonl, plan-note.md, conclusions.json, synthesis.json, legacy JSONL) and emits one validated TASK-{id}.json file per task in a .task/ directory or specified output path. The converter focuses on producing complete convergence fields and dependency metadata so tasks are execution-ready.

How this skill works

The converter parses CLI arguments to locate the input and optional -o output path, detects the input format, and extracts raw records using format-specific parsers. It transforms each source record into a unified task schema (identity, dependencies, convergence, files, implementation hints, context) and runs convergence-quality validation with auto-fix suggestions before writing cleaned JSON files to .task/*.json. A final summary reports record counts and any unresolved quality issues.

When to use it

• You have a roadmap.jsonl, plan-note.md, conclusions.json or synthesis.json and need execution-ready task files.
• Standardizing disparate planning artifacts into a single per-task JSON format for automated orchestration.
• Preparing tasks with explicit convergence criteria and verification steps for multi-agent workflows or CI-driven execution.
• Migrating legacy JSONL or ad-hoc markdown plans into a unified schema consumed by CLI tooling.
• Generating per-task files to populate a .task/ directory for downstream runners or review.

Best practices

• Provide session metadata (YAML frontmatter) in plan-note.md to preserve source.session_id and provenance.
• Ensure task descriptions include scope and file change hints so convergence can be generated accurately.
• Review and refine auto-generated convergence.criteria and verification entries to avoid vague language.
• Supply roadmap.jsonl with unified fields (title, description, convergence) when possible to minimize post-conversion edits.
• Use the -o flag to control output location and avoid accidental overwrites of existing .task/ folders.

Example use cases

• Convert a req-plan roadmap.jsonl into .task/ for automated multi-agent execution and tracking.
• Turn brainstorm synthesis.json into prioritized IDEA-* task files with feasibility-based effort estimates.
• Extract recommendations from conclusions.json into discrete tasks with generated definition_of_done and verification.
• Parse collaborative plan-note.md into per-domain TASK-NNN.json files, including file change directives and conflict risk.
• Normalize legacy tasks.jsonl or generic JSONL into the unified task schema for downstream CI or orchestrators.