maggie

Tools to sync AI agent skills, practices, and workflows across repositories.

Skills are authored once under skills/<techno>/<name>/SKILL.md and translated into each target platform's format (Claude Code, GitHub Copilot, Cursor, Windsurf).

It ships two CLIs — maggie (push skills to repos) and maggie-workspace (bootstrap a local workspace + status board) — plus a kanban dashboard, as an Nx monorepo on npm workspaces.

Why

Every repository in an organization ends up with its own drifting copy of the same agent instructions — one for Claude Code, another for Copilot, a third for Cursor. maggie keeps one reviewed source of truth: write the guidance once, declare which technologies each repo uses, and let the tool render and open the pull requests.

Quick start

Requires Node.js >= 22 and git on your PATH.

npm install -g @linktogo/maggie

# See what would be pushed to the repos in your config — no side effects
maggie --config repos.json --dry-run

The installed package bundles the skills library, so the CLI works from any directory. A skills/ folder in the current directory takes precedence, which is what you want when working from a clone; --skills <dir> overrides both.

To hack on the project itself, work from a checkout:

git clone https://github.com/linktogo/maggie.git
cd maggie
npm ci
node apps/sync/bin/sync.js --config repos.example.json --dry-run

Then copy repos.example.json, point it at your own repositories, and drop the --dry-run when the preview looks right.

npm run wk     # clone those repos into ./wk and print the command to open them
npm start      # serve the board (auto-detects wk/.maggie/board.json)

New here? Read Configuration next, then Adding a skill.

Documentation

Full reference lives in docs/:

Page	What it covers
Configuration	The repos.json schema, and the two ways both CLIs resolve it
Skills library	Authoring skills, how they map to each target platform
maggie CLI	Rendering skills into repos and pushing them
maggie-workspace CLI	Bootstrapping a workspace, worktrees, status tracking
Board dashboard	The kanban dashboard, its server and endpoints
CI status	Per-contributor CI badges on the board, and how to enable them
Architecture	Nx layout, module boundaries, testing and coverage gates

docs/superpowers/ holds the design record — one spec and plan per feature, kept as history rather than maintained.

Skills library

skills/ ships a starter set of guidance, grouped by technology and matched against each repo's technologies list: nestjs, postgres, nextjs, reactjs, angular, vuejs, nx, firebase, cloudflare.

Add one by creating skills/<techno>/<name>/SKILL.md with YAML frontmatter (name, description, optional globs) followed by the guidance body. Any repo whose technologies include <techno> picks it up on the next sync — see Skills library.

Published packages

Everything publishes under the single @linktogo scope. The CLIs ship as @linktogo/maggie (the package you install); the libraries are published independently so they can be reused on their own:

Package	What it gives you
@linktogo/maggie-config	load/validate the repo config from a file or a git repo
@linktogo/maggie-git	thin git/gh wrapper
@linktogo/maggie-renderers	render a skill for claude/copilot/cursor/windsurf
@linktogo/maggie-skill-sync	skill resolution + the sync pipeline
@linktogo/maggie-workspace-bootstrap	clone/install, hooks, board state
@linktogo/maggie-ci-status	CI status payloads, validation and state mapping

All are released in lockstep on the same version — see Releasing. The apps/* projects stay private, keep internal @maggie/* names, and are never published on their own.

Tests

npm test          # nx run-many -t test: every lib/app, 100% coverage gate each (except board)
npm run test:board # apps/board suite only: server (node:test) + front-end (vitest)

CI runs nx run-many -t lint test build. Because Nx detects the package manager from the lockfile, keep package-lock.json as the only lockfile — a pnpm-lock.yaml breaks the Nx project graph. Layout, testing conventions and the reasons behind them are in Architecture.

Contributing

Contributions are welcome — especially new skills, which are the easiest way in. Start with CONTRIBUTING.md for the dev setup, the coverage bar, the commit format, and how to add a skill. Participation is governed by our Code of Conduct.

• 🐛 Report a bug
• 💡 Propose a feature or a skill
• 🔒 Security issues: see SECURITY.md — never a public issue

Release notes live in CHANGELOG.md.

Security model

The CLIs run git and package-manager commands on your machine: they clone the repositories named in the config, install their dependencies, and shell out to gh when --pr is passed. Treat the config file — and any repository you pass to --config-repo — as trusted input. The board server is a local development tool with no authentication and should not be exposed to a network. See SECURITY.md for the full scope and reporting process.

License

Apache License 2.0 © Linktogo.

Third-party material redistributed in this repository is listed in THIRD_PARTY_NOTICES.md.