diff --git a/.agents/skills/cpn-commit/SKILL.md b/.agents/skills/cpn-commit/SKILL.md new file mode 100644 index 0000000000..ea7e8ef622 --- /dev/null +++ b/.agents/skills/cpn-commit/SKILL.md @@ -0,0 +1,68 @@ +--- +name: cpn-commit +description: + "Use when committing in this repo: conventional commit shape enforced by + commitlint." +version: 1.0.0 +license: Apache-2.0 +--- + +# Console commits + +The `commit-msg` Husky hook runs commitlint (`commitlint.config.cjs`, extends +`@commitlint/config-conventional` with `'body-leading-blank': [2, 'always']`). +Release Please derives version bumps from the type. + +## Prerequisites + +- Feature branch off `origin/main`, `git branch --show-current` to confirm — + never commit on `main`. +- Husky hooks active via `pnpm install`; commitlint rejects a malformed + message at `commit-msg`. + +An unmet requirement is a reported blocker, never a silent scope change. +Never bypass hooks with `--no-verify`. + +## Commit shape + +| Rule | Value | +| -------- | ----------------------------------------------------------------------------------------- | +| Types | `feat`, `fix`, `chore`, `docs`, `refactor`, `revert`, `build`, `feature` | +| Scope | optional, `type(scope):` | +| Breaking | `type!:` / `type(scope)!:` | +| Subject | imperative, lowercase start, no trailing period | +| Body | optional, separated from the subject by exactly one blank line | +| Footer | `Refs #N`; never `Closes #N` — issues close deliberately after verification | + +Reference safety: a bare `#N` resolves to a console issue/PR. Cross-repo +references use a full URL or `owner/repo#N`. + +## Procedure + +Single-line message: + +```bash +git commit -m "fix: prevent null group lookup in keycloak sync" +``` + +With a body, use a heredoc; repeated `-m` flags are fragile under shell +quoting. The blank line after the subject satisfies `body-leading-blank`: + +```bash +git commit -m "$(cat <<'EOF' +feat(plugins): add vault secret rotation + +Supports monthly rotation via the hook post step. + +Refs #123 +EOF +)" +``` + +Fold work into the last commit with `git commit --amend` — never amend a +commit that is already pushed and under review. + +## Verify + +`git log -1 --format=%B` — shape matches the table; footer `Refs #N` present +when an issue stands behind the commit. diff --git a/.agents/skills/cpn-dev-workflow/SKILL.md b/.agents/skills/cpn-dev-workflow/SKILL.md new file mode 100644 index 0000000000..6c56c46103 --- /dev/null +++ b/.agents/skills/cpn-dev-workflow/SKILL.md @@ -0,0 +1,73 @@ +--- +name: cpn-dev-workflow +description: + "Use when contributing to this repo: issue-first lifecycle, workspace + isolation, quality gates, and the PR workflow." +version: 1.0.0 +license: Apache-2.0 +--- + +# Console dev workflow + +## Stack + +- pnpm monorepo, Node >= 26, pnpm >= 11.8 +- Backend target: `apps/server-nestjs`. `apps/server` is frozen (read-only + reference) — never modify it. +- Git-backed repository: work on feature branches off `origin/main`; + `main` is protected. + +## Prerequisites + +```bash +gh api user --jq .login # authenticated +gh api repos/cloud-pi-native/console --jq .viewerPermission # need write +node --version && pnpm --version # Node >= 26, pnpm >= 11.8 +git status --porcelain # clean checkout +``` + +An unmet requirement is a reported blocker, never a silent scope change. + +## Lifecycle + +Lifecycle: discussion → issue → issue comments → PR. No PR without an issue +behind it; no bare-request implementation. + +1. **One issue per item.** Bug `🐛 [BUG] - ` / feature + `💡 [REQUEST] - `, via `.github/ISSUE_TEMPLATE/`. Body = problem + statement plus a `- [ ]` acceptance tasklist, Définition du fini — never + the solution; analysis goes in comments. Search existing issues before + creating. +2. **Triage before work**: set each empty, determinable field — labels + from `gh label list`, never invented; assignee; milestone: bug → highest + open patch of the current minor line, feature → next minor/major. +3. **Branch from `origin/main`**, implement, commit. +4. **Draft PR** linked to the issue. +5. **Human approving review is the merge gate** — do not self-merge. +6. **Close deliberately**: verify every acceptance box, then close the issue + with an evidence comment. Never rely on PR-merge auto-close. + +Details live in the `cpn-issue`, `cpn-commit`, `cpn-pr`, and `cpn-review` +skills. + +## Isolation + +- One logical change per branch and PR; out-of-scope fixes become follow-up + issues. +- When the current checkout holds unrelated work in progress, isolate in a + fresh git worktree instead of mixing: + +```bash +git worktree add ../console. -b origin/main +``` + +## Verify + +Before opening the PR: + +```bash +pnpm format +pnpm lint +pnpm test # targeted specs at minimum +pnpm playwright:test # only if a user journey is affected +``` diff --git a/.agents/skills/cpn-issue/SKILL.md b/.agents/skills/cpn-issue/SKILL.md new file mode 100644 index 0000000000..d68cb8d3fe --- /dev/null +++ b/.agents/skills/cpn-issue/SKILL.md @@ -0,0 +1,84 @@ +--- +name: cpn-issue +description: + "Use when opening, triaging, or closing an issue in this repo: French + templates, acceptance ledger, additive triage." +version: 1.0.0 +license: Apache-2.0 +--- + +# Console issues + +Issue-first repo norm: no PR without an issue behind it (lifecycle in the +`cpn-dev-workflow` skill, link-up in `cpn-pr`). + +## Prerequisites + +- Issues live on `cloud-pi-native/console`. +- `gh` authenticated with write access, verified: + +```bash +gh api user --jq .login # authenticated +gh api repos/cloud-pi-native/console --jq .viewerPermission # write to triage +``` + +An unmet requirement is a reported blocker, never a silent scope change. + +## Open + +1. Search before creating — reuse a matching open issue instead of a + duplicate: `gh issue list --repo cloud-pi-native/console --state open + --search ""`. +2. Title `🐛 [BUG] - ` or `💡 [REQUEST] - `, via + `.github/ISSUE_TEMPLATE/`; label `bug` / `enhancement`. +3. Body in **French**, from the template: problem statement (need, scope, + impact) plus a `- [ ]` **Définition du fini** acceptance tasklist as the + work ledger — never the solution; findings and analysis go in comments. +4. Free-text rules: natural paragraphs, no hard wrapping, never run a + formatter over a body; a literal `@` in prose triggers a user/team mention + — wrap it in a code span. + +```bash +gh issue create --repo cloud-pi-native/console \ + --title "💡 [REQUEST] - " --label enhancement --body-file +``` + +## Triage + +Fill each empty, determinable field, additively (`--add-label` / +`--add-assignee`, never `--label`); never invent a value the repo doesn't +have — filter labels against `gh label list`: + +```bash +gh issue edit --repo cloud-pi-native/console \ + --add-label