MazeBreak Trello
Sprint Board Automation

Getting Started

Prerequisites

• Node.js 18+ — required for modern JavaScript features. Verify with node --version.
• npm — ships with Node.js. Used to install dependencies.
• Trello Account — with access to create boards and workspaces.
• Trello API Key & Token — obtained from the Trello Power-Up admin portal (see Configuration below).

Installation

Clone the repository and install dependencies.

$ git clone https://github.com/RCushmaniii/mazebreak-trello.git
$ cd mazebreak-trello
$ npm install

This installs two dependencies:

• axios — HTTP client for Trello API calls
• dotenv — loads environment variables from .env

Create Your .env File

Create a .env file in the project root with your Trello credentials.

TRELLO_API_KEY=your_api_key_here
TRELLO_SECRET_KEY=your_secret_key_here
TRELLO_TOKEN=your_token_here

Configuration

The script requires three environment variables to authenticate with the Trello API. All three are loaded from the .env file at the project root.

How to Get Your Credentials

1. Go to https://trello.com/power-ups/admin
2. Click "New" to create a new Power-Up integration (or select an existing one).
3. Fill in basic details:
   • Name: MazeBreak (or any name you prefer)
   • Workspace: Select the workspace you want to use
   • Iframe connector URL: Your deployment URL + /connector (e.g., https://your-domain.com/connector)
4. After creating, you will see your API Key and Secret on the Power-Up details page.
5. To generate a Token, click the link on the Power-Up page that says "Token" or navigate to:
   url Copy

   https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=YOUR_API_KEY

6. Authorize the app when prompted. Copy the token displayed on the screen.
7. Paste all three values into your .env file.

Running the Script

With your .env configured, run the board builder.

$ node trelloSetup.js

What It Creates

The script provisions the following resources in order via the Trello API:

1. Workspace — "MazeBreak Development"
2. Board — "MazeBreak – Core Development" inside that workspace
3. Lists — 4 workflow columns for card progression
4. Labels — 8 color-coded labels for categorization
5. Cards — 10 fully-specified Sprint 0 cards with dependency prefixes
6. Checklists — Execution checklists, acceptance tests, and Definition of Done on every card
7. Comments — Dev Notes comment on every card with architecture guidance

Expected Output

Starting MazeBreak Sprint 0 Trello build (idempotent)...

✓ Workspace Created: MazeBreak Development
✓ Board Created: MazeBreak – Core Development
✓ List Created: 🧪 Sprint 0 – Combat Prototype
✓ List Created: 🔜 Sprint 1 – Core Loop
✓ List Created: 📦 Backlog
✓ List Created: ✅ Done
✓ 8 Labels Created

✓ [S0-00] Gate Rules — 2 checklists, dev notes, DoD
✓ [S0-01] Foundation Setup — 2 checklists, dev notes, DoD
✓ [S0-02] InputController — 3 checklists, dev notes, DoD
✓ [S0-03] CombatManager — 3 checklists, dev notes, DoD
✓ [S0-04] DamageResolver — 3 checklists, dev notes, DoD
✓ [S0-05] Zombie Enemy — 3 checklists, dev notes, DoD
✓ [S0-06] Health System — 3 checklists, dev notes, DoD
✓ [S0-07] Basic HUD — 3 checklists, dev notes, DoD
✓ [S0-08] Feel Tuning — 3 checklists, dev notes, DoD
✓ [S0-09] Exit Gate — 2 checklists, dev notes, DoD

✓ Sprint 0 PRODUCTION++ complete.
   Safe to re-run (idempotent).

Re-Running

The script is fully idempotent. If you run it again, it will detect all existing resources and skip creation. You will see recycling indicators instead of creation confirmations. See Idempotency for details.

Board Structure

Lists

The script creates 8 workflow lists that represent the full card lifecycle.

Labels

8 color-coded labels categorize cards by domain. Cards can have multiple labels.

Cards — The Sprint 0 Dependency Chain

10 cards form a strict dependency chain. Each card's title carries a [S0-##] prefix that encodes its position. You must complete earlier cards before starting later ones.

[S0-00] Gate Rules
  |
  v
[S0-01] Foundation Setup
  |
  v
[S0-02] InputController
  |
  v
[S0-03] CombatManager ← depends on S0-01 + S0-02
  |
  v
[S0-04] DamageResolver ← depends on S0-01 + S0-03
  |
  v
[S0-05] Zombie Enemy ← depends on S0-03 + S0-04
  |
  v
[S0-06] Health System ← depends on S0-04 + S0-05
  |
  v
[S0-07] Basic HUD
  |
  v
[S0-08] Feel Tuning
  |
  v
[S0-09] Exit Gate — Ship / No-Ship decision

Card Specification

Every card created by the script is a complete work specification. No card is a stub or placeholder. Here is what each card includes.

Title with Dependency Prefix

Every card title follows the pattern [S0-##] CARD TITLE. The prefix encodes the card's position in the dependency chain, making sprint order visible at a glance in the Trello board view.

[S0-03] CARD 3 — CombatManager (Server Authority Core)

Description with Dependencies

Every card description contains:

• Objective — what this card achieves
• Depends On — which cards must be finished first
• Technical specification — files to create, APIs to implement, folder structures
• Completion Criteria — how to know when this card is done
• Dependency Notes — appended automatically at the bottom of every card description

Execution Checklist

An ordered list of implementation steps. Work through these top-to-bottom. Each item is a concrete action, not a vague goal.

Execution Checklist (Ordered)
[ ] Create AttackRequest RemoteEvent in ReplicatedStorage/Remotes
[ ] Create InputController.client.lua in StarterPlayerScripts
[ ] Bind attack input (UIS or CAS) and fire AttackRequest:FireServer()
[ ] Add local throttle to prevent spam FireServer (visual only)
[ ] Test: clicks fire instantly with no console errors

Acceptance Tests

Cards 2 through 8 include an explicit acceptance test checklist. These are the verification criteria that must pass before the card can move to Done.

Acceptance Tests
[ ] Spam click does NOT freeze client
[ ] Remote fires instantly on input
[ ] No client damage calculations exist

Definition of Done (Global)

A 9-item quality checklist attached to every single card. This is the universal quality bar. No card is "done" until all 9 items are checked.

[ ] Runs in Studio with zero errors in Output
[ ] Server-authoritative rules not violated (no client damage outcomes)
[ ] No gameplay logic placed in Workspace
[ ] Code is modular (Managers/Systems), no spaghetti in random scripts
[ ] No magic numbers: key constants centralized + named
[ ] Basic logging added where it helps debugging (not spammy)
[ ] Edge cases handled (nil targets, dead targets, missing humanoid)
[ ] Performance sanity: no runaway loops / no heavy per-frame work
[ ] Quick manual test performed and recorded in checklist notes

Dev Notes (Comment)

Every card receives a comment with architecture guidance and common pitfalls. These are attached as Trello card comments, not part of the checklist, so they serve as persistent reference without cluttering the task items.

DEV NOTES (Architecture & Pitfalls)
- Keep CombatManager as an orchestrator: validate + route to systems.
- Don't subtract health in CombatManager. Always go through DamageResolver.
- If you add effects, don't hardcode them here — emit events/hooks later.

Dependency Notes

Appended to the bottom of every card description. Lists which cards must be finished before this one can start.

----
## Dependency Notes
- Finish: S0-01 before this
- Finish: S0-02 before this

Idempotency

The script is designed to be run multiple times without creating duplicates or corrupting existing data. This is the core engineering principle behind MazeBreak Trello.

How It Works

Every resource creation uses a find-or-create pattern:

1. Query — before creating any resource, the script fetches the list of existing resources of that type (workspaces, boards, lists, labels, cards, checklists, checklist items, comments).
2. Match — it searches the existing resources for a match by name (and color, for labels).
3. Skip or Create — if a match is found, the existing resource ID is returned and creation is skipped. If no match is found, the resource is created fresh.

async function findOrCreateCard(listId, name, desc, idLabels = []) {
  // 1. Query existing cards in this list
  const res = await api.get(`/lists/${listId}/cards`, { params: params() });

  // 2. Match by name
  const existing = res.data.find((c) => c.name === name);

  // 3. Skip if found
  if (existing) {
    console.log("♻  Card exists:", name);
    return existing.id;
  }

  // 4. Create if not found
  const created = await api.post("/cards", null, {
    params: params({ idList: listId, name, desc, idLabels: idLabels.join(",") }),
  });
  console.log("✓ Card Created:", name);
  return created.data.id;
}

What This Means in Practice

• Safe to re-run — run node trelloSetup.js any time. Nothing breaks.
• No duplicates — you will never get two copies of the same card, list, or label.
• Recovers from partial runs — if the script fails mid-way (network error, rate limit), re-run it. It picks up where it left off.
• Manual edits preserved — if you manually add notes, move cards, or check items, the script does not overwrite them. It only checks for existence by name.

Idempotent Resources

Trello Power-Up

MazeBreak Trello includes a minimal Power-Up connector that allows you to register the project as a Trello Power-Up. This enables API key registration and integration with the Trello Power-Up ecosystem.

The Connector

The connector is a static HTML file served at /connector. It loads the Trello Power-Up client library and calls TrelloPowerUp.initialize({}) with an empty capability set.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>MazeBreak — Trello Power-Up Connector</title>
</head>
<body>
  <script src="https://p.trellocdn.com/power-up.min.js"></script>
  <script>
    TrelloPowerUp.initialize({});
  </script>
</body>
</html>

How to Register the Power-Up

1. Deploy MazeBreak Trello to a public URL (e.g., via Vercel, Netlify, Railway, or any static hosting).
2. Go to https://trello.com/power-ups/admin.
3. Click "New" to register a new Power-Up.
4. Set the Iframe connector URL to your deployed URL plus /connector:
   example

   https://your-domain.com/connector

5. Save. Your API key and secret will be displayed on the Power-Up admin page.
6. Copy those values into your .env file as TRELLO_API_KEY and TRELLO_SECRET_KEY.
7. Generate a token (see Configuration) and add it as TRELLO_TOKEN.

Customization

The entire board specification lives in a single file: trelloSetup.js. All card content, checklists, labels, and structure are defined in plain JavaScript arrays and objects. No external config files, no database. Change the code, re-run the script.

Adding a New Card

Add a new entry to the array returned by the sprint0Spec() function. Follow the existing pattern:

// 1. Add a new ID constant in CARD_IDS
const CARD_IDS = {
  // ...existing IDs...
  C10: "S0-10",  // new card
};

// 2. Add the card spec inside sprint0Spec()
{
  id: CARD_IDS.C10,
  title: "CARD 10 — Your New Feature",
  dependsOn: [CARD_IDS.C8],  // must finish C8 first
  labels: [L.Critical, L.Server],
  desc: block([
    "## Objective",
    "Describe what this card achieves.",
    "",
    "## Depends On",
    `- ${CARD_IDS.C8}`,
    "",
    "## Completion Criteria",
    "- Define when this card is done",
  ]),
  checklists: [
    {
      title: "Execution Checklist (Ordered)",
      items: [
        "Step 1",
        "Step 2",
        "Step 3",
      ],
    },
    {
      title: "Acceptance Tests",
      items: [
        "Test condition 1",
        "Test condition 2",
      ],
    },
  ],
  devNotes: block([
    "DEV NOTES (Architecture & Pitfalls)",
    "- Guidance for the developer.",
  ]),
}

Modifying the Definition of Done

The global Definition of Done is defined in the DEFINITION_OF_DONE array near the top of trelloSetup.js. Add, remove, or edit items as needed.

const DEFINITION_OF_DONE = [
  "Runs in Studio with zero errors in Output",
  "Server-authoritative rules not violated",
  "No gameplay logic placed in Workspace",
  "Code is modular (Managers/Systems)",
  "No magic numbers: key constants centralized",
  "Basic logging added where it helps debugging",
  "Edge cases handled (nil targets, dead targets)",
  "Performance sanity: no runaway loops",
  "Quick manual test performed and recorded",
  // Add your own items here:
  "Accessibility check: screen reader tested",
];

Changing Labels

Labels are created in the main() function. To add a new label, add a findOrCreateLabel call and reference the new label ID in your card specs.

const labelIds = {
  // ...existing labels...
  Testing: await findOrCreateLabel(boardId, "Testing", "lime"),
};

Trello supports these label colors: green, yellow, orange, red, purple, blue, sky, lime, pink, black.

Modifying Checklists

Each card's checklists array accepts any number of checklist objects. Each object has a title and an items array of strings.

checklists: [
  {
    title: "Execution Checklist (Ordered)",
    items: ["Step 1", "Step 2", "Step 3"],
  },
  {
    title: "Acceptance Tests",
    items: ["Test 1", "Test 2"],
  },
  {
    title: "Research Notes",    // add as many as you want
    items: ["Link 1", "Link 2"],
  },
]

Adding More Lists

Lists are created in main() with findOrCreateList(). Add new lists in the order you want them to appear on the board (Trello creates them left-to-right).

// Add new lists in left-to-right order
await findOrCreateList(boardId, "In Review");
await findOrCreateList(boardId, "Blocked");
await findOrCreateList(boardId, "QA Testing");

Version Control Workflow

Because the board spec is code, you get full version control on board changes.

# Edit the board spec
$ code trelloSetup.js

# Commit the change
$ git add trelloSetup.js
$ git commit -m "Add QA testing list and code review checklist"

# Push and re-run
$ git push
$ node trelloSetup.js