From 049290830f9bfe096d53e3e328743f2ae2e9b70c Mon Sep 17 00:00:00 2001 From: Muhammad Rafay Nadeem Date: Wed, 5 Aug 2026 13:09:07 +0500 Subject: [PATCH 1/5] docs: require starting work from dev, never main Adds a Branching section to CLAUDE.md so agents branch from origin/dev and open PRs against dev instead of main. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index e1c17fc7..4e3d54d5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,6 +4,14 @@ This file provides guidance to Claude Code when working in this repository. Read `.ai/instructions.md` for full project instructions (architecture, conventions, testing, commits). +## Branching + +Always start work from `dev` — never from `main`. + +- Before creating a branch, make sure `dev` is current (`git fetch origin dev`) and branch from `origin/dev`. +- Open pull requests against `dev`. +- Never commit to, branch from, or target `main` directly. If a task appears to require it, stop and ask. + ## Skills Reference these files as needed for scaffolding: From 6be667960d78114ac8019456548674b6b9090cb9 Mon Sep 17 00:00:00 2001 From: Muhammad Rafay Nadeem Date: Wed, 5 Aug 2026 13:11:11 +0500 Subject: [PATCH 2/5] docs: extend dev-branch rule to worktrees A new worktree bases off the repo default branch (beta), not dev, so CLAUDE.md now spells out re-basing onto origin/dev before making changes. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4e3d54d5..c49e56ae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,12 +6,23 @@ Read `.ai/instructions.md` for full project instructions (architecture, conventi ## Branching -Always start work from `dev` — never from `main`. +Always start work from `dev` — never from `main`. This applies to branches and worktrees alike. - Before creating a branch, make sure `dev` is current (`git fetch origin dev`) and branch from `origin/dev`. - Open pull requests against `dev`. - Never commit to, branch from, or target `main` directly. If a task appears to require it, stop and ask. +### Worktrees + +A new worktree does **not** start from `dev` by default — it starts from this repo's default branch, which is `beta`. Re-base it onto `dev` before making any changes: + +```sh +git fetch origin dev +git reset --hard origin/dev # only in a fresh, clean worktree +``` + +Then confirm with `git log --oneline -1` that HEAD matches the `origin/dev` tip. Branch names and PRs from a worktree follow the same rules as above: cut from `origin/dev`, target `dev`. + ## Skills Reference these files as needed for scaffolding: From e46c91dd6b35917a798b133be68726b3ad939651 Mon Sep 17 00:00:00 2001 From: Muhammad Rafay Nadeem Date: Wed, 5 Aug 2026 13:31:57 +0500 Subject: [PATCH 3/5] docs: clarify worktree wording to avoid reading as a prohibition Lead with the imperative (base worktrees on origin/dev) and state the beta default as a caveat, so no sentence scans as "do not use dev". Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index c49e56ae..c4ef8ac2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,7 +14,9 @@ Always start work from `dev` — never from `main`. This applies to branches and ### Worktrees -A new worktree does **not** start from `dev` by default — it starts from this repo's default branch, which is `beta`. Re-base it onto `dev` before making any changes: +Base every worktree on `origin/dev` too. + +Be aware that a new worktree starts from this repo's default branch, `beta`. Always move it onto `dev` before making any changes: ```sh git fetch origin dev From 00cf7323f76e76b29e438eb9ea4603be86ccf54d Mon Sep 17 00:00:00 2001 From: Muhammad Rafay Nadeem Date: Wed, 5 Aug 2026 13:45:01 +0500 Subject: [PATCH 4/5] docs: disallow AI-generated code comments Comments must explain non-obvious why only; existing comment density in nearby code is not a reason to add more. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index c4ef8ac2..5f24570e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,6 +25,15 @@ git reset --hard origin/dev # only in a fresh, clean worktree Then confirm with `git log --oneline -1` that HEAD matches the `origin/dev` tip. Branch names and PRs from a worktree follow the same rules as above: cut from `origin/dev`, target `dev`. +## Comments + +AI-generated comments are not allowed. + +- Do not add comments that restate what the code already says. +- Do not narrate a change, leave notes for a future agent, or address the reader as an AI. +- Comment only to explain non-obvious *why*: a constraint, a workaround, a subtle invariant. +- Default to no comment. Do not add comments because nearby code has them — existing comment density is never a reason to add more. + ## Skills Reference these files as needed for scaffolding: From ec02bb976a7a133ccd989f53e8fb68900c885764 Mon Sep 17 00:00:00 2001 From: Muhammad Rafay Nadeem Date: Wed, 5 Aug 2026 14:11:36 +0500 Subject: [PATCH 5/5] docs: move branching and comment rules to .ai/instructions.md Project conventions belong in .ai/instructions.md; CLAUDE.md only points to it. Adds a Branching section (start from dev, never main, worktrees included) and a no-AI-generated-comments code convention, and reverts CLAUDE.md to its original content. Co-Authored-By: Claude Opus 5 (1M context) --- .ai/instructions.md | 11 +++++++++++ CLAUDE.md | 32 +------------------------------- 2 files changed, 12 insertions(+), 31 deletions(-) diff --git a/.ai/instructions.md b/.ai/instructions.md index df8edc83..e9a835ea 100644 --- a/.ai/instructions.md +++ b/.ai/instructions.md @@ -67,8 +67,19 @@ Supporting: **Types** (`src/types/`) for value objects, context objects, and dom - **Commands use `export default class`** — oclif requires default export; actions, prompts, and services use named exports (`export class`) - **Static fields use `readonly`** — `static readonly summary`, `static readonly description`, `static readonly cmdTxt` on every Command - **Topic separator is space** — `apimatic portal generate`, not `apimatic portal:generate` +- **No AI-generated comments** — comment only to explain non-obvious *why*: a constraint, a workaround, a subtle invariant. Never restate what the code already says, narrate a change, or leave notes addressed to a future agent. Default to no comment; existing comment density in nearby code is never a reason to add more. - **Telemetry** — After `outro(result)`, commands optionally track failures via `result.mapAll(() => {}, async () => { await new TelemetryService(configDir).trackEvent(new SomeFailedEvent(...), shell) }, () => {})`. Event classes extend `DomainEvent` (`src/types/events/`). Only the failure callback is populated; success/cancel are no-ops. +## Branching + +Always start work from `dev` — never from `main`. This applies to branches and worktrees alike. + +- Make sure `dev` is current (`git fetch origin dev`) and branch from `origin/dev`. +- Open pull requests against `dev`. +- Never commit to, branch from, or target `main` directly. If a task appears to require it, stop and ask. + +**Worktrees** — a new worktree starts from this repo's default branch, `beta`, so move it onto `dev` before making any changes: `git fetch origin dev && git reset --hard origin/dev` (fresh, clean worktrees only). Confirm with `git log --oneline -1` that HEAD matches the `origin/dev` tip. + ## Commit Conventions Uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitlint + husky. Pre-commit runs lint-staged (ESLint + Prettier). diff --git a/CLAUDE.md b/CLAUDE.md index 5f24570e..8af322f0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,37 +2,7 @@ This file provides guidance to Claude Code when working in this repository. -Read `.ai/instructions.md` for full project instructions (architecture, conventions, testing, commits). - -## Branching - -Always start work from `dev` — never from `main`. This applies to branches and worktrees alike. - -- Before creating a branch, make sure `dev` is current (`git fetch origin dev`) and branch from `origin/dev`. -- Open pull requests against `dev`. -- Never commit to, branch from, or target `main` directly. If a task appears to require it, stop and ask. - -### Worktrees - -Base every worktree on `origin/dev` too. - -Be aware that a new worktree starts from this repo's default branch, `beta`. Always move it onto `dev` before making any changes: - -```sh -git fetch origin dev -git reset --hard origin/dev # only in a fresh, clean worktree -``` - -Then confirm with `git log --oneline -1` that HEAD matches the `origin/dev` tip. Branch names and PRs from a worktree follow the same rules as above: cut from `origin/dev`, target `dev`. - -## Comments - -AI-generated comments are not allowed. - -- Do not add comments that restate what the code already says. -- Do not narrate a change, leave notes for a future agent, or address the reader as an AI. -- Comment only to explain non-obvious *why*: a constraint, a workaround, a subtle invariant. -- Default to no comment. Do not add comments because nearby code has them — existing comment density is never a reason to add more. +Read `.ai/instructions.md` for full project instructions (architecture, conventions, branching, testing, commits). ## Skills