ma-agents 2.18.0 → 2.19.0

package/README.md

@@ -61,7 +61,7 @@ skills/code-review/
 | Joseph (MIL-STD-498) | `_bmad/skills/` | `generic` | `_bmad/bmm/agents/mil498.md` |
 | Antigravity | `_bmad/skills/` | `generic` | `_bmad/bmm/agents/antigravity.md` |
 
-## Available Skills (25)
+## Available Skills (27)
 
 | Skill ID | Domain | Description |
 | :--- | :--- | :--- |
@@ -72,6 +72,8 @@ skills/code-review/
 | `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 |
 | **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) |

package/lib/bmad-workflows/mil498/ocd/instructions.md

@@ -40,6 +40,16 @@ This defines the required DID sections and content expectations for each paragra
 
 Write the document in {document_output_language}, populating each template section. The OCD should be written in language accessible to users and stakeholders, minimizing technical jargon.
 
+### Revision History
+
+Before writing any content, add a **Revision History table** immediately after the document title. If this is a new document, create the table with version `1.0`. If updating an existing document, read the existing revision history and add a new row with an incremented version number and a summary of all changes made in this session. See the `document-revision-history` skill for full formatting rules.
+
+```markdown
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {date} | Agent ({model}) | Initial document generation |
+```
+
 ### Section 1: Scope
 - **1.1 Identification**: Extract system name, version, identifiers from PRD
 - **1.2 System overview**: Summarize the system purpose from the user's perspective

package/lib/bmad-workflows/mil498/sdd/instructions.md

@@ -66,6 +66,16 @@ This defines the required DID sections and content expectations for each paragra
 
 Write the document in {document_output_language}, populating each template section.
 
+### Revision History
+
+Before writing any content, add a **Revision History table** immediately after the document title. If this is a new document, create the table with version `1.0`. If updating an existing document, read the existing revision history and add a new row with an incremented version number and a summary of all changes made in this session. See the `document-revision-history` skill for full formatting rules.
+
+```markdown
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {date} | Agent ({model}) | Initial document generation |
+```
+
 ### Section 1: Scope
 - **1.1 Identification**: Identify the CSCI by name, version, and project-unique identifier (as assigned in the SSDD)
 - **1.2 System overview**: Summarize the system and this CSCI's role within it, referencing the SSDD

package/lib/bmad-workflows/mil498/sdp/instructions.md

@@ -46,6 +46,16 @@ This defines the required DID sections and content expectations for each paragra
 
 Write the document in {document_output_language}, populating each template section. **Important**: Each paragraph in Sections 4 and 5 shall identify applicable risks/uncertainties and plans for dealing with them.
 
+### Revision History
+
+Before writing any content, add a **Revision History table** immediately after the document title. If this is a new document, create the table with version `1.0`. If updating an existing document, read the existing revision history and add a new row with an incremented version number and a summary of all changes made in this session. See the `document-revision-history` skill for full formatting rules.
+
+```markdown
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {date} | Agent ({model}) | Initial document generation |
+```
+
 ### Section 1: Scope
 - **1.1 Identification**: Extract project name, version, identifiers from PRD
 - **1.2 System overview**: Summarize from Product Brief and PRD

package/lib/bmad-workflows/mil498/srs/instructions.md

@@ -56,6 +56,16 @@ This defines the required DID sections and content expectations for each paragra
 
 Write the document in {document_output_language}, populating each template section. Each requirement shall be assigned a project-unique identifier, be stated so that an objective test can be defined for it, and be annotated with qualification method(s) and traceability to system requirements.
 
+### Revision History
+
+Before writing any content, add a **Revision History table** immediately after the document title. If this is a new document, create the table with version `1.0`. If updating an existing document, read the existing revision history and add a new row with an incremented version number and a summary of all changes made in this session. See the `document-revision-history` skill for full formatting rules.
+
+```markdown
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {date} | Agent ({model}) | Initial document generation |
+```
+
 ### Section 1: Scope
 - **1.1 Identification**: Extract software name, version, CSCI identifiers from the SSDD, PRD, and Architecture
 - **1.2 System overview**: Summarize purpose, nature, development history from PRD. Identify this CSCI's role within the system

package/lib/bmad-workflows/mil498/ssdd/instructions.md

@@ -88,6 +88,16 @@ Based on {user_name}'s answers:
 
 Write the document in {document_output_language}, populating each template section.
 
+### Revision History
+
+Before writing any content, add a **Revision History table** immediately after the document title. If this is a new document, create the table with version `1.0`. If updating an existing document, read the existing revision history and add a new row with an incremented version number and a summary of all changes made in this session. See the `document-revision-history` skill for full formatting rules.
+
+```markdown
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {date} | Agent ({model}) | Initial document generation |
+```
+
 ### Section 1: Scope
 - **1.1 Identification**: Extract system name, version, and project-unique identifiers from PRD/Product Brief
 - **1.2 System overview**: Summarize system purpose, history, stakeholders, and operating sites from Product Brief and PRD

package/lib/bmad-workflows/mil498/sss/instructions.md

@@ -45,6 +45,16 @@ This defines the required DID sections and content expectations for each paragra
 
 Write the document in {document_output_language}, populating each template section. Keep requirements at the **system/subsystem level** — avoid low-level software implementation details. Each requirement shall be assigned a project-unique identifier, be stated so that an objective test can be defined for it, and be annotated with qualification method(s).
 
+### Revision History
+
+Before writing any content, add a **Revision History table** immediately after the document title. If this is a new document, create the table with version `1.0`. If updating an existing document, read the existing revision history and add a new row with an incremented version number and a summary of all changes made in this session. See the `document-revision-history` skill for full formatting rules.
+
+```markdown
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {date} | Agent ({model}) | Initial document generation |
+```
+
 ### Section 1: Scope
 - **1.1 Identification**: Extract system name, version, identifiers from PRD/Product Brief
 - **1.2 System overview**: Summarize system purpose, nature, and stakeholders

package/lib/bmad-workflows/mil498/std/instructions.md

@@ -56,6 +56,16 @@ This defines the required DID sections and content expectations for each paragra
 
 Write the document in {document_output_language}, populating each template section. **Important**: Safety precautions (marked by WARNING or CAUTION) and security/privacy considerations shall be included as applicable throughout Sections 3 and 4.
 
+### Revision History
+
+Before writing any content, add a **Revision History table** immediately after the document title. If this is a new document, create the table with version `1.0`. If updating an existing document, read the existing revision history and add a new row with an incremented version number and a summary of all changes made in this session. See the `document-revision-history` skill for full formatting rules.
+
+```markdown
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {date} | Agent ({model}) | Initial document generation |
+```
+
 ### Section 1: Scope
 - **1.1 Identification**: Extract system and software identifiers from PRD/Architecture
 - **1.2 System overview**: Summarize the system and the CSCI(s) being tested

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {

package/skills/ai-audit-trail/SKILL.md

@@ -0,0 +1,148 @@
+# AI Audit Trail
+
+Track AI agent session activity in a project-level `AiAudit.md` file. This provides accountability and visibility into AI agent work — what was done, when, and the resources consumed.
+
+## Policy
+
+### 1. Always Maintain the Audit Log
+
+At the **end of every significant agent session** (document generation, multi-step workflow, code changes), the agent MUST append an entry to `AiAudit.md` in the project root.
+
+A "significant session" is any task that:
+- Generates or substantially modifies a document
+- Executes a multi-step workflow
+- Makes changes across multiple files
+- Takes more than a trivial amount of interaction
+
+Single-question answers or trivial lookups do NOT require an audit entry.
+
+### 2. File Location
+
+The audit log is always at:
+```
+{project_root}/AiAudit.md
+```
+
+If the file does not exist, create it with the header (see format below).
+
+### 3. File Format
+
+```markdown
+# AI Audit Trail
+
+This file tracks AI agent sessions, time spent, and resources consumed.
+
+---
+
+## Session: {session_title}
+
+| Field | Value |
+|-------|-------|
+| **Date** | {YYYY-MM-DD} |
+| **Agent** | {agent_name} ({model_name}) |
+| **Task** | {brief_task_description} |
+| **Duration** | {estimated_duration} |
+| **Tokens (est.)** | Input: ~{input_tokens} / Output: ~{output_tokens} |
+| **Files Modified** | {count} files |
+| **Documents Generated** | {list_or_count} |
+| **Status** | {Completed / Partial / Failed} |
+
+### Summary
+{2-3 sentence summary of what was accomplished}
+
+### Files Touched
+- `path/to/file1.md` — {action: created/updated/deleted}
+- `path/to/file2.md` — {action}
+
+---
+```
+
+### 4. Field Definitions
+
+| Field | Description | How to Determine |
+|-------|-------------|-----------------|
+| **Date** | Session date | Current date in `YYYY-MM-DD` format |
+| **Agent** | Agent identity | The agent name and model (e.g., `Joseph (Claude Opus 4.6)`, `Claude Code (Claude Sonnet 4.6)`) |
+| **Task** | What was requested | Brief description of the user's request |
+| **Duration** | Estimated wall-clock time | Estimate from session start to end. Use ranges if uncertain (e.g., `~15-20 minutes`) |
+| **Tokens (est.)** | Estimated token consumption | Provide best estimate of input/output tokens. Use `~` prefix to indicate approximation. If unknown, write `Not available` |
+| **Files Modified** | Number of files changed | Count of files created, updated, or deleted |
+| **Documents Generated** | Documents produced | List document names or count |
+| **Status** | Outcome | `Completed` if all tasks done, `Partial` if some remain, `Failed` if blocked |
+
+### 5. Rules
+
+1. **Append only** — Never delete or modify previous session entries. The audit log is an append-only record.
+2. **One entry per session** — Do not create multiple entries for the same continuous work session. If a session spans multiple tasks, combine them into one entry.
+3. **Estimate honestly** — Token estimates are approximations. Round to the nearest thousand. If you cannot estimate, say so explicitly.
+4. **Session title** — Use a descriptive, unique title (e.g., `Generate SSDD v1.0`, `Fix SRS interface requirements`, `MIL-498 workflow audit`).
+5. **End of session** — Write the audit entry as the **last action** before presenting final results to the user.
+6. **Chronological order** — New entries go at the **bottom** of the file, maintaining chronological order.
+
+### 6. Duration Estimation
+
+Since AI agents don't have built-in timers, use these guidelines:
+- Note the time when you start the task (from system context or user message timestamps)
+- Note the time when you finish
+- If timestamps aren't available, estimate based on the complexity: quick task (~5 min), medium task (~15-30 min), large task (~1-2 hours)
+- Always prefix with `~` to indicate it's an estimate
+
+### 7. Token Estimation
+
+Provide your best estimate:
+- **Input tokens**: Roughly proportional to the amount of context you consumed (files read, conversation history)
+- **Output tokens**: Roughly proportional to the amount of text you generated (documents, code, messages)
+- If precise counts are available from the environment, use them
+- If not, estimate and note `(estimated)` next to the values
+
+## Example
+
+```markdown
+# AI Audit Trail
+
+This file tracks AI agent sessions, time spent, and resources consumed.
+
+---
+
+## Session: Generate SSDD v1.0
+
+| Field | Value |
+|-------|-------|
+| **Date** | 2026-03-01 |
+| **Agent** | Joseph (Claude Opus 4.6) |
+| **Task** | Generate MIL-STD-498 SSDD document from project artifacts |
+| **Duration** | ~25 minutes |
+| **Tokens (est.)** | Input: ~45,000 / Output: ~12,000 |
+| **Files Modified** | 1 file |
+| **Documents Generated** | SSDD.md |
+| **Status** | Completed |
+
+### Summary
+Generated the System/Subsystem Design Description from PRD, architecture, and product brief artifacts. Conducted CSCI discovery interview identifying 5 CSCIs. All 6 DID sections populated with full requirements traceability.
+
+### Files Touched
+- `_bmad-output/planning-artifacts/SSDD.md` — created
+
+---
+
+## Session: Update SRS per user feedback
+
+| Field | Value |
+|-------|-------|
+| **Date** | 2026-03-02 |
+| **Agent** | Joseph (Claude Opus 4.6) |
+| **Task** | Update SRS interface requirements based on user review feedback |
+| **Duration** | ~10 minutes |
+| **Tokens (est.)** | Input: ~20,000 / Output: ~5,000 |
+| **Files Modified** | 1 file |
+| **Documents Generated** | SRS.md (updated) |
+| **Status** | Completed |
+
+### Summary
+Updated Section 3.3 interface requirements to add 4 new external interfaces identified during user review. Updated traceability matrix in Section 5.
+
+### Files Touched
+- `_bmad-output/planning-artifacts/SRS.md` — updated
+
+---
+```

package/skills/ai-audit-trail/skill.json

@@ -0,0 +1,20 @@
+{
+    "name": "AI Audit Trail",
+    "description": "Tracks AI agent session activity, time spent, and token usage in a project-level AiAudit.md log file.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "audit",
+        "logging",
+        "time-tracking",
+        "tokens",
+        "accountability",
+        "project-management"
+    ],
+    "applies_when": [
+        "starting a new agent task or workflow",
+        "completing a document generation session",
+        "finishing any multi-step agent workflow"
+    ],
+    "always_load": true
+}

package/skills/document-revision-history/SKILL.md

@@ -0,0 +1,100 @@
+# Document Revision History
+
+Manage a revision history table at the beginning of every generated or updated document. This ensures traceability of changes across document versions.
+
+## Policy
+
+### 1. Revision History Table Required
+
+Every document generated or updated by the agent MUST include a **Revision History** table immediately after the document title (before the Table of Contents or Section 1).
+
+### 2. Table Format
+
+Use the following markdown table format:
+
+```markdown
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-03-02 | Agent (Claude) | Initial document generation |
+```
+
+### 3. Column Definitions
+
+| Column | Description |
+|--------|-------------|
+| **Version** | Document version number (e.g., 1.0, 1.1, 2.0). Use semantic versioning: major version for structural changes, minor for content updates |
+| **Date** | Date of the change in `YYYY-MM-DD` format |
+| **Author** | Who made the change — use `Agent (<model>)` for AI-generated content, or the user's name for user-directed changes |
+| **Changes** | Brief summary of ALL changes made in this version. One line per version — consolidate multiple changes into a single descriptive entry |
+
+### 4. Rules for New Documents
+
+When **generating a new document** for the first time:
+- Add the revision history table immediately after the document title
+- Set version to `1.0`
+- Set date to today's date
+- Set author to `Agent (<model>)` where `<model>` is the AI model name
+- Set changes to `Initial document generation`
+
+### 5. Rules for Updated Documents
+
+When **updating an existing document**:
+- Read the existing revision history table
+- Determine the new version number:
+  - **Minor increment** (e.g., 1.0 → 1.1): Content updates, corrections, additions to existing sections
+  - **Major increment** (e.g., 1.1 → 2.0): Structural changes, section reorganization, significant rewrites
+- Add a **single new row** summarizing ALL changes made in this update session
+- Do NOT create multiple rows for changes made in the same session — consolidate them into one line
+- Preserve all previous revision history entries
+
+### 6. Changes Column Guidelines
+
+Write concise but descriptive change summaries:
+
+**Good examples:**
+- `Added Sections 7-8 (impacts, analysis), expanded interface requirements to cover categories a-g`
+- `Updated capability requirements based on user feedback, added 3 new interfaces`
+- `Fixed traceability matrix, corrected section numbering`
+
+**Bad examples:**
+- `Updated document` (too vague)
+- `Changed section 3.2.1 requirement SRS-CAP-001 description from X to Y, then changed 3.2.2...` (too granular — summarize)
+
+### 7. Placement
+
+The revision history table MUST appear in this order within the document:
+
+```markdown
+# Document Title
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-03-02 | Agent (Claude) | Initial document generation |
+
+> MIL-STD-498 or other document metadata...
+
+## Table of Contents (if applicable)
+
+## 1. Scope
+...
+```
+
+### 8. Multi-Author Sessions
+
+If the user provides their name or the changes are user-directed corrections:
+- Use the user's name as author
+- If both the agent and user contribute in the same session, use `{user_name} / Agent (<model>)`
+
+## Example
+
+A document updated twice would have:
+
+```markdown
+# Software Requirements Specification (SRS)
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-03-01 | Agent (Claude) | Initial document generation from SSDD and PRD artifacts |
+| 1.1 | 2026-03-02 | Joseph / Agent (Claude) | Added 4 interface requirements per user feedback, corrected capability traceability to SSDD |
+| 2.0 | 2026-03-15 | Agent (Claude) | Major rewrite: restructured CSCI decomposition after SSDD v2.0, updated all requirement IDs |
+```

package/skills/document-revision-history/skill.json

@@ -0,0 +1,18 @@
+{
+    "name": "Document Revision History",
+    "description": "Manages a revision history table at the beginning of generated documents, tracking changes per version.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "documentation",
+        "revision-history",
+        "version-tracking",
+        "mil-std-498",
+        "change-management"
+    ],
+    "applies_when": [
+        "generating or updating planning documents",
+        "creating specification or design documents",
+        "modifying existing markdown documents that have a revision history table"
+    ]
+}