ma-agents 2.19.2 → 2.20.0

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

@@ -0,0 +1,104 @@
+---
+name: Document Revision History
+description: Manages a revision history table at the beginning of generated documents, tracking changes per version.
+---
+# 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/.cursor/skills/git-workflow-skill/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: Git Workflow
+description: MANDATORY worktree-based workflow for ALL file-changing activities. Enforces isolated feature branches, conventional commits, and PR-based merging.
+---
+# Mandatory Usage Policy (CRITICAL)
+
+**This skill is MANDATORY for all activities that modify tracked files in this repository.**
+
+1.  **Before starting ANY work** that changes source code, config files, or documentation: You MUST run `./scripts/start-feature.sh` (or the equivalent `git worktree add`) to create an isolated feature branch and worktree.
+2.  **During development**: You MUST perform all file-writing activities inside the newly created worktree directory.
+3.  **After completing work**: You MUST run `./scripts/finish-feature.sh` (or the equivalent rebase/push/PR/cleanup sequence) to integrate your changes and clean up the worktree.
+
+**Failure to follow this workflow is a violation of repository standards.**
+
+---
+
+# Git Workflow (Worktree-Based)
+
+Multi-agent parallel development using git worktrees. Each agent gets an isolated working directory — no branch switching, no conflicts between agents.
+
+## Bundled Tools
+
+### Scripts (scripts/)
+| Script | Purpose |
+|--------|---------|
+| `start-feature.sh <type> <desc>` | Create worktree + feature branch from dev |
+| `finish-feature.sh [path]` | Rebase, push, create PR, remove worktree |
+| `validate-workflow.sh [--list]` | Check workflow compliance / list worktrees |
+| `install-hooks.sh` | Install git hooks to repo |
+
+### Git Hooks (hooks/)
+| Hook | Purpose |
+|------|---------|
+| `pre-commit` | Blocks commits on dev/main (shared across worktrees) |
+| `commit-msg` | Validates conventional commit format |
+| `prepare-commit-msg` | Adds commit message template |
+
+**Install hooks:** Run `scripts/install-hooks.sh` in target repository.
+
+### Requirements
+- Git (2.15+ for worktree support)
+- GitHub CLI (`gh`) - Required for automatic PR creation
+  ```bash
+  # macOS
+  brew install gh
+  # Windows
+  winget install --id GitHub.cli
+  # Linux
+  apt install gh
+
+  # Authenticate
+  gh auth login
+  ```
+
+---
+
+## Mandatory Pre-Change Check
+
+Before making ANY change to repository files (that are not in .gitignore):
+
+1. Check if files to be changed are tracked:
+   ```bash
+   git check-ignore -v <file-path>
+   ```
+   If file is ignored → proceed without this workflow
+   If file is tracked → continue with steps below
+
+2. Verify `dev` branch exists:
+   ```bash
+   git fetch origin
+   git branch -a | grep -E '(^|\/)dev$'
+   ```
+3. If `dev` does not exist → **STOP and ask user** to create it or specify base branch
+
+## Multi-Agent Development Flow
+
+```
+Main repo (stays on dev) ─── always clean, never modified directly
+  │
+  ├── .worktrees/auth-system/     ← Agent 1: feature/auth-system
+  │     └── (isolated copy of repo, own branch, own changes)
+  │
+  ├── .worktrees/api-refactor/    ← Agent 2: bugfix/api-refactor
+  │     └── (isolated copy of repo, own branch, own changes)
+  │
+  └── .worktrees/update-docs/     ← Agent 3: chore/update-docs
+        └── (isolated copy of repo, own branch, own changes)
+
+Each worktree:
+  1. Has its own directory and branch
+  2. Shares git history with the main repo
+  3. Can commit, push, and create PRs independently
+  4. Gets cleaned up automatically after finish-feature.sh
+```
+
+### Starting Work
+
+**Using script (recommended):**
+```bash
+./scripts/start-feature.sh feature my-feature-name
+# Output: .worktrees/my-feature-name/ created
+cd .worktrees/my-feature-name/
+```
+
+**Manual:**
+```bash
+git worktree add .worktrees/<desc> -b feature/<desc> origin/dev
+cd .worktrees/<desc>
+```
+
+### Branch Naming
+
+| Type | Use Case |
+|------|----------|
+| `feature/<desc>` | New functionality |
+| `bugfix/<desc>` | Bug fixes |
+| `hotfix/<desc>` | Urgent production fixes |
+| `chore/<desc>` | Maintenance tasks |
+
+### Completing Work
+
+**Using script (recommended):**
+```bash
+# Run from inside the worktree
+./scripts/finish-feature.sh
+```
+
+This script will:
+1. Validate you're on a feature branch
+2. Validate commit messages (conventional commits)
+3. Rebase on latest `dev` branch
+4. Push the feature branch
+5. **Automatically create a PR to `dev`** (requires `gh` CLI)
+6. **Remove the worktree** (auto-cleanup)
+
+**Note:** If `gh` CLI is not installed, the script will skip PR creation. The branch will still be pushed.
+
+**Manual:**
+```bash
+# From inside the worktree
+git fetch origin dev
+git rebase origin/dev
+git push -u origin <branch-name>
+gh pr create --base dev --head <branch-name>
+
+# Clean up from main repo
+cd /path/to/main/repo
+git worktree remove .worktrees/<desc>
+```
+
+### Managing Worktrees
+
+```bash
+# List all active worktrees
+git worktree list
+# or
+./scripts/validate-workflow.sh --list
+
+# Remove a specific worktree
+git worktree remove .worktrees/<desc>
+
+# Clean up stale references
+git worktree prune
+
+# Validate workflow compliance
+./scripts/validate-workflow.sh
+```
+
+## Commit Format (Conventional Commits)
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+```
+
+**Types:** `feat`, `fix`, `chore`, `docs`, `refactor`, `test`
+
+**Examples:**
+- `feat(auth): add OAuth2 flow support`
+- `fix(api): handle null response from endpoint`
+- `chore(deps): update Helm chart dependencies`
+- `docs(readme): add deployment instructions`
+
+## Critical Rules
+
+- **NEVER** modify tracked files without being in a worktree on a feature branch.
+- **NEVER** commit directly to `dev` or `main`.
+- **ALWAYS** check if a file is gitignored before applying this workflow.
+- **ALWAYS** create a worktree **BEFORE** calling any file-writing tools (write_to_file, replace_file_content, etc.).
+- **ALWAYS** rebase on `dev` before pushing.
+- **ALWAYS** use conventional commit format.
+- **ALWAYS** add `.worktrees/` to your `.gitignore`.
+- **ALWAYS** finish the workflow by creating a PR and removing the worktree once work is verified.

package/.cursor/skills/git-workflow-skill/hooks/commit-msg

@@ -0,0 +1,61 @@
+#!/bin/bash
+# commit-msg hook - Validate conventional commit format
+# Install: cp this file to .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+COMMIT_MSG_FILE="$1"
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+# Skip merge commits
+if echo "$COMMIT_MSG" | grep -qE '^Merge '; then
+    exit 0
+fi
+
+# Skip fixup/squash commits
+if echo "$COMMIT_MSG" | grep -qE '^(fixup|squash)! '; then
+    exit 0
+fi
+
+# Conventional commit regex
+# Format: type(scope): description
+# Types: feat, fix, chore, docs, refactor, test
+PATTERN='^(feat|fix|chore|docs|refactor|test)(\([a-zA-Z0-9_-]+\))?: .{1,}'
+
+if ! echo "$COMMIT_MSG" | head -1 | grep -qE "$PATTERN"; then
+    echo -e "${RED}=================================================${NC}"
+    echo -e "${RED}ERROR: Commit message doesn't follow conventional format${NC}"
+    echo -e "${RED}=================================================${NC}"
+    echo ""
+    echo "Your message: $(head -1 "$COMMIT_MSG_FILE")"
+    echo ""
+    echo "Expected format:"
+    echo "  <type>(<scope>): <description>"
+    echo ""
+    echo "Types:"
+    echo "  feat     - New feature"
+    echo "  fix      - Bug fix"
+    echo "  chore    - Maintenance task"
+    echo "  docs     - Documentation"
+    echo "  refactor - Code refactoring"
+    echo "  test     - Tests"
+    echo ""
+    echo "Examples:"
+    echo "  feat(auth): add OAuth2 flow support"
+    echo "  fix(api): handle null response from endpoint"
+    echo "  chore(deps): update Helm dependencies"
+    echo "  docs: update README with deployment steps"
+    echo ""
+    exit 1
+fi
+
+# Check description length (warn if too long)
+FIRST_LINE=$(head -1 "$COMMIT_MSG_FILE")
+if [[ ${#FIRST_LINE} -gt 72 ]]; then
+    echo -e "${YELLOW}WARNING: First line is ${#FIRST_LINE} characters (recommended: 72 max)${NC}"
+fi
+
+exit 0

package/.cursor/skills/git-workflow-skill/hooks/pre-commit

@@ -0,0 +1,38 @@
+#!/bin/bash
+# pre-commit hook - Block commits on protected branches
+# Works in both main repo and worktrees.
+# Install: ./scripts/install-hooks.sh
+
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Block commits on protected branches
+PROTECTED_BRANCHES="dev main master"
+
+for branch in $PROTECTED_BRANCHES; do
+    if [[ "$CURRENT_BRANCH" == "$branch" ]]; then
+        echo -e "${RED}=================================================${NC}"
+        echo -e "${RED}ERROR: Direct commits to '$branch' are not allowed${NC}"
+        echo -e "${RED}=================================================${NC}"
+        echo ""
+        echo "Create an isolated worktree for your changes:"
+        echo "  ./scripts/start-feature.sh feature <description>"
+        echo ""
+        echo "Or manually:"
+        echo "  git worktree add .worktrees/<desc> -b feature/<desc> origin/dev"
+        echo ""
+        exit 1
+    fi
+done
+
+# Warn if branch doesn't follow naming convention
+if ! echo "$CURRENT_BRANCH" | grep -qE '^(feature|bugfix|hotfix|chore)/'; then
+    echo -e "${YELLOW}WARNING: Branch '$CURRENT_BRANCH' doesn't follow naming convention${NC}"
+    echo -e "${YELLOW}Expected: feature|bugfix|hotfix|chore/<description>${NC}"
+    echo ""
+fi
+
+exit 0

package/.cursor/skills/git-workflow-skill/hooks/prepare-commit-msg

@@ -0,0 +1,56 @@
+#!/bin/bash
+# prepare-commit-msg hook - Add template for conventional commits
+# Install: cp this file to .git/hooks/prepare-commit-msg && chmod +x .git/hooks/prepare-commit-msg
+
+COMMIT_MSG_FILE="$1"
+COMMIT_SOURCE="$2"
+
+# Only add template for new commits (not amend, merge, etc.)
+if [[ -z "$COMMIT_SOURCE" ]]; then
+    # Get current branch to suggest type
+    CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+    
+    # Extract type from branch name if possible
+    SUGGESTED_TYPE=""
+    if echo "$CURRENT_BRANCH" | grep -qE '^feature/'; then
+        SUGGESTED_TYPE="feat"
+    elif echo "$CURRENT_BRANCH" | grep -qE '^bugfix/'; then
+        SUGGESTED_TYPE="fix"
+    elif echo "$CURRENT_BRANCH" | grep -qE '^hotfix/'; then
+        SUGGESTED_TYPE="fix"
+    elif echo "$CURRENT_BRANCH" | grep -qE '^chore/'; then
+        SUGGESTED_TYPE="chore"
+    fi
+
+    # Only add template if commit message is empty or just comments
+    if ! grep -qv '^#' "$COMMIT_MSG_FILE" 2>/dev/null || [[ ! -s "$COMMIT_MSG_FILE" ]]; then
+        {
+            if [[ -n "$SUGGESTED_TYPE" ]]; then
+                echo "${SUGGESTED_TYPE}(scope): "
+            else
+                echo "type(scope): "
+            fi
+            echo ""
+            echo "# Conventional Commit Format"
+            echo "# --------------------------"
+            echo "# <type>(<scope>): <description>"
+            echo "#"
+            echo "# Types:"
+            echo "#   feat     - New feature"
+            echo "#   fix      - Bug fix"
+            echo "#   chore    - Maintenance"
+            echo "#   docs     - Documentation"
+            echo "#   refactor - Code refactoring"
+            echo "#   test     - Tests"
+            echo "#"
+            echo "# Scope: Component or area (optional)"
+            echo "# Description: Short summary in present tense"
+            echo "#"
+            echo "# Examples:"
+            echo "#   feat(auth): add OAuth2 support"
+            echo "#   fix(api): handle null response"
+        } > "$COMMIT_MSG_FILE"
+    fi
+fi
+
+exit 0

package/.cursor/skills/git-workflow-skill/scripts/finish-feature.sh

@@ -0,0 +1,192 @@
+#!/bin/bash
+# finish-feature.sh - Rebase, validate, push, create PR, and clean up worktree
+# Usage: finish-feature.sh [worktree-path]
+#
+# Run from inside a worktree, or pass the worktree path as an argument.
+# After creating the PR, the worktree is removed automatically.
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+error() { echo -e "${RED}ERROR: $1${NC}" >&2; exit 1; }
+warn() { echo -e "${YELLOW}WARNING: $1${NC}" >&2; }
+success() { echo -e "${GREEN}$1${NC}"; }
+info() { echo -e "${CYAN}$1${NC}"; }
+
+# Determine working directory
+WORK_DIR="${1:-$(pwd)}"
+cd "$WORK_DIR"
+
+# Check we're in a git repo
+git rev-parse --git-dir > /dev/null 2>&1 || error "Not in a git repository"
+
+# Detect if we're in a worktree
+GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+
+IS_WORKTREE=false
+if [[ "$GIT_COMMON" != "$GIT_DIR" && "$GIT_COMMON" != "." ]]; then
+    IS_WORKTREE=true
+    MAIN_REPO=$(cd "$GIT_COMMON/.." && pwd)
+    info "Working in worktree: ${WORKTREE_PATH}"
+else
+    MAIN_REPO="$WORKTREE_PATH"
+    info "Working in main repository (not a worktree)"
+fi
+
+# Get current branch
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Validate we're on a feature branch
+if [[ "$CURRENT_BRANCH" == "dev" || "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+    error "You are on '$CURRENT_BRANCH'. Switch to a feature branch first."
+fi
+
+if ! echo "$CURRENT_BRANCH" | grep -qE '^(feature|bugfix|hotfix|chore)/'; then
+    warn "Branch '$CURRENT_BRANCH' doesn't follow naming convention (feature|bugfix|hotfix|chore)/<description>"
+    read -p "Continue anyway? (y/N) " -n 1 -r
+    echo
+    [[ $REPLY =~ ^[Yy]$ ]] || exit 1
+fi
+
+# Check for uncommitted changes
+if ! git diff-index --quiet HEAD -- 2>/dev/null; then
+    error "You have uncommitted changes. Please commit them first."
+fi
+
+# Check there are commits to push
+COMMITS_AHEAD=$(git rev-list --count origin/dev..HEAD 2>/dev/null || echo "0")
+if [[ "$COMMITS_AHEAD" == "0" ]]; then
+    error "No commits to push. Make some changes first."
+fi
+
+echo "Found $COMMITS_AHEAD commit(s) to push"
+
+# Validate commit messages
+echo ""
+echo "Validating commit messages..."
+INVALID_COMMITS=0
+while IFS= read -r commit_msg; do
+    if ! echo "$commit_msg" | grep -qE '^(feat|fix|chore|docs|refactor|test)(\([^)]+\))?: .+'; then
+        echo -e "${RED}  x Invalid: $commit_msg${NC}"
+        INVALID_COMMITS=$((INVALID_COMMITS + 1))
+    else
+        echo -e "${GREEN}  + Valid: $commit_msg${NC}"
+    fi
+done < <(git log origin/dev..HEAD --pretty=format:"%s")
+
+if [[ $INVALID_COMMITS -gt 0 ]]; then
+    warn "$INVALID_COMMITS commit(s) don't follow conventional commit format"
+    read -p "Continue anyway? (y/N) " -n 1 -r
+    echo
+    [[ $REPLY =~ ^[Yy]$ ]] || exit 1
+fi
+
+# Fetch and rebase on dev
+echo ""
+echo "Fetching latest from origin..."
+git fetch origin dev
+
+echo "Rebasing on dev..."
+if ! git rebase origin/dev; then
+    error "Rebase failed. Resolve conflicts, then run 'git rebase --continue' and try again."
+fi
+
+success "Rebased successfully on dev"
+
+# Push to remote
+echo ""
+echo "Pushing branch to origin..."
+git push -u origin "$CURRENT_BRANCH" --force-with-lease
+
+success "Branch '${CURRENT_BRANCH}' pushed to origin"
+
+# Create Pull Request using gh CLI
+echo ""
+echo "Creating Pull Request..."
+
+PR_CREATED=false
+
+if ! command -v gh &> /dev/null; then
+    warn "GitHub CLI (gh) not installed. Skipping PR creation."
+    echo "Install gh: https://cli.github.com/"
+elif ! gh auth status &> /dev/null; then
+    warn "GitHub CLI not authenticated. Run: gh auth login"
+else
+    # Generate PR title from branch name
+    PR_TITLE=$(echo "$CURRENT_BRANCH" | sed 's/^[^/]*\///' | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g')
+
+    # Get commit messages for PR body
+    FIRST_COMMIT=$(git log origin/dev..HEAD --reverse --pretty=format:"%s" | head -1)
+
+    if gh pr create --base dev --head "$CURRENT_BRANCH" --title "$PR_TITLE" --body "## Changes
+
+$FIRST_COMMIT
+
+## Commits
+$(git log origin/dev..HEAD --pretty=format:"- %s")
+
+---
+Generated with [AI Agent Skills](https://github.com/mayafit/AI_Agents)"; then
+        success "Pull Request created successfully"
+        PR_URL=$(gh pr view "$CURRENT_BRANCH" --json url -q .url 2>/dev/null || echo "")
+        if [[ -n "$PR_URL" ]]; then
+            echo ""
+            info "PR URL: ${PR_URL}"
+        fi
+        PR_CREATED=true
+    else
+        warn "Failed to create PR. You may need to create it manually."
+    fi
+fi
+
+# Clean up worktree
+if [[ "$IS_WORKTREE" == true ]]; then
+    echo ""
+    echo "Cleaning up worktree..."
+
+    # Move back to main repo before removing the worktree
+    cd "$MAIN_REPO"
+
+    # Remove the worktree
+    if git worktree remove "$WORKTREE_PATH" 2>/dev/null; then
+        success "Worktree removed: ${WORKTREE_PATH}"
+    else
+        warn "Could not auto-remove worktree. Remove manually:"
+        echo "  cd ${MAIN_REPO}"
+        echo "  git worktree remove ${WORKTREE_PATH}"
+    fi
+else
+    # Not a worktree — switch back to dev (legacy behavior)
+    echo ""
+    echo "Switching back to dev branch..."
+    git checkout dev
+    git pull origin dev
+    success "Switched back to dev branch"
+fi
+
+# Prune stale worktree references
+git worktree prune 2>/dev/null || true
+
+echo ""
+success "Done!"
+echo ""
+echo "Next steps:"
+if [[ "$PR_CREATED" == true ]]; then
+    echo "  1. Request code review on the PR"
+    echo "  2. Merge after approval"
+else
+    echo "  1. Create a Pull Request to merge '${CURRENT_BRANCH}' into 'dev'"
+    echo "  2. Request code review"
+    echo "  3. Merge after approval"
+fi
+echo "  Start new work: ./scripts/start-feature.sh <type> <description>"
+echo ""
+echo "Active worktrees:"
+git worktree list