Gas Town Decoded

To use it effectively, I spend a long time producing FSD (functional specification documents) to exhaustively plan out new features or architecture changes. I'll pass those docs back and forth between gemini, codex/chatgpt-pro, and claude. I'll ask each one something similar to following (credit to https://github.com/Dicklesworthstone for clearly laying out the utility of this workflow, these next few quoted prompts are verbatim from his posts on x):

"Carefully review this entire plan for me and come up with your best revisions in terms of better architecture, new features, changed features, etc. to make it better, more robust/reliable, more performant, more compelling/useful, etc.

For each proposed change, give me your detailed analysis and rationale/justification for why it would make the project better along with the git-diff style changes relative to the original markdown plan".

Then, the plan generally iteratively improves. Sometimes it can get overly complex so may ask them to take it down a notch from google scale. Anyway, when the FSD doc is good enough, next step is to prepare to create the beads.

At this point, I'll prompt something like:

"OK so please take ALL of that and elaborate on it more and then create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid, with detailed comments so that the whole thing is totally self-contained and self-documenting (including relevant background, reasoning/justification, considerations, etc.-- anything we'd want our "future self" to know about the goals and intentions and thought process and how it serves the over-arching goals of the project.) Use only the `bd` tool to create and modify the beads and add the dependencies. Use ultrathink."

After that, I usually even have another round of bead checking with a prompt like:

"Check over each bead super carefully-- are you sure it makes sense? Is it optimal? Could we change anything to make the system work better for users? If so, revise the beads. It's a lot easier and faster to operate in "plan space" before we start implementing these things! Use ultrathink."

Finally, you'll end up with a solid implementation roadmap all laid out in the beads system. Now, I'll also clarify, the agents got much better at using beads in this way, when I took the time to have them create SKILLS for beads for them to refer to. Also important is ensuring AGENTS.md, CLAUDE.md, GEMINI.md have some info referring to its use.

But, once the beads are laid out then its just a matter of figuring out, do you want to do sequential implementation with a single agent or use parallel agents? Effectively using parallel agents with beads would require another chapter to this post, but essentially, you just need a decent prompt clearly instructing them to not run over each other. Also, if you are building something complex, you need test guides and standardization guides written, for the agents to refer to, in order to keep the code quality at a reasonable level.

Here is a prompt I've been using as a multi-agent workflow base, if I want them to keep working, I've had them work for 8hrs without stopping with this prompt:

EXECUTION MODE: HEADLESS / NON-INTERACTIVE (MULTI-AGENT) CRITICAL CONTEXT: You are running in a headless batch environment. There is NO HUMAN OPERATOR monitoring this session to provide feedback or confirmation. Other agents may be running in parallel. FAILURE CONDITION: If you stop working to provide a status update, ask a question, or wait for confirmation, the batch job will time out and fail.

  YOUR PRIMARY OBJECTIVE: Maximize the number of completed beads in this single session. Do not yield control back to the user until the entire queue is empty or a hard blocker (missing credential) is hit.

  TEST GUIDES: please ingest @docs/testing/README.md, @docs/testing/golden_path_testing_guide.md, @docs/testing/llm_agent_testing_guide.md, @docs/testing/asset_inventory.md, @docs/testing/advanced_testing_patterns.md, @docs/testing/security_architecture_testing.md
  STANDARDIZATION: please ingest @docs/api/response_standards.md @docs/event_layers/event_system_standardization.md

─────────────────────────────────────────────────────────────────────────────── MULTI-AGENT COORDINATION (MANDATORY) ───────────────────────────────────────────────────────────────────────────────

  Before starting work, you MUST register with Agent Mail:

  1. REGISTER: Use macro_start_session or register_agent to create your identity:
     - project_key: "/home/bob/Projects/honey_inventory"
     - program: "claude-code" (or your program name)
     - model: your model name
     - Let the system auto-generate your agent name (adjective+noun format)

  2. CHECK INBOX: Use fetch_inbox to check for messages from other agents.
     Respond to any urgent messages or coordination requests.

  3. ANNOUNCE WORK: When claiming a bead, send a message to announce what you're working on:
     - thread_id: the bead ID (e.g., "HONEY-2vns")
     - subject: "[HONEY-xxxx] Starting work"

─────────────────────────────────────────────────────────────────────────────── FILE RESERVATIONS (CRITICAL FOR MULTI-AGENT) ───────────────────────────────────────────────────────────────────────────────

  Before editing ANY files, you MUST:

  1. CHECK FOR EXISTING RESERVATIONS:
     Use file_reservation_paths with your paths to check for conflicts.
     If another agent holds an exclusive reservation, DO NOT EDIT those files.

  2. RESERVE YOUR FILES:
     Before editing, reserve the files you plan to touch:
     ```
     file_reservation_paths(
       project_key="/home/bob/Projects/honey_inventory",
       agent_name="",
       paths=["honey/services/your_file.py", "tests/services/test_your_file.py"],
       ttl_seconds=3600,
       exclusive=true,
       reason="HONEY-xxxx"
     )
     ```

  3. RELEASE RESERVATIONS:
     After completing work on a bead, release your reservations:
     ```
     release_file_reservations(
       project_key="/home/bob/Projects/honey_inventory",
       agent_name=""
     )
     ```

  4. CONFLICT RESOLUTION:
     If you encounter a FILE_RESERVATION_CONFLICT:
     - DO NOT force edit the file
     - Skip to a different bead that doesn't conflict
     - Or wait for the reservation to expire
     - Send a message to the holding agent if urgent

─────────────────────────────────────────────────────────────────────────────── THE WORK LOOP (Strict Adherence Required) ───────────────────────────────────────────────────────────────────────────────

* ACTION: Immediately continue to the next bead in the queue and claim it

  For every bead you work on, you must perform this exact cycle autonomously:

   1. CLAIM (ATOMIC): Use the --claim flag to atomically claim the bead:
      ```
      bd update  --claim
      ```
      This sets BOTH assignee AND status=in_progress atomically.
      If another agent already claimed it, this will FAIL - pick a different bead.

        WRONG: bd update  --status in_progress  (doesn't set assignee!)
        RIGHT: bd update  --claim                (atomic claim with assignee)

   2. READ: Get bead details (bd show ).

   3. RESERVE FILES: Reserve all files you plan to edit (see FILE RESERVATIONS above).
      If conflicts exist, release claim and pick a different bead.

   4. PLAN: Briefly analyze files. Self-approve your own plan immediately.

   5. EXECUTE: Implement code changes (only to files you have reserved).

   6. VERIFY: Activate conda honey_inventory, run pre-commit run --files , then run scoped tests for the code you changed using ~/run_tests (test URLs only; no prod secrets).
       * IF FAIL: Fix immediately and re-run. Do not ask for help as this is HEADLESS MODE.
       * Note: you can use --no-verify if you must if you find some WIP files are breaking app import in security linter, the goal is to help catch issues to improve the codebase, not stop progress completely.

   7. MIGRATE (if needed): Apply migrations to ALL 4 targets (platform prod/test, tenant prod/test).

   8. GIT/PUSH: git status → git add only the files you created or changed for this bead → git commit --no-verify -m " " → git push. Do this immediately after closing the bead. Do not leave untracked/unpushed files; do not add unrelated files.

   9. RELEASE & CLOSE: Release file reservations, then run bd close .

  10. COMMUNICATE: Send completion message via Agent Mail:
      - thread_id: the bead ID
      - subject: "[HONEY-xxxx] Completed"
      - body: brief summary of changes

  11. RESTART: Check inbox for messages, then select the next bead FOR EPIC HONEY-khnx, claim it, and jump to step 1.

─────────────────────────────────────────────────────────────────────────────── CONSTRAINTS & OVERRIDES ───────────────────────────────────────────────────────────────────────────────

   * Migrations: You are pre-authorized to apply all migrations. Do not stop for safety checks unless data deletion is explicit.
   * Progress Reporting: DISABLE interim reporting. Do not summarize after one bead. Summarize only when the entire list is empty.
   * Tracking: Maintain a running_work_log.md file. Append your completed items there. This file is your only allowed form of status reporting until the end.
   * Blockers: If a specific bead is strictly blocked (e.g., missing API key), mark it as blocked in bd, log it in running_work_log.md, and IMMEDIATELY SKIP to the next bead. Do not stop the session.
   * File Conflicts: If you cannot reserve needed files, skip to a different bead. Do not edit files reserved by other agents.

  START NOW. DO NOT REPLY WITH A PLAN. REGISTER WITH AGENT MAIL, THEN START THE NEXT BEAD IN THE QUEUE IMMEDIATELY. HEADLESS MODE IS ON.

that's one reason I am less worried about him than some, although, I don't want to say that only to have something bad happen to him, that is, a form of complacency. Just because (say) Boltzmann and Cantor had useful insights along the way didn't mean people shouldn't have been looking to support them.

I think you have to remove an awful lot of what makes Gastown Gastown to find something sensible – at the minimum you need to restructure and simplify the roles, restructure the memory system, remove tmux, ...

The best bit about it was the agentic coding maturity model he presented. That was actually great.

I don't think it's at all like reading Dune. Dune is creative fiction, Gastown is. Oh ok wait, if you consider Gastown to be creative fiction then I guess I agree. As a software tool though I don't think this analogy works.

The difference between light-up arrows pointing the way "forward" for a car turning onto the expressway the wrong way, and doing so with the possibility humans might see and attempt to flag them down before they're too far to turn around.

People will make mistakes, and AI holding their hand and guiding them while they do it can have disastrous consequences.

But it's nice that the arrows will appear to also guide people going the right way I guess.