Test While Designing.
The tests exist before the code.
Ask in a Slack thread how a screen would look. TWD Design answers with a clickable HTML prototype that
uses your design guide, carries its acceptance criteria as TWD scenarios that already
pass in the page, and DEV: notes for whoever implements it. Iterate in the thread until the team agrees,
then it opens a pull request in your repo. Developers build until those scenarios pass.
Self-hosted and open source: your Slack app, your GitHub App, your model key. Nothing is stored.
design (TWD Design) → build (twd-js + twd-ai) → CI (twd-cli) → review (twd-relay, recordings)
- Iterate in the thread. Reply "and on mobile?" and the bot posts a new version that keeps what was agreed.
- Uses your design. Paste a GitHub repo link and it designs with that repo's
design/DESIGN.md. - Speaks to developers. Real routes and proposed endpoints live in
DEV:comments; prototype-only scaffolding is markedPROTOTYPE ONLY. - Ships as a PR. Say "approved, open the PR" and it commits
design/prototypes/<feature>/index.htmlplus anintent.mdon a new branch. - Stateless. No database: the Slack thread is the history, the last attached
.htmlis the current version, and the last GitHub link is the repo.
Slack mention / thread reply
→ slack/app.ts routes the event
→ slack/turn.ts one turn: load thread, read DESIGN.md, run the agent, post the result
→ slack/thread.ts history + current prototype + repo, all from the thread
→ github/files.ts design/DESIGN.md from the linked repo
→ agent/agent.ts Mastra agent with skill.md + template.html as instructions
→ agent/tools.ts write_prototype · edit_prototype · open_pull_request
→ files.uploadV2 the new .html in the thread (or a text reply)
src/
index.ts validates config, starts the Slack app, graceful shutdown
config.ts every environment variable, in one place, and its validation
log.ts JSON logs
slack/
app.ts Bolt app and event handlers
thread.ts reads the thread: history, current prototype, linked repo
turn.ts one bot turn, end to end
agent/
agent.ts runs the Mastra agent for a turn
tools.ts write_prototype, edit_prototype, open_pull_request
types.ts shared types
instructions.ts loads skill.md + template.html (re-read every turn)
skill.md how the bot works and the rules prototypes follow
template.html working Alpine + Tailwind prototype the model adapts
github/
client.ts GitHub App auth (JWT → installation token)
files.ts read repo files, find the repo linked in the thread
pull-request.ts branch + single commit + PR
prototype/
form-shim.ts makes forms work in Slack's sandboxed preview
edits.ts exact, all-or-nothing edits to the prototype
test/ deterministic tests, no network (Slack and GitHub are faked)
diagnostics/
slack-sandbox-probe.html measures what Slack's preview allows (open it in Slack)
docs/
index.md documentation home
guides/ the way of working: your design guide (more coming)
setup/ Slack app, GitHub App, model
install/ Docker, Docker Compose, Render
reference/ configuration, security, observability, troubleshooting
Dockerfile the image (node 24 slim, non-root, /healthz)
docker-compose.yml run it on any server
render.yaml Render blueprint (same Dockerfile)
slack-manifest.yaml Slack app manifest (annotated: what to change, what to keep)
examples/DESIGN.md template for your design guide
brand/ icon for the Slack app, logo, colors
.github/workflows/ CI, and image release to GHCR on v* tags
-
Create the Slack app from
slack-manifest.yaml. 5 min -
Create the GitHub App (optional: design guide and pull requests). 5 min
-
Choose a model and get its API key.
-
Configure and run:
cp .env.example .env # fill it in: docs/reference/configuration.md docker compose up -d # or docker run, or Render docker compose logs -f # wait for {"msg":"ready",...}
Guides: Docker · Docker Compose · Render
-
Invite the bot to a channel (
/invite @twd-design) and mention it.
Something not working? Troubleshooting.
npm install
npm run dev # Node 24+, restarts on code changes
npm run typecheck
npm test # node:test, no network, about 2 secondsThe tests cover the plumbing that fails silently when it breaks: reading the thread, edits to the prototype, the form shim, GitHub App auth, the pull request, and the turn lifecycle (one turn per thread, the turn limit, graceful shutdown). The model's output is not tested here: that is the job of evals.
- Configuration: environment variables only, validated at startup. Reference: docs/reference/configuration.md.
- Security and data: nothing is stored; what goes where is in docs/reference/security.md.
- Health check:
GET /healthzonPORT(3000), in both Socket Mode and HTTP mode. - Logs: one JSON object per line. Each bot turn logs duration, tools used and token usage.
- Shutdown: on
SIGTERMthe bot stops taking turns and lets running ones finish (SHUTDOWN_TIMEOUT_MS, 60 s) before exiting. - State: none. Restart, redeploy or scale down at any time; the threads hold everything.
MIT © BRIKEV