### Install and Run Todo App

Source: https://github.com/alfredoperez/speckit-companion/blob/main/examples/todo-claude/README.md

Commands to install dependencies, start the development server, and build the project for production.

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build
```

--------------------------------

### Parallel Task Execution Example (Bash)

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/007-spec-viewer-webview/tasks.md

Demonstrates how to launch multiple parallel tasks in the Setup phase using bash commands.

```bash
# Launch all parallel tasks in Setup together:
Task: "Create type definitions in src/features/spec-viewer/types.ts"
Task: "Create webview-side type definitions in webview/src/spec-viewer/types.ts"
```

--------------------------------

### Speckit Companion Development Setup

Source: https://github.com/alfredoperez/speckit-companion/blob/main/README.md

Commands to clone the repository, install dependencies, and compile the project for development. Ensure you are in the project directory after cloning.

```bash
git clone https://github.com/alfredoperez/speckit-companion.git
cd speckit-companion
npm install
npm run compile
```

--------------------------------

### Start Development Server with npm

Source: https://github.com/alfredoperez/speckit-companion/blob/main/examples/todo-claude/CLAUDE.md

Run this command to start the Vite development server for local development.

```bash
npm run dev
```

--------------------------------

### Compile and Setup Tasks

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/005-speckit-views-enhancement/tasks.md

Commands to verify TypeScript compilation and initiate setup tasks for Speckit.

```bash
# Launch both setup tasks together:
Task: "Verify TypeScript compilation with npm run compile"
Task: "Add SpecKit file type interfaces to src/features/steering/types.ts"
```

--------------------------------

### Example SpecKit Companion Settings with Qwen

Source: https://github.com/alfredoperez/speckit-companion/blob/main/docs/providers/qwen-setup.md

An example of a complete settings.json configuration for SpecKit Companion, specifying Qwen as the AI provider and its associated paths and modes.

```json
{
  "speckit.aiProvider": "qwen",
  "speckit.qwenPath": "qwen",
  "speckit.qwenYoloMode": false
}
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/alfredoperez/speckit-companion/blob/main/CONTRIBUTING.md

Run this command in the project root to install all necessary npm packages.

```bash
npm install
```

--------------------------------

### Build and Package Extension

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/082-always-show-icon/quickstart.md

Commands to build and package the extension for installation. Ensure you have Node.js and npm installed.

```bash
npm install && npm run compile && npm run package
```

--------------------------------

### Start Extension Development Host

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/006-plan-step-highlight/quickstart.md

Compile the extension and launch the Extension Development Host from the repository root.

```bash
# From the repo root
npm run compile
# Then press F5 in VS Code to launch Extension Development Host
```

--------------------------------

### Verify Qwen Code CLI Installation

Source: https://github.com/alfredoperez/speckit-companion/blob/main/docs/providers/qwen-setup.md

Checks if the Qwen Code CLI has been installed correctly by displaying its version. This command should be run after installation.

```bash
qwen --version
```

--------------------------------

### Install Qwen Code CLI with npm

Source: https://github.com/alfredoperez/speckit-companion/blob/main/docs/providers/qwen-setup.md

Installs the latest version of the Qwen Code CLI globally using npm. Ensure Node.js 18+ is installed.

```bash
npm install -g @qwen-code/qwen-code@latest
```

--------------------------------

### Install Testing Dependencies

Source: https://github.com/alfredoperez/speckit-companion/blob/main/examples/todo-claude/specs/001-due-dates/quickstart.md

Install necessary testing frameworks and libraries for Test-Driven Development (TDD).

```bash
npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom
```

--------------------------------

### Install and Compile Project

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/069-reveal-spec-folder/quickstart.md

These commands are used for setting up the project and compiling the code. They are essential for running the automated tests and ensuring the build is successful.

```bash
npm install
```

```bash
npm run compile
```

```bash
npm test -- specCommands
```

--------------------------------

### Example Plan Step Configuration

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/049-fix-plan-indent/data-model.md

Illustrates a typical configuration for a 'plan' step in a workflow, specifying its file, sub-files, and directory.

```json
{
    name: 'plan',
    label: 'Plan',
    file: 'plan.md',
    subFiles: ['research.md', 'data-model.md', 'quickstart.md'],
    subDir: 'contracts',
    includeRelatedDocs: true
}
```

--------------------------------

### Example .spec-context.json Structure

Source: https://github.com/alfredoperez/speckit-companion/blob/main/docs/spec-context-schema.md

This example demonstrates the typical structure and fields found in a .spec-context.json file, including core, step tracking, metadata, and SDD-enriched data.

```json
{
  "workflow": "sdd",
  "selectedAt": "2026-04-05T22:00:00.000Z",
  "currentStep": "implement",
  "progress": "phase1",
  "currentTask": "T003",
  "status": "active",
  "specName": "My Feature",
  "branch": "feat/my-feature",
  "stepHistory": {
    "specify": { "startedAt": "...", "completedAt": "..." },
    "plan": { "startedAt": "...", "completedAt": "..." },
    "tasks": { "startedAt": "...", "completedAt": "..." },
    "implement": { "startedAt": "...", "completedAt": null }
  },
  "approach": "Add migration layer and fix race condition",
  "currentTask": "T003",
  "task_summaries": {
    "T001": { "status": "DONE", "did": "...", "files": [...], "concerns": [] }
  }
}
```

--------------------------------

### Parallel Setup Tasks for Codex Provider

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/012-codex-cli-provider/tasks.md

These tasks can be launched in parallel as they are in different files and relate to the initial setup of the Codex provider.

```bash
# Launch all Setup tasks together (different files):
Task: "Add 'codex' to AIProviderType union in src/ai-providers/aiProvider.ts"
Task: "Add codex entry to PROVIDER_PATHS record in src/ai-providers/aiProvider.ts"
Task: "Add 'codex' enum value and description to package.json aiProvider configuration"
```

--------------------------------

### SpecKit CLI Initialization Command

Source: https://github.com/alfredoperez/speckit-companion/blob/main/docs/architecture.md

Example of initializing a workspace using the SpecKit CLI. This command is used to set up the necessary configuration and files for a new project.

```bash
specify init
```

--------------------------------

### Project Structure: Documentation

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/005-speckit-views-enhancement/plan.md

Illustrates the directory structure for the documentation of this feature, including plan, research, data-model, quickstart, contracts, and tasks files.

```text
specs/005-speckit-views-enhancement/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

```

--------------------------------

### Start Step Lifecycle

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/061-extension-lifecycle-writes/plan.md

Initiates a step's lifecycle, returning the spawned terminal for tracking. Errors are logged and ignored.

```typescript
stepLifecycle.startStep(specDir, step, 'extension')
      .then(terminal => {
        if (terminal) {
          terminalStepTracker.track(terminal, specDir, step);
        }
      });
```

--------------------------------

### Parallel User Story Execution Example (Bash)

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/007-spec-viewer-webview/tasks.md

Illustrates how User Stories 3 and 4 can proceed in parallel after User Story 2 is completed, as indicated by bash commands.

```bash
# US3 and US4 can proceed in parallel:
Developer A: User Story 3 (Markdown rendering)
Developer B: User Story 4 (Edit functionality)
```

--------------------------------

### Project Structure Documentation

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/054-archive-button-left/plan.md

Lists the documentation files for this feature, including the plan, research, data model, quickstart, and tasks.

```text
specs/054-archive-button-left/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
└── tasks.md             # Phase 2 output (created by /speckit.tasks)
```

--------------------------------

### Example Slash Command Dispatch

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/059-hide-launch-prompt/plan.md

Illustrates how a slash command with a prompt will be dispatched. The prompt content is read from a temporary file using `$(cat ...)`.

```bash
claude "/sdd:specify $(cat "/tmp/speckit-prompt-a3f2.md")"
```

--------------------------------

### Create a New AI Provider Class

Source: https://github.com/alfredoperez/speckit-companion/blob/main/docs/how-it-works.md

Example TypeScript class structure for adding a new AI provider, implementing the `IAIProvider` interface with methods for installation check, terminal execution, headless execution, and slash command handling.

```typescript
// src/ai-providers/myNewProvider.ts
export class MyNewProvider implements IAIProvider {
    readonly name = 'My New Provider';

    async isInstalled(): Promise<boolean> { ... }
    async executeInTerminal(prompt: string, title?: string): Promise<vscode.Terminal> { ... }
    async executeHeadless(prompt: string): Promise<AIExecutionResult> { ... }
    async executeSlashCommand(command: string, title?: string): Promise<vscode.Terminal> { ... }
}
```

--------------------------------

### Conditional Welcome Buttons in package.json

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/1-setup-welcome-buttons/tasks.md

Replace the existing `speckit.views.explorer` entry with three conditional entries in the `viewsWelcome` array of `package.json`. These entries control which welcome message and buttons are displayed based on the SpecKit CLI's installation and constitution setup status.

```json
"when": "speckit.cliInstalled && !speckit.detected"
```

```json
"contents": "SpecKit CLI detected. Initialize this workspace to start building with specs.\n\n[$(gear) Initialize Workspace](command:speckit.initWorkspace)"
```

```json
"when": "speckit.detected && speckit.constitutionNeedsSetup"
```

```json
"contents": "Configure your project principles to guide AI-assisted development.\n\n[$(book) Configure Constitution](command:speckit.constitution)\n\n[$(plus) Create New Spec](command:speckit.create)"
```

```json
"when": "speckit.detected && !speckit.constitutionNeedsSetup"
```

```json
"contents": "Build features with specs\n\n[$(plus) Create New Spec](command:speckit.create)"
```

--------------------------------

### Parallel Execution of User Stories

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/045-update-docs/tasks.md

Demonstrates how multiple user stories can be initiated simultaneously after the setup phase is complete. This highlights the parallel opportunities within the project's development workflow.

```bash
# All three user stories can start simultaneously:
Task: US1 - Rewrite docs/architecture.md (T005-T009)
Task: US2 - Update docs/how-it-works.md (T010-T017)
Task: US3 - Verify CLAUDE.md (T018)
```

--------------------------------

### Extension Activation and Command Registration

Source: https://context7.com/alfredoperez/speckit-companion/llms.txt

This is the entry point for the SpecKit Companion extension. Activation occurs on `onStartupFinished`. All SpecKit commands follow the `speckit.<feature>.<action>` pattern. Ensure `vscode` and other necessary modules are imported.

```typescript
import * as vscode from 'vscode';
import { AIProviderFactory } from './ai-providers/aiProviderFactory';
import { SpecExplorerProvider } from './features/specs';
import { SteeringManager } from './features/steering';

export async function activate(context: vscode.ExtensionContext) {
  const outputChannel = vscode.window.createOutputChannel('SpecKit Companion');

  // 1. Detect CLI and workspace state
  const detector = new SpecKitDetector();
  await detector.detect(context, outputChannel);

  // 2. Select AI provider (prompts if not yet configured)
  const provider = await AIProviderFactory.getProvider(context, outputChannel);

  // 3. Initialize feature managers
  const steeringManager = new SteeringManager(outputChannel, provider);
  const workflowManager = ...;

  // 4. Register tree views
  const specExplorer = new SpecExplorerProvider(context, outputChannel, provider);
  vscode.window.registerTreeDataProvider('speckit.views.explorer', specExplorer);

  // 5. Register commands
  context.subscriptions.push(
    vscode.commands.registerCommand('speckit.create', async () => {
      // Opens spec editor dialog, then dispatches /speckit.specify
      await specEditorCommands.createSpec(provider, specExplorer);
    }),
    vscode.commands.registerCommand('speckit.plan', async (specItem) => {
      // Dispatches /speckit.plan (or provider-formatted equivalent)
      await specCommands.runStep(specItem, 'plan', provider);
    }),
    // ... speckit.specify, speckit.tasks, speckit.implement, speckit.clarify,
    //     speckit.analyze, speckit.checklist, speckit.archive, etc.
  );

  // 6. Set up file watchers (1 s debounce on specs/ and .claude/)
  setupFileWatchers(context, specExplorer, steeringExplorer, outputChannel);
}
```

--------------------------------

### Example Qwen CLI Command Execution in SpecKit

Source: https://github.com/alfredoperez/speckit-companion/blob/main/docs/providers/qwen-setup.md

Illustrates the command executed by SpecKit Companion to invoke the Qwen CLI with a prompt from a file. This is typically seen in the integrated terminal during SpecKit operations.

```bash
qwen -p "$(cat /path/to/prompt.md)"
```

--------------------------------

### Check Codex CLI Installation

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/012-codex-cli-provider/research.md

Verify the Codex CLI installation by running the `codex --version` command. This follows standard CLI patterns for checking if a tool is available.

```bash
codex --version
```

--------------------------------

### Preview Production Build with npm

Source: https://github.com/alfredoperez/speckit-companion/blob/main/examples/todo-claude/CLAUDE.md

Use this command to preview the production build locally before deployment.

```bash
npm run preview
```

--------------------------------

### Configure Vitest for React and JSDOM

Source: https://github.com/alfredoperez/speckit-companion/blob/main/examples/todo-claude/specs/001-due-dates/research.md

Sets up Vitest configuration in `vitest.config.ts` to use the JSDOM environment for testing React components. Includes global setup and a specific setup file.

```typescript
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: './src/test/setup.ts',
  },
})
```

--------------------------------

### Example TempFileManifest JSON

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/004-spec-editor-webview/data-model.md

An example JSON object representing a TempFileManifest. This shows the structure for tracking temporary files, their associated session IDs, file paths, creation and expiration timestamps, and status.

```json
{
    "version": "1.0",
    "files": {
        "temp-abc123": {
            "id": "temp-abc123",
            "sessionId": "session-xyz789",
            "markdownFilePath": "/path/to/spec.md",
            "imageFilePaths": {
                "img-001": "/path/to/images/img-001.png"
            },
            "createdAt": 1704218400000,
            "expiresAt": 1704218700000,
            "status": "completed"
        }
    },
    "lastCleanup": 1704218400000
}
```

--------------------------------

### Watch for TypeScript Changes

Source: https://github.com/alfredoperez/speckit-companion/blob/main/CONTRIBUTING.md

Starts a watcher process that recompiles TypeScript files on change.

```bash
npm run watch
```

--------------------------------

### StepHistoryEntry Structure

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/060-spec-context-tracking/data-model.md

Represents the history of a single step within a specification, including start and completion times.

```json
{
  "startedAt": ISO 8601,
  "completedAt": ISO 8601 | null,
  "substeps": SubstepEntry[]
}
```

--------------------------------

### SubstepEntry Structure

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/060-spec-context-tracking/data-model.md

Defines the structure for individual substeps within a larger step, including their start and completion times.

```json
{
  "name": string,
  "startedAt": ISO 8601,
  "completedAt": ISO 8601 | null
}
```

--------------------------------

### VS Code Extension API Usage

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/008-spec-viewer-ux/plan.md

Example of how to manage a WebviewPanel lifecycle within a VS Code extension.

```typescript
src/features/spec-viewer/specViewerProvider.ts - Main provider managing WebviewPanel lifecycle
```

--------------------------------

### Compile and Test Project

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/055-fix-bullet-rendering/quickstart.md

Run this command to compile the project and execute the test suite. Ensure all tests pass after applying the renderer fix.

```bash
npm run compile && npm test
```

--------------------------------

### OpenCode Provider Implementation Sketch

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/064-provider-registry/plan.md

Conceptual outline for implementing the `IAIProvider` for OpenCode, including installation check and execution method.

```typescript
// `IAIProvider` impl modeled on `qwenCliProvider.ts`; `isInstalled()` shells `opencode --version` and returns false on ENOENT; uses `dispatchSlashCommandViaTempFile` for execution.
```

--------------------------------

### Build and Package Commands

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/002-edit-input-sizing/quickstart.md

Standard npm commands for compiling the extension once or packaging it for distribution.

```bash
# Compile once
npm run compile

# Package extension
npm run package
```

--------------------------------

### Project Structure Overview

Source: https://github.com/alfredoperez/speckit-companion/blob/main/examples/todo-claude/README.md

Illustrates the directory and file structure of the todo-test-app project.

```tree
todo-test-app/
├── src/
│   ├── components/
│   │   ├── AddTodo.tsx
│   │   ├── TodoItem.tsx
│   │   └── TodoList.tsx
│   ├── App.tsx
│   ├── main.tsx
│   └── types.ts
├── .specify/
│   └── specs/
│       ├── due-dates/
│       │   └── requirements.md
│       ├── categories/
│       │   └── requirements.md
│       └── priority-levels/
│           └── requirements.md
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
```

--------------------------------

### Webview Entry Point (TypeScript)

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/007-spec-viewer-webview/quickstart.md

Sets up the webview's message listeners, tab navigation, and edit button functionality. It acquires the VS Code API and posts a 'ready' message.

```typescript
declare const acquireVsCodeApi: () => {
    postMessage: (message: unknown) => void;
    getState: () => unknown;
    setState: (state: unknown) => void;
};

const vscode = acquireVsCodeApi();

function init(): void {
    setupTabNavigation();
    setupEditButton();
    setupMessageListener();
    vscode.postMessage({ type: 'ready' });
}

function setupTabNavigation(): void {
    document.querySelectorAll('.tab-button').forEach(btn => {
        btn.addEventListener('click', () => {
            const docType = (btn as HTMLElement).dataset.doc;
            if (docType) {
                vscode.postMessage({ type: 'switchDocument', documentType: docType });
            }
        });
    });
}

function setupEditButton(): void {
    const editBtn = document.getElementById('edit-button');
    editBtn?.addEventListener('click', () => {
        vscode.postMessage({ type: 'editDocument' });
    });
}

function setupMessageListener(): void {
    window.addEventListener('message', (event) => {
        const message = event.data;
        if (message.type === 'contentUpdated') {
            updateContent(message.content);
        }
    });
}

function updateContent(markdown: string): void {
    const contentEl = document.getElementById('content');
    if (contentEl) {
        contentEl.innerHTML = renderMarkdown(markdown);
        // Apply syntax highlighting
        (window as any).hljs?.highlightAll?.();
    }
}

document.addEventListener('DOMContentLoaded', init);
```

--------------------------------

### ElapsedTimer Preact Component

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/074-elapsed-timer-notification/tasks.md

A Preact component that displays the elapsed time since a given start time. It updates every second.

```typescript
import { h } from 'preact';
import { useState, useEffect } from 'preact/hooks';
import { formatElapsed } from './elapsedFormat';

export function ElapsedTimer({ startedAt }: { startedAt: string | null | undefined }) {
  const [now, setNow] = useState<number>(Date.now());

  useEffect(() => {
    if (!startedAt) {
      return;
    }

    const intervalId = setInterval(() => setNow(Date.now()), 1000);

    return () => clearInterval(intervalId);
  }, [startedAt]);

  if (!startedAt) {
    return null;
  }

  const elapsedMs = Date.now() - Date.parse(startedAt);
  return <span class="step-tab__elapsed">{formatElapsed(elapsedMs)}</span>;
}
```

--------------------------------

### Create Feature Module Structure

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/004-spec-editor-webview/quickstart.md

Sets up the necessary directories and files for the spec editor feature module.

```bash
mkdir -p src/features/spec-editor
mkdir -p webview/src/spec-editor
```

```text
src/features/spec-editor/
├── index.ts              # Module exports
├── types.ts              # TypeScript interfaces
├── specEditorProvider.ts # WebviewPanel provider
├── specEditorCommands.ts # Command registration
├── specDraftManager.ts   # Draft persistence
└── tempFileManager.ts    # Temp file management

webview/src/spec-editor/
├── index.ts              # Entry point
├── editor.ts             # Text editor component
├── imageAttachment.ts    # Image handling
└── preview.ts            # Preview rendering

webview/styles/
└── spec-editor.css       # Styles
```

--------------------------------

### Launch Foundational Phase Tasks in Parallel

Source: https://github.com/alfredoperez/speckit-companion/blob/main/specs/003-theme-integration/tasks.md

Execute multiple tasks concurrently to define different groups of CSS variables. This approach is used in the Foundational phase to set up theme variables efficiently.

```bash
# Launch variable definition tasks together (different variable groups):
Task: "T005 [P] Define text color variables in webview/styles/workflow.css"
Task: "T006 [P] Define accent color variables in webview/styles/workflow.css"
Task: "T007 [P] Define border color variables in webview/styles/workflow.css"
Task: "T008 [P] Define typography variables in webview/styles/workflow.css"
```