export

Files (1)

• SKILL.md

SKILL.md (first lines)

# export

Export one or more specs from the store to **Google Docs**. The browser can't call
the Drive MCP — only this session can — so the UI queues a request and the hook
routes here. The hook message lists each queued spec **id** and title.

`${CLAUDE_PLUGIN_ROOT}` below denotes the installed plugin directory. Claude and
Pi export it; Codex provides the exact value in SpecForge SessionStart context.
Substitute that value in every path and shell command. Specs live at
`~/.specforge/specs/<id>/spec.html`.

## 1. Locate the spec file

For each queued spec id:

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" comments <id> --all
```

prints `{ specId, htmlPath, ... }` (`--all` because this flow wants the full
comment history; the default payload is batch-scoped to pending threads).
`htmlPath` is the on-disk spec (clean content —
the review layer is injected only at serve time, so the file is plain house HTML).
Use the spec **title** from the hook message for the Doc title.

**A spec with child specs exports as one flat document, not as its root alone.**
A Doc has no folder, so a recipient given only the parent gets a document with
holes in it and no way to tell how much is missing. Ask the daemon for the
flattened tree instead of reading `htmlPath`:

```
curl -s "http://127.0.0.1:4180/spec/<id>?flat=1"
```

That is the root's document with every descendant appended, each in its own
section, section ids namespaced so the anchors inside it still resolve. Check
first with `curl -s "http://127.0.0.1:4180/api/spec/<id>/children"`, and use
`htmlPath` unchanged when the list is empty, which is every spec written before
child specs existed.

## 2. Mark it in-progress

So the dropdown shows "Exporting…" (the hook already does this when it routes here;
do it explicitly for a manual run):

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" export-working <id>
```

## 3. Create the Google Doc via the Drive MCP

Use the document step 1 settled on — the flattened tree for a spec with
children, `htmlPath`'s full contents for a spec without. Reading `htmlPath` here
regardless is the mistake this sentence exists to prevent: it makes a Doc of the
root alone, which is exactly the document with holes in it that step 1 is about.

Create the doc with your connected Google
Drive MCP's create-file tool (`mcp__claude_ai_Google_Drive__create_file`, or the
equivalent on whatever Drive MCP is connected):

- `title`: the spec title
- `textContent`: the full spec HTML
- `contentMimeType`: `text/html`

Drive converts HTML → a Google Doc (headings, lists, tables, bold/links survive;
the rich CSS/charts/`<script>` are dropped — this is a structural export). The
response carries `mimeType` and `viewUrl`.

**Verify the conversion:** the response `mimeType` must be
`application/vnd.google-apps.document`. If it isn't (the upload stayed an `.html`
file), delete nothing — instead re-create with the body text extracted to plain
text and `contentMimeType: text/plain` (always converts to a Doc, just unstyled).

The shareable link is the response's `viewUrl` (shape:
`https://docs.google.com/document/d/<fileId>/edit`).

## 4. Report the link back

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" export-done <id> --url "<viewUrl>"
```

On any failure (MCP not connected, auth, conversion both ways failed):

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" export-done <id> --error "<short reason>"
```

The dropdown shows the **Open Google Doc** link (or the error) on its next poll.

## 5. Report

Briefly tell the human: which spec(s) exported and the Doc link(s).

From NitinJ/specforge, MIT.

More from NitinJ/specforge