Collaborative Spec Writing & Coding Handoff

Create a new note and type a rough heading structure for your spec. Use Markdown headings to create sections like Problem, Approach, Data Model, and API Surface.

# Auth System Redesign

## Problem
Our current auth is session-based and doesn't support API keys...

## Approach
(to be filled in)

## Data Model
(to be filled in)

## API Surface
(to be filled in)

Open the agent panel and ask Moss to help flesh out sections. Unlike a linear chat, the agent writes directly into your note, so you can edit its output in place and ask for refinements.

Try prompts like:

• “Fill in the Data Model section with a Postgres schema for JWT auth with refresh tokens”
• “Add an API Surface section with REST endpoints for login, refresh, and revoke”
• “What edge cases am I missing?”

The agent inserts code blocks with schema definitions, adds bullet points for edge cases, and you refine inline. This is collaborative editing, not back-and-forth chat.

Use Moss's custom nodes to make the spec unambiguous:

• Code blocks for schema definitions, API contracts, and pseudocode
• Sketches to draw a UI wireframe or architecture diagram directly in the note
• Formulas for capacity calculations: {{86400 * 100 | 8640000}} requests/day
• Wiki links to reference related specs: [[Rate Limiting Spec]]

Insert a chart node to visualize expected load. Type /chart-line or ask the agent to generate one:

{
  "type": "line",
  "title": "Projected Auth Requests/Day",
  "data": [
    { "label": "Month 1", "value": 50000 },
    { "label": "Month 3", "value": 200000 },
    { "label": "Month 6", "value": 800000 },
    { "label": "Month 12", "value": 2000000 }
  ],
  "options": { "palette": "vibrant" }
}

Charts make your spec concrete. Stakeholders see the growth curve, and your coding agent understands the scale requirements.

When the spec is ready, use Copy as Markdown to export the entire note. All custom nodes serialize cleanly:

• Formulas become {{expr|result}}
• Charts become ```moss-chart``` blocks
• Sketches become ```moss-sketch``` blocks
• Wiki links become [[Title]]

Paste the Markdown into Claude Code as context, or drop the exported .md file into your project for Cursor or Cline to read. The spec becomes the implementation plan.