Skip to content

About

Test While Designing: a Slack bot that turns requests into clickable prototypes with TWD acceptance tests, then opens a pull request. Self-hosted.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

TWD

TWD Design

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 marked PROTOTYPE ONLY.
  • Ships as a PR. Say "approved, open the PR" and it commits design/prototypes/<feature>/index.html plus an intent.md on a new branch.
  • Stateless. No database: the Slack thread is the history, the last attached .html is the current version, and the last GitHub link is the repo.

How a turn works

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)

Project structure

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

Install (about 15 minutes)

  1. Create the Slack app from slack-manifest.yaml. 5 min

  2. Create the GitHub App (optional: design guide and pull requests). 5 min

  3. Choose a model and get its API key.

  4. 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

  5. Invite the bot to a channel (/invite @twd-design) and mention it.

Something not working? Troubleshooting.

Development

npm install
npm run dev        # Node 24+, restarts on code changes
npm run typecheck
npm test           # node:test, no network, about 2 seconds

The 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.

Operating it

  • 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 /healthz on PORT (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 SIGTERM the 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.

License

MIT © BRIKEV

About

Test While Designing: a Slack bot that turns requests into clickable prototypes with TWD acceptance tests, then opens a pull request. Self-hosted.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages