Skip to main content

Configuration Reference

SpecWeave uses three configuration surfaces: project config (config.json), increment metadata (metadata.json), and environment variables. This page documents every property, its type, default value, and purpose.

Config File Locations​

FileLocationScope
Project config.specweave/config.jsonPer-project settings
Increment metadata.specweave/increments/{id}/metadata.jsonPer-increment state

SpecWeave creates config.json during specweave init. Edit it directly or use CLI commands that modify it on your behalf.

Quick Reference: Disableable Features​

The most common configuration need is turning features on or off. This table shows every disableable feature at a glance.

FeatureConfig PathValue to DisableDefault
Living docs (copy-based sync)livingDocs.copyBasedSync.enabledfalsetrue
Living docs (three-layer sync)livingDocs.threeLayerSync.enabledfalsetrue
Living docs auto-generationlivingDocs.copyBasedSync.autoGeneratefalsetrue
TDD enforcementtesting.tddEnforcement"off"(not set)
Deep interview modeplanning.deepInterview.enabledfalsefalse
Plugin auto-loadingpluginAutoLoad.enabledfalsetrue
Reflection / skill learningreflect.enabledfalsetrue
Grill quality gategrill.requiredfalsetrue
External syncsync.enabledfalsefalse
Auto-sync on completionsync.autoSyncfalsefalse
Auto-create external issueshooks.post_increment_planning.auto_create_github_issuefalsetrue
Close external issue on donehooks.post_increment_done.close_github_issuefalsetrue
Living docs sync on donehooks.post_increment_done.sync_living_docsfalsetrue
Increment assistincrementAssist.enabledfalsetrue
Increment assist (mandatory)incrementAssist.mandatoryfalsetrue
Status linestatusLine.enabledfalsetrue
Auto-archivearchiving.autoArchivefalsefalse
API docs generationapiDocs.enabledfalsefalse
Translationtranslation.enabledfalsefalse
Context budget auto-adaptcontextBudget.autoAdaptfalsetrue
CI/CD auto-fixcicd.autoFix.enabledfalsetrue
Deduplicationdeduplication.enabledfalsetrue
Multi-repo workspaceworkspace.repos[] (empty array = single-project)—
All hooks at onceenv: SPECWEAVE_DISABLE_HOOKS1(not set)
Living Docs Trade-off

Living docs generate Architecture Decision Records (ADRs), API specs, and project knowledge that LLMs use to make better decisions in future increments. Disabling them speeds up increment closure but removes this accumulated context. Consider keeping them enabled if you use AI-assisted development across multiple sessions.

config.json Reference​

Core​

PropertyTypeDefaultDescription
versionstring"2.0"Config schema version. Used for automatic migrations
languagestring"en"Display language. Values: en, ru, es, zh, de, fr, ja, ko, pt
{
  "version": "2.0",
  "language": "en"
}

project​

Project metadata used for display and sync routing.

PropertyTypeDefaultDescription
namestring—Project display name
versionstring—Project version
descriptionstring—Project description
techStackstring[]—Technology keywords (e.g., ["typescript", "react"])
teamstring—Team identifier
{
  "project": {
    "name": "my-app",
    "version": "1.0.0",
    "techStack": ["typescript", "nextjs", "postgresql"]
  }
}

adapters​

Controls which LLM adapter SpecWeave uses for instruction generation.

PropertyTypeDefaultDescription
defaultstring"claude"Default adapter. Values: claude, cursor, generic
{
  "adapters": { "default": "claude" }
}

testing​

Testing mode, coverage targets, and TDD enforcement.

PropertyTypeDefaultDescription
defaultTestModestring"TDD"Test strategy. Values: TDD, test-after, manual, none
defaultCoverageTargetnumber90Default coverage percentage (0-100)
coverageTargets.unitnumber95Unit test coverage target
coverageTargets.integrationnumber90Integration test coverage target
coverageTargets.e2enumber100E2E test coverage target
tddEnforcementstring(not set)TDD enforcement level. Values: strict, warn, off
playwright.preferClibooleantrueUse Playwright CLI for E2E tests
playwright.cliFlagsstring[]—Additional Playwright CLI flags
{
  "testing": {
    "defaultTestMode": "TDD",
    "coverageTargets": { "unit": 95, "integration": 90, "e2e": 100 },
    "tddEnforcement": "strict",
    "playwright": { "preferCli": true }
  }
}

grill​

Quality gate requiring a grill report before increment closure.

PropertyTypeDefaultDescription
requiredbooleantrueRequire grill report before sw:done
{
  "grill": { "required": true }
}

limits​

Work-in-progress limits and staleness detection.

PropertyTypeDefaultDescription
maxActiveIncrementsnumber3Recommended max concurrent active increments
hardCapnumber5Absolute maximum active increments
allowEmergencyInterruptbooleantrueAllow hotfix/bug to bypass WIP limits
typeBehaviors.canInterruptstring[]["hotfix", "bug"]Increment types that can bypass limits
typeBehaviors.autoAbandonDays.experimentnumber14Days before auto-abandoning experiments
staleness.pausednumber7Days before marking paused increments as stale
staleness.activenumber30Days before marking active increments as stale
{
  "limits": {
    "maxActiveIncrements": 3,
    "hardCap": 5,
    "allowEmergencyInterrupt": true,
    "staleness": { "paused": 7, "active": 30 }
  }
}

planning​

Controls the deep interview feature during increment planning.

PropertyTypeDefaultDescription
deepInterview.enabledbooleanfalseEnable deep interview during sw:increment
deepInterview.enforcementstring—Enforcement level. Values: strict, warn, off
deepInterview.minQuestionsnumber5Minimum questions to ask
deepInterview.categoriesstring[](all 6)Question categories: architecture, integrations, ui-ux, performance, security, edge-cases
{
  "planning": {
    "deepInterview": {
      "enabled": true,
      "enforcement": "strict",
      "minQuestions": 5
    }
  }
}

incrementAssist​

Controls whether SpecWeave proactively suggests creating or reopening increments.

PropertyTypeDefaultDescription
enabledbooleantrueEnable increment assist
suggestNewIncrementbooleantrueSuggest creating new increments
suggestReopenbooleantrueSuggest reopening closed increments
confidenceThresholdnumber0.7Confidence required to trigger suggestion (0-1)
mandatorybooleantrueMake increment creation mandatory for implementation work
{
  "incrementAssist": {
    "enabled": true,
    "mandatory": false
  }
}

livingDocs​

Controls automatic living documentation synchronization.

PropertyTypeDefaultDescription
copyBasedSync.enabledbooleantrueEnable copy-based sync (spec copies to docs)
copyBasedSync.autoGeneratebooleantrueAuto-generate doc copies on increment done
threeLayerSync.enabledbooleantrueEnable three-layer sync (specs, ADRs, API docs)
threeLayerSync.autoSyncbooleantrueAuto-sync on changes
{
  "livingDocs": {
    "copyBasedSync": { "enabled": true, "autoGenerate": true },
    "threeLayerSync": { "enabled": true, "autoSync": true }
  }
}
Why Living Docs Matter

Living docs build up project knowledge over time — ADRs, API specifications, and increment history. LLMs use this context to make better architectural decisions in future increments. Disabling living docs removes this feedback loop but makes increment closure faster.

documentation​

Controls documentation preview and directory scanning.

PropertyTypeDefaultDescription
directoriesstring[][".specweave/docs"]Directories to scan for documentation
publicSitePathstring—Path to public documentation site
preview.enabledbooleanfalseEnable documentation preview server
preview.autoInstallboolean—Auto-install preview dependencies
preview.portnumber3015Preview server port
preview.openBrowserboolean—Auto-open browser on preview start
preview.themestring—Preview theme name
preview.excludeFoldersstring[]—Folders to exclude from preview
{
  "documentation": {
    "directories": [".specweave/docs"],
    "preview": { "enabled": true, "port": 3015 }
  }
}

apiDocs​

API documentation auto-generation from code.

PropertyTypeDefaultDescription
enabledbooleanfalseEnable API docs generation
openApiPathstring"openapi.yaml"Path to OpenAPI spec file
autoGenerateOpenApibooleantrueAuto-generate OpenAPI spec from code
generatePostmanbooleantrueGenerate Postman collection
postmanPathstring"postman-collection.json"Postman collection output path
postmanEnvPathstring"postman-environment.json"Postman environment output path
generateOnstring"on-increment-done"When to generate. Values: on-increment-done, on-api-change, manual
watchPatternsstring[]["**/routes/**", ...]File patterns to watch for API changes
baseUrlstring"http://localhost:3000"API base URL
{
  "apiDocs": {
    "enabled": true,
    "generateOn": "on-api-change",
    "watchPatterns": ["**/routes/**", "**/controllers/**"]
  }
}

sync​

External tool synchronization (GitHub, JIRA, Azure DevOps).

PropertyTypeDefaultDescription
enabledbooleanfalseMaster sync switch
directionstring"bidirectional"Sync direction. Values: import, export, bidirectional
autoSyncbooleanfalseAuto-sync on increment changes
includeStatusbooleantrueSync status fields
autoApplyLabelsbooleantrueAuto-apply labels during sync
providerstring—Exclusive provider: jira, github, ado
defaultProfilestring—Fallback sync profile name
autoCreateOnIncrementboolean—Auto-create external issues on increment creation
settings.canUpsertInternalItemsboolean—Allow creating internal items from external
settings.canUpdateExternalItemsboolean—Allow updating external items
settings.canUpdateStatusboolean—Allow status sync
settings.autoSyncOnCompletionboolean—Auto-sync when increment completes
github.enabledboolean—Enable GitHub sync
github.ownerstring—GitHub org/user
github.repostring—GitHub repository name
jira.enabledboolean—Enable JIRA sync
jira.domainstring—JIRA instance domain
jira.projectKeystring—JIRA project key
ado.enabledboolean—Enable Azure DevOps sync
ado.organizationstring—ADO organization
ado.projectstring—ADO project
profilesobject—Named sync profiles (keyed by profile ID)
{
  "sync": {
    "enabled": true,
    "direction": "bidirectional",
    "autoSync": true,
    "github": { "enabled": true, "owner": "my-org", "repo": "my-app" }
  }
}
Use sw:sync-setup to configure sync interactively instead of editing config.json manually.

hooks​

Lifecycle hooks that trigger actions on increment events.

PropertyTypeDefaultDescription
post_task_completion.sync_tasks_mdbooleantrueSync tasks.md after task completion
post_task_completion.external_tracker_syncbooleantrueSync to external tracker after task completion
post_increment_planning.auto_create_github_issuebooleantrueAuto-create external issue after planning
post_increment_planning.sync_living_docsbooleantrueSync living docs after planning
post_increment_done.sync_living_docsbooleantrueSync living docs on increment done
post_increment_done.sync_to_github_projectbooleantrueSync to GitHub project on done
post_increment_done.close_github_issuebooleantrueClose GitHub issue on done
post_increment_done.close_jira_issueboolean—Close JIRA issue on done
post_increment_done.close_ado_work_itemboolean—Close ADO work item on done
{
  "hooks": {
    "post_task_completion": { "sync_tasks_md": true, "external_tracker_sync": true },
    "post_increment_planning": { "auto_create_github_issue": false },
    "post_increment_done": { "sync_living_docs": true, "close_github_issue": true }
  }
}

issueTracker​

Issue tracking system provider configuration.

PropertyTypeDefaultDescription
providerstring"none"Provider. Values: none, jira, github, ado
domainstring—JIRA domain (JIRA only)
instanceTypestring—JIRA instance type. Values: cloud, server
strategystring—JIRA organization strategy. Values: single-project, project-per-team, component-based, board-based
projectsarray—JIRA project configurations
{
  "issueTracker": {
    "provider": "jira",
    "domain": "myteam.atlassian.net",
    "strategy": "single-project",
    "projects": [{ "key": "MYAPP", "name": "My Application" }]
  }
}

repository​

Repository provider and Git configuration.

PropertyTypeDefaultDescription
providerstring"local"Provider. Values: local, github, bitbucket, ado, gitlab, generic
organizationstring—Organization or team identifier
gitUrlFormatstring—Git URL format. Values: ssh, https
reposarray—Repository configurations
{
  "repository": {
    "provider": "github",
    "organization": "my-org",
    "gitUrlFormat": "ssh"
  }
}

cicd​

CI/CD pipeline and Git branching configuration.

PropertyTypeDefaultDescription
pushStrategystring"direct"Push strategy. Values: direct, pr-based
git.branchPrefixstring"sw/"Feature branch prefix
git.targetBranchstring"main"PR target branch
git.deleteOnMergebooleantrueDelete branch after merge
git.includeExternalKeybooleanfalseInclude JIRA/ADO key in branch name
release.strategystring—Release strategy. Values: trunk, gitflow, env-promotion
release.environmentsarray—Environment configs (for env-promotion)
autoFix.enabledbooleantrueEnable auto-fix on CI failure
autoFix.maxRetriesnumber1Max retry attempts
autoFix.allowedBranchesstring[]["develop", "main"]Branches where auto-fix is allowed
monitoring.pollIntervalnumber—CI poll interval (ms)
monitoring.autoNotifyboolean—Auto-notify on CI completion
{
  "cicd": {
    "pushStrategy": "pr-based",
    "git": { "branchPrefix": "sw/", "targetBranch": "develop" },
    "autoFix": { "enabled": true, "maxRetries": 2 }
  }
}

auto​

Autonomous execution mode (sw:auto) configuration.

PropertyTypeDefaultDescription
enabledboolean—Enable auto mode
maxRetriesnumber20Max retries before escalating
maxTurnsnumber50Max total turns in auto session
maxIterationsnumber2500Safety limit for iterations
maxHoursnumber—Max session hours
requireTestsbooleanfalseRequire tests pass before closure
requireValidationbooleantrueRequire sw:validate
requireJudgeLLMbooleanfalseRequire sw:judge-llm
skipQualityGatesbooleanfalseSkip all quality gates
testCommandstring—Custom test command
coverageThresholdnumber—Coverage requirement (%)
enforceTestFirstboolean—TDD enforcement in auto mode
{
  "auto": {
    "enabled": true,
    "maxRetries": 20,
    "requireTests": true,
    "requireValidation": true
  }
}

reflect​

Controls automatic skill learning from session corrections.

PropertyTypeDefaultDescription
enabledbooleantrueEnable reflection and skill memory extraction
modelstring"haiku"Model for extraction. Values: haiku, sonnet, opus
maxLearningsPerSessionnumber3Max learnings saved per session
{
  "reflect": { "enabled": false }
}

contextBudget​

Controls how much context SpecWeave injects into LLM prompts.

PropertyTypeDefaultDescription
levelstring"full"Budget level. Values: full (2500 chars), compact, minimal, off
autoAdaptbooleantrueAuto-reduce when context pressure detected
{
  "contextBudget": { "level": "compact", "autoAdapt": true }
}

skillGen​

Automatic skill generation from detected project patterns.

PropertyTypeDefaultDescription
detectionstring"on-close"When to detect patterns. Values: on-close, off
suggestbooleantrueShow skill suggestions on increment closure
minSignalCountnumber3Min pattern occurrences to qualify
maxSignalsnumber100Max signals to retain
declinedSuggestionsstring[][]Permanently excluded patterns
{
  "skillGen": { "detection": "off" }
}

translation​

Multi-language translation configuration.

PropertyTypeDefaultDescription
enabledbooleanfalseEnable auto-translation
languagesstring[]["en"]Enabled languages (always includes en)
primarystring"en"Primary output language
methodstring"auto"Trigger method. Values: auto, manual, none
preserveFrameworkTermsbooleantrueKeep SpecWeave terms in English
scope.incrementSpecsbooleanfalseTranslate increment specs
scope.livingDocsbooleanfalseTranslate living docs
scope.externalSyncbooleanfalseTranslate external sync content
keepEnglishOriginalsbooleanfalseKeep .en.md originals alongside translations
{
  "translation": {
    "enabled": true,
    "languages": ["en", "de"],
    "primary": "de"
  }
}

workspace​

Unified workspace configuration for single and multi-repository projects. Replaces the deprecated umbrella, multiProject, and projectMappings settings (v3.0+).

PropertyTypeDefaultDescription
namestring(required)Workspace display name
rootRepoobject—Sync targets for the umbrella/root repo itself
rootRepo.github.ownerstring—GitHub org/user for the root repo
rootRepo.github.repostring—GitHub repo name for the root repo
rootRepo.github.directionstring—Sync direction override
rootRepo.jira.projectKeystring—JIRA project key for the root repo
rootRepo.jira.domainstring—JIRA domain override
rootRepo.ado.organizationstring—ADO organization
rootRepo.ado.projectstring—ADO project name
reposarray(required)List of child repositories
repos[].idstring(required)Unique identifier; used as Project value in user stories
repos[].pathstring(required)Relative path to the repo (e.g., repositories/my-org/frontend)
repos[].prefixstring(required)Short prefix for US/AC IDs (e.g., FE, BE)
repos[].namestring—Display name (defaults to id)
repos[].techStackstring[]—Tech keywords for story routing (e.g., ["typescript", "react"])
repos[].rolestring—Repo role: frontend, backend, mobile, infra, shared, other
repos[].syncobject—Per-repo sync targets (same structure as rootRepo)
repos[].sync.githubobject—{ owner, repo, direction? }
repos[].sync.jiraobject—{ projectKey, domain? }
repos[].sync.adoobject—{ organization?, project }

Complete example​

{
  "workspace": {
    "name": "my-platform",
    "rootRepo": {
      "github": { "owner": "my-org", "repo": "platform-umbrella" }
    },
    "repos": [
      {
        "id": "frontend-app",
        "path": "repositories/my-org/frontend-app",
        "prefix": "FE",
        "name": "Frontend Application",
        "techStack": ["typescript", "react", "nextjs"],
        "role": "frontend",
        "sync": {
          "github": { "owner": "my-org", "repo": "frontend-app" },
          "jira": { "projectKey": "FE" }
        }
      },
      {
        "id": "backend-api",
        "path": "repositories/my-org/backend-api",
        "prefix": "BE",
        "name": "Backend API",
        "techStack": ["typescript", "nodejs", "postgresql"],
        "role": "backend",
        "sync": {
          "github": { "owner": "my-org", "repo": "backend-api" },
          "jira": { "projectKey": "BE" }
        }
      }
    ]
  }
}
Single-Project Workspaces

Single-project workspaces have workspace.repos: [] — the workspace.name IS the project. No additional flags are needed. The workspace section activates automatically when present; there is no enabled flag.

ID strategy​

The id field should match the canonical name from your source of truth:

ScenarioID SourceExample
GitHub repoExact repo namesw-qr-menu-fe
JIRA projectProject key (lowercase)WEBAPP → webapp
ADO projectProject name (kebab-case)Frontend Team → frontend-team
ADO area pathLast segment (kebab-case)Product\Web → web
Monorepo packagePackage name@acme/frontend → frontend

IDs should be predictable from the source — no arbitrary abbreviations.

archiving​

Increment archiving and cleanup rules.

PropertyTypeDefaultDescription
keepLastnumber5Keep last N completed increments
autoArchivebooleanfalseAuto-archive when threshold reached
autoArchiveThresholdnumber10Archive when count exceeds this
archiveAfterDaysnumber60Archive after N days of inactivity
preserveActivebooleantrueNever archive active increments
archiveCompletedbooleanfalseArchive completed increments
archivePatternsstring[][]Glob patterns to auto-archive
preserveListstring[][]Increment IDs to never archive
{
  "archiving": {
    "autoArchive": true,
    "archiveAfterDays": 30,
    "keepLast": 10
  }
}

deduplication​

Prevents duplicate command execution within a time window.

PropertyTypeDefaultDescription
enabledbooleantrueEnable command deduplication
windowMsnumber1000Deduplication window (milliseconds)
maxCacheSizenumber1000Max cached command entries
debugbooleanfalseEnable debug logging
cleanupIntervalMsnumber60000Cache cleanup interval (ms)
{
  "deduplication": { "enabled": true, "windowMs": 2000 }
}

statusLine​

Controls the status line displayed in Claude Code.

PropertyTypeDefaultDescription
enabledbooleantrueEnable status line
maxCacheAgenumber30000Max cache age before refresh (ms)
progressBarWidthnumber8Progress bar width (characters)
maxNameLengthnumber30Max increment name display length
{
  "statusLine": { "enabled": false }
}

pluginAutoLoad​

Controls automatic detection and loading of plugins.

PropertyTypeDefaultDescription
enabledbooleantrueEnable plugin auto-loading
suggestOnlybooleantrueOnly suggest plugins, don't auto-install
{
  "pluginAutoLoad": { "enabled": false }
}

lsp​

Language Server Protocol integration for code intelligence.

PropertyTypeDefaultDescription
enabledbooleantrueEnable LSP support
autoInstallPluginsbooleantrueAuto-install LSP plugins
marketplacestring"boostvolt/claude-code-lsps"Plugin marketplace source
{
  "lsp": { "enabled": true, "autoInstallPlugins": true }
}

projectMappings (removed)​

Migration Note

projectMappings was removed in v3.0. Existing configs auto-migrate to the workspace format on first load. Per-project sync targets are now configured via workspace.repos[].sync. See the workspace section above.

multiProject (removed)​

Migration Note

multiProject was removed in v3.0. Existing configs auto-migrate to the workspace format on first load. Define your projects as entries in workspace.repos[] instead. See the workspace section above.

billing​

Optional billing metadata.

PropertyTypeDefaultDescription
planTypestring—Plan type (e.g., subscription, enterprise)
monthlyAmountnumber—Monthly cost

metadata.json Reference​

Each increment has a metadata.json file at .specweave/increments/{id}/metadata.json. Most fields are managed automatically by SpecWeave — you rarely need to edit them directly.

Core Fields​

PropertyTypeDescription
idstringIncrement identifier (e.g., "0042-user-auth")
typestringIncrement type. Values: feature, hotfix, bug, change-request, refactor, experiment
statusstringLifecycle status. Values: planning, active, backlog, paused, ready_for_review, completed, abandoned
prioritystringPriority level (e.g., P0, P1, P2)
createdstringISO 8601 creation timestamp
lastActivitystringISO 8601 last modification timestamp
testModestringPer-increment test mode override. Values: TDD, test-after, manual, none
coverageTargetnumberPer-increment coverage target (0-100)

Lifecycle Fields​

These fields are set automatically as the increment moves through its lifecycle.

PropertyTypeDescription
backlogReasonstringWhy moved to backlog
backlogAtstringISO 8601 when moved to backlog
pausedReasonstringWhy paused
pausedAtstringISO 8601 when paused
abandonedReasonstringWhy abandoned
abandonedAtstringISO 8601 when abandoned
readyForReviewAtstringISO 8601 when all tasks completed
approvedAtstringISO 8601 when approved via sw:done

External Integration Fields​

PropertyTypeDescription
externalLinks.jira.epicKeystringJIRA epic key (e.g., MYAPP-123)
externalLinks.jira.epicUrlstringJIRA epic URL
externalLinks.jira.projectKeystringJIRA project key
externalLinks.jira.domainstringJIRA domain
externalLinks.jira.syncedAtstringLast sync timestamp
externalLinks.ado.featureIdstringADO feature ID
externalLinks.ado.featureUrlstringADO feature URL
externalLinks.ado.organizationstringADO organization
externalLinks.ado.projectstringADO project
externalLinks.ado.syncedAtstringLast sync timestamp
externalRefsobjectPer-user-story external references mapping
syncTargetobjectWhich external tool this increment syncs with
syncTarget.profileIdstringSync profile ID from config.sync.profiles
syncTarget.providerstringProvider: github, jira, ado
syncTarget.derivedFromstringHow target was determined: user-selection, project-mapping, default-profile, auto-detected

Multi-Project and CI/CD Fields​

PropertyTypeDescription
projectIdstringSingle project ID (backward compatible)
multiProject.projectsarrayList of projects this increment spans
multiProject.primaryProjectstringPrimary project for main spec
multiProject.syncStrategystringSync strategy: linked, primary-only, all
epicIdstringEpic this increment belongs to
skipLivingDocsSyncbooleanSkip living docs sync for this increment
prRefsarrayPR references for pr-based push strategy
prRefs[].branchstringBranch name
prRefs[].prNumbernumberPR number
prRefs[].prUrlstringPR URL
prRefs[].statestringPR state: open, merged, closed

Status Transitions​

Not all status transitions are valid. The lifecycle enforces these paths:

warning

active cannot transition directly to completed. An increment must pass through ready_for_review first (triggered by sw:done).

Environment Variables​

Environment variables provide runtime overrides and credential configuration. Set them in your shell profile, .env file, or CI/CD pipeline.

SpecWeave Control Variables​

VariablePurposeExample
SPECWEAVE_DISABLE_HOOKSDisable all SpecWeave hooksSPECWEAVE_DISABLE_HOOKS=1
SPECWEAVE_DEBUGEnable debug logging (issue tracker, sync)SPECWEAVE_DEBUG=1
SPECWEAVE_DEBUG_SKILLSLog skill activation decisionsSPECWEAVE_DEBUG_SKILLS=1
SPECWEAVE_DISABLE_AUTO_LOADDisable automatic plugin loadingSPECWEAVE_DISABLE_AUTO_LOAD=1
SPECWEAVE_AUTO_INSTALLControl auto-install behaviorSPECWEAVE_AUTO_INSTALL=false
SPECWEAVE_SHELLOverride shell detectionSPECWEAVE_SHELL=bash
SPECWEAVE_SKIP_IMAGE_GENSkip image generation in living docsSPECWEAVE_SKIP_IMAGE_GEN=true
SPECWEAVE_UPDATE_NO_SELFSkip self-update in specweave updateSPECWEAVE_UPDATE_NO_SELF=1
SPECWEAVE_DISABLE_GUARDDisable project scope guardSPECWEAVE_DISABLE_GUARD=1
SPECWEAVE_DISABLE_LOCKSDisable lock enforcementSPECWEAVE_DISABLE_LOCKS=1
SPECWEAVE_FORCE_LOCKSForce lock enforcementSPECWEAVE_FORCE_LOCKS=1
SPECWEAVE_NO_INCREMENTSkip increment requirement for current operationSPECWEAVE_NO_INCREMENT=1
SPECWEAVE_BACKGROUND_PROCESSInternal: marks process as background hook(set by SpecWeave)
SPECWEAVE_BACKGROUND_JOBInternal: marks process as background job(set by SpecWeave)

Import Configuration​

VariablePurposeExample
SPECWEAVE_IMPORT_ENABLEDEnable import featureSPECWEAVE_IMPORT_ENABLED=true
SPECWEAVE_IMPORT_TIME_RANGE_MONTHSImport time range in monthsSPECWEAVE_IMPORT_TIME_RANGE_MONTHS=6
SPECWEAVE_IMPORT_PAGE_SIZEPagination size for importsSPECWEAVE_IMPORT_PAGE_SIZE=50

External Tool Credentials​

VariablePurpose
GITHUB_TOKEN or GH_TOKENGitHub API authentication
JIRA_API_TOKENJIRA API token
JIRA_EMAILJIRA user email
JIRA_DOMAINJIRA instance domain
JIRA_PROJECTDefault JIRA project key
JIRA_PROJECTSComma-separated JIRA projects
JIRA_STRATEGYJIRA organization strategy
JIRA_BOARDSComma-separated JIRA boards
AZURE_DEVOPS_PATAzure DevOps personal access token
AZURE_DEVOPS_ORGADO organization
AZURE_DEVOPS_PROJECTADO project
AZURE_DEVOPS_TEAMSComma-separated ADO teams

CI/CD Variables​

VariablePurposeExample
CICD_POLL_INTERVALCI poll interval (ms)CICD_POLL_INTERVAL=30000
CICD_WEBHOOK_URLWebhook for CI notificationsCICD_WEBHOOK_URL=https://...
CICD_AUTO_NOTIFYAuto-notify on workflow completionCICD_AUTO_NOTIFY=true
Credential Management

SpecWeave reads credentials from environment variables. Set them in your .env file or use sw:sync-setup for interactive configuration. Never commit credentials to version control.