Shortcut Assistant Chrome Extension Development

This skill guides development of the Shortcut Assistant Chrome extension, which enhances the Shortcut project management platform with keyboard shortcuts, AI-powered story analysis, cycle time tracking, and external integrations.

Project Architecture

Dual Codebase Structure

The project maintains two distinct codebases:

1. **Legacy Vanilla JS/TS** (`src/js/`): Original extension functionality

- Keyboard shortcuts, notes, Todoist integration

- Content scripts for DOM manipulation

- Service worker for background tasks

- Analytics and OAuth handlers

2. **Modern React** (`src/react/`): New UI components and features

- AI-powered story analysis with streaming

- Settings drawer with authentication

- FAB (Floating Action Button) UI

- Component-based architecture

Communication Bridge

The systems communicate via `src/react/content-bridge.ts`:

Import Path Conventions

Development Workflow

Setup

1. Install dependencies:

```bash

npm install

```

2. Set up Doppler for secrets management:

```bash

brew install doppler/tap/doppler-cli

doppler login

doppler setup --project shortcut-assistant --config dev

```

Development Commands

**Build and develop:**

```bash

npm run dev # Watch mode for development

npm run build # Production bundle + manifest update

npm run dist # Production build + dist.zip

```

**Testing:**

```bash

npm test # Run all tests

npm test -- path/to/test.test.tsx # Single test file

npm run test-coverage # Coverage report

```

**Code quality:**

```bash

npm run lint # Lint code

npm run lint-fix # Auto-fix issues

```

**Versioning (use yarn):**

```bash

yarn version --patch # 1.0.0 -> 1.0.1 (bug fixes)

yarn version --minor # 1.0.0 -> 1.1.0 (new features)

yarn version --major # 1.0.0 -> 2.0.0 (breaking changes)

```

Local Testing

1. Build extension: `npm run dev`

2. Navigate to `chrome://extensions/`

3. Enable "Developer mode"

4. Click "Load unpacked" and select `build/` folder

5. After service worker or manifest changes, click "Reload"

Code Style Requirements

General TypeScript

Import Ordering

ESLint enforces this order:

1. Built-in Node modules

2. External dependencies

3. Internal modules (including `@sx/` paths)

4. Parent imports

5. Sibling imports

6. Index imports

Two blank lines after import block.

Testing Conventions

**Current tests:** Located in `tests/` directory mirroring `src/`

**Future convention:** Co-locate tests in `__tests__/` directories

**Test patterns:**

Key Architecture Patterns

Content Script Activation

Content scripts activate when:

1. User navigates to Shortcut story page

2. URL contains Shortcut host + "story"

3. Service worker sends "update" message

The content script then:

React-Service Worker Communication

Message flow:

1. React posts to window: `window.postMessage({ type: 'FROM_PAGE', message: {...} })`

2. Content bridge receives and validates

3. Forwards to service worker: `chrome.runtime.sendMessage({ action: '...' })`

4. Service worker processes and responds

5. Response flows back through bridge to React

AI Streaming System

React AI features use isolated streaming:

Webpack Entry Points

Build Process

1. `yarn build` runs `src/build-manifest.ts` → generates manifest.json

2. Webpack bundles all entry points → `build/` directory

3. `npm run dist` → production build + `dist/dist.zip`

4. Manifest version syncs with package.json via version scripts

Jest Configuration

Implementation Checklist

When working on this extension: