ma-agents 2.19.2 → 2.20.0

package/docs/architecture.md

@@ -0,0 +1,284 @@
+# Architecture — ma-agents
+
+**Generated:** 2026-03-04 | **Version:** 2.19.2
+
+## 1. Executive Summary
+
+ma-agents is a CLI tool that bridges the gap between AI coding assistants by providing a universal skill installation pipeline. The architecture is designed around three core concerns: **skill discovery** (finding and reading skill packages), **translation** (adapting generic skills to agent-specific formats), and **state management** (tracking installations via manifests for upgrade/downgrade detection).
+
+## 2. Architecture Pattern
+
+**Modular Pipeline Architecture** with a Registry-Based Plugin System.
+
+```
+User Input (CLI/API)
+        │
+        ▼
+┌─────────────────┐
+│   CLI Router     │  bin/cli.js — command parsing, interactive wizard
+│   (Entry Point)  │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     ┌──────────────────┐
+│  Installer       │────▶│  Agent Registry   │  lib/agents.js
+│  Engine          │     │  (11 agents)      │  — paths, templates, resource maps
+│  lib/installer.js│     └──────────────────┘
+│                  │
+│  • Skill listing │     ┌──────────────────┐
+│  • Install flow  │────▶│  Skill Library    │  skills/
+│  • Uninstall     │     │  (27 skills)      │  — skill.json + SKILL.md + resources
+│  • Manifest mgmt │     └──────────────────┘
+│  • Upgrade detect│
+│  • MANIFEST.yaml │     ┌──────────────────┐
+│  • Instruction   │────▶│  BMAD Integration │  lib/bmad.js
+│    injection     │     │  — install/update  │  — customizations, workflows, templates
+└─────────────────┘     │  — customize       │
+                         └──────────────────┘
+```
+
+## 3. Core Components
+
+### 3.1 CLI Router (`bin/cli.js`)
+
+**Responsibility**: User-facing command interface.
+
+**Commands**: `install`, `uninstall`, `status`, `list`, `agents`, `help`, `version`
+
+**Key Flows**:
+- **Interactive Mode** (no args): Presents wizard with install/status/list/agents options
+- **Install Wizard**: Multi-step prompt flow — select skills → select agents (IDE + BMAD separately) → choose scope → BMAD integration → confirm → execute
+- **Direct Install**: `npx ma-agents install <skill> <agents...> [--global] [--force] [--path <dir>]`
+- **Update Flow**: Detects existing `.ma-agents.json`, offers update/reinstall/uninstall options, handles skill additions and agent deselections
+
+**Design Decisions**:
+- Agents are presented in two groups: IDE Coding Assistants and BMAD Method Agents
+- The wizard pre-populates selections from existing installs during updates
+- BMAD integration prompt appears after scope selection for project-level installs
+
+### 3.2 Installer Engine (`lib/installer.js`)
+
+**Responsibility**: Core installation logic, manifest management, skill discovery.
+
+**Key Functions**:
+
+| Function | Purpose |
+|----------|---------|
+| `listSkills()` | Scans `skills/` directory, reads `skill.json` metadata |
+| `installSkill()` | Orchestrates install with upgrade detection, groups agents by path |
+| `performInstall()` | Low-level: template selection → frontmatter injection → file copy → resource mapping |
+| `uninstallSkill()` | Handles multi-agent manifests, only deletes files when no agents remain |
+| `generateSkillsManifest()` | Writes `MANIFEST.yaml` with skill IDs, descriptions, `applies_when`, `always_load` |
+| `updateAgentInstructions()` | Injects `<!-- MA-AGENTS-START -->` planning block into agent instruction files |
+| `compareSemver()` | Simple 3-part semver comparison for upgrade detection |
+| `getStatus()` | Reads manifests across all agents, reports installed skills |
+
+**Installation Pipeline**:
+
+```
+1. Validate skill exists in skills/
+2. Group agents by resolved install path (deduplication)
+3. For each path group:
+   a. Check existing manifest for version comparison
+   b. If installed: prompt upgrade/skip/reinstall/remove (unless --force)
+   c. Resolve template: <agent-template>.md → generic.md → SKILL.md
+   d. Strip existing frontmatter, inject from skill.json
+   e. Write SKILL.md to target directory
+   f. Copy resource directories with agent-specific remapping
+   g. Copy template.md if exists
+   h. Update .ma-agents.json manifest
+   i. Generate MANIFEST.yaml
+   j. Inject planning instruction into agent instruction files
+```
+
+**Manifest System** (`.ma-agents.json`):
+- Tracks installed skills with version, timestamps, installer version, agent version
+- Supports multi-agent manifests (v1.1.0): multiple agents can share one install path
+- Backward-compatible with v1.0.0 single-agent manifests
+- Enables upgrade detection via semver comparison
+
+### 3.3 Agent Registry (`lib/agents.js`)
+
+**Responsibility**: Agent configuration — paths, templates, resource mappings.
+
+**Schema per Agent**:
+
+```javascript
+{
+  id: 'agent-id',           // Unique kebab-case identifier
+  name: 'Display Name',     // Human-readable name
+  version: '1.0.0',         // Agent config version (independent semver)
+  category: 'ide' | 'bmad', // Agent category
+  description: 'Brief...',  // Description for CLI display
+  getProjectPath: () => ..., // Project-level skills directory
+  getGlobalPath: () => ...,  // Global/user-level skills directory (platform-aware)
+  fileExtension: '.md',      // Skill file extension
+  template: 'generic',       // Template priority ID
+  resourceMap: {},            // Optional: directory name remapping
+  instructionFiles: []        // Files to inject planning instruction into
+}
+```
+
+**Registered Agents** (11):
+
+| ID | Category | Template | Resource Map |
+|----|----------|----------|-------------|
+| `claude-code` | ide | claude-code | — |
+| `gemini` | ide | generic | — |
+| `copilot` | ide | generic | — |
+| `cursor` | ide | generic | — |
+| `cline` | ide | cline | references→docs, assets→templates |
+| `kilocode` | ide | generic | — |
+| `antigravity` | ide | generic | — |
+| `bmm-sre` | bmad | generic | — |
+| `bmm-devops` | bmad | generic | — |
+| `bmm-cyber` | bmad | generic | — |
+| `bmm-mil498` | bmad | generic | — |
+
+**Platform-Aware Paths**: Each agent's `getGlobalPath()` handles win32, darwin, and linux differently using `os.platform()` and `os.homedir()`.
+
+### 3.4 BMAD Integration (`lib/bmad.js`)
+
+**Responsibility**: Install, update, and customize BMAD-METHOD in target projects.
+
+**Key Functions**:
+
+| Function | Purpose |
+|----------|---------|
+| `isBmadInstalled()` | Checks for `_bmad/` directory |
+| `installBmad()` | Resolves bmad-method via `require.resolve` and runs `node <resolved-path> install --yes` with module/tool flags |
+| `updateBmad()` | Resolves bmad-method via `require.resolve` and runs `node <resolved-path> install --action update --yes` |
+| `applyCustomizations()` | 6-step post-install customization pipeline |
+| `registerMilWorkflows()` | Appends MIL-STD-498 entries to BMAD CSV registries |
+
+**Customization Pipeline** (6 steps, order-critical):
+
+```
+1. Apply YAML customizations → _bmad/_config/agents/*.customize.yaml
+2. Apply agent .md templates → _bmad/custom/agents/*.md
+3. Recompile BMAD (node <resolved-path> install) — regenerates _bmad/bmm/ tree
+4. Apply workflows → _bmad/bmm/workflows/ (AFTER recompile to persist)
+5. Apply MIL-STD-498 templates → _bmad/bmm/templates/mil498/ (AFTER recompile)
+6. Copy compiled agents → _bmad/bmm/agents/*.md (AFTER recompile)
+7. Register MIL workflows → append to module-help.csv and bmad-help.csv
+```
+
+**Critical Order Dependency**: Steps 3-6 must run AFTER the BMAD recompile in step 3 because recompile regenerates the `_bmad/bmm/` tree and would wipe files placed there earlier.
+
+### 3.5 Skill Library (`skills/`)
+
+**Responsibility**: Bundled skill packages following the unified structure.
+
+**Skill Structure**:
+
+```
+skills/<skill-name>/
+├── skill.json              # Metadata (name, description, version, tags)
+├── SKILL.md                # Main instructions (pure markdown, no frontmatter)
+├── claude-code.md           # Agent-specific template (optional)
+├── cline.md                 # Agent-specific template (optional)
+├── generic.md               # Generic template (optional)
+├── template.md              # Output template (optional)
+├── scripts/                 # Executable scripts (optional)
+├── references/              # Documentation (optional)
+├── examples/                # Sample outputs (optional)
+├── hooks/                   # Git hooks (optional)
+└── assets/                  # Configs, templates (optional)
+```
+
+**Template Resolution Priority**: `<agent-template>.md` → `generic.md` → `SKILL.md`
+
+**Skills by Domain** (27 total):
+- **General** (7): code-review, commit-message, test-generator, test-accompanied-development, code-documentation, skill-creator, document-revision-history, ai-audit-trail
+- **Security** (5): python-security-skill, js-ts-security-skill, create-hardened-docker-skill, verify-hardened-docker-skill, docker-image-signing, docker-hardening-verification
+- **Dependencies** (2): python-dependency-mgmt, js-ts-dependency-mgmt
+- **Modern C++** (6): cpp-memory-handling, cpp-robust-interfaces, cpp-modern-composition, cpp-const-correctness, cpp-concurrency-safety, cmake-best-practices
+- **Architecture** (5): logging-best-practices, opentelemetry-best-practices, vercel-react-best-practices, git-workflow-skill, self-signed-cert
+
+## 4. Data Flow
+
+### 4.1 Install Flow
+
+```
+User runs: npx ma-agents install code-review claude-code
+
+1. cli.js parses args → handleInstall()
+2. installer.installSkill('code-review', ['claude-code'])
+3. Resolve install path: .claude/skills/
+4. Check .ma-agents.json for existing version
+5. performInstall():
+   a. Find template: claude-code.md (exists) ✓
+   b. Read source, strip frontmatter
+   c. Inject frontmatter from skill.json
+   d. Write to .claude/skills/code-review/SKILL.md
+   e. Copy scripts/, references/ (no resourceMap remapping for claude-code)
+6. Update .ma-agents.json manifest
+7. Generate .claude/skills/MANIFEST.yaml
+8. Inject planning block into .claude/CLAUDE.md
+```
+
+### 4.2 BMAD Integration Flow
+
+```
+User selects BMAD install during wizard
+
+1. bmad.isBmadInstalled() → false
+2. bmad.installBmad(['bmm', 'bmb'], ['claude-code'])
+   → execSync('node <resolved-path> install --yes --modules bmm,bmb --tools claude-code')
+   (where <resolved-path> = require.resolve('bmad-method/tools/bmad-npx-wrapper.js'))
+3. bmad.applyCustomizations():
+   a. Copy .customize.yaml files to _bmad/_config/agents/
+   b. Copy agent .md templates to _bmad/custom/agents/
+   c. Recompile BMAD (node <resolved-path> install)
+   d. Copy workflows to _bmad/bmm/workflows/
+   e. Copy MIL-498 templates to _bmad/bmm/templates/mil498/
+   f. Copy compiled agents to _bmad/bmm/agents/
+   g. Register MIL workflows in CSV registries
+```
+
+## 5. Key Design Decisions
+
+### 5.1 Single Source of Truth for Metadata
+
+`skill.json` is the only place skill metadata (name, description, version) lives. Frontmatter is **injected at install time**, never authored manually. This prevents metadata drift across multiple files.
+
+### 5.2 Path Deduplication
+
+When multiple agents share the same install path (e.g., agents with identical `getProjectPath()`), the installer groups them and performs the file operations **once**, then updates the manifest with all agent IDs. This prevents redundant file copies.
+
+### 5.3 Multi-Agent Manifests
+
+The `.ma-agents.json` manifest evolved from v1.0.0 (single `agent` field) to v1.1.0 (array `agents` field) to support shared install paths. The code includes backward-compatibility migration.
+
+### 5.4 BMAD Post-Recompile Ordering
+
+BMAD customizations follow a strict order: YAML configs and custom agents must be placed **before** recompile (so BMAD can use them), while workflows, templates, and compiled agents must be placed **after** recompile (to avoid being wiped by the regeneration).
+
+### 5.5 Agent Instruction Injection
+
+The installer uses `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` HTML comment markers to manage its injected planning block in agent instruction files. This allows idempotent updates without corrupting user content.
+
+### 5.6 BMAD Agent File Protection
+
+When an agent instruction file doesn't exist and the agent category is `bmad`, the installer **skips** creating it. BMAD agent files are full persona definitions — creating them with only the MA-AGENTS block would destroy the agent.
+
+## 6. External Dependencies
+
+| Dependency | Type | Purpose |
+|------------|------|---------|
+| `prompts` | npm | Interactive terminal prompts (select, multiselect, confirm, text) |
+| `chalk` | npm | Terminal color/style formatting |
+| `fs-extra` | npm | Extended fs operations (ensureDir, copy, outputFile, remove) |
+| `bmad-method` | npm (local dep) | BMAD-METHOD installation and compilation (resolved via `require.resolve`, invoked as `node <resolved-path>`) |
+
+## 7. Versioning Strategy
+
+Three independent semver tracks:
+
+| Scope | Location | Bump When |
+|-------|----------|-----------|
+| Package | `package.json` | CLI changes, new features, bug fixes |
+| Skill | `skills/<name>/skill.json` | Skill content changes |
+| Agent | `lib/agents.js` (per agent) | Agent config changes (paths, templates, resource maps) |
+
+The installer compares skill versions between the package and installed manifests to offer upgrade/skip/downgrade options.

package/docs/development-guide.md

@@ -0,0 +1,122 @@
+# Development Guide — ma-agents
+
+**Generated:** 2026-03-04 | **Version:** 2.19.2
+
+## Prerequisites
+
+- **Node.js**: v16.0.0 or higher
+- **npm**: Bundled with Node.js
+- **Git**: Required for version control and git-related skills
+- **Bash**: Required for most skill scripts
+
+## Setup
+
+```bash
+git clone https://github.com/mayafit/AI_Agents.git
+cd AI_Agents
+npm install
+node bin/cli.js help
+```
+
+## Project Structure
+
+```
+bin/cli.js              # CLI entry point (wizard, commands, flags)
+lib/
+├── agents.js           # Agent registry (paths, versions, resource maps)
+├── installer.js        # Core logic (install, uninstall, manifest, status)
+├── bmad.js             # BMAD-METHOD integration
+├── bmad-customizations/# BMAD persona templates and YAML configs
+├── bmad-workflows/     # Specialized BMAD playbooks
+└── mil498-templates/   # MIL-STD-498 DID library
+skills/                 # 27 bundled skills (one directory per skill)
+index.js                # Programmatic API exports
+```
+
+## Common Development Tasks
+
+### Run CLI Locally
+
+```bash
+node bin/cli.js                    # Interactive wizard
+node bin/cli.js list               # List skills
+node bin/cli.js agents             # List agents
+node bin/cli.js status             # Show installed
+node bin/cli.js help               # Help text
+```
+
+### Test Install/Uninstall
+
+```bash
+node bin/cli.js install code-review claude-code --force
+node bin/cli.js status
+node bin/cli.js uninstall code-review claude-code
+```
+
+### Quick Smoke Test (Programmatic)
+
+```bash
+node -e "const m = require('.'); console.log('Skills:', m.listSkills().length, 'Agents:', m.listAgents().length)"
+```
+
+### Add a New Skill
+
+1. `mkdir -p skills/my-skill`
+2. Create `skill.json` with `name`, `description`, `version`
+3. Create `SKILL.md` — pure Markdown, no YAML frontmatter
+4. (Optional) Add `scripts/`, `references/`, `examples/`, `hooks/`, `assets/`
+5. (Optional) Create agent-specific templates: `claude-code.md`, `cline.md`, `generic.md`
+6. Verify: `node bin/cli.js list`
+7. Test install: `node bin/cli.js install my-skill claude-code`
+
+### Add a New Agent
+
+1. Edit `lib/agents.js`
+2. Add entry to `agents` array with all required fields
+3. Verify: `node bin/cli.js agents`
+4. Test install: `node bin/cli.js install code-review my-agent`
+
+## Versioning
+
+Three independent semver tracks:
+
+| Scope | File | Bump When |
+|-------|------|-----------|
+| Package | `package.json` | CLI or API changes |
+| Skill | `skills/<name>/skill.json` | Skill content changes |
+| Agent | `lib/agents.js` | Agent config changes |
+
+## Commit Conventions
+
+[Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new skill for API testing
+fix: correct Cline resource mapping
+chore: bump code-review to v1.0.1
+docs: update SKILLS_STRUCTURE.md
+refactor: extract manifest logic
+```
+
+Scopes: `cli`, `installer`, `agents`, `skills`, `docs`
+
+## Pre-Publish Checklist
+
+- [ ] Package version bumped in `package.json`
+- [ ] Skill versions bumped for changed skills
+- [ ] Agent versions bumped for changed configs
+- [ ] `node bin/cli.js list` — all skills appear
+- [ ] `node bin/cli.js agents` — all agents appear
+- [ ] Fresh install test with `--force`
+- [ ] Upgrade detection test (run install again without `--force`)
+- [ ] Uninstall test
+- [ ] Status test
+- [ ] Help text up to date
+- [ ] Conventional commit message
+
+## Code Style
+
+- 2 spaces indentation
+- Follow existing patterns
+- Comments for complex logic only
+- Functions kept focused and small

package/docs/index.md

@@ -0,0 +1,48 @@
+# Project Documentation Index — ma-agents
+
+## Project Overview
+
+- **Type:** Monolith — CLI Tool with Plugin/Skill System
+- **Primary Language:** JavaScript (Node.js >=16)
+- **Architecture:** Modular installer pipeline with registry-based agent targeting
+- **Version:** 2.19.2
+
+### Quick Reference
+
+- **Framework:** Custom CLI (prompts + chalk)
+- **Entry Points:** `bin/cli.js` (CLI), `index.js` (API)
+- **Dependencies:** prompts, chalk, fs-extra
+- **External:** bmad-method (npx, runtime)
+- **Skills:** 27 bundled across 5 domains
+- **Agents:** 11 supported (6 IDE + 5 BMAD)
+
+## Generated Documentation
+
+- [Project Overview](./project-overview.md)
+- [Architecture](./architecture.md)
+- [Source Tree Analysis](./source-tree-analysis.md)
+- [Development Guide](./development-guide.md)
+
+## Existing Documentation
+
+- [README.md](../README.md) — Full project documentation with usage, skills list, and structure
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Contribution guidelines for skills, agents, PRs
+- [DEVELOPMENT.md](../DEVELOPMENT.md) — Development guide with versioning, testing, and publish checklist
+- [QUICK_START.md](../QUICK_START.md) — 2-minute getting started guide
+- [SKILLS_STRUCTURE.md](../SKILLS_STRUCTURE.md) — Skill authoring specification and agent output formats
+- [LICENSE](../LICENSE) — MIT License
+
+## Getting Started
+
+```bash
+# Clone and setup
+git clone https://github.com/mayafit/AI_Agents.git
+cd AI_Agents
+npm install
+
+# Run the CLI
+node bin/cli.js
+
+# Quick smoke test
+node -e "const m = require('.'); console.log('Skills:', m.listSkills().length, 'Agents:', m.listAgents().length)"
+```

package/docs/project-overview.md

@@ -0,0 +1,56 @@
+# Project Overview — ma-agents
+
+**Generated:** 2026-03-04 | **Version:** 2.19.2
+
+## Executive Summary
+
+**ma-agents** is a universal NPX CLI tool that installs AI coding agent skills across multiple AI assistants. It provides a "write once, install everywhere" approach — skills are authored in a unified generic format and the installer translates them into each agent's native structure (frontmatter injection, directory mapping, manifest generation).
+
+The tool supports 11 target agents (6 IDE-based coding assistants + 5 BMAD-METHOD specialized agents) and ships with 27 bundled skills across 5 domains: General, Security, Dependencies, Modern C++, and Architecture.
+
+## Key Value Proposition
+
+- **Universal Skill Format**: Single skill definition works across Claude Code, Gemini, Copilot, Cursor, Cline, and Kilocode
+- **Automated Discovery**: Generates `MANIFEST.yaml` and injects planning instructions into agent config files
+- **BMAD-METHOD Integration**: First-class support for BMAD's multi-agent orchestration system with specialized personas (SRE, DevOps, Cyber, MIL-STD-498)
+- **Upgrade Detection**: Semver-based version tracking with upgrade/downgrade/skip workflows
+
+## Technology Stack
+
+| Category | Technology | Version |
+|----------|-----------|---------|
+| Runtime | Node.js | >=16.0.0 |
+| Language | JavaScript (CommonJS) | ES2017+ |
+| CLI Interaction | prompts | ^2.4.2 |
+| Terminal Styling | chalk | ^4.1.2 |
+| File System | fs-extra | ^11.1.1 |
+| Distribution | npm (npx) | N/A |
+| External Integration | bmad-method (npx) | N/A |
+
+## Architecture Classification
+
+- **Repository Type**: Monolith
+- **Project Type**: CLI Tool with Plugin/Skill System
+- **Architecture Pattern**: Modular installer pipeline with registry-based agent targeting
+- **Entry Points**: `bin/cli.js` (CLI), `index.js` (programmatic API)
+
+## Repository Structure
+
+```
+ma-agents/
+├── bin/cli.js              # CLI entry point
+├── lib/                    # Core logic (installer, agents, BMAD integration)
+├── skills/                 # 27 bundled skills
+├── mil498/                 # MIL-STD-498 DID templates
+├── examples/               # Programmatic usage examples
+├── index.js                # Programmatic API
+└── package.json
+```
+
+See [Source Tree Analysis](./source-tree-analysis.md) for full annotated directory tree.
+
+## Links
+
+- [Architecture](./architecture.md)
+- [Development Guide](./development-guide.md)
+- [Source Tree Analysis](./source-tree-analysis.md)

package/docs/project-scan-report.json

@@ -0,0 +1,50 @@
+{
+  "workflow_version": "1.2.0",
+  "timestamps": {
+    "started": "2026-03-04T10:00:00Z",
+    "last_updated": "2026-03-04T10:15:00Z",
+    "completed": "2026-03-04T10:15:00Z"
+  },
+  "mode": "initial_scan",
+  "scan_level": "deep",
+  "project_root": "d:/Code/agents",
+  "project_knowledge": "d:/Code/agents/docs",
+  "project_types": [
+    {
+      "part_id": "main",
+      "project_type_id": "cli",
+      "display_name": "CLI Tool (ma-agents)"
+    }
+  ],
+  "repository_type": "monolith",
+  "completed_steps": [
+    {"step": "step_0.5", "status": "completed", "timestamp": "2026-03-04T10:01:00Z", "summary": "Loaded documentation requirements for 12 project types"},
+    {"step": "step_1", "status": "completed", "timestamp": "2026-03-04T10:02:00Z", "summary": "Classified as monolith with 1 part: CLI tool (ma-agents)"},
+    {"step": "step_2", "status": "completed", "timestamp": "2026-03-04T10:03:00Z", "summary": "Found 6 existing docs (README, CONTRIBUTING, DEVELOPMENT, QUICK_START, SKILLS_STRUCTURE, LICENSE)"},
+    {"step": "step_3", "status": "completed", "timestamp": "2026-03-04T10:04:00Z", "summary": "Tech stack: JavaScript/Node.js with prompts, chalk, fs-extra"},
+    {"step": "step_4", "status": "completed", "timestamp": "2026-03-04T10:06:00Z", "summary": "Deep scan of all source files in bin/, lib/, skills/. CLI type - no API/data/UI scans required"},
+    {"step": "step_5", "status": "completed", "timestamp": "2026-03-04T10:07:00Z", "summary": "Source tree documented with 6 critical folders"},
+    {"step": "step_6", "status": "completed", "timestamp": "2026-03-04T10:08:00Z", "summary": "Dev setup and deployment documented"},
+    {"step": "step_8", "status": "completed", "timestamp": "2026-03-04T10:10:00Z", "summary": "Architecture doc written for 1 part"},
+    {"step": "step_9", "status": "completed", "timestamp": "2026-03-04T10:12:00Z", "summary": "Supporting docs written: project-overview, development-guide"},
+    {"step": "step_10", "status": "completed", "timestamp": "2026-03-04T10:13:00Z", "summary": "Master index generated"},
+    {"step": "step_11", "status": "completed", "timestamp": "2026-03-04T10:14:00Z", "summary": "Validation complete - no incomplete markers"},
+    {"step": "step_12", "status": "completed", "timestamp": "2026-03-04T10:15:00Z", "summary": "Workflow complete"}
+  ],
+  "current_step": "completed",
+  "findings": {
+    "project_classification": "Monolith CLI tool, 1 part, JavaScript/Node.js",
+    "technology_stack": "JavaScript/Node.js with prompts, chalk, fs-extra",
+    "existing_docs_count": 6,
+    "architecture_pattern": "Modular installer pipeline with registry-based agent targeting"
+  },
+  "outputs_generated": [
+    "project-scan-report.json",
+    "source-tree-analysis.md",
+    "project-overview.md",
+    "architecture.md",
+    "development-guide.md",
+    "index.md"
+  ],
+  "resume_instructions": "Workflow completed successfully"
+}

package/docs/source-tree-analysis.md

@@ -0,0 +1,84 @@
+# Source Tree Analysis — ma-agents
+
+**Generated:** 2026-03-04 | **Scan Level:** Deep
+
+## Annotated Directory Tree
+
+```
+ma-agents/
+├── bin/
+│   └── cli.js                          # CLI entry point — wizard, command routing, flag parsing
+├── lib/
+│   ├── agents.js                       # Agent registry — 11 agent configs (paths, versions, resource maps)
+│   ├── installer.js                    # Core engine — install, uninstall, manifest, upgrade detection, MANIFEST.yaml generation
+│   ├── bmad.js                         # BMAD-METHOD integration — install/update/customize via node <require.resolve'd path>
+│   ├── bmad-customizations/            # BMAD persona templates and YAML customization configs
+│   │   ├── *.customize.yaml            # Per-agent YAML customizations (claude-code, cline, cursor, gemini, antigravity, bmm-*)
+│   │   ├── sre.md                      # SRE Agent (Alex) full persona definition
+│   │   ├── devops.md                   # DevOps Agent (Amit) full persona definition
+│   │   ├── cyber.md                    # Cyber Analyst (Yael) full persona definition
+│   │   └── mil498.md                   # MIL-STD-498 Expert (Joseph) full persona definition
+│   ├── bmad-workflows/                 # Specialized BMAD playbooks deployed post-recompile
+│   │   ├── cyber/                      # Cyber security operational workflows
+│   │   ├── devops/                     # DevOps deployment/infra workflows
+│   │   ├── mil498/                     # MIL-STD-498 document generation workflows (SRS, SDD, SDP, OCD, SSS, STD, SSDD)
+│   │   └── sre/                        # SRE operational workflows
+│   └── mil498-templates/               # MIL-STD-498 DID templates (SRS, SDD, SDP, OCD, SSS, STD, SSDD)
+├── skills/                             # 27 bundled skills (one directory per skill)
+│   ├── ai-audit-trail/                 # AI session activity tracking
+│   ├── cmake-best-practices/           # CMake build patterns
+│   ├── code-documentation/             # Documentation standards enforcement
+│   ├── code-review/                    # Comprehensive code review
+│   ├── commit-message/                 # Conventional commit generation
+│   ├── cpp-concurrency-safety/         # C++ RAII locking and parallelism
+│   ├── cpp-const-correctness/          # C++ immutability patterns
+│   ├── cpp-memory-handling/            # C++ smart pointers and RAII
+│   ├── cpp-modern-composition/         # C++ STL and Ranges patterns
+│   ├── cpp-robust-interfaces/          # C++ contract-based design
+│   ├── create-hardened-docker-skill/   # Docker hardening (CIS/NIST)
+│   ├── docker-hardening-verification/  # Docker security audit
+│   ├── docker-image-signing/           # Docker image cryptographic signing
+│   ├── document-revision-history/      # Revision history management
+│   ├── git-workflow-skill/             # Worktree-based git workflow
+│   ├── js-ts-dependency-mgmt/          # JS/TS dependency best practices
+│   ├── js-ts-security-skill/          # JS/TS OWASP security verification
+│   ├── logging-best-practices/         # Structured JSON logging
+│   ├── opentelemetry-best-practices/   # Distributed tracing
+│   ├── python-dependency-mgmt/         # Python dependency management
+│   ├── python-security-skill/          # Python OWASP security
+│   ├── self-signed-cert/               # Root CA and certificate generation
+│   ├── skill-creator/                  # Meta: guide for creating new skills
+│   ├── test-accompanied-development/   # Test-alongside enforcement
+│   ├── test-generator/                 # Unit/integration test generation
+│   ├── vercel-react-best-practices/    # React/Next.js performance rules
+│   └── verify-hardened-docker-skill/   # Docker config verification
+├── mil498/                             # Published MIL-STD-498 DID templates (user-facing copies)
+├── examples/
+│   └── programmatic-usage.js           # Programmatic API usage example
+├── index.js                            # Programmatic API entry point (exports core functions)
+├── package.json                        # NPM package config (ma-agents v2.19.2)
+├── README.md                           # Full project documentation
+├── CONTRIBUTING.md                     # Contribution guidelines
+├── DEVELOPMENT.md                      # Development guide with versioning and testing
+├── QUICK_START.md                      # 2-minute getting started guide
+├── SKILLS_STRUCTURE.md                 # Skill authoring specification
+└── LICENSE                             # MIT License
+```
+
+## Critical Folders
+
+| Folder | Purpose | Key Files |
+|--------|---------|-----------|
+| `bin/` | CLI entry point | `cli.js` — command routing, interactive wizard, install/uninstall handlers |
+| `lib/` | Core business logic | `installer.js` (install engine), `agents.js` (agent registry), `bmad.js` (BMAD integration) |
+| `lib/bmad-customizations/` | BMAD agent personas and configs | `.customize.yaml` files + `.md` agent definitions |
+| `lib/bmad-workflows/` | BMAD operational playbooks | Subdirs per domain: cyber, devops, mil498, sre |
+| `lib/mil498-templates/` | MIL-STD-498 DID templates | 7 document templates (SRS, SDD, SDP, OCD, SSS, STD, SSDD) |
+| `skills/` | Bundled skill library | 27 skills across 5 domains (General, Security, Dependencies, C++, Architecture) |
+
+## Entry Points
+
+| Entry Point | Usage | Purpose |
+|-------------|-------|---------|
+| `bin/cli.js` | `npx ma-agents` | CLI — interactive wizard and direct commands |
+| `index.js` | `require('ma-agents')` | Programmatic API — `installSkill`, `listSkills`, `listAgents`, etc. |