Trim packaged Plan skills (#1124) · rangle/agent-native@a2a3e52 · GitHub
Skip to content

Commit a2a3e52

Browse files
steve8708steve8708
authored
Trim packaged Plan skills (BuilderIO#1124)
* chore(plan): trim packaged plan skills * chore(recap): simplify sticky comment copy * fix(recap): verify public image embeds * chore(plan): reference shared wireframe guidance * chore(skills): materialize wireframe references * fix(skills): hash sibling reference files * fix(skills): add exported skill file walker * chore(plan): sync skill reference files * chore(plan): materialize wireframe references * fix(skills): refresh copied skill installs * fix(plan): refresh skill refs and harden stored data * feat(recap): add setup diagnostics * fix(plan): preserve legacy MCP alias * fix(recap-workflow): rebuild canonical plan URL (path-prefix aware) in Read plan URL step * fix(plan): sync marketplace MCP aliases * docs(recap): clarify setup defaults * fix(mcp): write config files atomically * fix(mcp): atomically update env files * fix(visual-recap skill): drop kit-tree endorsement (contradicted references/wireframe.md HTML-only rule) * fix(cli): guard node support and command typos * fix(security): encrypt clips share passwords * test(security): cover SQL gates and share passwords * fix(plan): preserve prototypes and comments * docs(security): clarify credential scoping * fix(plan): preserve version anchors and sync guidance * fix(plan): harden CLI and block interactions * fix(plan): improve install and recap flows * fix(plan): protect config writes and recap navigation * feat(plan): emit lifecycle events and improve overview * fix(recap-workflow): canonical plan URL handles absolute + path-relative handoffs (self-host mounts) * test(plan): cover lifecycle event helpers * fix(plan): use shared MCP app embeds * fix(plan): smooth reader controls * chore: format visual recap workflow * test(plan): update access fixture coverage
1 parent 43547a8 commit a2a3e52

151 files changed

Lines changed: 11291 additions & 6000 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/plugins/agent-native-visual-plans/.codex-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion

‎.agents/plugins/agent-native-visual-plans/.mcp.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
{
22
"mcpServers": {
3+
"plan": {
4+
"type": "http",
5+
"url": "https://plan.agent-native.com/_agent-native/mcp"
6+
},
37
"agent-native-plans": {
48
"type": "http",
59
"url": "https://plan.agent-native.com/_agent-native/mcp"

‎.agents/plugins/agent-native-visual-plans/skills/visual-plan/SKILL.md‎

Lines changed: 57 additions & 504 deletions
Large diffs are not rendered by default.

‎.agents/plugins/agent-native-visual-plans/skills/visual-plan/references/canvas.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Canvas & artboard placement — single source of truth
2+
3+
This file is the canonical guide for how the visual-plan canvas works: artboard
4+
placement, lane layout, annotations, patching, and the legacy kit tree. Read it
5+
in full before authoring or editing any canvas/artboard content; do not author
6+
canvas layouts from memory or paraphrase these rules per mode.
7+
8+
<!-- SHARED-CORE:canvas-surface START -->
9+
10+
**Artboard placement is locked by the `surface`, not by coordinates.** The
11+
surface locks the footprint and aspect; never set artboard width/height and
12+
never use coordinates inside the wireframe HTML. Let canvas auto-placement
13+
handle simple one-row boards. For mixed-footprint canvases, board-level artboard
14+
`x`/`y` is allowed and expected when it creates clear lanes.
15+
16+
**Lay out mixed canvases in lanes.** When a canvas contains broad browser /
17+
desktop frames plus compact `mobile`, `popover`, or `panel` surfaces, do not put
18+
everything in one horizontal strip. Use board-level artboard `x`/`y` to reserve
19+
lanes with generous empty space: main flow on one row, compact surfaces in their
20+
own column or row, and loading/error states in a lower row. Keep at least 96px
21+
between rendered artboard rectangles plus room for annotation gutters. Connect
22+
only neighboring steps; never draw a long connector that skips across unrelated
23+
frames. Before handoff, inspect the top canvas at default zoom and move any
24+
frame whose label, connector, or annotation crosses another frame.
25+
26+
**Canvas annotations are designer notes on the artboard.** When a top canvas is
27+
present, sprinkle Figma-style notes near the frames they explain: a short
28+
heading, supporting text, and bullets — plain text layers, never bordered or
29+
shadowed cards, and never a box around a frame. The renderer spaces notes away
30+
from frames, so place each note by the frame it describes. Use an arrow only to
31+
point at one specific control or transition; for a broad frame-level note, write
32+
text beside the frame with no connector. Connectors are for real sequences only —
33+
never fake "Step 1 → Step 2" lines between independent states.
34+
35+
**Do not create overlapping annotations.** Anchor each ordinary note to the
36+
frame it explains with `targetId` + `placement` (top/right/bottom/left), and
37+
omit `type` or use `type: "note"`. The renderer parks notes in a gutter beside
38+
the frame and lays them out automatically. Do not use `type: "callout"`,
39+
`type: "text"`, `type: "arrow"`, x/y, or points for ordinary notes; those are
40+
freeform review-markup layers and must be reserved for intentional markup in
41+
open canvas space. Reserve arrows for a note that must point at one specific
42+
control inside a frame; a note that simply sits beside its frame needs no arrow.
43+
44+
**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted `contentPatches`
45+
(for example `patch-wireframe-html`, `patch-diagram-html`, `update-block`,
46+
`replace-blocks`, `update-canvas-annotation`) rather
47+
than regenerating the whole plan. `contentPatches` are part of the public MCP
48+
action schema, so Claude Code, Codex, Cursor, and other hosts can make surgical
49+
edits. If an agent is working from exported source files, use
50+
`read-visual-plan-source` / `patch-visual-plan-source`: `plan.mdx` holds
51+
frontmatter plus markdown/document blocks, `canvas.mdx` holds
52+
`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>`, and the
53+
patch action normalizes the MDX back into the same JSON runtime model. JSON is
54+
the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
55+
In the browser, humans edit `rich-text` prose inline; agents should still use
56+
`update-rich-text` content patches or source patches for prose, and use
57+
comments/structured patches for canvas, artboard, wireframe, and diagram edits.
58+
59+
**Never emit a titled artboard with no interior wireframe content.** Every artboard
60+
you place on the canvas must carry an `html` wireframe or reference a wireframe
61+
block via `blockId`; when using `blockId`, the referenced `wireframe` /
62+
`legacy-wireframe` block must remain in the plan. If you remove a duplicate
63+
wireframe from the document body, first move its `data` inline onto the
64+
corresponding `content.canvas.frames[*].wireframe` / `legacyWireframe`. A
65+
label-only frame or a frame pointing at a deleted block renders empty and is
66+
rejected at parse time. If you only have a title, write it as a section header or
67+
annotation, not an empty artboard.
68+
69+
**UI mockups belong in the top visual review area.** Static UI/product visuals
70+
live on the canvas; multi-step UI flows get both canvas wireframes and a
71+
prototype. When the user asks for a mockup, UI state, loading state, layout,
72+
screen, or visual comparison, make the canvas the primary home for that static
73+
visual. When the user asks for a prototype or the plan contains a sequence the
74+
reviewer must feel, keep the canvas artboards and add `content.prototype` so the
75+
top surface shows Wireframes / Prototype tabs. Architecture/code diagrams are
76+
different: keep them inline in the document, close to the recommendation they
77+
support, unless the user explicitly asks for a spatial board. Document blocks
78+
can explain, compare, or map implementation, but they should not host the
79+
primary UI mockup or prototype just because `custom-html`, screenshots, or prose
80+
are easier to produce. If the canvas/prototype surface cannot represent the
81+
requested UI fidelity, still keep the closest top-surface representation and
82+
call out or extend the needed renderer capability. A skeleton/loading mockup
83+
also lives in a canvas artboard — never move a mockup out of the canvas.
84+
85+
**Legacy kit tree.** Older plans set a `screen` array of `{ el, ...props }` kit
86+
nodes instead of `html`; the renderer still accepts and displays it, but new
87+
plans emit `html`. Do not author fresh kit-tree screens - write the HTML mockup
88+
instead. Likewise, old or imported plans may carry coordinate-based regions or
89+
free-float x/y on notes; those are legacy escape hatches the renderer still
90+
shows but you must never produce. The `surface` drives each artboard's aspect
91+
and footprint, and the gutter parks notes by `targetId` + `placement`. The only
92+
new-plan coordinate exception is deliberate board-level artboard `x`/`y` for
93+
multi-lane mixed-surface canvases; never supply artboard width/height, note
94+
coordinates, or wireframe-internal coordinates.
95+
96+
<!-- SHARED-CORE:canvas-surface END -->

‎.agents/plugins/agent-native-visual-plans/skills/visual-plan/references/document-quality.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Plan document quality — single source of truth
2+
3+
This file is the canonical quality bar for the plan document below the canvas:
4+
how it reads, which blocks to use, how open questions are surfaced, and the
5+
pre-handoff check. Read it in full before authoring the plan document; it is the
6+
quality bar. Do not write the document from memory or paraphrase these rules per
7+
mode.
8+
9+
<!-- SHARED-CORE:document-quality START -->
10+
11+
**The document is a serious technical plan, not marketing.** Write it the way a
12+
strong Claude or Codex implementation plan reads: outcome-first, prose-first,
13+
self-contained, and specific. State the objective and what "done" means, the
14+
scope and non-goals, the proposed approach with the key decisions and their
15+
rationale, ordered steps that name real files, symbols, actions, and data
16+
shapes, the risks, and a closing verification step (tests, build, or a checkable
17+
behavior). Replace vague prose with specifics; never ship a step like "make it
18+
work." No hero art, gradients, logos, nav bars, slogans, value props, giant
19+
landing-page headings, or marketing cards unless the user explicitly asks.
20+
21+
**When top visuals exist, they and the document never duplicate each other.**
22+
For UI work, the UI story lives in the top visual surface: canvas artboards for
23+
static inspection, plus prototype tabs when the flow should be functional. The
24+
document carries the technical depth the visuals cannot show — concrete
25+
file/symbol maps, API and data contracts, code snippets, migration or
26+
implementation phases, risks, and validation. For architecture/code reviews,
27+
invert that: the document is the visual surface, and each recommendation should
28+
carry its own nearby inline `diagram` / `data-model` block plus file evidence
29+
and terse Problem/Solution/Why text. For architecture/code diagrams, prefer
30+
standard two-dimensional layouts: paired before/after panels, layered diagrams,
31+
swimlanes, dependency maps, matrices, or grouped regions. Do not default to
32+
left-to-right chains; use a line only when the relationship is truly a sequence.
33+
Use native `diagram` blocks with `data.html` / `data.css` for these richer
34+
layouts; the fragment may use semantic HTML and inline SVG, and the renderer
35+
applies the viewer's sketch/clean style. Leave room for the sketch font: keep
36+
labels short, give nodes generous width, and place boundary/annotation labels in
37+
unused space instead of over nodes. For small text/SVG changes to an existing
38+
HTML diagram, use `patch-diagram-html` with a unique `find`/`replace` snippet
39+
instead of resending the whole `data.html` string. Legacy `nodes` / `edges` are
40+
only for tiny previews or genuinely linear step flows. Repeat a wireframe in the document only
41+
for a genuinely new detail view or comparison. Skip the visual surface entirely
42+
for non-visual work and write a clean rich document. For a simple binary UI
43+
visual choice, show the two directions in the canvas only; do not repeat the
44+
same options as body wireframes or prose. Put the actual
45+
choice in the bottom "Open Questions" form.
46+
47+
**Use the right block, and make it carry substance.** For the authoritative,
48+
machine-checked list of block types and their data schemas, call `get-plan-blocks`
49+
— it returns the live registry vocabulary (type, MDX tag, placement, key fields)
50+
so you never emit a block the editor cannot render or round-trip:
51+
52+
- `rich-text` for plan prose with real bold/italic/code/links and nested lists.
53+
- `annotated-code` for the file map: when a load-bearing file is worth
54+
highlighting, prefer the annotated walkthrough over a bare `code` block — carry
55+
the real, syntax-highlighted code AND anchor short margin notes to the lines
56+
that actually change (the new action, the changed schema, the wiring point), so
57+
the reader sees what matters and why instead of code for code's sake. Each
58+
annotation is `{ lines: "12" | "12-18"; label?; note }`; keep a few high-signal
59+
notes per file, not one per line. Highlight only the files worth reading; never
60+
an exhaustive list of every touched file, and never a prose-only description of
61+
a file. Drop to a plain `code` block only for a throwaway snippet with nothing
62+
to call out. When more than one file matters, group the blocks in a vertical
63+
`tabs` block (the standard tab primitive) rather than a bespoke container. If
64+
the exact code is unknown, show the smallest plausible planned shape or a
65+
commented stub naming what to fill in. (`code-tabs` and `implementation-map`
66+
are legacy: their renderers stay for old plans, but do not author new ones.)
67+
- For a decision: if the reviewer must still pick between a genuinely-open
68+
either/or, put it in the bottom Open Questions `question-form` as a `single`
69+
question — one option per real alternative, each with a short detail and
70+
`recommended: true` on the one you would choose; do not also restate the same
71+
choice elsewhere. If you have already committed to an approach, state it as
72+
settled prose or a `callout` with `tone="decision"`, optionally with a
73+
`columns` block for a side-by-side comparison of the options you weighed — not
74+
as a confusing mid-document form for a question you have already answered.
75+
- `columns` for side-by-side before/after or current/target comparisons where
76+
each side needs real nested blocks; label the columns clearly and avoid
77+
stacking comparison blocks vertically when parallel reading is the point.
78+
- `diagram` for two-dimensional architecture, dependency, data-flow, or state
79+
relationships, only when it clarifies something real. For architecture/code
80+
diagrams, prefer `data.html` / `data.css` with semantic HTML and inline SVG so
81+
the diagram can use panels, layers, matrices, arrows, annotations, and
82+
responsive layout directly. Author diagram HTML with renderer-owned primitives
83+
like `.diagram-panel`, `.diagram-card`, `.diagram-node`, `.diagram-box`,
84+
`.diagram-pill`, `.diagram-muted`, and `[data-rough]`; they map to the plan's
85+
Tailwind theme variables through `--wf-ink`, `--wf-muted`, `--wf-line`,
86+
`--wf-paper`, `--wf-card`, `--wf-accent`, `--wf-accent-soft`, `--wf-warn`, and
87+
`--wf-ok`, and switch to Excalifont plus rough.js outlines in sketchy mode. Do not
88+
set `font-family` and do not hard-code hex, rgb, or hsl colors in diagram HTML
89+
or CSS. Use legacy `nodes` / `edges` only for small previews or truly
90+
sequential flows. In architecture/code plans, prefer a repeated section rhythm:
91+
recommendation title, confidence and category badges, code-path evidence, a
92+
local before/after or current/target spatial diagram, then concise
93+
Problem/Solution/Why text. Labels must not overlap nodes, connectors, or each
94+
other.
95+
- `tabs` for multiple states, directions, or comparisons. A tab that reveals
96+
only prose usually means the plan is under-specified — include a relevant
97+
visual unless the tab is intentionally document-only.
98+
- `table`, `checklist`, `callout` for scannable structure.
99+
100+
**Open questions live at the bottom as a form when answers would change the
101+
plan.** Surface answerable unresolved decisions in a final `question-form`
102+
block titled "Open Questions" so the renderer presents it as a distinct section.
103+
That bottom form is the ONLY place that enumerates the open questions: never add
104+
a second "Open Questions" heading, list, or recap of the same questions earlier
105+
in the document. A one-line pointer in the overview prose ("a few decisions are
106+
still open — see Open Questions below") is fine, but do not reproduce the
107+
question list or a parallel questions/decisions section above it.
108+
Use `single` or `multi` for clear choices, `freeform` for constraints,
109+
`recommended: true` for the default you would pick, and option `wireframe` /
110+
`diagram` previews only when the options are not already visible in the top
111+
canvas. `single` and `multi` questions always render a write-in field so a
112+
reviewer can answer with a custom option — never add an explicit "Other" option
113+
yourself; set `allowOther: false` only when a free-text answer makes no sense.
114+
Keep non-answerable assumptions or risks as concise `callout` blocks in
115+
the relevant section. Never bury a questions/decisions wall inside the plan
116+
narrative, and never ask the same question twice.
117+
118+
**`custom-html` is a bounded escape hatch only** — a single complete fragment
119+
inside a block, never `html`/`head`/`body`/`script` tags, never a generic
120+
placeholder, density demo, or proof that custom HTML works. Prefer the native
121+
blocks for normal plans. For architecture/code reviews, use `diagram`
122+
`data.html` / `data.css` for rich local HTML/SVG diagrams instead of
123+
`custom-html`. For UI/product work, `custom-html` is never the primary home for a
124+
requested mockup, UI state, or visual comparison. If UI fidelity requires
125+
HTML/CSS, image capture, or real React/CSS, the product fix is canvas support
126+
for that artifact type, not moving the mockup into the document.
127+
128+
**Before handoff, open the plan and check it.** Fix overlap, excessive
129+
whitespace, clipped fragments, misleading inactive controls, poor contrast, and
130+
unreadable diagrams before asking for approval.
131+
132+
<!-- SHARED-CORE:document-quality END -->

‎.agents/plugins/agent-native-visual-plans/skills/visual-plan/references/exemplar.md‎

Lines changed: 48 additions & 0 deletions

0 commit comments

Comments
 (0)