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.md — Add the build-proposal skill to plan-agent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-build-proposal-skill.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 the build-proposal skill to plan-agent. The plan at docs/plans/add-build-proposal-skill.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-build-proposal-skill.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-build-proposal-skill.md — Add the build-proposal skill to plan-agent. Brief subagents with the plan file at docs/plans/add-build-proposal-skill.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-build-proposal-skill.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-build-proposal-skill.html
Path
docs/plans/add-build-proposal-skill.html
Spec
docs/plans/add-build-proposal-skill.md
Definition of done
9 / 9 done
Context
The story behind this plan — what prompted the work and why it matters now.
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 that change
Every file this plan touches, and what happens to each one.
agentics/
kit/plugins/plan-agent/skills/build-proposal/SKILL.mdnew the build-proposal workflow skill- references/
artifact-shape.mdnew canonical proposal templateoperating-principles.mdnew principles + capability mapexample-design-md-spec-alignment.mdnew trimmed Tier 2 exemplarexample-proposal-builder-skill.mdnew trimmed recursive exemplar
.claude-plugin/plugin.jsonmodified description updateCHANGELOG.mdmodified 2.5.0 entryREADME.mdmodified document the skill.claude-plugin/marketplace.jsonmodified bump to 2.5.0, tagsdocs/proposals/.gitkeepnew artifact root scaffoldtests/plugins/test-build-proposal.shnew structural smoke testCLAUDE.mdmodified plan-agent capability row
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
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 -p s the resolved dir, and one-level pointers to the two references.
Why
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
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
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
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
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
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
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
The tests that prove the change does what it promises.
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.
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 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).
Wrapping up
Three gates that must all pass before this plan is marked completed.
Required
Completion Report
No items to report — all requirements met.