Using spec kit and copilot

Version 15.11.2025

• I am using GPT-5 mini inside VS Code, because under the Github education program it is free.
• As external support AI, I am using the free (& limited) Claude Sonnet 4.5.

As per usual: Speak to the AI in English. Why? All the prompt sub-information you don't see is English. If you mix in German, it makes it harder for the AI.

Why spec kit? Can't I just tell Copilot what I want?

No, because the model has a very limited memory / context. Spec kit allows to organize everything into files as well as organize how to provide information for these files.

Install

Install uv package and env manager

curl -LsSf https://astral.sh/uv/install.sh | sh
/root/.local/bin/uv tool update-shell

Don't forget toi close and open the terminal for loading the new setting. Install spec kit

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Prepare the project

I made a new project

mkdir -p /data_1/dev_latex_editor
cd /data_1/dev_latex_editor
specify init --here
specify check

I selected the copilot (copilot modus) and the I am under linux (sh modus)

• /speckit.constitution - Establish project principles
• /speckit.specify - Create baseline specification
• /speckit.plan - Create implementation plan
• /speckit.tasks - Generate actionable tasks
• /speckit.implement - Execute implementation

Optional commands that you can use for your specs (improve quality & confidence)

• /speckit.clarify (optional) - Ask structured questions to de-risk ambiguous areas before planning (run before /speckit.plan if used)
• /speckit.analyze (optional) - Cross-artifact consistency & alignment report (after /speckit.tasks, before /speckit.implement)
• /speckit.checklist (optional) - Generate quality checklists to validate requirements completeness, clarity, and consistency (after /speckit.plan)

In VS Code:

More information about the spec kit is here: https://github.com/github/spec-kit

Using spec kit

Step 1: Establish project principles

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

Sound for me like it should be default for all project.

Step 2: Create the spec

"Use the /speckit.specify command to describe what you want to build. Focus on the what and why, not the tech stack."

This is the moment where you will not write the text alone. Open the webpage of the AI chat of your chosing (Not Akinator!) -> Let's call it "Outsider AI". And tell it

I am working on the text for /speckit.specify of spec kit. 

This is my text so far. Can you help me to improve the text? Thanks!

[your idea]

Removing all the tangents I had, I mainly used:

• What additional details would you suggest?
• Thanks a lot! Do you have any suggestions?
• Please show me the finished text. Thanks!

In the end I got this text:

# LaTeX Equation Editor Plugin Specification

## Overview

Build an Overleaf plugin that provides a LaTeX equation editor in a floating window. Users access this editor via a button in the main editor's toolbar.

## Core Components

### 1. Equation Display Area

- **Output Field**: Renders the current LaTeX equation as a typeset preview with live updates as the user types

  - **Preview Size Control**: Toggle or slider to adjust the size of the rendered equation for better visibility of complex equations

- **Input Field**: Text area where users type LaTeX code

- **Clear Button**: Clears the equation input field

- **Error Handling**:

  - Display a small warning icon or red border around the output field when LaTeX syntax is invalid

  - Show specific error message below the preview (e.g., "Missing closing brace" or "Unknown command \xyz")

  - If rendering fails, show the last valid preview or keep the output field empty

  - Users can continue typing even with errors present (non-blocking)

### 2. Symbol Selection System

- **Symbol Group Selector**: Displays available symbol categories in a grid layout. Clicking a category updates the symbol palette below.

  - **Recent Symbols Category**: Only displayed when window width exceeds 600px. Shows recently used symbols for quick access.

- **Symbol Palette**: Shows symbols from the selected group in a responsive grid layout

  - Grid adapts to window width to use available space effectively

  - Minimum symbol button size: 40x40px for usability

  - Visual hover feedback on symbol buttons

  - Clicking any symbol inserts its LaTeX code into the equation input field and updates the rendered preview

### 3. Symbol Database Structure

Located in the `symbolDB` directory:

- Each file represents one symbol group

- **Symbol Group properties**:

  - Name (used for tooltip)

  - Label (displayed on the category button)

- **Individual Symbol properties**:

  - Label (displayed on the symbol button)

  - LaTeX string (inserted when clicked)

  - Description (used for tooltip and search)

### 4. Search Functionality

A search bar allows users to find symbols by searching through symbol descriptions.

### 5. Equation History

- Maintains a history of equations within the current session

- Previous/Next navigation buttons to cycle through equation history

- Allows users to revisit or restore previously entered equations

- History is independent of the main editor's undo system

## Window Behavior

### Positioning & Sizing

- **Default Size**: 500x400px (or ~30% of screen width/height)

  - On screens smaller than 1024px wide, opens smaller or maximized for optimal use of space

- **Default Position**: Centered on first open, then remembers last position

- **Minimum Dimensions**:

  - Width: 400px (accommodates equation input, 4-6 symbol buttons per row, and search bar)

  - Height: 300px (ensures all components remain functional)

- **Movable**: Users can drag the window to any position

- **Resizable**: Users can scale the window size while respecting minimum dimensions

### Window Controls

- **Close Button**: Closes the LaTeX editor window completely

- **Minimize Button**: Collapses the window to the lower-left corner

- **Restore**: Clicking the minimized window returns it to its previous position and size

### Interaction Model

- **Non-blocking**: The window operates modally—users can continue editing in the main editor while the LaTeX editor is open

- **Compact Design**: Balance minimizing screen space usage with maintaining usability

- **Performance**: Must not slow down or interfere with main editor operations

## Integration with Main Editor

### Equation Insertion

- **Insert Button**: Inserts the current equation at the text cursor position in the main editor

- **Copy Button**: Copies the current LaTeX code to the clipboard for use elsewhere

- After insertion, the equation remains in the input field (not cleared)

- Window stays open after insertion to support continued editing workflow

### Equation Loading

- When users select text in the main editor **while the LaTeX window is already open**, that text replaces the content in the equation input field, allowing quick editing of existing equations

- The window does **not** automatically open when text is selected (to avoid disrupting user experience)

## Keyboard Shortcuts

- **Open/Close LaTeX Editor**: Ctrl+E (or Cmd+E on Mac)

- **Insert Equation**: Ctrl+Enter while focused in the LaTeX editor window

- **Close Window**: ESC key

- **Navigate Symbol Palette**: Arrow keys to move between symbols, Enter to select

- **Navigate History**: Alt+Left/Right (or Cmd+Left/Right on Mac) to cycle through equation history

## Accessibility

- **Keyboard Navigation**: Full keyboard support for navigating the symbol palette using arrow keys

- **Focus Indicators**: Clear visual indicators for keyboard navigation

- **Screen Reader Support**: Symbol descriptions are properly labeled for screen readers

- **High Contrast**: All UI elements maintain sufficient contrast ratios

## Theming

- The LaTeX editor window automatically adapts to Overleaf's current theme setting (light/dark mode)

- Rendered equations remain clearly visible in both themes

- All UI components respect the selected theme

## Design Philosophy

The LaTeX editor is a support tool meant to enhance workflow without disruption. The design anticipates that users will frequently minimize and restore the window as they work. Prioritize:

1. Non-obtrusiveness

2. Responsiveness and live feedback

3. Seamless integration with the main editing experience

4. Efficient use of screen space while maintaining functionality

I stuffed it into Copilot

/speckit.specify [BLA BLA lot of text]

Step 3: Define the tools available

You want to close the test loop such that Copilot can see what it is doing and what tools / commands are necessary for doing so

I have a rather complicated workflow because I need to build the code and restart a docker container before testing. The outside AI helped to me to define the workflow:

Before we start implementation, here's the complete build/test/verification workflow:

**Build Process:**
Location: /data_1/dev_latex_editor/overleaf-source/server-ce

Full build (slow, builds 3 containers):
```bash
cd /data_1/dev_latex_editor/overleaf-source/server-ce && make all
```

Quick build (recommended - only builds sharelatex:modifications):
```bash
cd /data_1/dev_latex_editor/overleaf-source/server-ce && make build-community
```

**CRITICAL: Build takes 5-15 minutes. You MUST wait for the build to complete before restarting the container. Do not proceed until you see "Successfully tagged" messages in the output.**

**Restart Container:**
```bash
cd /data_1/docker/compose_cep && docker compose down overleafserver && docker compose up -d overleafserver
```

**Verify Container Health:**
**CRITICAL: Wait for container to be healthy before any testing. This can take 30-60 seconds.**
```bash
sleep 2s && docker ps | grep overleafserver
```
Look for "healthy" status. If not healthy, wait and check again. DO NOT proceed with tests until status shows "healthy".

**Check Logs:**
Container logs:
```bash
cd /data_1/docker/compose_cep && docker compose logs overleafserver
```

Web log (snapshot):
```bash
docker exec overleafserver bash -c "cat /var/log/overleaf/web.log"
```

Web log (live tail):
```bash
docker exec overleafserver bash -c "tail -n 200 -f /var/log/overleaf/web.log"
```

**Testing Workflow:**
1. Make code changes in overleaf-source/
2. Run `make build-community` - **WAIT 5-15 minutes for completion**
3. Restart container
4. **WAIT for healthy status (30-60 seconds)** - check with docker ps command
5. Check logs for errors
6. Manually verify in browser (Playwright tests coming later)

**DO NOT skip wait steps or you will test against old code.**

Now please proceed with: Start implementing the migration script first to generate symbolDB/index.json, so the frontend work can import the new symbol files as we build the UI.

Discuss with the outside AI how to explain this stuff as well the test loop to Copilot.

Step 4: /speckit.clarify

Ask Copilot if it has clarification questions and answer them

Step 5: Create a technical implementation plan

"Use the /speckit.plan command to provide your tech stack and architecture choices."

In my case I had an example module which it analysed and used as basis. This is what the example on the spec kit page is:

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

Step 6: Break down into tasks

"Use /speckit.tasks to create an actionable task list from your implementation plan."

/speckit.tasks

Step 7: Execute implementation

"Use /speckit.implement to execute all tasks and build your feature according to the plan."

/speckit.implement

Motivational speeches to the copilot AI

(generated by the outside AI)

**Change your working style:**

STOP asking for approval after every tiny change. You have full permission to work autonomously on this project.

**New rules:**

1. **Work in meaningful chunks** - implement complete phases/features before reporting
2. **Only report when:**
   - A complete phase is done and ready to test
   - You encounter a blocking issue you can't resolve
   - You need a design decision from me
   - Ready to run the full build/test cycle

3. **Don't report:**
   - Individual file changes
   - Small refactors
   - Minor fixes
   - Intermediate progress

4. **Batch your work:**
   - Analyze all the symbol palette files
   - Understand the integration
   - Implement the complete LaTeX editor module following Overleaf's patterns
   - Test it works
   - THEN report back with summary

**Example of good reporting:**
"Phase A complete: Implemented toolbar integration, floating window, and basic editor. Ready to test. Here's what changed: [summary]. Run full-build-test-cycle.sh?"

**Example of bad reporting:**
"I added one line to file X. Should I continue?"

Now: Analyze the symbol palette code, understand the integration, implement Phase A completely, then report back when it's ready to test.

Work autonomously. I trust you.

**Project Permissions & Backup Policy:**

**Full Access Permission:**
You have full read/write access to the project directory `/data_1/dev_latex_editor/` and can make any changes needed without asking for permission. This includes:
- Creating, modifying, or deleting files
- Creating new directories
- Running commands in this directory
- Making configuration changes

**Automatic Backup Before Major Changes:**
Before any significant changes (build, migration, major refactoring), create a timestamped backup:
```bash
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
cp -r /data_1/dev_latex_editor /data_1/dev_latex_editor_backup_$TIMESTAMP
echo "Backup created: /data_1/dev_latex_editor_backup_$TIMESTAMP"
```

**Backup Policy:**
- Create backup before: builds, migrations, multi-file refactors, structural changes
- Do NOT backup before: single file edits, small fixes, test runs
- Keep backups labeled with timestamp format: `YYYYMMDD_HHMMSS`
- Example: `/data_1/dev_latex_editor_backup_20241114_153045`

**Now please:**
1. Create a backup of the current state
2. Update sso-open-latex.js to use credentials.json as described
3. Create a template credentials.json file with placeholder password (I'll fill in the actual password manually)
4. Then proceed with the build/test workflow

Notes

1. The AI is stubborn as hell. It does stop and stop and stop. Under Linux I made a motivational trainer. Normally, you would use just Proceed to not create a thought process but it keeps forgetting the core aspects of its procedures.

   #!/bin/bash
   
   MotivationString="Proceed (Remember to use the scripts/full-build-test-cycle.sh for the build, restart and test processes; We don't git push anything to the outside; Fix the bugs iteratively until **all** the tests pass;)"
   
   countdown() {
       local seconds=$1
       while [ $seconds -gt 0 ]; do
           local mins=$((seconds / 60))
           local secs=$((seconds % 60))
           printf "Next attempt in: %02d:%02d\r" $mins $secs
           sleep 1
           : $((seconds--))
       done
       echo -e "\nResuming...        "
   }
   
   while true; do
       date
       echo "Ping..."
       
       WINDOW_ID=$(DISPLAY=:100 xdotool search --name "Visual Studio Code" | head -1)
       
       if [ -z "$WINDOW_ID" ]; then
           echo "Could not find VS Code window"
           sleep 10
           continue
       fi
       
       echo "Found window: $WINDOW_ID"
       
       DISPLAY=:100 xdotool windowactivate --sync $WINDOW_ID
       sleep 1
       DISPLAY=:100 xdotool windowfocus $WINDOW_ID
       sleep 0.5
       DISPLAY=:100 xdotool type --delay 100 "${MotivationString}"
       sleep 0.5
       DISPLAY=:100 xdotool key Return
       
       echo "Waiting..."
       countdown 250
   done
   

2. If it fails to deliver want you want then put that into tests. Tell it to pass the tests. Don't remember it of the design goal, but the into tests.
3. Force it to give you screenshots.
4. Manage your allow command list in VS Code's User setting.json

   {
       "workbench.startupEditor": "none",
       "diffEditor.ignoreTrimWhitespace": true,
       "chat.tools.terminal.autoApprove": {
           "eslint": true,
           "/^cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/overleaf_modifiers && sh distribute_files\\.sh && sh build\\.sh && cd /data_1/docker/compose_cep && sh cycle_overleafserver\\.sh$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^npm run sso-open-latex --silent$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node playwright-tests/sso-open-latex-features\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "npx": true,
           "true": true,
           "/^cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/overleaf_modifiers && sh distribute_files\\.sh && sh build\\.sh$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^cd /data_1/docker/compose_cep && sh cycle_overleafserver\\.sh$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^sh scripts/build_and_mark\\.sh$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^sh /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/scripts/build_and_mark\\.sh$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/scripts/build_and_mark\\.sh$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/playwright-tests/sso-open-latex-features\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/playwright-tests/editor-smoke-test\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node playwright-tests/editor-smoke-test\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "npm run playwright:install": true,
           "/^node playwright-tests/editor-feature-test\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "docker compose": true,
           "/^node playwright-tests/live-open-latex\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/playwright-tests/live-open-latex\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "sed": true,
           "identify": true,
           "/^bash \\./scripts/build_and_mark\\.sh$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash -lc 'cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor && node playwright-tests/sso-open-latex-features\\.js'$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash -lc 'cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor && node playwright-tests/sso-open-latex-features\\.js && cat playwright-tests/sso-open-latex-features-report\\.json'$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash -lc 'cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor && git --no-pager diff -- playwright-tests/sso-open-latex-features\\.js \\| sed -n \"1,200p\"'$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash -lc 'cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor && node playwright-tests/sso-open-latex-features\\.js && ls -la playwright-tests/features-steps && sed -n \"1,200p\" playwright-tests/sso-open-latex-features-report\\.json'$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash -lc 'git add -A && git commit -m \"docs\\(skills\\): add Playwright feature-test skill and document test/run workflow; cleanup screenshots before test\" \\|\\| true && git --no-pager show --name-only --pretty=\"format:\" HEAD'$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash -lc 'cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor && node playwright-tests/latex-editor-regression-tests\\.js && sed -n \"1,240p\" latex-editor-regression-report\\.json'$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash -lc 'cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor && sed -n \"1,240p\" playwright-tests/latex-editor-regression-report\\.json && echo \"\\\\n--- regression screenshots ---\" && ls -la playwright-tests/features-steps/regression \\|\\| true'$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^bash -lc 'cd /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor && node playwright-tests/latex-editor-regression-tests\\.js && sed -n \"1,240p\" playwright-tests/latex-editor-regression-report\\.json'$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node playwright-tests/latex-editor-regression-tests\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/playwright-tests/latex-editor-regression-tests\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/playwright-tests/latex-editor-regression-tests\\.js \\|\\| true$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node \\./playwright-tests/latex-editor-regression-tests\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node /data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/playwright-tests/sso-open-latex-features\\.js --output=/data_1/docker/compose_cep/overleafserver/build_overleaf_docker_image/latex-editor/playwright-tests/features-steps/regression$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "docker logs": true,
           "docker exec": true,
           "git fetch": true,
           "git ls-remote": true,
           "/^node tools/migrate-symbols-to-symbolDB\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node -e \"require\\('\\./overleaf-source/services/web/modules/symbol-palette/frontend/utils/categories\\.js'\\); console\\.log\\('ok'\\)\"$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^TIMESTAMP=\\$\\(date \\+%Y%m%d_%H%M%S\\) && cp -r /data_1/dev_latex_editor /data_1/dev_latex_editor_backup_\\$TIMESTAMP && echo \"Backup created: /data_1/dev_latex_editor_backup_\\$TIMESTAMP\"$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "make": true,
           "docker ps": true,
           "break": true,
           "/^cd /data_1/dev_latex_editor/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^rm -rf /data_1/dev_latex_editor/playwright-tests/": {
               "approve": true,
               "matchCommandLine": true
           },
           "/^node /data_1/dev_latex_editor/playwright-tests/sso-open-latex\\.js$/": {
               "approve": true,
               "matchCommandLine": true
           },
           "npm install": true,
           "node": true,
           "cd": true,
           "cp": true,
           "bash": true,
           "chmod": true,
           "docker system": true,
           "/bin/bash": true,
           "/data_1/dev_latex_editor/.specify/scripts/bash/check-prerequisites.sh": true,
           "/data_1/dev_latex_editor/build-and-restart.sh": true,
           "/data_1/dev_latex_editor/scripts/build-and-restart.sh": true,
           "/data_1/dev_latex_editor/scripts/full-build-test-cycle.sh": true,
           "/data_1/dev_latex_editor/scripts/run-playwright-test.sh": true,
           "git rev-parse": true,
           "npm run webpack:profile": true,
           "docker cp": true,
           "mkdir": true,
           "git add": true,
           "git commit": true,
           "git push": true,
           "nohup": true,
           "docker images": true,
           "ps": true,
           "docker inspect": true,
           "git format-patch": true
       },
       "git.enableSmartCommit": true,
       "chat.agent.maxRequests": 250,
       // Adding the lines for Python 
       "editor.rulers": [
           80,
           120
       ],
       // I don't like the automatic interference 
       "editor.autoClosingBrackets": "never",
       "editor.autoClosingDelete": "never",
       "editor.autoClosingOvertype": "never",
       "editor.autoClosingQuotes": "never",
       "editor.autoSurround": "never",
       // Stopping drag and drop from interfering 
       "editor.dragAndDrop": false,
       // I don't like if I hover over a word and 
       // VS Code blocks my view with information
       "editor.hover.delay": 5000,
       // Bigger fonts (bad eyes)
       "editor.fontSize": 16,
       // Black does it's work on saving
       "editor.formatOnSave": true,
       // I decided to violate these rules:
       // E402: Module level import not at top of file https://www.flake8rules.com/rules/E402.html
       // E501: Line too long (> 79 characters) https://www.flake8rules.com/rules/E501.html
       // W503: Line break occurred before a binary operator https://www.flake8rules.com/rules/W503.html
       //       PEP8 was changed; replaced by W504 "Line break occurred after a binary operator https://www.flake8rules.com/rules/W504.html"
       // E203: Whitespace before ':' https://www.flake8rules.com/rules/E203.html Black wants this really badly!
       "flake8.args": [
           "--ignore=E402,E501,W503,E203"
       ],
       "python.analysis.typeCheckingMode": "basic",
       "window.zoomLevel": 1.5
   }
   

   I have the feeling that the regular expressions don't really work.
5. Dealing with switches between Home Office (i.e. mobile office) and the office in the university. Try to prevent to close the VS code. I am using xpra for connect to VS code (-insiders) from both places.