genai instructions

Author: mwunderl

instra/README.md

@@ -0,0 +1,63 @@
+# AWS Developer Tutorials - Instructions
+
+This directory contains instructions and resources for generating new AWS CLI tutorials and scripts.
+
+## Overview
+
+The instructions in this directory guide you through the process of creating high-quality AWS CLI tutorials and scripts using Amazon Q Developer CLI. These instructions are designed to help you:
+
+1. Collect information about AWS services and use cases
+2. Generate working AWS CLI scripts
+3. Create comprehensive tutorials that explain the scripts
+4. Validate and improve both scripts and tutorials
+
+## Directory Structure
+
+- `/tutorial-gen`: Step-by-step instructions for generating tutorials and scripts
+
+## Tutorial Generation Process
+
+The tutorial generation process is divided into several steps, each with its own instruction file in the `/tutorial-gen` directory:
+
+1. **Information Collection**
+   - Collect documentation topics
+   - Gather example CLI commands
+
+2. **Script Creation**
+   - Generate an initial script
+   - Test and run the script
+   - Validate script functionality
+   - Simplify and improve the script
+
+3. **Tutorial Creation**
+   - Draft a tutorial based on the script
+   - Validate tutorial content
+
+4. **Finalization**
+   - Address feedback
+   - Make final improvements
+
+## Using These Instructions
+
+To generate a new tutorial:
+
+1. Start with the file `0-general-instructions.md` in the `/tutorial-gen` directory
+2. Follow the numbered instruction files in sequence
+3. Use Amazon Q Developer CLI to assist with each step
+4. Place the final tutorial and script in a new folder in the `/tuts` directory
+
+## Example Usage with Amazon Q Developer CLI
+
+```bash
+q "read the instructions in the ../../instra/tutorial-gen folder and follow them in order, using this topic: https://docs.aws.amazon.com/payment-cryptography/latest/userguide/getting-started.html when instructed to run the script in step 2b, it's ok to actually run the script and create resources. this is part of the process. when you generate the script, be careful to check required options and option names for each command."
+```
+
+This command instructs Amazon Q Developer CLI to:
+1. Read the tutorial generation instructions
+2. Follow them in order
+3. Use the AWS Payment Cryptography getting started guide as the source material
+4. Generate and test a script for this service
+
+## Contributing
+
+If you have suggestions for improving the tutorial generation process, please submit them as pull requests or issues in the repository.

instra/tutorial-gen/0-general-instructions.md

@@ -0,0 +1,15 @@
+# GENERAL INSTRUCTIONS
+
+these instructions take a tutorial URL as input. get the URL from the user if they didn't provide one already.
+
+you also need an identifier for this tutorial. prefix all filenames with the identifier. If the user didn't provide an identifier, use the name of the current directory.
+
+if the output files for some or all steps already exist in the current directory, use these as input. Limit modifications to existing docs to changes that improve the functionality or guidance.
+
+note the wall time when you start processing a prompt and when you return control to the user. show the actual time elapsed.
+
+## ⚠️ REQUIRED REFERENCE MATERIALS ⚠️
+When creating tutorials for specific AWS services:
+1. CRITICAL FOR VPC CREATION:
+   - Use the architecture defined in vpc-example.md as reference
+   - This step is mandatory before creating any VPC resources

instra/tutorial-gen/1a-collect-topic.md

@@ -0,0 +1,13 @@
+# Collect topic
+
+use the docs MCP server to retrieve the tutorial and store it in markdown format in the current directory. use a max length of 20000. name the file "1-input-topic.md"
+
+## formatting
+
+Don't add linebreaks in the middle of a paragraph. Keep all of the text in the paragraph on one line. Ensure that there is an empty line between all headers, paragraphs, example titles, and code blocks.
+
+For any relative path links, replace the './' with the full path that it represents.
+
+## baseline tutorial
+
+Create a CLI tutorial that does what's in this topic. This is the baseline tutorial that you create without any additional input or instructions. Call it 1-baseline.md

instra/tutorial-gen/1b-collect-examples.md

@@ -0,0 +1,16 @@
+# Collect examples
+
+read the input topic, which includes the identifier and "1-input-topic" in the filename. 
+
+get the full list of API commands for the service, and general information about the service, by running aws <service-name> help. note that the service name might not match the service name used in the input tutorial. some service APIs are bundled together. For example, EC2 has APIs for autoscaling, VPC, and elastic block store, in addition to EC2 instance APIs. reference the documentation if you can't find the right service name.
+
+## command inventory
+save a list of the commands returned by the help command to a file named 1-commands.md.
+
+## copy examples
+read the AWS CLI examples for the service API actions from the AWS CLI source repository. check the user directory for the aws-cli repo. If it is there, copy the examples folder for the service into the working directory like this: cp -r ~/aws-cli/awscli/examples/<service-name>.  
+
+## generate workflow
+determine which CLI commands can be run to accomplish each of the steps in the tutorial. use the CLI examples and API names as a reference point. if there aren't examples the correspond to a step, determine which API needs to be used and refer to its API documentation to figure out what command you need to run.
+
+create a CLI workflow document, cli-workflow.md as an example. each section in the workflow document lists API commands that correspond to a section in the input tutorial. there might not be a 1:1 relationship between actions that the user takes in the tutorial and CLI commands. figure out the intent of the tutorial step and determine which CLI commands are necessary to accomplish it. name this doc 1-cli-workflow.md.

instra/tutorial-gen/2a-create-script.md

@@ -0,0 +1,34 @@
+# create a script
+based on the cli workflow doc 1-cli-workflow.md, generate a shell script that runs all of the included CLI commands. Use the AWS CLI --query operator and --text output flag as necessary to capture resource IDs, secrets, and other information from command output. keep the script as simple as possible. don't create redundant resources or use options that are not relevant to the use case. name this script 2-cli-script.sh. make it executable. 
+
+## portability
+to keep the script portable, avoid using the region option in commands. use random names for resources that require a unique name. if the script uses S3 buckets, generate a random 12 digit hex identifier for the bucket an prepend it with the API name of the service (all lowercase). use this as the bucket name.
+
+don't use jq or other commands that are not available by default in linux systems. don't use the --cli-binary-format option as this is not available to AWS CLI v1 users. when you need to read a parameter value from a file, use the cat command in a subshell like this: $(cat config.json)
+
+## security
+apply security best practices to all API operations when possible. do not create resources that are publicly accessible. do not create security policies or network rules that have open permissions, such as resource identifiers with wildcards, or IP address ranges. use least privilege permissions at all times, or call out specifically that there is a requirement to use something less secure. note in comments when anything in the script can't be used in production environments due to security or scaling concerns.
+
+do not every hardcode passwords or keys. If you need a database password, generate a new secure password and store it in AWS Secrets Manager. Retrieve the password from secrets manager when you need to use it to access resources. don't create IAM users. Assume that the user already has AWS credentials configured in their development environment. 
+
+## cleanup
+keep track of all resources that you create and ensure that all resources that you create are also cleaned up. before deleting any resources, pause the script and show a list of all of the resources that it created, so that the user can confirm. 
+
+When prompting for user input (especially for cleanup confirmation):
+1. Use separate `echo` statements with visual formatting (like separator lines) instead of `read -p`
+2. Use a plain `read -r` command to capture input
+3. Format the prompt to be clearly visible, for example:
+```bash
+echo ""
+echo "==========================================="
+echo "CLEANUP CONFIRMATION"
+echo "==========================================="
+echo "Do you want to clean up all created resources? (y/n): "
+read -r CLEANUP_CHOICE
+```
+This ensures the prompt is properly displayed across different terminal environments.
+
+## error handling
+handle all errors within the script, and log all commands and outputs to a log file. when you capture the output of a command in a variable, check the output for errors and handle them before processing the output. use case insensitive pattern matching to get all varations of the word error. whether an error is caught or not, print the output of all commands. 
+
+if the script encounters an error, print a list of all of the resources created prior to the error, and attempt to delete them in the reverse order of when you created them. when resources depend on one another, use wait commands to confirm that the first resource is ready before creating the second one, and the second one is deleted before deleting the first one.

instra/tutorial-gen/2b-run-script.md

@@ -0,0 +1,5 @@
+# run the script
+
+run the script created in the previous step, 2-cli-script.sh. if there are errors, determine the cause of the error and update the script. verify that all resources that were created are cleaned up. each time you run the script, record the name of the log, any errors that occurred, and the final status of each resource in a test run record. Continue running and updating the script until it runs end to end without error.
+
+When you update the script, add a version number to the name, instead of coming up with a new name. For example, if you update 2-cli-script.sh, save the initial version as 2-cli-script-v1.sh and create 2-cli-script-v2.sh with the changes. Increment the version number each time you iterate on the script. When you save a log or test report, include the version of the script in the name, such as 2-cli-script-v2-log.md or 2-cli-script-v2-report.mdd

instra/tutorial-gen/2c-validate-script.md

@@ -0,0 +1,79 @@
+
+# static analysis
+
+After you've confirmed that the script is functional, perform a thorough static analysis of the provided shell script without executing it. Focus on identifying potential issues in the following categories:
+
+1. Resource Dependencies and Sequencing:
+   - Identify operations that create dependencies between resources
+   - Verify that resources are created in the correct order
+   - Check for operations that modify the same resource multiple times
+   - Flag any attempts to associate resources that might already have existing associations
+
+2. Error Handling and Resilience:
+   - Evaluate error handling mechanisms
+   - Check for proper exit strategies when commands fail
+   - Identify sections that might leave resources in an inconsistent state
+   - Verify cleanup procedures are comprehensive and properly sequenced
+
+3. Security and Best Practices:
+   - Identify overly permissive security configurations
+   - Flag hardcoded credentials or sensitive information
+   - Check for adherence to infrastructure-as-code best practices
+   - Verify proper resource tagging and naming conventions
+
+4. Resource Limitations:
+   - Identify potential service quotas or limits that might be exceeded
+   - Check for resource creation without corresponding cleanup
+   - Flag operations that might incur unexpected costs
+
+5. Logic and Control Flow:
+   - Analyze conditional logic for potential flaws
+   - Verify loop constructs for proper termination conditions
+   - Check for race conditions or timing issues
+   - Identify potential infinite loops or deadlocks
+
+6. AWS-Specific Concerns (for AWS scripts):
+   - Verify proper handling of AWS region settings
+   - Check for proper IAM permissions and least privilege principles
+   - Identify potential cross-region or cross-account issues
+   - Verify proper handling of AWS resource identifiers
+
+## Output Files and Response Format
+
+When validating a script, create the following output files:
+
+1. Validation Report File:
+   - Name: `[original-script-name]-validation-report.md`
+   - Content: Detailed analysis of issues found in the script
+   - Location: Save in the validation-tools directory
+
+2. Fixed Script File (ONLY if HIGH severity issues are found):
+   - Name: `[original-script-name]-fixed.sh`
+   - Content: Complete fixed version of the script with comments explaining changes
+   - Location: Save in the validation-tools directory
+
+3. Response to User:
+   - Provide a brief summary of the validation results
+   - Include the number and types of issues found (High/Medium/Low)
+   - Clearly state which issues will be fixed (HIGH severity) and which won't be fixed (MEDIUM and LOW severity)
+   - Mention that the detailed report and fixed script (if applicable) have been saved as files
+   - DO NOT include the entire fixed script in your response to the user
+
+The validation report should include:
+- A summary of potential issues categorized by severity (High, Medium, Low)
+- Clear distinction between issues that will be fixed in the fixed script (HIGH severity) and those that won't be fixed (MEDIUM and LOW severity)
+- Line numbers or code snippets where issues were found
+- Specific recommendations for addressing each issue
+- Suggestions for improving the overall script quality and reliability
+
+In the fixed script:
+- Add comments before each fixed section explaining what HIGH severity issue is being addressed
+- Include a header comment summarizing all HIGH severity issues that were fixed
+- Optionally include comments about MEDIUM and LOW severity issues that weren't fixed but could be improved in the future
+
+## File Organization
+
+- If validation reports and fixed scripts already exist for the script being validated, move the existing files to the `archive` directory before creating new ones
+- This ensures that the main directory contains only the most recent validation results while preserving previous work
+
+This naming convention ensures clear association between original scripts, validation reports, and fixed versions.

instra/tutorial-gen/2d-simplify-script.md

@@ -0,0 +1,5 @@
+# create a simplified script
+
+verify that the most recent version of the script is named correctly. It should be named "2-cli-script-vX.sh" with X being the iteration version, which should be the highest version of any script in the folder. If the name is something like "2-cli-script-final-fixed.sh" it is not always clear if this is the most recent version. rename the file if needed.
+
+create a simplified version of the script. don't include any error handling. just run the cli commands like a customer would when learning the API for the first time. this is not a production script and doesn't need to organize commands into functions. as long as the script runs end to end and doesn't leave any resources behind, it's good. call the script 2-simple-script.sh

instra/tutorial-gen/3a-draft-tutorial.md

@@ -0,0 +1,36 @@
+# draft a tutorial
+
+Use the example commands and output in cli-workflow.md to generate a tutorial, with a section for each group of related commands, and sections on prerequisites and next steps. Include guidance before and after every code block, even if it's just one sentence. reference the content in golden-tutorial.md as an example of a good tutorial. If content in the prerequisites section of the golden tutorial applies to this tutorial, reuse it. Name the output file 3-tutorial-draft.md.
+
+## links
+
+The tutorial may be published in the service guide, so don't include any general links to the guide or documentation landing page. In the next steps section, link to a topic in the service guide for each feature or use case listed. The prerequisites section can also have links, but avoid adding links to the core sections of the tutorial where readers are following instructions. Links in these sections can pull the reader away from the tutorial unnecessarily. 
+
+## formatting
+
+Only use two levels of headers. H1 for the topic title, and H2 for the sections. To add a title to a code block or procedure, just use bold text.
+
+Use sentence case for all headers and titles.
+Use present tense and active voice as much as possible.
+
+Don't add linebreaks in the middle of a paragraph. Keep all of the text in the paragraph on one line. Ensure that there is an empty line between all headers, paragraphs, example titles, and code blocks.
+
+For any relative path links, replace the './' with the full path that it represents.
+
+## portability
+
+Omit the --region option in example commands, unless it is required because by the specific use case or the service API. For example, if a command requires you to specify an availability zone, you need to ensure that you are calling the service in the same AWS Region as the availability zone. Otherwise, assume that the reader wants to create resources in the Region that they configured when they set up the AWS CLI, or write a script that they can run in any Region.
+
+## naming rules
+
+**account ids** - Replace 12 digit AWS account numbers with 123456789012. For examples with two account numbers, use 234567890123 for the second number. 
+
+**GUIDs** - Obfuscate GUIDs by making the second character sequence in the guid "xmpl". 
+
+**resource IDs** - For hex sequences, replace characters in the example with "abcd1234". For other numeric IDs, renumber starting with 1234. For alphanumric ID strings, replace characters 5-8 with "xmpl". 
+
+**timestamps** - Replace timestamps with a value representing January 13th of the current year. 
+
+**IP addresses** - Replace public IP addresses with fictitious addresses such as 203.0.113.75 or another address in the 203.0.113
+
+**bucket names** - For S3 buckets, the name in the tutorial must start with "amzn-s3-demo". The script can't use this name because it's reserved for documentation. Leave the script as is but replace the prefix used by the script with "amzn-s3-demo" in the tutorial.