init-workspace

/init-workspace — Workspace Setup

One-time workspace setup, or new-developer onboarding. Generates the context files that all other workflows depend on.

Hard constraint — human-only command. /init-workspace requires interactive human confirmation during language discovery (Phase 3 negotiate). It MUST NEVER be invoked by a background agent. The orchestrator must never delegate this command to a sub-agent lane. If language configuration is missing when a workflow starts, ask the human to run /init-workspace directly.

Usage

/init-workspace                         # First-time setup or onboarding
/init-workspace --full                  # Force full regeneration
/init-workspace --refresh-conventions   # Only regenerate conventions.md
/init-workspace --refresh-permissions   # Only re-propose Bash permissions (Step 3c)
/init-workspace --refresh-shared        # Only re-mirror plugin agents/shared/ files (Step 6c)
/init-workspace --keep-legacy           # In-place schema upgrade without re-running discovery

Output Files

All generated files live at .claude/context/:

File	Description
provider-config.md	Work item and git provider settings, tool mappings, field mappings
repos-metadata.md	Each repo's purpose, stack, domain, default branch
repos-paths.md	Maps repo names to local filesystem paths
language-config.md	Discovered per-repo language, toolchain, commands, regex patterns, permissions
conventions.md	Team coding patterns, language baselines, repo-specific patterns
state.md	Workspace lifecycle state (Bootstrap completed, Workflow active, Last metric stamp) — owner: P0

All files are local and git-ignored. Each developer generates their own set by running /init-workspace.

naming-config.md schema (CC-01.8 — IMPL-15-01)

.claude/context/naming-config.md holds the four required naming templates (branch_format, commit_format, pr_title_format, tag_format). Per CC-01.8 every consumer reads from here — never hardcodes.

Schema and placeholder DSL: naming-templates · Defaults: naming-defaults.md.

state.md schema (CC-01.4 — IMPL-02-01)

state.md is the workspace-level lifecycle file. The orchestrator reads it at startup (per CC-05.4) and refuses to enter P1 until Bootstrap completed <ts> is present. Fields: Bootstrap completed, Workflow active, Last metric stamp.

Full schema and example: language-discovery.md.

Language configuration is discovered at setup time (no hard-coded language adapters). All agents read only language-config.md and conventions.md at runtime.

Reference Documents

Topic	File
Four-phase language discovery pipeline + language-config.md schema	language-discovery.md
Bash permissions proposal + Read pre-approvals (Step 3c) and preflight semantics	permissions.md
Legacy schema migration + --keep-legacy semantics	schema-upgrade.md

Behavior

Step 0 — Detect Existing Context

Before doing anything, check which context files already exist in .claude/context/:

• .claude/context/provider-config.md
• .claude/context/repos-metadata.md
• .claude/context/repos-paths.md
• .claude/context/language-config.md
• .claude/context/conventions.md

Also check for the legacy ado-config.md — if it exists but provider-config.md does not, offer to migrate per schema-upgrade.md:

"I found a legacy ado-config.md file. I'll migrate its settings to the new provider-config.md format which supports multiple providers."

If all five files exist, the workspace is already fully initialized. Inform the user:

"Your workspace is already fully initialized — all context files exist:

• provider-config.md, repos-metadata.md, repos-paths.md, language-config.md, conventions.md

Nothing to do. If you want to update files, use:

• /init-workspace --refresh-conventions to regenerate conventions
• /init-workspace --refresh-permissions to re-propose Bash permissions only
• /init-workspace --full to regenerate everything from scratch"

Then stop.

If some files exist but not all, inform the user which files are missing and proceed to generate only the missing ones. Offer --full to regenerate everything instead.

If no files exist, proceed with full setup from Step 1.

Step 1 — Provider Selection

Ask the user to select their work item provider and git provider:

Work Item Provider — where your stories/issues live:

1. ADO (Azure DevOps Work Items)
2. Jira (Atlassian Jira Issues)
3. GitLab (GitLab Issues)
4. GitHub (GitHub Issues)
5. Zoho (Zoho Mail Group Tasks)
6. local-markdown (Local .md file — no external system required)

Git Provider — where your code repos and PRs/MRs live:

1. ADO (Azure DevOps Repos)
2. GitLab (GitLab Repos + Merge Requests — via GitLab MCP)
3. GitLab CLI (glab-cli) (via glab CLI, no MCP needed)
4. GitHub (GitHub Repos + Pull Requests — via @anthropic/github-mcp)
5. GitHub CLI (gh-cli) (via gh CLI, no MCP needed)

After selection, verify MCP server / CLI availability by exercising a lightweight call:

Provider	Verification
ADO	Call any mcp__azure-devops__* tool
Jira	Call mcp__jira__get_issue
GitLab	Call mcp__gitlab__get_issue
GitHub	Call mcp__github__get_issue
GitHub CLI	Run gh --version && gh auth status
GitLab CLI	Run glab --version && glab auth status
Zoho	Call mcp__zoho__ZohoMail_getMailAccounts
local-markdown	No verification — Read/Write tools are always available

If the required MCP server or CLI is not available or not authenticated, warn the user with the appropriate remediation (gh auth login, install MCP server, etc.) and proceed only after they confirm.

Step 2 — Provider Configuration

Based on the selected providers, collect provider-specific settings.

ADO (Work Item Provider)

1. Organization URL: e.g., https://dev.azure.com/your-org
2. Project name: e.g., MyProject
3. Area path: e.g., MyProject\Engineering\Backend Team
4. Iteration path pattern: e.g., MyProject\Sprint 42
5. Work item types: Confirm hierarchy (Epic > Feature > User Story > Task, or custom)
6. Custom fields: Any team-specific fields

Jira (Work Item Provider)

1. Jira instance URL: e.g., https://your-company.atlassian.net
2. Project key: e.g., PROJ
3. Acceptance Criteria field: Custom field (get field ID), embedded in description, or subtasks
4. Sprint field / Story points field: Default or custom field name
5. Issue types: Confirm hierarchy

GitLab (Work Item Provider)

1. GitLab URL: https://gitlab.com or self-hosted
2. Group/Project path: e.g., myorg/myproject
3. AC convention and label taxonomy

GitHub (Work Item Provider)

1. Organization/Owner, issue repo(s)
2. AC convention and label taxonomy

Zoho (Work Item Provider)

1. Group ID — integer from the Zoho Mail URL or group settings. Verify by calling mcp__zoho__ZohoMail_listGroupTask. Record as zoho_group_id.
2. Categories — call mcp__zoho__ZohoMail_getCategoriesInGroupTasks. Record names and IDs.
3. AC convention — confirm ACs are embedded in the task description under ## Acceptance Criteria (no dedicated field exists in Zoho Group Tasks).
4. Assignee Zuids — record team member Zuids; ZohoMail_getMailAccounts returns the current user's Zuid.

local-markdown (Work Item Provider)

1. Default stories directory (optional): stored as stories_dir in provider-config.md. Story-workflow commands always accept an explicit file path regardless of this setting.
2. No further configuration needed.

Git Provider Settings (if different from work item provider)

Collect repository-specific settings (these overlap with Step 3 — combine them): GitLab project paths, GitHub owner/repo names, ADO already collected above.

Step 3 — Repo Discovery

Ask the user to provide the local filesystem path for each team repo:

"Please provide the local path for each of your team's repos, one at a time. For example: /home/dev/repos/auth-service Type 'done' when you've listed all repos."

For each path provided:

1. Verify the path exists and is a git repo.

2. Identify the default branch (main or master).

3. Ensure the repo is on the default branch and up to date:

   git -C <path> checkout <default-branch>
   git -C <path> pull
   

   If git pull fails (no remote, auth issue), warn but continue with the local state. If the checkout fails (uncommitted changes), warn and proceed on the current branch.

4. Detect the git provider's remote by parsing git remote get-url origin:

   • dev.azure.com / *.visualstudio.com → ADO
   • gitlab.com or configured GitLab host → GitLab
   • github.com → GitHub

   Extract the project/repo identifier from the remote URL.

5. Scan the repo for metadata: name, type, stack, domain, key patterns.

6. Present for confirmation and apply corrections.

Write .claude/context/repos-metadata.md with the standard format.

Multi-language monorepos: If a single git repo contains more than one primary language (e.g. Python backend + TypeScript frontend), ask the user to register it as two logical repos in repos-paths.md, each with its own project_root (e.g. monorepo-api → /path/to/monorepo/api and monorepo-web → /path/to/monorepo/web). The language-config schema is one language per logical repo.

Step 3b — Language Discovery

Run the four-phase language discovery pipeline (Detect → Infer → Negotiate → Write) per repo. The full procedure, marker file lists, inference rules, negotiation prompts, and language-config.md schema live in language-discovery.md.

If --keep-legacy was passed, follow the in-place upgrade flow in schema-upgrade.md instead of running Phase 3 negotiation.

Step 3c — Permissions Proposal

After Phase 3 negotiate completes for all repos, propose Bash permissions (interactive, per-command-head) and auto-add Read pre-approvals for the harness plugin files (Read(~/.claude/plugins/**)) and every repo path in repos-paths.md (Read(//<repo-path>/**)). Read pre-approvals are added without prompting — the paths are already trusted by virtue of installation and configuration, and prompting would stall background agents that cannot respond. Full procedure (collation, presentation, JSON edit, idempotency, fallback, preflight semantics) in permissions.md.

Step 4 — Conventions Extraction

Compose .claude/context/conventions.md — the single authoritative conventions file that all agents consume at runtime. Assemble it from three layers:

1. Team Rules (universal) — Ask the user before writing:

   "A few team-wide conventions to capture:

   1. Team name — used as the branch prefix (e.g. backend, platform, payments). All feature branches will be <team-name>/feature/<id>-<slug>.
   2. Coverage threshold — minimum line coverage required (default: 90%).
   3. PR title format — any required prefix or format? (e.g. [STORY-ID] title, or leave blank for default)"

   Record the answers as concrete values — never leave <team> as a placeholder. The team name is required; re-prompt if left blank.

2. Language Baselines — one section per distinct language detected across the workspace. Naming, project structure, testing patterns. Generated from the Phase 2 inferences and Phase 3 negotiated answers — not from any static adapter file.

3. Repo-Specific Patterns — per-repo section with the architecture style, detected frameworks, and any review enforcements the user requested in Phase 3 (e.g. "no DB imports in api/").

Write .claude/context/conventions.md with the combined result. This is the only conventions file agents read.

SOLID / DRY / YAGNI do NOT live in conventions.md. Those universal engineering principles are baked into the Developer and Reviewer agent prompts directly — static, identical across all projects, not discovered per-repo.

conventions.md schema

Three sections: ## 1. Team Rules (universal) (team name, commit format, coverage threshold), ## 2. Language Baselines (per-language naming/structure/testing), ## 3. Repo-Specific Patterns (architecture, frameworks, review enforcements).

Full schema with example: language-discovery.md.

Step 5 — Local Repo Paths

Generate .claude/context/repos-paths.md mapping repo names to local paths. For multi-language monorepos registered as two logical repos, each entry points to its own project_root.

Step 5b — Propose Naming Templates (IMPL-15-02 / CC-01.8)

Read the shipped defaults from naming-defaults.md and present them to the human:

Proposed naming templates (from naming-defaults.md):
  Branch:     ${type}/${story_id}-${slug}
  Commit:     #${story_id} #${task_id} ${type}: ${slug}
  PR title:   [${repo}] ${slug}
  Tag:        v${story_id}

Accept defaults (Y), customise (c), or skip and accept later (s)?

Step 5c — Cross-check against pr-conventions (IMPL-15-06)

Resolve the configured git provider (from Step 1) and check its skills/providers/<provider>/pr-conventions.md (or pull-requests.md) for any required PR-title prefix or shape constraint. If the chosen pr_title_format conflicts (e.g. ADO requires [<team>] prefix and the chosen template omits it), surface the conflict to the human before writing:

⚠ Your chosen pr_title_format `${slug}` does not include the `[<team>]` prefix
that the configured git provider (ado) expects per shared/pr-conventions.md.
[a] Accept anyway (record deviation as a comment in naming-config.md)
[c] Customise pr_title_format
[d] Drop the cross-check entirely

The user's choice wins; the validator records the deviation in naming-config.md as a comment so future audits can locate it.

Step 5d — Emit naming-config.md

Write .claude/context/naming-config.md with the four chosen templates. The file format matches the schema declared at the top of this SKILL.md. Cross-check warnings (if any) are appended as <!-- deviation: ... --> comments below the relevant key.

Step 6 — Generate Provider Config

Read the template from skills/providers/provider-config-template.md and fill in all values based on the selections from Steps 1–2. Read the relevant provider adapters from skills/providers/<provider>/ to populate tool mappings.

Write .claude/context/provider-config.md with the completed configuration.

Step 6b — Emit state.md (IMPL-02-02 / CC-05.3)

Write .claude/context/state.md with the Bootstrap completed line. Use the canonical UTC timestamp helper per CC-05.3 — never reproduce the date -u literal inline.

Authoritative reference: timestamp

TS=$(date -u +"%Y-%m-%d %H:%M UTC")
cat > .claude/context/state.md <<EOF
# Workspace State

Bootstrap completed: ${TS}
Workflow active: none
Last metric stamp: Bootstrap completed ${TS}
EOF

Idempotency: re-running init-workspace rewrites state.md only when the file is absent OR --full was passed. When the file exists and --full was not passed, the existing Bootstrap completed timestamp is preserved (the user accepted the bootstrap state previously); the Workflow active and Last metric stamp lines are reset on --full.

Step 6c — Mirror plugin shared files into the workspace

Subagents (planner / developer / tester / reviewer) reference shared markdown in agents/shared/ via their Read tool — but CLAUDE_PLUGIN_ROOT is not exported to the agent runtime (only to hook scripts), so a relative path like agents/shared/engineering-principles.md resolves against the user's project workspace, where the file doesn't exist. The agents report not found (non-blocking but noisy). Resolution: mirror the plugin's agents/shared/*.md into the workspace at .claude/context/agents-shared/ so agents resolve them via workspace-relative paths.

Run the shared-files refresh script (idempotent — overwrites existing copies so a plugin upgrade propagates on the next run):

bash "${CLAUDE_PLUGIN_ROOT}/scripts/refresh-shared.sh" "$PWD"

refresh-shared.sh discovers the latest installed plugin version under ~/.claude/plugins/cache/ai-sdlc-harness/ai-sdlc-harness/<version>/ and copies every .md file from its agents/shared/ directory into the workspace's .claude/context/agents-shared/. The agent index files reference .claude/context/agents-shared/<file>.md (workspace-relative) — this Step ensures those paths resolve.

Exit codes from the script:

• 0 — copied (count printed) or already in sync
• 1 — plugin install not found (the user must install / update the plugin)
• 2 — workspace lacks .claude/context/ (an earlier Step failed)

/init-workspace --refresh-shared re-runs only this Step — useful after a plugin upgrade adds new shared files. Existing workspace files are overwritten; agent customisations in .claude/context/agents-shared/ are not preserved (the directory is plugin-managed, not user-edited).

Step 6d — Emit cost-config.md (IMPL-25-03 / ADR-010)

Write .claude/context/cost-config.md from the shipped template at skills/init-workspace/templates/cost-config.md.

Idempotency: skip if the file already exists and --full was not passed — the user may have filled in their rates and a re-run must not overwrite them. On --full, overwrite and note in the summary that the file was reset.

After writing, remind the human to fill in their model rates:

"📊 cost-config.md created at .claude/context/cost-config.md. Edit the rate table to enable $ cost columns in /dev-workflow report. Leave cells empty for models you don't use — empty rates render as cost: n/a rather than $0.00."

Step 7 — Summary

Present a summary:

"Workspace initialized! Here's what was generated:

• provider-config.md — Work items: , Git:
• repos-metadata.md — [N] repos registered
• repos-paths.md — local paths configured
• language-config.md — [N] repos with discovered toolchains
• conventions.md — team rules + language baselines + repo-specific patterns
• cost-config.md — fill in model rates to enable $ columns in reports (ADR-010)

Languages discovered:

• AuthService → python 3.12 (FastAPI, layered, zero_warning_support=linter-based)
• PaymentGateway → go 1.22 (Gin, hexagonal, zero_warning_support=native)

Permissions updated: N Bash entries (per-command) plus 1 plugin-read entry (Read(~/.claude/plugins/**)) and M repo-read entries (Read(//<repo-path>/**)) added to settings.json. Restart your session if you hit unexpected permission prompts.

Next steps:

• All context files are local and git-ignored — no commit needed.
• You're ready to use /dev-workflow and /story-workflow."

Flags

• --full — Force full setup even if context files exist. Will overwrite all context files. Asks for confirmation before proceeding.
• --refresh-conventions — Only regenerate conventions.md from the current codebase and prior language-config.md. Useful after major architectural changes.
• --refresh-permissions — Re-run only Step 3c against the existing language-config.md. Does not touch discovery. See permissions.md.
• --keep-legacy — In-place schema upgrade for an existing legacy-schema language-config.md. See schema-upgrade.md.