# 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.
