feat: agentic-coding transpiler — single-source-of-truth across 15 AI agent platforms

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,77 @@
+name: Bug Report
+description: Report a bug in ASH
+labels: ["bug"]
+body:
+  - type: dropdown
+    id: version
+    attributes:
+      label: ASH Version
+      description: Which version of ASH are you using?
+      options:
+        - v3.4.x
+        - v3.3.x
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Linux
+        - macOS
+        - Windows
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation Method
+      options:
+        - uvx
+        - pip
+        - pipx
+        - container
+        - homebrew
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal steps to reproduce the behavior.
+      placeholder: |
+        1. Run `ash ...`
+        2. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened.
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Log Output
+      description: Paste any relevant log output here.
+      render: shell

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature Request
+description: Suggest a new feature
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Description
+      description: What problem does this solve?
+      placeholder: I'm frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like this to work?
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Other approaches you've thought about.
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other information that helps explain the request.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+<!-- Brief description of what this PR does -->
+
+## Related Issues
+<!-- Link to related issues: Closes #123 -->
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] CI/build change
+- [ ] Refactoring (no functional change)
+
+## Checklist
+- [ ] Tests added/updated for the change
+- [ ] Documentation updated (if applicable)
+- [ ] `uv run pytest tests/unit/` passes locally
+- [ ] Commit messages follow conventional format

.github/workflows/ash-unified-ci.yml

@@ -41,6 +41,8 @@ jobs:
             echo "::error::JSON schemas are out of date. Run 'python -m automated_security_helper.schemas.generate_schemas' and commit the result."
             exit 1
           fi
+      - name: Verify documentation freshness
+        run: uv run python scripts/verify_docs_freshness.py
 
   unit-test:
     name: "unit-test (${{ matrix.os }}, py${{ matrix.python-version }})"

README.md

@@ -121,7 +121,7 @@ brew install ash
 
 ```bash
 # Install with pipx (isolated environment)
-pipx install git+https://github.com/awslabs/automated-security-helper.git@v3.0,1
+pipx install git+https://github.com/awslabs/automated-security-helper.git@v3.4.1
 
 # Use as normal
 ash --help
@@ -225,7 +225,7 @@ The ASH MCP server provides:
     "ash": {
       "command": "uvx",
       "args": [
-        "--from=git+https://github.com/awslabs/automated-security-helper@v3.0.0",
+        "--from=git+https://github.com/awslabs/automated-security-helper@v3.4.1",
         "ash",
         "mcp"
       ],
@@ -243,7 +243,7 @@ The ASH MCP server provides:
     "ash-security": {
       "command": "uvx",
       "args": [
-        "--from=git+https://github.com/awslabs/automated-security-helper@v3.0.0",
+        "--from=git+https://github.com/awslabs/automated-security-helper@v3.4.1",
         "ash",
         "mcp"
       ]
@@ -259,7 +259,7 @@ The ASH MCP server provides:
     "ash": {
       "command": "uvx",
       "args": [
-        "--from=git+https://github.com/awslabs/automated-security-helper@v3.0.0",
+        "--from=git+https://github.com/awslabs/automated-security-helper@v3.4.1",
         "ash",
         "mcp"
       ],
@@ -321,7 +321,7 @@ based on the instructions provided in the prompt.
 
 The MCP server supports all ASH configuration methods:
 
-- **Configuration files**: `.ash/ash.yaml` or custom config paths
+- **Configuration files**: `.ash/.ash.yaml` or custom config paths
 - **Environment variables**: `ASH_DEFAULT_SEVERITY_LEVEL`, `ASH_OFFLINE`, etc.
 - **CLI parameters**: Severity thresholds, custom output directories
 
@@ -330,7 +330,7 @@ For detailed information about streaming capabilities and advanced usage, see th
 
 ## Configuration
 
-ASH v3 uses a YAML configuration file (`.ash/ash.yaml`) with support for JSON Schema validation:
+ASH v3 uses a YAML configuration file (`.ash/.ash.yaml`) with support for JSON Schema validation:
 
 ```yaml
 # yaml-language-server: $schema=https://raw.githubusercontent.com/awslabs/automated-security-helper/refs/heads/main/automated_security_helper/schemas/AshConfig.json
@@ -359,7 +359,7 @@ Add this to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/awslabs/automated-security-helper
-    rev: v3.0.0
+    rev: v3.4.1
     hooks:
       - id: ash-simple-scan
 ```
@@ -382,7 +382,7 @@ ASH v3 produces several output files in the `.ash/ash_output/` directory:
 - `reports/ash.html`: Interactive HTML report
 - `reports/ash.csv`: CSV report for filtering and sorting findings
 
-ASH also supports CycloneDX, SPDX, OCSF, GitLab SAST, JUnit XML, and YAML output. Enable any combination of reporters in your `.ash/ash.yaml` configuration. For the complete schema reference, consumption examples, and format details, see [Output Formats](https://awslabs.github.io/automated-security-helper/docs/output-formats/).
+ASH also supports CycloneDX, SPDX, OCSF, GitLab SAST, JUnit XML, and YAML output. Enable any combination of reporters in your `.ash/.ash.yaml` configuration. For the complete schema reference, consumption examples, and format details, see [Output Formats](https://awslabs.github.io/automated-security-helper/docs/output-formats/).
 
 The `ash_aggregated_results.json` file includes comprehensive validation information that tracks scanner registration, enablement, execution, and result inclusion throughout the scan process. The Scanner Validation System can also generate detailed validation reports that provide comprehensive analysis of scanner states, validation checkpoints, dependency issues, and actionable recommendations for troubleshooting scan issues.
 
@@ -403,7 +403,7 @@ ASH can be run in container mode in any CI/CD environment that supports containe
 <details>
 <summary>How do I exclude files from scanning?</summary>
 
-ASH respects `.gitignore` files. You can also configure ignore paths in your `.ash/ash.yaml` configuration file.
+ASH respects `.gitignore` files. You can also configure ignore paths in your `.ash/.ash.yaml` configuration file.
 </details>
 
 <details>

SECURITY.md

@@ -0,0 +1,51 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 3.x     | Yes                |
+| 2.x     | No (end of life)   |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this project, please report it responsibly.
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Instead, use one of the following channels:
+
+- Email: aws-security@amazon.com
+- GitHub Security Advisories: use the "Report a vulnerability" button on the [Security tab](../../security/advisories/new)
+
+### What to include
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof of concept
+- The affected version(s)
+- Any suggested fix, if you have one
+
+### Response timeline
+
+- **Acknowledgment**: within 48 hours of receipt
+- **Fix timeline**: depends on severity. Critical issues are prioritized for the next patch release; lower-severity issues are scheduled into the regular release cycle.
+
+## Scope
+
+### In scope
+
+- Vulnerabilities in ASH source code (Python, shell scripts)
+- Dependency vulnerabilities that affect ASH at runtime
+- CI/CD injection or supply-chain risks in the build pipeline
+- Authentication or authorization flaws in MCP server endpoints
+
+### Out of scope
+
+- False positives produced by scanners that ASH orchestrates (e.g., Semgrep, Bandit, cfn-lint)
+- Bugs in third-party tools that ASH invokes but does not maintain
+- Reports that require physical access to the machine running ASH
+- Social engineering attacks against maintainers
+
+## Preferred Languages
+
+We accept vulnerability reports in English.

ash-agent-plugins/.github/workflows/validate.yml

@@ -0,0 +1,65 @@
+name: Validate plugin packages
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # Drift + structural validation runs once on the full output tree.
+  # Cheap, deterministic, catches the byte-identical-output regressions.
+  drift-and-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Run drift + structural validation
+        run: uv run --project agentic-coding/transpiler agentic-plugins check
+      - name: Run pytest regression suite
+        run: uv run --project agentic-coding/transpiler --extra test pytest agentic-coding/transpiler/tests/
+
+  # Generate the (backend, validator-CLI) matrix from the transpiler so
+  # adding a new backend or CLI declaration auto-expands the CI surface.
+  matrix-config:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.generate.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - id: generate
+        name: Generate matrix from `agentic-plugins matrix --validators-only`
+        run: |
+          MATRIX=$(uv run --project agentic-coding/transpiler agentic-plugins matrix --validators-only | jq -c .)
+          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
+
+  # One job per (backend, validator-CLI) pair. Each cell installs only
+  # the CLI it needs at the pinned version (matching cli_versions.json),
+  # then runs `agentic-plugins smoke-test <backend>`. Fail-fast disabled
+  # so a single broken pair doesn't mask other regressions.
+  smoke-test:
+    needs: [drift-and-validate, matrix-config]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.matrix-config.outputs.matrix) }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install ${{ matrix.cli }} (pinned)
+        if: matrix.install_cmd != '' && matrix.headless
+        run: ${{ matrix.install_cmd }}
+
+      - name: Smoke-test ${{ matrix.backend }} (validator=${{ matrix.cli }})
+        run: uv run --project agentic-coding/transpiler agentic-plugins smoke-test ${{ matrix.backend }}

ash-agent-plugins/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+__pycache__/
+*.pyc
+*.pyo
+*.swp
+*.swo
+.vscode/
+.idea/
+*.log
+.ash/ash_output/
+node_modules/
+# uv-managed virtualenv inside transpiler/
+transpiler/.venv/

ash-agent-plugins/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+# pre-commit hooks for the agentic-coding-plugins repo.
+#
+# Two hooks driven by `uv run`:
+#   1. transpile-base — regenerates AGENTS.md + claude/, codex/, kiro/, ...
+#                       whenever transpiler/_base/ or transpiler/ changes.
+#   2. verify-no-drift — fails the commit if any platform output differs from
+#                        what the transpiler would produce. Catches hand-edits.
+#
+# uv handles its own .venv inside transpiler/ — pre-commit doesn't manage it.
+# First run is slow (creates .venv, installs jinja2); subsequent runs are ~50ms.
+#
+# Install hooks once:  pre-commit install
+# Run on demand:       pre-commit run --all-files
+
+repos:
+  - repo: local
+    hooks:
+      - id: agentic-plugins-build
+        name: Build all platform plugins from _base/ + backend class vars
+        entry: uv run --project agentic-coding/transpiler agentic-plugins build
+        language: system
+        files: '^agentic-coding/transpiler/'
+        pass_filenames: false
+
+      - id: agentic-plugins-check
+        name: Verify drift + validation across all backends
+        entry: uv run --project agentic-coding/transpiler agentic-plugins check
+        language: system
+        files: '^agentic-coding/'
+        pass_filenames: false