Configure

Configure Accelerator

You help users manage their Accelerator plugin configuration.

Configuration Files

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

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:

- You mirror tickets from Jira, Linear, or another external tracker
  and want filenames to align with the tracker's IDs.
- Multiple projects share one repo and you want a clear visual
  separation between project workstreams.

#### Width changes vs structural changes

Changing the width spec (`{number:04d}` → `{number:05d}`) is
**absorbed transparently**: legacy files remain visible because the
scan regex is width-agnostic. New files are generated at the new
width.

Changing the structural shape (default → `{project}-{number:04d}`,
or vice versa) leaves legacy files coexisting with their original IDs.
Use `/accelerator:migrate` to apply migration `0002-rename-work-items-with-project-prefix`,
which renames legacy `NNNN-*.md` files to the configured pattern with
your `default_project_code`. The migration stays pending until both
the pattern includes `{project}` and `default_project_code` is set; if
neither applies, you can opt out via `accelerator migrate --skip
0002-rename-work-items-with-project-prefix`.

#### Recognised keys

Only `work.integration`, `work.id_pattern`, and
`work.default_project_code` are recognised. Other `work.*` keys are not
consumed by any plugin script.

### visualiser

Configure the visualiser plugin.

| Key               | Default                                                         | Description                                                                  |
|-------------------|-----------------------------------------------------------------|------------------------------------------------------------------------------|
| `kanban_columns`  | `[draft, ready, in-progress, review, done, blocked, abandoned]` | Ordered list of kanban column keys                                           |
| `idle_timeout`    | `8h`                                                            | Idle auto-shutdown window (humantime duration; `never`/`0` to disable)       |
| `editor`          | (empty)                                                         | Editor deep-link command; absent disables the "open in editor" button        |
| `editor_project`  | (empty)                                                         | Companion project argument passed alongside `editor`                         |
| `binary`          | (bundled)                                                       | Override visualiser binary path (absolute or project-relative; must be executable) |

Example configuration for a project using a reduced column set:

\```yaml
---
visualiser:
  kanban_columns: [ready, in-progress, review, done]
---
\```

Each key becomes a kanban column; the display label is the key
title-cased with hyphens replaced by spaces (`in-progress` → `In progress`).

#### Boot-time validation

| Condition                         | Behaviour                              |
|-----------------------------------|----------------------------------------|
| Key absent                        | Falls back to the seven defaults above |
| Key present, non-empty list       | Accepted; each entry becomes a column  |
| Key present, empty list (`[]`)    | Rejected at boot with a clear error    |
| Malformed inline-array syntax     | Rejected at boot                       |

The column set is read once at boot. Changing `visualiser.kanban_columns`
requires a server restart; the browser will pick up the new columns on the
next page-load (TanStack Query re-fetches `/api/kanban/config` each time).

#### Idle auto-shutdown

The visualiser server auto-exits after a period with no incoming HTTP
requests. `visualiser.idle_timeout` sets that window as a humantime
duration string (`"8h"`, `"30m"`, `"1h30m"`); it defaults to `8h` when
absent.

Setting it to `never` (case-insensitive), `0`, or any zero-length
duration (`0s`, `0ms`) **disables** idle auto-shutdown — the idle timer
never fires, which is **not** the same as "shut down immediately". The
server still terminates when the process that launched it exits and on
`/accelerator:visualise stop`.

An unparseable value (e.g. `soon`) is rejected at launch with a clear
error naming the bad value, rather than silently defaulting.

The `ACCELERATOR_VISUALISER_IDLE_TIMEOUT` environment variable overrides
the config key for one-shot, shell-scoped use. Precedence is
**env var > `visualiser.idle_timeout` > 8h default**.

The window is read once at boot and honoured to within one ~60s polling
tick — shutdown lands on the next tick after the window elapses, so
sub-minute values are effectively rounded up to the next tick. Changing it
requires a server restart.

#### Kanban write-back contract

`PATCH /api/docs/{path}/frontmatter` validates the incoming `status` value
against the configured column keys. A value outside the configured set —
including values currently in the "Other" swimlane — is rejected with
`400 unknown_kanban_status`. Recovery from an accidental drag is a direct
file edit followed by VCS revert.

See ADR-0024 for full rationale.

#### Editor deep-link and binary override

`visualiser.editor` and `visualiser.editor_project` are free-form passthrough
strings that drive the doc "open in editor" deep-link; when both are absent the
button is disabled. Precedence is **env var
(`ACCELERATOR_VISUALISER_EDITOR` / `_EDITOR_PROJECT`) > config key > omitted**;
a whitespace-only value collapses to absent.

`visualiser.binary` points the launcher at an alternative server binary instead
of the bundled/downloaded one — useful for local development. The path may be
absolute or project-relative and **must be executable** (a non-executable path
fails the launch loudly). Precedence is **`ACCELERATOR_VISUALISER_BIN` env var >
`visualiser.binary` > bundled binary**.

#### Recognised keys

Only `visualiser.kanban_columns`, `visualiser.idle_timeout`,
`visualiser.editor`, `visualiser.editor_project`, and `visualiser.binary` are
recognised. Other `visualiser.*` keys are not consumed by any plugin script.

### jira

Configure access to a Jira Cloud tenant. One key belongs in team-shared
`config.md`:

| Key              | Default | Description                                            |
|------------------|---------|--------------------------------------------------------|
| `site`           | (empty) | Cloud subdomain (e.g. `atomic-innovation`)             |
| `allowed_sites`  | (empty) | Extra exact hostnames the Rust client may send the token to, beyond `*.atlassian.net` |

`allowed_sites` exists for self-hosted and non-`atlassian.net` tenants. The
Rust client refuses to send credentials to any host outside `*.atlassian.net`
unless it is listed here as an exact hostname — no wildcard expansion, matched
at a label boundary, so neither `atlassian.net.example.com` nor
`evil-atlassian.net` is admitted. Like `token_cmd`, it is refused when the file
it came from is tracked by version control: a committed allowlist is a
credential-destination decision a clone would inherit.

Example shared configuration in `config.md`:

\```yaml
---
jira:
  site: atomic-innovation
---
\```

#### Personal settings (do not commit)

Three keys are personal and **must live exclusively in
`config.local.md`**, which is gitignored:

| Key         | Default | Description                                            |
|-------------|---------|--------------------------------------------------------|
| `email`     | (empty) | Your Atlassian account email                           |
| `token`     | (empty) | Plaintext API token (discouraged — prefer `token_cmd`) |
| `token_cmd` | (empty) | Shell command whose stdout is the token                |

`token_cmd` from the team-shared `config.md` is **never** honoured: a
committed `token_cmd` is a supply-chain command-injection sink (a single PR
could land arbitrary shell that runs on every contributor's machine). When
detected, the resolver emits `E_TOKEN_CMD_FROM_SHARED_CONFIG: jira.token_cmd
in config.md ignored — move to config.local.md` to stderr.

`token` plaintext is supported but discouraged — prefer `token_cmd` with a
password manager. The resolver refuses to read credentials from a
`config.local.md` looser than `0600` (override with
`ACCELERATOR_ALLOW_INSECURE_LOCAL=1` plus a committed
`.accelerator/allow-insecure-local` marker).

Example `config.local.md` (preferred form, using a password manager):

\```yaml
---
jira:
  email: toby@go-atomic.io
  token_cmd: "op read op://Work/Atlassian/credential"
---
\```

Authentication resolves through this chain (first non-empty wins):

1. `ACCELERATOR_JIRA_TOKEN` env var.
2. `ACCELERATOR_JIRA_TOKEN_CMD` env var (run via `bash -c`, stdout trimmed).
3. `config.local.md` `jira.token`.
4. `config.local.md` `jira.token_cmd`.
5. `config.md` `jira.token` *(only when `config.local.md` does not
   exist; emits a runtime warning)*.

`jira.token_cmd` is **never** consumed from the team-shared `config.md`
file. Only the four sources above (env vars and `config.local.md`) are
honoured. A `jira.token_cmd` value found in `config.md` is ignored; a
runtime warning prints `E_TOKEN_CMD_FROM_SHARED_CONFIG: jira.token_cmd in
config.md ignored — move to config.local.md` to stderr. Rationale:
a committed `token_cmd` is a supply-chain command-injection sink — a single PR
could land `jira.token_cmd: "<arbitrary shell>"` and that command would execute
on every contributor's machine the next time any Jira helper or `/init-jira`
ran. Restricting the executable indirection to local-only files keeps the blast
radius bounded to the user's own machine.

`token_cmd` is the supported integration point for password managers and
keychains: 1Password CLI (`op read ...`), `pass`, macOS Keychain (`security
find-generic-password ...`), Freedesktop Secret Service (`secret-tool ...`),
and AWS Secrets Manager all work without plugin-side knowledge.

The default Jira project key is **`work.default_project_code`** — the same key
used by the work-item ID pattern. No separate `jira.default_project_key`
exists.

#### Skill registration order

The `skills` array in `.claude-plugin/plugin.json` is **workflow-ordered**, not
alphabetical. Its sequence groups categories by lifecycle:

vcs → external trackers (github, integrations/jira) → planning → execution (work) → review → meta (config)

Future integrations (Linear, Trello) land in the `integrations/` group,
immediately after `./skills/integrations/jira/`. Do not sort the array
alphabetically.

#### Recognised keys

Only `jira.site`, `jira.allowed_sites`, `jira.email`, `jira.token`, and
`jira.token_cmd` are recognised. Other `jira.*` keys are not consumed by any
plugin script. `jira.allowed_sites` has no bash consumer — it is read by the
Rust client only.

### linear

Configure access to Linear. Linear is single-tenant SaaS, so there is no
site/subdomain key — authentication is a personal API token only.

One key belongs in team-shared `config.md`:

| Key       | Default | Description                                              |
|-----------|---------|----------------------------------------------------------|
| `team_id` | (empty) | The Linear team the client creates and searches issues in |

`team_id` has no bash consumer: the shell path reads `.team.id` from the
`catalogue.json` that `/init-linear` writes, and the Rust client falls back to
that same file when the key is unset, so an already-onboarded repository needs
no new configuration.

#### Personal settings (do not commit)

Both token keys are personal and **must live exclusively in
`config.local.md`**, which is gitignored:

| Key         | Default | Description                                            |
|-------------|---------|--------------------------------------------------------|
| `token`     | (empty) | Plaintext API token (discouraged — prefer `token_cmd`) |
| `token_cmd` | (empty) | Shell command whose stdout is the token                |

Authentication resolves through this chain (first non-empty wins):

1. `ACCELERATOR_LINEAR_TOKEN` env var.
2. `ACCELERATOR_LINEAR_TOKEN_CMD` env var (run via `bash -c`, stdout trimmed).
3. `config.local.md` `linear.token`.
4. `config.local.md` `linear.token_cmd`.
5. `config.md` `linear.token` *(only when `config.local.md` does not exist)*.

`linear.token_cmd` is **never** consumed from the team-shared `config.md` file:
a committed `token_cmd` is a supply-chain command-injection sink. A
`linear.token_cmd` found in `config.md` is ignored, emitting
`E_TOKEN_CMD_FROM_SHARED_CONFIG: linear.token_cmd in config.md ignored — move to
config.local.md` to stderr. The resolver also refuses to read credentials from a
`config.local.md` looser than `0600` (override with
`ACCELERATOR_ALLOW_INSECURE_LOCAL=1` plus a committed
`.accelerator/allow-insecure-local` marker), mirroring the Jira integration.

Example `config.local.md` (preferred form, using a password manager):

\```yaml
---
linear:
  token_cmd: "op read op://Work/Linear/token"
---
\```

`token_cmd` is the supported integration point for password managers and
keychains (1Password CLI, `pass`, macOS Keychain, Secret Service), exactly as
for Jira.

#### Recognised keys

Only `linear.team_id`, `linear.token` and `linear.token_cmd` are recognised.
Other `linear.*` keys are not consumed by any plugin script.

### templates

Override document templates by placing custom template files in the
templates directory (`paths.templates`, defaults to `.accelerator/templates/`):

\```
.accelerator/templates/
  plan.md            # Custom plan template
  research.md        # Custom research template
  adr.md             # Custom ADR template
  validation.md      # Custom validation template
  pr-description.md  # PR description template (used by describe-pr)
  work-item.md       # Custom work-item template
\```

All templates — both skill structure templates (plan, ADR, research,
validation) and user content templates (PR description) — live in the same
directory. Override `paths.templates` to move them all:

\```yaml
---
paths:
  templates: docs/templates
---
\```

For advanced use cases, you can also point individual templates to specific
file paths using the `templates` config section:

\```yaml
---
templates:
  plan: docs/templates/our-plan-format.md
  adr: docs/templates/our-adr-format.md
  pr-description: docs/templates/our-pr-template.md
---
\```

Resolution order: `templates.<name>` config path (if set) → templates
directory (`paths.templates`) → plugin default. Use the plugin's
`templates/` directory as a starting point for customisation.

**Note on cross-references**: Default templates contain hardcoded references
to other skills' output paths (e.g., the plan template references
`meta/research/codebase/` in its References section). If you override output paths
(e.g., `paths.research_codebase: docs/research/codebase`), you should also provide custom
templates with updated cross-references.

#### Template Management Commands

Use `/accelerator:configure templates <action>` to manage templates:

| Command                 | Description |
|-------------------------|--------------------------------------------------------|
| `templates list`        | List all templates with resolution source and path     |
| `templates show <key>`  | Display the effective template content                 |
| `templates eject <key>` | Copy plugin default to your templates directory        |
| `templates eject --all` | Eject all templates at once                            |
| `templates diff <key>`  | Show differences between your template and the default |
| `templates reset <key>` | Remove your customisation, revert to plugin default    |

Available template keys: `plan`, `research`, `adr`, `validation`, `pr-description`, `work-item`.

### Project Context

The markdown body is injected into skills as project-specific guidance:

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

# Project Context

## Tech Stack
- Language: TypeScript with strict mode
- Framework: Next.js 14 with App Router
- Database: PostgreSQL via Prisma ORM
- Testing: Vitest for unit tests, Playwright for E2E

## Convention

…(truncated)