new-workspace

Provision Technical-Docs Workspace

Creates a new workspace for technical documentation work. This plugin's commands (/technical-docs:create-readme, /technical-docs:create-reference, /technical-docs:document-stack, etc.) are globally available once installed — this skill only provisions the data scaffold (CLAUDE.md, directory layout, starter files) that those commands read from and write to.

Arguments

$ARGUMENTS is parsed as:

• First positional: workspace name (kebab-case, used as directory and GitHub repo name). Required.
• Second positional (optional): target parent path. Defaults to ~/repos/github/my-repos.
• --variant=<api-reference|code-docs|environment-docs|dev-notebook> (optional): which scaffold to copy. Default: code-docs.
• --local-only (optional): skip GitHub repo creation and push. Default: create a public GitHub repo and push.
• --private (optional): create the GitHub repo as private. Default: public.

Variants

• api-reference — structured API/SDK reference docs with an endpoints/ or reference/ layout.
• code-docs — general codebase documentation workspace (README drafts, architecture notes, module docs).
• environment-docs — split human-facing vs. agent-facing environment documentation (adapted from the Environment Docs pattern).
• dev-notebook — developer notebook: entries, snippets, and references for ongoing engineering learning.

Examples

/technical-docs:new-workspace my-api-docs --variant=api-reference
/technical-docs:new-workspace project-env --variant=environment-docs
/technical-docs:new-workspace eng-notebook --variant=dev-notebook
/technical-docs:new-workspace repo-docs --local-only

Procedure

1. Parse arguments

Extract workspace name, target parent path, variant, and flags from $ARGUMENTS. If workspace name is missing, ask the user. If variant is missing, default to code-docs.

2. Resolve the scaffold path

The bundled scaffold lives at ${CLAUDE_SKILL_DIR}/../../template/<variant>/. Confirm it exists. If the variant isn't one of api-reference, code-docs, environment-docs, dev-notebook, tell the user which variants are available.

3. Read ambient facts

Read ~/.claude/CLAUDE.md if it exists. Extract OS, locale, timezone, and user identity facts. These will personalise the workspace's CLAUDE.md at step 5.

4. Create the workspace directory

mkdir -p <target-parent>/<workspace-name>
cp -r ${CLAUDE_SKILL_DIR}/../../template/<variant>/. <target-parent>/<workspace-name>/

Do not copy any .claude/ tree. The plugin's primitives are global.

5. Personalise CLAUDE.md

Open the new workspace's CLAUDE.md and:

• Replace any placeholder identity/<PROJECT> tokens with facts from step 3 (or leave blank if unknown).
• Add a short header noting the workspace name and variant.
• Embed OS/locale/timezone facts if ambient facts include them.

6. Prompt for workspace-specific facts

Ask the user only for facts this plugin can't infer:

• api-reference: the API name, base URL, and auth style (record in CLAUDE.md).
• code-docs: the target repository path or URL being documented.
• environment-docs: the system / machine / environment being described.
• dev-notebook: the notebook's topical focus (e.g. "backend engineering", "ML ops").

7. Initialise git and (optionally) publish

cd <target-parent>/<workspace-name>
git init
git add .
git commit -m "Initial workspace from technical-docs plugin"

Unless --local-only is set:

gh repo create <workspace-name> --<public|private> --source=. --push

Use --public by default, --private if flag was passed.

8. Print next steps

Tell the user:

• Workspace path and variant chosen.
• Which plugin commands apply most (e.g. /technical-docs:create-readme, /technical-docs:create-reference, /technical-docs:document-stack, /technical-docs:create-changelog, /technical-docs:save-fix-note).
• That the doc-writer agent can drive multi-step doc work.
• Reminder that the workspace is data — they can delete/move it freely without losing the plugin's commands.

Notes

• The scaffold path must be resolved via ${CLAUDE_SKILL_DIR}/../../template/ (not ${CLAUDE_PLUGIN_ROOT} — that variable isn't exported in skill bash injection, only in hooks/MCP).
• Never copy .claude/commands/, .claude/agents/, or .claude/skills/ into the new workspace.
• Don't hard-code any personal paths or identifiers — everything comes from user memory or prompts.