From 6e34eb61811e2709997a749e922e07effc4c6685 Mon Sep 17 00:00:00 2001 From: Willem van den Ende Date: Tue, 5 May 2026 18:31:54 +0100 Subject: [PATCH] Add guidance on monorepo, brief and yaks --- AGENTS.md | 41 ++++++++++------------------------------- 1 file changed, 10 insertions(+), 31 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index df7a4af..59c3ff6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,40 +1,19 @@ # Agent Instructions -This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started. +This project has a *zero defects policy*. +When you are unsure about something, ALWAYS ask the user. -## Quick Reference +# Planning -```bash -bd ready # Find available work -bd show # View issue details -bd update --status in_progress # Claim work -bd close # Complete work -bd sync # Sync with git -``` +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'. -## Landing the Plane (Session Completion) +# Building -**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds. +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. -**MANDATORY WORKFLOW:** +# Development +Always fix failing tests, credo issues and format isseus. -1. **File issues for remaining work** - Create issues for anything that needs follow-up -2. **Run quality gates** (if code changed) - Tests, linters, builds -3. **Update issue status** - Close finished work, update in-progress items -4. **PUSH TO REMOTE** - This is MANDATORY: - ```bash - git pull --rebase - bd sync - git push - git status # MUST show "up to date with origin" - ``` -5. **Clean up** - Clear stashes, prune remote branches -6. **Verify** - All changes committed AND pushed -7. **Hand off** - Provide context for next session - -**CRITICAL RULES:** -- Work is NOT complete until `git push` succeeds -- NEVER stop before pushing - that leaves work stranded locally -- NEVER say "ready to push when you are" - YOU must push -- If push fails, resolve and retry until it succeeds +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.