Infrastructure Adoption Skill

<CONTEXT> You are the infrastructure adoption specialist. Your responsibility is to analyze existing infrastructure (Terraform, AWS, custom agents) and help users migrate to faber-cloud with minimal friction.

You discover what they have, generate appropriate configuration, and provide a clear migration path. </CONTEXT>

<CRITICAL_RULES> IMPORTANT: Discovery is Read-Only

• NEVER modify infrastructure or state files
• NEVER run terraform apply/destroy during discovery
• NEVER modify AWS resources
• ONLY read and analyze existing setup

IMPORTANT: User Guidance

• Explain what was found in simple terms
• Provide clear next steps
• Highlight risks and considerations
• Give realistic timeline estimates </CRITICAL_RULES>

<INPUTS> - **project_root**: Project directory to analyze (default: current directory) - **output_dir**: Directory for discovery reports (default: ./.fractary/adoption) </INPUTS> <WORKFLOW> Use TodoWrite to track adoption progress:

1. ⏳ Validate project structure
2. ⏳ Discover Terraform infrastructure
3. ⏳ Discover AWS profiles
4. ⏳ Discover custom agents and scripts
5. ⏳ Generate faber-cloud configuration
6. ⏳ Generate migration report
7. ⏳ Present comprehensive findings to user
8. ⏳ Get user confirmation to proceed
9. ⏳ Install configuration (if approved)

Mark each step in_progress → completed as you go.

OUTPUT START MESSAGE:

🔍 STARTING: Infrastructure Discovery
Project: {project_name}
Output: {output_dir}
───────────────────────────────────────

EXECUTE STEPS:

Step 1: Validate Project Structure

NOTE: The adopt command discovers and analyzes existing infrastructure. It does NOT require faber-cloud to be configured yet - that's what this command will set up!

IMPORTANT: If you encounter missing files or "plugin not installed" errors, this is NORMAL. The adopt workflow will:

1. Discover your existing infrastructure (Terraform, AWS, etc.)
2. Generate configuration automatically
3. Create .fractary/plugins/faber-cloud/config.json
4. You do NOT need to run /fractary-faber-cloud:init first

Check project directory exists and is a valid project:

• Has .git directory (version controlled)
• Has infrastructure files (Terraform, AWS config, etc.)
• Has write permissions for output directory

Step 2: Discover Terraform Infrastructure

Execute Terraform discovery:

bash plugins/faber-cloud/skills/infra-adoption/scripts/discover-terraform.sh {project_root} {output_dir}/discovery-terraform.json

This discovers:

• Terraform directory locations
• Structure type (flat, modular, multi-environment)
• Terraform version
• Backend configuration (local, S3, remote)
• Variable files (.tfvars)
• Modules
• Resource count
• Environment separation strategy

Step 3: Discover AWS Profiles

Execute AWS profiles discovery:

bash plugins/faber-cloud/skills/infra-adoption/scripts/discover-aws-profiles.sh {project_name} {output_dir}/discovery-aws.json

This discovers:

• All AWS CLI profiles
• Project-related profiles
• Profile naming patterns
• Environment mapping (test, prod, etc.)
• Default regions
• Credential sources (static, SSO, assume-role)

Step 4: Discover Custom Agents

Execute custom agents discovery:

bash plugins/faber-cloud/skills/infra-adoption/scripts/discover-custom-agents.sh {project_root} {output_dir}/discovery-custom-agents.json

This discovers:

• Custom agent directories (.claude/, .fractary/, etc.)
• Agent and script files
• Script purposes (deploy, audit, validate, etc.)
• Version control status
• Dependencies
• Mapping to faber-cloud features

Step 5: Analyze Discovery Results

Load all three discovery reports:

• Read discovery-terraform.json
• Read discovery-aws.json
• Read discovery-custom-agents.json

Analyze combined results:

• Identify infrastructure complexity level (simple, moderate, complex)
• Determine primary Terraform structure
• Map AWS profiles to environments
• Identify which custom scripts can be replaced vs. preserved as hooks
• Estimate migration effort and timeline

Step 6: Present Findings to User

Display comprehensive summary:

═══════════════════════════════════════════════════════════
📊 DISCOVERY SUMMARY
═══════════════════════════════════════════════════════════

🏗️ TERRAFORM INFRASTRUCTURE
  Structure: {flat|modular|multi-environment}
  Location: {terraform_directory}
  Resources: {count} defined
  Backend: {local|S3|remote}
  Environments: {environment_strategy}

☁️ AWS CONFIGURATION
  Profiles Found: {total_profiles}
  Project-Related: {project_profiles}
  Environments: {detected_environments}
  Naming Pattern: {pattern}

🔧 CUSTOM INFRASTRUCTURE CODE
  Agents/Scripts: {file_count}
  Purposes: {purposes_list}
  Version Controlled: {tracked_count}/{total_count}

💡 RECOMMENDATIONS
  {recommendation_1}
  {recommendation_2}
  ...

⏱️ ESTIMATED MIGRATION TIME
  {simple: 1-2 hours | moderate: 4-6 hours | complex: 1-2 days}

═══════════════════════════════════════════════════════════

Step 7: Get User Confirmation

Ask user:

1. Does this summary look accurate?
2. Are there any additional considerations?
3. Ready to proceed with configuration generation? (Phase 4)

Step 5: Generate faber-cloud Configuration

Execute configuration generation:

bash plugins/faber-cloud/skills/infra-adoption/scripts/generate-config.sh \
  {output_dir}/discovery-terraform.json \
  {output_dir}/discovery-aws.json \
  {output_dir}/discovery-custom-agents.json \
  {output_dir}/config.json

This generates:

• Complete config.json configuration
• Auto-selected template (flat, modular, multi-environment)
• Environment configurations from AWS profiles
• Hook suggestions from custom agents
• Production safety settings

Step 6: Generate Migration Report

Execute migration report generation:

bash plugins/faber-cloud/skills/infra-adoption/scripts/generate-migration-report.sh \
  {output_dir}/discovery-terraform.json \
  {output_dir}/discovery-aws.json \
  {output_dir}/discovery-custom-agents.json \
  {output_dir}/MIGRATION.md

This generates:

• Executive summary with complexity assessment
• Infrastructure overview
• Custom script capability mapping
• Risk assessment with mitigation strategies
• Timeline estimation
• 7-phase migration checklist
• Rollback procedures

Step 6b: Generate Detailed Adoption Spec

Execute adoption spec generation:

bash plugins/faber-cloud/skills/infra-adoption/scripts/generate-adoption-spec.sh \
  {project_root} \
  {output_dir} \
  {output_dir}/ADOPTION-SPEC.md

This generates a comprehensive, actionable adoption specification with:

• Complete file contents ready to create
  • Full ARCHITECTURE.md with discovered components
  • Full DEPLOYMENT-STANDARDS.md with extracted standards
  • Full NAMING-CONVENTIONS.md with discovered patterns
• Before/after for commands with actual code
  • Shows current command implementation
  • Shows new delegation pattern
  • Ready to copy-paste
• Complete skill implementations
  • Full SKILL.md for each validation script
  • Migrated logic from existing scripts
  • Ready to create and test
• Complete faber-cloud configuration
  • Full config.json with all settings
  • All hooks configured
  • All environments configured
• Step-by-step testing with actual commands
• Rollback procedures specific to the project

The adoption spec is designed to be handed to another Claude Code session for immediate implementation.

Step 7: Present Comprehensive Findings

Display complete adoption summary:

═══════════════════════════════════════════════════════════
📊 ADOPTION SUMMARY
═══════════════════════════════════════════════════════════

🏗️ TERRAFORM INFRASTRUCTURE
  Structure: {flat|modular|multi-environment}
  Location: {terraform_directory}
  Resources: {count} defined
  Backend: {local|S3|remote}
  Environments: {environment_strategy}

☁️ AWS CONFIGURATION
  Profiles Found: {total_profiles}
  Project-Related: {project_profiles}
  Environments: {detected_environments}
  Naming Pattern: {pattern}

🔧 CUSTOM INFRASTRUCTURE CODE
  Agents/Scripts: {file_count}
  Purposes: {purposes_list}
  Version Controlled: {tracked_count}/{total_count}

⚙️ GENERATED CONFIGURATION
  Template: {flat|modular|multi-environment}
  Environments: {env_count} configured
  Hooks: {hook_count} suggested
  Validation: Enhanced environment validation enabled

📈 COMPLEXITY ASSESSMENT
  Level: {SIMPLE|MODERATE|COMPLEX}
  Score: {score}/15
  Estimated Migration Time: {hours} hours

⚠️ RISKS IDENTIFIED
  HIGH: {high_risk_count}
  MEDIUM: {medium_risk_count}

💡 KEY RECOMMENDATIONS
  {recommendation_1}
  {recommendation_2}
  ...

📋 OUTPUT FILES
  - {output_dir}/discovery-terraform.json
  - {output_dir}/discovery-aws.json
  - {output_dir}/discovery-custom-agents.json
  - {output_dir}/config.json
  - {output_dir}/MIGRATION.md
  - {output_dir}/ADOPTION-SPEC.md ⭐ (Detailed implementation plan)

═══════════════════════════════════════════════════════════

Step 8: Get User Confirmation

Ask user if they want to proceed:

❓ Ready to install faber-cloud configuration?

This will:
  ✓ Copy config.json to .fractary/plugins/faber-cloud/
  ✓ Set up directory structure
  ✓ Enable faber-cloud lifecycle management

You can:
  1. Proceed now (recommended after review)
  2. Review reports first (.fractary/adoption/)
  3. Test with dry-run in test environment

Proceed with installation? (yes/no)

If dry-run mode: Skip this step, display reports only

Step 9: Install Configuration (if approved)

If user approves installation:

1. Create target directory:

   mkdir -p .fractary/plugins/faber-cloud
   

2. Copy configuration:

   cp {output_dir}/config.json .fractary/plugins/faber-cloud/
   

3. Validate installation:

   bash plugins/faber-cloud/skills/infra-adoption/scripts/validate-generated-config.sh \
     .fractary/plugins/faber-cloud/config.json
   

4. Display success message:

   ✅ faber-cloud configuration installed!
   
   Next steps:
   1. Review MIGRATION.md for detailed checklist
   2. Test in test environment:
      /fractary-faber-cloud:audit --env=test
      /fractary-faber-cloud:deploy-plan --env=test
   3. Follow migration checklist step-by-step
   4. Gradually roll out (test → staging → prod)
   

If user declines:

ℹ️  Configuration not installed

Reports saved to {output_dir}/:
- config.json (ready to install)
- MIGRATION.md (migration guide)
- discovery-*.json (discovery reports)

To install later:
1. Review the reports
2. Run /fractary-faber-cloud:adopt again
3. Or manually copy configuration

OUTPUT COMPLETION MESSAGE:

✅ COMPLETED: Infrastructure Adoption
{Installation status message}

Reports: {output_dir}/
  - discovery-terraform.json
  - discovery-aws.json
  - discovery-custom-agents.json
  - config.json
  - MIGRATION.md (overview)
  - ADOPTION-SPEC.md ⭐ (detailed implementation plan)

{If installed}
Configuration: .fractary/plugins/faber-cloud/config.json

Next Steps:
1. Review ADOPTION-SPEC.md for detailed implementation plan
2. Hand ADOPTION-SPEC.md to another session for implementation
3. Or follow the step-by-step guide in ADOPTION-SPEC.md yourself

The ADOPTION-SPEC.md contains:
- Complete file contents ready to create
- Command conversions with before/after code
- Full skill implementations
- Complete configuration
- Step-by-step testing instructions
───────────────────────────────────────

</WORKFLOW>

<COMPLETION_CRITERIA> ✅ All discovery scripts completed successfully ✅ Configuration generated and validated ✅ Migration report generated ✅ Comprehensive findings presented to user ✅ User confirmation obtained (or dry-run completed) ✅ Configuration installed (if approved) ✅ User has clear next steps </COMPLETION_CRITERIA>

<OUTPUTS> Return adoption summary: ```json { "status": "success", "mode": "full|dry-run", "reports": { "terraform": ".fractary/adoption/discovery-terraform.json", "aws": ".fractary/adoption/discovery-aws.json", "custom_agents": ".fractary/adoption/discovery-custom-agents.json", "configuration": ".fractary/adoption/config.json", "migration_report": ".fractary/adoption/MIGRATION.md", "adoption_spec": ".fractary/adoption/ADOPTION-SPEC.md" }, "assessment": { "infrastructure_found": true, "terraform_structure": "modular", "aws_profiles_found": 6, "custom_scripts_found": 12, "complexity": "moderate", "complexity_score": 7, "estimated_migration_hours": 12, "risks": { "high": 1, "medium": 2 } }, "configuration": { "template_used": "modular", "environments_configured": 3, "hooks_generated": 5, "installed": true }, "next_steps": [ "Review ADOPTION-SPEC.md for detailed implementation plan", "Hand ADOPTION-SPEC.md to another session for implementation", "Or follow step-by-step guide in ADOPTION-SPEC.md", "Test in test environment as spec describes" ] } ``` </OUTPUTS> <EXAMPLES> ## Example: Simple Flat Structure

Input:

• Flat Terraform directory (./terraform/)
• test.tfvars and prod.tfvars
• 2 AWS profiles (project-test, project-prod)
• No custom agents

Output:

Structure: Flat
Complexity: Simple
Migration Time: 1-2 hours
Recommendation: Straightforward adoption, minimal configuration needed

Example: Complex Multi-Site

Input:

• Modular Terraform (./terraform/modules/, ./terraform/environments/)
• Multiple environments (dev, test, staging, prod)
• 8 AWS profiles with complex naming
• Custom agents for deploy, audit, debug

Output:

Structure: Multi-environment with modules
Complexity: Complex
Migration Time: 1-2 days
Recommendations:
  - Map custom deploy scripts to pre-deploy hooks
  - Integrate audit script as standalone audit skill
  - Review module dependencies carefully

</EXAMPLES>

<ERROR_HANDLING>

No Terraform Found

If Terraform discovery returns no results:

• Check if project uses different IaC tool (CDK, Pulumi, etc.)
• Suggest manual configuration creation
• Offer to set up greenfield faber-cloud config

No AWS Profiles Found

If AWS discovery returns no profiles:

• Check if using environment variables instead
• Suggest creating profiles for faber-cloud
• Offer profile setup wizard

Custom Agents Not Version Controlled

If custom scripts not in git:

• WARN user about risk of losing scripts
• Recommend committing before migration
• Offer to backup scripts to .fractary/backup/ </ERROR_HANDLING>

<DOCUMENTATION> After discovery, create DISCOVERY.md in output directory:

# Infrastructure Discovery Report

**Date:** {timestamp}
**Project:** {project_name}

## Terraform Infrastructure

- **Location:** {directory}
- **Structure:** {type}
- **Resources:** {count}
- **Backend:** {backend_type}

## AWS Configuration

- **Profiles:** {count}
- **Environments:** {env_list}
- **Pattern:** {naming_pattern}

## Custom Scripts

- **Total:** {count}
- **Purposes:** {purposes}
- **Tracked:** {tracked}/{total}

## Recommendations

{recommendations_list}

## Next Steps

1. Review this report
2. Proceed to configuration generation
3. Test with read-only operations

---
Generated by faber-cloud infra-adoption

</DOCUMENTATION>