Alex Gleason
bd68a32708
Extract eleven topic areas into loadable skills so AGENTS.md can serve as a scannable overview instead of a specification dump. The file shrinks from 1480 to 358 lines (~76%) while keeping every concrete rule, critical code pattern, and pointer that an agent needs on first read. New Ditto-specific skills: - nostr-kinds: NIP-vs-custom-kind decision framework, kind ranges, tag design, content-vs-tags, NIP.md update rule, and Ditto's seven-location UI registration checklist for new kinds (NoteCard, PostDetailPage, extraKinds.ts, KIND_LABELS/KIND_ICONS in CommentContext, WELL_KNOWN_KIND_LABELS in ExternalContentHeader, EmbeddedNote/EmbeddedNaddr, ReplyComposeModal). - nostr-publishing: useNostrPublish, the read-modify-write pattern via fetchFreshEvent + prev for replaceable/addressable events, published_at contract, and d-tag collision prevention. - nostr-queries: the standard useNostr + useQuery pattern, combining kinds into one filter to avoid rate limits, and the NIP-52 validator walkthrough. - theming: @fontsource install flow, the Ditto runtime font-loader path (sanitizeUrl + sanitizeCssString), color scheme variables, useTheme toggle, and the isolate + negative-z-index gotcha. - ci-cd-publishing: Zapstore NIP-46 bunker auth (zsp + nip46-auth.mjs), nsite deploys (nsyte nbunksec + configured relays/servers), and Google Play AAB uploads via fastlane supply (service-account JSON base64 encoding and rotation). - capacitor-compat: WKWebView/WebView limitations, the downloadTextFile / openUrl helpers in src/lib/downloadFile.ts, platform detection, and the full plugin list. - git-workflow: pre-commit validation order and the Regression-of: trailer convention used by the release skill's changelog generator. Ported from mkstack, lightly adapted where needed: - nip19-routing: root-level /:nip19 routing and filter construction patterns (adapted to reference Ditto's existing NIP19Page). - nostr-relay-pools: nostr.relay() and nostr.group() for targeted queries. - nostr-encryption: NIP-44 / NIP-04 via the user's signer. - file-uploads: useUploadFile + Blossom + NIP-94 imeta tag construction. AGENTS.md itself now follows mkstack's density — concrete rules inline, one code example per section, pointer to the matching skill for details. The enumerations that previously bloated it (every shadcn primitive, every hook, every Capacitor plugin, the full NostrMetadata type dump, the NIP-19 prefix reference table, etc.) are either removed in favor of "ls the directory" or moved into their skill.
3.3 KiB
name, description
| name | description |
|---|---|
| git-workflow | Ditto's git conventions — validating changes before committing, writing commit messages that match project style, and attributing regressions with a Regression-of trailer so the release changelog skill can filter them from the "Fixed" section. |
Git Workflow
Ditto expects every completed task to end with a git commit. This skill covers the pre-commit validation loop, commit-message conventions, and the Regression-of: trailer used by the release skill to filter intra-release regressions from the changelog.
Pre-commit Validation
Your task is not finished until the code type-checks and builds without errors. In priority order:
- Type Checking (required) —
tsc --noEmit - Building/Compilation (required) —
vite build - Linting (recommended; fix anything critical) —
eslint - Tests (if available) —
vitest run - Git commit (required)
The full npm run test script runs all of these in sequence; running it is equivalent to steps 1–4.
Using Git
Use git status and git diff to review changes, and git log to learn the project's commit-message conventions before writing a new one. If you make a mistake, git checkout restores files.
When your changes are complete and validated, create a commit with a message that focuses on why the change was made (not just what). Summaries should fit on one line; a body is warranted for non-trivial changes.
Always commit when you are finished making changes. Non-negotiable — every completed task ends with a commit. Don't leave uncommitted changes.
Contributing Guide
When preparing changes for a merge request, also follow the guidelines in CONTRIBUTING.md. It includes a self-review checklist (step 8) that should be run against your diff before committing.
Attributing Regressions
When a commit fixes a bug that was introduced by an identifiable prior commit, add a Regression-of: trailer at the bottom of the commit message body referencing the offending commit's short SHA:
Fix missing background on expanded emoji picker in feeds
The compose box overhaul accidentally dropped the bg-background class
when refactoring the picker out of QuickReactMenu.
Regression-of: 3aa08ba9
This is a standard Git trailer (compatible with git interpret-trailers) that records the cause-and-effect link directly in history. It is consumed by the release skill to detect intra-release regressions and exclude them from the changelog's "Fixed" section, and it makes future debugging and post-mortems substantially faster.
When to add it
- The commit fixes a bug (not a new feature, refactor, or doc change).
- The introducing commit is identifiable with reasonable effort.
When to skip it
- The bug is pre-existing with no clear single origin.
- The behavior was always wrong (no regression).
- The introducing commit cannot be determined after a brief search.
Finding the introducing commit
git log -S '<removed-or-changed-string>'— find commits that touched a specific string.git log --oneline -- path/to/file— list all commits touching a file.git blame -L <start>,<end> -- path/to/file— find who last changed specific lines.
This convention is strongly recommended but not required. When the origin is non-obvious, prioritize shipping the fix over hunting indefinitely.