| name | sdlc-workspace-init |
| description | Initialize a new repository with SDLC workspace files — MCP config, copilot-instructions.md, quality instructions, and prompt files. Use when setting up a new project, bootstrapping SDLC, onboarding a repo, or when Harness detects missing workspace files. Use when this capability is needed. |
| metadata | {"author":"Dongbumlee"} |
SDLC Workspace Initialization
When to use
- Setting up a new repository for SDLC-driven development
- After installing the SDLC Agent Template plugin into a repo that has no
.github/copilot-instructions.md
- When Harness detects missing workspace files during first-run initialization
What this skill does
Copies workspace-specific files from the skill's assets/ folder into the target repo's
.github/ and .vscode/ directories. These files cannot be distributed via the plugin
system because they require per-project customization or live outside .github/plugin/.
This skill is the ONLY place that deploys .vscode/mcp.json.
No other agent or skill should deploy mcp.json to avoid duplicate writes.
Files deployed
| Source (skill assets) | Target (workspace) | Customized? |
|---|
assets/mcp.template.json | .vscode/mcp.json | No — copied as-is (MCP server definitions) |
assets/copilot-instructions.template.md | .github/copilot-instructions.md | Yes — project name, domain, stack |
assets/instructions/*.instructions.md | .github/instructions/ | No — copied as-is |
assets/prompts/*.prompt.md | .github/prompts/ | No — copied as-is |
| (generated at runtime) | .github/reference-catalog.md | Yes — empty template with 5 fixed sections |
Procedure
Step 1: Check workspace state
Check what already exists in the workspace:
.vscode/mcp.json — MCP server config.github/copilot-instructions.md — project-specific Copilot instructions.github/instructions/ — quality instruction files (check if directory has files, not just exists).github/prompts/ — SDLC prompt files (check if directory has files, not just exists)
If ALL four are present and populated → Report: "Workspace already initialized. Skipping." and stop.
If any are missing or empty → continue and deploy only the missing pieces.
Step 2: Create directory structure
Before writing any files, create the required directories using the terminal.
These directories may not exist in a fresh workspace:
mkdir -p .github/instructions .github/prompts .vscode
This step is mandatory — do NOT skip it. File writes will fail silently in
directories that don't exist.
Step 3: Deploy MCP server configuration
This is the ONLY place mcp.json should be deployed. Do NOT deploy it anywhere else.
CRITICAL: Use the terminal to write this file — do NOT use create/edit tools.
LLM file tools sometimes append instead of overwrite, producing invalid JSON.
- Check if
.vscode/mcp.json exists in the workspace.
- If NOT found → deploy using the terminal:
a. Read mcp.template.json to get the content.
b. Delete any partial file and write fresh using the terminal:
rm -f .vscode/mcp.json
Then write the content using a heredoc redirect (which ALWAYS overwrites):
cat > .vscode/mcp.json << 'MCPEOF'
<paste the exact content of mcp.template.json here>
MCPEOF
c. Validate the file is valid JSON:
python3 -c "import json; json.load(open('.vscode/mcp.json')); print('✅ mcp.json is valid JSON')"
If validation fails → rm -f .vscode/mcp.json and retry from step (b) once.
- If found → validate it anyway:
python3 -c "import json; json.load(open('.vscode/mcp.json')); print('✅ mcp.json is valid JSON')"
If valid → Skip. Report: "Existing .vscode/mcp.json found — keeping current config."
If invalid → rm -f .vscode/mcp.json and deploy fresh from step (b).
After deploying (or confirming it exists), tell the user:
✅ .vscode/mcp.json — 7 MCP server definitions ready.
Please start all MCP servers: open .vscode/mcp.json and click "Start" on each.
Step 4: Gather project information
Ask the user for:
- Project name (required) — e.g., "SmartDoc Analyzer"
- Business domain (required) — e.g., "Intelligent document processing"
- Tech stack (required) — e.g., "Python, FastAPI, React, TypeScript"
- Primary language(s) (derived from tech stack) — used to filter instruction files (e.g.,
code-quality-py.md vs code-quality-ts.md)
Step 5: Deploy copilot-instructions.md
- Read copilot-instructions.template.md.
- Replace these placeholders:
{{PROJECT_NAME}} → user's project name{{BUSINESS_DOMAIN}} → user's business domain{{TECH_STACK}} → user's tech stack
- Write the result to
.github/copilot-instructions.md.
Step 6: Create empty reference catalog template
Create .github/reference-catalog.md with the empty catalog template. This template will be populated
by the Analyst agent during Phase 1-2 using the sdlc-reference-catalog skill.
Write this content to .github/reference-catalog.md:
# Reference Catalog
> This catalog is populated by the Analyst agent during the design phase.
> Downstream agents may append new entries but must not modify existing ones.
> Each entry includes the source agent that added it.
## Approved Libraries
<!-- Analyst: Research and list approved packages with versions, purpose, and installation -->
## Project Templates
<!-- Analyst: Document project structure patterns, scaffolding templates, starter repos -->
## API Patterns
<!-- Analyst: Document key design patterns (Repository Pattern, SDK abstractions, etc.) -->
## Code Examples
<!-- Analyst: Include representative code snippets showing approved usage patterns -->
## Documentation Links
<!-- Analyst: Link to official docs, internal wikis, and reference guides -->
Why an empty template? The Analyst populates this during the design phase using live research
from GitHub MCP, Context7, awesome-copilot, and web sources. A static pre-populated catalog
falls out of date; a living catalog stays current with each project's actual tech stack.
Step 6b: Ask catalog review preference
Ask the user:
Catalog review preference: Would you like to review the reference catalog before
development begins, or proceed automatically?
- review (default) — Harness will show you the catalog summary after the Analyst
populates it, and you can approve, edit, or proceed.
- auto — Harness proceeds automatically after catalog population.
Store the answer in harness-config.yml as:
catalog_review: true
catalog_review: false
If the user doesn't answer or skips the question, default to catalog_review: true.
Step 7: Deploy instruction files
Copy each file from assets/instructions/ to .github/instructions/:
Only copy instruction files matching the project's language stack:
- Python project → copy
code-quality-py + test-quality
- TypeScript project → copy
code-quality-ts + test-quality-ts
- React project → copy all TypeScript + TSX files
- Java project → copy
code-quality-java + test-quality-java
- C# project → copy
code-quality-csharp + test-quality-csharp
- Go project → copy
code-quality-go + test-quality-go
- Rust project → copy
code-quality-rust + test-quality-rust
- Full stack → copy all applicable files
Step 8: Deploy prompt files
Copy each file from assets/prompts/ to .github/prompts/:
Step 9: Report
## ✅ SDLC Workspace Initialized
- ✅ `.vscode/mcp.json` — 7 MCP server definitions deployed
- ✅ `.github/copilot-instructions.md` — customized for "{{PROJECT_NAME}}"
- ✅ `.github/instructions/` — X quality instruction files deployed
- ✅ `.github/prompts/` — 6 SDLC prompt files deployed
- ✅ `.github/reference-catalog.md` — empty catalog template created (Analyst will populate during Phase 1-2)
**Next steps:**
1. **Start MCP servers** — open `.vscode/mcp.json` and click "Start" on each server.
All 7 servers are required.
2. Review `.github/copilot-instructions.md` and adjust if needed.
3. Use `@Harness` to start your first SDLC task.
4. Use `/requirement-and-design` to begin Phase 1-2.
Source: Dongbumlee/sdlc-harness — distributed by TomeVault.
