POCs & Hand-off Docs

The hand-off doc is the thing that decides whether your POC becomes a real implementation or dies in an inbox. It's also the thing every SE procrastinates on and then bangs out at 11 PM the night before the kickoff. This page breaks the procrastination with a skill, a structure, and a sequence.

What a hand-off doc is for

Three audiences read it and each wants something different.

• The customer sponsor wants to understand what was built and what it proves. They'll read the overview and maybe the architecture section.
• The customer admin or implementation partner wants to understand how to run it, extend it, and not break it. They'll read everything.
• Future-you wants to pick the project up six months later and remember what you decided. You'll skim the "decisions" section and thank yourself.

A hand-off doc that serves all three looks like a short book. Seven or eight sections, a handful of diagrams, and a known structure that doesn't change between POCs.

Install the skill

The skill lives at github.com/dylandersen/afd360-poc-docs-skill. Install it once at the user level and it's available in every Cursor project on your machine.

npx skills install github:dylandersen/afd360-poc-docs-skill

npx skills update afd360-poc-docs-skill

mkdir -p ~/.cursor/skills
cd ~/.cursor/skills
git clone https://github.com/dylandersen/afd360-poc-docs-skill.git

cd /path/to/your-poc-repo
mkdir -p .cursor/skills
git submodule add https://github.com/dylandersen/afd360-poc-docs-skill.git .cursor/skills/afd360-poc-docs-skill
git commit -m "Add afd360-poc-docs-skill"

Verify it's installed

Open Cursor, then:

1. Cursor Settings → Rules (or press Cmd+Shift+J on macOS / Ctrl+Shift+J on Windows and navigate to Rules).
2. Scroll to Agent Decides. You should see afd360-poc-docs-skill listed.
3. In chat, type / — you should see /setup-docs and /update-docs in the slash-command menu.

If neither appears, restart Cursor. If it still doesn't appear, check that ~/.cursor/skills/afd360-poc-docs-skill/SKILL.md exists and its frontmatter parses (the YAML has to be valid).

First-run: scaffold a POC docs site

The skill runs in four phases: preflight, intake, scaffold, smoke test. The whole thing is conversational — the agent asks you four questions and does the rest.

/setup-docs

cd <target-dir>
pnpm install
pnpm build          # smoke test: confirms the template builds
pnpm dev            # starts http://localhost:3000

What gets scaffolded

Out of the box, the site has these top-level sections pre-populated with customer and POC context:

Each page ships as an editable .mdx with real starter content — tables, Mermaid diagrams, example callouts — not a lorem-ipsum skeleton. You edit in place instead of writing from scratch.

Incremental updates: /update-docs

Two weeks later, you shipped a new topic and need to add a Security section. Don't re-scaffold. Run:

/update-docs add-section security

The skill drops content/docs/security.mdx, updates content/docs/meta.json, and runs placeholder substitution. It touches no other files.

Available sections

Other /update-docs actions:

• /update-docs refresh-starter <slug> — re-copy the starter into an existing section (destructive; warns before overwrite).
• /update-docs resync-config — regenerate site.config.ts from fresh intake answers.

Natural language also works:

"Add a rollout-plan section to the Acme docs."

"Refresh the glossary starter in my CS Triage docs — I want to start over on that page."

The build–test–document–handoff arc

The skill is one piece. The full arc is four. Each stage has a natural way to use Cursor.

1. Build

Normal development loop. Your First Project, Debugging Apex, and the skill library do the heavy lifting.

2. Test

Don't ship a POC without tests. Agent tests, Apex tests, LWC Jest tests, and a scripted smoke check. See Running & Writing Apex Tests and Session Tracing & Agent Testing.

3. Document

This is where the afd360-poc-docs-skill fires. But the docs draw from real project artifacts:

• The data model section is generated from @force-app/main/default/objects/ using sf-diagram-mermaid.
• The agents section is generated from @force-app/main/default/genAiPlugins/ or .agent files.
• The setup section is a variation of your demo reset script.
• The troubleshooting section is the list of real issues you hit during the build. Keep a scratchpad during development. Copy the entries in at the end.

4. Hand off

Package the POC (Packaging & Hand-off), share the docs URL, and schedule the walk-through. That's the full arc.

Letting Cursor draft the prose

Once the scaffold exists, you don't write the prose by hand. You point Cursor at the real metadata.

A template prompt for a section:

Draft the "Data Model" section of the POC hand-off doc. Read
@force-app/main/default/objects/ and produce:

1. One paragraph explaining the custom objects at a high level.
2. A bulleted list naming each custom object and its purpose.
3. A Mermaid ERD using the sf-diagram-mermaid skill.
4. A one-paragraph section on "what's on the roadmap but not in this POC".

Keep the prose plain. No filler, no marketing words, no em dashes.

The agent pulls the real names and relationships from the metadata. Your job is to fix anything wrong and add the customer-specific framing the agent can't know.

Repeat the pattern for Architecture (point at @force-app/main/default/genAiPlugins/ and integration metadata), Setup (point at config/project-scratch-def.json and your reset script), and Agents & Flows (point at .agent or .genAiFunction files).

A realistic section template

Here's what the Architecture section of a hand-off doc looks like when it's done well:

## Architecture

The CS Triage POC sits across three layers.

### Salesforce

- Agentforce Builder agent: **CS Triage**
- Topics: Warranty, Billing, Shipping
- Apex services: `CaseTriageService`, `CustomerInsightService`
- LWC: `agentSummary`, `caseRouter`
- Permission set group: `CS_Agent_Demo_User`

### Data 360

- DMOs in scope: Customer_Profile__dlm, Case_History__dlm
- Segments: Active_Shippers, High_Value_Warranty
- Data actions: Enrich_Case

### External systems

- Jira: via Named Credential `AcmeJira` (OAuth 2.0, Jira admin scope)

![architecture](architecture.png)

Short. Specific. Named. The reader can open Salesforce, find the named thing, and match it to the doc. No hand-waving.

Customer-ready polish

A few things turn a draft into something you'd hand a CIO:

• A cover page. One line per thing: customer name, POC name, SE name, date, GitHub URL, install URL. The sf-diagram-nanobananapro skill makes a clean cover graphic if you want one.
• A single diagram that summarises the whole thing. See Screenshots & Diagrams.
• Named decisions. A short "Decisions" subsection in Architecture listing the two or three meaningful calls you made ("Used Agentforce Builder over Agent Script because the customer wants to extend topics declaratively"). Future-you loves this.
• A "how to extend" section. Point at the skills the customer's developers should install and the starter prompts. Every hand-off should also hand off the workflow, not just the code.

What not to ship

• Internal Slack messages, meeting notes, or customer complaints.
• Dev Hub IDs, access tokens, or anything from .env.
• Scratch-org-specific settings that don't apply to the customer's org.
• Apologies or "we didn't get to X" framing. Note what's in scope and what's not. Don't apologise for the scope.

Common traps

The docs drift from the code

The docs were right on the day you shipped and wrong within a week. Mitigate with two habits: generate the diagrams from the code (they update when the code does), and leave a note at the top of each section saying which commit SHA it was last verified against.

The docs are too long

A hand-off doc shouldn't read like a novel. Each section should land in a screen or two of content. If it's longer, split it into a child page. The skill handles this structure automatically.

The docs don't match what the customer actually asked for

Reread the discovery notes. The hand-off doc should restate the original problem in the customer's words in the first paragraph, then describe what the POC does to prove it. If you can't do that in two sentences, the docs are focused on the wrong thing.

Troubleshooting the skill

/setup-docs isn't recognised

The skill isn't registered. Check:

1. ls ~/.cursor/skills/afd360-poc-docs-skill/SKILL.md — the file has to exist.
2. Open SKILL.md and confirm the YAML frontmatter parses (name: and description: on separate lines).
3. Restart Cursor.

Preflight fails: "Node 20 detected. Fumadocs 16 requires Node 22+."

Install Node 22 with Homebrew (brew install node@22) or nvm (nvm install 22 && nvm use 22). Re-run /setup-docs.

The scaffold refuses to write into my directory

The target isn't empty. Either pick a fresh directory or pass --force (the skill will warn you first). Never --force into a directory with uncommitted work.

pnpm build fails after scaffold

That's a template bug, not your fault. File an issue at github.com/dylandersen/afd360-poc-docs-skill/issues with the error text. In the meantime, the agent can help you patch whichever template file is broken.

Leftover __SOMETHING__ tokens in the output

verify-placeholders.mjs should have caught this. File an issue with the filename and the token — it means the skill added a template file without wiring the replacement map.

Verification

After the docs are published, send the URL to a colleague who wasn't in the project. Ask them: "If you had to pick this up and demo it next week, would you know how?" If the answer is yes, the docs are good. If they come back with six questions, those are your missing sections.

Next moves

• If you haven't yet, install the skill and run /setup-docs against a real POC.
• Packaging & Hand-off for the install URL the docs reference.
• Screenshots & Diagrams for the visuals inside the docs.
• Subagents & Parallelism for the "build the whole docs site in parallel" pattern.