From e6dbd9877c9adf71a864f63f95e34fea8d35e0b4 Mon Sep 17 00:00:00 2001 From: Ovi Trif Date: Wed, 6 May 2026 15:30:28 +0200 Subject: [PATCH 1/2] chore: improve agent PR QA notes --- {.claude => .agents}/commands/pr.md | 77 +++++++++++++++++++----- {.claude => .agents}/commands/release.md | 0 .claude/commands | 1 + AGENTS.md | 6 +- 4 files changed, 69 insertions(+), 15 deletions(-) rename {.claude => .agents}/commands/pr.md (57%) rename {.claude => .agents}/commands/release.md (100%) create mode 120000 .claude/commands diff --git a/.claude/commands/pr.md b/.agents/commands/pr.md similarity index 57% rename from .claude/commands/pr.md rename to .agents/commands/pr.md index de2c514b..fa148d5d 100644 --- a/.claude/commands/pr.md +++ b/.agents/commands/pr.md @@ -102,27 +102,76 @@ This PR adds support for... - Minimize code and file references like `TheClassName` or `someFunctionName`, `thisFileName.ext` - Exception: for refactoring PRs (1:10 ratio of functionality to code changes), more technical detail is ok -**QA Notes / Testing Scenarios:** -- Structure with numbered headings and steps -- Make steps easily referenceable -- Be specific about what to test and expected outcomes +**Custom Instructions:** +When the user provides custom instructions after `--`: +- Parse any referenced commit SHAs and read their full messages +- Focus the description content on areas the user emphasizes +- Structure QA Notes according to user's specific manual testing instructions and automated coverage notes +- Custom instructions take priority over default generation rules for sections they address +- Preserve exact manual testing steps provided by the user (don't summarize or omit details) +- If custom instructions include automated checks or coverage notes, place them under `#### Automated Checks` + +**QA Notes / Validation:** +- QA Notes separate actionable human QA instructions from automated verification coverage. +- Always use this structure: + ```md + ### QA Notes + #### Manual Tests + #### Automated Checks + ``` +- Keep local verification commands, `xcodebuild`, Swift tests, SwiftFormat, translation validation, unit tests, build passes, cargo test, cargo clippy, npm test, typecheck, CI coverage, or similar automated checks out of `#### Manual Tests`; summarize them under `#### Automated Checks` when they add useful context. +- Use `#### Automated Checks` to summarize automated verification evidence, prioritizing coverage added, modified, or removed with file paths and a short explanation. +- For removed automated coverage, state why it was removed. +- Do not list standard CI or PR bot commands as checkbox items just because they run for every PR. If standard CI coverage is worth mentioning, summarize it in one sentence. +- List raw commands only when they were run locally, are non-standard, use special flags or environment values, validate workflow behavior, or explain a meaningful verification gap. +- For workflow behavior validation, include `(after merge)` in the automated check item because workflow changes only take effect for PRs opened after the workflow update merges. +- If no actionable manual validation exists, write `N/A` under `#### Manual Tests`. +- If no automated checks were run and no automated coverage changed, write `N/A` under `#### Automated Checks`. +- Write manual tests using this template: + ```md + - [ ] **{numbering}.** {optional_condition + →} {screen_action} → {next_screen_action}: expectation + ``` +- Use a list of unchecked checkboxes for each individual test. +- Use a numbered prefix for each test, in bold, for example `**1.**`, `**2.**`. +- Use `regression:` for regression checks, positioned after the numbering. +- Use sub-lists for variations of the same test. +- Use letter suffixes in numbering for each variation when a test has a sub-list, for example `**3a.**`, `**3b.**`. +- Always use `→` to denote navigation, for example `Send → Amount`. +- Use screen names from code, formatted as separate words without the `View` or `Screen` suffix, for example `FundReceiveView` becomes `Fund Receive`. +- Use short-form wording like `in-sheet` for sheet screens, `nav` for navigation, `back` for back nav, and `LN` for Lightning Network. **For library repos (has `bindings/` directory or `Cargo.toml`):** -Structure QA Notes around testing and integration: +Structure manual QA around integration validation only. Automated checks belong under `#### Automated Checks`. Example: ``` ### QA Notes +#### Manual Tests +- [ ] **1.** Consumer app → exercise updated binding flow: behavior matches previous release. +- [ ] **2.** `regression:` iOS integration screen → trigger changed API path: no crash or stale data. +#### Automated Checks +- Binding tests added: cover updated iOS API path in `bindings/ios/...`. +- CI: standard cargo and binding checks run by the PR bot. +``` -#### Testing -- [ ] `cargo test` passes -- [ ] `cargo clippy` clean -- [ ] Android bindings: `./build_android.sh` -- [ ] iOS bindings: `./build_ios.sh` - -#### Integration -- Tested in: [bitkit-android#XXX](link) -- Or N/A if internal refactor with no API changes +Concrete style target: +```md +### QA Notes +#### Manual Tests +- [ ] **1.** No usable channels/spending balance → scan LN invoice: error shows immediately, not after 15s. +- [ ] **2.** Scanner → scan fixed amount LN invoice: Send Confirm or QuickPay opens directly. +- [ ] **3a.** `regression:` Send → scanner/paste fixed amount LN invoice: in-sheet nav to Confirm or QuickPay. + - [ ] **3b.** `regression:` Variable amount LN invoice/LNURL-pay: lands on Amount view. +- [ ] **4a.** Activity Detail of LN transfer → tap Connection: lands on Channel Detail. + - [ ] **4b.** back: returns to Activity Detail. +- [ ] **5a.** Settings → Lightning Connections → tap channel: still opens Channel Detail. + - [ ] **5b.** back: returns to Connections List. +- [ ] **6.** `regression:` Channel Detail → tap Close Connection: works. +#### Automated Checks +- Unit tests added: cover invoice timeout handling in `BitkitTests/TransferViewModelTests.swift`. +- Unit tests modified: update channel navigation assertions in `BitkitTests/ChannelDetailsViewModelTests.swift`. +- Test coverage removed: delete stale mock-only assertions from `BitkitTests/OldFlowTests.swift` because the flow no longer exists. +- CI: standard build and test checks run by the PR bot. ``` **Preview Section (conditional):** diff --git a/.claude/commands/release.md b/.agents/commands/release.md similarity index 100% rename from .claude/commands/release.md rename to .agents/commands/release.md diff --git a/.claude/commands b/.claude/commands new file mode 120000 index 00000000..1ea3574a --- /dev/null +++ b/.claude/commands @@ -0,0 +1 @@ +../.agents/commands \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index f0e0f636..7ef24be4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,14 @@ # AGENTS.md -This file provides guidance to AI agents like Claude Code (claude.ai/code) when working with code in this repository. +This file provides guidance to Codex, Claude Code, and Cursor when working with code in this repository. This file is symlinked for cross-agents compatibility to the following paths: - `CLAUDE.md` +## Agent Commands + +Durable shared agent command specs live in `.agents/commands/`. For PR creation, follow `.agents/commands/pr.md`; `.claude/commands` is a compatibility symlink to the same files. + ## Project Overview Bitkit iOS is a native Swift implementation of a Bitcoin and Lightning Network wallet. This is a work-in-progress repository that is **NOT** the live production app. The production app uses React Native and is at github.com/synonymdev/bitkit. From 91c66ad6e6707861e90c7cf491e86ad87d1b292b Mon Sep 17 00:00:00 2001 From: Ovi Trif Date: Wed, 6 May 2026 15:35:19 +0200 Subject: [PATCH 2/2] docs: clarify cursor command instructions --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7ef24be4..e137bd12 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ This file is symlinked for cross-agents compatibility to the following paths: ## Agent Commands -Durable shared agent command specs live in `.agents/commands/`. For PR creation, follow `.agents/commands/pr.md`; `.claude/commands` is a compatibility symlink to the same files. +Durable shared agent command specs live in `.agents/commands/`. For PR creation, follow `.agents/commands/pr.md`; `.claude/commands` is a compatibility symlink and Cursor command entries under `.cursor/commands/` resolve to the same files. ## Project Overview