Plans
Implementation Plan

Add markdown-source conversion to the implementation-plan skill

todo
2026-06-06 agentics feature
Objective

Teach the existing implementation-plan skill to convert an existing markdown plan into a full, interactive HTML implementation plan — auto-detecting a .md source token, transcribing every section into the rich skeleton, and enriching thin areas through the built-in interview — so one skill both generates and converts plans without a second skill.

Implement Read and implement all steps in the plan at docs/plans/add-markdown-plan-conversion.html — Add markdown-source conversion to the implementation-plan skill
File add-markdown-plan-conversion.html
Path docs/plans/add-markdown-plan-conversion.html
Acceptance criteria 0 / 6 done

Context

The plan-agent plugin already turns an objective into a rich interactive HTML plan via the implementation-plan skill, and it already accepts alternate input sources — GitHub/GitLab issue refs (#n) and .html revision files ($PLAN_FILE). What it cannot do is take an existing markdown plan (the SKELETON.md shape: Context, Objective, Steps with Why/Verify, Acceptance Criteria, Verification, Next Steps, Unresolved Questions) and produce the same full HTML plan. The repo holds many such markdown plans under docs/plans/*.md.

The conversion maps almost 1:1: every SKELETON.md section has a matching placeholder in SKELETON.html ({context}, {objective}, {step-N-action}/{step-N-why}/{step-N-verify}, {criterion-N}, {end-to-end-verification}, {next-step-N-*}, {question-N-*}). The existing plan-interview:markdown-to-html skill only emits a generic render — it does not produce the interactive plan-agent format (step chips, acceptance checkboxes, implement prompt, completion checklist), so a real gap remains. Per the decision to keep one skill, this work adds a markdown-source input mode to implementation-plan rather than creating a second skill, reusing the entire downstream pipeline (frontmatter, browser render, implement/edit/exit). Fidelity is transcribe + enrich: faithfully map the markdown, then run the built-in interview to deepen thin steps and criteria.

Files to Modify

agentics/
  • .claude-plugin/
    • marketplace.json modified bump plan-agent 1.7.0 → 1.8.0; update description
  • kit/plugins/plan-agent/
    • .claude-plugin/
      • plugin.json modified update description to mention markdown-source conversion
    • skills/implementation-plan/
      • SKILL.md modified .md detection, Step 0.6 ingestion, mapping table, conversion branch, argument-hint
    • CHANGELOG.md modified add v1.8.0 entry
    • README.md modified document the markdown-source input mode

Conversion Mapping

SKELETON.md section → SKELETON.html target
How each markdown plan section maps onto the HTML skeleton placeholder or meta tag
Markdown source (SKELETON.md) HTML target (SKELETON.html)
YAML frontmatter status / type / created / repo-name<meta> tags + {status} / {type} / {created} / {repo-name}
# Plan: <title>{title} + <title>
## Context{context}
## Objective{objective}
## Steps — n. action — Why: … Verify: …{step-N-action} / {step-N-why} / {step-N-verify}
## Acceptance Criteria — - [ ] items{criterion-N} + {criteria-count}
## Verification{end-to-end-verification}
## Next Steps — label + fenced text prompt{next-step-N-label} / {next-step-N-prompt}
## Unresolved Questions — label + fenced prompt{question-N-label} / {question-N-prompt}
source filename basename<meta name="plan-source"> (provenance)

Steps

1
todo Detect a .md source token in argument parsing. Extend the "Plan file reference detection" block in SKILL.md so a first non-flag token ending in .md is captured as $MD_SOURCE, mirroring the existing .html → $PLAN_FILE rule: reduce to basename, resolve only against the plan roots (--dir / plansDirectory / docs/plans/), and fall back to AskUserQuestion when the file can't be read.
Adds a third input source consistent with issue refs and .html revision files, so /plan-agent:implementation-plan some-plan.md parses cleanly without the filename polluting the objective.
Verify
Re-read SKILL.md: the detection paragraph names .md → $MD_SOURCE with basename path-safety and graceful fallback, evaluated before objective extraction and after issue-ref detection.
2
todo Add a new Step 0.6 — Markdown Source Ingestion to the Workflow (immediately after Step 0.5 Issue Ingestion). When $MD_SOURCE is set, read the file and parse each SKELETON.md section into planning-input variables (title, context, objective, steps[] with action/why/verify, criteria[], verification, next-steps[], questions[], and frontmatter status/type/created), HTML-escaping every captured value at capture time.
Turns the file's existing prose into the structured inputs the skeleton-fill consumes; escaping at capture (& < > " ') prevents injection from arbitrary markdown content.
Verify
Convert a conforming sample plan (e.g. docs/plans/harden-plan-documenter-completion-guard.md, which uses Context/Objective/Steps/Verification headings matching SKELETON.md) and confirm each parsed section appears in the resolved inputs with special characters escaped.
3
todo Document the conversion-mapping table in SKILL.md near the new Step 0.6 — markdown section → HTML placeholder/meta-tag, covering frontmatter, title, Context, Objective, Steps (action/why/verify), Acceptance Criteria, Verification, Next Steps, and Unresolved Questions.
Makes the parse target unambiguous and prevents drift between SKELETON.md and SKELETON.html as either evolves.
Verify
The table lists every SKELETON.md section mapped to its {placeholder} / <meta> target with no section left unmapped (matches the Conversion Mapping table in this plan).
4
todo Branch Steps 0b (Explore), 1 (Clarify), and 2 (Create) for the conversion path. On the $MD_SOURCE path: the objective and section content come from the parsed file (not generated); Explore/Clarify act as enrichment only (confirm files/symbols the plan references still exist); the output filename derives from the source basename (foo.md → foo.html), re-validated against the verb-target convention and renamed if non-descriptive.
Reuses the entire downstream pipeline (frontmatter, browser render, implement/edit/exit) while sourcing content from the file rather than generating it from an objective.
Verify
Reading the branched steps shows the conversion path reuses Step 7 render and Step 8 menu unchanged and derives the output filename from the source basename.
5
todo Wire the enrich phase and provenance. Specify that on the conversion path Step 5b Interview still runs (transcribe + enrich) to deepen thin steps and acceptance criteria; carry source frontmatter (status / type / created) into the HTML meta unless a flag overrides; and add <meta name="plan-source" content="<basename>.md"> to Step 3 frontmatter for provenance.
Implements the chosen transcribe + enrich fidelity and records where the converted plan originated, so a reader can trace it back to the source markdown.
Verify
Converted HTML carries the plan-source meta, reflects interview-added detail, and flags (--type, --priority, --no-interview) still override the source frontmatter.
6
todo Bump the version and update docs. Bump marketplace.json plan-agent 1.7.0 → 1.8.0 (a MINOR — new capability), update its description and plugin.json description to mention markdown-source conversion, add a v1.8.0 CHANGELOG.md entry, and update README.md plus the SKILL argument-hint to show the <plan.md> source form.
Marketplace versioning rules require a MINOR bump for a new input mode, and user-facing docs must reflect it; version stays in marketplace.json only, never plugin.json.
Verify
marketplace.json shows 1.8.0 (and no version in plugin.json); CHANGELOG.md has the v1.8.0 entry; argument-hint and README.md mention the .md source.

Acceptance Criteria

Verification

End-to-end: run /plan-agent:implementation-plan harden-plan-documenter-completion-guard.md against an existing conforming markdown plan in docs/plans/ (this file uses Context/Objective/Steps/Verification headings matching SKELETON.md). Confirm the skill (1) auto-detects the .md token as the source, (2) parses every section into the skeleton, (3) renders the result in the browser via Step 7 with all sections populated and HTML-escaped, (4) names the output harden-plan-documenter-completion-guard.html (source basename), (5) carries the source frontmatter plus a plan-source meta tag, and (6) presents the Step 8 implement/edit/exit menu unchanged. Then re-read SKILL.md end-to-end to confirm no second skill was introduced and the conversion path is a branch of the existing workflow. Finally verify marketplace.json shows 1.8.0, plugin.json has no version, and the CHANGELOG/README/argument-hint all mention the markdown source.

Completion Checklist

Required

Completion Report

No items to report — all requirements met.

Next Steps

Add batch directory conversion

Paste this prompt into Claude to execute this follow-up:

In the plan-agent plugin's implementation-plan skill, extend the markdown-source conversion mode (which currently converts a single .md plan into an HTML implementation plan) to optionally convert every .md plan in a directory in one run. Add a --batch flag (or directory-token detection) to the SKILL.md argument parsing, loop the existing single-file conversion over each .md file under the resolved plan root, skip files already having an .html sibling unless --force is given, and report a summary table of (source .md -> output .html -> status). Keep per-file errors non-fatal so one bad file doesn't abort the batch. Bump marketplace.json plan-agent one MINOR and add a CHANGELOG entry.
Backfill existing markdown plans to HTML

Paste this prompt into Claude to execute this follow-up:

Using the implementation-plan skill's markdown-source conversion mode, convert every plan under docs/plans/*.md that does not already have an .html sibling into a full HTML implementation plan. For each, preserve the source frontmatter (status/type/created) and add the plan-source provenance meta. Do not modify the original .md files. After conversion, run /plan-agent:plans-library to rebuild the gallery index. Report a list of converted files and any that could not be parsed.
Wish List
Auto-route plan-shaped markdown from markdown-to-html Wish List

Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:

Investigate teaching the plan-interview:markdown-to-html skill to detect when its input markdown is plan-shaped (matches the SKELETON.md section structure: Context, Objective, Steps with Why/Verify, Acceptance Criteria, Verification) and, in that case, delegate to plan-agent's implementation-plan markdown-source conversion mode so it emits the rich interactive plan format instead of a generic render. Recommend whether this should be automatic, prompt-on-detection, or behind a flag, and outline the cross-plugin invocation mechanics and any risks of the two skills fighting over output format.