Gabriel Vidal
18229c8975
Document the open-pr finish flow: homelab specifics (alias, body
template pointer) in CLAUDE.md, and the generic {{pr_command}} section
with the PR body sections in the portable PROJECT_CLAUDE.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
94 lines
4.4 KiB
Markdown
94 lines
4.4 KiB
Markdown
# Project working conventions
|
|
|
|
Generic, host-agnostic conventions for working in a repo that the ai-agent tool
|
|
manages. These are the portable rules — worktree workflow, artefacts, plans,
|
|
committing, and how to signal a task is finished — with none of the homelab's
|
|
Traefik/Compose/registry specifics baked in. A concrete repo (e.g. the homelab)
|
|
keeps its own `CLAUDE.md` for its architecture and layers this on top; the
|
|
ai-agent ships this file as the starting point for a new project's root
|
|
`CLAUDE.md`.
|
|
|
|
Anything wrapped in `{{…}}` is a placeholder to fill in per repo.
|
|
|
|
## Before you edit: isolate your work
|
|
|
|
**Spin up an isolated git worktree and work there**, rather than editing files on
|
|
the checked-out branch. Before creating the worktree, pull the latest `main` so
|
|
the worktree starts from current state.
|
|
|
|
- `{{worktree_command}}` — create the worktree (e.g. `scripts/new-worktree.sh`).
|
|
- `{{pull_command}}` — pull `main` first (e.g. `git pull`, or an
|
|
auth-wrapped variant if a proxy fronts your git host).
|
|
|
|
Skip the worktree only for trivial, read-only inspection; any change to tracked
|
|
files goes through one.
|
|
|
|
## Directory conventions
|
|
|
|
- `data/` — file-backed working data: notes, logs, plans, boards. Not tracked in
|
|
git. Write a plan to `data/log/<YYYY-MM-DD>-[title].md`.
|
|
- **Generated artefacts** (images, screenshots, renders, charts, exports — any
|
|
binary/media file) tied to a project go into that project's artefact folder:
|
|
|
|
```
|
|
<projectFolder>/.ai/artefacts/<YYYY-MM-DD>/<sessionId>/<file>
|
|
```
|
|
|
|
where `<projectFolder>` is the **canonical** directory (never a worktree copy —
|
|
worktrees get deleted and aren't mounted into the viewer) and `<sessionId>` is
|
|
the current conversation id (`$CLAUDE_SESSION_ID`, else resolve it via the
|
|
session-id helper). The ai-agent viewer serves these folders: images you `Read`
|
|
from there render inline in the tool call, and the conversation details page
|
|
lists the whole set in its **Artefacts** card. Add `.ai/` to the repo's
|
|
`.gitignore` (or `.git/info/exclude`) if it isn't already ignored.
|
|
- Artefacts tied to no particular project still go under `data/` — e.g.
|
|
`data/artifacts/<YYYY-MM-DD>-[title].png` — which is likewise mounted into the
|
|
viewer and previewed inline. Files written anywhere else can't be served or
|
|
previewed.
|
|
|
|
## Committing changes
|
|
|
|
**Commit after each change.** When you finish a logical unit of work — a source
|
|
edit, a config change, a script, docs — commit it right away in its own focused
|
|
commit rather than batching unrelated changes, and push as you go.
|
|
|
|
Use `{{commit_command}}` to commit and push (e.g. the `commit-project` skill for
|
|
per-project Gitea/GitHub repos, or a repo-specific commit skill).
|
|
|
|
## Finishing a feature: open a documented PR
|
|
|
|
When the task's guidelines ask for a PR instead of a deploy, finish feature
|
|
work by pushing the branch and opening a pull request with `{{pr_command}}`
|
|
(e.g. the `open-pr` skill), assigned to the repo owner. The PR body is the
|
|
feature's documentation — write it with these sections:
|
|
|
|
- **Summary** — what changed and why, for someone reading history later.
|
|
- **Key changes** — one bullet per meaningful change, not per commit.
|
|
- **Key decisions** — non-obvious choices and their trade-offs.
|
|
- **Changelog** — user-facing Keep-a-Changelog bullets (`Added/Changed/Fixed/
|
|
Removed`); these entries are harvested to generate the project's changelog.
|
|
- **Test notes** — how it was verified.
|
|
|
|
Attach a screenshot of any visible result. Deployment happens after the PR is
|
|
reviewed and merged, not as part of the task.
|
|
|
|
## When work is done
|
|
|
|
**Send a push notification after finishing any task the user kicked off** — not
|
|
just long-running ones but every completed task — so they know it's done:
|
|
|
|
```bash
|
|
{{notify_command}} "✅ Task finished" "short outcome" --type {{type}}
|
|
```
|
|
|
|
Keep it short: say what finished and the outcome. Pass `--type <type>` to pick a
|
|
fitting icon and `--url <url>` when the task has a more relevant page than the
|
|
default (the conversation in the ai-agent viewer).
|
|
|
|
**Then end the turn with `DONE`.** After sending that notification, your final
|
|
message must end with the literal marker `DONE` on its own line. The ai-agent
|
|
conversation viewer keys "finished" off this: a conversation that has both
|
|
recorded a notification and ended its last message with `DONE` is shown as
|
|
finished, instead of being stuck on the stale `running` badge the
|
|
worktree/select-project step set at the start.
|