feat(docs): add guided implementation prompts to task guides by aXenDeveloper · Pull Request #887 · aXenDeveloper/vitnode

aXenDeveloper · 2026-10-18T22:35:31Z

Description

What?

Guides can now declare an optional implementation field in their frontmatter. A page that has it shows a Copy implementation prompt button next to Copy Markdown.

One click copies a prompt for a coding agent. The prompt links the guide and its .md version, tells the agent to inspect the reader's project and ask a short set of questions, then implement where the reader chose.
An eye button next to it opens a preview of the exact same text, with its own copy button. Copying never requires opening the preview.
Nothing is generated by AI, and the docs site asks the reader nothing.

How it works

Schema (apps/web/src/docs/implementation/schema.ts): a strict zod schema added to the fumadocs page schema. Fields are objective, decisions (1-6), optional constraints (up to 6) and optional related (up to 4 /docs/... links). Bad metadata fails the docs build and names the file. Pages without the field are unchanged.
Prompt builder (prompt.ts): a pure function holding the one shared agent workflow:
- inspect before editing, and treat the guide's example plugin as an example, not the target;
- skip questions the user already answered, offer only choices found in the project, and ask dependent questions after their answer;
- fall back to plain numbered options when the agent has no question tool;
- explain a missing target instead of guessing;
- implement without a redundant confirmation, then report.
Links are absolute on SITE_ORIGIN.
UI (prompt-actions.tsx, prompt-preview-dialog.tsx): reuses the core CopyButton, ButtonGroup, Tooltip and Dialog. The dialog is lazy-loaded and prefetched on hover or focus, so the docs bundle only grows by the button.

Enabled guides (11)

Content Engine: Threaded replies, Public write, Containers, Publishing policies, Public pages, Search.
Notifications: Publish notifications.
Widgets: End-to-end Example, Editable Pages.
AI: AI Actions.
Moderation: Enable reports.

Fixed option sets in the decisions (publication status, container depth and ordering, policy modes, AI action actors and output kinds, delivery path and sitemap rules, report snapshot kinds) were checked against the source. There is no reactions guide or reactions feature in the codebase, so none was enabled.

Docs and tests

Contributor docs: an "Implementation prompts" section in dev/contribution.mdx, plus a pointer to it in the vitnode-docs skill.
Tests: 21 tests on Node's built-in runner in apps/web/src/tests/. They cover the prompt builder, the schema, and every guide that declares the field. No new dependency.

Why?

A reader can paste one prompt into their coding agent and get the documented feature built into their own plugin and content type, instead of the guide's example names. The preview lets them see what they are about to hand over. Each guide keeps only a few lines of metadata, and the tutorial stays the single technical reference. The metadata does not appear in the article, the .md export, /llms.txt or /llms-full.txt.

Checks

pnpm typecheck and pnpm lint in apps/web pass.
pnpm test passes (21/21).
Production pnpm build passes.
All changed TS/TSX files pass oxfmt --check. pnpm check fails on the same 103 files before and after this change; none of them are touched here.
All 11 guides return 200 as HTML and Markdown, with no metadata in the Markdown.
In headless Chromium:
- one-click copy works, and the preview text is identical to the copied text;
- the preview opens by keyboard with focus trapped in the dialog, and Escape returns focus to the button;
- the tooltip shows on hover and keyboard focus;
- after client navigation, the preview and the copy belong to the new page;
- a blocked clipboard shows the error toast;
- there is no horizontal overflow at 360px wide, in light or dark theme;
- on the production server, the first click opens the preview in about 0.4s.
The agent scenarios (answered questions, several plugins, dependent choices, missing target, no question tool, guide differing from installed code) were reviewed against the prompt text only. The prompt has not been run through an external coding agent.

🤖 Generated with Claude Code

https://claude.ai/code/session_0129cPmZegPiTUyX5NPnpdZ3

Guides can declare optional `implementation` frontmatter (objective, decisions, constraints, related links), validated by the docs schema. Pages that declare it show "Copy implementation prompt", which copies a prompt built from one shared agent workflow: read the guide, inspect the project, settle the page's decisions with the user, then implement. Enabled on Threaded replies, Publish notifications and the widgets End-to-end Example. Contributor docs explain how to author the metadata. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129cPmZegPiTUyX5NPnpdZ3

chatgpt-codex-connector · 2026-10-18T22:35:46Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-19T12:10:30.043308Z	`ee67e3d`	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

github-actions · 2026-10-18T22:35:55Z

React Doctor found no issues. 🎉

⚠️ Warning: .github/workflows/react-doctor.yml is configured incorrectly. See below to fix.

React Doctor compares against canary to report only the issues this pull request introduces. This run couldn't complete that comparison (usually a shallow CI checkout with no merge base), so it listed every issue in the changed files, including ones that already existed on canary.

Add fetch-depth: 0 to the actions/checkout step in .github/workflows/react-doctor.yml so the checkout includes the history React Doctor needs:

 jobs:
   react-doctor:
     steps:
       - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0

       - uses: millionco/react-doctor@v2

To silence this warning, set silence-missing-baseline-warning: true on the React Doctor action.

_{Reviewed by React Doctor for commit ee67e3d.}

An eye button next to "Copy implementation prompt" opens a lazily loaded dialog with the exact prompt text and its own copy button. One-click copying stays unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129cPmZegPiTUyX5NPnpdZ3

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1175ce2e27

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-10-19T08:30:40Z

+describe('pilot implementation metadata', () => {
+  const pilots = [
+    'content-engine/threads.mdx',
+    'dev/notifications/publishing.mdx',
+    'dev/widgets/end-to-end.mdx',
+  ]


Remove the static pilot-frontmatter tests

These tests hard-code the current pilot files and inspect their frontmatter, so renaming or intentionally removing a guide can break the suite while adding another implementation-enabled guide receives no coverage. The docs build already validates this metadata through docsPageSchema; keep behavioral tests for the schema and prompt builder rather than testing static documentation configuration.

AGENTS.md reference: AGENTS.md:L122-L124

Useful? React with 👍 / 👎.

Adds implementation metadata to Public write, Containers, Search, Public pages, Publishing policies, AI Actions, Editable Pages and Enable reports. Each decision offers only options the installed code supports. The schema test now covers every guide that declares the field instead of a fixed list. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129cPmZegPiTUyX5NPnpdZ3

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9192a6ad1f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-10-19T08:40:23Z

+    `## 3. Implement\n\n${list([
+      'When the required answers are in, state the resulting scope in two or three lines and start. Do not ask for another confirmation.',
+      'Reuse the existing VitNode features, permissions and UI conventions instead of building parallel ones.',
+      'Complete the server part and the public UI integration the guide describes, for the chosen target.',


Scope UI work to the selected implementation

When a reader chooses a server-only trigger—such as the background job or cron options offered by the new AI Actions metadata—the generated prompt still instructs the coding agent to complete a public UI integration. This contradicts the selected scope and can cause unrelated frontend work for guides such as AI Actions or notification publishing; make this step conditional on the guide and choices actually requiring a public UI.

Useful? React with 👍 / 👎.

…compressPublicAssets`

github-actions Bot added the 💡 Feature A new feature label Oct 18, 2026

chatgpt-codex-connector Bot reviewed Oct 19, 2026

View reviewed changes

github-actions Bot added 💡 Feature A new feature and removed 💡 Feature A new feature labels Oct 19, 2026

chatgpt-codex-connector Bot reviewed Oct 19, 2026

View reviewed changes

refactor(ssr-externals): 🔧 simplify Nitro configuration by removing `…

ee67e3d

…compressPublicAssets`

aXenDeveloper merged commit 7a92494 into canary Oct 19, 2026
7 checks passed

aXenDeveloper deleted the claude/docs-implementation-prompts branch October 19, 2026 12:20

Navigation Menu

Repository navigation

feat(docs): add guided implementation prompts to task guides - #887

feat(docs): add guided implementation prompts to task guides#887
aXenDeveloper merged 4 commits into
canaryfrom
claude/docs-implementation-prompts

aXenDeveloper commented Oct 18, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot commented Oct 18, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 18, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Oct 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Oct 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

aXenDeveloper commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What?

Why?

Checks

Uh oh!

chatgpt-codex-connector Bot commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

github-actions Bot commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Oct 19, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Oct 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aXenDeveloper commented Oct 18, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Oct 18, 2026 •

edited

Loading

github-actions Bot commented Oct 18, 2026 •

edited

Loading