pointbreak
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.
Badge for your README
Markdown
[](/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
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "pointbreak",
- "description": "Pointbreak: context memory and workflow for AI agents in microservice teams.",
- "owner": {
- "name": "Saad Rupai",
- "url": "https://github.com/saadrupai"
- },
- "plugins": [
- {
- "name": "pointbreak",
- "description": "Per-service context files, /pointbreak and /pointbreak-setup commands, a session-start hook and a Go MCP server for microservice workspaces.",
- "version": "0.4.0",
- "author": { "name": "Saad Rupai" },
- "category": "development",
- "source": "./",
- "homepage": "https://github.com/saadrupai/pointbreak"
- }
- ]
- }
README.md · README · 194 lines
- # Pointbreak
- **Shared memory and a one-command workflow for AI agents in microservice teams.**
- [](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)
- 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.
- 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:
- ```
- /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"
- ```
- 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.
- ## Why teams use it
- ### 1. Low token usage
- 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.
- - 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.
- - `load_context` takes a `files` filter, so a task that only needs the schema loads only `database.md`.
- - Logs are split by month, so history doesn't grow the default load: only the newest month is read.
- - `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.
- ### 2. Cache-friendly by design
- Prompt caching makes repeated input much cheaper, but only when the start of the prompt stays the same. Pointbreak keeps it stable:
- - `/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.
- - 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.
- - `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.
- - 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.
- ### 3. Context that holds
- - **Across sessions:** tomorrow's session resumes from `temp.md` and the log instead of from zero.
- - **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.
- - **Across people:** a teammate picking up your branch reads the same memory you wrote.
- - **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.
- ### 4. Engineering standards built in
- `/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.
- ### 5. Safe by default
- - 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.
- - **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.
- - No commits, pushes, resets or branch switches unless asked. Other branches are read with `git show`, never checked out.
- - Secret files are never read. Context files hold names, never values.
- - Every write stays inside `context/`. Applied migrations are never edited.
- ## What's inside a workspace
- ```
- <workspace>/
- CLAUDE.md imports context/README.md (added by /pointbreak-setup)
- context/
- README.md your team's rules for agents
- global-architecture.md the service map: calls, events, queues, shared contracts
- orders-svc/
- temp.md today's task: goal, plan, progress
- architecture.md how the service is built and wired
- features.md what it does, with entry points
- database.md tables, indexes, relations, enums, migration log
- logs/2026-11.md finished work, one file per month
- payments-svc/ …
- orders-svc/ your repos, untouched
- payments-svc/
- ```
- Everything is markdown your team can read, review and edit. Nothing leaves your machine.
- ## Commands
- | Command | Does |
- |---|---|
- | `/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` |
- | `/pointbreak <repos> [branches] [ticket / doc / image / "prompt"…]` | Start a task across one or more services |
- | `/pointbreak save [repos]` | Checkpoint progress into `temp.md` |
- | `/pointbreak end [repos]` | Fold the task into the monthly log and update the service docs |
- | `/pointbreak status` | Show today's active tasks |
- Full behaviour: [spec/pointbreak-command.md](spec/pointbreak-command.md).
- ## MCP tools
- 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.
- | Tool | Does | Writes? |
- |---|---|---|
- | `init_workspace` | Create `context/` for every repo (never overwrites) | `context/` only |
- | `list_services` | Registered services and repos still missing context | no |
- | `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 |
- | `start_task` | Add today's task block to a service's `temp.md` | `context/` only |
- | `save_progress` | Checkpoint Plan / Done / Next / Decisions / Questions | `context/` only |
- | `end_task` | Move a task to the top of the monthly log | `context/` only |
- | `task_status` | Today's tasks across services, stale entries and out-of-date docs flagged | no |
- | `search_logs` | Search past work across services | no |
- | `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 |
- | `sync_database` | Rebuild a database doc from migration files: tables, columns, keys, indexes, relations, enums, migration log | `context/` only |
- ### Database docs that keep themselves current
- `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.
- - **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.
- - **Human notes are safe.** Generated content lives between markers; ownership notes, data notes and anything else you write stay as written.
- - **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.
- - Statements it doesn't understand are listed under "check by hand" instead of being guessed.
- ### Docs that warn when they drift
- 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.
- `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.
- Every tool declares MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so hosts can show what is safe to run.
- ## Quick start
- ### 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, …)
- ```bash
- 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.
- ## Status and roadmap
- Current release: **v0.3.0** ([changelog](CHANGELOG.md)). Contributions welcome: [CONTRIBUTING.md](CONTRIBUTING.md) · security: [SECURITY.md](SECURITY.md).
- | Phase | What | Status |
- |---|---|---|
- | 1 | Context spec, templates, `/pointbreak` and `/pointbreak-setup`, example workspace, init script | ✅ |
- | 2 | Go MCP server with 9 tools, tests | ✅ |
- | 3 | Claude Code plugin: one-step install, `pointbreak` skill, session-start hook | ✅ |
- | 4 | `sync_database`: database docs from migrations, including shared databases | ✅ |
- ## Develop
- ```bash
- go vet ./...
- go test ./...
- go build -o bin/pointbreak-mcp ./cmd/pointbreak-mcp
- ```
- | Path | What |
- |---|---|
- | `templates/context/` | Templates (embedded in the binary) |
- | `commands/` | `/pointbreak` and `/pointbreak-setup` |
- | `skills/pointbreak/` | The skill that applies the workflow whenever you work in a Pointbreak workspace |
- | `hooks/` | Session-start hook and pre-write approval hook |
- | `.claude-plugin/` | Plugin manifest, marketplace entry, icon |
- | `.mcp.json`, `scripts/mcp-launch.sh` | Starts the MCP server from the plugin |
- | `internal/workspace/` | Reading and writing `context/` |
- | `internal/dbschema/` | Migration replay and Prisma parsing (files only) |
- | `internal/mcp/` | Minimal stdio JSON-RPC MCP server |
- | `internal/tools/` | Tool definitions and annotations |
- | `cmd/pointbreak-mcp/` | The binary |
- | `spec/` | File formats and command behaviour |
- | `examples/kitebox/` | A filled-in example workspace |
- | `scripts/init.sh` | Shell alternative to `init_workspace` |
- ## License
- MIT © 2026 Saad Rupai
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.