Configuration

Customize CLI behavior with .wseng configuration files at personal and project levels.

Configuration Files

The CLI uses JSON configuration files stored in two locations:

Personal Configuration

Location: ~/.wseng (your home directory)

This file contains your user-specific settings that apply across all projects:

• awsProfile: Default AWS profile to use
• emailAddress: Your work email address
• localPaths: Where your repositories are cloned
• commandConfigurations: User-specific command defaults
• extensionVersions: VSCode extension versions
• obsSettings: OBS Studio settings for demo recording

Project Configuration

Location: .wseng (in each project root directory)

This file contains project-specific settings:

• contextFolder: Where context files are stored (default: .context)
• specs: List of spec documents to pull
• pullRequestTemplate: PR template using Handlebars syntax
• commandConfigurations: Project-specific command defaults
• stagingBranch: Staging branch name for the project

Creating Configuration Files

Run wseng init in any repository to create/update configuration files:

cd /path/to/your/project
wseng init

What this creates:

• Personal config at ~/.wseng (if it doesn't exist)
• Project config at .wseng in the current directory
• Context folder (typically .context/)

You can run wseng init multiple times. It updates existing configs without losing custom settings.

Command Configurations

Both personal and project configs support commandConfigurations to set default parameter values for any command.

Structure

{
  "commandConfigurations": {
    "command-name": {
      "defaultInputs": {
        "parameterName": value
      }
    }
  }
}

Example: Personal Configuration

Configure start-ticket to always use current branch as base:

{
    "awsProfile": "wseng-dev",
    "emailAddress": "you@trilogy.com",
    "localPaths": ["/Users/you/code"],
    "commandConfigurations": {
        "start-ticket": {
            "defaultInputs": {
                "currentBranchAsBase": true
            }
        }
    }
}

Now wseng start-ticket LAMBDA-12345 automatically uses your current branch as the base instead of main.

Example: Project Configuration

Configure commit command for a specific project:

{
    "contextFolder": ".context",
    "stagingBranch": "staging",
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "push": false,
                "check": true
            }
        }
    }
}

Now commits in this project won't auto-push and will run pre-commit checks.

Release-Notes Profiles

The release-notes command (wseng rn) supports named profiles declared in the project's .wseng under commandConfigurations["release-notes"].profiles. A profile points the command at a different audience: it replaces the whole system prompt with a repo-owned file, and can set its own output schema, model, evidence grounding, and diff settings. Select one with --prompt-profile <name>.

Example

{
    "commandConfigurations": {
        "release-notes": {
            "profiles": {
                "kid-friendly": {
                    "promptFile": ".github/whats-new/kid-changelog.instructions.md",
                    "outputSchemaFile": ".github/whats-new/kid-changelog.schema.json",
                    "model": "claude-opus",
                    "evidence": "diff",
                    "diff": {
                        "pathspecs": ["src/frontend/**", "src/api/**"],
                        "maxTotalBytes": 409600
                    }
                }
            }
        }
    }
}

Profile fields:

• promptFile (required): path to a file whose content becomes the system prompt verbatim. The CLI-assembled evidence (tickets, commit subjects, and/or the net diff, per evidence) is sent as the user message.
• outputSchemaFile: path to a JSON Schema file. The generation result is validated against it and returned exactly as the model produced it. The schema root must be an object type (or a oneOf/anyOf of object types).
• model: one of the CLI's model names (e.g. claude-opus, gemini-pro). Defaults to gemini-pro.
• evidence: tickets (default), diff, or both. diff grounds the model in the net code diff of the range and skips ticket fetching entirely — a feature added and removed inside the same range cancels out of the code diff, so no code evidence of it reaches the model. The evidence block still lists every commit subject in the range (for ordering and context), so a profile prompt that must never mention cancelled work should instruct the model to ground its content on the code changes.
• diff.pathspecs: git pathspecs limiting which files' patches the model reads. The diff stat always covers all non-excluded paths, so the model still sees that other files changed without reading them.
• diff.maxFileBytes / diff.maxFileLines: per-file caps (defaults: 200 KiB / 5000 lines); oversized files are truncated with a [truncated: ...] marker.
• diff.maxTotalBytes: total patch budget (default 400 KiB); once exceeded, each remaining file appears only as (diff omitted: <path>) and the omissions are logged.

Path rule: promptFile and outputSchemaFile resolve relative to the directory containing .wseng, not the invocation directory.

Setting resolution: a resolved command input (a typed flag or a .wseng defaultInputs entry) wins over the profile's value, which wins over the built-in default.

When a profile declares outputSchemaFile, the markdown (--output-file) and Google Chat (--chat-space) outputs are skipped with a warning — their layouts assume the built-in {summary, bulletPoints} shape. The results are available on the terminal and via --json-output-file.

Release-Notes Flags and Invocation

The two invocation shapes consumers typically use:

# A technical Chat post over an explicit commit range
wseng rn --from-sha <a> --to-sha <b> --chat-space "My Team Space"

# An audience profile writing JSON for downstream publish machinery
wseng rn --prompt-profile kid-friendly --from-sha <a> --to-sha <b> --json-output-file /tmp/notes.json

• --from-sha <sha> (exclusive) and --to-sha <sha> (inclusive, defaults to HEAD) select the commit range directly, skipping the workflow-history lookup. The checkout must be deep enough to contain from — raise fetch-depth on the checkout step if the command reports a missing commit.
• --evidence tickets|diff|both selects what the model is grounded in without needing a profile.
• --json-output-file <path> writes the schema-validated generation result as JSON. The file holds the model result verbatim with nothing added — no metadata, no envelope — so strict downstream parsers keep working. On a generation failure, the CLI exits non-zero and writes no file. An empty commit range exits zero without writing a file, so downstream publish machinery should gate on file presence, not exit code alone.
• --json-output-file composes with --dry-run the way --output-file does: the file is still written; confirmation and Chat posting are skipped.

Configuration Precedence

When the CLI looks up a parameter value:

1. Explicit command-line argument (highest priority)
2. Project configuration (.wseng in project root)
3. Personal configuration (~/.wseng in home directory)
4. Command default (defined in CLI code)

Example

# Project config sets: "currentBranchAsBase": true
# Personal config sets: "currentBranchAsBase": false

# This uses project config (true)
wseng start-ticket LAMBDA-12345

# This overrides everything (false)
wseng start-ticket LAMBDA-12345 --no-current-branch-as-base

Model Selection for Large Diffs (infer-breakdown)

When using the infer-breakdown command on tickets with large PR diffs, you may need to use a model with a larger context window. The CLI will automatically detect if your input is too large and suggest alternatives.

Available Models by Context Window

Using a Specific Model

Command line:

# Claude with 1M context (via Bedrock)
wseng --model claude-4-5-sonnet ws infer-breakdown TICKET-123

# Gemini with 1M context
wseng --model gemini-pro ws infer-breakdown TICKET-123
wseng --model gemini-2.5-pro ws infer-breakdown TICKET-123

Configuration file (~/.wseng):

{
    "model": "gemini-pro"
}

Token Limit Errors

If your input exceeds the model's context window, the CLI will:

1. Stop before making the API call
2. Show the estimated token count vs. model's context window
3. Suggest models with larger context windows (1M tokens)

Model Tracking

The model_used field in the estimation YAML output records which model was used for inference, helping with reproducibility and debugging.

Default Model

The default model is claude-4-5-sonnet which has a 1M token context window via AWS Bedrock.

Common Configuration Patterns

Always Stage Changes Before Commit

Personal ~/.wseng:

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "stage": true
            }
        }
    }
}

Skip Git Sync for Fast Workflows

Personal ~/.wseng:

{
    "commandConfigurations": {
        "start-ticket": {
            "defaultInputs": {
                "gitSync": false
            }
        }
    }
}

Custom Context Folder Location

Project .wseng:

{
    "contextFolder": "docs/context"
}

Configure Multiple Commands

Personal ~/.wseng:

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "push": true,
                "stage": true
            }
        },
        "start-ticket": {
            "defaultInputs": {
                "clearContext": true,
                "gitSync": true
            }
        },
        "review-work": {
            "defaultInputs": {
                "includeSubtasks": true
            }
        }
    }
}

Disabling Personal Defaults

Sometimes you want to ignore personal configuration for a single command:

wseng commit --no-personal-defaults

This uses only project config and CLI defaults, skipping your personal commandConfigurations.

Interactive Configuration

Instead of manually editing JSON, use the interactive configuration command:

wseng ws configure-command-defaults <command-name> --scope personal
# or
wseng ws configure-command-defaults <command-name> --scope project

Example:

wseng ws configure-command-defaults commit --scope personal

This opens an interactive prompt for each parameter where you can:

• Skip (keep current value)
• Set/modify default value
• Remove default (if one exists)

The CLI validates your inputs and updates the appropriate config file automatically.

Common Configuration Issues

❌ Bad: Invalid JSON syntax

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "push": true // Comments not allowed in JSON!
            }
        }
    }
}

Solution: Use a JSON validator. No trailing commas, no comments.

❌ Bad: Wrong parameter names

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "autoPush": true // Wrong! Parameter is "push"
            }
        }
    }
}

Solution: Check command help for exact parameter names:

wseng commit --help

❌ Bad: Wrong value types

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "push": "true" // Wrong! Should be boolean true, not string "true"
            }
        }
    }
}

Solution: Use correct JSON types: true/false for booleans, numbers without quotes, strings with quotes.

Configuration Files in Git

✅ Good: Commit project config

git add .wseng
git commit -m "chore: add project configuration"

Project .wseng files should be committed so all team members share project defaults.

❌ Bad: Commit personal config

Never commit ~/.wseng to Git. It's user-specific and lives outside repositories.

✅ Good: Document project config

Add comments to your PR when changing project .wseng:

Updated project config:
- Disabled auto-push for commits (requires explicit push)
- Enabled pre-commit checks by default

Related Docs

Configuration Reference

Auto-generated reference for .wseng configuration file properties.

Command Reference

See all available commands and their configurable parameters.