jetbrains-setup.md
# 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.
scripts/setup-vscode-server-based.sh
#!/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
SKILL.md
---
name: spec-loop-setup-doc-rendering
description: >-
Help set up and troubleshoot rendering for task files and glossary
files. Use when the user asks about PlantUML, AsciiDoc, VS Code,
Cursor, other VS Code-based IDEs, JetBrains, preview rendering,
Java, or Graphviz needed to review rendered task or glossary files.
---
Use for setting up or fixing rendering of task files and glossary
files.
Keep agent-only behavior in this file. Treat [vscode-setup.md](vscode-setup.md) and
[jetbrains-setup.md](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](vscode-setup.md).
For JetBrains IDEs, read [jetbrains-setup.md](jetbrains-setup.md).
Use only the setup documents that actually exist here.
vscode-setup.md
# 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](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
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.
### Option B: local-only Markdown preview
Use this when the user wants local rendering.
Install:
- `shd101wyy.markdown-preview-enhanced`
Require:
- Java
- Graphviz (`dot` executable on `PATH`)
- local `plantuml.jar`
Here, Graphviz means the `dot` command must be installed and available on
`PATH`.
Required setting:
- `markdown-preview-enhanced.plantumlJarPath`
Use Markdown Preview Enhanced preview rather than the built-in preview.
## AsciiDoc setup
Install:
- `asciidoctor.asciidoctor-vscode`
This is required whenever `glossary.adoc` is active or configured as the
default format for new glossaries.