Contributing Skill for Claude

Contributing to Tel-Agent

You are helping somebody contribute to Tel-Agent, an open-source AI phone assistant

published under AGPL-3.0 by Dpro GmbH.

Read CLAUDE.md at the repository root before anything else. It is the working

contract and it overrides this file wherever the two disagree.

Before you touch anything

Three rules that are not negotiable, and breaking any of them wastes the maintainer's

time and the contributor's:

• Everything you write is in English — code, comments, identifiers, commit

messages, pull request text, issue comments. This is Rule 0 in CLAUDE.md. It is not

about anybody's first language; it is what keeps one codebase readable.

• Never name a competitor anywhere — code, comment, commit, issue, pull request, in

any language. This is irreversible once pushed, so the check happens *before* the

commit, not after.

• Never commit a secret — no key, token, password, or real phone number. If one is

needed to run something, it goes in .env, which is ignored.

Translation — the first contribution, and the one that never runs out

Do not send somebody new to a code issue. Send them here.

**If this is their first contribution, walk them through

docs/ONBOARDING.md rather than this section.** It is

the same work written for somebody who has never opened a pull request: one file, about

thirty strings, no setup at all. This section is the reference; that page is the path.

The size is a ceiling, not a target: one file, then stop and open the pull request.

The point of a first contribution is not the translation in it — it is running the

fork-to-merge loop once on something small enough that a mistake costs nothing. A

contributor who translates thirty strings and opens a pull request has learned more

than one who translates three hundred and never opens it.

Thirty languages sit in locales/ as directories holding nothing but .gitkeep — that

is the pick-list, and the script prints it. Any language not among them is added in the

same pull request as its first translated file.

The whole task is one loop, and it is the same loop every time:

run the script  →  pick what is missing  →  translate it  →  open a pull request
       ↑                                                              │
       └──────────────────────────────────────────────────────────────┘

node scripts/check-locales.mjs               # every language, and where each stands
node scripts/check-locales.mjs --locale fr   # one language: what is left, smallest first

The script measures everything against English, which is the source language. It prints

the remaining files smallest first, and the smallest are 16 to 26 strings — about

twenty minutes.

mkdir -p locales/fr
cp locales/en/code.json locales/fr/
# translate the values, leave the keys alone
node scripts/check-locales.mjs --locale fr   # confirm the number moved

Then the normal flow from step 2: claim, branch, pull request. **One file per pull

request.** A translator who has finished one runs the script again, takes the next file

— or a different language entirely — and repeats. Nothing needs to be assigned again

after the first time.

This is why it never runs out: every language is 2,972 strings across 33 files, and any

language anybody speaks is welcome. There is more of this work than there will ever be

people to do it.

Four things that get a translation pull request sent back, all easy to avoid:

• Copying all 33 files and translating one. An untranslated copy of English looks

finished and ships English to somebody who asked for their own language. One file.

• Translating the keys. Only the values on the right-hand side change.
• Translating {placeholders}. {count} and {name} are filled at runtime, and a

translated placeholder breaks only on that language — so nobody catches it.

• Machine translation nobody read. Translate the meaning. If it reads oddly to a

native speaker it is wrong, whatever the dictionary says. Only take a language you

actually speak.

locales/README.md has the rest: the two tiers, why a partial language breaks nothing,

and when a language gets registered.

After the first one is merged, anything on the board is open to them. The

translation is not a test to be passed — it is the smallest real thing in the project,

and it is where the workflow gets learned on something that does not matter if it takes

two attempts.

Step 1 — Find something to work on

Work comes from the public board and nowhere else. Do not invent a task, and do not

"just fix something you noticed while you were in there" — that goes in a new issue.

gh issue list --repo Dpro-at/Tel-Agent --label "good first issue" --state open
gh issue list --repo Dpro-at/Tel-Agent --label "help wanted" --state open

The board is at https://github.com/orgs/Dpro-at/projects/6

Only take from the Ready column. Backlog means blocked on something else; the

issue looks available and is not. Every issue carries a level: label:

| Label | What it means |

|---|---|

| level: first-issue | Small, self-contained, finishable in one sitting. Start here. |

| level: easy | Straightforward, little context needed. |

| level: medium | Needs some understanding of the codebase. |

| level: hard | Substantial, touches several parts. |

| level: maintainer | Decides architecture. Do not take this one. |

If the person you are helping has not contributed here before, steer them to

level: first-issue. There are real ones, not a token entry.

Read the whole issue before starting. Every issue is written with the same fields:

*Why* (the reason it exists), *Do* (what to build), *Done when* (the acceptance test),

*Verify* (the exact commands a reviewer will run), and sometimes *Needs* (issues that

must be closed first). If Needs lists something still open, this task is not ready —

go back to step 1.

Step 2 — Claim it

gh issue comment <number> --repo Dpro-at/Tel-Agent --body "I would like to take this."

Wait to be assigned before writing code. One person per issue, and the assignment is

what stops two people building the same thing. If nobody responds within a few days, say

so on the issue rather than starting anyway.

Step 3 — Set up, once

If the person you are helping has never worked on this repository, walk them through

this in order and confirm each command actually worked before moving on. Do not

paste all of it at once and hope. Budget about half an hour the first time, and roughly

nothing every time after.

3.1 — What has to be installed

git --version      # any recent version
node --version     # v20 or newer. Next.js 16 and React 19 will not run on v18
npm --version
gh --version       # GitHub CLI - https://cli.github.com
python --version   # 3.12+, only needed for backend issues

gh is not optional here. Claiming an issue, opening the pull request and reading the

board all go through it. If it is missing, install it before anything else.

Python is only needed if the issue touches api/ or agent/. A documentation or

frontend issue needs Node and nothing more.

3.2 — Log in to GitHub

gh auth status

If that says you are not logged in:

gh auth login

Choose GitHub.com → HTTPS → Yes to authenticate git → **Login with a web

browser**, then paste the one-time code it prints.

This step is skipped more often than any other, and it fails late rather than early:

everything looks fine until the first gh command, which then prints *"To get started

with GitHub CLI, please run: gh auth login"* instead of doing the thing. If any gh

command produces that message, this is why.

Reading the project board needs one extra scope, which the default login does not grant:

gh auth refresh -s read:project

3.3 — Fork and clone

Everyone contributes through a fork. Nobody gets write access to the repository, and

that is the same rule for everyone.

gh repo fork Dpro-at/Tel-Agent --clone
cd Tel-Agent
git remote -v          # expect: origin = your fork, upstream = Dpro-at

gh repo fork --clone sets upstream for you. If git remote -v does not show it:

git remote add upstream https://github.com/Dpro-at/Tel-Agent.git

3.4 — Check the email on your commits

git config user.email

If that address is not on your GitHub account — or your @users.noreply.github.com one

— your commits land unlinked: the work gets merged and your name is on nothing.

This is the single most common way somebody does real work here and does not appear in

the contributors list, and it is awkward to correct afterwards. Fix it now:

git config user.email "[email protected]"

3.5 — Run what exists

The frontend runs today:

npm --prefix web install
npm --prefix web run dev

Open http://localhost:3000. It redirects to a locale — /en, /de or /ar — and you

should land on the sign-in screen. If you see that, the setup worked. Every screen

has a state switcher pinned to the top in development; it is stripped from a production

build.

The screens read from static fixture modules, so they render without a server. Nothing

is wired to anything yet.

The backend does not run, because it does not exist. agent/ and api/ hold six

.gitkeep files and two READMEs, and building them is what most of the open issues are.

If an issue asks you to run something that is not there, re-read it — the task is

almost certainly to create it.

3.6 — Confirm the tooling before you touch code

npx --prefix web tsc --noEmit    # expect: no output
npm --prefix web run lint

Run these before your first edit, not after. If something is already red on a clean

clone, that is worth reporting as its own issue — and it is not yours to fix inside an

unrelated pull request.

Step 4 — Do the work

git checkout -b <type>/<short-name>

Types: feat/, fix/, docs/, chore/, refactor/, test/. Example:

feat/backend-skeleton.

Stay inside the issue. A pull request that does two things gets reviewed as slowly

as its harder half. Something else that needs fixing goes in a new issue.

Commits follow Conventional Commits:

feat(api): add health endpoint
docs(contributing): add a what-to-work-on section

Match the code around you — its naming, its comment density, its idiom. A change that

reads like it was always there is the goal.

Step 5 — Verify before you open anything

Run the issue's own Verify commands first, then the repository gate for whichever

half you touched:

# Python
ruff check . && ruff format --check . && mypy . && pytest

# web/
npm --prefix web run lint
npx --prefix web tsc --noEmit
npm --prefix web run build

Nothing you touched may go red.

Then check by hand:

• No secret, key, token, password or real phone number in the diff.
• No competitor named anywhere, in any language.
• Everything in English.
• If it is visible, screenshots in light and dark, and one in ar if the layout is

direction-sensitive.

Do not report the task finished until these actually pass. If something fails and

you cannot fix it, say so plainly in the pull request — a known failure stated honestly

is useful; a silent one wastes a review cycle.

Step 6 — Open the pull request

git push -u origin <branch>
gh pr create --repo Dpro-at/Tel-Agent --title "<same as the commit>" --body "..."

The body says: what you did, what you deliberately did not do, and how you tested it.

Link the issue with Closes #<number>. Paste the output of the Verify commands.

Open it as a draft while it is not ready. Ready for review means you believe it is

done.

The CLA. The first pull request cannot be merged until its author has signed the

Contributor License Agreement. Expect to be asked.

Step 7 — Review

Expect changes to be requested. It is not a verdict on the person.

Push follow-up commits to the same branch. Do not force-push during a review — the

reviewer loses their place in the diff.

It lands as a squash-merge, done by a maintainer. The branch is deleted automatically.

If the work has to stop

Half the people who take an issue never finish, and that is normal. Saying so is a

contribution: it returns the task to the pool the same day instead of fourteen days

later, which is when an inactive assignment is cleared automatically.

gh issue comment <number> --repo Dpro-at/Tel-Agent --body "I cannot finish this - unassigning so somebody else can take it."

What "done" means

The code works, the tests cover it, the documentation says so, and .env.example lists

any variable that was introduced. All four, not three.