# ma-agents

A universal NPX tool to install AI coding agent skills. Write skills once, install them across Claude Code, Gemini, Copilot, Cline, Cursor, Kilocode, and Roo Code.

## Installation & Usage

`ma-agents` is designed to be run via `npx` in the root of your project.

### 1. Interactive Wizard (Recommended)
The wizard is the easiest way to set up or update your environment.
```bash
npx ma-agents
```

### 2. Direct Command Line
```bash
# Install specific skills to specific agents
npx ma-agents install code-review claude-code copilot

# Global installation (user-level)
npx ma-agents install code-review claude-code --global

# CI/CD: skip all prompts, use defaults
npx ma-agents install --yes

# Target a specific agent only
npx ma-agents install --yes --agent claude-code
```

## How It Works

Skills are written in a **unified generic format** and stored in this package. When you install a skill, the installer:

1. Reads the skill's `SKILL.md` (or agent-specific template if available)
2. Injects YAML frontmatter from `skill.json` (the single source of metadata)
3. Copies the skill and its resources into the target agent's directory
4. Renames resource directories to match the agent's native structure (e.g., `references/` becomes `docs/` for Cline)
5. **Generates `MANIFEST.yaml`**: A central discovery file for the agent to find all installed skills.
6. **Updates Instruction Blocks**: Stamps a universal planning-instruction block into every agent's instruction file (`CLAUDE.md`, `.clinerules`, `.cline/clinerules.md`, `.roo/rules/00-ma-agents.md`, `AGENTS.md`) between `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` markers. User content outside the markers is preserved. On-prem profile additionally stamps guardrails for local LLMs.
7. **BMAD Roo Code Modes**: Generates `.roomodes` with 4 BMAD planning-mode custom modes (`bmad-pm`, `bmad-architect`, `bmad-techlead`, `bmad-dev`), each with `fileRegex` restrictions that enforce planning-phase file access at the application layer.
8. **BMAD-METHOD Integration**: Automatically detects and integrates with [BMAD-METHOD](https://docs.bmad-method.org/), applying project-specific customizations and orchestration.

```
Generic (this repo)                    Installed Output
───────────────────                    ────────────────
skills/code-review/
├── skill.json        ──────────►     Injected as YAML frontmatter
├── SKILL.md          ──────────►     .claude/skills/code-review/SKILL.md
├── scripts/          ──────────►     .claude/skills/code-review/scripts/
└── references/       ──────────►     .claude/skills/code-review/references/
                                       + Generated MANIFEST.yaml
                                       + Updated Agent Instructions (CLAUDE.md, etc.)
```

## Project Knowledge: _bmad-output/

The `_bmad-output/` folder is **intentionally tracked in version control** as project knowledge. Do not add `_bmad-output/` to your `.gitignore`.

### What it contains

`_bmad-output/` holds all AI-generated planning artifacts produced by BMAD agents:

- **`planning-artifacts/`** — PRDs, architecture documents, UX designs
- **`implementation-artifacts/`** — Epics, user stories, sprint status, backlog
  - **`sprint-status.yaml`** — Unified single source of truth for all sprint and backlog state (epics map, backlog array, sprints map)
  - **`done/`** — Archived completed and cancelled stories and bugs
- **`methodology/`** — BMAD-METHOD training materials and onboarding presentation

### Why it is version-controlled

1. **Team alignment** — all team members see the same AI-generated plans and decisions
2. **AI context continuity** — AI agents need prior context across sessions to maintain consistency
3. **Decision history** — preserves the rationale and evolution of architectural and product decisions

### Installer behaviour

The `ma-agents` installer automatically removes `_bmad-output/` from `.gitignore` if it finds it there. This is intentional — if your IDE or tooling suggests adding `_bmad-output/` to `.gitignore`, you should decline. The folder is project knowledge, not build artefacts.

> **Do not add `_bmad-output/` to your `.gitignore`** — the installer will remove it automatically if it appears there.

---

## Project Context

When you run `npx ma-agents install` at the project level, ma-agents automatically generates
`_bmad-output/project-context.md` — a constitutional document that governs how AI agents
behave in this project.

**What it contains:**
- Mandatory pre-task rules: which MANIFEST.yaml files to read, which skills to load
- Git workflow mandate: fresh worktrees per mission (not just branches)
- Agent mission lifecycle: 8-step sequence from pre-flight to post-mission cleanup

**It is safe to edit.** The installer never regenerates the file from scratch once it exists.
On reinstall, only the `## AI Agent Mandatory Rules` MANIFEST paths section is updated
if new agents have been added — all your custom edits are preserved. Edit it freely — it belongs to your project.

**Expand it over time:**
- After architecture phase: run `/bmad-generate-project-context` to auto-detect your stack
- After each sprint: run `/bmad-retrospective`, then `/project-context-expansion`
- Manually: add conventions you notice agents getting wrong

The file is version-controlled as part of `_bmad-output/` project knowledge. Commit it.

---

## On-Prem / Air-Gapped Deployment

When running AI coding agents against a locally-hosted LLM (e.g., Nemotron Super 49B on vLLM), `ma-agents install` asks a one-time profile question at setup:

```
? Profile (standard / on-prem):
```

Your answer is persisted in `.ma-agents.json` under the `profile` field and is read on every subsequent install, update, or reconfigure. The manifest also records the `toolVersion` (ma-agents version) and `bmadVersion` (bundled bmad-method version) on every install, making it easy to verify what ran last. The `standard` profile produces the same output as always; the `on-prem` profile additionally stamps on-prem-specific guardrails into every agent's instruction block — including `/no_think` directives for planning personas, `str_replace_editor` prohibition, and home-directory write restrictions.

To change your profile after initial setup: `npx ma-agents reconfigure`
To remove all on-prem profile artifacts: `npx ma-agents uninstall --profile-artifacts`

### What the on-prem profile stamps

| File | What is added |
|------|--------------|
| `CLAUDE.md` | Universal instruction block + on-prem guardrails (inside `MA-AGENTS-START/END` markers) |
| `.roo/rules/00-ma-agents.md` | Same block for Roo Code |
| `.clinerules` + `.cline/clinerules.md` | Same block for Cline |
| `AGENTS.md` | Same block for OpenCode |
| `opencode.json` | Additive entry in `instructions[]` array |
| `.roomodes` | 4 BMAD planning modes with `fileRegex` phase enforcement |
| `_bmad/_config/agents/bmm-*.customize.yaml` | Per-persona phase prefix: planning personas get `/no_think` prefix; dev personas get careful-coding prefix |

The standard profile stamps the universal block only (no `/no_think`, no `str_replace_editor` prohibition, no home-dir restriction).

For vLLM server configuration, quantization tradeoffs, per-phase sampling parameters, and the `str_replace_editor` hallucination mitigation, see [`docs/deployment/vllm-nemotron.md`](docs/deployment/vllm-nemotron.md).

---

## Supported Coding Tools

Skills can be installed into any of these AI coding agents:

| Tool | Project Path | Template | Instruction File |
|------|-------------|----------|------------------|
| Claude Code | `.claude/skills/` | `claude-code` | `.claude/CLAUDE.md` |
| Google Gemini | `.gemini/skills/` | `generic` | `.gemini/gemini.md` |
| GitHub Copilot | `.github/copilot/skills/` | `generic` | `.github/copilot/copilot.md` |
| Cursor | `.cursor/skills/` | `generic` | `.cursor/cursor.md` |
| Kilocode | `.kilocode/skills/` | `generic` | `.kilocode/kilocode.md` |
| Cline | `.cline/skills/` | `cline` | `.cline/clinerules.md` |
| Roo Code | `.roo/skills/` | `generic` | `.roo/rules/00-ma-agents.md` |
| Antigravity | `_bmad/skills/` | `generic` | `_bmad/bmm/agents/antigravity.md` |
| OpenCode | `.opencode/skills/` | `generic` | `opencode.json` |

## Specialized BMAD Agents

These domain-expert agents are installed alongside BMAD-METHOD and provide guided workflows through their agent menus:

| Agent | Persona | Skills Path | Instruction File |
|-------|---------|-------------|------------------|
| SRE Agent | Alex | `_bmad/skills/sre/` | `_bmad/bmm/agents/sre.md` |
| DevOps Agent | Amit | `_bmad/skills/devops/` | `_bmad/bmm/agents/devops.md` |
| Cyber Analyst | Yael | `_bmad/skills/cyber/` | `_bmad/bmm/agents/cyber.md` |
| ML Scientist | Demerzel | `_bmad/skills/demerzel/` | `_bmad/bmm/agents/demerzel.md` |
| SQA & Standards Expert | Gad | `_bmad/skills/sqa/` | `_bmad/bmm/agents/qa.md` |

## Available Skills

### General-Purpose Skills (34)

These skills are installed into your coding tool of choice and provide reusable best-practice guidance:

| Skill ID | Domain | Description |
| :--- | :--- | :--- |
| **General** | | |
| `code-review` | Quality | Comprehensive reviews following best practices and security guidelines |
| `commit-message` | Git | Generates conventional commit messages from code changes |
| `test-generator` | Testing | Generates comprehensive unit and integration tests |
| `test-accompanied-development` | Quality | Enforces "test-alongside" policy for every public method |
| `code-documentation` | Quality | Enforces PEP 257, Doxygen, JSDoc, and XML standards |
| `skill-creator` | Meta | Guide for creating new skills to extend agent capabilities |
| `document-revision-history` | Documentation | Manages revision history tables at the beginning of generated documents |
| `ai-audit-trail` | Audit | Tracks AI agent session activity, time spent, and token usage |
| `open-presentation` | Methodology | Opens the BMAD-METHOD AI Development Training presentation (`/open-presentation`) |
| **Security** | | |
| `python-security-skill` | Python | OWASP Top 10 2025 aligned guardrails for Python |
| `js-ts-security-skill` | JS/TS | Security verification for JS/TS codebases (OWASP aligned) |
| `create-hardened-docker-skill` | Docker | Creates production-ready hardened Docker (CIS/NIST) |
| `verify-hardened-docker-skill` | Docker | Security verification for Docker configurations |
| **Dependencies** | | |
| `python-dependency-mgmt` | Python | Best practices for `uv` (lockfiles/sync) and `pip` |
| `js-ts-dependency-mgmt` | JS/TS | Stability and security for NPM, Yarn, and PNPM |
| **Modern C++** | | |
| `cpp-memory-handling` | C++ | RAII, smart pointers, and safe buffer management |
| `cpp-robust-interfaces` | C++ | Contract-based design and strong typing (C++14+) |
| `cpp-modern-composition` | C++ | Replaces C-style patterns with STL and Ranges |
| `cpp-const-correctness` | C++ | Immutability-by-default and `constexpr` logic |
| `cpp-concurrency-safety` | C++ | RAII locking and task-based parallelism |
| `cmake-best-practices` | Build | Target-based, property-oriented CMake patterns |
| **Architecture** | | |
| `logging-best-practices` | Logic | Standardized structured logging (JSON) across domains |
| `opentelemetry-best-practices` | Logic | Distributed tracing and semantic conventions |
| `vercel-react-best-practices` | Web | 57 Performance rules for React and Next.js |
| `git-workflow-skill` | Git | Worktree-based feature branch workflow |
| `self-signed-cert` | Security | Automated Root CA and self-signed certificate generation |
| `docker-image-signing` | Security | Automated cryptographic signing for Docker images |
| `docker-hardening-verification` | Security | Audits images for least-privilege and OpenShift compatibility |

### Agent Workflows (34)

These workflows are installed as part of the BMAD agent system and are invoked through the agent's menu (not installed individually):

| Workflow | Agent | Description |
| :--- | :--- | :--- |
| **Machine Learning (Demerzel)** | | |
| `ml-ideation` | ML Scientist | Frame ML research problem, produce Research Thesis and PRD |
| `ml-eda` | ML Scientist | Exploratory Data Analysis, establish baselines, produce EDA report |
| `ml-architecture` | ML Scientist | Model architecture, stack, and experiment tracking strategy |
| `ml-detailed-design` | ML Scientist | Implementation task breakdown (INF-* and EXP-* namespaces) |
| `ml-techspec` | ML Scientist | Lock experiment parameters and performance tiers before training |
| `ml-infra` | ML Scientist | Build ML infrastructure, manage dependencies, run smoke tests |
| `ml-experiment` | ML Scientist | Execute training experiments against locked TechSpec, log metrics |
| `ml-analysis` | ML Scientist | Evaluate experiment outcomes against TechSpec success tiers |
| `ml-hparam` | ML Scientist | Automated hyperparameter optimization (Optuna, W&B Sweeps, Ray Tune) |
| `ml-revision` | ML Scientist | Amend hypothesis and requirements based on experiment findings |
| `ml-advise` | ML Scientist | Search past experiments, surface findings and failure warnings |
| `ml-retrospective` | ML Scientist | Capture session learnings and update project context |
| **SQA & MIL-STD-498 (Gad)** | | |
| `sqa-audit` | SQA & Standards Expert | Multi-dimensional project quality audit: code↔story traceability, stories↔architecture/PRD alignment, process compliance, sprint health, release state — saves audit report and optional remediation plan |
| `sqa-ieee12207` | SQA & Standards Expert | IEEE/ISO/IEC 12207:2017 compliance assessment across 23 process areas in 4 groups — produces compliance matrix, gap analysis, and optional remediation plan |
| `sqa-requirements-quality` | SQA & Standards Expert | Requirements quality audit against 14 criteria with scope selection (PRD FRs, NFRs, epics, stories) — per-requirement audit table, critical-fail detection, Overall Quality Score, and optional remediation plan |
| `mil498-srs` | SQA & Standards Expert | Generate Software Requirements Specification (SRS) per MIL-STD-498 DID |
| `mil498-sdd` | SQA & Standards Expert | Generate Software Design Description (SDD) per MIL-STD-498 DID |
| `mil498-sdp` | SQA & Standards Expert | Generate Software Development Plan (SDP) per MIL-STD-498 DID |
| `mil498-ocd` | SQA & Standards Expert | Generate Operational Concept Description (OCD) per MIL-STD-498 DID |
| `mil498-sss` | SQA & Standards Expert | Generate System/Subsystem Specification (SSS) per MIL-STD-498 DID |
| `mil498-std` | SQA & Standards Expert | Generate Software Test Description (STD) per MIL-STD-498 DID |
| `mil498-ssdd` | SQA & Standards Expert | Generate System/Subsystem Design Description (SSDD) per MIL-STD-498 DID |
| `mil498-requirement-quality` | SQA & Standards Expert | Evaluate requirements against 14 quality criteria — per-requirement audit table, Missing Elements report, and Overall Quality Score (MIL-STD-498 context) |
| **Sprint Management** | | |
| `bmad-sprint-planning` | Scrum Master | Bootstrap or refresh the unified `sprint-status.yaml` from epics and bug stories |
| `generate-backlog` | Scrum Master | Generate or refresh the `backlog` section of `sprint-status.yaml` from epics |
| `add-sprint` | Scrum Master | Add a new sprint entry to the `sprints` map with capacity and optional ISO dates |
| `add-to-sprint` | Scrum Master | Move backlog items into a sprint using atomic movement semantics |
| `remove-from-sprint` | Scrum Master | Return sprint items to the backlog with status reset and priority assignment |
| `modify-sprint` | Scrum Master | Update sprint metadata (name, capacity, dates, status transitions) |
| `sprint-status-view` | Scrum Master | Display formatted sprint progress, backlog, and epic status (read-only) |
| `bmad-sprint-status` | Scrum Master | Analyze sprint health, surface risk flags, and recommend next actions |
| `cleanup-done` | Scrum Master | Archive done/cancelled items — remove from `sprint-status.yaml` and move files to `done/` |
| `close-sprint` | Scrum Master | Full sprint closure — archive done items, disposition incomplete items, set sprint to closed |
| `prioritize-backlog` | Scrum Master | Reprioritize backlog using severity, business value, dependencies, type, and age |

## Automated Skill Discovery

`ma-agents` features an automated discovery system that ensures installed skills are actually used by the agent without manual configuration.

### 1. The Manifest (`MANIFEST.yaml`)
Every installation automatically generates a `MANIFEST.yaml` in the skills directory. It contains:
- **Skill IDs and Paths**: Where to find the instructions.
- **`applies_when` Conditions**: Hints about when a skill should be loaded (e.g., "when writing public APIs").
- **`always_load` Flags**: Mandatory skills that should always be in context.

### 2. Instruction Injection
The installer automatically updates agent-specific instruction files (like `CLAUDE.md` or `.clinerules`) with a "Planning Instruction" block. This block tells the agent to:
1. Consult the `MANIFEST.yaml` before starting a task.
2. Select and read only the relevant skills for the current context.

---

## CLI Usage

```bash
npx ma-agents                              # Launch interactive wizard
npx ma-agents install                      # Interactive install wizard
npx ma-agents install --yes                # Non-interactive, use defaults (CI/CD)
npx ma-agents install --yes --agent <id>   # Non-interactive, target one agent
npx ma-agents install --log                # Log all output to install_<datetime>.log
npx ma-agents status                       # Show installed skills and paths
npx ma-agents list                         # List all available skills
npx ma-agents agents                       # List supported agents
npx ma-agents uninstall <skill> <agents>   # Direct uninstall
npx ma-agents reconfigure               # Re-run profile prompt and re-stamp all artifacts
npx ma-agents uninstall --profile-artifacts  # Remove on-prem profile content from all agent files
```

### The Update Process
Running `ma-agents` on a project where skills are already installed triggers the **Update Flow**:
1. **Detection**: Recognizes existing `.ma-agents.json` manifest.
2. **Selection**: Allows you to add new skills or remove existing ones.
3. **Synchronization**: 
   - Re-injects the latest instructions into `CLAUDE.md`, `.clinerules`, etc.
   - Regenerates the `MANIFEST.yaml` to reflect the current skill set.
   - Updates BMAD-METHOD personas and workflows to the latest versions if detected.

### BMAD-METHOD Integration
`ma-agents` bundles [BMAD-METHOD](https://docs.bmad-method.org/) **v6.2.2** to provide advanced orchestration and specialized personas.

#### Core Features
- **Auto-Detection**: Recognizes existing BMAD installations and prompts for silent updates.
- **Silent Setup**: Non-interactive installation/update of BMAD tailored to your project's agents.
- **Customization Engine**: Injects project-specific `.customize.yaml` templates to align agents with your workflow.
- **Advanced Agent Templates**: Deploys full XML-structured agent definitions directly into the BMAD system.

#### Bundled & Offline Installation (v2.20+)

`ma-agents` ships with everything needed to install BMAD without any network access at install time:

- **`bmad-method` is a direct npm dependency** — no runtime `npx bmad-method` fetch required. The correct version is pinned and bundled inside `node_modules/` when you `npm install ma-agents`.
- **External modules pre-bundled** — `lib/bmad-cache/` ships the 4 optional BMAD modules (`bmb`, `cis`, `gds`, `tea`) inside the package itself. They are pre-populated to `~/.bmad/cache/external-modules/` before any install runs, so BMAD never needs to clone them from GitHub.
- **Deterministic installs** — same `ma-agents` version always produces the same `_bmad/` output, regardless of network conditions (NFR21).
- **Air-gapped friendly** — install from a tarball (`npm install ./ma-agents-x.y.z.tgz`) and run `npx ma-agents install` completely offline.

```
npm install ma-agents          # bundles bmad-method + 4 external modules
npx ma-agents install --yes    # fully offline BMAD install — no network needed
```

#### Specialized BMAD Agents
1. **SRE Agent (Alex)**:
   - **Focus**: High availability, Kubernetes, Docker, and Podman.
   - **Capabilities**: Day 1/2 operations, GitOps (ArgoCD/Flux), and advanced deployment strategies (Canary, Blue-Green).
   - **Workflows**: System status, drift detection, and automated troubleshooting.
2. **DevOps Agent (Amit)**:
   - **Focus**: Build automation and multi-environment deployment.
   - **Capabilities**: Helm charts/umbrellas, Docker Compose, and infrastructure provisioning (PV/PVC/LB).
   - **On-Prem Support**: Specialized strategies for disconnected (air-gapped) environments.
3. **Cyber Analyst (Yael)**:
   - **Focus**: Cyber immunity, security auditing, and vulnerability management.
   - **Capabilities**: Immunity estimation (scoring), Vault secret management, and PKI automation.
   - **Integration**: Orchestrates ma-agents security skills for deep scans.
4. **Demerzel (ML Scientist)**:
   - **Focus**: Hypothesis-driven machine learning lifecycle with scientific rigor.
   - **Capabilities**: EDA, architecture design, locked TechSpec contracts, experiment execution, failure-cost analysis.
   - **Workflows**: 12-stage ML lifecycle from ideation through retrospective, with mandatory review gates.
5. **Gad (SQA & Standards Expert)**:
   - **Focus**: Software quality assurance and defense documentation standards — a unified persona covering SQA auditing and MIL-STD-498 document generation.
   - **SQA Capabilities**: Multi-dimensional project quality audits, IEEE/ISO/IEC 12207:2017 compliance assessments (23 process areas, 4 groups), requirements evaluation against 14 established quality criteria (scope-selectable: PRD FRs, NFRs, epics, stories).
   - **MIL-STD-498 Capabilities**: Full Data Item Description (DID) generation for SRS, SDD, SDP, OCD, SSS, STD, and SSDD. Requirements quality review tailored to MIL-STD-498 structure and military-standard terminology (CSCI, HWCI, IRS).
   - **Remediation**: All audit and compliance workflows offer an optional remediation plan (`sqa-remediation-plan-{date}.md`) and per-finding `create-bug-story` integration for critical gaps.

#### Operational Workflows
The integration includes a suite of specialized playbooks:
- **GitOps & Deployment**: Canary releases, rolling updates, and sync monitoring.
- **Infrastructure**: PV/PVC management, Load Balancer configuration, and storage setup.
- **Security & Trust**: Vault secrets, certificate generation, and vulnerability scanning.
- **Diagnostics**: Advanced health checks across K8s, Docker, and Podman.

#### Sprint Management (v4.0+)

`ma-agents` includes a complete sprint management system built on a **unified `sprint-status.yaml`** — a single file that is the sole source of truth for all sprint and backlog state.

**Data Model:**

The entire sprint state lives in one file at `_bmad-output/implementation-artifacts/sprint-status.yaml`:

```yaml
# Metadata
generated: <ISO-8601>
last_updated: <ISO-8601>
project: <string>
project_key: <string>
tracking_system: file-system   # or "jira" (future)
story_location: _bmad-output/implementation-artifacts

# Three data sections
epics:
  epic-17:
    status: in-progress        # backlog | in-progress | done | on-hold | cancelled
    retrospective: optional

backlog:                       # ordered array — position = priority
  - id: "17-10-rework-generate-backlog"
    type: story                # story | bug
    epic: 17
    title: "Rework generate-backlog Skill"
    priority: 1                # denormalized index, kept in sync with array position
    status: ready-for-dev
    severity: null             # null for stories; critical|high|medium|low for bugs

sprints:
  sprint-1:
    name: "Sprint 1"
    status: active             # planning | active | closed
    capacity: 8
    start: "2026-04-01"
    end: "2026-04-14"
    items:
      - id: "17-10-rework-generate-backlog"
        type: story
        epic: 17
        title: "Rework generate-backlog Skill"
        status: in-progress
        severity: null         # no priority field — ordering is implicit in array position
```

**Workflows:**

| Command | Description |
|---------|-------------|
| `/bmad-sprint-planning` | Bootstrap or refresh the entire `sprint-status.yaml` from epics |
| `/generate-backlog` | Refresh the `backlog` section from epic/story definitions |
| `/add-sprint` | Add a new sprint entry to the `sprints` map |
| `/add-to-sprint` | Move backlog items into a sprint (atomic — removes from backlog, adds to sprint) |
| `/remove-from-sprint` | Return sprint items to the backlog (status reset to `ready-for-dev`) |
| `/modify-sprint` | Update sprint metadata (name, capacity, dates, status transitions) |
| `/sprint-status-view` | Display sprint progress, backlog, and epic status (read-only) |
| `/bmad-sprint-status` | Sprint health analysis with risk flags and recommendations |
| `/cleanup-done` | Archive done/cancelled items — remove from YAML, move files to `done/` |
| `/close-sprint` | Full sprint closure — archive done items, disposition incomplete items |
| `/prioritize-backlog` | Reorder backlog — full, quick-adjust, or AI-suggested modes |

**Key Design Principles:**
- **Single file, single truth**: all state lives in `sprint-status.yaml` — no separate backlog or sprint files
- **Movement semantics**: items exist in exactly one location (backlog OR a sprint, never both)
- **Forward-only transitions**: sprint status follows `planning → active → closed` with no reversals
- **Single-active-sprint constraint**: at most one sprint can have `status: active` at any time
- **Done item archival**: completed work is removed from the YAML entirely and files moved to `done/`
- **Priority as denormalized index**: backlog array order is authoritative; `priority` field mirrors position
- **Jira-ready**: `tracking_system: jira` routes all operations through a Jira adapter (Epic 14)

### Install Options (Direct)
```bash
# Default: installs to project-level paths (current directory)
npx ma-agents install code-review claude-code

# Install to global/user-level paths
npx ma-agents install code-review claude-code --global

# Install to a custom directory
npx ma-agents install code-review claude-code --path ./my-skills

# Skip all prompts, use defaults — ideal for CI/CD pipelines
npx ma-agents install --yes
npx ma-agents install --yes --global
npx ma-agents install --yes --agent claude-code

# Target a specific agent (skips agent selection prompt)
npx ma-agents install code-review --agent cursor

# Force overwrite without upgrade prompts
npx ma-agents install code-review claude-code --force
```

| Flag | Description |
|------|-------------|
| `--yes` | Skip all prompts, use defaults. Selects all detected agents, installs/updates BMAD automatically. |
| `--agent <name>` | Target a specific agent — skips agent selection. Run `npx ma-agents agents` for valid names. |
| `--force` | Skip upgrade prompts, always overwrite existing installations. |
| `--global` | Install to global/user-level paths instead of project-level. |
| `--path <dir>` | Custom installation directory. |
| `--log` | Log all console output to `install_<datetime>.log` in the current directory. |

## Requirements

### Global Requirements
- **Node.js**: v16+ (npx support)
- **Git**: Required for git-related skills and version detection.
- **Bash**: Most skill scripts require a bash-compliant shell.

### Skill-Specific Requirements
- **Python Security/Deps**: `pip`, `uv` (recommended), `pip-audit`.
- **JS/TS Security/Deps**: `npm`, `yarn`, or `pnpm`.
- **C++ Skills**: C++14+ compiler recommended.
- **Docker Skills**: `docker`, `docker-compose`, `trivy` (for scanning).
- **Git Workflow**: `gh` (GitHub CLI) for PR automation.

## Skill Structure

Every skill follows a unified structure. See [SKILLS_STRUCTURE.md](SKILLS_STRUCTURE.md) for full documentation.

```
skills/<skill-name>/
├── skill.json              # Metadata — single source of truth (required)
├── SKILL.md                # Main instructions in pure Markdown (required)
├── claude-code.md          # Claude Code-specific template (optional)
├── cline.md                # Cline-specific template (optional)
├── generic.md              # Generic template for other agents (optional)
├── template.md             # Output template for the agent (optional)
├── scripts/                # Executable scripts (optional)
├── references/             # Documentation and reference material (optional)
├── examples/               # Sample outputs (optional)
├── hooks/                  # Git hooks or other hook scripts (optional)
└── assets/                 # Config files, templates, resources (optional)
```

### Key Design Decisions

- **`skill.json` is the single source of truth** for metadata (`name`, `description`). YAML frontmatter is injected automatically at install time — you never write it in source files.
- **Template priority**: The installer looks for `<agent-template>.md` first (e.g., `claude-code.md`), then `generic.md`, then falls back to `SKILL.md`.
- **Resource mapping**: Some agents use different directory names. For example, Cline expects `docs/` instead of `references/` and `templates/` instead of `assets/`. The installer handles this mapping automatically.

## Creating a New Skill

### 1. Create the skill directory

```bash
mkdir -p skills/my-skill
```

### 2. Create `skill.json`

```json
{
  "name": "My Skill",
  "description": "What this skill does in one sentence",
  "version": "1.0.0",
  "author": "Your Name",
  "tags": ["category", "keywords"]
}
```

### 3. Create `SKILL.md`

Write pure Markdown instructions. Do **not** add YAML frontmatter — the installer injects it from `skill.json`.

```markdown
# My Skill

## Purpose
What problem this skill solves.

## Instructions
Step-by-step instructions for the agent.

## Rules
Constraints the agent must follow.

## Output Format
What the agent should produce.
```

### 4. Add optional resources

```bash
mkdir -p skills/my-skill/scripts      # Executable scripts
mkdir -p skills/my-skill/references    # Documentation
mkdir -p skills/my-skill/examples      # Sample outputs
```

### 5. (Optional) Create agent-specific templates

If a skill needs different instructions for different agents:

```bash
# Claude Code gets tailored instructions
skills/my-skill/claude-code.md

# Cline gets its own version
skills/my-skill/cline.md

# All other agents use SKILL.md
```

### 6. Test

```bash
npx ma-agents list                          # Verify it appears
npx ma-agents install my-skill claude-code  # Test installation
```

## Adding a New Agent

Edit [lib/agents.js](lib/agents.js) and add a new entry to the `agents` array:

```javascript
{
  id: 'my-agent',
  name: 'My Agent',
  description: 'My Agent Description',
  getProjectPath: () => path.join(process.cwd(), '.my-agent', 'skills'),
  getGlobalPath: () => {
    const platform = os.platform();
    if (platform === 'win32') {
      return path.join(os.homedir(), 'AppData', 'Roaming', 'MyAgent', 'skills');
    } else if (platform === 'darwin') {
      return path.join(os.homedir(), 'Library', 'Application Support', 'MyAgent', 'skills');
    } else {
      return path.join(os.homedir(), '.config', 'my-agent', 'skills');
    }
  },
  fileExtension: '.md',
  template: 'generic',
  // Optional: rename resource directories to match agent's native structure
  resourceMap: {
    'references': 'docs',
    'assets': 'templates'
  }
}
```

### Agent Configuration Fields

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique kebab-case identifier (used in CLI) |
| `name` | Yes | Display name shown to users |
| `description` | Yes | Brief description |
| `getProjectPath` | Yes | Returns project-level skills directory |
| `getGlobalPath` | Yes | Returns global/user-level skills directory (platform-specific) |
| `fileExtension` | Yes | File extension for skill files (usually `.md`) |
| `template` | Yes | Template ID — determines which `.md` file to look for first |
| `resourceMap` | No | Maps generic directory names to agent-specific names |

## Project Structure

```
ma-agents/
├── bin/
│   └── cli.js                  # CLI entry point (wizard + commands)
├── lib/
│   ├── agents.js               # Agent configurations, paths, and extraInstructionTemplates
│   ├── installer.js            # Skill installation, instruction-block stamping, marker management
│   ├── bmad.js                 # BMAD-METHOD integration, recompile, persona phase prefix
│   ├── profile.js              # Profile persistence (getProfile / setProfile / resolveProfile / clearProfile)
│   ├── reconfigure.js          # ma-agents reconfigure — re-stamp profile-dependent artifacts
│   ├── uninstall.js            # ma-agents uninstall --profile-artifacts
│   ├── merge/
│   │   └── roomodes.js         # YAML merger for .roomodes slug collision / user-slug preservation
│   ├── templates/
│   │   ├── instruction-block-universal.template.md   # Universal planning-instruction block
│   │   ├── instruction-block-onprem.template.md      # On-prem guardrails append (profile=on-prem)
│   │   ├── roomodes.template.yaml                    # 4 BMAD Roo Code modes with fileRegex
│   │   ├── agents-md.template.md                     # AGENTS.md for OpenCode
│   │   ├── clinerules.template.md                    # .clinerules expansion for Cline
│   │   └── project-context.template.md               # project-context.md generation template
│   ├── bmad-customize/         # Per-persona customize.yaml with phase: + on_prem_phase_prefix:
│   ├── bmad-cache/             # Pre-bundled BMAD external modules (bmb, cis, gds, tea)
│   ├── bmad-customizations/    # BMAD persona templates (.md) and YAML configs
│   ├── bmad-extension/         # Extension module: sprint management, bug tracking, agent skills
│   ├── bmad-workflows/         # Specialized BMAD playbooks (SRE, Cyber, etc.)
│   └── mil498-templates/       # MIL-STD-498 DID library (SRS, SSS, SSDD, etc.)
├── scripts/
│   └── build-bmad-cache.js     # Rebuilds lib/bmad-cache/ from upstream repos
├── skills/
│   ├── code-review/            # 27 bundled skills across 5 domains
│   ├── commit-message/
│   ├── create-hardened-docker-skill/
│   ├── git-workflow-skill/
│   ├── js-ts-security-skill/
│   ├── skill-creator/
│   ├── test-generator/
│   ├── vercel-react-best-practices/
│   └── verify-hardened-docker-skill/
├── test/
│   └── yes-flag.test.js        # Tests for --yes / --agent flag behavior
├── docs/
│   └── validation/             # Manual validation reports (e.g., bundled install)
├── SKILLS_STRUCTURE.md         # Full skill authoring documentation
├── package.json
└── README.md
```

## Development

```bash
# Clone the repository
git clone https://github.com/mayafit/AI_Agents.git
cd AI_Agents

# Install dependencies
npm install

# Run locally
node bin/cli.js

# Test skill listing
node bin/cli.js list

# Test agents listing
node bin/cli.js agents

# Run tests
npm test

# Rebuild the bundled BMAD module cache (lib/bmad-cache/)
npm run build:bmad-cache
```

## Programmatic API

```javascript
const { installSkill, listSkills, listAgents } = require('ma-agents');

// List all available skills
const skills = listSkills();

// List all supported agents
const agents = listAgents();

// Install a skill programmatically
await installSkill('code-review', ['claude-code', 'copilot'], '', 'project');
```

## Contributing

Contributions welcome:

- **New skills** — Follow the structure in [SKILLS_STRUCTURE.md](SKILLS_STRUCTURE.md)
- **New agents** — Add to [lib/agents.js](lib/agents.js) with both project and global paths
- **Bug fixes** and improvements

## License

MIT
