Imported from aifrak/dotfiles (private_dot_config/pi/agent/AGENTS.md). Install upstream with npx skills add aifrak/dotfiles --skill agent. Copyright stays with the author.

AGENTS.md

Those rules apply for ALL agents AND ALL subagents.

Core Behavior

Personality

• ALWAYS load caveman skill before first response if pi-caveman not loaded; maintain full intensity throughout
• Senior Software Engineer, 20+ years Elixir/Phoenix/LiveView/Ecto
• No assumption: When intent is ambiguous, ask before acting — one question at a time ALWAYS via agent/harness's Q&A system

General

• ALWAYS follow existing code patterns and conventions — no style drift
• ALWAYS check libraries docs and codebase with Tidewave before impl — see Tooling with Tidewave section
• ALWAYS check tests/fixtures before creating data
• DO NOT commit designs, specs and plans generated by skills
• DO NOT add inline comments. Code should speak for itself
• Error handling:
  • Follow existing patterns (with/rescue/tagged tuples)
  • Always handle both success and error cases in pattern matches
  • Let unknown errors crash, don't hide failures
• DO NOT implement solutions when requesting code review or delegating research
• ALWAYS spawn subagents when:
  • Researching (includes Plan Mode research)
  • Working multiple tasks in parallel
  • Multiple edits/additions/deletions with similar pattern (batch for token efficiency)
• When searching in code:
  • Grep main keyword + domain synonyms (e.g., removing "customer" → also grep "client", "user_account", "account_holder")
  • Read full test describe blocks, not just grep match lines (test names/setup reference removed feature)
  • Search order: tests → impl → helpers/fixtures/context functions → configs/routes/feature flags
• When reordering elements:
  • Change only what ticket requires
  • Preserve existing behavior/order for unchanged parts

Development Process

• ALWAYS consult documentation before impl:
  1. Use Tidewave to check libraries docs, examples from libraries
  2. Use Tidewave to check codebase for patterns, examples, tests, fixtures, helpers, context functions
  3. Use context7 for non-Elixir libraries/frameworks
  4. Use WebSearch otherwise
• ALWAYS work vertically with smallest increments: UI + backend + tests + configs
• Vertical slice = smallest shippable increment (commit after each GREEN cycle)
• Horizontal work allowed when:
  • Batch refactor (rename, move, format)
  • Cross-cutting change (schema, auth, logging)
  • Explicitly requested
• Default = vertical. If going horizontal: state reason before starting
• ALWAYS strictly follow TDD with those rules:
  • Read existing test patterns before writing new tests
  • If tests exist: run them, identify gaps, add missing coverage before impl
  • Follow RED-GREEN-REFACTOR cycle
  • RED → GREEN = 1 commit (impl + tests together)
  • REFACTOR = separate commit if substantial, otherwise amend if not already pushed
  • When changing constraints (unique indexes, validations, FKs):
    1. Read existing changeset/schema
    2. Write business logic test (not just validation test)
    3. RED → update migration + schema → GREEN
    4. Grep old constraint names → remove dead code

Working with subagents

• Subagent verification: Subagent runs verification commands (test & credo) and reports summary (pass/fail count + exit codes)
• Parent verifies by reading subagent report + git diff, NOT by re-running same commands
• Spawn when:
  • 5+ files touched
  • 10+ steps required
  • Parallel workstreams
• Skip when:
  • Single file edit
  • Quick lookup
• Delegate to protect context:
  • Large reads
  • Web research
  • Test runs
  • Codebase exploration
• Return format:
  • Files changed + why
  • Errors encountered + resolution
  • Open questions for parents
  • summary max 20 lines
  • always include errors and warnings verbatim
  • trim verbose logs only

Cavekit Modes

When user mentions a feature to build or invokes any /bp: command, ask:

Which mode?

1. cavekit-manual — step by step, approve each phase
2. cavekit-auto — grill first, then autonomous

Mode 1: Manual (/cavekit-manual "feature")

All steps marked [M] or [M?] require approval. Steps marked [A] run automatically.

Mode 2: Semi-auto (/cavekit-auto "feature")

Steps marked [M?] become auto-approve unless unresolved ? found in output. Steps marked [M] always require human approval regardless of mode. Steps marked [A] always run automatically.

Stop conditions for semi-auto:

• any output contains unresolved ?
• /bp:build hits circuit breaker (3 failures same task)
• /bp:inspect finds gaps after /boomerang /bp:revise already ran once

Legend:

• [M] always manual, both modes
• [M?] manual in mode 1, auto-approvable in mode 2 unless ? found
• [A] always automatic, both modes

Cavekit Phase Flow

After every cavekit command completes, suggest next phase in one line:

• [M] /grill done → human answers questions, approves §G/§C → suggest /boomerang /bp:research (large codebase) or /bp:draft
• [M?] /boomerang bp:research done → review research brief → suggest /bp:draft
• [M?] /bp:draft done → review kits → check DESIGN.md:
  • missing → suggest /bp:design create
  • exists → run git log <commit>..HEAD --oneline
    • changes found → suggest /bp:design update first
    • no changes → suggest /bp:architect
• [A] /bp:design create|update done → store date + HEAD commit in DESIGN.md Meta section → suggest /bp:architect
• [M?] /bp:architect done → review task graph → suggest /boomerang /bp:build
• [A] /boomerang /bp:build done → suggest /bp:inspect
• [A] /bp:inspect done → gaps found → suggest /boomerang /bp:revise / no gaps → mark done
• [A] /boomerang /bp:revise done → suggest /bp:inspect

DESIGN.md Meta section format (exact, for parsing):

## Meta
last-updated: 2026-06-27T14:32:00
git-commit: a3f9b2c

End every cavekit response with: Next: <command> — <one reason>

Dangerous Commands

Require explicit user approval before running:

• mix ecto.reset, mix ecto.drop — any variant, with or without flags
• git push --force
• rm -rf
• Any command where destructiveness is unclear — ask first

Elixir only

Extra behavior

• Before any code, ALWAYS double check documentation with Tidewave get_docs
• Use shift instead of add for Date, DateTime, NaiveDateTime and Time manipulation
• Prefer mix test over mix compile — only use mix compile when checking errors without running tests
• When adding / changing new migration:
  1. Check status: MIX_ENV=test mix ecto.migrations | grep <number>
  2. If migration "up" → rollback FIRST: MIX_ENV=test mix ecto.rollback -n 1. NEVER modify migration while "up"
  3. Change migration file
  4. Migrate: MIX_ENV=test mix ecto.migrate
  5. Test rollback: MIX_ENV=test mix ecto.rollback -n 1 && MIX_ENV=test mix ecto.migrate

Tooling with Tidewave

• Prefer Tidewave tools over bash/grep for all Elixir work
• Use get_docs for documentation, get_source_location for module/function lookup
• Evaluate code and query DB via Tidewave, not shell where possible

Project conventions and pattern

Elixir

• Add typespecs for Elixir public functions
• Good context modules examples [LIST]
• Good Ecto schemas examples [LIST]
• Good fixtures modules examples [LIST]
• Good tests example to test context module [LIST]

Tests

• Test modules should have async: true when possible, unless:
  • Usage of feature flags
  • Fixtures with values that are unique
• When testing LiveView rendered output:
  1. Use LiveViewTest functions first (has_element?/3, element/3, render/1, ...)
  2. Fallback: LazyHTML for complex DOM queries
  3. Never: Floki (replaced by LazyHTML since LiveView 1.1) or :binary.match
• Tests for non-LiveView modules should be inside describe blocks per function:

# ✅ Good:

describe "list_products/1" do
  test "list_products/1 returns all feedbacks for a given user_id" do
    # test implementation
  end

  test "list_products/1 returns errors" do
    # test implementation
  end
end

describe "get_product/2" do
  test "get_product/2 returns product" do
    # test implementation
  end
end

# ❌ Bad:

test "list_products/1 returns all feedbacks for a given user_id" do
# test implementation
end

test "list_products/1 returns errors" do
# test implementation
end

test "get_product/2 returns product" do
# test implementation
end

• When asserting for length of a short list with at most 5 elements with followups assertions, use pattern matching instead of length/1:

# ✅ Good:
assert [first, second] = list
assert first.name == "First"
assert second.name == "Second"

# ❌ Bad:
assert length(list) == 2
assert Enum.at(list, 0).name == "First"
assert Enum.at(list, 1).name == "Second"

• When asserting on logs, check its level:

# ✅ Good:
assert log =~ "[error] Failed to list products"
assert log =~ "[info] Process completed successfully"

# ❌ Bad:
assert log =~ "Failed to list products"
assert log =~ "Process completed successfully"

• In ExUnit, keep in mind that all logs are available to all tests, so race conditions are possible because of async: true. So assert on the complete log line including the message AND metadata together, not separate fragments.

# ✅ Good: Complete line
assert log =~ "key=value [info] Message"

# ❌ Bad: Separate fragments
assert log =~ "key=value"
assert log =~ "[info] Message"

• If checking if nil or not nil use shorter assert value or refute value:

# ✅ Good:
assert value
refute value

# ❌ Bad:
assert value != nil
refute value == nil

Fixtures

• Use simple fallback pattern from existing fixtures:

def fixture(attrs \\ %{}) do
  product = attrs[:product] || ProductsFixtures.product_fixture()

  attrs = Enum.into(attrs, %{product_id: product.id, ...})

  %Product{} |> changeset(attrs) |> Repo.insert!()
end

Commits

• Commit messages format: "[TICKET_NUMBER] [Message]":
  • ✅ Good "APP-123 Add list_products/1 query"
  • ❌ Bad "feat(products): add list_products/1 query."
• Ask ticket number if not provided
• First word capitalized