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)
└── Makefile                # make (test, check) 

Two blogs are configured:

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.