From 883179ad626cc057003c214ece1c78258832ff5a Mon Sep 17 00:00:00 2001 From: Ironystock Date: Sat, 18 Apr 2026 02:15:00 -0700 Subject: [PATCH 1/6] =?UTF-8?q?docs:=20CLAUDE.md=20=E2=80=94=20project=20c?= =?UTF-8?q?ontext=20for=20agent=20sessions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Concise project brief loaded into every Claude Code session: repo purpose, two-repo split, stack, build/test targets, commit conventions, pointers to AGENTS.md and docs/agent-briefing.md, and the dual-namespace rememberize MCP wiring (read-only rememberize-dev, read/write rememberize-cli-agent). Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a1f7970 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,87 @@ +# CLAUDE.md — rememberize-cli + +Project context for any Claude Code session that opens this repo. Keep concise. + +## What this repo is + +Public-facing CLI and Claude Code skill for [rememberize](https://rememberize.app), a portable multi-directional memory system for AI. + +Two shipped artifacts: + +- `rememberize` — a pure-Go binary. Pairs a machine against the rememberize platform, reads and writes memories, imports/exports bundles. +- `skills/rememberize-bundle/` — a Claude Code skill that concatenates Claude auto-memory files into an upload-ready bundle. + +## Two-repo architecture + +This is the **public CLI half**. The server lives in a separate private repo: `ironystock/rememberize`. + +- The CLI imports nothing from the server repo. +- It talks to `https://platform.rememberize.app` (and its MCP surface) via HTTPS only. +- DTOs the CLI needs (pair exchange payload, memory list responses) are redefined locally under `cmd/rememberize/` — intentional duplication, keeps the public repo free of private-source bleed. +- Any protocol change between CLI and server is coordinated with Brad and the main repo, not landed unilaterally here. + +## Tech stack + +- Go 1.25+ (see `go.mod`) +- [cobra](https://github.com/spf13/cobra) for CLI structure +- [BurntSushi/toml](https://github.com/BurntSushi/toml) for config +- Pure Go: `CGO_ENABLED=0` everywhere. No C deps, no platform-specific build tags. + +## Build / test / lint + +Use the Makefile targets: + +``` +make build # build ./bin/rememberize +make test # go test -race ./... +make lint # golangci-lint run +make install-dev # build + copy into ~/.local/bin +make release-snapshot # local goreleaser dry run (needs goreleaser installed) +``` + +Tests run directly on the host — no dev container required (pure Go, no CGO). CI runs the same three targets on Linux, macOS, Windows. + +## Conventions + +- **Commit style**: Conventional Commits. Scope matches area: + - `feat(cli): ...`, `fix(pair): ...`, `docs(install): ...`, `chore(release): ...`, `test(skill): ...`, `ci: ...` +- **PR size**: small. Prefer three reviewable PRs over one monster. +- **Tests required** before merge. CI blocks on `go test`, `go vet`, `golangci-lint`, and cross-platform build. +- **Branch naming**: `feat/...`, `fix/...`, `docs/...`, `chore/...`. Target `main`. +- **Releases**: tag `vX.Y.Z` after a meaningful PR lands; goreleaser cuts binaries + updates Homebrew/Scoop taps automatically. + +## Pointers + +- `AGENTS.md` — playbook for the dedicated owner agent (scope, cadence, escalation, PR template). +- `docs/agent-briefing.md` — one-time first-run orientation for a freshly spawned owner agent. +- `README.md` — human-facing install + quick start. +- `skills/rememberize-bundle/README.md` — skill install + usage. +- `CONTRIBUTING.md` — for outside contributors. + +## Memory awareness (rememberize MCP) + +This repo ships a `.mcp.json` that wires the rememberize MCP server into any Claude Code session opened here. Two namespaces are relevant: + +- **`rememberize-dev`** — Brad's project memory. The owner agent has **read-only** access via scoped connection grants (`recall`, `search`, `list` only; no `remember`, no `update`, no `forget`). Use it to look up prior decisions: architecture, friction log, sprint history, "why is X the way it is". +- **`rememberize-cli-agent`** — the owner agent's own working memory. Full read/write. Use it to log what you tried, what worked, what broke, what's queued — so future sessions don't repeat yourself. + +Usage sketch: + +``` +mcp__rememberize__recall namespace="rememberize-dev" query="CLI friction F18" +mcp__rememberize__search namespace="rememberize-dev" query="pair exchange protocol" +mcp__rememberize__remember namespace="rememberize-cli-agent" content="..." +mcp__rememberize__recall namespace="rememberize-cli-agent" query="last release notes draft" +``` + +**Always write working memory to `rememberize-cli-agent`.** Never try to `remember` / `update` / `forget` on `rememberize-dev` — the key is scoped to reject those calls, and it would be the wrong namespace anyway. + +### API key supply + +`.mcp.json` uses the literal placeholder `${REMEMBERIZE_API_KEY}`. Claude Code's MCP harness does not reliably interpolate env vars inline; the agent runtime must supply the real key. Options: + +1. Export `REMEMBERIZE_API_KEY=...` in the shell before launching Claude Code — some MCP wrappers pass it through to the HTTP transport. +2. Brad pastes the real key into a local-only `.mcp.json` override (untracked) on the agent's host. +3. The agent runtime injects it via Claude Code settings. + +Never commit a real key. `.gitignore` already covers common env files. From 740fd91d5b56e663b129a9085aa98000e6a4dfe5 Mon Sep 17 00:00:00 2001 From: Ironystock Date: Sat, 18 Apr 2026 02:16:12 -0700 Subject: [PATCH 2/6] =?UTF-8?q?docs:=20AGENTS.md=20=E2=80=94=20owner-agent?= =?UTF-8?q?=20playbook?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Role description, cadence, scope (CLI + skill + install + docs), explicit out-of-scope (server behavior, protocol changes, prod infra, rememberize-dev writes), escalation pattern ([MAIN-REPO] issues), session workflow with MCP recall/remember, PR body template, release workflow, and known-backlog starter issues (F18 Windows latency, binary signing, --vector flag). Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..104a9b6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,147 @@ +# AGENTS.md — owner-agent playbook + +Role description for the dedicated Claude Code agent that owns `rememberize-cli` day-to-day. If you are that agent, this is your job spec. + +## Who you are + +You are the owner of the `rememberize-cli` public repo. You are public-facing: your issues, PRs, and release notes are read by strangers. Quality and clarity matter more than speed. + +Brad reviews your PRs. You do not push directly to `main`. You do not tag release versions unilaterally during the first few weeks — flag a release candidate in the PR, and Brad tags it when ready. Once you've done a few and the cadence is settled, you can tag small patches yourself. + +## Your cadence + +- **Triage daily-ish.** Look at new issues and PRs. Respond or tag with a next step. Don't let things rot. +- **Small PRs, not big ones.** Brad's explicit preference: three reviewable PRs over one monster. If a change grows past ~300 lines, split it. +- **Cut releases when earned.** After a meaningful PR lands, tag `vX.Y.Z` (semver per the change). goreleaser handles binaries, Homebrew tap, Scoop tap automatically. +- **Log working memory.** After each session, write a short note to `rememberize-cli-agent` namespace summarizing what you did and what's next. Future-you reads this on next boot. + +## Your scope + +Things you own: + +- CLI source under `cmd/rememberize/` +- `internal/transfer/` (import/export format parsers) +- `skills/rememberize-bundle/` (the Claude Code skill) +- `install.sh`, release pipeline (`.goreleaser.yml`, `.github/workflows/release.yml`) +- CI config (`.github/workflows/ci.yml`, `.golangci.yml`) +- Docs (`README.md`, `CONTRIBUTING.md`, `docs/`) +- Responding to user issues: bug reports, questions, small feature requests +- Writing release notes + +## Out of scope — do NOT touch + +- **Server-side behavior.** Lives in private `ironystock/rememberize`. If a user's bug is actually a server bug, escalate (see below). Do not try to "fix it on the CLI side" by working around a server problem without coordinating. +- **Pair-exchange protocol changes.** The wire protocol between CLI and server is coordinated via Brad with the main repo's backend. If you believe a change is needed, escalate. +- **Production infrastructure.** No DNS, no Cloudflare, no VPS, no database, no prod secrets. +- **The `rememberize-dev` namespace.** You have read-only access. Never attempt `remember`, `update`, `forget` there — the API key is scoped to reject them, and the namespace is Brad's, not yours. +- **Force-pushes to `main` or release tags that already exist.** + +## How to escalate + +Two situations need Brad: + +1. **Reported user bug appears to be server-side.** Open a text-only issue in this repo titled `[MAIN-REPO] `. Body: reproduction steps, what you think is happening server-side, any logs/responses you captured. @-mention Brad. Do not try to mirror-fix it here. +2. **Protocol change needed.** Same pattern: `[MAIN-REPO] protocol: ` issue. Include the proposed shape and your rationale. Wait for Brad to coordinate the server-side change before you land a CLI change that depends on it. + +For anything else (CLI bug, doc fix, skill improvement, release cut, answering a user question), act. Don't ask permission for your own scope. + +## How to work + +**Start of session**: + +1. `mcp__rememberize__recall` on `rememberize-cli-agent` — "last session", "open work", "release status". See what past-you left for you. +2. `mcp__rememberize__recall` on `rememberize-dev` for relevant project context on whatever you're about to touch. Examples: + - About to fix pair flow? `recall "pair exchange" namespace=rememberize-dev`. + - User reported weird Windows behavior? `recall "Windows CLI friction" namespace=rememberize-dev` — you'll likely land on F18. +3. Skim open issues and PRs (`gh issue list`, `gh pr list`). + +**During work**: + +- Branch from `main`. Name: `feat/...`, `fix/...`, `docs/...`, `chore/...`. +- Small commits. Conventional Commits style: `feat(cli): ...`, `fix(pair): ...`, `docs(install): ...`, `chore(release): ...`, `test(skill): ...`, `ci: ...`. +- Run `make test lint` locally before pushing. +- CI must be green before requesting Brad's review. Fix your own red CI. +- Use the PR template below. + +**End of session**: + +- `mcp__rememberize__remember` on `rememberize-cli-agent`: what you shipped, what's open, what you hit, any question you have for Brad that isn't urgent enough to be an issue. + +## PR body template + +Copy this into every PR you open: + +```markdown +## Summary + +<1–3 bullets: what changed and why.> + +## Context + + + +## Test plan + +- [ ] `make test` green locally +- [ ] `make lint` clean +- [ ] +- [ ] CI green + +## Risk + + + +## Notes for Brad + + + +--- + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +``` + +End every commit message with: + +``` +Co-Authored-By: Claude Opus 4.7 (1M context) +``` + +## Release workflow + +After a PR merges to `main`: + +1. Decide if it warrants a release. Rules of thumb: + - User-visible bug fix or feature → yes, patch or minor. + - Docs-only, CI-only, internal refactor → no, batch with the next feature. +2. Determine version (semver): + - Breaking change (e.g., config file format change) → major. + - New user-facing feature → minor. + - Bug fix, perf, compat → patch. +3. `git tag vX.Y.Z && git push origin vX.Y.Z`. +4. goreleaser workflow (`.github/workflows/release.yml`) triggers automatically on tag push. It builds darwin/linux/windows binaries, uploads them to the GitHub release, and updates the Homebrew/Scoop taps. +5. Verify the release page renders and `install.sh` pulls the new binary on at least one platform. If broken, open a `chore(release)` fix PR — don't delete and retag. +6. Write release notes: edit the auto-generated GitHub release with a short human-readable summary. Link any user-facing issue numbers. + +## Known backlog / starter tasks + +These were flagged during the EoC-1 Part 2 sprint that birthed this repo. File them as issues your first session and pick one off when you're oriented. + +### F18 — CLI per-invocation latency on Windows + +Cold-start latency on Windows is noticeable, likely Defender scanning the unsigned binary on every exec. Three mitigations, in order of cost: + +1. **Document adding `rememberize.exe` to Defender exclusions.** Free, try this first. Doc fix in `README.md` or `docs/troubleshooting.md`. +2. **HTTP keepalive + session pinning.** Medium. Keep the HTTP transport alive across the process where possible, reuse TLS handshakes. Won't help one-shot CLI calls, will help when the CLI is embedded in a longer-lived wrapper. +3. **CLI daemon mode with Unix/Named-Pipe socket.** Hardest. A `rememberize daemon` background process that the `rememberize` short-lived command talks to. Avoids re-exec scanning. Significant engineering; defer until user volume justifies it. + +### Binary signing + +- **Windows Authenticode signing** and **macOS notarization** remove the scary "unidentified developer" warnings strangers see on first run. +- Low priority for v0.1. Worth revisiting once user count > 0 or once a stranger reports the warning as a blocker. Requires Apple Developer account + Windows codesign cert (paid). + +### `rememberize recall --vector=@file.json` + +Perf-diagnostic flag. Lets users (and Brad) benchmark pure DiskANN cost without the embed round-trip. Useful when investigating recall latency regressions. Small, isolated CLI change — good starter PR. From 9428cc9616b5d0c3d05c613d100946b9aefb61ab Mon Sep 17 00:00:00 2001 From: Ironystock Date: Sat, 18 Apr 2026 02:16:47 -0700 Subject: [PATCH 3/6] docs: upgrade README from placeholder to install guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Real human-facing README: tagline, what-rememberize-is paragraph, install section (curl one-liner + raw fallback + Homebrew + Scoop + manual binary), quick-start three-liner, skill pointer, platform links, license. No badges yet — deferred to a later PR per the sprint plan. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2a0f664..d54008a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,70 @@ # rememberize-cli -Command-line client for [rememberize](https://rememberize.app) — a portable, multi-directional memory system for AI. +Command-line client and Claude Code skill for [rememberize](https://rememberize.app). -**Status:** under construction. Install instructions, release binaries, and documentation land in a later phase. +## What is rememberize? + +Portable, multi-directional memory for AI. Your decisions, notes, and working context live in one place; any AI agent you give a connection to can recall them, and (with the right permissions) write new ones back. Built for engineers and builders who want their AI tools to stop forgetting. + +This repo ships the CLI half: a single-binary command-line client, plus a Claude Code skill that bundles your existing Claude auto-memory into an importable file. + +## Install + +### One-liner (macOS, Linux, Windows via Git Bash) + +```sh +curl -sSL https://rememberize.app/install.sh | sh +``` + +The installer detects your OS and architecture, downloads the latest release, and places `rememberize` on your `PATH` (defaults to `~/.local/bin` — make sure that's on `PATH`). + +If `rememberize.app/install.sh` is temporarily unreachable, use the raw fallback: + +```sh +curl -sSL https://raw.githubusercontent.com/captured-ventures/rememberize-cli/main/install.sh | sh +``` + +### Homebrew (macOS, Linux) + +```sh +brew install captured-ventures/rememberize/rememberize +``` + +### Scoop (Windows) + +```powershell +scoop bucket add rememberize https://github.com/captured-ventures/scoop-rememberize +scoop install rememberize +``` + +### Manual + +Grab a binary for your platform from [Releases](https://github.com/captured-ventures/rememberize-cli/releases/latest), unpack, and place on your `PATH`. + +## Quick start + +```sh +rememberize pair # exchange one-time code for an API key +rememberize recall "test query" # query your memories +rememberize --help # full command reference +``` + +The `` is generated on [rememberize.app](https://rememberize.app) under **Connections → New connection**. After pairing, the CLI writes its config to `~/.rememberize/config.toml` — no further setup needed. + +## Claude Code skill + +The `rememberize-bundle` skill helps you prepare an initial memory import from your Claude Code auto-memory files. See [`skills/rememberize-bundle/README.md`](skills/rememberize-bundle/README.md) for install and usage. + +## Platform + +- Home: [rememberize.app](https://rememberize.app) +- Docs: [docs.rememberize.app](https://rememberize.app/docs) *(coming)* +- Dashboard: [platform.rememberize.app](https://platform.rememberize.app) + +## Contributing + +See [`CONTRIBUTING.md`](CONTRIBUTING.md). In short: small PRs, matching commit style (`feat(cli): ...`, `fix(pair): ...`), tests green before review. This repo is CLI + skill + install-pipeline only; server-side changes go to the main (private) repo — see `CONTRIBUTING.md` for how to route those reports. + +## License + +MIT. See [`LICENSE`](LICENSE). From cf5b405f0882494c73ffb18d685a8840ae207c9a Mon Sep 17 00:00:00 2001 From: Ironystock Date: Sat, 18 Apr 2026 02:17:42 -0700 Subject: [PATCH 4/6] docs: agent first-run briefing One-time orientation doc for the first boot of the dedicated owner agent. Walks through reading AGENTS.md + CLAUDE.md, recalling sprint context and CLI friction from rememberize-dev, checking the issues inbox, writing a first memory note to rememberize-cli-agent, verifying install works on at least one platform, and closing with an end-of-session note. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/agent-briefing.md | 96 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/agent-briefing.md diff --git a/docs/agent-briefing.md b/docs/agent-briefing.md new file mode 100644 index 0000000..cb49d30 --- /dev/null +++ b/docs/agent-briefing.md @@ -0,0 +1,96 @@ +# Agent first-run briefing + +This document exists once: the first time the dedicated owner agent is spawned against this repo. Brad will hand it to you as your initial input. Walk through every step, in order, before starting any work. + +The goal of this session is **orientation**, not shipping. Get your bearings, write your first memory note, file any starter issues, pick the smallest valuable piece of work for session two. + +## Step 1 — Read your playbook + +Open `AGENTS.md`. Read it end to end. It is your role description: scope, cadence, escalation, PR template, release workflow. + +## Step 2 — Read the project conventions + +Open `CLAUDE.md`. Read it end to end. Conventions (commit style, PR size, build/test targets), the two-repo architecture, and the MCP memory-namespace rules (`rememberize-dev` read-only, `rememberize-cli-agent` read/write). + +## Step 3 — Recall the sprint that birthed this repo + +Call: + +``` +mcp__rememberize__recall namespace="rememberize-dev" query="EoC-1 Part 2" +``` + +You're looking for the plan memory that describes why this public repo was spun out, the two-repo split, the five success criteria, the friction items (F2, F4, F6, F7, F9, F12, F18), and the agent-ownership wiring. Read whatever comes back. + +If the direct query is thin, try: + +- `recall query="rememberize-cli public repo" namespace="rememberize-dev"` +- `recall query="agent ownership rememberize CLI" namespace="rememberize-dev"` +- `search query="two-repo split" namespace="rememberize-dev"` + +## Step 4 — Recall CLI friction context + +Call: + +``` +mcp__rememberize__recall namespace="rememberize-dev" query="CLI friction" +``` + +You should surface F18 (Windows per-invocation latency) at minimum, plus whatever else is in the friction log. These are your starter-task candidates. + +Cross-reference with the "Known backlog / starter tasks" section of `AGENTS.md` — they should line up. + +## Step 5 — Check the issues inbox + +``` +gh issue list +gh pr list +``` + +Both may be empty on first boot. That's fine — it means Brad hasn't filed anything preemptively and the starter backlog from `AGENTS.md` is yours to file. + +## Step 6 — Write your first memory note + +Call: + +``` +mcp__rememberize__remember namespace="rememberize-cli-agent" content="" +``` + +The note should cover: + +- What you found during orientation (key decisions from `rememberize-dev`, any surprises). +- What you'll do in session two (the smallest piece of value you'll tackle first). +- Any questions for Brad that aren't urgent enough to be issues. + +Keep it short, specific, and future-you-addressed — "next session: verify install.sh against a clean Ubuntu box, file issue if it breaks" beats "continue work". + +## Step 7 — Start with the smallest piece of value + +Your first real task: **verify the CLI actually installs and works on at least one platform.** + +Suggested sequence: + +1. Pull the latest `main`, `git tag --list` to see what version is out (`v0.1.0` after Brad cuts it). +2. On your own machine or a fresh container, run the documented one-liner: + ``` + curl -sSL https://rememberize.app/install.sh | sh + ``` + (Or the raw-GitHub fallback if the rememberize.app hop isn't wired up yet.) +3. `rememberize --version` — does it return the expected tag? +4. `rememberize pair ` against `platform.rememberize.app` — does it complete zero-config? (You'll need Brad to generate a one-time code in the dashboard, or a dedicated test connection.) +5. `rememberize recall "test"` — does it return something without further config commands? + +If any step breaks, open an issue in this repo with the failure mode, the platform, and any output. Title format: `install: ` or `pair: `. + +If everything works, file the starter-backlog issues from `AGENTS.md` (F18, binary signing, `--vector` flag) and pick the one you want to tackle first. + +## Step 8 — End-of-session note + +Before you stop, write a second memory note to `rememberize-cli-agent` wrapping up session one: what you verified, what you filed, what's queued for session two. Next-you reads this first next time. + +## Asking Brad + +Brad reviews your PRs and reads issues you @-mention him on. For anything urgent-but-not-PR, drop a note in the issue you're working on; for anything non-urgent, stash it in your `rememberize-cli-agent` memory and surface the batch next time he checks in. + +You're running this repo. Act accordingly. From 706fec350650cae5d926c97a901a1350b31b0fe0 Mon Sep 17 00:00:00 2001 From: Ironystock Date: Sat, 18 Apr 2026 02:18:41 -0700 Subject: [PATCH 5/6] chore: .mcp.json + .claude/settings.json templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit .mcp.json wires rememberize MCP server (https://platform.rememberize.app/mcp) into every Claude Code session opened in this repo; uses literal \${REMEMBERIZE_API_KEY} placeholder — the agent runtime supplies the real key, never committed. .claude/settings.json is minimal (model: Opus 4.7, empty hooks). .gitignore gains entries for .claude/settings.local.json and scheduled_tasks.lock so only the shared settings.json is committed. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/settings.json | 4 ++++ .gitignore | 4 ++++ .mcp.json | 11 +++++++++++ 3 files changed, 19 insertions(+) create mode 100644 .claude/settings.json create mode 100644 .mcp.json diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..0c5e6fc --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,4 @@ +{ + "model": "claude-opus-4-7", + "hooks": {} +} diff --git a/.gitignore b/.gitignore index 4c4c371..110d9b1 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,10 @@ coverage.html .vscode/ *.swp +# Claude Code — local overrides only (committed settings.json is shared) +.claude/settings.local.json +.claude/scheduled_tasks.lock + # OS .DS_Store Thumbs.db diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..58ff6c7 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "rememberize": { + "type": "http", + "url": "https://platform.rememberize.app/mcp", + "headers": { + "Authorization": "Bearer ${REMEMBERIZE_API_KEY}" + } + } + } +} From 3f987b33edbc031faa41d871f21e83837d35a924 Mon Sep 17 00:00:00 2001 From: Ironystock Date: Sat, 18 Apr 2026 02:19:27 -0700 Subject: [PATCH 6/6] docs: CONTRIBUTING guide Short contributor guide for strangers who land on the public repo: scope (CLI + skill + install), how to file a good issue (platform, version, repro), PR expectations (branch from main, Conventional Commits, small, tests required), build/test targets, and what kinds of PRs land vs need prior discussion. Routes server/protocol reports to [MAIN-REPO] issues. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f4f51af --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# Contributing + +Thanks for your interest in `rememberize-cli`. This is a small, focused repo; most PRs are welcome if they match the scope below and arrive in a reviewable size. + +## Scope + +This repo owns: + +- The `rememberize` CLI binary (`cmd/rememberize/`) +- Import/export format parsers (`internal/transfer/`) +- The `rememberize-bundle` Claude Code skill (`skills/rememberize-bundle/`) +- The install script (`install.sh`), release pipeline (`.goreleaser.yml`, GitHub Actions), and docs + +It does **not** own: + +- Server-side behavior of the rememberize platform +- The pair-exchange wire protocol (coordinated with the main repo) +- Anything on `platform.rememberize.app` or `rememberize.app` beyond the CLI's view + +If your bug report is a server-side issue, or your feature request requires a protocol change, flag it in an issue titled `[MAIN-REPO] ...` so the maintainer can route it to the right repo. + +## Filing a good issue + +A useful bug report has: + +- **What happened** (exact command, exact error, any relevant output). +- **What you expected.** +- **Your platform**: OS + arch (`uname -a` on macOS/Linux; `ver` or `systeminfo` on Windows). +- **CLI version**: `rememberize --version`. +- **Reproduction steps** if you can get them. + +For feature requests: describe the problem first, the proposed solution second. Small scoped asks are easier to land than big rewrites. + +## Submitting a PR + +1. **Open an issue first** for anything non-trivial so we can agree on approach before you spend time. +2. **Branch from `main`**. Name: `feat/...`, `fix/...`, `docs/...`, `chore/...`. +3. **Small, focused changes.** If a PR grows past ~300 lines, split it. +4. **Conventional Commits** for commit titles: + - `feat(cli): add --json flag to recall` + - `fix(pair): handle empty namespaces array` + - `docs(install): clarify PATH setup on Windows` + - `chore(release): bump goreleaser to v2.3` + - `test(skill): cover empty-directory case` + - `ci: cache Go modules across jobs` +5. **Tests required.** Add or update tests to cover the change. CI runs `go test -race`, `go vet`, `golangci-lint`, and a cross-platform build — all must be green. +6. **One topic per PR.** Mixed "drive-by fix plus feature" PRs take longer to review. + +## Building and testing locally + +You need Go 1.25+. No CGO, no build tags, no platform-specific deps. + +```sh +make build # build ./bin/rememberize +make test # go test -race ./... +make lint # golangci-lint run (install: https://golangci-lint.run/) +make install-dev # build + copy into ~/.local/bin +``` + +Tests run directly on the host on macOS, Linux, and Windows. + +## What kinds of PRs get accepted + +Likely to land: + +- Bug fixes with a clear reproduction, a test covering the bug, and a scoped fix. +- Docs improvements (install troubleshooting, clearer error messages, typo fixes). +- Small user-facing CLI ergonomics (flag additions, better error text, config-file improvements). +- Cross-platform compatibility fixes. +- Skill improvements in `skills/rememberize-bundle/`. + +Unlikely to land without prior discussion: + +- Large refactors. +- New top-level commands or subsystems. +- Changes to the wire protocol with the server (we can't land those unilaterally here). +- Dependencies on CGO or platform-specific build tags. +- New runtime dependencies. + +If you're unsure, open an issue and ask before writing code. + +## Code of conduct + +Be kind. Assume good faith. We're here to ship useful software, not win arguments. + +## License + +By contributing, you agree that your contributions are licensed under the MIT License (see [`LICENSE`](LICENSE)).