npm package: @jml-dev/agents
Description: JML-Dev PCH Agent Workflow — AI coding agents for VS Code
Latest version: 3.3.0

# @jml-dev/agents

AI coding agents for VS Code — a phased, multi-session development workflow powered by GitHub Copilot.

## Quick Start

```bash
npx @jml-dev/agents init
```

This installs six specialized agents into your project's `.github/agents/` directory, ready to use in VS Code's Copilot Chat.

## What Gets Installed

```
.github/
├── agents/
│   ├── jml-dev-visionary.md
│   ├── jml-dev-researcher.md
│   ├── jml-dev-planner.md
│   ├── jml-dev-plan-reviewer.md
│   ├── jml-dev-coder.md
│   ├── jml-dev-helper.md
│   ├── agents.sh
│   └── VERSION.txt
└── copilot-instructions.md
```

## Agents

The agents follow a sequential workflow: **Visionary → Researcher → Planner → Plan Reviewer → Coder**

Not every step is required — start with `@jml-dev-helper` if you're unsure.

| Agent | Purpose |
|-------|---------|
| `jml-dev-visionary` | Transforms raw ideas into structured vision documents via guided Q&A |
| `jml-dev-researcher` | Conducts phased codebase/technology research |
| `jml-dev-planner` | Creates detailed, phased implementation plans |
| `jml-dev-plan-reviewer` | Reviews plans for quality before implementation |
| `jml-dev-coder` | Executes approved plans with production-ready code |
| `jml-dev-helper` | Guides on agent workflow and agent selection |

## Commands

| Command | Description |
|---------|-------------|
| `npx @jml-dev/agents init` | Install agents into the current project |
| `npx @jml-dev/agents update` | Update agent files and managed blocks |
| `npx @jml-dev/agents status` | Show installed versions and configuration state |
| `npx @jml-dev/agents verify` | Verify installation integrity |

### Options

| Flag | Description |
|------|-------------|
| `--yes`, `-y` | Non-interactive mode (accept all defaults) |
| `--force`, `-f` | Force overwrite of existing files |
| `--verbose`, `-v` | Show detailed output |
| `--changelog` | Show release notes for current or incoming version |
| `--no-root-check` | Skip project-root detection check |

For detailed command documentation including all flags, behaviors, and examples, see the [CLI Command Reference](docs/setup-guide-npm.md#cli-command-reference).

## Version Pinning

Install a specific version instead of latest:

```bash
npx @jml-dev/agents@3.0.0 init        # exact version
npx @jml-dev/agents@^3.0.0 init       # compatible range
```

Check available versions:

```bash
npm view @jml-dev/agents versions
```

## Requirements

- **Node.js 18+**
- **VS Code** with the **GitHub Copilot** extension
- VS Code setting: `github.copilot.chat.customAgents.showOrganizationAndEnterpriseAgents: true`

## Documentation

- [Setup Guide](docs/setup.md) — Installation, verification, updating, and troubleshooting
- [Managed Blocks](docs/managed-blocks.md) — How universal workflow content syncs across projects
- [npm Setup Guide (PDF)](docs/setup-guide-npm.pdf) — Installation for individual projects
- [Organization Setup Guide (PDF)](docs/setup-guide-org.pdf) — Distribution for GitHub organizations

## What's New

See [RELEASE-NOTES.md](RELEASE-NOTES.md) for the latest version highlights. For the full change log, see [CHANGELOG.md](CHANGELOG.md).

## License

MIT