org-conventions

Ennam Org Conventions

These conventions apply to every agent on every Ennam team, regardless of tech stack (NextJS, Python, Flutter, or any other). Follow them on every task without exception.

1. Branch Naming Convention

<domain>/<task-id>-<short-description>

Examples:

• backend/task-001-user-auth-api
• frontend/task-004-login-screen
• tests/task-006-auth-unit-tests
• infra/task-010-ci-pipeline

Rules:

• Lowercase only — no uppercase letters
• Hyphens only — no spaces, no underscores
• Task ID must match the assigned task exactly
• Description should be 2-5 words summarizing the work

2. Starting a Task

git checkout -b <branch-name>
git status  # Verify you are on the correct branch

Immediately confirm to the orchestrator:

Branch created: <branch-name>
Starting TASK-<ID>: <title>

3. Commit Convention

Use conventional commits. Commit each logical chunk of work as it is completed. Do NOT batch all changes into a single commit at the end of a task.

<type>(<scope>): <description>

[optional body — explain the why, not the what]

Task: TASK-<ID>

Commit Types

Type	When to use
feat	A new feature or capability
fix	A bug fix
test	Adding or updating tests (no production code change)
refactor	Code restructuring with no behavior change
docs	Documentation changes only
chore	Build process, tooling, dependency, or config changes

Scope

The scope identifies the area of the codebase affected. Use whatever scope is meaningful for your project (e.g., api, auth, ui, db, ci). Keep it short and consistent within your team.

Examples

feat(auth): add JWT refresh token endpoint

Issues a short-lived access token and a long-lived refresh token.
Refresh tokens are stored hashed in the database.

Task: TASK-003

fix(db): correct nullable constraint on user email field

Email was required at the schema level but the migration left
the column nullable, causing silent insert failures.

Task: TASK-007

test(auth): add unit tests for token refresh service

Covers happy path, expired refresh token, and revoked token cases.

Task: TASK-009

chore(ci): add lint step to GitHub Actions workflow

Task: TASK-012

4. Domain Boundaries — Hard Rule

Every agent owns a specific set of directories. You may ONLY modify files within your assigned domain.

If you need to change a file outside your domain:

1. STOP — do not edit the file
2. Report to the orchestrator: "Need change in <file-path> because <reason>"
3. Wait for the orchestrator to either make the change or reassign the work

This rule exists to prevent merge conflicts and to keep each agent's work reviewable in isolation. There are no exceptions.

5. Pre-Completion Self-Check

Run ALL of the following before reporting a task done. The exact commands will vary by stack — use the equivalent for your project.

# 1. Verify only your domain files were changed
git diff --name-only main...HEAD

# 2. No uncommitted changes remain
git status

# 3. Type-check / compile (use the appropriate command for your stack)
#    TypeScript:  npx tsc --noEmit
#    Python:      mypy .
#    Dart/Flutter: flutter analyze

# 4. Lint (use the appropriate linter for your stack)
#    NextJS:   npx next lint
#    Python:   ruff check .
#    Flutter:  flutter analyze

# 5. Relevant tests pass
#    Run only the tests that cover your changed code

If any check fails, fix the issue and re-run all checks before reporting done.

6. Task Completion Message

When all self-checks pass, report to the orchestrator using this exact format:

DONE: TASK-<ID>
Branch: <branch-name>
Files changed:
- <path/to/file> (new)
- <path/to/other-file> (modified)
Summary: <1-3 sentences describing what was implemented and why>
Tests: <X passed / not applicable>

7. When Blocked

If you cannot proceed for any reason, report immediately — do not wait:

BLOCKED: TASK-<ID>
Reason: <specific thing that is missing or broken>
Need from: <orchestrator | specific teammate | external dependency>

Do NOT attempt to work around a blocker by modifying files outside your domain or by making assumptions that should be confirmed first.

8. Merge Conflicts

If you encounter merge conflicts:

1. Do NOT resolve them yourself
2. Report to the orchestrator with the full list of conflicting file paths
3. Wait for the orchestrator to coordinate resolution

9. PR Description Template

When opening a pull request, use this structure:

## Summary
- <bullet: what was added or changed>
- <bullet: why — the business or technical reason>

## Changes
- `<file-path>` — <one-line description>
- `<file-path>` — <one-line description>

## Test Plan
- [ ] <specific thing to verify manually or via automated test>
- [ ] <edge case to check>

Task: TASK-<ID>