bootstrap-workspace

name	bootstrap-workspace
description	Bootstrap repository-scoped VS Code workspace files for a plugin-native Alex ACT workspace. Use when a new repository lacks Markdown Preview CSS, the current workspace needs the explicit /alex-act-manager bootstrap-workspace repair path, or a repo needs deterministic .vscode/settings.json and .gitignore setup without touching user settings.
lastReviewed	2026-08-02T00:00:00.000Z

Bootstrap Workspace

Provision the current repository's workspace files for plugin-native Alex ACT use. This skill owns repository scope only.

When to fire

• A new plugin-native workspace has no .vscode/markdown-light.css
• A repository is missing workspace-scoped Markdown Preview CSS wiring
• The heir asks for /alex-act-manager bootstrap-workspace
• A workspace needs deterministic repair after manual drift in .vscode/settings.json or .gitignore

Scope

• Current repository by default, or an explicit --target repository path
• Repository files only: .vscode/markdown-light.css, .vscode/settings.json, and .gitignore when a broad .vscode ignore rule hides managed files
• Never user settings
• Never network access

Runtime

The deterministic runtime is shared at ../plugin-management/scripts/manager-operations.cjs so Manager owns one lifecycle runtime instead of duplicating scripts across commands.

Command surface:

node <plugin-management-skill>/scripts/manager-operations.cjs bootstrap-workspace [--target <path>] [--refresh-css] [--apply]

Rules:

• No --apply means preview only
• --refresh-css changes a differing existing CSS action from preserve to refresh; it still writes only with --apply
• Unknown arguments or a missing --target value fail fast
• Default target is process.cwd()
• The script prints the exact JSON plan before any write

Preview contract

Run preview first. The preview output is the decision surface.

The plan must remain a JSON object with this shape:

{
  "target": "<absolute workspace path>",
  "apply": false,
  "css": {
    "action": "create | preserve | refresh",
    "source": "<absolute source path>",
    "destination": "<absolute destination path>",
    "bytes": 0,
    "sha256": "<hex>",
    "currentSha256": "<hex-or-null>",
    "matchesSource": false
  },
  "settings": {
    "action": "create | merge | preserve",
    "destination": "<absolute settings path>",
    "changes": [
     
     
  
   
     
     
     
  

Show this exact JSON plan to the user before asking for consent.

Apply contract

Only run --apply after an explicit yes.

CSS behavior

• Source is the bundled resources/markdown-light.css in this skill
• If .vscode/markdown-light.css is absent, create it
• If it already exists, preserve it byte-for-byte
• If it differs, report both hashes; refresh it only after explicit approval by rerunning with --refresh-css --apply
• Verify the destination SHA-256 after a copy

Settings behavior

• Use set-if-absent semantics for markdown.styles
• Parse .vscode/settings.json as JSONC
• Preserve unrelated keys semantically
• Stop on malformed JSON or JSONC before any write
• Add "markdown.styles": [".vscode/markdown-light.css"] only when the key is absent
• Preserve any existing markdown.styles value exactly, including custom arrays and null
• Do not replace comments with model-authored prose; the merger owns the parse and rewrite behavior

.gitignore behavior

• Only act when a broad .vscode ignore rule hides settings.json or markdown-light.css
• Narrow that single broad rule to tracked-file exceptions
• Preserve unrelated .gitignore rules exactly
• Never widen tracking beyond the two managed workspace files

Write discipline

• Create .vscode/ only when needed
• Use atomic sibling temp files plus rename for .vscode/settings.json and .gitignore
• No network fetch, no remote version lookup, no user-scope side effects

Verification

After apply, report deterministic evidence:

• target path
• CSS action and destination
• settings action and destination
• .gitignore action and destination
• CSS byte count
• CSS SHA-256
• settings changes
• settings skips
• whether the run was idempotent or wrote files

If a second apply would change nothing, say so explicitly.

Rollback

Rollback is repository-local:

• remove .vscode/markdown-light.css only if this skill created it and the heir wants it removed
• restore .vscode/settings.json and .gitignore from version control or local backups if the heir wants to undo the merge
• never attempt rollback in user settings, because this skill never mutates them

Distinction from configure-vscode

bootstrap-workspace owns repository scope.

configure-vscode owns user scope.

Rules:

• Workspace-relative local CSS such as .vscode/markdown-light.css is supported here
• User-scope guidance must not recommend absolute local file paths for markdown.styles
• User-scope CSS guidance must use HTTPS if a user-level stylesheet is needed
• If the heir asks for user settings, route to /alex-act-manager configure-vscode

Anti-patterns

Anti-pattern	Correction
Applying without preview	Preview first, always show the JSON plan, then ask for explicit consent.
Replacing an existing workspace stylesheet	Preserve existing CSS byte-for-byte.
Hiding CSS drift behind preserve	Report both hashes and offer the explicit --refresh-css preview.
Overwriting a custom or null markdown.styles value	Set the key only when absent; preserve existing values exactly.
Rewriting .gitignore broadly	Narrow only the broad .vscode rule that blocks the two managed files.
Treating this as a user-settings repair	Repository scope only. Route user-scope work to configure-vscode.
Pulling CSS or settings from the network	Use only bundled local assets.
Reporting a package failure when the host only lacks generic skill-tool exposure	Read the installed SKILL.md directly and continue with the deterministic steps.

Related

• configure-vscode.prompt.md for user-scope VS Code settings
• Markdown and Mermaid authoring remains a Core capability; Manager bundles only the CSS asset needed for workspace setup
• plugin-management for namespaced command fallback discipline

Would Revise If

• The preview plan stops matching the runtime contract by 2026-11-02
• A second run is not idempotent by 2026-11-02
• The skill mutates user settings or reaches the network even once by 2026-11-02
• The JSONC-safe merge fails to preserve an existing custom or null markdown.styles value by 2026-11-02
• Heirs report that the repo-scope and user-scope boundary remains unclear after using this skill by 2026-11-02