Workspace Init

Use this skill to initialize or update a multi-repo workspace created from dev-config-template. Invoke whenever the user wants to: set up a fresh workspace c...

Security Scan

The skill's requirements and instructions are consistent with a workspace initialization tool; nothing requests unrelated credentials or surprising system privileges, though the skill runs repo-provided setup scripts (so users should review those) and there is a small metadata inconsistency about an openspec install.

Purpose & Capability

Name/description (initialize/update a dev-config-template workspace) align with required binaries (git, jq) and actions (write repos.json, fill CLAUDE.md, clone sub-repos, initialize OpenSpec). The included validate.py and config template are appropriate for verification and OpenSpec config generation.

Instruction Scope

SKILL.md stays within workspace-init scope (collects user info, writes repos.json, replaces placeholders, clones repos via ./script/setup, runs OpenSpec initialization). Note: it instructs running ./script/setup in the workspace — that script is part of the user’s repo and may execute arbitrary commands or network activity, so users should inspect that repository script before running. The skill does not request unrelated files or environment variables.

Install Mechanism

This is an instruction-only skill (no install spec) which is low-risk. SKILL.md and its embedded metadata require openspec (npm package) and instruct `npm install -g openspec`, but the registry-level install spec is absent—minor inconsistency. No downloads from untrusted URLs or archive extraction are present in the package itself.

Credentials

No environment variables or credentials are requested by the skill. Cloning repositories may use the user's existing git/SSH credentials, which is expected for this purpose.

Persistence & Privilege

always is false and the skill does not request persistent/system-wide configuration changes beyond writing files in the workspace. It does not modify other skills or require elevated privileges.

Assessment

This skill appears to do exactly what it says (scaffold and sync a multi-repo workspace). Before running it: 1) confirm you trust the repository you created from dev-config-template; 2) inspect ./script/setup (in your workspace) before executing — it will run commands and may perform network activity; 3) be aware openspec is required (SKILL.md suggests `npm install -g openspec`) though the registry metadata doesn't list that install step; 4) expect git to use your existing SSH/git credentials when cloning private repos. If you want an extra safety step, run the phases manually (create repos.json, template substitutions, then run cloning) rather than allowing an automated run that executes ./script/setup automatically.

Interactive initialization for workspaces created from dev-config-template. Takes a blank template to a fully working multi-repo workspace in one session.

Prerequisites

Tool	Required	Install
git	Yes	Pre-installed on most systems
jq	Yes	brew install jq (macOS) / sudo apt install jq (Ubuntu)
openspec	Yes	npm install -g openspec

Do NOT verify prerequisites on skill load. Check them at the start of Phase 2 (before execution begins). If a tool is missing, provide install instructions and wait for the user to confirm before continuing.

When to Use

• User just created a repo from dev-config-template and wants to set it up
• User says "initialize workspace", "set up my project", "configure workspace"
• User mentions dev-config-template and asks for help getting started
• User wants to update an existing workspace to match the latest template

Workflow Overview

Phase 1: Collect ──► Phase 2: Scaffold ──► Phase 3: OpenSpec
                                                    │
              Phase 5: Finalize ◄── Phase 4: Environments

All information is collected in Phase 1 (interactive). Phases 2-5 execute without further prompts -- errors are reported with remediation steps.

Phase 1: Information Collection

Ask the user for the following, one at a time. Wait for each answer before asking the next question.

1.1 Project basics

1. Project name -- used for config.yaml, VSCode workspace file, commit messages. Example: "srhome-dev", "my-iot-platform"
2. Project description -- one sentence describing the workspace. Example: "Multi-tenant smart home management system"

1.2 User profile

1. Role -- what they do. Goes into CLAUDE.md [ROLE]. Example: "a backend developer", "a full-stack engineer"
2. Experience level -- "experienced" or "learning while developing". Goes into CLAUDE.md [LEVEL].
3. Preferred language -- for AI conversations and documentation. Goes into CLAUDE.md [YOUR_LANGUAGE]. Example: "English", "简体中文", "日本語"

1.3 Tech stack and tooling

1. Tech stack -- "Python", "TypeScript", or "mixed".

After selection, present defaults and ask user to confirm or override:

	Python	TypeScript
Formatter	ruff format .	prettier --write .
Linter	ruff check .	eslint .
Type checker	mypy .	tsc --noEmit
Test runner	pytest	vitest
Style guide	PEP 8	Google TypeScript Style Guide

Say something like:

Based on your tech stack, here are the suggested tools:

• Formatter: ruff format .
• Linter: ruff check .
• Type checker: mypy .
• Test runner: pytest

Want to keep these, or change any of them?

For "mixed", show both sets.

1.4 Sub-repositories

Collect repos one at a time in a loop:

1. For each repo, ask:
   • Name -- identifier, used as directory name. Example: "sunlite-backend"
   • Git URL -- clone URL. Example: [e-mail]:org/repo.git
   • Description -- short description for CLAUDE.md table. Example: "Backend API service"

After each repo, ask: "Add another repo, or done?"

Continue until user says "done" (or equivalent like "完了", "没了", "that's all").

1.5 Confirm before executing

Summarize all collected info and ask for confirmation:

Project: my-project
Description: A multi-repo IoT platform
Role: backend developer
Level: learning while developing
Language: 简体中文
Stack: Python (ruff format / ruff check / mypy / pytest)

Repos:
  1. iot-backend ([e-mail]:org/iot-backend.git) -- Backend API
  2. iot-docs ([e-mail]:org/iot-docs.git) -- Documentation

Proceed with setup?

Phase 2: Scaffold Structure

2.1 Check prerequisites

Before making any changes, verify required tools:

which git && which jq && which openspec

If any tool is missing, stop and provide install instructions. Do not proceed until all tools are available.

2.2 Write repos.json

Generate repos.json in the workspace root:

{
  "repos": [
    {
      "name": "{name}",
      "url": "{git_url}",
      "path": "repos/{name}"
    }
  ]
}

2.3 Customize CLAUDE.md

Read the template CLAUDE.md and replace all placeholders. For the complete mapping of placeholders to collected values, read references/claude-md-fields.md.

Key replacements:

• [ROLE: e.g., ...] -> collected role
• [LEVEL: e.g., ...] -> collected level
• [YOUR_LANGUAGE: e.g., ...] -> collected language (appears twice)
• [YOUR_FORMAT_COMMAND] -> confirmed formatter
• [YOUR_LINT_COMMAND] -> confirmed linter
• [YOUR_TYPE_CHECK_COMMAND] -> confirmed type checker
• [YOUR_TEST_COMMAND] -> confirmed test runner
• [PROJECT_STYLE_GUIDE: e.g., ...] -> style guide based on tech stack
• Repository table in section 1 -> generated from repo list

2.4 Clone sub-repos

Run script/setup to clone all repositories:

./script/setup

If this fails (e.g., authentication issues, network errors), report the error and suggest the user fix it manually, then re-run.

Phase 3: OpenSpec Initialization

3.1 Run openspec init

openspec init

3.2 Generate config.yaml

Read references/config-template.yaml and populate it with:

• {project_name} -> collected project name
• {description} -> collected description
• {repos_list} -> formatted repo list, one per line:

  - **{name}**: {description}

Write the result to openspec/config.yaml.

Phase 4: Environment Configuration

For each cloned sub-repo under repos/, detect project type and configure:

4.1 Python project (pyproject.toml detected)

cd repos/{name}
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]" 2>/dev/null || pip install -e .

If venv creation fails, report the error and continue with the next repo.

4.2 TypeScript project (package.json detected)

cd repos/{name}
# Use bun if bun.lockb exists, otherwise npm
if [ -f bun.lockb ]; then
    bun install
else
    npm install
fi

4.3 Pre-commit (if .pre-commit-config.yaml exists)

cd repos/{name}
pre-commit install

Skip silently if pre-commit is not installed.

4.4 No recognizable project config

If a repo has no pyproject.toml, package.json, or setup.py, skip it and note:

"No pyproject.toml or package.json found in {name}. You may need to set up the environment manually."

4.5 VSCode workspace file

Generate {project-name}.code-workspace:

{
  "folders": [
    { "path": ".", "name": "Config" },
    { "path": "repos/{name1}", "name": "{Name1}" },
    { "path": "repos/{name2}", "name": "{Name2}" }
  ]
}

Phase 5: Finalize

5.1 Version tracking

Write the template commit SHA to .workspace-init-version for future updates:

gh api repos/niracler/dev-config-template/commits/main --jq '.sha' > .workspace-init-version

If gh is not available, write unknown -- update will still work but will show all template changes instead of just the diff.

5.2 Initial commit

Stage and commit all generated/modified files:

git add repos.json CLAUDE.md openspec/ *.code-workspace .workspace-init-version
git commit -m "chore: initialize workspace"

Do NOT push -- let the user decide when to push.

5.3 Validate

Run the bundled validation script to verify everything is in place:

python3 <skill-path>/scripts/validate.py .

This checks: repos.json structure, CLAUDE.md placeholder replacement, sub-repo cloning, OpenSpec config, environment setup, and VSCode workspace file.

If any ERROR-level checks fail, show the output and help the user fix the issues before proceeding. WARNING-level items are informational -- note them but continue.

5.4 Next steps

Display a checklist:

Workspace initialized! Here's what to do next:

1. Open the workspace in VSCode:
   code {project-name}.code-workspace

2. Start Claude Code and try a conversation:
   claude

3. Create your first change:
   /opsx:new

4. Set up project scheduling (optional):
   Ask Claude: "planning init {project-name}"

5. Push when ready:
   git push -u origin main

Common Mistakes

Error	Cause	Fix
script/setup fails	jq not installed	brew install jq or sudo apt install jq
openspec init fails	openspec CLI missing	npm install -g openspec
Clone fails	SSH key not configured	Check SSH access to the git host
venv creation fails	Python not installed or wrong version	Install Python 3.10+
CLAUDE.md placeholders remain	Placeholder format mismatch	Check references/claude-md-fields.md for exact tokens
Update shows no changes	.workspace-init-version missing	Run update anyway -- it compares against all template history

Update Mode

When the user asks to update the workspace template, follow this flow.

Trigger phrases: "update workspace", "update template", "sync template", "更新工作区模板", "模板有更新吗", "template changed"

Step 1: Check current version

Read .workspace-init-version to get the local template SHA.

cat .workspace-init-version 2>/dev/null || echo "unknown"

Step 2: Fetch remote template state

gh api repos/niracler/dev-config-template/commits/main --jq '.sha'

If local SHA matches remote HEAD, report "Already up to date" and stop.

Step 3: Show what changed

Fetch the diff between local version and remote HEAD:

gh api "repos/niracler/dev-config-template/compare/{local_sha}...main" \
  --jq '.files[] | "\(.status)\t\(.filename)"'

If local SHA is unknown, fetch the full file list instead and compare against local files.

Display a summary:

Template updates available (3 files changed):

  modified  script/setup        -- Updated clone logic
  modified  CLAUDE.md           -- Added new section 10
  added     .editorconfig       -- New file

Files that will NOT be touched (your customizations):
  repos.json
  openspec/config.yaml
  CLAUDE.md filled values ([ROLE], [LEVEL], etc.)

Step 4: Apply updates (with confirmation)

Ask the user to confirm before applying.

For each changed template file:

script/setup, .gitignore, .editorconfig (non-customized files):

• Fetch the new version and overwrite directly

CLAUDE.md (partially customized):

• Fetch the new template version
• Extract the user's current filled values (role, level, language, commands, repo table)
• Apply the new template structure
• Re-fill the extracted values into the new template
• Show the user a diff of structural changes for review

Files to NEVER touch:

• repos.json -- user's repo configuration
• openspec/ -- user's change management data
• repos/ -- sub-repo contents
• .claude/ -- user's Claude settings and skills

Step 5: Update version and commit

gh api repos/niracler/dev-config-template/commits/main --jq '.sha' > .workspace-init-version
git add -A
git commit -m "chore: update workspace template"

Step 6: Validate

Run scripts/validate.py to confirm the update didn't break anything.