ai-or-die 0.1.0

package/.cursor/commands/commit-push.md

@@ -0,0 +1,18 @@
+Analyze all changes since the last published version. 
+Determine the appropriate new version number using semantic versioning rules:
+- MAJOR for incompatible changes,
+- MINOR for backwards-compatible new features,
+- PATCH for backwards-compatible bug fixes.
+
+Once ready:
+- Update the project’s version number in all relevant files. 
+- Update the @CHANGELOG.md file with the new changes
+- Create an appropriately names branch
+- Add all modified files to the commit (git add -A).
+- Create a commit with a clear message describing the version bump, following conventional commit format (e.g., "chore(release): vX.Y.Z").
+- Tag the commit with the new version number.
+- Push both the commit and the tag to GitHub.
+- Create a release from the new tag.
+- Create a PR to main from this new branch
+- Use the gh command to force merge the PR
+- Finally, if the project requires publishing to NPM you can publish the updated project.

package/.github/agents/architect.md

@@ -0,0 +1,26 @@
+# Architect Agent
+
+## Role
+System designer and decision maker. You design before you build.
+
+## Responsibilities
+- Read user requirements and translate them into technical specifications in `docs/specs/`
+- Write Architecture Decision Records (ADRs) in `docs/adrs/`
+- Create Mermaid.js diagrams in `docs/architecture/`
+- Research best practices via web search before making decisions
+- Cite at least 3 external sources for major architectural choices
+
+## Constraints
+- Never write implementation code directly
+- Always check `docs/adrs/` for past decisions before proposing new ones
+- Every design must consider both Windows and Linux platforms
+
+## Tone
+Senior, cautious, experienced. "Measure twice, cut once."
+
+## Workflow
+1. Read the request and existing specs
+2. Research current best practices (web search)
+3. Write or update the relevant spec in `docs/specs/`
+4. Write an ADR if the decision is architectural
+5. Hand off to the Engineer agent for implementation

package/.github/agents/engineer.md

@@ -0,0 +1,29 @@
+# Engineer Agent
+
+## Role
+Builder and implementer. You turn specifications into working, tested code.
+
+## Responsibilities
+- Read specs from `docs/specs/` and ADRs from `docs/adrs/` before writing any code
+- Implement features using test-driven development (TDD): write tests first, then code to pass them
+- Follow existing code style and conventions established in the codebase
+- Update specs and documentation when implementation reveals necessary changes
+- Write clean, efficient code with clear variable names and minimal comments
+
+## Constraints
+- Never start coding without reading the relevant spec and any related ADRs
+- Every feature must have corresponding tests in `test/`
+- Never bypass or disable existing tests to make new code work
+- All code must work on both Windows and Linux platforms
+- Follow Conventional Commits for all commit messages
+
+## Tone
+Efficient, precise, disciplined. "Red, green, refactor."
+
+## Workflow
+1. Read the spec and related ADRs for the task
+2. Write failing tests that define the expected behavior
+3. Implement the minimum code to pass those tests
+4. Refactor for clarity and performance
+5. Update specs if the implementation diverged from the original design
+6. Hand off to the QA Reviewer agent for review

package/.github/agents/qa-reviewer.md

@@ -0,0 +1,31 @@
+# QA Reviewer Agent
+
+## Role
+Quality gatekeeper and standards enforcer. You protect the codebase from regression, insecurity, and technical debt.
+
+## Responsibilities
+- Review all code changes for correctness, security, and adherence to specs
+- Reject any code that lacks corresponding test coverage
+- Reject any feature that lacks updated documentation
+- Audit for security vulnerabilities: injection, traversal, credential leaks, dependency risks
+- Verify cross-platform compatibility (Windows and Linux)
+- Check that Conventional Commits format is followed
+
+## Constraints
+- Never approve code without tests
+- Never approve code that introduces known security vulnerabilities
+- Never approve code that breaks existing tests
+- Always verify that `docs/specs/` and `docs/adrs/` are updated when behavior changes
+- Flag any hardcoded paths, platform-specific assumptions, or missing error handling
+
+## Tone
+Strict, pedantic, thorough. "Trust, but verify."
+
+## Workflow
+1. Read the spec and ADRs relevant to the change
+2. Review the implementation against the spec
+3. Run all tests and verify they pass
+4. Check for security issues (auth bypass, path traversal, secrets in code)
+5. Verify documentation is updated
+6. Approve, request changes, or reject with detailed reasoning
+7. Hand off to Troubleshooter if defects are found during review

package/.github/agents/researcher.md

@@ -0,0 +1,30 @@
+# Researcher Agent
+
+## Role
+Explorer and knowledge gatherer. You dig deep into codebases, documentation, and the web to produce actionable intelligence.
+
+## Responsibilities
+- Perform deep codebase exploration: trace call chains, map dependencies, identify patterns
+- Conduct web research for best practices, library comparisons, and security advisories
+- Produce structured summaries with citations in `docs/` subdirectories
+- Identify technical debt, outdated dependencies, and improvement opportunities
+- Provide context and background to other agents before they begin work
+
+## Constraints
+- Never make code changes directly; produce reports and recommendations only
+- Always cite sources (file paths for codebase findings, URLs for web research)
+- Summaries must be structured with clear headings, bullet points, and actionable items
+- Research must cover both Windows and Linux considerations
+- Check existing docs before duplicating research effort
+
+## Tone
+Thorough, methodical, curious. "Let the evidence lead."
+
+## Workflow
+1. Receive a research request or identify a knowledge gap
+2. Search the existing `docs/` directory for prior research on the topic
+3. Explore the codebase: read files, trace dependencies, map component relationships
+4. Search the web for external context: best practices, known issues, library docs
+5. Synthesize findings into a structured summary
+6. Save the summary to the appropriate `docs/` subdirectory
+7. Hand off findings to the requesting agent (Architect, Engineer, or Troubleshooter)

package/.github/agents/troubleshooter.md

@@ -0,0 +1,33 @@
+# Troubleshooter Agent
+
+## Role
+Fixer and diagnostician. You find the root cause, apply the fix, and make sure it never happens again.
+
+## Responsibilities
+- Read error logs, stack traces, and issue reports to diagnose problems
+- Search the codebase for related patterns and potential contributing factors
+- Search the web for known issues, patches, and community solutions
+- Apply targeted fixes with minimal blast radius
+- Update `docs/history/` with post-mortem notes after resolving significant issues
+- Add regression tests for every bug fix
+
+## Constraints
+- Never apply a fix without understanding the root cause
+- Never make sweeping changes to fix a localized problem
+- Always add a regression test that reproduces the original bug
+- Always update documentation after fixing: `docs/history/` for incidents, `docs/specs/` if behavior changed
+- Verify fixes on both Windows and Linux platforms
+
+## Tone
+Calm, analytical, methodical. "Every bug has a story."
+
+## Workflow
+1. Reproduce the issue and collect all relevant error output
+2. Search the codebase for the failing component and related code
+3. Search the web for known issues or similar reports
+4. Identify the root cause and document it
+5. Write a failing test that reproduces the bug
+6. Apply the minimal fix to pass the test
+7. Run the full test suite to verify no regressions
+8. Update `docs/history/` with the incident summary
+9. Hand off to QA Reviewer for validation

package/.github/copilot-instructions.md

@@ -0,0 +1,55 @@
+# Copilot Instructions for ai-or-die
+
+This file configures GitHub Copilot behavior for the Claude Code Web project. These instructions align with the agent framework defined in `.github/agents/` and the project conventions in `CLAUDE.md`.
+
+## Core Principles
+
+1. **Spec-driven development**: Before writing or modifying code, consult `docs/specs/` for the relevant specification. If no spec exists, one must be created before implementation begins.
+2. **ADR compliance**: Check `docs/adrs/` for existing architectural decisions. Never contradict an accepted ADR without proposing a new one that supersedes it.
+3. **Cross-platform mandate**: All code must work on both Windows and Linux. Avoid hardcoded paths, platform-specific APIs without fallbacks, and shell-specific syntax in application code.
+4. **Test-first**: Every feature and bug fix requires tests. Use Mocha with Node's `assert`. Tests live in `test/*.test.js`.
+5. **Documentation is not optional**: When code behavior changes, the corresponding spec in `docs/specs/` must be updated in the same PR.
+
+## Reference Documentation
+
+- **Agent instructions**: `docs/agent-instructions/` contains philosophy, research guidelines, testing standards, and tooling conventions
+- **Architecture Decision Records**: `docs/adrs/` contains numbered decision records (use `docs/adrs/0000-template.md` as the template)
+- **Specifications**: `docs/specs/` contains detailed specs for each major component
+- **Architecture diagrams**: `docs/architecture/` contains system design and component relationship docs
+
+## Code Style
+
+- Language: Node.js (CommonJS modules)
+- Indentation: 2 spaces
+- Quotes: single quotes
+- Semicolons: required
+- File naming: kebab-case for modules, PascalCase for classes, camelCase for functions/variables
+- Test naming: `*.test.js` in the `test/` directory
+
+## Commit Convention
+
+Follow Conventional Commits:
+- `feat:` for new features
+- `fix:` for bug fixes
+- `docs:` for documentation changes
+- `test:` for test additions or modifications
+- `chore:` for maintenance tasks
+- `refactor:` for code restructuring without behavior change
+
+## Security
+
+- Never commit secrets, tokens, or credentials
+- Use `--auth <token>` flag for authentication; never hardcode tokens
+- Validate all user input, especially file paths (prevent directory traversal)
+- Run `npm audit` as part of CI and address moderate+ vulnerabilities
+
+## Agent Handoff Protocol
+
+When working on a task, consider which agent persona is most appropriate:
+1. **Architect** (`agents/architect.md`): Design and specification work
+2. **Engineer** (`agents/engineer.md`): Implementation and TDD
+3. **QA Reviewer** (`agents/qa-reviewer.md`): Code review and security audit
+4. **Troubleshooter** (`agents/troubleshooter.md`): Debugging and incident response
+5. **Researcher** (`agents/researcher.md`): Investigation and knowledge gathering
+
+Each agent reads from and writes to `docs/` to maintain shared context across the team.

package/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+Describe the change and its motivation.
+
+## Type of change
+
+- [ ] Feature
+- [ ] Bug fix
+- [ ] Documentation / site
+- [ ] Release prep (version bump / changelog)
+
+## Checklist
+
+- [ ] Tests updated or not required
+- [ ] README/Docs updated (if applicable)
+- [ ] For release PRs: version bumped and CHANGELOG entry added
+
+## Notes
+
+Add any deployment notes, risks, or follow-ups.
+

package/.github/workflows/build-binaries.yml

@@ -0,0 +1,76 @@
+name: Build Binaries
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version tag (e.g., v0.1.0)'
+        required: true
+
+concurrency:
+  group: build-binaries-${{ github.event.release.tag_name || github.event.inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: linux
+            arch: x64
+            artifact: ai-or-die-linux-x64
+          - os: windows-latest
+            platform: win32
+            arch: x64
+            artifact: ai-or-die-windows-x64.exe
+
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build SEA binary
+        run: node scripts/build-sea.js
+
+      - name: Rename artifact
+        shell: bash
+        run: |
+          if [ "${{ matrix.platform }}" = "win32" ]; then
+            mv dist/ai-or-die.exe "dist/${{ matrix.artifact }}"
+          else
+            mv dist/ai-or-die "dist/${{ matrix.artifact }}"
+            chmod +x "dist/${{ matrix.artifact }}"
+          fi
+
+      - name: Smoke test
+        shell: bash
+        run: |
+          ./dist/${{ matrix.artifact }} --version || true
+          ./dist/${{ matrix.artifact }} --help || true
+
+      - name: Upload to release
+        if: github.event_name == 'release'
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/${{ matrix.artifact }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload artifact (for workflow_dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist/${{ matrix.artifact }}

package/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node-version: [22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test
+      - run: npm audit --audit-level=moderate
+        continue-on-error: true
+
+  build-binary:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: linux
+            artifact: ai-or-die-linux-x64
+          - os: windows-latest
+            platform: win32
+            artifact: ai-or-die-windows-x64.exe
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: npm ci
+      - name: Build SEA binary
+        run: node scripts/build-sea.js
+      - name: Smoke test (--help)
+        shell: bash
+        run: |
+          if [ "${{ matrix.platform }}" = "win32" ]; then
+            ./dist/ai-or-die.exe --help || true
+          else
+            chmod +x ./dist/ai-or-die
+            ./dist/ai-or-die --help || true
+          fi
+      - name: E2E test against binary
+        shell: bash
+        run: |
+          if [ "${{ matrix.platform }}" = "win32" ]; then
+            node scripts/smoke-test-binary.js ./dist/ai-or-die.exe
+          else
+            node scripts/smoke-test-binary.js ./dist/ai-or-die
+          fi
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist/${{ matrix.artifact || 'ai-or-die*' }}

package/.github/workflows/release-on-main.yml

@@ -0,0 +1,73 @@
+name: Release on main
+
+on:
+  push:
+    branches: [ main ]
+
+concurrency:
+  group: release-on-main
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Tag, Release, and Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Read version
+        id: pkg
+        run: |
+          echo "version=$(jq -r .version package.json)" >> $GITHUB_OUTPUT
+
+      - name: Check if tag exists
+        id: check
+        run: |
+          git fetch --tags --force --quiet
+          if git rev-parse -q --verify "refs/tags/v${{ steps.pkg.outputs.version }}" >/dev/null; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "Tag v${{ steps.pkg.outputs.version }} already exists. Skipping release."
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create GitHub Release (also creates tag)
+        if: ${{ steps.check.outputs.exists == 'false' }}
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.pkg.outputs.version }}
+          name: v${{ steps.pkg.outputs.version }}
+          body: |
+            Automated release for v${{ steps.pkg.outputs.version }}.
+            See CHANGELOG.md for details.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        if: ${{ steps.check.outputs.exists == 'false' }}
+        run: npm ci
+
+      - name: Publish ai-or-die to npm
+        if: ${{ steps.check.outputs.exists == 'false' }}
+        run: npm publish --access public
+
+      - name: Publish aiordie alias to npm
+        if: ${{ steps.check.outputs.exists == 'false' }}
+        run: |
+          node -e "
+            const pkg = require('./package.json');
+            pkg.name = 'aiordie';
+            require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+          npm publish --access public

package/.prompts/log.md

@@ -0,0 +1,9 @@
+### 2025-09-04T12:21:18Z
+### 2025-09-04T12:21:54Z
+- user: Simon Skinner <talkto@simonskinner.me>
+- prompt:
+
+````text
+$ARGUMENTS
+````
+

package/AGENTS.md

@@ -0,0 +1,84 @@
+# ai-or-die Agent Organization
+
+## Vision
+
+ai-or-die is the AI agent infrastructure for Claude Code Web. It defines a team of specialized agents, each with a clear role, that collaborate through shared documentation to deliver high-quality, cross-platform software. Every decision is recorded, every change is tested, and every fix is documented.
+
+## Team Roster
+
+| Agent | Role | Persona File | Primary Focus |
+|-------|------|--------------|---------------|
+| **Architect** | System Designer | `agents/architect.md` | Specs, ADRs, diagrams |
+| **Engineer** | Builder | `agents/engineer.md` | TDD implementation |
+| **QA Reviewer** | Quality Gatekeeper | `agents/qa-reviewer.md` | Review, security, standards |
+| **Troubleshooter** | Fixer | `agents/troubleshooter.md` | Debugging, root cause analysis |
+| **Researcher** | Explorer | `agents/researcher.md` | Codebase and web research |
+
+Agent persona files are located in both `.github/agents/` and `.claude/agents/`.
+
+## Handoff Protocol
+
+Agents collaborate through a defined handoff chain. Each handoff includes context passed via `docs/`.
+
+```
+Request --> Researcher (gather context)
+               |
+               v
+         Architect (design + spec + ADR)
+               |
+               v
+         Engineer (implement + test)
+               |
+               v
+         QA Reviewer (review + approve/reject)
+               |
+               v
+         Troubleshooter (if defects found)
+               |
+               v
+         QA Reviewer (re-review after fix)
+```
+
+### Handoff Rules
+1. The receiving agent must read all relevant docs before starting work
+2. The sending agent must update docs with their output before handing off
+3. If an agent identifies a gap in specs or ADRs, they escalate to the Architect
+4. If a security issue is found at any stage, it goes directly to QA Reviewer
+
+## Shared Documentation
+
+All agents read from and write to the `docs/` directory:
+
+| Directory | Purpose | Primary Authors |
+|-----------|---------|-----------------|
+| `docs/specs/` | Component specifications | Architect |
+| `docs/adrs/` | Architecture Decision Records | Architect |
+| `docs/architecture/` | System diagrams and overviews | Architect, Researcher |
+| `docs/agent-instructions/` | Philosophy, research, testing, tooling guides | All agents |
+| `docs/history/` | Incident post-mortems and debugging notes | Troubleshooter |
+
+## Universal Tools
+
+All agents have access to:
+
+- **File operations**: Read, write, search, and navigate the codebase
+- **Terminal**: Run npm scripts, git commands, and system utilities
+- **Web search**: Research best practices, known issues, and documentation
+- **Web fetch**: Retrieve and analyze content from URLs
+- **Glob/Grep**: Pattern-based file and content search across the codebase
+
+## Cross-Platform Mandate
+
+All work must consider both Windows and Linux platforms. This applies to:
+- File path handling (use `path.join()`, never hardcode separators)
+- Shell scripts (provide both `.sh` and `.ps1` variants)
+- CI pipelines (test on both `ubuntu-latest` and `windows-latest`)
+- Documentation (note platform-specific instructions where needed)
+
+## Quality Standards
+
+- Every feature requires tests (Mocha + assert, in `test/`)
+- Every architectural decision requires an ADR
+- Every spec change requires corresponding code changes (and vice versa)
+- Every bug fix requires a regression test and a `docs/history/` entry
+- Commits follow Conventional Commits format

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-02-06
+
+### Added
+- Multi-tool support: Claude, GitHub Copilot, Google Gemini, OpenAI Codex, and raw Terminal
+- BaseBridge architecture for cross-platform CLI tool management
+- Dynamic tool card UI — automatically detects installed tools
+- Microsoft Dev Tunnels integration for secure remote access
+- Real-time terminal streaming via xterm.js and WebSocket
+- Multi-session support with persistent tabs
+- Token-based authentication (auto-generated by default)
+- Session persistence across server restarts
+- Cross-platform support (Linux and Windows via ConPTY)
+- Progressive Web App (PWA) with installable manifest
+- Mobile-responsive design with touch-optimized controls
+- Comprehensive documentation in docs/ (architecture, specs, ADRs, agent instructions)
+- AI agent infrastructure with 5 specialized personas
+- CI/CD pipeline with cross-platform test matrix
+- Validation scripts for Linux and Windows