Plans
Implementation Plan

Add the build-proposal skill to plan-agent

completed
2026-06-15 agentics feature
Objective

Ship build-proposal — a plan-agent skill that turns a half-formed idea into a decision-complete proposal. It codifies the proposal's 8-step research→decide→author loop, the Tier 0/1/2 right-sizing gate, the canonical artifact shape, and the operating principles, then hands the result to the planning layer for the “how”.

Implement Read and implement all steps in the plan at docs/plans/add-build-proposal-skill.html — Ship build-proposal, a plan-agent skill that authors decision-complete proposals. Start from the embedded digest: awk '!f && /<script[^>]*id="plan-digest"/{f=1;next} f && /<\/script>/{exit} f' docs/plans/add-build-proposal-skill.html
File add-build-proposal-skill.html
Path docs/plans/add-build-proposal-skill.html
Acceptance criteria 0 / 9 done

Context

The source proposal-builder-skill.md codifies a thinking-partner workflow that takes a vague idea (“compare X to ours”, “should we adopt Y”) to a decision-complete proposal — grounding every claim, separating facts from decisions, driving a human decision cadence, and committing a living artifact. It is a proposal, not an execution plan: its own “Next step” is to convert it into one, and it explicitly stops at the handoff to the planning layer. The proposal locked four decisions — name proposal-builder, placement in the agentics marketplace, a dedicated docs/proposals/ dir, and a hard stop at handoff. This plan implements that handoff inside this repo. Three packaging choices were confirmed: ship it as a build-proposal skill inside the existing plan-agent plugin (invoked /plan-agent:build-proposal); bundle two trimmed worked exemplars; and wire deep-research as optional with a WebSearch/WebFetch + Explore fallback. The design-md-spec-alignment.md proposal is the Tier 2 exemplar the skill must be able to reproduce.

Files to Modify

agentics/
  • kit/plugins/plan-agent/skills/build-proposal/
    • SKILL.md new the build-proposal workflow skill
    • references/
      • artifact-shape.md new canonical proposal template
      • operating-principles.md new principles + capability map
      • example-design-md-spec-alignment.md new trimmed Tier 2 exemplar
      • example-proposal-builder-skill.md new trimmed recursive exemplar
  • kit/plugins/plan-agent/
    • .claude-plugin/plugin.json modified description update
    • CHANGELOG.md modified 2.5.0 entry
    • README.md modified document the skill
  • .claude-plugin/marketplace.json modified bump to 2.5.0, tags
  • docs/proposals/.gitkeep new artifact root scaffold
  • tests/plugins/test-build-proposal.sh new structural smoke test
  • CLAUDE.md modified plan-agent capability row

Diagram

The 8-step proposal loop the skill codifies
Step 0
Frame + tier
restate the idea; pick Tier 0/1/2
Step 1
Fan-out research
web + codebase, in parallel; ground, never speculate
Steps 2–3
Synthesize · facts vs decisions
central insight; what's known vs the human's call
Step 4
Resolve with human
recommendation-first; record + propagate every answer
Steps 5–6
Author + deepen
docs/proposals/<slug>.md; commit each round
Step 7
Converge + hand off
stop at decision-complete; hand off via /plan-agent:implementation-plan <slug>.md
Where build-proposal sits among existing capabilities
build-proposal (owns)
  • Idea → decision-complete proposal
  • Codebase + web grounding
  • Facts-vs-decisions cadence
  • Living docs/proposals/ artifact
deep-research (composes)
  • One-shot cited web report
  • Optional research delegate
  • Fallback: WebSearch/WebFetch + Explore
implementation-plan (hands off to)
  • Owns the “how”
  • Receives the decided proposal
  • Produces the HTML execution plan

Steps

1
done Scaffold the skill (and the docs/proposals/ artifact root, via a committed .gitkeep) and author SKILL.md. Frontmatter: name: build-proposal; model: opus (matching implementation-plan's research-heavy profile); omit disable-model-invocation so the skill stays model-invocable (peers omit the field); a drafted three-part description ≤200 chars whose trigger clause uses “idea / should-we / compare-and-align” wording and explicitly avoids implementation-plan's “plan document / HTML plan / write a plan file” phrasing; full allowed-tools (Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, ToolSearch, ExitPlanMode, WebSearch, WebFetch, Skill, Agent); argument-hint. Body under 500 lines — each of the 8 loop steps carrying its key imperative (e.g. “Frame: restate the idea in one line, name the domains, ask 2–3 clarifying questions if underspecified, then proceed”) — plus a runtime artifact-dir resolver — --dir flag → planAgent.proposalsDirectory setting → docs/proposals/ → default, mirroring how implementation-plan resolves plansDirectory — that mkdir -ps the resolved dir, and one-level pointers to the two references.
Why: SKILL.md is the sole runtime artifact Claude loads; its description governs ambient activation and must not collide with implementation-plan (idea / “should-we” vs. plan-document intent). The skill delegates research to deep-research via Skill and fans out via Agent/WebSearch/WebFetch, so all must be declared in allowed-tools.
Verify
grep confirms name: build-proposal, model: opus, and no disable-model-invocation line; the description is ≤200 chars, three-part, and shares no trigger phrase with implementation-plan; the body shows all three tiers and the eight numbered steps; wc -l < 500; allowed-tools lists Skill, Agent, WebSearch, WebFetch alongside ToolSearch+ExitPlanMode; the body resolves the artifact dir via --dir → planAgent.proposalsDirectory → docs/proposals/ in order; docs/proposals/.gitkeep exists.
2
done Author the artifact-shape reference. Write references/artifact-shape.md capturing the canonical proposal artifact: front-matter (status: proposal→plan, type, created), Context, Core finding (block quote), Side-by-side comparison table, Locked & resolved decisions (dated), Workstreams/options, Risks & tensions, Open questions (decisions-only), Roadmap (phased, S/M/L), Appendices.
Why: progressive disclosure keeps SKILL.md lean; the template is reference material, so it lives one level deep instead of bloating the body.
Verify
The file lists every canonical section in order and is reachable from SKILL.md via a one-level references/artifact-shape.md path.
3
done Author the operating-principles reference. Write references/operating-principles.md with (a) the ten operating principles (ground every claim, quantify, separate facts from decisions, recommendation-first questions, record & propagate, iterative deepening, parallel fan-out, surface incidental findings, commit each round, signal convergence) and (b) the relationship-to-existing-capabilities map.
Why: these are the guardrails that make the loop converge instead of gathering forever; the deep-research framing must match the chosen optional-with-fallback wiring.
Verify
Both sections present; deep-research is described as an optional delegate with a WebSearch/WebFetch + Explore fallback (not a hard dependency); the implementation-plan handoff seam (“should-we + what” → “how”) is named.
4
done Bundle the worked-example corpus (flat, one level deep). Fetch the two source docs from the external branch — e.g. gh api "repos/shawn-sandy/agentic-acss-plugins/contents/docs/proposals/proposal-builder-skill.md?ref=claude/design-md-spec-alignment-sitq7t" -H "Accept: application/vnd.github.raw" (and the docs/plans/design-md-spec-alignment.md path) — then write trimmed copies directly under references/ as example-design-md-spec-alignment.md and example-proposal-builder-skill.md (no examples/ subdir, so references stay one level deep). Trim each to front-matter + core finding + locked decisions + one appendix; stamp a header with the source URL + commit SHA/date; audit the trimmed content for inadvertent internal URLs or credentials.
Why: a built-in regression corpus — authoring the skill must reproduce shapes like these; if it can't, the body is underspecified. Flat placement honors the “file references one level deep” rule from skill-authoring.md; the SHA/date stamp makes future drift from the external source detectable.
Verify
Both references/example-*.md files exist at one level, retain valid front-matter and a core-finding block, carry a source-URL + SHA/date header, and contain no internal URLs or credentials.
5
done Register the skill in the marketplace. In .claude-plugin/marketplace.json bump plan-agent version 2.4.1 → 2.5.0 (MINOR — new skill), extend its description to name /plan-agent:build-proposal, and add tags proposal and research (singular only — drop the redundant proposals plural).
Why: marketplace.json is the canonical registry and the only version home for relative-path plugins; the new value must exceed main.
Verify
node -e "require('./.claude-plugin/marketplace.json')" parses; the plan-agent entry shows version: 2.5.0 and a description naming build-proposal; the settings JSON-validation hook passes.
6
done Sync the manifest, changelog, and docs. Update plugin.json description (no version field), add a ## 2.5.0 CHANGELOG entry dated today, add a build-proposal row + component section to the README Features table, and update the plan-agent row in the root CLAUDE.md plugin table.
Why: README-first + changelog conventions keep the manifest, changelog, and capability catalog in lockstep with the registry.
Verify
CHANGELOG has a ## 2.5.0 heading dated 2026-06-15; README lists /plan-agent:build-proposal; grep confirms plugin.json has no version key both before and after the description edit; the CLAUDE.md plan-agent row mentions build-proposal.
7
done Add a structural smoke test. Create tests/plugins/test-build-proposal.sh with numbered PASS/FAIL assertions and a failure counter (matching test-plan-digest.sh): the SKILL.md frontmatter contract; description ≤200 chars with the three-part structure (regex on the “ — ” separators) and no trigger-phrase overlap with implementation-plan; body wc -l < 500; both references and both example-*.md resolve; marketplace.json plan-agent version dynamically greater than git show origin/main:.claude-plugin/marketplace.json (not a hardcoded 2.4.1); plugin.json carries no version key; and an optional fixture slice asserting a generated docs/proposals/<slug>.md matches the canonical sections.
Why: locks the objective (skill installed, structurally complete, registered) into a re-runnable guard alongside the existing tests/plugins/*.sh family.
Verify
bash tests/plugins/test-build-proposal.sh exits 0; the activation-collision and dynamic-version assertions are present (not a hardcoded 2.4.1).

Tests

Tier 1 — Code-touching plan
Objective build-proposal skill is installed, registered, and structurally complete

File: tests/plugins/test-build-proposal.sh

Type: smoke test

Asserts: /plan-agent:build-proposal resolves — SKILL.md present with valid name/description frontmatter, the body carries the Tier 0/1/2 gate and all 8 workflow steps, both references and both example-*.md resolve (flat, one level), and marketplace.json registers plan-agent above the origin/main version (valid JSON).

Run: bash tests/plugins/test-build-proposal.sh

Unit Frontmatter & description contract

File: tests/plugins/test-build-proposal.sh

Targets: the SKILL.md YAML frontmatter and body

Key cases: name is build-proposal (kebab, no reserved words); model: opus and no disable-model-invocation line; description ≤200 chars with a three-part structure (regex on the “ — ” separators) and no trigger-phrase overlap with implementation-plan; body wc -l < 500; allowed-tools lists Skill, Agent, WebSearch, WebFetch alongside ToolSearch + ExitPlanMode.

Integration Marketplace registration & version guard

File: tests/plugins/test-build-proposal.sh (+ existing publish checks)

Targets: the .claude-plugin/marketplace.json plan-agent entry

Key cases: JSON parses; the plan-agent version is 2.5.0 and dynamically greater than git show origin/main:.claude-plugin/marketplace.json (no hardcoded 2.4.1); description names build-proposal; no version key in plugin.json.

E2E Skill produces a decision-complete proposal (guided manual)

File: manual acceptance — guided smoke

Targets: the /plan-agent:build-proposal flow end-to-end

Key cases: invoking on a sample idea writes docs/proposals/<slug>.md in the canonical shape (front-matter, core finding, locked decisions), asks recommendation-first questions, and stops at handoff without authoring an execution plan. Automatable slice: after a real invocation, grep the output file for the canonical section headings — a fixture check independent of LLM quality; the reasoning quality stays a guided manual smoke.

Acceptance Criteria

Verification

Run bash tests/plugins/test-build-proposal.sh and confirm it exits 0 (skill present and structurally complete, references + example-*.md resolve, plan-agent registered above the origin/main version with valid JSON). Load the plugin locally with claude --plugin-dir ./kit/plugins/plan-agent and confirm /plan-agent:build-proposal <a half-formed idea> activates the new skill (not implementation-plan), runs the Tier gate and 8-step loop, writes a docs/proposals/<slug>.md in the canonical shape with recommendation-first questions, and stops at the planning handoff — then confirm that artifact feeds straight into /plan-agent:implementation-plan docs/proposals/<slug>.md via its existing .md conversion path. Confirm node -e "require('./.claude-plugin/marketplace.json')" parses and the plan-agent version is 2.5.0. Finally, run /skill-reviewer:reviewing-skills on the new SKILL.md for a scored audit (description ≤200 chars, progressive disclosure, one-level references).

Completion Checklist

Required

Completion Report

No items to report — all requirements met.

Next Steps

Backfill the full regression corpus + a dogfood example check

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

In the agentics repo, extend the build-proposal skill's worked-example corpus. Vendor the remaining regression docs the source proposal lists — component-md-spec.md and plugins-refactoring.md from shawn-sandy/agentic-acss-plugins (branch claude/design-md-spec-alignment-sitq7t, docs/plans/) — flat into kit/plugins/plan-agent/skills/build-proposal/references/ as example-component-md-spec.md and example-plugins-refactoring.md, trimmed to front-matter + core finding + locked decisions and stamped with a source URL + SHA. Then add a check to tests/plugins/test-build-proposal.sh asserting every references/example-*.md file has valid front-matter and a core-finding block. Bump the plan-agent patch version in .claude-plugin/marketplace.json and add a CHANGELOG entry.
Add a /plan-agent:build-proposal-bg background dispatcher

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

In the agentics repo, add a background dispatcher for the build-proposal skill, mirroring kit/plugins/plan-agent/commands/review-plan-bg.md. Create kit/plugins/plan-agent/commands/build-proposal-bg.md with frontmatter (description; allowed-tools: Agent, Bash, ToolSearch, ExitPlanMode) that exits plan mode, validates the idea argument, and dispatches a background agent invoking the build-proposal skill so a proposal can be developed without blocking the session. Add a plan-agent agent definition if the dispatch needs one. Bump the plan-agent minor version in .claude-plugin/marketplace.json, update the CHANGELOG and README, and document the new command in CLAUDE.md.
Wish List
One-click proposal → execution-plan handoff Wish List

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

Design and build a one-click handoff from build-proposal to implementation-plan in the plan-agent plugin. When a proposal converges (decision-complete), offer a "turn this into an execution plan" action that invokes /plan-agent:implementation-plan seeded directly from the proposal's locked decisions, core finding, and workstreams — pre-filling the objective and steps so the human doesn't re-enter context. Decide whether the seam is a new flag on implementation-plan (e.g. --from-proposal <path>) or a dedicated command, and wire the proposal's docs/proposals/<slug>.md as the input.
Generated by plan-agent · 2026-06-15 · agentics
Team Review (2026-06-16 00:58:49 UTC) — 5 core reviewers, Apply all

Executive Summary

Architecturally sound and convention-aligned; the panel converged on a consistent set of concrete, high-confidence improvements rather than any blocking objection. No reviewer recommended rejection. All accepted findings were integrated into the plan in place (see Triage Outcome).

Role-by-Role

  • Architecture (sound): the handoff seam to implementation-plan had no mechanical contract; docs/proposals/ lacked a resolution hierarchy; deep-research delegation needs Skill in allowed-tools; exemplar provenance could go stale.
  • Completeness (moderately executable): Step 4 didn't say how to fetch the external-branch sources (critical); the description text was undrafted; an allowed-tools contradiction vs. the source proposal; docs/proposals/ never created; model: undecided; the body was specified by headings only.
  • Testability: the three-part-description and <500-line checks weren't mechanized; activation-collision untested; an automatable E2E slice (output-file shape) was available but unused; the hardcoded 2.4.1 comparison is drift-prone.
  • Risk (high): ambient-activation collision with implementation-plan; under-specified 8-step body; cross-repo exemplar provenance; missing docs/proposals/ dir; no plugin.json version-leak pre-check.
  • Conventions: references/examples/ nesting violates "references one level deep" (high); omit disable-model-invocation rather than set false; rename the test to test-build-proposal.sh; drop the redundant proposals tag.

Agreements & Conflicts

  • Agree (3 reviewers): docs/proposals/ must exist before runtime writes — resolved via a committed .gitkeep + a runtime mkdir -p.
  • Agree (3 reviewers): the activation boundary vs. implementation-plan needs to be real and tested — resolved via a drafted disjoint description + a collision assertion.
  • No conflicts: findings were complementary; the only tension (the source proposal's "omit allowed-tools" vs. listing tools) was resolved toward the repo's actual convention — peers list allowed-tools.

Highest-Risk Issues (all resolved)

  1. External-branch exemplar fetch unspecified (blocker) → added the gh api … vnd.github.raw command to Step 4.
  2. Ambient-activation collision → drafted a disjoint description + a test assertion; criterion 8 strengthened.
  3. docs/proposals/ missing at runtime → .gitkeep + mkdir -p; new criterion 9.
  4. references/examples/ two-level nesting → flattened to references/example-*.md.

Triage Outcome — Apply all (accepted as-is)

  • Step 1: drafted three-part description; full allowed-tools incl. Skill/Agent/WebSearch/WebFetch; model: opus; omit disable-model-invocation; per-step body imperatives; runtime mkdir -p docs/proposals + .gitkeep scaffold.
  • Step 4: gh api retrieval command; flattened to references/example-*.md; source-URL + SHA/date stamp + sensitive-content audit.
  • Step 5: dropped the redundant proposals tag (kept proposal, research).
  • Step 6: plugin.json version-leak pre-check (before and after the edit).
  • Step 7: renamed to test-build-proposal.sh; added wc -l < 500, a three-part-description regex, an activation-collision grep, and a dynamic origin/main version comparison; plus an optional output-shape fixture slice.
  • Propagated: Tests, Files, Acceptance Criteria (now 9), Verification, and the embedded digest were all updated to match; the handoff seam to implementation-plan is now concrete via its .md conversion path.
  • Post-review decision (2026-06-16): docs/proposals/ configurability — deferred at review time — was resolved per user direction to mirror plansDirectory (--dir → planAgent.proposalsDirectory → docs/proposals/ → default), now encoded in Step 1. Proposal artifacts are committed (tracked via .gitkeep), consistent with docs/plans/.