Project setup

Everything a workspace needs to be useful the moment it exists lives in one committed file. Getting this right once is worth more than any other configuration work in the product: it is the difference between “the new workspace is ready” and “the new workspace is a broken checkout I have to fix by hand.” For the complete key list, including which keys are not yet wired up, see the settings reference.

Three layers

Layer	Where	Commit it?
App shared defaults	Application settings, per machine	n/a
Repository settings	`.archductor/settings.toml`	Yes
Local overrides	`.archductor/settings.local.toml`	No — gitignore it

Later layers win key by key. Team decisions go in settings.toml; absolute paths, personal endpoints, and anything secret go in settings.local.toml.

archductor archcar settings --repository my-app                    # effective merged settings
archductor archcar settings-source --repository my-app --layer local
archductor repo settings my-app export --output team.toml
archductor repo settings my-app import team.toml

Reading the effective settings rather than the file is the reliable way to answer “why is this workspace behaving like that” — it is the merged result the daemon actually uses.

Scripts

[scripts]
setup     = "pnpm install --frozen-lockfile"
run       = "pnpm dev --port $ARCHDUCTOR_PORT"
archive   = "./script/workspace-archive.sh"
test      = "pnpm test"
lint      = "pnpm lint"
typecheck = "tsc --noEmit"
build     = "pnpm build"
run_mode  = "concurrent"

setup runs once when a workspace is created. The single most important key in the file: a fresh worktree has no gitignored files, so no dependencies, no build output, no virtualenv.
run is the long-running dev process, started and stopped from the app or with archductor run / archductor stop.
archive runs on archive — tear down containers, free a database.
test / lint / typecheck / build become the workspace’s checks.
run_mode defaults to concurrent. Set nonconcurrent when the dev server binds something genuinely global (a fixed database port, a docker network) and only one workspace may run at a time. Starting a second run then fails with a message naming the workspace already running, instead of a confusing port collision.

Several run scripts

When a workspace starts more than one thing, run takes a table:

[scripts.run.web]
command = "pnpm dev --port $ARCHDUCTOR_PORT"
default = true

[scripts.run.worker]
command = "pnpm worker"

Checks

There is no separate checks configuration. The four script keys are it.

archductor archcar check-list <workspace>       # what is configured
archductor archcar run-check <workspace> test   # run one, by key
archductor archcar check-log <workspace>        # latest output
archductor checks <workspace>                   # stored summary

Keys are test, lint, typecheck, build. Each falls back to customization.automation.<name>_command if the [scripts] key is unset; prefer [scripts]. The same four commands also populate the command palette.

Getting local files into a workspace

# .worktreeinclude — one pattern per line, repository root
.env*
certs/**

# .archductor/settings.toml — added to the above, not overridden by it
file_include_globs = """
.env
config/*.local.json
"""

The two sources are combined, not ranked: the .worktreeinclude lines and file_include_globs are concatenated into one pattern list. A .worktreeinclude does not disable file_include_globs. With both genuinely empty, nothing is copied — .env* is scaffolded into a new settings.toml at bootstrap, but it is not a runtime fallback. Lines starting with ! or # are discarded, so gitignore-style negation does not work. Only gitignored files are ever copied.

env_file_refs = """
.env
"""

env_file_refs is different from copying: these files are parsed and their variables injected into scripts and agent processes.

Every env_file_refs path must exist when a workspace launches, or the launch fails. That is intentional — a missing .env should be a loud error, not an app that boots with empty configuration. The workspace copy is preferred; the repository root is the fallback.

Environment

[environment_variables]
NODE_ENV = "development"
API_BASE = "http://localhost:8080"

Scripts and agent processes always receive these built-ins:

Variable	Value
`ARCHDUCTOR_WORKSPACE_NAME`	The workspace name
`ARCHDUCTOR_WORKSPACE_PATH`	Absolute path to the worktree
`ARCHDUCTOR_WORKING_DIRECTORY`	Where scripts actually run
`ARCHDUCTOR_ROOT_PATH`	Absolute path to the main repository checkout
`ARCHDUCTOR_DEFAULT_BRANCH`	The repository’s default branch
`ARCHDUCTOR_PORT`	Base of this workspace’s reserved port block
`ARCHDUCTOR_IS_LOCAL`	Always `1`

Precedence, lowest to highest: built-ins, then env_file_refs contents, then [environment_variables].

Prompts and prompt packs

Prompts are the text sent to an agent for each built-in action — creating a pull request, resolving conflicts, fixing failing tests. Worth editing, because they encode how your repository wants those jobs done.

[prompt_pack]
active = "team"
path = ".archductor/prompt-packs/team.toml"

[prompts]
create_pr = "Write the PR body in our house format: Summary, Risk, Rollback."

A pack is a file under .archductor/prompt-packs/; default.toml is created on bootstrap. Available keys in both [prompts] and a pack: new_workspace, general, continue_work, summarize_session, handoff, code_review, create_pr, fix_errors, resolve_merge_conflicts, rename_branch, commit_generation, push_branch, merge_pr, revert_changes, review_comments, test_fixing, refactor_style, setup_script, run_script. Inline [prompts] overrides the active pack, so a pack can carry house defaults while one repository deviates on a single key.

archductor archcar prompt-packs my-app
archductor archcar set-prompt-pack my-app team
archductor archcar git-action-prompt <workspace> --action create-pr

Pull requests

[customization.naming]
default_merge_method = "squash"
pr_title_template = "{type}({workspace}): {summary}"
pr_body_sections = ["Summary", "What Changed", "Risk", "Validation"]

Title placeholders: {workspace}, {branch}, {summary}, {session_summary}, {changed_files}, {changed_files_count}, {type}. pr_body_sections replaces the default headings (Summary, What Changed, Why, User Impact, Validation). Content is generated by matching the heading text, so keep recognisable words in your section names.

Merge rules

[customization.merge_rules]
block_on_open_todos = true       # default true
block_on_open_comments = true    # default true
block_on_failed_checks = false   # default false
block_on_pending_checks = false  # default false

Enforced by archductor pr merge. The first two default to on, so an open todo refuses the merge until you close it or opt out.

Workspace defaults

[customization.workspace_defaults]
base_branch = "main"
workspace_parent = "~/worktrees/my-app"
branch_prefix = "pk"          # default "lc"
working_directory = "apps/web"
port_block_size = 20          # default 10
default_visible_tab = "changes"

working_directory is the monorepo key: scripts and agent sessions start there instead of at the worktree root.

A working example

.archductor/settings.toml

"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"

file_include_globs = """
.env
.env.local
"""

env_file_refs = """
.env
"""

[scripts]
setup     = "pnpm install --frozen-lockfile"
run       = "pnpm dev --port $ARCHDUCTOR_PORT"
test      = "pnpm test"
lint      = "pnpm lint"
typecheck = "tsc --noEmit"

[environment_variables]
NODE_ENV = "development"

[git]
archive_on_merge = true

[customization.naming]
default_merge_method = "squash"
pr_body_sections = ["Summary", "What Changed", "Risk", "Validation"]

[customization.merge_rules]
block_on_failed_checks = true

[customization.workspace_defaults]
base_branch = "main"
port_block_size = 20

[customization.view]
default_layout_preset = "code"

Get started

Guides

Reference

Three layers

Scripts

Several run scripts

Checks

Getting local files into a workspace

Environment

Prompts and prompt packs

Pull requests

Merge rules

Workspace defaults

A working example

​Three layers

​Scripts

​Several run scripts

​Checks

​Getting local files into a workspace

​Environment

​Prompts and prompt packs

​Pull requests

​Merge rules

​Workspace defaults

​A working example

Three layers

Scripts

Several run scripts

Checks

Getting local files into a workspace

Environment

Prompts and prompt packs

Pull requests

Merge rules

Workspace defaults

A working example