Spec Loop Setup Doc Rendering

Name: Spec Loop Setup Doc Rendering
Author: dpolivaev

dpolivaev/spec-loop

51 installs
34 repo stars
Updated July 27, 2026
dpolivaev/spec-loop

Part of the spec-loop workflow: sets up documentation rendering so specs and plans display cleanly.

About

A spec-loop setup step that configures document rendering so specifications, plans and generated docs display cleanly in the project. A solo builder reaches for it once when bootstrapping the spec-loop workflow so the documents it produces are readable.

Sets up doc rendering for specs
One-time workflow setup
Part of the spec-loop workflow

Spec Loop Setup Doc Rendering by the numbers

51 all-time installs (skills.sh)
Ranked #802 of 1,879 Documentation skills by installs in the Skillselion catalog
Data as of Jul 29, 2026 (Skillselion catalog sync)

npx skills add https://github.com/dpolivaev/spec-loop --skill spec-loop-setup-doc-rendering

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/dpolivaev/spec-loop/spec-loop-setup-doc-rendering.svg)](https://skillselion.com/skills/dpolivaev/spec-loop/spec-loop-setup-doc-rendering)

Installs	51
repo stars	★ 34
Last updated	July 27, 2026
Repository	dpolivaev/spec-loop ↗

What it does

Part of the spec-loop workflow: sets up documentation rendering so specs and plans display cleanly.

Who is it for?

solo builders running a spec-driven development loop

Files

SKILL.mdMarkdownGitHub ↗

Use for setting up or fixing rendering of task files and glossary files.

Keep agent-only behavior in this file. Treat vscode-setup.md and jetbrains-setup.md as shared setup references rather than the place for agent-policy instructions.

Do not just restate the setup references. First gather evidence yourself from commands and accessible project-local config, then report:

what is already working,
what is missing or broken, and
what you still cannot verify directly.

After the direct checks, suggest creating small Markdown and AsciiDoc probe files to verify rendering end to end. Those probes should cover the diagram kinds the current workflow expects to use and must include at least one class diagram. Include other relevant kinds too, such as sequence, component, and Mermaid glossary diagrams.

Prefer direct checks over assigning routine checks to the user.

Follow the selected setup path:

On the JetBrains path, check Graphviz with command -v dot and

dot -V as part of PlantUML verification.

On the VS Code local-only PlantUML path, check Java with

command -v java and java -version, Graphviz with command -v dot and dot -V, and any configured local plantuml.jar path with test -f.

On the VS Code server-based path, prefer the helper-script check

path and do not run Java, Graphviz, or local plantuml.jar checks unless troubleshooting points to the local-only path.

Determine whether AsciiDoc support is required from the current project state, including glossary.adoc or explicit use of the Spec Loop AsciiDoc glossary format.

Use project-local evidence first, such as .idea/, .vscode/, and workspace files when present.

For VS Code, Cursor, and other VS Code-based IDEs, prefer the helper script check path when the server-based setup path, this skill directory, and a supported editor CLI are available.

Stay inside the project directory unless the user explicitly approves inspection of editor state outside the repository. If plugin or IDE settings cannot be verified from project-local files, ask before inspecting external editor config directories.

Ask for confirmation before changing plugins, extensions, IDE settings, or editor settings.

When the user clearly means an obvious typo fix or a trivial one-word ambiguity, confirm it plainly. Do not invoke formal clarification framing for that.

For VS Code, Cursor, and other VS Code-based IDEs, read vscode-setup.md. For JetBrains IDEs, read jetbrains-setup.md.

Use only the setup documents that actually exist here.

JetBrains Setup Reference for `spec-loop-setup-doc-rendering`

Use this reference when spec-loop-setup-doc-rendering is helping a user who works in a JetBrains IDE.

Decision rules

PlantUML support in Markdown preview is mandatory unless the user

explicitly opts out of PlantUML.

Explain the consequence of opting out: Spec Loop diagrams in Markdown will

stay as code blocks or will not preview correctly.

AsciiDoc support is mandatory when Spec Loop glossary format guidance is

installed, when an existing project glossary uses glossary.adoc, or when the configured default format for new glossaries is adoc.

Explain the consequence of skipping AsciiDoc support: glossary.adoc

will lose normal editing and preview support.

Ask for confirmation before changing plugins or IDE settings.

Detect before changing anything

Check whether the IDE already has:

a working Markdown preview,
the Markdown PlantUML extension path available,
Graphviz available as the dot command on PATH, and
AsciiDoc support whenever glossary.adoc is active or configured as the

default format for new glossaries.

If the required pieces are already in place, no JetBrains setup change is needed.

PlantUML setup

For most JetBrains IDEs:

1. Open Settings / Preferences -> Languages & Frameworks -> Markdown. 2. Ensure Markdown preview works. 3. Enable the PlantUML Markdown extension.

If Markdown preview is missing or blank, especially in Android Studio:

1. Fix the runtime or preview support first, typically by switching to a JetBrains Runtime with JCEF. 2. After preview works, enable the PlantUML Markdown extension.

If PlantUML preview shows graphviz not found, install Graphviz and ensure that the dot command is available on PATH.

Graphviz here means the dot executable. Observed field evidence shows that some JetBrains PlantUML rendering cases, including at least one class diagram case, fail with graphviz not found when Graphviz is missing or not configured. This reference does not claim that every JetBrains PlantUML preview always requires Graphviz, only that it must be checked on this path and treated as required when that error appears.

AsciiDoc setup

Install the AsciiDoc plugin.

If glossary.adoc is active or configured as the default format for new glossaries, also ensure the preview path needed by the plugin works in the current IDE/runtime.

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_NAME="$(basename "$0")"
REQUIRED_EXTENSIONS=(
  "myml.vscode-markdown-plantuml-preview"
  "asciidoctor.asciidoctor-vscode"
)

usage() {
  cat <<EOF
Usage: $SCRIPT_NAME [--check|--apply|--help]

Check or apply the Spec Loop VS Code-based IDE server-based rendering setup.

Requirements:
- A supported editor CLI command on PATH: code, code-insiders,
  cursor, code.cmd, code-insiders.cmd, or cursor.cmd

This helper is intended for macOS, Linux, WSL, and Git Bash for Windows.

Actions:
- --check  Detect the supported editor CLI and report whether the
           required extensions are installed. This is the default.
- --apply  Install any missing required extensions.
- --help   Show this help.

This helper covers only the server-based path for supported
VS Code-based IDEs. It does not:
- configure local PlantUML rendering,
- automate JetBrains IDE setup, or
- edit optional IDE settings such as markdown.plantuml.server.
EOF
}

find_vscode_command() {
  local candidate
  for candidate in code code-insiders cursor code.cmd code-insiders.cmd cursor.cmd; do
    if command -v "$candidate" >/dev/null 2>&1; then
      printf '%s\n' "$candidate"
      return 0
    fi
  done
  return 1
}

list_extensions() {
  local output
  if ! output="$("$VSCODE_CMD" --list-extensions 2>&1)"; then
    printf 'Error: Failed to query editor extensions with "%s --list-extensions".\n' "$VSCODE_CMD" >&2
    printf '%s\n' "$output" >&2
    exit 1
  fi
  output=${output//$'\r'/}
  printf '%s\n' "$output"
}

extension_is_installed() {
  local extension="$1"
  printf '%s\n' "$EXTENSIONS_OUTPUT" | grep -Fxq "$extension"
}

collect_missing_extensions() {
  MISSING_EXTENSIONS=()
  local extension
  for extension in "${REQUIRED_EXTENSIONS[@]}"; do
    if ! extension_is_installed "$extension"; then
      MISSING_EXTENSIONS+=("$extension")
    fi
  done
}

print_status() {
  local extension
  printf 'Editor CLI: %s\n' "$VSCODE_CMD"
  for extension in "${REQUIRED_EXTENSIONS[@]}"; do
    if extension_is_installed "$extension"; then
      printf 'OK: %s\n' "$extension"
    else
      printf 'MISSING: %s\n' "$extension"
    fi
  done
}

install_missing_extensions() {
  local extension
  for extension in "${MISSING_EXTENSIONS[@]}"; do
    printf 'Installing: %s\n' "$extension"
    "$VSCODE_CMD" --install-extension "$extension"
  done
}

MODE="--check"
if [[ $# -gt 1 ]]; then
  usage >&2
  exit 2
elif [[ $# -eq 1 ]]; then
  MODE="$1"
fi

case "$MODE" in
  --check|--apply)
    ;;
  --help|-h)
    usage
    exit 0
    ;;
  *)
    usage >&2
    exit 2
    ;;
esac

if ! VSCODE_CMD="$(find_vscode_command)"; then
  printf 'Error: No supported editor CLI was found on PATH. Expected one of: code, code-insiders, cursor, code.cmd, code-insiders.cmd, cursor.cmd.\n' >&2
  exit 1
fi

EXTENSIONS_OUTPUT="$(list_extensions)"
collect_missing_extensions
print_status

if [[ "$MODE" == "--check" ]]; then
  if [[ ${#MISSING_EXTENSIONS[@]} -eq 0 ]]; then
    printf 'Ready: server-based rendering support is installed for the detected VS Code-based IDE.\n'
    exit 0
  fi
  printf 'Not ready: install the missing extensions or rerun with --apply.\n' >&2
  exit 1
fi

if [[ ${#MISSING_EXTENSIONS[@]} -eq 0 ]]; then
  printf 'No changes needed.\n'
  exit 0
fi

install_missing_extensions
EXTENSIONS_OUTPUT="$(list_extensions)"
collect_missing_extensions
print_status

if [[ ${#MISSING_EXTENSIONS[@]} -eq 0 ]]; then
  printf 'Done: server-based rendering support is installed for the detected VS Code-based IDE.\n'
  exit 0
fi

printf 'Error: Some required extensions are still missing after installation.\n' >&2
exit 1

VS Code-Based IDE Setup Reference for `spec-loop-setup-doc-rendering`

Use this reference when spec-loop-setup-doc-rendering is helping a user who works in Visual Studio Code, Cursor, or another VS Code-based environment.

The extension IDs and settings below apply to VS Code, Cursor, and other VS Code-based IDEs. Where this document says "VS Code", read it as the user's VS Code-based IDE unless a step explicitly narrows the scope to the helper script.

Decision rules

PlantUML support is mandatory unless the user explicitly opts out of

PlantUML.

Explain the consequence of opting out: Spec Loop diagrams in Markdown will

remain plain code blocks or will not preview correctly.

AsciiDoc support is mandatory when Spec Loop glossary format guidance is

installed, when an existing project glossary uses glossary.adoc, or when the configured default format for new glossaries is adoc.

Explain the consequence of skipping AsciiDoc support: glossary.adoc will

lose normal editing and preview support.

Ask for confirmation before changing extension state or editor settings.

Detect before changing anything

Check whether the environment already has:

PlantUML preview support for Markdown,
AsciiDoc support whenever glossary.adoc is active or configured as the

default format for new glossaries, and

for the local-only Markdown preview path, Java, Graphviz (dot on

PATH), and the local plantuml.jar.

If the required pieces for the selected path are already sufficient, report that no editor setup change is needed.

PlantUML setup options

Option A: server-based Markdown preview

Use this when the user is fine with a PlantUML server dependency.

Install:

myml.vscode-markdown-plantuml-preview

Optional setting:

markdown.plantuml.server
default: https://www.plantuml.com/plantuml

Privacy note for this option: myml.vscode-markdown-plantuml-preview sends PlantUML render URLs to the configured PlantUML server. The PlantUML diagram representation is encoded in those URLs. The default server uses HTTPS, so the URL path is encrypted in transit unless TLS is terminated or intercepted by a proxy. The PlantUML FAQ says URLs are not saved on their server, but the public service still processes the diagram during rendering. Use local-only rendering or an intranet PlantUML server when project policy forbids third-party processing of diagrams.

Use the IDE's built-in Markdown preview after installation.

The helper script scripts/setup-vscode-server-based.sh is stored in this skill's scripts/ subdirectory, both in a repository checkout and in an installed skill bundle. If you want this server-based path and can access the skill directory, you can run the script directly instead of using the interactive skill flow. For example, from this directory:

bash ./scripts/setup-vscode-server-based.sh --check
bash ./scripts/setup-vscode-server-based.sh --apply

If you are in a different working directory, run the same script by its full path.

The helper requires a supported editor CLI command on PATH (code, code-insiders, cursor, code.cmd, code-insiders.cmd, or cursor.cmd) and is intended for macOS, Linux, WSL, and Git Bash for Windows. It covers only the server-based path described here. In other VS Code-based IDEs, apply the same extension IDs and settings manually. It does not configure the local-only PlantUML path, and it does not edit the optional markdown.plantuml.server setting.