Plans

Ship the guidelines library and markdown-first authoring for implementation-plan

High completed
2026-07-12 agentics feature High effort
Objective

Implement Phase 2 of the guideline-driven plan generation proposal: replace the implementation-plan skill's prescriptive HTML rulebook with a four-document guidelines library and rewrite SKILL.md so the agent authors a Markdown spec and renders it with the bundled build-plan-html.mjs.

At a glance

Plan authors stop hand-typing 85 KB of HTML — the agent writes a small markdown spec guided by a judgment-based guidelines library, and a bundled script renders the styled interactive plan. We'll know it worked when the skill's own smoke tests pass and this very plan renders from its markdown source.

Implement Read and implement all steps in the plan at docs/plans/add-plan-guidelines-library.md — Ship the guidelines library and markdown-first authoring for implementation-plan. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-plan-guidelines-library.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome
Achieve this goal: Ship the guidelines library and markdown-first authoring for implementation-plan. The plan at docs/plans/add-plan-guidelines-library.md describes one approach — use it as reference, but optimize for the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-plan-guidelines-library.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File add-plan-guidelines-library.html
Path docs/plans/add-plan-guidelines-library.html
Spec docs/plans/add-plan-guidelines-library.md
Definition of done 0 / 5 done

Context

The story behind this plan — what prompted the work and why it matters now.

Phase 1 (plan-agent 2.18.0) shipped the deterministic renderer: build-plan-html.mjs parses a small markdown plan spec and emits the full styled HTML plan with the exact DOM contract downstream tools depend on. The skill, however, still instructed the agent to copy a 2,015-line HTML skeleton and fill placeholders by hand — roughly 60k tokens of pure mechanics per plan run. Phase 2 (this plan) inverts the authoring flow per docs/proposals/plan-generation-from-markdown-guidelines.md: guidelines carry the judgment, the spec carries the content, the renderer carries the presentation.

Files that change

Every file this plan touches, and what happens to each one.

agentics/
  • kit/plugins/plan-agent/skills/implementation-plan/guidelines/
    • planning-principles.md new falsifiable done, what/why/verify, scope discipline
    • section-catalog.md new section menu with purpose, triggers, and exact spec syntax
    • right-sizing.md new minimal/standard/deep depth profiles and calibration table
    • writing-style.md new tone and plain-language rules moved out of the workflow doc
  • kit/plugins/plan-agent/skills/implementation-plan/SKILL.md modified rewritten around explore, read guidelines, author spec, render, deliver
  • kit/plugins/plan-agent/skills/implementation-plan/reference/SKELETON.md modified now the copyable spec starter in the parser's exact format
  • tests/plugins/
    • test-goal-prompt.sh modified SKILL assertion checks the derived goal-prompt contract, not a placeholder
    • test-resources-section.sh modified Resources guidance assertion repointed to the guidelines and spec skeleton
  • kit/plugins/plan-agent/
    • README.md modified structure tree and component section reflect the pipeline
    • CHANGELOG.md modified 2.19.0 entry
  • .claude-plugin/marketplace.json modified plan-agent bumped to 2.19.0, description updated

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
todo Author the four guideline documents under skills/implementation-plan/guidelines/
Why
the prescriptive Required Structure rulebook becomes advisory judgment the agent applies per plan, loaded via progressive disclosure
Verify
all four files exist and section-catalog.md matches the syntax parseSpecMarkdown() actually accepts.
2
todo Rewrite SKILL.md around the markdown-spec pipeline while keeping workflow Steps 0-8 intact
Why
the authoring medium changes but issue ingestion, clarify, align, interview, tests, status gates, delivery, and the next-action menu orchestrate content that is unchanged
Verify
SKILL.md documents the render command, keeps the Step 8 menu contracts, and never tells the agent to hand-write plan HTML.
3
todo Rewrite reference/SKELETON.md as the spec starter
Why
the old humanized-headings skeleton used headings the renderer's parser rejects, so copying it would produce unparseable specs
Verify
the skeleton's headings and step markers match the section catalog exactly.
4
todo Update the smoke tests that pinned retired placeholder prose and bump the plugin to 2.19.0
Why
test-goal-prompt.sh and test-resources-section.sh grepped SKILL.md for {goal-prompt} and resource placeholders that the renderer now owns
Verify
the full tests/plugins suite passes and marketplace.json carries 2.19.0.

Tests

The tests that prove the change does what it promises.

Tier 1 — This plan changes application code
Objective: the markdown-first pipeline authors and renders valid plans. File: tests/plugins/test-build-plan-html.mjs; Type: smoke; Asserts: parseSpecMarkdown and the renderer round-trip every committed plan and reject malformed specs; Run: node tests/plugins/test-build-plan-html.mjs
Integration: skill contracts survive the rewrite. File: tests/plugins/test-goal-prompt.sh; Targets: SKILL.md goal-prompt contract, skeleton drawer rows; Key cases: derived prompt format documented, plan-goal meta and copyGoal wiring present
Integration: Step 8 menu unchanged. File: tests/plugins/test-step8-review-option.sh; Targets: SKILL.md next-action menu; Key cases: adaptive option swap, review foreground/background flows, graceful Agent Teams fallback

Definition of done

The plan counts as done when every statement below is true — check each one off as you verify it.

Final check

One last pass to confirm the whole change works end to end.

Render this plan's own markdown source with node kit/plugins/plan-agent/scripts/build-plan-html.mjs docs/plans/add-plan-guidelines-library.md and confirm it exits 0 and produces the styled sibling HTML — the pipeline the plan ships is the pipeline that built the plan. Then run the tests/plugins suite end to end and confirm zero failures.

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.