firehose/AGENTS.md

Agent Instructions

This project has a zero defects policy. When you are unsure about something, ALWAYS ask the user.

Communication

When creating yaks or working on features, always ask clarifying questions to ensure understanding. Ask questions one at a time to maintain clear communication and allow for focused discussion.

You run in a nono sandbox. Always ask the user to run commands that require privilege, like docker, sudo or package installation.

Repository structure

This is an Elixir monorepo with two parts:

firehose/
├── app/                    # Phoenix application (OTP app: :firehose)
│   ├── lib/firehose/       # Application logic
│   ├── lib/firehose_web/   # Web layer (controllers, live views, components)
│   ├── lib/firehose/blogs/ # Blog definitions (engineering, release notes)
│   ├── priv/blog/          # Markdown posts
│   └── mix.exs
├── blogex/                 # Blogex library (multi-blog engine)
│   ├── lib/
│   └── mix.exs
├── mise.toml               # Runtime versions (Elixir, Erlang, Node)
├── Dockerfile              # Deploy build; ARG pins must match mise.toml
├── scripts/check-pins.sh   # Verifies the pin sync; runs in `make check`
└── Makefile                # make (test, check) 

Two blogs are configured:

Toolchain pins

mise.toml and the Dockerfile ARG pins must agree; scripts/check-pins.sh (runs as part of make check) enforces this. When bumping versions, change both files in one commit. Upstream drift (newer Elixir/OTP/Debian releases) is reported by dokku-updates firehose check (dokku-maintenance repo). Upgrading pins or mix packages is largely unscripted: for such tasks, a Pi sub agent can be started in this directory — it reads this AGENTS.md and follows the zero-defects policy above.

Blog	Route	Description
Engineering	/blog/engineering	Main blog
Release Notes	/blog/releases	What's new in an app

Permissions

ALWAYS ask the user for permission when you want to add a fallback, or are unsure something work. The user can perform exploratory testing.

We have a zero defects policy, so never continue when there are errors, warnings or test failures, even when they are pre-existing. ALWAYS report these to the user and discuss an action plan with root cause analysis. (see TDD below).

Planning

we use yx for planning run yx --help to see options. Invoke when the user wants to make a plan, work on something for a plan or mentions 'yak' or 'yaks'.

yx list - shows open yaks yx add - adds yaks yx context "yak name" - adds human-readable description (pipe via stdin) yx show "yak name" - shows yak details including context

Building

This is a Phoenix Liveview monorepo, the blogging library is in blogex, the application is in 'app'. Use make to build and brief to find out more about mix.

Main make targets:

• make test
• make check - runs credo static analysis and suggests refactorings

Development

Always fix failing tests, credo issues and format isseus.

When developing new features, we apply TDD. Work Test-First, and Refactor when all tests are passing.

If you believe an issue is pre-existing, stop work, and have a conversation with the user on how to address the pre-existing issue, as well as how to prevent this in the future.