From nexus
Initialize project configuration file with interactive wizard. Also supports `validate` and `migrate` modes for existing installs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/nexus:configuration-init [validate | migrate][validate | migrate]claude-sonnet-4-6This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Initialize `.claude/configuration.yml` for the current project using an interactive wizard. Also supports:
Initialize .claude/configuration.yml for the current project using an interactive wizard. Also supports:
/configuration-init validate — check an existing config for errors and warnings./configuration-init migrate — detect and rewrite legacy configuration and state file formats in place (with backups).Set up project-specific configuration that skills and agents use for storage locations, artifact paths, and behavior flags.
install.sh to install skills globallyIf $ARGUMENTS contains "validate":
/configuration-init to create one."If $ARGUMENTS contains "migrate":
# Source resolve-config: marketplace installs get ${CLAUDE_PLUGIN_ROOT} substituted
# inline before bash runs; ./install.sh users fall back to ~/.claude. If neither
# path resolves, fail loudly rather than letting resolve_artifact be undefined.
if [ -f "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh" ]; then
source "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh"
elif [ -f "$HOME/.claude/shared/resolve-config.sh" ]; then
source "$HOME/.claude/shared/resolve-config.sh"
else
echo "ERROR: resolve-config.sh not found. Install via marketplace or run ./install.sh" >&2
exit 1
fi
EXISTING_CONFIG="$CONFIG"
# New configurations are always written to CWD
WRITE_CONFIG=".claude/configuration.yml"
If $EXISTING_CONFIG is found (in current or parent directory), read it and show current state:
Configuration already exists: .claude/configuration.yml
Current configuration:
execution_mode: subagent
storage.locations: local, team-repo (if configured)
storage.artifacts: work, brainstorms, proposals, requirements, product-knowledge, refactoring
Use AskUserQuestion:
If user selects "Cancel", stop with: "Configuration unchanged."
If user selects "Validate", jump to Step 9: Validate Configuration.
Read the template from ~/.claude/templates/configuration.yml.
If template not found:
Template not found at ~/.claude/templates/configuration.yml
Run install.sh first to install templates:
cd /path/to/claude-skills && ./install.sh
Or install templates only:
cd /path/to/claude-skills && ./install.sh
Select option: 8) Templates only
Stop execution.
Use AskUserQuestion:
If "Sub-agent" or "Team" selected:
Store the selected mode as a simple string: "subagent" or "team".
If "Per-phase" selected:
Use AskUserQuestion:
Then use AskUserQuestion:
--local modes)"Store the result as an object:
execution_mode:
default: subagent # or team
overrides:
requirements_deep_dive: team # only if selected
qa_review: team # only if selected
Only include overrides that differ from the default. If no overrides differ, simplify back to the string format.
Use AskUserQuestion to ask about a shared git repository for team artifacts.
Use AskUserQuestion:
The user can type a custom path via the built-in "Other" option. Store the selected value as LOCAL_PATH (e.g., .claude, .claude-data, or a custom value). Then skip to Step 6.
First, resolve the parent directory of the current working directory at runtime:
PARENT_DIR=$(dirname "$PWD")
For example, if cwd is /home/user/code/my-project, then PARENT_DIR=/home/user/code.
Use AskUserQuestion:
The user can type a custom path via the built-in "Other" option.
If "Create new" selected:
Show setup instructions and stop the repository section:
To create a team-knowledge repository:
mkdir team-knowledge
cd team-knowledge
git init
mkdir requirements proposals
cp -r ~/.claude/templates/requirements-repo/* requirements/ # If templates installed
git add . && git commit -m "Initial setup"
Then re-run /configuration-init to connect it.
See: docs/workflows/requirements-knowledge-base.md
If user selects the default path or enters a custom path via "Other", validate it exists:
if [[ -d "$USER_PATH" ]]; then
echo "Found: $USER_PATH"
if [[ -d "$USER_PATH/.git" ]]; then
echo "Git repository detected."
else
echo "Warning: Not a git repository. Sync will not be available."
fi
else
echo "Warning: Directory not found: $USER_PATH"
echo "The path will be saved but the integration won't work until the directory exists."
fi
Determine the location type: git if .git/ exists, otherwise directory.
Use AskUserQuestion:
The user can type a custom path via the built-in "Other" option. Store the selected value as LOCAL_PATH.
Use AskUserQuestion:
If "Customize", ask about each flag individually. If "Use defaults", use:
auto_archive: trueauto_search: trueauto_load_threshold: 0.9max_suggestions: 3archive_on_pr: trueIf LOCAL_PATH was not set (e.g., user selected "Create new" in Step 5 and execution stopped), default it:
LOCAL_PATH="${LOCAL_PATH:-.claude}"
Build the YAML configuration using the LOCAL_PATH value. The storage section always includes a local location and default artifact mappings. If the user configured a team repo, add a team-repo location and map shared artifacts to it.
Base config (always included):
# Simple format (string):
execution_mode: subagent # or team
# Per-phase format (if selected in Step 3):
# execution_mode:
# default: subagent
# overrides:
# requirements_deep_dive: team
# qa_review: team
storage:
locations:
local:
type: directory
path: ${LOCAL_PATH} # e.g., .claude, .claude-data, or custom
artifacts:
work:
location: local
subdir: work
brainstorms:
location: local
subdir: brainstorm
proposals:
location: local
subdir: proposals
refactoring:
location: local
subdir: work/refactoring-sessions
requirements:
location: local
subdir: requirements
product-knowledge:
location: local
subdir: .
If team repo configured — override shared artifacts to point to the team repo:
storage:
locations:
local:
type: directory
path: ${LOCAL_PATH} # e.g., .claude, .claude-data, or custom
team-repo:
type: git # or directory
path: /absolute/path/to/team-knowledge
artifacts:
# ... local artifacts as above, except override shared ones ...
requirements:
location: team-repo
subdir: requirements
proposals:
location: team-repo
subdir: proposals
product-knowledge:
location: team-repo
subdir: .
Add requirements behavior flags:
requirements:
auto_archive: true
auto_search: true
auto_load_threshold: 0.9
max_suggestions: 3
archive_on_pr: true
mkdir -p .claude
Write the built YAML to .claude/configuration.yml using the Write tool.
Then create all artifact directories using LOCAL_PATH so skills don't encounter missing paths:
mkdir -p ${LOCAL_PATH}/work
mkdir -p ${LOCAL_PATH}/brainstorm
mkdir -p ${LOCAL_PATH}/proposals
mkdir -p ${LOCAL_PATH}/work/refactoring-sessions
mkdir -p ${LOCAL_PATH}/requirements
If LOCAL_PATH differs from .claude, also ensure .claude/ exists (the configuration file itself always lives at .claude/configuration.yml).
If team repo is configured, skip creating directories for artifacts that point to the team repo (those directories should already exist in the repo).
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Configuration Created
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File: .claude/configuration.yml
EXECUTION MODE
────────────────────────────────────────────────
default: ${default_mode} (subagent|team)
requirements_deep_dive: ${override_or_default}
qa_review: ${override_or_default}
STORAGE LOCATIONS
────────────────────────────────────────────────
local: ${LOCAL_PATH} (directory)
team-repo: ${path} (${type}) # if configured
ARTIFACTS
────────────────────────────────────────────────
work: local → ${LOCAL_PATH}/work
brainstorms: local → ${LOCAL_PATH}/brainstorm
proposals: ${location} → ${resolved_path}
refactoring: local → ${LOCAL_PATH}/work/refactoring-sessions
requirements: ${location} → ${resolved_path}
product-knowledge: ${location} → ${resolved_path}
REQUIREMENTS BEHAVIOR
────────────────────────────────────────────────
auto_search: ${value}
auto_archive: ${value}
auto_load_threshold: ${value}
max_suggestions: ${value}
archive_on_pr: ${value}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skills and agents will now use this configuration.
To modify later, edit .claude/configuration.yml directly
or re-run /configuration-init.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Triggered by: "Validate" option in Step 1, or $ARGUMENTS containing "validate".
Read $EXISTING_CONFIG and run validation checks. Report results using pass/warn/fail format.
Validation checks:
1. YAML Syntax
→ Parse the file. If invalid YAML → FAIL with parse error location.
2. execution_mode
→ If string: must be "subagent" or "team" → else FAIL
→ If object: must have "default" key with value "subagent" or "team"
→ If object with "overrides": each key must be a known phase name
Known phases: requirements_deep_dive, qa_review, documentation_update, refactor, troubleshoot, pr_review
Unknown phase name → WARN ("unknown phase: {name}, will be ignored by skills")
3. storage.locations
→ Each location must have "type" and "path"
→ "type" must be "git" or "directory" → else FAIL
→ "path": check if directory exists → if not, WARN ("path does not exist: {path}")
→ If type is "git": check if path contains .git/ → if not, WARN ("not a git repository: {path}")
4. storage.artifacts
→ Each artifact must have "location" and "subdir"
→ "location" must reference a key defined in storage.locations → else FAIL ("artifact '{name}' references undefined location '{loc}'")
→ Known artifact names: work, brainstorms, proposals, refactoring, requirements, product-knowledge
→ Unknown artifact name → WARN ("unknown artifact: {name}")
5. requirements section (if present)
→ auto_archive: must be boolean → else WARN
→ auto_search: must be boolean → else WARN
→ auto_load_threshold: must be number between 0 and 1 → else WARN
→ max_suggestions: must be positive integer → else WARN
→ archive_on_pr: must be boolean → else WARN
Output format:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Configuration Validation: {config_path}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[PASS] YAML syntax valid
[PASS] execution_mode: "subagent"
[PASS] storage.locations.local: type=directory, path=.claude (exists)
[WARN] storage.locations.team-repo: path /home/user/code/team-knowledge does not exist
[PASS] storage.artifacts: all 6 artifacts reference valid locations
[FAIL] storage.artifacts.proposals: references undefined location "shared"
[PASS] requirements: all values valid
Result: 5 passed, 1 warning, 1 failure
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If any FAIL results exist, suggest fixes. If only WARN or PASS, report "Configuration is valid."
Triggered by: $ARGUMENTS containing "migrate".
Scan the project for legacy configuration and state file formats left over from past breaking changes and rewrite them in place. All rewrites create a .bak-YYYYMMDD-HHMMSS copy beside the original so nothing is destroyed.
Three migrations are checked:
configuration.json → configuration.yml (JSON to YAML)*-state.json (per-skill state files) → unified state.json with type fielddomain_knowledge configuration key → product_knowledgeTIMESTAMP=$(date -u +%Y%m%d-%H%M%S)
PROJECT_ROOT=$(pwd)
PLAN=()
# 1. configuration.json → configuration.yml
if [[ -f ".claude/configuration.json" && ! -f ".claude/configuration.yml" ]]; then
PLAN+=("config-json-to-yml:.claude/configuration.json")
fi
# 2. Per-skill state files → state.json
LEGACY_STATE_NAMES=(
"brainstorm-state.json:brainstorm"
"requirements-state.json:requirements"
"proposal-state.json:proposal"
"implementation-state.json:implementation"
"epic-state.json:epic"
)
WORK_DIR=$(resolve_artifact work work 2>/dev/null || echo ".claude/work")
for dir in "$WORK_DIR"/*/; do
[[ -d "$dir" ]] || continue
for pair in "${LEGACY_STATE_NAMES[@]}"; do
old_name="${pair%:*}"
type_field="${pair#*:}"
if [[ -f "${dir}${old_name}" && ! -f "${dir}state.json" ]]; then
PLAN+=("state-rename:${dir}${old_name}:${type_field}")
fi
done
done
# 3. domain_knowledge key in configuration.yml
if [[ -f ".claude/configuration.yml" ]] && grep -q '^[[:space:]]*domain_knowledge:' ".claude/configuration.yml"; then
PLAN+=("rename-key:.claude/configuration.yml:domain_knowledge:product_knowledge")
fi
Report the plan to the user:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Migration Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Legacy config file .claude/configuration.json → .claude/configuration.yml
Legacy state file .claude/work/JIRA-123/requirements-state.json → state.json (type: requirements)
Legacy config key .claude/configuration.yml: domain_knowledge → product_knowledge
Backups will be written as *.bak-${TIMESTAMP}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If PLAN is empty, report:
✓ No legacy formats detected. Nothing to migrate.
…and exit.
Use AskUserQuestion:
If "Cancel" → stop with: "Migration cancelled. No files were modified."
For each planned action, create the backup, then rewrite:
config-json-to-yml (uses yq to convert JSON to YAML):
cp ".claude/configuration.json" ".claude/configuration.json.bak-${TIMESTAMP}"
yq -P '.' ".claude/configuration.json" > ".claude/configuration.yml"
# Only remove original after successful YAML write
if [[ -s ".claude/configuration.yml" ]]; then
rm ".claude/configuration.json"
fi
state-rename (add type field, rename file):
if [[ -s "${dir}state.json" ]]; then
echo "⚠ Skipping ${old_path} — ${dir}state.json already written by an earlier migration in this directory."
continue
fi
cp "${old_path}" "${old_path}.bak-${TIMESTAMP}"
jq --arg t "${type_field}" '. + {type: $t}' "${old_path}" > "${dir}state.json"
if [[ -s "${dir}state.json" ]]; then
rm "${old_path}"
fi
rename-key (update a top-level YAML key, preserve structure):
cp "${file}" "${file}.bak-${TIMESTAMP}"
yq -i '.product_knowledge = .domain_knowledge | del(.domain_knowledge)' "${file}"
After each action, print a single line confirmation:
✓ .claude/configuration.json → .claude/configuration.yml (backup: .bak-20260423-160500)
✓ .claude/work/JIRA-123/requirements-state.json → state.json (backup: .bak-20260423-160500)
✓ .claude/configuration.yml: domain_knowledge → product_knowledge (backup: .bak-20260423-160500)
If any step fails, stop and report which action failed. The user can retry after resolving the issue.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Migration Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Actions applied: {count}
Backups created: {count}
Next step: run /configuration-init validate to confirm the
rewritten configuration passes validation.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scope note: This migration only handles known-historical format changes. Unknown legacy formats are left untouched — the user can file an issue if they encounter a case this skill misses.
/configuration-init
# → Select execution mode: Sub-agent
# → Select: No team repository
# → Select local path: .claude (Recommended)
# → Writes local-only configuration.yml with path: .claude
/configuration-init
# → Select execution mode: Sub-agent
# → Select: Yes, configure team repository
# → Select repo path: /home/user/code/team-knowledge (default)
# → Select local path: .claude (Recommended)
# → Use default requirements behavior
# → Writes configuration.yml with team-repo location and shared artifacts
/configuration-init
# → Select execution mode: Sub-agent
# → Select: No team repository
# → Select local path: Other → type ".data"
# → Writes configuration.yml with path: .data
/configuration-init
# → Shows current config
# → Select: Validate
# → Runs all checks, reports pass/warn/fail
# → Shows "Configuration is valid" or suggests fixes
/configuration-init migrate
# → Scans for legacy configuration.json, *-state.json, domain_knowledge key
# → Prints plan; no writes yet
# → Asks for confirmation (Apply / Cancel)
# → On Apply: creates .bak-TIMESTAMP copies, rewrites in place
# → Reports which migrations landed; suggests running validate next
/configuration-init
# → Shows current config
# → Select: Reconfigure
# → Walks through wizard again
# → Overwrites with new configuration
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub nexus-a1/claude-skills --plugin nexus