ma-agents 3.5.6 → 3.6.1

package/.ma-agents.json

@@ -0,0 +1,10 @@
+{
+  "manifestVersion": "1.2.0",
+  "agent": null,
+  "agents": [
+    null
+  ],
+  "scope": "project",
+  "skills": {},
+  "profile": "standard"
+}

package/AGENTS.md

@@ -0,0 +1,97 @@
+<!-- Generated by ma-agents. Edit outside the MA-AGENTS-START/END markers to preserve your changes. -->
+# Project Agent Instructions
+
+This file is auto-discovered by OpenCode and any agent that respects `AGENTS.md`.
+It establishes universal safety rules, text-vs-file discipline, and BMAD phase
+discipline for every agent operating in this project.
+
+## Universal Rules
+
+The universal rules block below is stamped and maintained by ma-agents. Edit
+outside the HTML-comment `MA-AGENTS` start and end markers to preserve your
+own additions — content inside the markers is regenerated on every install.
+
+<!-- MA-AGENTS-START -->
+# AI Agent Skills - Planning Instruction
+
+You have access to a library of skills in your skills directory. Before starting any task:
+
+1. Read the skill manifest at .opencode/skills/MANIFEST.yaml
+2. Based on the task description, select which skills are relevant
+3. Read only the selected skill files
+4. Then proceed with the task
+
+Always load skills marked with always_load: true.
+Do not load skills that are not relevant to the current task.
+
+## Respond in TEXT vs. create FILES
+
+Choose your response medium deliberately. Defaulting to file creation when the user asked a question is a common failure mode — especially for coding agents running in web UIs.
+
+- **Create or modify FILES when the user's request contains file-action keywords:** `create`, `write`, `generate`, `build`, `implement` (and obvious synonyms such as `add`, `produce`, `refactor`, `fix`, `update <file>`). These signal a concrete artifact is expected.
+- **Respond in TEXT when the request contains text-response keywords:** `what do you think`, `how should we`, `discuss`, `opinion` (and obvious synonyms such as `explain`, `why`, `should I`, `compare`, `recommend`). These signal that a conversation is expected, not a deliverable.
+- **If unsure, respond in TEXT.** A text answer can always be followed by file creation on confirmation; an unwanted file cannot be cleanly undone.
+- **Never create `response.md`, `output.md`, or any similarly named scratch file as a reply.** A reply belongs in the chat transcript, not on disk.
+- **Confirm file paths before writing.** When you are about to create or modify a file whose path the user has not explicitly named, state the intended path in text and wait for confirmation, unless the path is unambiguous from the task context.
+
+## BMAD phase discipline
+
+BMAD-METHOD organizes work into declared phases (analysis, planning, architecture, story-creation, implementation, review). Respect the currently declared phase.
+
+- **Do not skip ahead to implementation during planning.** If the project is in a planning phase — or the user has asked for requirements, architecture, or a story — produce planning artifacts, not code.
+- **Do not retroactively plan after you have already coded.** If implementation has already started, flag the gap instead of fabricating back-dated planning documents.
+- The declared phase is established by the active skill, the story status, or an explicit statement from the user. When none of these is available, ask before assuming.
+<!-- MA-AGENTS-END -->
+
+## Critical Behavior Rules
+
+These rules are non-negotiable across every profile and every agent.
+
+- **Never create files in `~/.claude/` or any user home directory.** All
+  project artifacts must land inside the current working directory. Home-
+  directory writes cross-contaminate between projects and are a common source
+  of secret/config leakage.
+- **Never write outside the project root without an explicit user request
+  naming the absolute path.** "Write to disk" means the project, not the
+  operator's machine.
+- **Do not modify files you did not read first.** Read the current content
+  before proposing or performing an edit — blind writes silently destroy user
+  work.
+
+## BMAD Phase Declaration
+
+BMAD-METHOD organizes work into four phases. Respect the currently declared
+phase; do not skip ahead to the next phase without a phase transition signal
+from the user, the active skill, or the story status.
+
+- **Discovery / PM (analysis, planning).** Deliverables: product briefs,
+  PRDs, market and domain research, epics and stories lists. Do NOT produce
+  code, architecture diagrams, or implementation artifacts in this phase.
+  When asked "what do you think", respond in text.
+- **Architecture.** Deliverables: solution design, component boundaries,
+  data-flow, interface contracts. Do NOT write application code or skill
+  implementations. Narrate decisions and capture them as documents.
+- **Tech Lead / Stories.** Deliverables: individual story files with full
+  acceptance criteria, task breakdowns, and dev notes. Do NOT begin
+  implementation — stories are contracts the implementer consumes later.
+- **Implementation.** Deliverables: code, tests, and the Dev Agent Record on
+  the story file. At this phase, write files. Do NOT retroactively fabricate
+  planning documents for code that already exists — flag the gap instead.
+
+When no phase is declared (no active skill, no story in progress, no explicit
+user statement), ask before assuming.
+
+## Project BMAD Output Structure
+
+BMAD artifacts live under `_bmad-output/` (or the paths configured in
+`_bmad/bmm/config.yaml` when present). The install-time resolver logs the
+resolved paths on each run; consult that log output if in doubt.
+
+- **Planning artifacts** — PRDs, product briefs, market and domain research.
+- **Architecture artifacts** — solution design, component boundaries. May be
+  co-located with planning artifacts when no separate directory is configured.
+- **Implementation artifacts (stories)** — individual story files and their
+  Dev Agent Records.
+
+Always consult the `MANIFEST.yaml` referenced inside the universal block above
+for the full list of installed skills and their locations.

package/MANIFEST.yaml

@@ -0,0 +1,3 @@
+# MANIFEST.yaml
+
+skills:

package/README.md

@@ -36,8 +36,9 @@ Skills are written in a **unified generic format** and stored in this package. W
 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 Instructions**: Injects planning hints into agent files (e.g., `CLAUDE.md`, `.clinerules`) to ensure the agent uses the skills.
-7. **BMAD-METHOD Integration**: Automatically detects and integrates with [BMAD-METHOD](https://docs.bmad-method.org/), applying project-specific customizations and orchestration.
+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
@@ -103,6 +104,37 @@ The file is version-controlled as part of `_bmad-output/` project knowledge. Com
 
 ---
 
+## 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:
@@ -246,6 +278,8 @@ 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
@@ -573,16 +607,25 @@ ma-agents/
 ├── bin/
 │   └── cli.js                  # CLI entry point (wizard + commands)
 ├── lib/
-│   ├── agents.js               # Agent configurations and paths
-│   ├── installer.js            # Skill discovery and installation logic
-│   ├── bmad.js                 # BMAD-METHOD integration and injection logic
+│   ├── 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
-│   │   ├── skills/             # SKILL.md packages (add-sprint, generate-backlog, etc.)
-│   │   ├── workflows/          # Legacy workflow copies (redirects to SKILL.md)
-│   │   ├── module.yaml         # Extension module definition
-│   │   └── module-help.csv     # Skill registry with descriptions and output paths
 │   ├── bmad-workflows/         # Specialized BMAD playbooks (SRE, Cyber, etc.)
 │   └── mil498-templates/       # MIL-STD-498 DID library (SRS, SSS, SSDD, etc.)
 ├── scripts/

package/_bmad-output/implementation-artifacts/21-10-profile-reconfigure.md

@@ -1,6 +1,6 @@
 # Story 21.10: Profile Reconfigure
 
-Status: ready-for-dev
+Status: Review
 
 ## Story
 
@@ -117,21 +117,45 @@ Match the existing test layout (node:test or mocha-style — verify by reading o
 
 ### Epic 21 Cross-Story Context
 
-**Story 21.10 (this):** Reconfigure subcommand — escape hatch for a previously-persisted profile. Depends on Stories 21.1 (profile API), 21.2 (marker injection + backup convention), 21.3 (slug-stomp protection), 21.5 (dual-file drift detection), 21.6 (on-prem layer composition — the actual content being re-stamped). Runs after 21.6 in the execution order; must exist before 21.9's end-to-end tests so the round-trip test (21.9 AC #1 (f)) can exercise the real command instead of manual `.ma-agents.json` edits.
+**Story 21.10 (this):** Reconfigure subcommand — escape hatch for a previously-persisted profile. Depends on Stories 21.1 (profile API), 21.2 (marker injection + backup convention), 21.3 (slug-stomp protection), 21.4 (`AGENTS.md` template + `markdown-markers` merger — re-stamped on profile flip), 21.5 (dual-file drift detection), 21.6 (on-prem layer composition — the actual content being re-stamped), 21.7 (BMAD persona `on_prem_phase_prefix` — re-composed when profile flips, per Task 3.3). Runs after 21.6 in the execution order; must exist before 21.9's end-to-end tests so the round-trip test (21.9 AC #1 (f)) can exercise the real command instead of manual `.ma-agents.json` edits.
 
 ## Dev Agent Record
 
 ### Agent Model Used
-_(to be filled by dev agent)_
+Claude Opus 4.6 (1M context) — bmad-dev-story flow.
 
 ### Debug Log References
-_(to be filled by dev agent)_
+- `.roomodes` slug-divergence comparison deliberately strips `customInstructions` because installed files already carry the profile-composed universal block; a profile flip legitimately rewrites that field. `whenToUse`, `roleDefinition`, `groups`, `name` are the user-editable surfaces the check catches. Documented inline in `lib/reconfigure.js::checkRoomodesSlugDivergence`.
+- `updateAgentInstructions` is invoked with `yesMode: true` from the reconfigure loop so per-file drift prompts do not re-ask after the global `Continue?` confirmation (AC #7). The installer's `handleMarkerBlockDrift` still emits the pinned WARNING line and writes the canonical `<target>.backup-<ISO>` sibling (AC #8).
+- `appendProfileHistory` does a fresh read-modify-write of `.ma-agents.json` so it composes with `setProfile`'s write — no parallel JSON-IO path. Cap enforcement is `shift()`-based (oldest-first eviction).
 
 ### Completion Notes List
-_(to be filled by dev agent)_
+- New `lib/reconfigure.js` orchestrator exports `reconfigure({ projectRoot, argv, promptsLib, now })` plus three named error classes (`RoomodesSlugDivergenceError`, `ManifestNotFoundError`, `ReconfigureYesRejectedError`) and the `PROFILE_HISTORY_CAP` constant (20).
+- `bin/cli.js` registers the `reconfigure` verb and routes to `handleReconfigure`, which maps each error class to a user-facing exit(1) message. `--yes` on reconfigure exits nonzero with the pinned message verbatim (AC #6).
+- Re-stamp reuses the canonical `updateAgentInstructions` path from `lib/installer.js`; zero forked logic. Backups are produced by the installer's existing drift handler using the canonical `buildBackupFilename` helper owned by Story 21.2.
+- `checkRoomodesSlugDivergence` throws `RoomodesSlugDivergenceError` when any ma-agents-owned slug present in the existing `.roomodes` differs from the shipped template on non-customInstructions fields; `--force-roomodes-overwrite` bypasses the check (AC #9). `.clinerules` dual-file drift is delegated to Story 21.5's `checkClinerulesDualFileDrift` (no override, AC #10).
+- `profileHistory` append uses a fresh read-modify-write that composes with `setProfile`'s write — capped at 20, oldest-first eviction (AC #11). Missing-field start is handled (first reconfigure creates the array).
+- Prompt shape mirrors Story 21.1's wizard prompt (same two choices) but with `initial` set to the persisted value's row and the message `Current profile: <value>. Change to?` per AC #2.
+
+### Adversarial Review Findings
+
+| # | Layer | Severity | Finding | Disposition |
+|---|-------|----------|---------|-------------|
+| 1 | Cynical | P1 | setProfile runs BEFORE re-stamp loop; mid-flight re-stamp failure leaves profile+artifacts out of sync | Accepted — story explicitly lists "Auto-rollback" as out of scope; `profileHistory` append is gated on full loop success so forensic log does not falsely record a partial reconfigure |
+| 2 | Cynical | P2 | `--yes` detection is string-includes on argv; benign for reconfigure (no positional args) | Accepted — same pattern as installer; reconfigure AC #1 forbids positional args |
+| 3 | Edge-case | P1 | Slug-divergence check drops `customInstructions` from the compare | Correct by design — installer-stamped `customInstructions` carries the composed block which legitimately changes per profile; other fields remain user-edit detectors. Test 8.7 exercises `whenToUse` drift |
+| 4 | Cynical | P2 | `appendProfileHistory` is read-modify-write, not atomic rename | Accepted — matches `setProfile`'s write pattern; reconfigure is interactive-only so concurrency isn't a realistic vector |
+| 5 | Edge-case | P2 | Same-value short-circuit when `persistedProfile === undefined` requires user to pick a value; cannot short-circuit to undefined | Accepted — prompt choices are `on-prem` | `standard` only; chosenProfile is always a concrete value |
+| 6 | Edge-case | P2 | No help-text doc for `--force-roomodes-overwrite` | **Fixed** — added Reconfigure options block in `showHelp()` |
 
 ### File List
-_(to be filled by dev agent)_
+- CREATED: `lib/reconfigure.js`
+- CREATED: `test/reconfigure.test.js` (12 tests, all passing)
+- MODIFIED: `bin/cli.js` (new `reconfigure` case + `handleReconfigure` + help text)
+- MODIFIED: `package.json` (added `test/reconfigure.test.js` to npm test script)
+- MODIFIED: `_bmad-output/implementation-artifacts/21-10-profile-reconfigure.md` (Dev Agent Record / File List / Change Log)
 
 ## Change Log
+- 2026-04-15: Story 21.10 implemented — reconfigure CLI verb + orchestrator + slug/dual-file guards + profileHistory append. Status ready-for-dev → review.
+- 2026-04-15: Upstream dependency list completed per adversarial-review finding — added Stories 21.4 (`AGENTS.md` re-stamping surface), 21.7 (BMAD persona phase prefix re-composition). Restores Dependencies bidirectionality with those stories' downstream lists.
 - 2026-04-14: Story created (Epic 21, Story 21.10). Closes adversarial-review Findings #5 and #7 (no escape hatch for persisted profile; CI-default silent-downgrade trap).

package/_bmad-output/implementation-artifacts/21-11-profile-uninstall.md

@@ -129,7 +129,7 @@ Story 21.1 AC #1 pinned `lib/profile.js` to exactly three exports: `getProfile`,
 
 ### Epic 21 Cross-Story Context
 
-**Story 21.11 (this):** Uninstall subcommand — rollback path for profile-dependent content. Depends on Stories 21.1 (profile API — extends it), 21.2 (marker injection + backup convention), 21.3 (slug list + audit log), 21.6 (on-prem layer composition — reverses it), 21.10 (`profileHistory` field — preserves + appends). Runs LAST in the Epic 21 execution order (after 21.9) because the 21.9 end-to-end test harness needs uninstall as part of round-trip coverage, and uninstall must not land before all upstream stamping work is committable.
+**Story 21.11 (this):** Uninstall subcommand — rollback path for profile-dependent content. Depends on Stories 21.1 (profile API — extends it), 21.2 (marker injection + backup convention), 21.3 (slug list + audit log), 21.4 (`AGENTS.md` — removes the ma-agents-stamped file / marker block), 21.5 (`.clinerules` + `.cline/clinerules.md` — removes both Cline rule files' ma-agents marker blocks), 21.6 (on-prem layer composition — reverses it), 21.7 (BMAD persona `on_prem_phase_prefix` — strips prefix when uninstalling profile artifacts), 21.10 (`profileHistory` field — preserves + appends). Runs LAST in the Epic 21 execution order (after 21.9) because the 21.9 end-to-end test harness needs uninstall as part of round-trip coverage, and uninstall must not land before all upstream stamping work is committable.
 
 ## Dev Agent Record
 
@@ -146,4 +146,5 @@ _(to be filled by dev agent)_
 _(to be filled by dev agent)_
 
 ## Change Log
+- 2026-04-15: Upstream dependency list completed per adversarial-review finding — added Stories 21.4 (`AGENTS.md` removal surface), 21.5 (`.clinerules` dual-file removal surface), 21.7 (BMAD persona phase-prefix strip on uninstall). Restores Dependencies bidirectionality with those stories' downstream lists.
 - 2026-04-14: Story created (Epic 21, Story 21.11). Closes adversarial-review Finding #17 (no uninstall / rollback path).