Vibecoding Malware & Monsters

So you want to contribute to Malware & Monsters using an AI coding agent. This guide walks you through the entire process — from cloning the repo to getting your PR merged — without assuming you’re using any specific agent.

The Vibecoding Loop

Contributing with an AI agent isn’t about typing code. It’s a conversation. You set direction and verify results; the agent explores the codebase and implements changes. This is vibecoding — and it’s a genuinely different skill from coding.

The mental model is simple: you are the strategist, the agent is the implementer. You don’t need to know how to write Quarto markdown or configure a Lua filter. You need to understand what the project needs and be able to tell when the agent is delivering it correctly. Think of it like commissioning work: you describe the outcome, the agent figures out how to get there, and you check the result before signing off.

What a session actually looks like

Here’s what happens when you sit down to work on an issue. This isn’t abstract — it’s the literal sequence of what you’ll be doing:

  1. You open your agent and orient it. You tell it what issue you’re working on. Paste the issue description, or summarize what needs to happen. The agent needs to understand what “done” looks like before it starts exploring the codebase. (How you do this depends on the tool — see Section 2.)
  2. The agent explores. It reads files. It searches the codebase. It figures out what’s relevant and what isn’t. From your side, you’ll see it reading files and running searches. This is normal — let it work. Don’t rush it to start making changes. An agent that explores first makes far fewer mistakes than one that dives in blind.
  3. The agent proposes or starts implementing. It tells you what it plans to do, or just starts doing it. This is the moment you start paying close attention. Read what it’s doing. Does it match what the issue asked for? Is it changing things it shouldn’t? Is it taking a simpler or more complex path than you expected?
  4. You give feedback. This is your main job. “That looks right, keep going.” Or: “Wait — that file isn’t the right place for this.” Or: “The issue asked for X but you’re doing Y.” The agent adjusts and continues. You don’t need to know the right answer yourself — you just need to spot when something’s off.
  5. You verify the result. The agent says it’s done. Don’t take its word for it. Build the project (make quick). Look at the rendered output. Check that links work, formatting renders correctly, and the change actually does what the issue asked for.
  6. You loop back or finish. If something’s wrong, go back to step 4 with specific feedback about what’s broken. If it’s right, commit and move on.

Steps 4-6 repeat many times within a single session. A typical contribution might run through that loop 5–15 times before it’s ready to commit. The whole thing feels less like programming and more like directing.

Your job vs the agent’s job

Be clear about the division of labour. The most common mistake new vibecoders make is either doing too much (writing code themselves when the agent can do it) or too little (trusting the agent without checking its work).

Your job:

  • Understand what the issue is asking for
  • Tell the agent what you want at the start of the session
  • Read and review what the agent does as it goes
  • Catch mistakes before they get committed
  • Verify the output actually works by building and looking at it

The agent’s job:

  • Read and understand the relevant parts of the codebase
  • Figure out what files need changing and how
  • Write the actual code and content
  • Run builds and check for errors
  • Explain what it did and why

How to know when to intervene

The agent will sometimes go in the wrong direction. It won’t always be obvious — agents don’t hesitate or hedge. Here are the signs to watch for:

  • It’s changing files you didn’t ask about. A small issue shouldn’t touch 10 files. If the scope is creeping, ask why before it goes further.
  • It hasn’t read the relevant files before changing them. If it’s editing a file without having read it first, it’s guessing. Tell it to read the file first.
  • It’s confident but wrong. Agents state incorrect file paths or non-existent functions with the exact same tone as correct ones. Anything that sounds specific — a file path, a function name, a line number — verify it actually exists before you trust it. (See “Agent hallucination” in Common Pitfalls.)
  • The solution is getting complicated. If you started with a simple issue and the agent is building something elaborate, something’s gone sideways. Ask it to step back and reconsider the simplest path to the goal.
  • It says “done” but you haven’t verified. Never accept “done” without building and checking the output yourself. Every time.

1. Prerequisites

Before you start, you need:

  • A GitHub account with collaborator access to the malware-and-monsters repository — or a fork, if you don’t have push access
  • Git installed locally
  • Quarto (version 1.4+) — install from quarto.org
  • An AI coding agent — Claude Code, Codex, Gemini CLI, Antigravity, or any agent capable of reading files and running commands in your terminal

Verify your setup:

$ git --version
$ quarto --version

You do not need LaTeX unless you want to build PDFs. HTML-only builds work fine for development and are much faster.

2. Working With Your Agent

Every agent has its own way of starting a session, loading context, and iterating. This section covers the workflow — how you actually use each tool to run the vibecoding loop on Malware & Monsters. Installation is covered in Prerequisites.

The one thing that’s the same across all tools: your agent needs to have read the project rules file before it starts making changes. This file contains the project’s formatting rules, link conventions, build commands, and workflow expectations. If the agent hasn’t read it, it will repeat the same mistakes every session. How each tool loads it is different — that’s what this section is about.

Claude Code

Claude Code is terminal-based. You open it in the repo directory and have a conversation. It reads files, makes changes, and runs commands — all in your terminal, in real time.

Starting a session:

$ cd malware-and-monsters
$ claude

Claude Code reads CLAUDE.md automatically when it starts. No configuration needed — it already knows the project rules before you type your first message.

Running the loop:

Tell it what issue you’re working on. Describe what you want. Watch it explore — you’ll see it reading files and searching the codebase before it starts changing anything. When it proposes changes, read them. Give feedback. When it says it’s done, run make quick yourself and check the rendered output.

Claude Code is well-suited for this repo because the entire build and validation cycle is command-line driven. It can run builds, check for errors, and iterate — all without you leaving the terminal.

End of session: Context is gone when you close the terminal. If you come back later, start a new session and tell the agent what issue you’re working on again. It has no memory of previous sessions.

Codex

Codex is OpenAI’s terminal-based coding agent. It works similarly to Claude Code but with a different interaction style — it tends to lay out a plan before executing, and walks through changes step by step rather than making them all at once.

Codex natively reads an AGENTS.md file from the project root (the git root directory). If one doesn’t exist in the repo, create one before your first session. It doesn’t need to be long — the key conventions are in Section 3: formatting rules, link conventions, and build commands. Write those down in AGENTS.md and Codex will pick them up automatically. Keep it out of version control if you wrote it yourself; if the project ships one later, use that instead.

Starting a session:

$ cd malware-and-monsters
$ codex

Running the loop:

Describe the issue. Codex will typically propose a plan first — read it, check it makes sense, then approve. It executes step by step. This makes it easier to catch wrong turns early: if the plan looks off, you can redirect before any code gets written. Review each step as it goes, and verify the final output with make quick.

End of session: Stateless, same as Claude Code. Re-orient at the start of each new session.

Gemini CLI

Gemini CLI is Google’s open-source terminal coding agent. It reads a context file called GEMINI.md for project rules. It also has a built-in command to generate one for you — no manual writing required.

Starting a session:

$ cd malware-and-monsters
$ gemini

Once you’re in, run /init. This analyses the repo and generates a GEMINI.md tailored to the project. Review what it produces — add or correct anything based on the conventions in Section 3. Gemini CLI then reads GEMINI.md automatically from that point on. If the project changes significantly, run /init again or use /memory refresh to reload.

Running the loop:

Describe the issue. Gemini CLI is good at exploring — it’ll read files and map out the codebase before it starts. Be explicit about what you want changed: “Edit this file to do X” is clearer than “fix the issue.” Review its changes as it goes, and verify with make quick before you commit.

End of session: Stateless. Re-orient each session.

Antigravity

Antigravity is Google’s agent-first IDE — a VS Code fork built for multi-agent workflows. The workflow here is structurally different from the terminal agents: instead of a single back-and-forth conversation, you define a mission and agents produce Artifacts (plans, task lists, file diffs) as intermediate outputs that you review before they write code. The Artifact review step is where you do your strategist work — it’s explicit and visible.

Starting a session:

Open the repo in Antigravity. Make sure the project rules file is open in the editor so the agents can see it.

Running the loop:

  1. Start a mission in the Manager panel. Your mission description is your issue — paste it or summarize it. Tell the agents to follow the project conventions.
  2. Review Artifacts. Before any code gets written, the agents produce Artifacts — plans, task breakdowns, file lists. This is where you check that the approach matches the issue. If the plan looks wrong, redirect here. It’s much easier to fix a plan than to fix code after the fact.
  3. Let it implement. Once the plan looks right, the agents write the code. Monitor progress in the Manager panel.
  4. Verify. Build with make quick and check the rendered output, same as any other tool.

End of session: Missions persist in Antigravity, so you have more continuity between sessions than with the terminal agents. But always review your mission and the current state before picking up where you left off.

3. Repo Orientation

The repo is a Quarto documentation project. Everything renders to a website. Here’s what matters:

malware-and-monsters/
├── players-handbook/     # Player documentation (13 chapters)
├── im-handbook/          # Incident Master documentation (15 chapters)
│   └── resources/
│       ├── scenario-cards/   # All scenario cards (the bulk of the content)
│       ├── malmon-details/   # Malware creature profiles
│       └── practical-tools/  # IM tools, templates, guides
├── slides/               # RevealJS presentations
├── shared/               # Shared filters, styles, JS, assets
├── scripts/              # Automation scripts
├── docs/                 # Developer docs (GitHub-only, not rendered to site)
├── _quarto.yml           # Site navigation and build config
├── Makefile              # Build system
└── CLAUDE.md             # Project rules (read this first)

Building

Two equivalent approaches — pick whichever your agent handles better:

# Full build (HTML + PDF + slides)
$ quarto render

# Fast development build (HTML + slides only, no PDFs)
$ make quick

# Watch mode — auto-rebuilds on file changes
$ quarto preview

Check dependencies before your first build:

$ make check-deps

Key conventions

  • All content files are .qmd (Quarto Markdown)
  • File names use kebab-case: my-new-content.qmd
  • Navigation links use .html extensions (not .qmd) — Quarto renders .qmd to .html
  • Always add a blank line before lists in .qmd files — Quarto requires it

4. Claiming Work

The biggest risk when multiple people contribute to an open project is duplicate work. Malware & Monsters uses a GitHub Project board to coordinate — it’s the single place to see what’s being worked on, what’s ready to pick up, and what’s done. Before you start anything, check it.

Picking an issue

Issues move through these statuses on the project board:

Status What it means
📋 Backlog Not yet prioritised
🎯 Ready Prioritised and scoped — good candidates to pick up
🚧 In Progress Someone is actively working on it
👀 Review/Testing Work is done, waiting for review
✅ Done Completed and merged
🔒 Blocked Can’t proceed — needs something resolved first

Pick something in ‘🎯 Ready’ status. If nothing in ‘🎯 Ready’ appeals to you, ‘📋 Backlog’ items are fair game too — but check with the project maintainers first.

Every issue is also labeled with an effort estimate — a vibecoding metric that measures how many conversations with your agent the work typically takes, not how difficult it is. A conversation is one continuous session with your agent, from when you start it to when you close it. effort: quick is 1–2 conversations, effort: standard is 3–5, effort: extended is 5+. Use it to plan your time: a quick issue is something you can close in a single session. An extended issue means coming back across multiple sessions.

Claiming it

When you find an issue you want to work on, do these three things before you write a line of anything:

  1. Assign the issue to yourself on GitHub. This is the primary signal that the issue is taken. If it’s already assigned to someone else, it’s not yours to work on.
  2. Set the status to ‘🚧 In Progress’ on the project board. This moves it out of the ‘🎯 Ready’ column so no one else picks it up.
  3. Create a branch named after the issue or your work (e.g., docs/my-contribution or feature/new-scenario).
$ git checkout -b docs/my-contribution

Keeping it updated

The project board is only useful if it reflects reality. Update the status as you go:

  • Blocked? Set it to ‘🔒 Blocked’ and leave a comment on the issue explaining what’s in the way.
  • Done coding, needs review? Set it to ‘👀 Review/Testing’ when you open your PR.
  • Abandoning it? Unassign yourself and set it back to ‘🎯 Ready’ so someone else can pick it up. Leave a comment if there’s anything useful for the next person to know.

A note on statefulness

Tell your agent what issue you’re working on at the start of each session. Agent sessions are stateless — they don’t remember previous conversations. The issue number and a short description of where you left off is all you need.

5. Branch Workflow

Malware & Monsters uses a testing branch as a staging environment — changes pushed there auto-deploy to a password-protected preview site before going to production. The workflow is:

Your feature branch
        │
        ▼
   testing branch  →  auto-deploys to preview site
        │                (password-protected)
        ▼
      PR to main  →  production site

Step by step

  1. Work on your feature branch. Make changes, build locally with make quick, verify things look right.
  2. Merge your feature branch into testing. This triggers a GitHub Actions deployment to the preview site. The preview site is password-protected (use password ‘malmon-testing-2025’).
  3. Verify on the preview site. Check that your changes render correctly. Test navigation, links, and formatting in a real browser.
  4. Open a PR from testing to main. The main branch is protected — no direct merges. Open a Pull Request on GitHub, get it reviewed, and merge from there. This deploys to the production site at malwareandmonsters.com.

The project uses squash merges — your commits get squashed into a single commit on merge.

Git hooks

Run this once after cloning the repo:

$ ./scripts/setup-git-hooks.sh

This installs a pre-commit hook that warns you if you’re about to commit directly to main. It’s a safety net, not a hard block — you can override it if you genuinely need to.

6. Submitting Contributions

When your work is ready:

  1. Verify the build passes:

    $ make quick```bash
cp CLAUDE.md GEMINI.md

For a full check (build, serve, screenshots, and issue detection): bash $ ./scripts/dev-workflow.sh test

  1. Run link validation:

    $ python3 scripts/validate-links.py

  2. Create a Pull Request on GitHub and include:

    • What issue this addresses
    • What changed and why
    • A note that you’ve verified the build passes

  3. Update the project board. Set your issue to ‘👀 Review/Testing’. This tells everyone the work is done on your end and is waiting for review.

Reviewers will look at: - Does the build pass? - Are links and formatting correct? - Is the content accurate and consistent with the existing project? - Does it follow the project conventions?

7. Common Pitfalls

These are the mistakes that show up repeatedly. Your agent may make them — it’s your job to catch them.

Quarto formatting

Always put a blank line before a list:

<!-- ❌ Breaks rendering -->
Here are the steps:
- Step one
- Step two

<!-- ✅ Correct -->
Here are the steps:

- Step one
- Step two

For line breaks within a paragraph, end the line with two trailing spaces (not a single space, not a <br>). The two spaces are invisible but required:

<!-- ❌ No line break — renders as one continuous line -->
First line
Second line

<!-- ✅ Two trailing spaces after "First line" force a line break -->
First line··
Second line

(The ·· above represents two spaces — they won’t be visible in your editor.)

Deleting files

If you delete a .qmd file, you must remove it from the root _quarto.yml. All site navigation — both handbooks, slides, and standalone pages — is controlled from this single config file. Search it for the filename before deleting; it may appear in the render list, the sidebar, or both.

Don’t just delete the file and trust the build to tell you what broke. The GitHub Actions build will fail, but the error message won’t always point you back to _quarto.yml.

Theming and styling

Do not touch colors, themes, or visual styling unless explicitly asked to. The project has a carefully maintained visual design. If something looks wrong, the fix is almost always in the content or structure — not the CSS.

Agent hallucination

AI agents can confidently make up file paths, function names, or navigation structures that don’t exist. Always verify that files the agent references actually exist before trusting its output. If the agent says “edit shared/filters/my-filter.lua”, check that the file exists first.

Session context loss

Agent sessions are stateless. If you close and reopen your agent, it has zero memory of what you were doing. Before starting a session:

  • Make sure the project rules file is loaded into your agent’s context (see Section 2)
  • Tell the agent what issue you’re working on

Have questions? Open a GitHub Discussion or drop into the HackBack Discord.