hrynco-ef/AGENTS.md

# hrynco-ef Agent Rules

This file is the authoritative source for hrynco-ef workflow, delivery, and role rules.

## 1. Startup

- Command timeout: if a command runs longer than 10 minutes, report timeout and ask the user.
- Validate required services before task work:
  - YouTrack authenticated access
  - Gitea authenticated access and the `hrynco/hrynco-ef` repo
  - TeamCity authenticated access
- If any startup check fails, stop and ask the user.

### Operational cadence

- TeamCity polling: do not poll more often than once every 30 seconds.
- If no relevant build is visible after 60 seconds, warn once and continue waiting normally.
- Play the completion sound after multi-step work.
- Play the question sound before or with any blocking user question.

### Startup report

Print one startup report line per check:

- `✅` success, `⚠️` failure
- include a service emoji on every line
- use bright colors when supported
- after all checks, print `✅` or `⚠️` for initialization

Required report items:

- Workflow rules loaded
- YouTrack auth + reachability
- Gitea auth + reachability
- Gitea resource access (`hrynco/hrynco-ef`)
- TeamCity auth + reachability
- Initialization

## 2. Workflow

- `AGENTS.md` is the source of truth; treat other docs as references only.
- Do not start a new task before the current one is complete.
- Default development branch: `development`.
- Before task work:
  - be on local `development`
  - local `development` must be clean
  - local `development` must match remote
  - if not, fix that first
- On task start:
  - set YouTrack state to `In Progress`
  - create a feature branch from `development`
  - name the branch after the task
- Work only in the feature branch.
- Keep diffs small, targeted, and consistent with existing style.
- Do not merge or publish during development.

### Issue lifecycle

1. Product analyst creates/refines the YouTrack task.
2. Developer takes the task and starts implementation.
3. Developer finishes implementation and hands off to code review.
4. Code reviewer reviews and either passes or returns to developer.
5. Repeat developer/reviewer cycles as needed.
6. Maximum five review rounds total for the same unresolved task state.
7. After review round five, if still unresolved, return to product analysis.
8. Tester validates the implementation against acceptance criteria.
9. Developer waits for user validation approval.
10. Delivery and release manager handles commit, push, PRs, merge, and TeamCity publish validation.

### Task rules

- Create the YouTrack task before development starts.
- Default assignee is AI unless the task flow requires another assignee.
- Define scope and acceptance criteria.
- Tasks must be independently deliverable and testable.

## 3. Validation

- Build before finishing.
- Run relevant tests and checks.
- Verify no regressions.
- Do not guess about validation; use actual evidence.

## 4. Completion

After explicit user validation approval:

- commit staged changes
- push the feature branch
- create PR from feature branch to `development`
- merge that PR
- create PR from `development` to `main`
- merge that PR
- wait for TC `HrynCo / HrynCo.EF / publish` to finish successfully
- set the YouTrack task to `Done`
- calculate exact Spent Time from YouTrack timestamps only
- set the YouTrack Spent Time field
- switch back to `development`
- pull latest `development`
- ensure local `development` and `main` match their remotes
- leave the repository in a clean end state

### Spent Time

- Do not estimate or infer Spent Time.
- Use exact YouTrack creation and Done timestamps only.
- If exact timestamps are unavailable, stop and ask the user.

### Command output

- Keep command summaries concise.
- Do not dump raw output unless needed for diagnosis or explicitly requested.

## 5. Communication

- Keep command output summaries concise.
- Do not dump raw command output unless needed.
- Use direct links in YouTrack and implementation notes when stable links exist.
- Use emojis intentionally for scanning, not mechanically.
- Commit messages must be Conventional Commit style, lowercase subject, short body, and final line `Ref: IT-<number>`.

## 6. Audio

- Play `C:\Sounds\AgentSounds\warcraft_2_jobs_done.mp3` after multi-step work completes.
- Play `C:\Sounds\AgentSounds\peasantdeath.mp3` before or with any blocking user question.
- Use `System.Windows.Media.MediaPlayer` for MP3 playback on Windows.

## 7. Engineering

- This repo publishes two NuGet packages: `HrynCo.DAL.Abstract` and `HrynCo.DAL.EF`.
- Package versions are injected by TeamCity at build time via `Directory.Build.props`.
- Packages are pushed to nuget.org by the `HrynCo / HrynCo.EF / publish` TC build.
- Do not hardcode versions in `.csproj` files.
- `Directory.Packages.props` centralizes all dependency versions.
- Keep `HrynCo.DAL.Abstract` free of EF Core dependencies — it must remain infrastructure-agnostic.
- `HrynCo.DAL.EF` may depend on EF Core and `HrynCo.DAL.Abstract`.

## 8. Role rules

### Developer

- Implement end to end.
- Do not leave partial work.
- Do not refactor unrelated code.
- Validate before finishing.

### Code reviewer

- Focus on correctness, regressions, security, and missing tests.
- Report only meaningful findings.
- Do not modify code.

### Product analyst

- Make tasks clear, scoped, and executable.
- Avoid implementation assumptions unless necessary.

### Tester

- Validate happy path, failure path, and adjacent regressions.
- Report exact steps, actual result, expected result, and severity.

### Delivery and release manager

- Handle PR flow and publish validation.
- Do not trigger the publish build manually — it runs automatically on merge to `main`.
- Mark delivered only after TC publish build succeeds.