https://github.com/atomicinnovation/accelerator
Development acceleration toolkit with multi-lens code review, implementation planning, codebase research, and git workflow automation.
https://github.com/atomicinnovation/accelerator
ai-assisted-development ai-coding ai-workflow claude claude-code rpi skills
Last synced: 7 days ago
JSON representation
Development acceleration toolkit with multi-lens code review, implementation planning, codebase research, and git workflow automation.
- Host: GitHub
- URL: https://github.com/atomicinnovation/accelerator
- Owner: atomicinnovation
- License: mit
- Created: 2026-03-15T00:07:31.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-02T11:41:16.000Z (19 days ago)
- Last Synced: 2026-06-02T13:26:01.060Z (19 days ago)
- Topics: ai-assisted-development, ai-coding, ai-workflow, claude, claude-code, rpi, skills
- Language: HTML
- Homepage: https://go-atomic.io
- Size: 29.9 MB
- Stars: 19
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
A Claude Code plugin for structured, context-efficient software development.
[Jump to installation](#installation) if you're ready to get started.
## Philosophy
Accelerator structures development into discrete phases — research, plan,
implement — where each phase runs with minimal context and communicates with
the next through the filesystem. This design is intentional: by writing
research findings, plans, and other artifacts to disk rather than holding them
in the conversation, each step stays focused and avoids the quality degradation
that comes with large, cluttered context windows.
The result is a development workflow where:
- Each phase has a clear purpose and bounded scope
- The filesystem (specifically the `meta/` directory) serves as persistent
shared memory between phases and sessions
- Subagents handle exploratory work in isolation, returning only summaries to
the main context
- Human review happens at the highest-leverage points (research quality and
plan quality) before implementation begins
For example, a research phase might read 50 files across a codebase, but only
a structured summary is written to disk and passed to the planning phase —
keeping the planner focused and accurate.
## The Development Loop
The primary workflow is a three-phase loop:
```
research-codebase → create-plan → implement-plan
↓ ↓ ↓
meta/research/codebase/ meta/plans/ checked-off plan
```
1. **Research** (`/accelerator:research-codebase "how does auth work?"`):
Investigate the codebase using parallel subagents. Produces a structured
research document in `meta/research/codebase/` with findings, file
references, and architectural context.
2. **Plan** (`/accelerator:create-plan ENG-1234`): Build a phased
implementation plan informed by research. Produces a plan document in
`meta/plans/` with specific file changes, success criteria, and testing
strategy. The plan is reviewed by the developer before proceeding.
3. **Implement** (`/accelerator:implement-plan @meta/plans/plan.md`): Execute
the plan phase by phase, checking off success criteria as each phase
completes. The plan file serves as both instructions and progress tracker.
A companion skill handles issue investigation:
- `/accelerator:research-issue "auth timeout on token refresh"` — Investigate
production issues through hypothesis-driven debugging. Accepts stacktraces,
logs, or behavioral descriptions and produces an RCA document in
`meta/research/issues/`.
Three complementary skills support this loop:
- `/accelerator:review-plan @meta/plans/plan.md` — Review a plan through
multiple quality lenses before implementation
- `/accelerator:stress-test-plan @meta/plans/plan.md` — Interactively
stress-test a plan through adversarial questioning to find issues,
inconsistencies, and gaps
- `/accelerator:validate-plan @meta/plans/plan.md` — Verify after
implementation that the code matches the plan
## The `meta/` Directory
Every project using Accelerator gets a `meta/` directory (by default) that
serves as persistent state for the development workflow. Each skill reads from
and writes to predictable paths within it. Run `/accelerator:init` to
create all directories up front, or let skills create them on first use.
These paths can be overridden via the `paths` configuration section:
`research/` is itself subdivided into four subcategories — codebase
research, issue/RCA research, design inventories, and design gaps:
| Directory | Purpose | Written by |
|---------------------------------|----------------------------------------------------------------|--------------------------------------------------------------|
| `research/` | (parent — see subcategories below) | — |
| ` ├─ codebase/` | Codebase research findings with YAML frontmatter | `research-codebase` |
| ` ├─ issues/` | Issue / RCA research findings | `research-issue` |
| ` ├─ design-inventories/` | Per-source design inventory snapshots (markdown + screenshots) | `inventory-design` |
| ` └─ design-gaps/` | Design-gap analysis artifacts | `analyse-design-gaps` |
| `plans/` | Implementation plans with phased changes | `create-plan` |
| `decisions/` | Architecture decision records (ADRs) | `create-adr`, `extract-adrs`, `review-adr` |
| `reviews/` | Review summaries and per-lens results | `review-pr`, `review-plan` |
| `validations/` | Plan validation reports | `validate-plan` |
| `prs/` | PR descriptions | `describe-pr` |
| `work/` | Work item files referenced by planning | `create-work-item`, `extract-work-items`, `update-work-item` |
| `notes/` | Notes and working documents | manual |
This approach means:
- No skill assumes access to another skill's conversation history
- Work survives session boundaries and context compaction
- Plans can be resumed after interruption (implement-plan picks up from the
first unchecked item)
- Artifacts are structured and machine-parseable (YAML frontmatter, JSON
schemas)
## Migrations
When a new plugin version renames directories, config keys, or file formats, a
migration script handles the upgrade. Run `/accelerator:migrate` after updating
the plugin to apply any pending migrations.
```
/accelerator:migrate
```
Safety guards: the skill refuses to run on a dirty working tree, prints a
pre-run banner listing each pending migration, and previews each one before
applying. All mutations are tracked in `.accelerator/state/migrations-applied`.
Recovery is via VCS revert. Set `ACCELERATOR_MIGRATE_FORCE=1` to bypass the
clean-tree check if needed.
To opt out of an individual migration, run
`bash skills/config/migrate/scripts/run-migrations.sh --skip ` (and
`--unskip ` to re-enable it). Skipped IDs are tracked in
`.accelerator/state/migrations-skipped` and surfaced by name in the runner's
summary line so a permanent skip is never invisible. A migration can also
self-defer by emitting `MIGRATION_RESULT: no_op_pending` on stdout — useful
for migrations whose preconditions (e.g. a `{project}` pattern in
`work.id_pattern`) aren't yet configured.
A `SessionStart` hook fires automatically when the bundled migrations have not
all been applied, reminding you to run `/accelerator:migrate`. (On repos that
haven't run migration `0003` yet, the hook reads the legacy
`meta/.migrations-applied` file as a fallback.)
## VCS Detection
Accelerator automatically detects whether a repository uses git or
[jujutsu (jj)](https://github.com/jj-vcs/jj) and adapts its behaviour
accordingly. A `SessionStart` hook inspects the working directory for `.jj/` and
`.git/` directories, injecting VCS-specific context (command references and
conventions) into the session. A complementary `PreToolUse` guard warns when raw
git commands are used in a jujutsu repository.
This means all VCS-aware skills — `commit`, `respond-to-pr`, and ad-hoc
interactions — use the correct CLI commands without manual configuration. The
detection covers three modes:
| Mode | Detected when | VCS commands used |
|--------------------|--------------------|-------------------|
| **git** | `.git/` only | `git` |
| **jj (colocated)** | `.jj/` and `.git/` | `jj` |
| **jj (pure)** | `.jj/` only | `jj` |
## Configuration
Accelerator supports project-specific configuration through markdown files with
YAML frontmatter. Configuration allows you to provide project context, customise
agent behaviour, and tune review settings.
### Config Files
| File | Scope | Purpose |
|-----------------------------------|-------------------------|-------------------------------------|
| `.accelerator/config.md` | Team-shared (committed) | Shared project context and settings |
| `.accelerator/config.local.md` | Personal (gitignored) | Personal overrides and preferences |
Local settings override team settings for the same key. Markdown bodies from
both files are concatenated (team context first, then personal).
### File Format
Both files use YAML frontmatter for structured settings and a markdown body for
free-form project context:
```yaml
---
agents:
reviewer: my-custom-reviewer
review:
disabled_lenses: [ portability, compatibility ]
max_inline_comments: 15
pr_request_changes_severity: major
---
## Project Context
This is a Ruby on Rails application using PostgreSQL and Redis.
### Conventions
- Follow StandardRB for code style
- Use service objects for business logic
- All API endpoints require authentication
### Build & Test
- `bundle exec rspec` to run tests
- `bin/dev` to start the development server
```
The YAML frontmatter supports `agents` (override which agents skills spawn),
`review` (customise review behaviour), `paths` (override where skills write
output documents), `templates` (point to custom document templates), and
`work` (customise work-item ID filename pattern and default project code).
See `/accelerator:configure help` for the full key reference.
### Template Management
Templates control the structure of documents produced by skills (plans, ADRs,
research, validation reports, PR descriptions). The configure skill provides
subcommands for managing templates without manually locating plugin internals:
| Command | Description |
|------------------------------------------------|--------------------------------------------------------|
| `/accelerator:configure templates list` | List all templates with resolution source and path |
| `/accelerator:configure templates show ` | Display the effective template content |
| `/accelerator:configure templates eject ` | Copy plugin default to your templates directory |
| `/accelerator:configure templates eject --all` | Eject all templates at once |
| `/accelerator:configure templates diff ` | Show differences between your template and the default |
| `/accelerator:configure templates reset ` | Remove your customisation, revert to plugin default |
Available template keys: `plan`, `research`, `adr`, `validation`,
`pr-description`, `work-item`, `design-inventory`, `design-gap`.
A typical customisation workflow:
1. `templates list` to see what's available and where each resolves from
2. `templates eject plan` to copy the plugin default to your templates directory
3. Edit the ejected file to match your project's conventions
4. `templates diff plan` to review your changes against the default
5. `templates reset plan` if you want to revert to the plugin default
Templates are resolved in order: config path (`templates.`) → templates
directory (`paths.templates`, default `.accelerator/templates/`) → plugin default.
### Getting Started
Run `/accelerator:configure` to create or view your configuration. The skill
walks you through gathering project context and writes the config file for you.
### How It Works
- A `SessionStart` hook detects config files and injects a summary into the
session context
- Skills read project context at invocation time via the `!` preprocessor
- Config changes take effect on the next skill invocation (no session restart
needed for skills); the SessionStart summary updates on session restart
### Custom Review Lenses
You can add custom review lenses alongside the 13 built-in ones. Place them in
`.accelerator/lenses/` following the `[name]-lens/SKILL.md` convention.
Custom lenses are auto-discovered and included in the lens catalogue. See
`/accelerator:configure help` for details and a minimal template.
### Per-Skill Customisation
Beyond global context, you can provide context or instructions targeted at
individual skills by placing files in
`.accelerator/skills//`:
```
.accelerator/skills/
review-pr/
context.md # Context specific to PR review
instructions.md # Additional instructions for PR review
create-plan/
instructions.md # Additional instructions for plan creation
```
- **`context.md`** — Injected after global project context. Use for information
only one skill needs (e.g., review criteria for `review-pr`, architecture
context for `create-plan`).
- **`instructions.md`** — Appended to the end of the skill's prompt. Use to add
steps, enforce conventions, or modify output format. Instructions at the end
of the prompt typically take precedence when they conflict with earlier
instructions.
Both files are optional. Directory names must match the skill name exactly (the
part after `/accelerator:`). The SessionStart hook warns about unrecognised
directory names. See `/accelerator:configure help` for the full reference.
## Work Item Management
Work item skills capture work items — features, bugs, tasks, spikes, and epics —
as structured documents that feed into planning. The filename prefix
defaults to a 4-digit number (`meta/work/0042-add-search.md`) but is
configurable via `work.id_pattern` and `work.default_project_code` —
e.g. `{project}-{number:04d}` with `default_project_code: PROJ` produces
`meta/work/PROJ-0042-add-search.md`. The `work.integration` key (allowed
values `jira`, `linear`, `trello`, `github-issues`; empty by default)
selects the active remote tracker. When unset, all work-management skills
operate purely against `meta/work/` with no external API calls. See
[`skills/config/configure/SKILL.md`](skills/config/configure/SKILL.md#work)
for the full reference.
```
existing docs (specs, PRDs, notes)
│
├── extract-work-items ──┐
│ ↓
create-work-item ──→ meta/work/ ←── update-work-item
│
list-work-items ──┬──→ review-work-item → meta/reviews/work/
└──→ create-plan → implement-plan
```
| Skill | Usage | Description |
|------------------------|------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| **create-work-item** | `/accelerator:create-work-item [topic-or-ref]` | Interactively create a work item from a topic, or enrich an existing one by path or number |
| **extract-work-items** | `/accelerator:extract-work-items [doc paths...]` | Batch-extract work items from existing specs, PRDs, research, plans, or notes |
| **list-work-items** | `/accelerator:list-work-items [filter]` | List and filter work items by status, type, priority, tag, parent, or title |
| **update-work-item** | `/accelerator:update-work-item [work-item-ref] [field-op]` | Update work item fields with diff preview and confirmation |
| **review-work-item** | `/accelerator:review-work-item [work-item-ref]` | Review a work item through completeness, testability, and clarity lenses |
Work items use a shared template with YAML frontmatter (`work_item_id`, `title`,
`type`, `status`, `priority`, `parent`, `tags`) and structured body sections
(Summary, Context, Requirements, Acceptance Criteria, Open Questions,
Dependencies, Assumptions, Technical Notes, Drafting Notes, References).
The template is customisable via
`/accelerator:configure templates eject work-item`.
## Jira Integration
Accelerator includes a full set of skills for interacting with a Jira Cloud
tenant — searching for and reading issues, creating and updating them,
commenting, transitioning through workflows, and uploading attachments. Run
`/accelerator:init-jira` once to verify credentials and persist the
team-shared field and project catalogue before using the other skills.
### Configuration
Add the shared site setting to `.accelerator/config.md` and personal
credentials to `.accelerator/config.local.md` (gitignored):
```yaml
# .accelerator/config.md — commit this
---
jira:
site: your-subdomain # e.g. "atomic-innovation" for atomic-innovation.atlassian.net
---
```
```yaml
# .accelerator/config.local.md — do not commit
---
jira:
email: you@example.com
token_cmd: "op read op://Work/Atlassian/credential" # any password-manager command
---
```
The default project key reuses `work.default_project_code`; set
`work.integration: jira` to enable auto-scoping. See
`/accelerator:configure help` for the full credential resolution chain and
`token_cmd` examples (1Password, `pass`, macOS Keychain, AWS Secrets Manager).
### Skills
| Skill | Usage | Description |
|---------------------------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| **init-jira** | `/accelerator:init-jira` | Verify credentials, discover projects and custom fields, persist the team-shared catalogue to `.accelerator/state/integrations/jira/` |
| **search-jira-issues** | `/accelerator:search-jira-issues [flags]` | Search via structured flags (assignee, status, label, type, component, reporter, parent, watching); composes safe JQL with a `--jql` escape hatch |
| **show-jira-issue** | `/accelerator:show-jira-issue ` | Fetch a single issue with optional comment slice and Markdown rendering of ADF descriptions |
| **create-jira-issue** | `/accelerator:create-jira-issue [flags]` | Create a new issue; body accepted inline, from a file, from stdin, or via `$EDITOR` |
| **update-jira-issue** | `/accelerator:update-jira-issue [flags]` | Edit summary, description, assignee, priority, labels, components, parent, and custom fields |
| **comment-jira-issue** | `/accelerator:comment-jira-issue ` | Add, list, edit, or delete comments (`add`, `list`, `edit`, `delete` sub-actions) |
| **transition-jira-issue** | `/accelerator:transition-jira-issue ` | Move an issue through its workflow by state name (case-insensitive lookup), with optional resolution and comment |
| **attach-jira-issue** | `/accelerator:attach-jira-issue ` | Upload one or more files as issue attachments |
Read skills (`search-jira-issues`, `show-jira-issue`) trigger automatically on
natural-language phrasing. Write skills are slash-only — they display a
payload preview and require explicit confirmation before making any change to
the tenant.
### ADF / Markdown
Jira Cloud v3 stores rich-text fields in Atlassian Document Format (ADF).
Accelerator converts bidirectionally using pure bash + awk + jq with no
additional dependencies:
- **Reading** — ADF is rendered to Markdown by default on `show-jira-issue`
(pass `--no-render-adf` for raw JSON) and on `comment-jira-issue list`.
`search-jira-issues` defaults render-off; pass `--render-adf` for bulk
results with description text.
- **Writing** — `create-jira-issue`, `update-jira-issue`, and
`comment-jira-issue add`/`edit` convert Markdown input to ADF before
sending.
Supported Markdown: paragraphs, headings (`#`–`######`), fenced code blocks
with language, single-level bullet/ordered lists, GitHub-style checklists
(`- [ ]` / `- [x]`), inline bold/italic/code/links, and hard breaks.
### State cache
`/init-jira` persists the field catalogue, project list, and site metadata to
`.accelerator/state/integrations/jira/`. This directory is version-controlled
and team-shared — instance-specific custom field IDs are not secrets and are
worth committing so teammates don't need to re-run init. Per-developer
credentials live in `.accelerator/config.local.md` and env vars only.
## Architecture Decision Records
ADR skills capture architectural decisions that emerge from research and
planning:
```
research-codebase → create-plan → implement-plan
↓ ↓
meta/research/codebase/ meta/plans/
↓ ↓
extract-adrs ←──────────┘
↓
meta/decisions/
↓
review-adr → accepted ADRs inform future research & planning
```
| Skill | Usage | Description |
|------------------|--------------------------------------------|------------------------------------------------------------|
| **create-adr** | `/accelerator:create-adr [topic]` | Interactively create an ADR with context gathering |
| **extract-adrs** | `/accelerator:extract-adrs [doc paths...]` | Extract decisions from existing meta documents into ADRs |
| **review-adr** | `/accelerator:review-adr [path to ADR]` | Review proposed ADRs; accept, reject, or suggest revisions |
ADRs follow an append-only lifecycle: once accepted, an ADR's content becomes
immutable. To revise a decision, create a new ADR that supersedes the original.
## VCS and PR Workflow Skills
Alongside the development loop, Accelerator provides skills for version control
and team workflows around pull requests:
| Skill | Usage | Description |
|-------------------|----------------------------------|--------------------------------------------------------------------------|
| **commit** | `/accelerator:commit` | Create well-structured, atomic commits (works with both git and jujutsu) |
| **describe-pr** | `/accelerator:describe-pr 123` | Generate comprehensive PR descriptions from a configurable template |
| **review-pr** | `/accelerator:review-pr 123` | Review a PR through multiple quality lenses with inline comments |
| **respond-to-pr** | `/accelerator:respond-to-pr 123` | Address PR review feedback interactively with code changes |
## Visualiser
`/accelerator:visualise` opens a browser-based companion view of your project's
`meta/` directory. Three views cover the breadth of the directory:
| View | What it shows |
|---------------|-----------------------------------------------------------------------|
| **Library** | Markdown reader for every doc type (plans, research, ADRs, tickets …) |
| **Lifecycle** | Slug-clustered timelines grouping related documents across phases |
| **Kanban** | Ticket board driven by `status:` frontmatter; drag-and-drop to update |
### Launching
```bash
/accelerator:visualise # from inside a Claude Code session
accelerator-visualiser # CLI wrapper — optionally symlink onto $PATH
```
The server binds to `localhost` on a dynamic port. It has no authentication
and emits no telemetry. Re-running the command while the server is alive
returns the same URL.
### Lifecycle
```bash
/accelerator:visualise status # JSON: running | stale | not_running
/accelerator:visualise stop # SIGTERM, escalating to SIGKILL after 2s
```
Both subcommands also work via the `accelerator-visualiser` CLI wrapper.
The server auto-exits after 8 hours idle or when the process that
launched it exits, so explicit `stop` is rarely necessary.
### First-run binary download
The server is distributed as a pre-compiled native binary (~8 MB). On first
run the launcher:
1. Reads `bin/checksums.json` (committed in the plugin) to find the SHA-256
for your platform and the current plugin version.
2. Downloads the matching binary from the plugin's GitHub Releases over HTTPS.
3. Verifies the download against the manifest and caches it under the plugin
root. Subsequent launches skip the download.
Every plugin version — pre-release (`X.Y.Z-pre.N`) and stable (`X.Y.Z`) —
ships four-platform binaries. There is no need to build locally to use a
pre-release version.
### Customisation
| Mechanism | Purpose |
|--------------------------------------------|--------------------------------------------------------------------|
| `ACCELERATOR_VISUALISER_BIN` | One-shot override pointing at a locally-built binary |
| `visualiser.binary` config key | Persistent binary override in `.accelerator/config.local.md` |
| `ACCELERATOR_VISUALISER_IDLE_TIMEOUT` | One-shot override of the idle auto-shutdown window (duration string, or `never`/`0` to disable) |
| `visualiser.idle_timeout` config key | Persistent idle auto-shutdown window (humantime duration; default `8h`; `never`/`0` to disable) |
| `ACCELERATOR_VISUALISER_RELEASES_URL` | Alternative HTTPS mirror for air-gapped or self-hosted installs |
| `ACCELERATOR_VISUALISER_VERIFY_PROVENANCE` | Set to `1` to verify SLSA build-provenance after the SHA-256 check |
The `ACCELERATOR_VISUALISER_RELEASES_URL` mirror must be HTTPS. A localhost
exemption (`127.0.0.1`, `::1`, `localhost`) accepts HTTP for integration
testing; any other plaintext URL is rejected by the launcher.
### Provenance verification
Every released binary carries a SLSA build-provenance attestation
(sigstore-keyless, GitHub Actions OIDC, transparency-log-backed). The default
SHA-256 check proves the cached binary matches what the build runner produced.
Setting `ACCELERATOR_VISUALISER_VERIFY_PROVENANCE=1` adds a second layer: the
launcher calls `gh attestation verify --repo atomicinnovation/accelerator`
and refuses to start if the attestation is missing or invalid. Requires
`gh >= 2.49.0` and network reachability to `api.github.com`.
## Review System
The `review-pr`, `review-plan`, and `review-work-item` skills use a multi-lens
review system. Each lens is a specialised subagent that evaluates the artefact
through a specific quality perspective.
**Code review lenses** (used by `review-pr` and `review-plan`):
| Lens | Focus |
|-------------------|----------------------------------------------------------------------|
| **Architecture** | Modularity, coupling, dependency direction, structural drift |
| **Code Quality** | Complexity, design principles, error handling, code smells |
| **Compatibility** | API contracts, cross-platform, protocol compliance, deps |
| **Correctness** | Logical validity, boundary conditions, state management, concurrency |
| **Database** | Migration safety, schema design, query correctness, integrity |
| **Documentation** | Documentation completeness, accuracy, audience fit |
| **Performance** | Algorithmic efficiency, resource usage, concurrency, caching |
| **Portability** | Environment independence, deployment flexibility, vendor lock |
| **Safety** | Data loss prevention, operational safety, protective mechanisms |
| **Security** | OWASP Top 10, input validation, auth/authz, secrets, data flows |
| **Standards** | Project conventions, API standards, naming, accessibility |
| **Test Coverage** | Coverage adequacy, assertion quality, test pyramid, anti-patterns |
| **Usability** | Developer experience, API ergonomics, configuration, migration paths |
**Work item review lenses** (used by `review-work-item`):
| Lens | Focus |
|------------------|----------------------------------------------------------------|
| **Completeness** | Section presence, content density, type-appropriate content |
| **Testability** | Measurable criteria, verifiable outcomes, verification framing |
| **Clarity** | Unambiguous referents, internal consistency, jargon handling |
Lenses are automatically selected based on scope, or you can specify focus
areas:
```
/accelerator:review-pr 123 focus on security and architecture
/accelerator:review-work-item 0042 focus on testability
```
## Design Convergence
Design convergence skills capture two design surfaces — a current frontend and a
target prototype — as structured inventory artifacts, then compute a structured
gap between them. The gap artifact's prose paragraphs satisfy the cue-phrase
contract that `extract-work-items` consumes, so the workflow plugs straight into
the existing work-item lifecycle. Each inventory snapshot is self-contained
(markdown plus screenshots in a dated directory); re-running for the same source
supersedes the prior snapshot without losing it.
```
inventory-design (current) ─┐
├─▶ analyse-design-gaps ─▶ extract-work-items ─▶ meta/work/*
inventory-design (target) ─┘
```
| Skill | Usage | Description |
|-------------------------|---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| **inventory-design** | `/accelerator:inventory-design [source-id] [location] [--crawler MODE]` | Generate a design inventory (tokens, components, screens, features) for a frontend source |
| **analyse-design-gaps** | `/accelerator:analyse-design-gaps [current-source-id] [target-source-id]` | Compute a structured gap between two inventories as actionable prose |
Three-step example:
```
/accelerator:inventory-design current ./apps/webapp
/accelerator:inventory-design prototype https://prototype.example.com
/accelerator:analyse-design-gaps current prototype
```
The resulting gap artifact under `meta/research/design-gaps/` feeds straight into
`/accelerator:extract-work-items `.
`inventory-design` supports three crawler modes: `code` (static analysis only,
no Playwright needed), `runtime` (Playwright executor only), and `hybrid`
(both, default for code-repo sources).
New flags: `--allow-internal` (permit RFC1918 / loopback-variant hosts) and
`--allow-insecure-scheme` (permit plain `http://` to non-localhost public
hosts). `http://localhost` and `http://127.0.0.1` are accepted without any
flag.
### Requirements
For `--crawler runtime` or `--crawler hybrid`:
- **Node ≥ 20** — executor bootstrap and daemon require Node.js 20 or later
- **macOS or Linux** — Windows is not supported
- **~500 MB free disk** — first-run Chromium install writes to the cache
Run `ensure-playwright.sh` to bootstrap the executor manually; the skill runs
it automatically on first use.
### Runtime browser dependency
The executor (`run.sh`) wraps a Node.js daemon that drives Playwright's
Chromium. On first use with `--crawler runtime|hybrid`, the skill runs
`ensure-playwright.sh` to install Playwright and Chromium into a per-machine
cache. Subsequent runs reuse the cache without a network round-trip.
Cache root: `~/.cache/accelerator/playwright//` (namespace keyed on the
skill-shipped `package-lock.json` hash).
For the executor wire protocol see
[`skills/design/inventory-design/PROTOCOL.md`](skills/design/inventory-design/PROTOCOL.md).
### Cache & cleanup
| Path | Purpose |
|------|---------|
| `~/.cache/accelerator/playwright/` | Per-machine Playwright + Chromium cache |
| `/.accelerator/tmp/inventory-design-playwright/` | Per-project daemon state (port file, PID) |
To reset both:
```bash
run.sh daemon-stop
rm -rf ~/.cache/accelerator/playwright .accelerator/tmp/inventory-design-playwright
```
### Troubleshooting
- **Hung daemon**: run `run.sh daemon-stop` to shut it down cleanly.
- **Bootstrap failure**: run `ensure-playwright.sh` directly to see the full
error output. Check `NPM_CONFIG_REGISTRY`, `NODE_EXTRA_CA_CERTS`,
`HTTPS_PROXY`, and `PLAYWRIGHT_DOWNLOAD_HOST`.
- **Downgrade to code**: if bootstrap fails in `hybrid` mode the skill
automatically falls back to `code`-only crawl with a printed notice.
### Authenticated browser crawls
`/accelerator:inventory-design` reads the following environment variables when
the location is a hosted prototype or running app and authentication is
required. They are also read by any future skill that uses the `browser-*`
agents.
| Variable | Purpose |
|-----------------------------------|------------------------------------------------------------------|
| `ACCELERATOR_BROWSER_AUTH_HEADER` | Header injected on navigations to the resolved location's origin |
| `ACCELERATOR_BROWSER_USERNAME` | Form-login username (used with `_PASSWORD` and `_LOGIN_URL`) |
| `ACCELERATOR_BROWSER_PASSWORD` | Form-login password |
| `ACCELERATOR_BROWSER_LOGIN_URL` | Login form URL |
Precedence: if `AUTH_HEADER` is set it takes precedence and the form-login
vars are ignored (with a warning). If `AUTH_HEADER` is unset, all three of
`USERNAME`, `PASSWORD`, and `LOGIN_URL` must be set together — partial sets
cause the skill to fail with a clear error. With none set, auth-walled routes
are skipped and noted in the inventory's Crawl Notes.
Security: `AUTH_HEADER` is sent **only** on navigations whose origin matches
the resolved location (or the login URL); cross-origin navigations strip it.
Screenshots mask password and token fields. The skill refuses to write an
inventory if any env-var literal appears in the generated body.
### Security considerations
- **Env vars**: store `ACCELERATOR_BROWSER_*` values in your shell profile or
a local `.env` file (gitignored), not in committed config.
- **Screenshots**: each inventory directory contains screenshots committed to
the repo. Avoid pointing `inventory-design` at screens that display
sensitive personal data, PII, or credentials.
- **Side-effecting forms**: the `browser-analyser` agent uses `browser_click`
and `browser_type` for state-transition testing. Do not point
`inventory-design` at production systems with forms that have real-world
side effects (payments, email sends, account mutations).
- **Executor isolation**: the Playwright executor runs as a local TCP daemon on
`127.0.0.1` only. It never binds to an external interface. Screenshots mask
`[type=password]`, `[autocomplete*=token]`, and `[data-secret]` fields
automatically.
## Agents
Accelerator uses specialised subagents to keep the main context lean. Each
agent runs in its own context window with restricted tools, returning only a
focused summary to the parent:
| Agent | Role | Tools |
|-----------------------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **codebase-locator** | Finds files and components by description | Grep, Glob, LS |
| **codebase-analyser** | Analyses implementation details of specific components | Read, Grep, Glob, LS |
| **codebase-pattern-finder** | Finds similar implementations and usage examples | Read, Grep, Glob, LS |
| **documents-locator** | Discovers relevant documents in configured directories | Grep, Glob, LS |
| **documents-analyser** | Extracts insights from meta documents | Read, Grep, Glob, LS |
| **reviewer** | Evaluates code/plans through a specific quality lens | Read, Grep, Glob, LS |
| **web-search-researcher** | Researches external documentation and resources | WebSearch, WebFetch, Read, Grep, Glob, LS |
| **browser-locator** | Locates routes/screens/components in a running app via Playwright | `Bash(run.sh navigate)`, `Bash(run.sh snapshot)` |
| **browser-analyser** | Analyses screens, captures state and screenshots via Playwright | `Bash(run.sh navigate\|snapshot\|screenshot\|evaluate\|click\|type\|wait_for)` |
The separation between locators (find, no Read) and analysers (understand, with
Read) is deliberate: it prevents any single agent from needing to both search
broadly and read deeply, keeping each agent's context bounded.
`browser-*` agents drive Playwright through the skill-shipped executor
(`run.sh`), a Bash wrapper around a Node.js TCP daemon that runs Chromium.
No MCP server is required. See `skills/design/inventory-design/PROTOCOL.md`
for the executor wire protocol.
## Installation
Add the marketplace and install the plugin:
```bash
/plugin marketplace add atomicinnovation/accelerator
/plugin install accelerator@atomic-innovation
```
### Prerelease Versions
Prerelease versions (`X.Y.Z-pre.N`) are published to GitHub Releases on every
push to `main`. A separate marketplace file always points to the latest
prerelease. Add it once:
```bash
/plugin marketplace add https://raw.githubusercontent.com/atomicinnovation/accelerator/main/.claude-plugin/marketplace-prerelease.json
/plugin install accelerator@atomic-innovation-prerelease
```
Re-run `/plugin install accelerator@atomic-innovation-prerelease` to pick up a
newer prerelease as they are published.
To return to the stable channel, uninstall the prerelease plugin and remove its
marketplace:
```bash
/plugin uninstall accelerator@atomic-innovation-prerelease
/plugin marketplace remove atomic-innovation-prerelease
/plugin marketplace add atomicinnovation/accelerator
/plugin install accelerator@atomic-innovation
```
### Development
To load from a local checkout:
```bash
claude --plugin-dir /path/to/accelerator
```
### Claude Code compatibility
This plugin relies on Claude Code's subagent `skills:` preload mechanism
to inject configuration context into agents (e.g. `accelerator:paths`
into the `documents-*` agents, `accelerator:browser-executor` into the
`browser-*` agents). **Minimum supported Claude Code: v2.1.144.**
Earlier releases may not support the mechanism; later releases that
change subagent skill-preloading semantics will surface the failure via
the agents' Preload guards.
## License
MIT — see [LICENSE](LICENSE).