# agentme

Curated distribution package of XDRs and AI agent workflow files for AI-assisted software development.

This collection is being updated as we develop applications and feel the need for new instructions and skills to help with AI agents.

For guidance on turning recurring delivery friction into reusable decision records, see [Continuous XDR improvement](.xdrs/agentme/edrs/principles/articles/001-continuous-xdr-improvement.md).

## Getting Started

To install all agentme artifacts (skills, XDRs, AGENTS.md) into the current folder:

```sh
npx agentme install --output . --presets basic
```

If you want the version pinned in a project, add `agentme` to a repository that already has a `package.json` and run it through the local dependency:

```sh
mise exec -- pnpm add -D agentme
mise exec -- pnpm exec agentme install --output . --presets basic
mise exec -- pnpm exec agentme check --output . --presets basic
```

## Overview

agentme is published as an npm package and consumed through `filedist`-based extraction. It ships a curated set of reusable artifacts for other repositories:

- XDRs in `.xdrs/agentme/` for engineering, architecture, testing, tooling, and CI/CD standards.

The package is intentionally static: consumers install it as a development dependency, extract files into their own repository, and commit the generated output.

## Presets

| Preset | Contents |
| --- | --- |
| `core` | `xdrs-core` baseline ADRs, `AGENTS.md`, and the skill for selecting relevant XDRs |
| `basic` | everything in `core` plus all agentme XDRs and the XDRS index |
| no preset | all shipped artifacts combined |

Typical consumer workflow:

1. For one-off use or a new empty folder, run `npx agentme install --output . --presets <preset>`.
2. For a pinned project version, add `agentme` to `package.json` and use `pnpm exec agentme ...`.
3. Review and commit the extracted files.
4. Re-run `install` and `check` when upgrading the package.

## Usage Scenarios

### Guide AI coding with maintained ADRs and EDRs

Use agentme when you want architectural and engineering decisions to actively constrain how coding agents implement features. The extracted ADRs and EDRs give the repository a durable source of truth for architecture, coding practices, testing expectations, tooling, and delivery standards.

This is useful when you want agents to:

- consult explicit architecture records before choosing patterns or integrations;
- follow engineering rules for project structure, quality, testing, and operations;
- produce code that stays aligned with documented decisions instead of ad hoc prompt instructions.

### Register feature and product knowledge as BDRs

Use XDR business records to capture product and operational knowledge while features are being delivered. BDRs are meant to document workflows, requirements, business rules, operating procedures, and product decisions in the same structured format as technical decisions.

This is useful when you want feature work to leave behind maintainable documentation for:

- application workflows and operating procedures;
- product requirements and business constraints;
- business decisions that explain why the feature behaves the way it does.

## Development

Install [Mise](https://mise.jdx.dev/getting-started.html), then bootstrap the repository through the root `Makefile`:

```sh
make setup
```

Use the root `Makefile` as the entry point for local verification:

```sh
make build
make lint
make test
```

What these targets do:

- `make build` installs dependencies and creates a local npm package in `dist/`.
- `make lint` runs the repository lint target.
- `make test` rebuilds the package and validates the consumer extraction flow through the runnable example in `examples/`.

## Repository Map

```text
.
├── AGENTS.md           Project instructions for AI coding agents
├── Makefile            Root build, lint, test, and publish entry point
├── .mise.toml          Pinned tool versions (Node.js, pnpm)
├── bin/                CLI entrypoint delegated to filedist
├── dist/               Generated npm package tarballs
├── examples/           Runnable verification of consumer extraction behavior
├── .github/            Shipped agent and prompt files
└── .xdrs/              Shipped XDRs plus local project-only decision records
```

Key folders:

- `.xdrs/_core/` contains the baseline XDR framework imported from `xdrs-core`.
- `.xdrs/agentme/` contains the reusable XDRs distributed to consumers.
- `.xdrs/_local/` contains internal decisions for this repository only and is not shipped to consumers.
- `examples/output/` is generated during tests to validate preset extraction and cleanup behavior.

## Release Notes

The published package exposes the `agentme` CLI through `bin/filedist.js` and is released to npm using the root `publish` target. The examples install the locally packed tarball from `dist/` so they exercise the same package shape an external consumer receives.