Metadata-Version: 2.4
Name: mackit
Version: 0.1.0
Summary: Tiny agent-ready project initializer and adapter.
Project-URL: Homepage, https://github.com/Suchenl/multi-agent-collaboration-kit
Project-URL: Repository, https://github.com/Suchenl/multi-agent-collaboration-kit
Author: mackit contributors
License: MIT
License-File: LICENSE
Keywords: AGENTS.md,Claude,Codex,Cursor,agents,handoff
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# mackit

Make a repository ready for multi-agent work with one clone and one command.

This kit gives agents a shared workspace (`.agents/`), a small set of
coordination rules, and a curated skill catalog inside `.agents/skills/`. Users do not need to design
their own handoff protocol or hunt for skills before starting: ask an agent to
install this repo, keep the default skill bundles, and start working.

It stays local-first and lightweight. There is no daemon, database, hosted
service, lock server, or required dependency.

It is not trying to replace public skill marketplaces. It complements them by
making a single project immediately usable by agents: install the repo-local
coordination layer, seed a small curated skill set, and add external marketplace
skills only after review.

## Quick Start

```bash
pip install mackit
mackit adapt .
```

For local development from this repository, use `PYTHONPATH=src python -m mackit`.

## Two Use Cases

### 1. Start a new project

```bash
mackit new ./my-project --package-name my_project
```

This creates a simple Python `src/` layout plus the agent-native coordination
files.

### 2. Adapt an existing project

```bash
mackit adapt /path/to/existing-project
```

The adapter is additive and idempotent:

- Existing files are not overwritten.
- Missing files are created.
- `AGENTS.md`, `CLAUDE.md`, and `.gitignore` receive managed sections only once.
- Cursor receives `.cursor/rules/multi-agent.mdc`.
- Curated skills from this kit's `.agents/skills/` catalog are installed by default.

## What Gets Installed

```text
.agents/
├── README.md
├── STATE.md
├── agents/.gitkeep
├── retros/.gitkeep
├── skills/
│   ├── .gitkeep
│   ├── README.md
│   ├── registry.toml
│   └── common/
│       └── improve-this-kit/
│           └── SKILL.md
├── tasks/.gitkeep
├── improve-this-kit/
│   ├── .gitkeep
│   ├── README.md
│   ├── feedback/
│   │   ├── .gitkeep
│   │   └── README.md
│   └── proposals/
│       ├── .gitkeep
│       └── README.md
└── templates/
    ├── agent_state.md
    ├── feedback.md
    ├── proposal.md
    ├── retro.md
    ├── skill.md
    └── task_state.md

.cursor/rules/multi-agent.mdc
AGENTS.md
CLAUDE.md
.gitignore
src/<package_name>/        # only for `new`, or when --package-name is passed
```

Selected curated skills are copied from this kit's `.agents/skills/` into the
target `.agents/skills/`, preserving grouped paths such as
`design/image-to-editable-slides/`.

## Design Principles

- `AGENTS.md` is the cross-tool canonical contract.
- `CLAUDE.md` is a thin Claude Code shim.
- `.cursor/rules/` is a Cursor-native adapter.
- `.agents/` stores runtime coordination, not long-term design knowledge.
- `.agents/retros/` stores raw post-task learning drafts.
- `.agents/skills/` stores reviewed, reusable skills for future agents.
- `.agents/improve-this-kit/feedback/` stores raw usage feedback about the kit.
- `.agents/improve-this-kit/proposals/` stores review-gated kit improvement proposals and is trackable by default.
- `improve-this-kit` turns real usage feedback into reviewed proposals and tests.
- `.agents/skills/registry.toml` describes curated skills and bundles.
- `.agents/skills/external/README.md` tells agents how to recommend external skills safely.
- Design decisions should move to your real docs, ADRs, or README.
- Work isolation should still prefer branches or worktrees for heavy parallelism.

## Self-Improvement Loop

The kit is designed to improve from real usage without letting agents rewrite it
from a single anecdote:

1. Agents write raw usage notes in `.agents/improve-this-kit/feedback/`.
2. Repeatable issues become proposals in `.agents/improve-this-kit/proposals/`.
3. Proposals require explicit review/approval before implementation.
4. Accepted changes must include or update an idempotency check, fixture, or test.
5. Reviewed, reusable know-how can become a skill in `.agents/skills/`.

Use `.agents/skills/common/improve-this-kit/SKILL.md` for the review-gated workflow.

## Curated Skill Catalog

The repo ships its maintained catalog directly in `.agents/skills/`. During
installation, all curated bundles are installed by default so users do not need
to hunt for skills first:

```bash
mackit adapt /path/to/project
```

Agents may ask the user to keep the default selection or narrow it:

```bash
mackit adapt /path/to/project --skill-bundles common,design
```

Use `list-skill-bundles` to inspect available bundles.

External skill discovery is optional. Agents may recommend external skills, but
must report candidates and wait for user approval before copying them. See
`.agents/skills/external/README.md`.

## For Agents

If a user gives you this repository link and asks you to make their project
agent-ready, read [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md) first.

For public sharing, see [`docs/external_download.md`](docs/external_download.md).

