Project Configuration

Automate your development workflow with custom scripts and environment setup using .zenflow/settings.json

Overview

Zenflow supports project-level automation through a .zenflow/settings.json configuration file that you can add to your repository. This file defines scripts and behaviors that execute at specific points in your task lifecycle, enabling consistent environment setup, automated testing, and verification across all tasks in your project.

Why it matters

Project configuration ensures every task runs with the right dependencies, environment files, and validation checks—eliminating manual setup and catching issues before code reaches review.

Getting Started with Project Configuration

If your project doesn’t have a .zenflow/settings.json file yet, Zenflow will display a sidebar notification prompting you to set one up.

You can use the guided setup flow to create your configuration:

1. Click “Set up” from the sidebar notification
2. Zenflow creates a task where an agent analyzes your repository structure, dependencies, and typical development workflow
3. Review the suggested configuration that the agent generates based on your project
4. Edit the configuration to match your specific needs
5. Merge the changes directly or create a pull request for team review

This guided approach ensures your project configuration is tailored to your repository’s technology stack and development practices.

Configuration File Structure

Create a .zenflow/settings.json file in the root of your repository with the following structure:

{
  "setup_script": "npm install && npm run build",
  "dev_server_script": "npm run dev",
  "verification_script": "npm run lint && npm test",
  "copy_files": [
    ".env.local",
    "secrets/api-keys.json",
    "config/local.config.js"
  ]
}

All fields are optional—configure only what your project needs.

Configuration Fields

setup_script

Executes after each task worktree is created

The setup script runs automatically when Zenflow creates a new Git worktree for a task. Use this to install dependencies, configure the environment, or prepare the workspace for development.

Common use cases:

• Installing project dependencies (npm install, pip install -r requirements.txt, bundle install)
• Building necessary artifacts (npm run build, make setup)
• Initializing databases or running migrations
• Setting up git hooks or local tools

Example:

{
  "setup_script": "pnpm install && pnpm run db:migrate"
}

The setup script runs in the root of the newly created worktree with the project’s default shell environment. Long-running setup steps are visible in the task logs.

dev_server_script

Defines the command to start your development server

While not currently executed automatically, this field documents how to run your project’s development server. Future Zenflow versions will use this to automatically start and manage dev servers during task execution.

Common use cases:

• Starting local development servers (npm run dev, python manage.py runserver)
• Running hot-reload watchers
• Launching containerized environments (docker-compose up)

Example:

{
  "dev_server_script": "npm run dev -- --port 3000"
}

Define this field now to future-proof your configuration and document your development workflow for team members.

verification_script

Runs after each agent turn to validate changes

The verification script executes automatically after every agent interaction within a task, acting as a continuous quality gate. Use this to run linters, type checkers, tests, or any static analysis tools that should pass before the agent proceeds.

Common use cases:

• Running linters (eslint ., ruff check ., rubocop)
• Type checking (tsc --noEmit, mypy .)
• Running unit tests (npm test, pytest, go test ./...)
• Security scanning (npm audit, safety check)
• Custom validation scripts

Example:

{
  "verification_script": "npm run typecheck && npm run lint && npm test -- --coverage"
}

Verification benefits

Automatic verification catches syntax errors, type issues, and test failures immediately—giving agents fast feedback to self-correct before changes accumulate.

How verification works:

1. Agent makes changes to the codebase
2. Verification script runs automatically
3. If the script exits with code 0 (success), the task continues
4. If the script fails (non-zero exit), you’ll see the error output and can instruct the agent to fix the issues

Planned feature: Future versions will automatically pass verification errors to agents for self-correction. Currently, you review errors and provide guidance to the agent as needed.

Keep verification scripts fast (under 30 seconds when possible) to avoid slowing down agent iterations. Consider running only critical checks in verification and deferring comprehensive test suites to CI/CD.

copy_files

List of files to copy into each task worktree

Specify files that should be copied from your local development environment into every task worktree. This is essential for environment-specific configuration, secrets, and local settings that shouldn’t be committed to version control.

Common use cases:

• Environment files (.env, .env.local, .env.development)
• API keys and secrets (secrets.json, credentials.yaml)
• Local configuration overrides (config.local.js, settings.local.py)
• SSL certificates for local development
• Private keys for service authentication

Example:

{
  "copy_files": [
    ".env.local",
    "config/database.local.yml",
    ".secrets/api-keys.json",
    "certs/localhost.pem"
  ]
}

Using glob patterns:

Glob patterns are supported for matching multiple files at once:

{
  "copy_files": [
    ".env*",
    "config/*.local.json",
    ".secrets/**/*.key",
    "certs/**/*.pem"
  ]
}

Common glob patterns:

• *.env - All files ending with .env in the root directory
• .env* - All files starting with .env (e.g., .env.local, .env.test)
• config/**/*.json - All JSON files in config directory and subdirectories
• secrets/*.{key,pem} - All .key and .pem files in the secrets directory

Path resolution:

• Paths are relative to your repository root
• Files are copied from your main working directory to the same relative path in each task worktree
• Subdirectories in paths are created automatically if they don’t exist
• Both explicit file paths and glob patterns are supported

Security reminder: The source files must exist in your local repository directory (even if git-ignored). Never commit sensitive files to version control—use .gitignore to exclude them while keeping them available for worktree copying.

Complete Example

Here’s a comprehensive configuration for a Node.js web application:

{
  "setup_script": "pnpm install && pnpm run db:migrate && pnpm run build:deps",
  "dev_server_script": "pnpm run dev",
  "verification_script": "pnpm run typecheck && pnpm run lint && pnpm test:unit -- --run",
  "copy_files": [
    ".env*",
    "config/*.local.json",
    ".secrets/**/*.json"
  ]
}

This configuration:

1. Installs dependencies, runs migrations, and builds supporting packages when creating the worktree
2. Documents the dev server command for future use
3. Verifies TypeScript types, linting rules, and unit tests after each agent turn
4. Copies all environment files (.env.local, .env.test, etc.), local config files, and secret JSON files into the worktree using glob patterns

Best Practices

Keep setup scripts idempotent

Design setup scripts to be safely re-runnable. Avoid commands that fail if run multiple times, or add conditional checks to skip steps that are already complete.

Example: Check if dependencies are already installed before running a slow installation step.

Use verification scripts strategically

Balance thoroughness with speed. Include critical checks (linting, type checking, fast unit tests) in verification, but save comprehensive integration tests and end-to-end tests for CI/CD after PR creation.

Document environment file requirements

Create a .env.example or README section that lists all required environment variables. This helps team members understand what files need to be present for copy_files to work correctly.

Version your project configuration

Commit .zenflow/settings.json to version control so the entire team shares the same automation setup. This creates a single source of truth for project workflow configuration.

Use exit codes correctly

Ensure your verification script exits with code 0 only when all checks pass. Most test runners and linters already follow this convention, but custom scripts should explicitly exit 1 on failure.

Troubleshooting

Setup script fails when creating worktree

Check the task logs to see the exact error output. Common issues:

• Missing dependencies on the system (Node.js, Python, package managers)
• Incorrect paths in the script (remember it runs from the worktree root)
• Network issues preventing dependency downloads
• Insufficient permissions for file operations

Solution: Test the setup script manually in a fresh clone of your repository to reproduce the issue.

Verification script always fails

If your verification script consistently fails even when code looks correct:

• Ensure the script runs successfully in your main development directory first
• Check that all required files are being copied via copy_files (e.g., .env files)
• Verify that the setup script completed successfully before verification runs
• Confirm that your verification commands are compatible with CI-style execution (no interactive prompts)

Tip: Add echo statements to your verification script to debug which specific command is failing.

Copy files not appearing in worktree

If files specified in copy_files aren’t being copied:

• Confirm the files exist in your main repository directory (check the exact paths)
• Verify paths are relative to the repository root, not absolute paths
• Check file permissions—Zenflow needs read access to the source files
• Look for typos in file paths (paths are case-sensitive on Unix systems)

Note: Files are copied when the worktree is created, not continuously synced. Changes to source files require recreating the task worktree.

Configuration file not being recognized

Zenflow looks for .zenflow/settings.json in the repository root. Ensure:

• The file path is exactly .zenflow/settings.json (note the leading dot)
• The JSON is valid (use a JSON validator or jq to check)
• The file is committed and present in the branch being used for task creation
• You’ve restarted Zenflow or refreshed the project after adding the configuration

Next Steps

Task Types

Learn how different task types use your project configuration to execute workflows

Integrations and Settings

Configure additional project settings like AI rules and GitHub integration

Orchestrating Agents

Understand how agents use verification scripts to self-correct and improve

Support & Troubleshooting

Get help with common issues and learn how to report problems