Configure Accelerator

You help users manage their Accelerator plugin configuration.

Configuration Files

Accelerator reads configuration from two files in the project's .claude/ directory:

File	Scope	Git	Purpose
.accelerator/config.md	Team-shared	Committed	Shared project context and settings
.accelerator/config.local.md	Personal	Gitignored	Personal overrides and preferences

Both files use YAML frontmatter for structured settings and a markdown body for free-form project context. Local settings override team settings for the same key.

Available Actions

When invoked:

1. Check current configuration state:

• Check if .accelerator/config.md exists
• Check if .accelerator/config.local.md exists
• If either exists, read and display current settings
• If a config file already exists, always show its current contents and ask the user to confirm before overwriting. Never silently replace an existing config file.

2. Based on the argument or user intent:

view (or no argument with existing config)

Display the current configuration:

## Current Accelerator Configuration

### Team Config (.accelerator/config.md)
[Display frontmatter settings as a formatted table]
[Display markdown body if present]

### Personal Config (.accelerator/config.local.md)
[Display frontmatter settings as a formatted table]
[Display markdown body if present]

### Effective Settings
[Show merged settings with source attribution]

### Per-Skill Customisations
[For each directory under .accelerator/skills/ that contains
non-empty context.md or instructions.md, list:]

- `<skill-name>`:
  - context.md: [present / not found]
  - instructions.md: [present / not found]

[If no per-skill customisation directories exist:]

No per-skill customisations found. See `/accelerator:configure help`
for details on per-skill context and instructions.

create (or no argument with no existing config)

Help the user create a configuration file. Focus on gathering project context for the markdown body — this is the highest-value feature.

1. Ask whether they want to create a team config (shared) or personal config (local), or both
2. If creating a personal config, check whether .accelerator/config.local.md is in .gitignore (or .accelerator/.gitignore). If not, offer to add it to the repo root .gitignore.
3. Ask about their project context — frame questions around "What should Accelerator skills know about your project?":

• What tech stack do they use? (languages, frameworks, build system)
• Any specific conventions or standards?
• Any domain-specific context that should inform skills?
• Build and test commands?

4. Optionally ask about agent overrides: "Would you also like to configure custom agent overrides? (This is an advanced feature — most users can skip this.)" If yes, explain the available agents and their roles, then gather override mappings.
5. Mention that additional customisation is available: "You can also customise review behaviour (lens selection, verdict thresholds, inline comment limits), output paths (where skills write documents), document templates (plan, ADR, research, validation formats), and per-skill context and instructions (.accelerator/skills/<skill-name>/). Run /accelerator:configure help for the full key reference."
6. Write the config file with a markdown body containing the gathered context and YAML frontmatter containing any agent overrides (or empty frontmatter if none).

help

Display the configuration reference:

## Accelerator Configuration Reference

### File Format

Both config files use YAML frontmatter with a markdown body:

\```yaml
---
agents:
  reviewer: my-custom-reviewer
---

# Free-form project context (markdown)
Additional context that skills will consider when making decisions.
\```

### agents

Override which agents are used when skills spawn sub-agents. Config keys
use the same hyphenated names as the agents themselves:

Available agents and their roles:

| Config Key                | Default Role                                               |
|---------------------------|------------------------------------------------------------|
| `reviewer`                | Reviews plans, PRs, and work items using configured lenses |
| `browser-analyser`        | Analyses screen state and behaviour in a running web app   |
| `browser-locator`         | Finds routes, screens, and components in a running web app |
| `codebase-locator`        | Finds relevant source files for a given task               |
| `codebase-analyser`       | Analyses implementation details of components              |
| `codebase-pattern-finder` | Finds similar implementations and usage examples           |
| `documents-locator`       | Discovers relevant documents in meta/ directory            |
| `documents-analyser`      | Deep-dives on research topics in documents                 |
| `web-search-researcher`   | Researches topics via web search                           |

\```yaml
---
agents:
  reviewer: my-custom-reviewer
  codebase-locator: my-locator
  codebase-analyser: my-analyser
  codebase-pattern-finder: my-pattern-finder
  documents-locator: my-doc-locator
  documents-analyser: my-doc-analyser
  web-search-researcher: my-web-researcher
---
\```

Only list agents you want to override. Unlisted agents use their defaults.
Unrecognised keys produce a warning to stderr and are ignored. Override
values can be any agent name — the plugin does not validate values since
the override may reference a user-defined agent outside the plugin.

### review

Customise review behaviour for `/accelerator:review-pr`,
`/accelerator:review-plan`, and `/accelerator:review-work-item`. Config keys use
underscores (e.g., `max_inline_comments`). Lens names within array values use
their original hyphenated form (e.g., `code-quality`, `test-coverage`):

Shared settings (apply to `review-pr`, `review-plan`, and `review-work-item`):

| Key               | Default                                                    | Description                   |
|-------------------|------------------------------------------------------------|-------------------------------|
| `min_lenses`      | `4` (3 for work item)                                      | Minimum lenses to run         |
| `max_lenses`      | `8`                                                        | Maximum lenses to run         |
| `core_lenses`     | `[architecture, code-quality, test-coverage, correctness]` | Lenses considered "core four" |
| `disabled_lenses` | `[]`                                                       | Lenses to never use           |

PR review only (`review-pr`):

| Key                           | Default    | Description                                                       |
|-------------------------------|------------|-------------------------------------------------------------------|
| `max_inline_comments`         | `10`       | Max inline comments                                               |
| `dedup_proximity`             | `3`        | Line proximity for merging findings                               |
| `pr_request_changes_severity` | `critical` | Min severity for REQUEST_CHANGES (`critical`, `major`, or `none`) |

Plan review only (`review-plan`):

| Key                       | Default    | Description                                              |
|---------------------------|------------|----------------------------------------------------------|
| `plan_revise_severity`    | `critical` | Min severity for REVISE (`critical`, `major`, or `none`) |
| `plan_revise_major_count` | `3`        | Major findings count to trigger REVISE                   |

Work item review only (`review-work-item`):

| Key                            | Default    | Description                                              |
|--------------------------------|------------|----------------------------------------------------------|
| `work_item_revise_severity`    | `critical` | Min severity for REVISE (`critical`, `major`, or `none`) |
| `work_item_revise_major_count` | `2`        | Major findings count to trigger REVISE                   |

Work items are smaller artifacts than plans, so `work_item_revise_major_count`
defaults to `2` (not `3`): a lower threshold produces equivalent signal density.

Example configuration:

\```yaml
---
review:
  min_lenses: 3
  max_lenses: 10
  core_lenses: [architecture, security, test-coverage, correctness]
  disabled_lenses: [portability, compatibility]
  max_inline_comments: 15
  dedup_proximity: 5
  pr_request_changes_severity: major
  plan_revise_severity: critical
  plan_revise_major_count: 2
  work_item_revise_severity: major
  work_item_revise_major_count: 3
---
\```

Note: YAML comments (`#`) are not supported by the config parser. Do not
add inline comments to config values.

#### Per-Review-Type Lenses

Built-in lenses are partitioned by review type: the 13 code-review lenses
(`architecture`, `code-quality`, etc.) are used by `review-pr` and
`review-plan`; work-item-specific lenses (`completeness`, `testability`,
`clarity`) are used by `review-work-item`. Each command sees only its own lenses
in the Lens Catalogue.

`core_lenses` and `disabled_lenses` entries are cross-mode: they are validated
against the union of all built-in and custom lens names, so naming a PR lens in
`core_lenses` does not produce a warning when running `review-work-item`. Entries
not applicable to the active mode are silently filtered out, with an
informational note in the `## Review Configuration` block so you have an audit
trail. Entries that are not valid in any mode still produce an "unrecognised
lens" warning.

#### Custom Lenses

Create custom review lenses in `.accelerator/lenses/`:

\```
.accelerator/lenses/
  compliance-lens/
    SKILL.md           # Follow the same structure as built-in lenses
  accessibility-lens/
    SKILL.md
\```

Custom lenses are auto-discovered and added to the available lens catalogue.
They must have YAML frontmatter with a `name` field and follow the same
SKILL.md structure as built-in lenses. Custom lenses that provide an
`auto_detect` field participate in auto-detect selection like built-in
lenses. Those without `auto_detect` are always included. Minimal template:

\```markdown
---
name: compliance
description: Evaluates regulatory and policy compliance
auto_detect: Relevant when changes touch regulatory, compliance, or policy-related code
---

# Compliance Lens

## Core Responsibilities
- [What this lens evaluates]

## Key Questions
1. [Questions the reviewer should ask through this lens]

## Boundary
- [What is NOT in scope for this lens]
\```

See any lens in the plugin's `skills/review/lenses/` directory for full
examples of the expected structure.

**Optional fields** — by default a custom lens appears in all review modes
(`pr`, `plan`, and `work-item`). To restrict it to specific modes, add an
`applies_to` field:

\```markdown
---
name: compliance
description: Evaluates regulatory and policy compliance
auto_detect: Relevant when changes touch regulatory, compliance, or policy-related code
# no applies_to — applies to all modes: pr, plan, and work-item
---
\```

\```markdown
---
name: work-item-style
description: Evaluates work-item-specific style conventions
applies_to: [work-item]   # work item reviews only
---
\```

Accepted values: `pr`, `plan`, `work-item`. The field accepts a YAML flow array
(`[pr, plan]`) or a bare scalar (`pr`). Omitting it is equivalent to all modes.
The `applies_to` field is only for custom lenses — built-in lenses are
partitioned via script arrays, not frontmatter.

### Per-Skill Customisation

Provide context or additional instructions for specific skills by placing
files in `.accelerator/skills/<skill-name>/`:

\```
.accelerator/skills/
  create-plan/
    context.md          # Context specific to plan creation
    instructions.md     # Additional instructions for plan creation
  review-pr/
    context.md          # Context specific to PR review
    instructions.md     # Additional instructions for PR review
  review-work-item/
    context.md          # Context specific to work item review
    instructions.md     # Additional instructions for work item review
  commit/
    instructions.md     # Additional instructions for commits
\```

**`context.md`** — Skill-specific context injected after global project
context. Use this for information that is only relevant to a particular
skill. For example, review-pr might need to know about specific review
criteria, while create-plan might need architecture context.

**`instructions.md`** — Additional instructions appended to the skill's
prompt. Use this to customise skill behaviour: add extra steps, enforce
conventions, or modify output format.

Both files are optional. If neither exists for a skill, it behaves as
before. Files are read at skill invocation time. Do not add YAML
frontmatter to these files — their entire content is injected as-is.

**When to use which**: Use **global context** (`.accelerator/config.md`)
for information all skills should know. Use **skill context**
(`context.md`) for information only one skill needs. Use **skill
instructions** (`instructions.md`) to change how a skill behaves — add
steps, enforce formats, or modify output. Per-skill context and
instructions supplement global context (both are visible to the skill);
per-skill instructions appear at the end of the prompt and will typically
take precedence if they conflict with earlier instructions.

**Shared vs personal**: Per-skill files are typically committed to the
repository as team-shared customisations. For personal per-skill
preferences, add the relevant directories to `.gitignore`.

**Troubleshooting**: Directory names must match a known skill name exactly.
The directory name matches the skill name after `/accelerator:` — for
example, `/accelerator:review-pr` uses `review-pr/`,
`/accelerator:create-plan` uses `create-plan/`. Run
`/accelerator:configure view` to see all available skill names and any
active per-skill customisations. The SessionStart hook output also lists
detected per-skill customisations and warns about unrecognised directory
names. To temporarily disable a customisation, rename the file (e.g.,
`context.md.disabled`).

Note: The `configure` skill is not customisable via this mechanism as it
manages configuration itself.

Example `context.md` for review-pr:

\```markdown
## Review Focus Areas

Our team particularly cares about:
- API backward compatibility (we have external consumers)
- Database migration safety (zero-downtime deploys required)
- Test coverage for error paths (we've had incidents from untested error handling)
\```

Example `instructions.md` for create-plan:

\```markdown
- Always include a "Security Considerations" section in plans
- Reference our threat model at docs/security/threat-model.md
- Plans touching the payments service require a rollback strategy
\```

### paths

Override where skills write output documents. Paths are relative to the
project root (absolute paths are also supported):

| Key                           | Default                            | Description                                                                      |
|-------------------------------|------------------------------------|----------------------------------------------------------------------------------|
| `plans`                       | `meta/plans`                       | Implementation plans                                                             |
| `research_codebase`           | `meta/research/codebase`           | Codebase research documents                                                      |
| `research_issues`             | `meta/research/issues`             | Issue / RCA research documents                                                   |
| `research_design_inventories` | `meta/research/design-inventories` | Design-inventory artifacts (one directory per snapshot, with screenshots/)       |
| `research_design_gaps`        | `meta/research/design-gaps`        | Design-gap analysis artifacts                                                    |
| `decisions`                   | `meta/decisions`                   | Architecture decision records                                                    |
| `prs`                         | `meta/prs`                         | PR descriptions                                                                  |
| `validations`                 | `meta/validations`                 | Plan validation reports                                                          |
| `review_plans`                | `meta/reviews/plans`               | Plan review artifacts                                                            |
| `review_prs`                  | `meta/reviews/prs`                 | PR review working directories                                                    |
| `review_work`                 | `meta/reviews/work`                | Work item review artifacts                                                       |
| `templates`                   | `.accelerator/templates`           | User-provided templates (e.g., PR description)                                   |
| `work`                        | `meta/work`                        | Work item files referenced by create-plan                                        |
| `notes`                       | `meta/notes`                       | Notes directory                                                                  |
| `tmp`                         | `.accelerator/tmp`                 | Ephemeral working data (gitignored)                                              |
| `integrations`                | `.accelerator/state/integrations`  | Per-integration cached state (Jira fields/projects, future Linear/Trello caches) |

Example configuration:

\```yaml
---
paths:
  plans: docs/plans
  research_codebase: docs/research/codebase
  research_issues: docs/research/issues
  research_design_inventories: docs/research/design-inventories
  research_design_gaps: docs/research/design-gaps
  decisions: docs/adrs
  prs: docs/prs
  validations: docs/validations
  review_plans: docs/reviews/plans
  review_prs: docs/reviews/prs
  review_work: docs/reviews/work
  templates: docs/templates
  work: docs/work
  notes: docs/notes
  tmp: docs/tmp
  integrations: docs/integrations
---
\```

Note: YAML comments (`#`) are not supported by the config parser. Do not
add inline comments to config values.

### work

Configure work-item identifiers and the active remote tracker. Three keys are recognised:

| Key                          | Default          | Description                                |
|------------------------------|------------------|--------------------------------------------|
| `integration`                | (empty)          | Active remote tracker. Allowed values: `jira`, `linear`, `trello`, `github-issues`. When set, integration skills auto-scope to `default_project_code`. Team→local override precedence applies; use `/accelerator:configure view` to confirm which source is active. |
| `id_pattern`                 | `{number:04d}`   | DSL controlling work-item ID shape         |
| `default_project_code`       | (empty)          | Project code substituted into `{project}`  |

Example configuration for a project tracking issues with project-coded
IDs (matching Jira/Linear conventions):

\```yaml
---
work:
  integration: jira
  id_pattern: "{project}-{number:04d}"
  default_project_code: "PROJ"
---
\```

This produces work-item filenames such as `meta/work/PROJ-0042-add-foo.md`,
H1 headings like `# PROJ-0042: add foo`, and an `id: "PROJ-0042"`
frontmatter field.

#### Local-first storage

Work items are always written to `meta/work/` as local files, regardless
of whether `work.integration` is configured. The remote integration is an
additional layer on top of local storage, not a replacement. A skill that
pushes a work item to a remote tracker must still write the work item
to `meta/work/` first.

This invariant applies to every skill under `skills/work/`
(`create-work-item`, `update-work-item`, `list-work-items`,
`extract-work-items`, `refine-work-item`, `review-work-item`,
`stress-test-work-item`). Integration skills under `skills/integrations/`
add remote behaviour on top — they read from and write to the same
local store. When `work.integration` is unset, every work-management
skill operates purely against `meta/work/` with no external API calls.

#### Pattern DSL Reference

The `id_pattern` value is a small DSL with two tokens:

- `{number[:format]}` — required, exactly one occurrence. The `format`
  is a printf width spec of the form `0Nd` (e.g. `04d`, `05d`). If
  omitted, defaults to `04d`. The width is enforced when generating
  new IDs; scanning is width-agnostic, so legacy 4-digit files remain
  visible after a width change.
- `{project}` — optional, at most one occurrence. Substituted with a
  project value at use time, taken from `--project` flags or
  `default_project_code`.
- `{{` and `}}` — escaped literals for a literal `{` or `}`.

**Validation rules** (enforced when the pattern is consumed):

1. Pattern must contain at least one `{number}` token.
2. No filesystem-hostile chars (`/`, `\`, `:`, `*`, `?`, `<`, `>`,
   `|`, `"`) outside token format specs.
3. Adjacent dynamic tokens must have at least one literal char between
   them (`{project}{number}` is rejected; `{project}-{number}` is
   accepted).
4. The `{number}` format spec must be `0Nd`. Non-padded specs (`%d`)
   are rejected so the overflow guard cap is well-defined.
5. Project values must match `[A-Za-z][A-Za-z0-9]*`. This covers
   Jira/Linear-style alphanumeric project keys (`PROJ`, `ENG`, `ENG2`).
   Project keys with internal hyphens or underscores (`PROJ-FE`,
   `proj_alpha`) are rejected — this is a known limitation of the
   initial scope.

#### `id` and `external_id`: local own-identity vs remote identifier

A work item carries two distinct identity fields:

- **`id`** — the **local own-identity**, allocated locally by
  `accelerator work create` (via `accelerator work next-number`) under
  the configured `id_pattern`. It is **always a quoted YAML string**,
  regardless of the pattern: new work items write `id: "0001"` under
  the default pattern and `id: "PROJ-0001"` under
  `{project}-{number:04d}`. Consumers must treat it as a string; do not
  coerce to integer. (Legacy work items carry the same own-identity
  value under `work_item_id:`; `accelerator work show` bridges the two
  names transparently, so a consumer asking for `id` against a legacy file
  still gets the value.)
- **`external_id`** — the **remote tracker's identifier** (e.g. a Jira or
  Linear key), written when the item is pushed to the configured
  `work.integration`. It is the per-item local→remote mapping, so no
  separate mapping store is needed. Its **presence is the synced signal**:
  an item with a non-empty `external_id` is *synced* (exists remotely), an
  item without one is *unsynced* (never pushed) — see `/list-work-items`.

`id` and `external_id` **may coincide** when the local and remote ID schemes
align (Jira/Linear, under `{project}-{number:04d}`) or be **independent**
when they do not (Trello, whose card IDs are opaque). `external_id` is always
written on a successful push, even when it equals `id`, because presence —
not value — is what marks an item synced.

#### Choosing between default and project-coded patterns

Pick the default `{number:04d}` if your project tracks work items
internally and does not link out to an external tracker. Pick
`{project}-{number:04d}` when: