Flexion MSP Readiness Automation

A Claude Code skill that uses AI-powered parallel generation to create comprehensive MSP compliance documentation in hours instead of weeks.

🚀 Quick Start: AI-Powered Generation

# 1. From your AWS project directory
cd /path/to/your-aws-project

# 2. Assess Prerequisites (must be met before audit)
msp-readiness prerequisites --interactive-ai

# 3. Assess Technical Requirements
msp-readiness assess --interactive-ai --skip-aws

# 4. In Claude Code conversation:
# "Launch parallel agents to generate all MSP documentation"

# 5. Result: 60+ documents (200,000 words) in 10-20 minutes

Real Results: Compliance Concierge (FIPCO) went from 30% → 93% complete in 3 hours, saving 310 hours of manual work.

👉 Quick Start Guide | Full AI Generation Guide | Prerequisites Guide

Overview

This tool combines automated project analysis with AI-powered document generation to prepare for AWS Managed Service Provider (MSP) Program requirements:

Scans your AWS infrastructure (CDK, CloudFormation, Terraform) and project files
Analyzes services, stacks, team structure, and security posture
Generates 2,000-7,500 word documents per requirement using AI
Collects evidence from AWS services (Config, CloudTrail, Security Hub, Inspector, etc.)
Creates a real-time compliance dashboard showing readiness status

What Problem Does This Solve?

Manual MSP readiness preparation takes 400-500 hours and is error-prone:

❌ Weeks spent writing documentation from scratch
❌ Manual evidence collection from multiple AWS services
❌ Generic templates that don't reflect your actual infrastructure
❌ No single view of overall readiness status
❌ Risk of missing requirements or inconsistent documentation

This tool automates 99% of the work using AI to generate project-specific, production-ready documentation:

✅ 3-5 hours instead of 400-500 hours
✅ Comprehensive documents (2,000-7,500 words each)
✅ Project-specific content (real stack names, services, procedures)
✅ Parallel generation (15-20 documents simultaneously)
✅ Zero API costs (uses Claude Code conversation)

Workspace Model

This tool uses a workspace-based approach where this repository serves as your MSP readiness workspace:

Self-Assessment Mode: Run msp-readiness assess --self to assess workspace completeness
Overwrite Protection: Generated files include frontmatter metadata to detect user modifications
Status Tracking: Documents progress through lifecycle: draft → in-progress → approved → complete
Completion Tracking: Requirements are complete when: playbook exists + evidence collected + playbook approved

Typical Workflow:

Generate missing playbooks: msp-readiness generate
Review and customize playbooks in ./playbooks/
Collect evidence from AWS: msp-readiness collect-evidence
Approve completed playbooks: msp-readiness approve <requirement-id>
Check progress: msp-readiness assess --self
View dashboard: msp-readiness dashboard --workspace

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Claude Code Skill                          │
│                     (msp-readiness)                             │
└────────────┬────────────────────────────────────────────────────┘
             │
             ├── Assessors (analyze current state)
             │   ├── Documentation Scanner
             │   ├── AWS Config Analyzer
             │   ├── IAM Policy Evaluator
             │   └── Security Hub Inspector
             │
             ├── Collectors (gather evidence)
             │   ├── CloudTrail Evidence
             │   ├── Config Rules Evidence
             │   ├── Backup Verification
             │   └── Security Findings
             │
             ├── Generators (create artifacts)
             │   ├── Playbook Generator
             │   ├── Runbook Generator
             │   ├── Evidence Matrix Builder
             │   └── Self-Assessment Filler
             │
             ├── Dashboard (visualize status)
             │   ├── Requirement Coverage Map
             │   ├── Evidence Completeness
             │   ├── Gap Analysis View
             │   └── Effort Estimates
             │
             └── Monitoring (continuous compliance)
                 ├── Scheduled Assessments
                 ├── Drift Detection
                 ├── Slack/Email Notifications
                 └── CloudWatch Metrics

Quick Start

Installation

# Clone the repository
git clone https://github.com/flexion/flexion-msp-readiness.git
cd flexion-msp-readiness

# Install dependencies
npm install

# Set up AWS credentials
export AWS_PROFILE=your-profile
export AWS_REGION=us-east-1

# Initialize configuration
cp config.example.yaml config.yaml
# Edit config.yaml with your project paths

Using as a Claude Code Skill

The tool is designed to be invoked by Claude Code when you ask about MSP readiness:

# In Claude Code, simply ask:
"Check our MSP readiness"
"What do we need for AWS MSP certification?"
"Collect evidence for our MSP audit"
"Show me the compliance dashboard"

# Claude Code will automatically:
# 1. Check if config.yaml exists (create from template if needed)
# 2. Run the appropriate msp-readiness command
# 3. Parse and summarize the results
# 4. Suggest next steps

The skill helper script makes it easy for Claude to invoke:

# Claude Code will run commands like:
~/repos/flexion-msp-readiness/bin/msp-skill assess
~/repos/flexion-msp-readiness/bin/msp-skill collect-evidence
~/repos/flexion-msp-readiness/bin/msp-skill generate
~/repos/flexion-msp-readiness/bin/msp-skill dashboard
~/repos/flexion-msp-readiness/bin/msp-skill full  # Complete workflow

Using Directly (CLI)

You can also use the tool directly from the command line:

# Link for global access
cd ~/repos/flexion-msp-readiness
npm link

# Now use from any project directory
cd /path/to/your/project
msp-readiness assess
msp-readiness collect-evidence
msp-readiness generate
msp-readiness dashboard
msp-readiness diff --baseline old.json --current new.json

# Or use the skill helper
~/repos/flexion-msp-readiness/bin/msp-skill full

Features

1. MSP Prerequisites Assessment

Assesses the 15 prerequisites that must be met BEFORE the technical audit:

Categories:

Business (3): Web presence, case studies, sales accreditations
People (1): Training and skills development
Governance (3): Supplier management, operations improvement, sustainability
Platform (1): Expert design review processes
Security (2): Access key detection, public resource prevention
Operations (5): Incident/problem management, deployment, FinOps, continuity

Command:

msp-readiness prerequisites --interactive-ai

Output:

Prerequisite completion status (15 requirements)
Gap analysis by category
AI-ready project context for document generation

See Prerequisites Guide for details.

2. Technical Requirements Assessment

Scans your project for the 46 technical validation requirements:

Existing documentation (README, CLAUDE.md, docs/)
AWS infrastructure state (via AWS SDK)
Current security controls (Security Hub, Config)
Existing playbooks and runbooks
Evidence artifacts

Outputs:

Requirement coverage matrix (46 requirements)
Gap analysis with priorities
Implementation effort estimates
Compliance percentage by category

3. Evidence Collection

Automatically collects evidence for MSP requirements:

Requirement	Evidence Source	Automation
SECP-001	AWS Health Events	CloudWatch Events subscription
SECP-002	AWS Config Rules	Config rule deployment + findings
SEC-003	AWS Config	Resource inventory snapshots
SEC-007	Inspector	Vulnerability scan results
OPS-004	CloudTrail	Log retention verification
OPS-005	AWS Backup	Backup job status + test restores

4. Playbook & Runbook Generation

Generates documentation using templates and project-specific context:

Playbooks: High-level operational procedures (Incident Response, Deployment, DR)
Runbooks: Step-by-step technical procedures
Evidence matrices: Pre-populated with collected evidence
Self-assessment: Auto-filled checklist responses

All generated content is:

Based on proven templates (from fipco-infra MSP work)
Customized with actual AWS resource details
CIS Controls v8 aligned
Ready for review (not requiring rewrite)

5. Assessment Comparison

Compare two assessment runs to track improvements and validate remediation efforts:

# Compare baseline with current assessment
msp-readiness diff \
  --baseline assessment-2026-01-01.json \
  --current assessment-2026-02-01.json

# Filter for specific changes
msp-readiness diff --only improvements
msp-readiness diff --only regressions

# CI/CD integration - exits with code 1 if compliance decreases
msp-readiness diff --baseline baseline.json --current current.json

Features:

Show compliance changes: Percentage point increase/decrease
Track improvements: Requirements that moved from gap → partial → addressed
Detect regressions: Requirements that lost compliance
Explain changes: Specific reasons for each status change (new findings, evidence, etc.)
CI/CD integration: Exit code 1 if compliance drops (blocks deployments)
Multiple formats: JSON and markdown reports

Example output:

📊 Assessment Comparison

Baseline:
  Date: 2026-01-01
  Compliance: 50%

Current:
  Date: 2026-02-01
  Compliance: 65%

📈 Compliance Change: +15%

📝 Changes Summary:
✅ Improved:   5 requirements
❌ Regressed:  0 requirements
➡️  Unchanged: 14 requirements

📈 Improvements:
📈 OPSP-001: Incident Management
  Status: gap → addressed
  Confidence: 50% → 90%
  Reason: Status changed from 'gap' to 'addressed'; Confidence increased by 40%; 2 new findings added; 1 new evidence artifact

6. Compliance Dashboard

Interactive HTML dashboard showing:

┌───────────────────────────────────────────────────────┐
│  MSP Readiness Dashboard - Project: fipco-infra       │
│  Overall Completion: 67% (20/30 requirements)         │
├───────────────────────────────────────────────────────┤
│  ✅ Addressed (8)  ⚠️  Partial (7)  ❌ Gap (4)  ⬜ N/A (11) │
├───────────────────────────────────────────────────────┤
│  By Category:                                         │
│  Security:       ████████░░ 80% (12/15)              │
│  Operations:     ██████░░░░ 60% (6/10)               │
│  Support:        ███░░░░░░░ 30% (2/5)                │
├───────────────────────────────────────────────────────┤
│  Critical Gaps (blocking MSP approval):               │
│  🔴 SECP-001: Access Key Exposure Detection           │
│  🔴 SECP-002: Public Resource Detection               │
│  🔴 OPS-006: Change Management Playbook               │
│  🔴 SEC-008: Vulnerability Remediation SLA            │
├───────────────────────────────────────────────────────┤
│  Next Actions:                                        │
│  1. Deploy Config rules (SECP-002) - 8h              │
│  2. Create Change Management playbook - 6h           │
│  3. Document vuln remediation SLA - 2h               │
├───────────────────────────────────────────────────────┤
│  Evidence Status:                                     │
│  📊 12 evidence files collected                       │

7. Automated Drift Detection & Monitoring

NEW: Continuous compliance monitoring with automated alerts:

Scheduled Assessments: Run assessments on a cron schedule (e.g., daily at 9 AM)
Drift Detection: Compare current state against baseline to detect compliance changes
Smart Notifications: Slack/email alerts when compliance drops or new gaps appear
CloudWatch Metrics: Publish compliance metrics to AWS CloudWatch for dashboards
Historical Tracking: Store assessment history to track compliance trends over time
Alert Deduplication: Prevent notification spam from repeated issues

Quick Start:

# Create baseline
msp-readiness assess
msp-readiness drift --save-baseline

# Detect drift
msp-readiness drift

# Run monitoring cycle
msp-readiness monitor

# View compliance history
msp-readiness history

# Start continuous monitoring daemon
node dist/monitoring/daemon.js config.yaml

Configuration:

monitoring:
  enabled: true
  schedule: "0 9 * * *"  # Daily at 9 AM

notifications:
  slack:
    webhook_url: "https://hooks.slack.com/..."
    alert_on:
      compliance_drop: 5  # Alert if drops by 5%
      new_gaps: true
  
  cloudwatch:
    enabled: true
    namespace: "MSP/Readiness"

See Monitoring README for full documentation │ 📝 8 playbooks/runbooks generated │ │ ⏱️ Last updated: 2026-07-27 14:23 UTC │ └───────────────────────────────────────────────────────┘


## Configuration

Edit `config.yaml` to customize:

```yaml
project:
  name: "Compliance Concierge"
  docs_path: "../fipco-infra/docs/managed-service-provider"
  cdk_path: "../fipco-infra/cdk"
  
aws:
  profile: "default"
  region: "us-east-1"
  stage: "test"
  
msp:
  version: "Feb2026-Aug2026"
  ig_level: 1  # CIS IG1
  
output:
  evidence_path: "./evidence"
  playbooks_path: "./playbooks"
  dashboard_path: "./dashboard.html"
  
assessment:
  skip_requirements: []  # Optional: skip N/A requirements
  custom_priorities: {}  # Optional: override priority levels

Troubleshooting

AWS Authentication Issues

The tool includes automatic AWS environment validation that checks for common credential problems before running any AWS operations.

Multiple Credential Sources Warning

If you see:

⚠️  AWS Environment Warnings:

  ! Multiple credential sources detected: Both AWS_PROFILE and static 
    credentials (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY) are set.

Fix: The tool will provide the exact commands needed:

unset AWS_ACCESS_KEY_ID
unset AWS_SECRET_ACCESS_KEY
unset AWS_SESSION_TOKEN
export AWS_PROFILE=your-profile-name

Profile Mismatch Error

If you see:

❌ AWS_PROFILE mismatch: Expected "AWSAdministratorAccess-688672519222" 
   but found "ClaudeCodeAccess"

Fix: Set the correct profile:

export AWS_PROFILE=AWSAdministratorAccess-688672519222
aws sso login --profile AWSAdministratorAccess-688672519222

Missing Credentials Error

If you see:

❌ No AWS credentials configured

Fix: Configure AWS SSO:

export AWS_PROFILE=your-profile-name
aws sso login

Detailed Troubleshooting

See the comprehensive troubleshooting guides:

AWS-LOGIN-GUIDE.md - How to login to the correct AWS account
AWS-PERMISSIONS-GUIDE.md - Required IAM permissions

Permission Errors

If you see AccessDeniedException errors, you're missing required AWS permissions. The tool needs read-only access to:

CloudTrail (cloudtrail:DescribeTrails)
AWS Config (config:DescribeConfigRules, config:DescribeConformancePacks)
AWS Backup (backup:ListBackupVaults, backup:ListBackupPlans)
Amazon Inspector (inspector2:ListFindings)
Security Hub (securityhub:GetFindings, securityhub:DescribeHub)
IAM (iam:GetAccountPasswordPolicy, iam:ListUsers)
CloudWatch (cloudwatch:DescribeAlarms, logs:DescribeLogGroups)
Systems Manager (ssm:DescribeInstanceInformation)

Fix: Attach the AWS SecurityAudit managed policy or see AWS-PERMISSIONS-GUIDE.md for detailed instructions.

Build Issues

If npm run build fails:

# Clean and rebuild
npm run clean
rm -rf node_modules package-lock.json
npm install
npm run build

Project Structure

flexion-msp-readiness/
├── .claude/
│   └── skills/
│       └── msp-readiness.md      # Main Claude Code skill
├── src/
│   ├── assessors/                # Assessment modules
│   │   ├── doc-scanner.ts
│   │   ├── aws-config-analyzer.ts
│   │   ├── iam-evaluator.ts
│   │   └── security-hub-checker.ts
│   ├── collectors/               # Evidence collection
│   │   ├── cloudtrail-collector.ts
│   │   ├── config-collector.ts
│   │   ├── backup-collector.ts
│   │   └── inspector-collector.ts
│   ├── generators/               # Content generation
│   │   ├── playbook-generator.ts
│   │   ├── runbook-generator.ts
│   │   ├── evidence-matrix.ts
│   │   └── self-assessment.ts
│   ├── dashboard/                # Dashboard creation
│   │   ├── builder.ts
│   │   ├── templates/
│   │   └── assets/
│   └── cli.ts                    # CLI entry point
├── templates/                    # Document templates
│   ├── playbooks/
│   ├── runbooks/
│   └── evidence/
├── docs/                         # Project documentation
│   ├── DEVELOPMENT.md
│   ├── ARCHITECTURE.md
│   └── SKILL-USAGE.md
├── examples/                     # Example outputs
│   └── fipco-infra-assessment/
├── tests/
├── package.json
├── tsconfig.json
├── config.example.yaml
└── README.md

Development Status

Phase 1: Foundation ✅ (Current)

Phase 2: Core Assessment (In Progress)

Phase 3: Evidence Collection

Phase 4: Content Generation

Phase 5: Dashboard

Data aggregator
HTML/CSS dashboard
Interactive features
Export functionality

Phase 6: Claude Skill

Contributing

See DEVELOPMENT.md for development setup, architecture decisions, and contribution guidelines.

License

MIT License - see LICENSE file for details.

Credits

Based on the MSP readiness work for Compliance Concierge (Flexion/FIPCO), specifically:

AWS MSP Program Self-Assessment Checklist (Feb 2026 - Aug 2026)
CIS Controls v8 Cloud Companion Guide
Operations & Security Playbook patterns

Documentation

For Users

README.md (this file) - Overview and usage
config.example.yaml - Configuration template

For Developers

SETUP.md - Environment setup and prerequisites ⭐ Start here
CLAUDE.md - Architecture and development guidelines
WORKFLOW.md - Git workflow and PR process
TESTING.md - Testing procedures and checklist
CONTRIBUTING.md - How to contribute, definition of done
TROUBLESHOOTING.md - Common issues and solutions
PROJECT_ROADMAP.md - Development roadmap with all issues

Quick Start for Developers

# 1. Setup environment
See SETUP.md for complete setup instructions

# 2. Pick an issue from "Ready" column
https://github.com/orgs/flexion/projects/53

# 3. Start working
./scripts/move-issue.sh <issue-number> in-progress
git checkout -b feature/issue-<number>-description

# 4. Make changes, test, commit

# 5. Create PR and move to review
git push -u origin feature/issue-<number>-description
gh pr create
./scripts/move-issue.sh <issue-number> in-review

See WORKFLOW.md for detailed workflow.

Project Status

Current Phase: Phase 1 - Critical MVP

Completed:

✅ Issue #7: fipco-infra integration with CDK parser
✅ Issue #37: Workspace model redesign with self-assessment
✅ Issue #9: Better reporting formats (markdown + JSON)

Workspace Status: 26% complete (5/19 requirements)

5 complete requirements with approved playbooks and evidence
14 in-progress requirements with draft playbooks
Run msp-readiness assess --self to see current status

Next Priorities:

Issue #39: Evidence validation (verify playbook compliance)
Issue #5: Fix build process
Issue #2: Complete playbook coverage

Project Board: https://github.com/orgs/flexion/projects/53

Name		Name	Last commit message	Last commit date
.claude/skills		.claude/skills
.github		.github
bin		bin
docs		docs
examples		examples
playbooks		playbooks
scripts		scripts
src		src
templates		templates
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
ARCHITECTURE.md		ARCHITECTURE.md
AUTO_PLAYBOOK_GENERATION.md		AUTO_PLAYBOOK_GENERATION.md
AWS-LOGIN-GUIDE.md		AWS-LOGIN-GUIDE.md
AWS-PERMISSIONS-GUIDE.md		AWS-PERMISSIONS-GUIDE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE-CODE-INTEGRATION.md		CLAUDE-CODE-INTEGRATION.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVELOPMENT.md		DEVELOPMENT.md
FIPCO_MSP_STATUS.md		FIPCO_MSP_STATUS.md
LICENSE		LICENSE
PLAYBOOK_GENERATION_SUMMARY.md		PLAYBOOK_GENERATION_SUMMARY.md
PROJECT_ROADMAP.md		PROJECT_ROADMAP.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SETUP.md		SETUP.md
SKILL-USAGE.md		SKILL-USAGE.md
SMART_AUTO_COMPLETION.md		SMART_AUTO_COMPLETION.md
TESTING.md		TESTING.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
WORKFLOW.md		WORKFLOW.md
config.example.yaml		config.example.yaml
config.fipco.yaml		config.fipco.yaml
config.self.yaml		config.self.yaml
dashboard-workspace.md		dashboard-workspace.md
jest.config.js		jest.config.js
msp-requirements-extracted.json		msp-requirements-extracted.json
msp-requirements-update-summary.md		msp-requirements-update-summary.md
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Flexion MSP Readiness Automation

🚀 Quick Start: AI-Powered Generation

Overview

What Problem Does This Solve?

Workspace Model

Architecture

Quick Start

Installation

Using as a Claude Code Skill

Using Directly (CLI)

Features

1. MSP Prerequisites Assessment

2. Technical Requirements Assessment

3. Evidence Collection

4. Playbook & Runbook Generation

5. Assessment Comparison

6. Compliance Dashboard

7. Automated Drift Detection & Monitoring

Troubleshooting

AWS Authentication Issues

Multiple Credential Sources Warning

Profile Mismatch Error

Missing Credentials Error

Detailed Troubleshooting

Permission Errors

Build Issues

Project Structure

Development Status

Phase 1: Foundation ✅ (Current)

Phase 2: Core Assessment (In Progress)

Phase 3: Evidence Collection

Phase 4: Content Generation

Phase 5: Dashboard

Phase 6: Claude Skill

Contributing

License

Credits

Documentation

For Users

For Developers

Quick Start for Developers

Project Status

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages