Skip to content
Back to search

pointbreak

MarketplaceWorks with Claude CodeGitHub

Pointbreak: context memory and workflow for AI agents in microservice teams.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/saadrupai--pointbreak/badge.svg)](/listings/saadrupai--pointbreak)

HTML

<a href="/listings/saadrupai--pointbreak"><img src="/api/listings/saadrupai--pointbreak/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code (plugin, one step)

/plugin install pointbreak --marketplace saadrupai/pointbreak

Or add the marketplace first, then install:

/plugin marketplace add saadrupai/pointbreak
/plugin install pointbreak@pointbreak

The plugin brings everything: `/pointbreak`, `/pointbreak-setup`, the `pointbreak` skill, the MCP server, and a session-start hook. Open Claude Code at your workspace root and run once:

/pointbreak-setup

The MCP server is built from source on first use (needs Go 1.23+), or uses `pointbreak-mcp` from your `PATH` if you installed it.

**The session-start hook** prints one short note when a session opens inside a Pointbreak workspace: which service you're in, what's active today, and anything left unfinished from earlier days. Outside a microservice workspace it prints nothing, so it costs no tokens there. In a folder with several repos but no `context/`, it suggests `/pointbreak-setup`.

Other MCP clients (Cursor, Codex, Antigravity, …)

go install github.com/saadrupai/pointbreak/cmd/pointbreak-mcp@latest

Point the client at `pointbreak-mcp` over stdio. It finds the workspace by walking up from its working directory to the nearest `context/README.md`, or takes `--workspace /path`. Copy `commands/*.md` wherever your client keeps prompts.

No MCP at all

`./scripts/init.sh ~/work/yourco` creates the same `context/` folder; the commands work with plain file reads.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "pointbreak",
  4. "description": "Pointbreak: context memory and workflow for AI agents in microservice teams.",
  5. "owner": {
  6. "name": "Saad Rupai",
  7. "url": "https://github.com/saadrupai"
  8. },
  9. "plugins": [
  10. {
  11. "name": "pointbreak",
  12. "description": "Per-service context files, /pointbreak and /pointbreak-setup commands, a session-start hook and a Go MCP server for microservice workspaces.",
  13. "version": "0.4.0",
  14. "author": { "name": "Saad Rupai" },
  15. "category": "development",
  16. "source": "./",
  17. "homepage": "https://github.com/saadrupai/pointbreak"
  18. }
  19. ]
  20. }
README.md · README · 194 lines
  1. # Pointbreak
  2. **Shared memory and a one-command workflow for AI agents in microservice teams.**
  3. [![M8ven Score](https://m8ven.ai/badge/mcp/saadrupai-pointbreak-q4tjxg?v=36c805d833cfae7b25f2ab9843696263)](https://m8ven.ai/mcp/saadrupai-pointbreak-q4tjxg?s=readme) · MIT · Go, zero dependencies · v0.4.0 · [Also on Agensi](https://www.agensi.io/skills/pointbreak-microservice-context-workflow)
  4. Pointbreak grew out of daily use: the author runs this structure every working day on a production microservice codebase, where it keeps the work tracked by service, branch and date, holds context across sessions and cuts down repeated exploration. This repo turns that habit into a spec, templates, commands and tools any team can use.
  5. AI coding agents forget your system every session. In a microservice codebase that's expensive: the agent rediscovers each service, misses the consumers of an event, and edits code in the wrong layer. Pointbreak gives every service a small, plain-markdown memory and gives the agent one command to start real work across services:
  6. ```
  7. /pointbreak orders-svc,payments-svc feature/ORD-142 https://yourco.atlassian.net/browse/ORD-142 ./designs/refund-modal.png "partial refunds, max 3 per order"
  8. ```
  9. The agent loads your team's rules, reads each service's architecture, database and recent history, reads the ticket, the design and your instruction, checks the right branch in each repo, writes a plan per service (including every consumer a contract change affects), and waits for approval before touching code.
  10. ## Why teams use it
  11. ### 1. Low token usage
  12. Without shared memory, every session starts by crawling repos: directory listings, entrypoints, config, migrations, grep after grep, often across several services. Pointbreak replaces that with one `load_context` call that returns a few small, curated files.
  13. - In the bundled [Kitebox example](examples/kitebox/context), one service's full context (architecture, database, features, current task, this month's log) is about **6 KB, roughly 1,500 tokens**. All three services plus the rules and system map are about 28 KB.
  14. - `load_context` takes a `files` filter, so a task that only needs the schema loads only `database.md`.
  15. - Logs are split by month, so history doesn't grow the default load: only the newest month is read.
  16. - `impact` and `search_logs` answer "who consumes this event?" and "how did we do this last time?" by scanning the docs, without opening a single repo file.
  17. ### 2. Cache-friendly by design
  18. Prompt caching makes repeated input much cheaper, but only when the start of the prompt stays the same. Pointbreak keeps it stable:
  19. - `/pointbreak-setup` imports the team rules into your workspace `CLAUDE.md` (`@context/README.md`), so they sit in the fixed start of every session, where caching applies.
  20. - The rules loaded every turn are kept slim (about 7 KB). The full engineering standards live in `context/STANDARDS.md` and load only when planning or building code.
  21. - `load_context` always returns files in the same order (rules, system map, then each service's architecture, database, features, task, log). Same task, same bytes, same cache prefix.
  22. - The large files (`architecture.md`, `database.md`, `features.md`) change rarely. The parts that change every day (`temp.md`, the current log) are small and come last, so a day of edits doesn't invalidate the big stable block in front of them.
  23. ### 3. Context that holds
  24. - **Across sessions:** tomorrow's session resumes from `temp.md` and the log instead of from zero.
  25. - **Across compaction and model switches:** the plan, decisions and next step live in files, not only in the chat history, so a long session that gets summarised (or moves to another agent) loses nothing that matters.
  26. - **Across people:** a teammate picking up your branch reads the same memory you wrote.
  27. - **Across services:** `global-architecture.md` keeps the calls, events and queues between services in one place, so a change in one repo is checked against every consumer.
  28. ### 4. Engineering standards built in
  29. `/pointbreak-setup` installs team rules that every agent session follows: test-driven development (failing test first, then code, then refactor), clean code, layered design, wrapped and typed errors, backward-compatible APIs and events, idempotent writes and consumers, safe migrations on large tables, security, observability, timeouts and retries, typed config, the testing pyramid, and a review checklist the agent runs before saying a task is done. Teams can switch any standard off in one settings row.
  30. ### 5. Safe by default
  31. - Plans are approved before any code changes. Then **every single file write** is shown as a diff with what changed and why, and written only after you approve that file — tests, migrations and config included. Approving the plan approves no file.
  32. - **Enforced, not just asked for:** the plugin's pre-write hook makes Claude Code ask before any write outside `context/`, even when edits would otherwise be auto-accepted.
  33. - No commits, pushes, resets or branch switches unless asked. Other branches are read with `git show`, never checked out.
  34. - Secret files are never read. Context files hold names, never values.
  35. - Every write stays inside `context/`. Applied migrations are never edited.
  36. ## What's inside a workspace
  37. ```
  38. <workspace>/
  39. CLAUDE.md imports context/README.md (added by /pointbreak-setup)
  40. context/
  41. README.md your team's rules for agents
  42. global-architecture.md the service map: calls, events, queues, shared contracts
  43. orders-svc/
  44. temp.md today's task: goal, plan, progress
  45. architecture.md how the service is built and wired
  46. features.md what it does, with entry points
  47. database.md tables, indexes, relations, enums, migration log
  48. logs/2026-11.md finished work, one file per month
  49. payments-svc/ …
  50. orders-svc/ your repos, untouched
  51. payments-svc/
  52. ```
  53. Everything is markdown your team can read, review and edit. Nothing leaves your machine.
  54. ## Commands
  55. | Command | Does |
  56. |---|---|
  57. | `/pointbreak-setup` | One-time setup: finds every service repo, creates `context/`, fills each service's docs from its code and migrations, builds the system map, wires the rules into `CLAUDE.md` |
  58. | `/pointbreak <repos> [branches] [ticket / doc / image / "prompt"…]` | Start a task across one or more services |
  59. | `/pointbreak save [repos]` | Checkpoint progress into `temp.md` |
  60. | `/pointbreak end [repos]` | Fold the task into the monthly log and update the service docs |
  61. | `/pointbreak status` | Show today's active tasks |
  62. Full behaviour: [spec/pointbreak-command.md](spec/pointbreak-command.md).
  63. ## MCP tools
  64. The `pointbreak-mcp` server (Go, standard library only, single binary) exposes the same operations to any MCP client: Claude Code, Cursor, Codex, Antigravity and others.
  65. | Tool | Does | Writes? |
  66. |---|---|---|
  67. | `init_workspace` | Create `context/` for every repo (never overwrites) | `context/` only |
  68. | `list_services` | Registered services and repos still missing context | no |
  69. | `load_context` | Rules, system map and service memory in one call, stable order; warns when a service's docs are older than its code | no |
  70. | `start_task` | Add today's task block to a service's `temp.md` | `context/` only |
  71. | `save_progress` | Checkpoint Plan / Done / Next / Decisions / Questions | `context/` only |
  72. | `end_task` | Move a task to the top of the monthly log | `context/` only |
  73. | `task_status` | Today's tasks across services, stale entries and out-of-date docs flagged | no |
  74. | `search_logs` | Search past work across services | no |
  75. | `impact` | Searches the system map, shared-DB docs and every service's architecture, database and features docs for an event, RPC, table or field, and says which file each hit is in | no |
  76. | `sync_database` | Rebuild a database doc from migration files: tables, columns, keys, indexes, relations, enums, migration log | `context/` only |
  77. ### Database docs that keep themselves current
  78. `sync_database` replays a service's migrations (golang-migrate, goose, Flyway, plain SQL) or reads its Prisma schema and writes the result into `database.md`: every table with columns, types, nulls, defaults, keys, indexes, foreign keys and enums, plus a migration log, newest first. `ALTER`, `RENAME` and `DROP` are applied in order, so the doc shows the schema as it stands today.
  79. - **No database connection, ever.** It reads migration files only. No credentials, no drivers, nothing on the network. A test fails the build if a database or network package is ever imported.
  80. - **Human notes are safe.** Generated content lives between markers; ownership notes, data notes and anything else you write stay as written.
  81. - **Shared databases.** Each service can have its own database, several services can share one, or all can use the same one. A shared database is documented once in `context/_db/<name>.md` (with which service's code touches which tables), and each service's `database.md` links to it. `load_context` brings the shared doc along automatically.
  82. - Statements it doesn't understand are listed under "check by hand" instead of being guessed.
  83. ### Docs that warn when they drift
  84. Memory is only useful while it's true. When a service's repo has commits newer than its docs (`architecture.md`, `database.md`, `features.md`), `load_context`, `task_status` and `impact` say so: "payments-svc · 4 commits since its docs were last updated (2026-11-02)". The agent then checks the code before trusting those docs and updates them as part of the task. Commits made within 6 hours of a doc update count as the same work. It only reads `git log` in the service repo; nothing is written there.
  85. `impact` searches docs, not code, so treat its list as the place to start: the agent confirms real consumers in code before changing a contract.
  86. Every tool declares MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so hosts can show what is safe to run.
  87. ## Quick start
  88. ### Claude Code (plugin, one step)
  89. ```
  90. /plugin install pointbreak --marketplace saadrupai/pointbreak
  91. ```
  92. Or add the marketplace first, then install:
  93. ```
  94. /plugin marketplace add saadrupai/pointbreak
  95. /plugin install pointbreak@pointbreak
  96. ```
  97. The plugin brings everything: `/pointbreak`, `/pointbreak-setup`, the `pointbreak` skill, the MCP server, and a session-start hook. Open Claude Code at your workspace root and run once:
  98. ```
  99. /pointbreak-setup
  100. ```
  101. The MCP server is built from source on first use (needs Go 1.23+), or uses `pointbreak-mcp` from your `PATH` if you installed it.
  102. **The session-start hook** prints one short note when a session opens inside a Pointbreak workspace: which service you're in, what's active today, and anything left unfinished from earlier days. Outside a microservice workspace it prints nothing, so it costs no tokens there. In a folder with several repos but no `context/`, it suggests `/pointbreak-setup`.
  103. ### Other MCP clients (Cursor, Codex, Antigravity, …)
  104. ```bash
  105. go install github.com/saadrupai/pointbreak/cmd/pointbreak-mcp@latest
  106. ```
  107. Point the client at `pointbreak-mcp` over stdio. It finds the workspace by walking up from its working directory to the nearest `context/README.md`, or takes `--workspace /path`. Copy `commands/*.md` wherever your client keeps prompts.
  108. ### No MCP at all
  109. `./scripts/init.sh ~/work/yourco` creates the same `context/` folder; the commands work with plain file reads.
  110. ## Status and roadmap
  111. Current release: **v0.3.0** ([changelog](CHANGELOG.md)). Contributions welcome: [CONTRIBUTING.md](CONTRIBUTING.md) · security: [SECURITY.md](SECURITY.md).
  112. | Phase | What | Status |
  113. |---|---|---|
  114. | 1 | Context spec, templates, `/pointbreak` and `/pointbreak-setup`, example workspace, init script | ✅ |
  115. | 2 | Go MCP server with 9 tools, tests | ✅ |
  116. | 3 | Claude Code plugin: one-step install, `pointbreak` skill, session-start hook | ✅ |
  117. | 4 | `sync_database`: database docs from migrations, including shared databases | ✅ |
  118. ## Develop
  119. ```bash
  120. go vet ./...
  121. go test ./...
  122. go build -o bin/pointbreak-mcp ./cmd/pointbreak-mcp
  123. ```
  124. | Path | What |
  125. |---|---|
  126. | `templates/context/` | Templates (embedded in the binary) |
  127. | `commands/` | `/pointbreak` and `/pointbreak-setup` |
  128. | `skills/pointbreak/` | The skill that applies the workflow whenever you work in a Pointbreak workspace |
  129. | `hooks/` | Session-start hook and pre-write approval hook |
  130. | `.claude-plugin/` | Plugin manifest, marketplace entry, icon |
  131. | `.mcp.json`, `scripts/mcp-launch.sh` | Starts the MCP server from the plugin |
  132. | `internal/workspace/` | Reading and writing `context/` |
  133. | `internal/dbschema/` | Migration replay and Prisma parsing (files only) |
  134. | `internal/mcp/` | Minimal stdio JSON-RPC MCP server |
  135. | `internal/tools/` | Tool definitions and annotations |
  136. | `cmd/pointbreak-mcp/` | The binary |
  137. | `spec/` | File formats and command behaviour |
  138. | `examples/kitebox/` | A filled-in example workspace |
  139. | `scripts/init.sh` | Shell alternative to `init_workspace` |
  140. ## License
  141. MIT © 2026 Saad Rupai

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.