Package workflow review standard and streamline MCP setup

README.md

@@ -1,6 +1,6 @@
 # Cisco Workflows Automation
 
-This repository contains automation workflows organized by target platform and functionality as described in the following repository structure:
+This repository contains automation workflows organized by target platform and functionality, plus a public toolkit for reviewing and improving workflow exports before submission.
 
 
 ## Repository Structure
@@ -11,15 +11,26 @@ CiscoWorkflowsAutomation/
 ├── CONTRIBUTING.md                       # Contribution guidelines and procedures
 ├── README.md                             # This file - repository overview
 ├── AI/                                   # AI-powered automation workflows and integrations
-├── Catalyst Center/                      # Cisco Catalyst Center automation workflows
-├── Cross Domain/                         # Multi-platform and cross-domain integration workflows
-├── Learning Series/                      # Educational workflows and training materials
+├── Catalyst_Center/                      # Cisco Catalyst Center automation workflows
+├── Cross_Domain/                         # Multi-platform and cross-domain integration workflows
+├── Learning_Series/                      # Educational workflows and training materials
 ├── LICENSE                               # Repository license terms
 ├── Meraki/                               # Cisco Meraki automation workflows and integrations
-├── Restful WebService/                   # RESTful API integration workflows and examples
+├── Restful_WebService/                   # RESTful API integration workflows and examples
+├── Toolkit/                              # Public review, remediation, CLI, primary MCP integration, and optional Cursor helpers
 └── SECURITY.md                           # Security policies and reporting procedures
 ```
 
+## Public Toolkit
+
+The `Toolkit/` area provides reusable helpers for the workflow review checklist in this repository. It is intended for:
+
+- VS Code and Cursor users who want a user-level MCP integration that works across workspaces
+- solution engineers or contributors using another LLM
+- external contributors who want a documented CLI and MCP-based path
+
+See `Toolkit/README.md` for the audience guide and `WorkflowReviewChecklist.md` for the canonical review contract. The recommended editor integration is the MCP path in `Toolkit/mcp/`, while the review and remediation guides live under `Toolkit/exchange-review/` and `Toolkit/exchange-remediation/`.
+
 ## Contributing
 
 We welcome contributions to expand and improve the automation workflows and supporting utilities. Please review our contribution guidelines:

Toolkit/README.md

@@ -0,0 +1,83 @@
+# Workflow Toolkit
+
+This toolkit turns the internal workflow review standard into reusable review and remediation paths for the team.
+
+`WorkflowReviewChecklist.md` at the repository root is the canonical review contract. The CLI ships a packaged fallback copy for installed environments, but everything in `Toolkit/` should reference the root checklist first so the source of truth stays in one place.
+
+## Who It Is For
+
+### VS Code and Cursor users
+
+Start with `Toolkit/mcp/` for the primary cross-workspace install path. The MCP server is the recommended integration for VS Code and Cursor because one user-level configuration can make it available in every workspace.
+
+Use `Toolkit/cursor/` only if you also want optional thin skill wrappers that call the shared CLI.
+
+### Other LLM users
+
+Use `Toolkit/exchange-review/` and `Toolkit/exchange-remediation/` as copyable playbooks, then run the CLI in `Toolkit/cli/` for deterministic enumeration and checklist resolution.
+
+### External contributors
+
+Start with:
+
+1. `WorkflowReviewChecklist.md`
+2. `Toolkit/exchange-review/README.md`
+3. `Toolkit/cli/README.md`
+
+That path does not require Cursor.
+
+## Layout
+
+```text
+Toolkit/
+├── README.md
+├── cli/            # Layer 1: shared Python CLI and core helpers
+├── mcp/            # Layer 2: primary stdio MCP integration for editors
+├── cursor/         # Layer 3: optional thin Cursor skill wrappers
+├── examples/       # Example commands and sample output
+├── exchange-remediation/ # Public remediation guidance and mode reference
+└── exchange-review/      # Public review guidance and checklist companion
+```
+
+## Layering
+
+- Layer 1: the CLI is the shared core for enumeration, checklist resolution, review preparation with remediation suggestions, and remediation planning.
+- Layer 2: the MCP server wraps the same core instead of re-implementing logic and is the recommended editor integration.
+- Layer 3: Cursor skills stay thin, optional, and delegate deterministic work to the CLI.
+
+## Quick Start
+
+### Review a workflow export with the CLI
+
+```bash
+cd Toolkit/cli
+python3 -m workflow_review inspect-workflow-export "/path/to/workflow.json"
+python3 -m workflow_review prepare-review "/path/to/workflow.json" --json
+```
+
+### Install the workflow review MCP
+
+```bash
+bash Toolkit/mcp/install_mcp.sh
+```
+
+This is the recommended setup for VS Code and Cursor because it is configured at the user level rather than tied to a single workspace.
+
+### Install the optional Cursor wrappers
+
+```bash
+bash Toolkit/cursor/install_cursor_skills.sh
+```
+
+### Run the stdio MCP scaffold
+
+```bash
+cd Toolkit/cli
+python3 -m workflow_review.mcp_server
+```
+
+For installed-client usage, see `Toolkit/mcp/README.md` for Cursor, VS Code, and generic stdio MCP examples that point at `workflow-review-mcp` directly and start with `review`; `inspect_export` is available as an advanced helper. Treat `Toolkit/cursor/` as an optional convenience layer rather than the primary install surface.
+
+## Scope
+
+This public toolkit intentionally focuses on shareable workflow review and remediation content. Internal Jira/reporting skills and local scratch exports should remain outside this repo unless they are scrubbed and clearly reusable.

Toolkit/cli/README.md

@@ -0,0 +1,89 @@
+# Workflow Review CLI
+
+This directory contains the Layer 1 core for the public toolkit.
+
+The initial CLI focuses on deterministic tasks that are useful across Cursor, other LLMs, and MCP-capable clients:
+
+- inspect a workflow export and list its parent and embedded workflows
+- validate that an export can be parsed
+- resolve the canonical checklist path
+- prepare a structured review brief
+- prepare a structured remediation plan
+
+## Install
+
+From this directory:
+
+```bash
+python3 -m pip install -e .
+```
+
+If you do not want to install the package, you can run it in-place:
+
+```bash
+PYTHONPATH=src python3 -m workflow_review inspect-workflow-export "/path/to/workflow.json"
+```
+
+## Commands
+
+### Enumerate workflows
+
+```bash
+PYTHONPATH=src python3 -m workflow_review inspect-workflow-export "/path/to/workflow.json"
+PYTHONPATH=src python3 -m workflow_review inspect-workflow-export "/path/to/workflow.json" --json
+```
+
+The legacy `enumerate` subcommand still works as an alias, but `inspect-workflow-export` is the clearer public-facing name.
+
+### Validate exports
+
+```bash
+PYTHONPATH=src python3 -m workflow_review validate "/path/to/workflow.json"
+```
+
+### Resolve the checklist
+
+```bash
+PYTHONPATH=src python3 -m workflow_review checklist
+PYTHONPATH=src python3 -m workflow_review checklist --show
+```
+
+When run from this repository, the CLI resolves `WorkflowReviewChecklist.md` at the repo root first. If the repo-root file is not available, it falls back to the packaged checklist that ships with the installed package.
+
+### Prepare a review run
+
+```bash
+PYTHONPATH=src python3 -m workflow_review prepare-review "/path/to/workflow.json" --json
+```
+
+### Prepare a remediation plan
+
+```bash
+PYTHONPATH=src python3 -m workflow_review plan-remediation "/path/to/workflow.json" \
+  --mode fix-high-only \
+  --safety ask-before-major-change \
+  --json
+```
+
+## Checklist Resolution
+
+The CLI resolves the checklist in this order:
+
+1. `--checklist /path/to/file.md`
+2. `WORKFLOW_REVIEW_CHECKLIST=/path/to/file.md`
+3. the repo-root `WorkflowReviewChecklist.md`
+4. the packaged internal review standard
+
+That keeps the repository copy canonical while still allowing the team to point at another checklist during development or use the packaged fallback when installed elsewhere.
+
+## MCP
+
+The stdio MCP scaffold is implemented in the same package and exposed through:
+
+```bash
+workflow-review-mcp
+```
+
+For the easiest MCP setup, run `bash Toolkit/mcp/install_mcp.sh` from the repo root. It installs the package and prints the exact command path to use.
+
+See `../mcp/README.md` for client configuration examples. For VS Code and Cursor, MCP is the recommended editor-facing install path; the Cursor skill wrappers are optional thin helpers on top of the same core.

Toolkit/cli/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cisco-workflow-review"
+version = "0.1.0"
+description = "Public CLI and MCP helpers for Cisco workflow review and remediation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Cisco Sample Code License" }
+authors = [
+  { name = "Cisco Workflows Automation DevNet Team" }
+]
+dependencies = []
+
+[project.scripts]
+workflow-review = "workflow_review.cli:main"
+workflow-review-mcp = "workflow_review.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/workflow_review"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"../../WorkflowReviewChecklist.md" = "src/workflow_review/data/WorkflowReviewChecklist.md"

Toolkit/cli/src/workflow_review/__init__.py

@@ -0,0 +1,5 @@
+"""Shared workflow review helpers for the public toolkit."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

Toolkit/cli/src/workflow_review/__main__.py

@@ -0,0 +1,5 @@
+from workflow_review.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

Toolkit/cli/src/workflow_review/checklist.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from importlib import resources
+
+
+CHECKLIST_ENV_VAR = "WORKFLOW_REVIEW_CHECKLIST"
+CHECKLIST_FILENAME = "WorkflowReviewChecklist.md"
+PACKAGE_CHECKLIST_RESOURCE = "data/WorkflowReviewChecklist.md"
+_PACKAGED_CHECKLIST_PATH: Path | None = None
+
+
+def _candidate_repo_roots() -> list[Path]:
+    current = Path(__file__).resolve()
+    return list(current.parents)
+
+
+def resolve_checklist_path(explicit_path: str | None = None) -> Path:
+    candidates: list[Path] = []
+
+    if explicit_path:
+        candidates.append(Path(explicit_path).expanduser().resolve())
+
+    env_value = os.getenv(CHECKLIST_ENV_VAR)
+    if env_value:
+        candidates.append(Path(env_value).expanduser().resolve())
+
+    for parent in _candidate_repo_roots():
+        candidates.append(parent / CHECKLIST_FILENAME)
+
+    for candidate in candidates:
+        if candidate.exists() and candidate.is_file():
+            return candidate
+
+    package_resource = resources.files("workflow_review").joinpath(PACKAGE_CHECKLIST_RESOURCE)
+    if package_resource.is_file():
+        return _materialize_packaged_checklist(package_resource)
+
+    searched = ", ".join(str(path) for path in candidates[:5])
+    raise FileNotFoundError(
+        f"Could not resolve {CHECKLIST_FILENAME}. Checked explicit path, "
+        f"{CHECKLIST_ENV_VAR}, and repo-relative candidates such as: {searched}"
+    )
+
+
+def read_checklist(explicit_path: str | None = None) -> tuple[Path, str]:
+    checklist_path = resolve_checklist_path(explicit_path=explicit_path)
+    return checklist_path, checklist_path.read_text(encoding="utf-8")
+
+
+def _materialize_packaged_checklist(package_resource: resources.abc.Traversable) -> Path:
+    global _PACKAGED_CHECKLIST_PATH
+    if _PACKAGED_CHECKLIST_PATH and _PACKAGED_CHECKLIST_PATH.exists():
+        return _PACKAGED_CHECKLIST_PATH
+
+    with resources.as_file(package_resource) as checklist_path:
+        source_path = Path(checklist_path)
+        with NamedTemporaryFile("w", suffix=".md", delete=False, encoding="utf-8") as handle:
+            handle.write(source_path.read_text(encoding="utf-8"))
+            _PACKAGED_CHECKLIST_PATH = Path(handle.name)
+
+    return _PACKAGED_CHECKLIST_PATH