Scaffold project structure and Synthex configuration.
Invocation
Run from inside Claude Code in any project where Synthex is installed:
/synthex:init
Some commands accept parameters; see the source-of-truth file linked below for the full parameter list and workflow.
Lifecycle phase
Setup. One-time project scaffolding.
Related agents
No agents declare this command's lifecycle phase. The command runs structurally — delegating to whichever agents the command's workflow names directly.
/synthex:init/synthex:init sets up Synthex in a project. You run it once per repo; re-running is
safe.
Checks for an existing config at config_path. If one exists, it asks whether to review
it, reset it to defaults, or leave it as-is.
Runs init-scaffold.sh in one shell call. The script:
copies the plugin's config/defaults.yaml to .synthex/config.yaml byte-for-byte (an
existing file is left alone unless you chose "reset to defaults", which re-runs it with
--force);
creates docs/reqs/, docs/plans/, docs/specs/, docs/specs/decisions/,
docs/specs/rfcs/, docs/runbooks/, and docs/retros/ if missing;
samples up to 50 commits from git log and writes the majority convention to
git.commit_convention (conventional, issue-key, gitmoji, plain, or auto when
nothing reaches 60%). This re-samples on every run.
Writes .synthex/facts.md — cached project facts (commit convention, test runner and
coverage command, frontend framework, spec index), each with a freshness rule. Facts it
can't detect are left out rather than guessed. Other commands read this file first and fall
back to detecting directly when a fact is missing or stale.
Asks how many parallel tasks to run. It detects your CPU count (falling back to 12) and
offers Yolo (all CPUs), Aggressive (75% of CPUs, minimum 8), Default (3), or a custom
positive integer. The answer is written to both implementation_plan.concurrent_tasks and
next_priority.concurrent_tasks.
Configures multi-model review (optional) by running the
/synthex:configure-multi-model/synthex:configure-multi-model wizard inline in fresh-configuration mode: CLI
detection, the three options, and the data-transmission warning.
Updates .gitignore with the five per-developer paths: .claude/worktrees/ (or your
worktrees.base_path), .synthex/state.json, .synthex/loops/, .synthex/facts.md, and
.synthex/config.local.yaml. Lines already present are skipped.
Creates .worktreeinclude (if missing) listing .env and .env.local, so Claude Code
copies those gitignored files into new worktrees. An existing file is never touched. It's
meant to be committed.
Asks about starring the repo, running the prompt from /synthex:star/synthex:star inline.
Prints a summary of what it created, next steps, and the available commands.
Parameters
Parameter
Description
Default
Required
config_path
Where to create the config file
.synthex/config.yaml
No
Configuration
init writes configuration rather than reading it. The keys it sets in the new config:
Key
Default shipped
Set by init to
implementation_plan.concurrent_tasks
3
Your parallelism choice
next_priority.concurrent_tasks
3
Your parallelism choice
git.commit_convention
auto
Detected from the last 50 commits
multi_model_review.*
disabled
Whatever you pick in the wizard
The commit-lint.sh hook only lints commit messages when git.commit_convention is exactly
conventional.
Output
.synthex/config.yaml — the shared, committed project config.
.synthex/facts.md — cached facts, gitignored (they hold per-clone SHAs and mtimes).
.gitignore and .worktreeinclude updates.
The seven docs/ directories (empty — no files are created inside them).
Console lines such as Detected commit convention: conventional (from 50 commits) and
Wrote 4 facts to .synthex/facts.md.
init does not create .synthex/config.local.yaml; it only gitignores it so one developer's
overrides for this repo never get committed.
Examples
/synthex:init/synthex:init config/synthex.yaml
Host notes
On Claude Code the scaffold script runs from ${CLAUDE_PLUGIN_ROOT}/scripts/init-scaffold.sh.
On other hosts (Codex, Gemini CLI, OpenCode, Grok, Hermes), or when that variable is empty, it
resolves the plugin root from plugin_root in .synthex/state.json.
Without a shell tool (or if the script is missing), init falls back to the Read and Write
tools for the config copy and runs the same commit-convention classification itself. It never
shells out with the defaults file as an argument, so the plugin's template can't be
overwritten.
The script checks writability first and exits with a clear message in a read-only sandbox.
See also
/synthex:configure-multi-model/synthex:configure-multi-model — re-run the multi-model wizard later