org-conventions

Category: Tools & Productivity | Uploader: En-Nam | Downloads: 0 | Version: v1.0（Latest）
Organization-wide conventions for commit messages, branch naming, PR descriptions, and task communication. Loaded automatically by all Ennam plugins.
Changelog: Source: GitHub https://github.com/En-Nam/ennam-claude-agent-team
Directory Structure

Current level: core/ennam-conventions/skills/org-conventions/
📄 SKILL.md 5.3 KB
SKILL.md

---
name: org-conventions
description: Organization-wide conventions for commit messages, branch naming, PR descriptions, and task communication. Loaded automatically by all Ennam plugins.
user-invokable: false
---

# 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

```bash
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.

```bash
# 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>
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
org-conventions

Directory Structure

SKILL.md

Report

Notice
