m.mabrey/sde-meeting-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f1200b7d79bc7523ac3fd2ced75f735d1cc1eb6f
sde-meeting-toolkit/README.md

8.8 KiB
Raw Blame History

Project SDE Meeting Toolkit

Purpose

This folder holds two workshop tools for Project SDE. Each tool is one HTML file. Each tool runs in a web browser. The tools do not need a server or a database. The tools do not connect to the Work Package Suite application.

Contents

File Purpose
tools/field-problem-workshop.html Field problem workshop. Captures problems, groups them into clusters, and records breadcrumbs and actions.
tools/scope-lock-meeting-suite.html Scope lock meeting suite. Holds the scope boundary board, the MVP priority ranker, the decision registry, and the Micron pilot readiness check.
skills/construction-breadcrumbs.skill A Claude skill. The skill encodes the breadcrumb method. Install this skill to use the method in any Claude chat.

Requirements

Install Node.js version 18 or later to run the local server.

You do not need Node.js to open a tool file directly in a browser.

Setup

Follow these steps to set up the project on your computer.

  1. Open a terminal.
  2. Go to the sde-meeting-toolkit folder.
  3. Run this command to check that Git tracks the folder: 
    git status
  4. To use the AI draft button through the local server, copy .env.example to .env.
  5. Open .env and set ANTHROPIC_API_KEY to your key.
  6. Do not commit .env. Git already ignores it.

Skip steps 4 through 6 if you plan to run the AI draft button only from inside a Claude artifact (see Method 3 below). The project has no other dependencies to install.

Run a tool

Choose one of the two methods below.

Method 1: Open the file directly

  1. Open a file browser.
  2. Go to the tools folder.
  3. Double-click a tool file to open it in your default browser.

This method works offline. This method does not run the AI draft button in the Field Problem Workshop.

Method 2: Run a local server

Use this method to test the tools the way a browser would load them from a web server. This method also makes the AI draft button work, if you completed steps 4 through 6 in Setup.

  1. Open a terminal.
  2. Go to the sde-meeting-toolkit folder.
  3. Run this command: 
    npm run serve
  4. Check the terminal output. It reports whether it found an API key.
  5. Open a browser.
  6. Go to this address: http://localhost:5173
  7. Click a tool link, or go directly to a file under the tools folder.
  8. Press Ctrl+C in the terminal to stop the server.

Method 3: Use the tool as a Claude artifact

Use this method to run the AI draft button without setting up a local API key.

  1. Open a chat in Claude.
  2. Upload the tool file, or add it to a Claude project.
  3. Ask Claude to render the file as an artifact.

This method needs a network connection. It does not need the local server or a .env file.

AI draft button

The Field Problem Workshop calls Claude to draft breadcrumb fields. It reaches Claude through one of two paths, never directly from the browser to the Anthropic API.

  • Local server path: The browser calls /api/claude on your own machine. server.js reads ANTHROPIC_API_KEY from .env and forwards the request. Your key stays on your machine and is never sent to the browser.
  • Claude artifact path: The Claude environment handles the request. No key setup is needed on your side.

If you run a tool by double-clicking the file, with no server, the AI draft button fails. This is expected: a plain file has no server to call.

If you run npm run serve without a .env file, or with ANTHROPIC_API_KEY unset, the button reports that the key is missing. Add the key to .env and restart the server to fix it.

Save and load your work

The two tools store data in different ways.

Field Problem Workshop: The tool holds data in the browser session only. Closing the browser tab erases unsaved data.

  1. Click Export JSON before you close the tool.
  2. Save the JSON file to your computer.
  3. Click Load JSON the next time you open the tool.
  4. Select the saved JSON file to restore your data.

Scope Lock Meeting Suite: The tool saves data automatically to the browser's local storage on the computer where you open it. Local storage does not transfer to another computer.

  1. Click Export in the tool to create a durable record.
  2. Save the exported file to your computer or to a shared drive.

Reset a tool

Each tool has a Reset control.

  • Field Problem Workshop: Reset returns the tool to the July 21 baseline. The baseline holds 43 problems in 7 root clusters, 6 breadcrumbs, and 5 actions.
  • Scope Lock Meeting Suite: Reset returns the tool to its starting state.

Reset erases current data in the tool. Export your data before you click Reset.

Install the skill

  1. Open Claude.
  2. Open the skill file: skills/construction-breadcrumbs.skill.
  3. Use the Save skill action to install it.
  4. Open a new chat to use the skill.

Version control

This folder is a Git repository. Use normal Git commands to track changes.

git add .
git commit -m "Describe your change here"

The .gitignore file excludes node_modules and common system files from commits.

Deploy for the whole company

Use this when the tool needs to be reachable by anyone on the internal network or VPN, not just on one person's machine. This uses a company-owned Anthropic API key shared by everyone who reaches the tool, so it adds a per-person login, a per-person daily token quota, and a request cap that a solo local setup does not need.

  1. Get an Anthropic API key billed to a company account, not a personal one. IT or finance should provision this, since it is billed like any other company vendor cost.
  2. Decide who needs their own login. Each name gets its own password and its own daily token quota, tracked separately.
  3. On the host or container platform, set these values as environment variables, or in a .env file next to docker-compose.yml: 
    ANTHROPIC_API_KEY=<company key>
APP_USERS=alice:pass1,bob:pass2,carol:pass3
TOKEN_LIMIT_PER_USER=50000
  4. Build and run the container: 
    docker compose up -d --build
  5. To run this alongside the existing Work Package Suite container instead of on its own, copy the sde-meeting-toolkit service block from docker-compose.yml into that stack's compose file, including its volumes entry, and apply the same environment variables there.
  6. Confirm the login prompt appears when you open the tool's URL from another machine on the network, and that it accepts one of the named user/password pairs.

What the login gate does and does not do

  • It requires a username and password before any page or API call on this tool succeeds, and identifies which named user made each AI draft call.
  • It does not encrypt traffic on its own. Run this behind the same network and VPN protections used for the Work Package Suite, and add TLS at the reverse proxy or load balancer if one is already in place for that stack.
  • It is a shared-credential list, not a real identity system. Anyone who has a name's password can use that name's quota. If real single-sign-on attribution matters later, that needs a larger integration than this tool currently supports.
  • Old single-shared-login setups still work: set APP_USERNAME and APP_PASSWORD instead of APP_USERS if you want everyone to share one login and one quota, unchanged from before this feature existed.

Per-user token quota

TOKEN_LIMIT_PER_USER caps combined input and output tokens per named user, per UTC calendar day. Default: 50000 tokens/day, which is roughly 100 to 200 AI drafts with this tool's prompt size. A user who hits the cap gets a clear error naming their usage and the time until reset, instead of a silent failure or an unexplained cost.

Usage is written to TOKEN_USAGE_FILE (default ./data/token-usage.json) after every AI call. In Docker, docker-compose.yml mounts ./data as a volume so this file survives a restart or redeploy. If you remove that volume mount, usage resets to zero every time the container restarts, which defeats the point of a daily cap.

To reset one person's quota early, stop the container, edit their entry out of the usage file (or set its date to any past date), and restart. To raise or lower the cap for everyone, change TOKEN_LIMIT_PER_USER and restart; the change applies from that point on, not retroactively.

Rate limit

RATE_LIMIT_MAX and RATE_LIMIT_WINDOW_MS cap AI draft requests per source IP address, independent of the token quota. This catches a runaway script in the first few seconds, before it could burn through a whole day's token quota. Defaults: 20 requests per 5 minutes.

Relation to the Work Package Suite

These tools support meetings about the Work Package Suite project. The tools do not call the Work Package Suite application. The tools do not read or write Work Package Suite data. Treat this toolkit and the Work Package Suite codebase as separate projects.