# NexusCRM Agent Helpers

Private PingCAP helpers for running the guarded NexusCRM development workflow in
OpenAI Codex, ZCode, or Pi. All three integrations load two shared skills from
`plugin/skills/`:

- `develop-task` keeps the source task issue unchanged, maintains one
  current-state tracker, and routes validation to Test or Staging.
- `shepherd-pull-request` owns pull-request scope, metadata, Codex Review
  handling, guarded stack updates, merge readiness, and authorized merges.

## Prerequisites

You need access to the private
[`pingcap-inc/nexuscrm-agent-helpers`](https://github.com/pingcap-inc/nexuscrm-agent-helpers)
repository and Git credentials that the selected agent can use.

## Install the Codex plugin

Add this repository as a Codex marketplace, then install the
`nexuscrm-development` plugin:

```bash
codex plugin marketplace add pingcap-inc/nexuscrm-agent-helpers --ref main
codex plugin add nexuscrm-development@nexuscrm-agent-helpers
```

Start a new Codex task after installation so Codex loads the skills. Invoke
`$develop-task` for task/tracker/deploy coordination and
`$shepherd-pull-request` for pull-request work.

## Install the Pi package

Install the repository as a user-level Pi package:

```bash
pi install git:github.com/pingcap-inc/nexuscrm-agent-helpers
```

To install it only for the current project instead, add `-l`:

```bash
pi install git:github.com/pingcap-inc/nexuscrm-agent-helpers -l
```

Start or reload Pi after installation. Pi discovers both shared skills through
the root `package.json`; invoke `/skill:develop-task` for task coordination or
`/skill:shepherd-pull-request` for pull-request work.

To try the package for one Pi session without installing it:

```bash
pi -e git:github.com/pingcap-inc/nexuscrm-agent-helpers
```

## Install the ZCode plugin

Add this repository as a ZCode marketplace, then install the
`nexuscrm-development` plugin: in **Settings → Plugins → Create → Add
marketplace**, enter `pingcap-inc/nexuscrm-agent-helpers` (or the local path to
this repository), then install `nexuscrm-development`. The skills are invoked as
`/develop-task` and `/shepherd-pull-request`.

## Repository layout

- `marketplace.json` defines the ZCode marketplace.
- `.agents/plugins/marketplace.json` defines the Codex marketplace.
- `plugin/` contains the Codex and ZCode plugin manifests and the shared
  `develop-task` and `shepherd-pull-request` skills.
- `package.json` exposes `plugin/skills` as a Pi package resource.