Plans

Add an effort level to implementation-plan HTML output

Medium completed
2026-06-30 agentics feature Medium effort
Objective

Surface a Low/Medium/High effort level — auto-derived from each plan's size — as a color-coded badge, a header meta-row chip, and a plan-effort meta tag on every generated HTML plan, so a reader can gauge implementation cost at a glance before diving in.

Implement Read and implement all steps in the plan at docs/plans/add-effort-level-to-plan-html.md — Add an effort level to implementation-plan HTML output. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-effort-level-to-plan-html.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, in parallel
Achieve this goal: Add an effort level to implementation-plan HTML output. The plan at docs/plans/add-effort-level-to-plan-html.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-effort-level-to-plan-html.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.
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/add-effort-level-to-plan-html.md — Add an effort level to implementation-plan HTML output. Brief subagents with the plan file at docs/plans/add-effort-level-to-plan-html.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-effort-level-to-plan-html.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-effort-level-to-plan-html.html
Path docs/plans/add-effort-level-to-plan-html.html
Spec docs/plans/add-effort-level-to-plan-html.md
Definition of done 6 / 6 done

Context

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

plan-agent's generated HTML plans already expose status , type , created , and repo as header chips and <meta> tags, but nothing tells a reader how much work the plan represents before they commit to reading it. The skill even computes a complexity tier internally (short / medium / complex) during the Step 5b interview, yet that signal is thrown away. This plan surfaces it as an auto-derived Low / Medium / High effort level, reusing the exact pattern the status badge already uses — a data-* attribute on <html> driving a CSS-colored badge, paired with a visible chip and a machine-readable meta tag — so it ships with zero new JavaScript and no extra author input.

Files that change

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

agentics/
  • reference/SKELETON.html modified effort CSS, meta tag, header chip + badge
  • SKILL.md modified derivation rule + output requirements
  • kit/plugins/plan-agent/CHANGELOG.md modified 2.11.0 entry
  • .claude-plugin/marketplace.json modified version bump 2.10.1 → 2.11.0
  • tests/test-effort-level.sh new smoke test for effort markup

Steps

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

1
done Add the effort badge, header chip, meta tag, and CSS to SKELETON.html .
Why
Why: Reuse the proven status-badge mechanism so effort is visually consistent and needs zero new JavaScript. Add a data-effort attribute to <html> (mirroring data-status ), a <meta name="plan-effort" content="{effort}"> tag in <head> , an .effort-badge CSS rule with three color variants ( [data-effort="low"] green, medium amber, high red), a visible badge in .plan-header-actions beside the status badge, and an effort chip in the .plan-meta row. Hide the badge in @media print only if it clutters the PDF — otherwise keep it.
Verify
Open SKELETON.html in a browser with data-effort="high" hard-set: the badge renders red and reads "High", and the meta-row chip shows the effort. Grep the file for plan-effort , effort-badge , and data-effort — all three present.
2
done Define the auto-derivation rule in SKILL.md Step 2 (Create).
Why
Why: Auto-derivation keeps effort objective and free — no author judgement, no new flag. Add a deterministic rule: score from step count, distinct files in the file-tree, and the Step 5b interview complexity tier, then map to Low (≤3 steps and ≤2 files), High (≥7 steps, or ≥6 files, or the "complex" tier), Medium otherwise. Store the result as the {effort} placeholder (capitalized label for display) and the data-effort value (lowercase).
Verify
Re-read SKILL.md Step 2: the rule names all three buckets with explicit thresholds and states that both {effort} and the data-effort value derive from the same score. The interview step is referenced so the tier feeds in even when --quick skips it (fall back to step/file counts alone).
3
done Document plan-effort in SKILL.md Step 3 (Frontmatter) and HTML Output Requirements.
Why
Why: Keep the spec and the skeleton in lockstep so the agent always fills the new placeholder. List <meta name="plan-effort"> among the required meta tags in Step 3, and add a bullet to HTML Output Requirements describing the data-effort attribute, the badge, and the meta-row chip — modeled on the existing status-badge bullet.
Verify
Grep SKILL.md for plan-effort and data-effort — both appear in Step 3 and in HTML Output Requirements. The required-meta-tags sentence now lists effort alongside status/type/created.
4
done Bump plan-agent to 2.11.0 and add a CHANGELOG entry.
Why
Why: A new visible feature is a MINOR bump per the project's semver rule. Edit the plan-agent version in .claude-plugin/marketplace.json from 2.10.1 to 2.11.0 , and add a top entry to kit/plugins/plan-agent/CHANGELOG.md under an ### Added heading describing the auto-derived effort level.
Verify
grep -A1 '"name": "plan-agent"' .claude-plugin/marketplace.json region shows 2.11.0 ; head of the CHANGELOG shows the new 2.11.0 entry. The .claude/settings.json JSON-validation hook reports no errors after the edit.
5
done Add a smoke test at tests/test-effort-level.sh .
Why
Why: Lock the feature so a future skeleton edit can't silently drop it — mirrors the existing tests/test-checkbox-portability.sh . The test greps SKELETON.html and asserts it contains the plan-effort meta tag, the .effort-badge CSS rule, and a data-effort attribute. Make it executable and exit non-zero on any missing marker.
Verify
bash tests/test-effort-level.sh exits 0 against the updated skeleton. Temporarily remove the meta tag and confirm the test exits non-zero, then restore it.

Tests

The tests that prove the change does what it promises.

Tier 1 — Code-touching plan
Objective A generated plan renders an auto-derived effort level File: tests/test-effort-level.sh Type: smoke test (grep-based, no framework — matches the project's existing test-checkbox-portability.sh ) Asserts: SKELETON.html contains a <meta name="plan-effort"> tag, an .effort-badge CSS rule, and a data-effort attribute on <html> — proving every generated plan carries a visible, machine-readable effort level. Run: bash tests/test-effort-level.sh
Integration Effort badge color tracks data-effort File: tests/test-effort-level.sh Targets: the .effort-badge CSS variants in SKELETON.html Key cases: all three selectors ( [data-effort="low"] , medium , high ) are present so the rendered badge color always matches the derived level; missing any variant fails the test.

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.

Run /plan-agent:implementation-plan twice: once for a tiny objective (a one-file typo fix → expect Low ) and once for a broad objective (a multi-domain refactor → expect High ). Open both generated HTML files and confirm each renders the correct badge color, meta-row chip, and plan-effort meta tag, and that the data-effort attribute matches. Then run bash tests/test-effort-level.sh and confirm it exits 0 . Finally, confirm the existing test suite ( tests/test-checkbox-portability.sh and any skeleton smoke tests) still passes — the effort additions must not regress current rendering.

Wrapping up

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

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

Surface effort in the plans-library gallery

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

Update the plan-agent plans-library skill and its gallery template so each plan card reads the plan-effort meta tag from the HTML and renders a small effort badge, and add an effort filter (Low/Medium/High) to the gallery toolbar alongside the existing status/type filters. Plans without a plan-effort tag should render with no badge and pass all filters. Bump plan-agent minor and add a CHANGELOG entry.
Show an effort estimate range (hours/days) per level Wish List

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

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

Explore extending the plan-agent effort level beyond Low/Medium/High to an estimated time range (e.g. Low ≈ under 1h, Medium ≈ half a day, High ≈ multi-day). Investigate whether the derivation signals (step count, files touched, interview tier) are reliable enough to attach a defensible range, and propose how to render it without implying false precision. Recommend whether to ship it or keep the qualitative level only.