aws-samples /ipa-help — IPA Project State Inspector
Reports the current state of an IPA project and suggests the next lifecycle skill. Does not run any skill automatically.
Lifecycle: /ipa-init → /ipa-compose → /ipa-prepare → /ipa-deploy
What This Skill Does
- Reads
.env(if present) to determine initialization and security state - Checks
scripts/prepare.mkandscripts/deploy.mkexistence to determine composition state - Queries AWS CloudFormation for stack deployment status
- Reports a one-line state summary with a suggested next skill
What This Skill Does NOT Do
- Does not run any skill automatically — it only suggests
- Does not list individual stacks or dump
.envcontents - Does not troubleshoot failures or diagnose errors
- Does not modify any files or deploy any infrastructure
State Detection
AWS credential resolution: All
awsCLI commands must be prefixed withsource .env 2>/dev/null;to load credentials into the environment. Do NOT pass--profileor--regionflags explicitly.
Step 1: Read Filesystem State
- Check if
.envexists at the project root. - If
.envexists, read it and check for:APP_NAMESPACE(set by/ipa-init)APP_ENV(set by/ipa-init)APP_BUILDER_ROLE_ARN(set by/ipa-securityvia/ipa-compose)
- Check if
scripts/deploy.mkexists. - Check if
scripts/prepare.mkexists.
Step 2: Query AWS Stack Status (if credentials available)
If .env contains APP_NAMESPACE and APP_ENV, attempt to query stack status:
- Security stack:
{APP_NAMESPACE}-{APP_ENV}-security - Prepare stacks: Parse
scripts/prepare.mk(if exists) for stack names, query each. - Deploy stacks: Parse
scripts/deploy.mk(if exists) for stack names, query each.
For each stack:
source .env 2>/dev/null; aws cloudformation describe-stacks \
--stack-name {stack-name} --query 'Stacks[0].StackStatus' --output text
If AWS calls fail (no credentials, network issues): degrade gracefully. Report filesystem state and note "AWS status unavailable."
Decision Matrix
| State | Detection | Suggestion |
|---|---|---|
| Not initialized | .env missing or APP_NAMESPACE absent |
Run /ipa-init |
| Initialized, not composed | .env present, no scripts/deploy.mk |
Run /ipa-compose <stacks> |
| Composed, security missing | scripts/deploy.mk present, APP_BUILDER_ROLE_ARN absent or security stack not *_COMPLETE |
Run /ipa-compose (triggers security phase) |
| Composed, not prepared | Prepare stacks defined in prepare.mk but not deployed |
Run /ipa-prepare |
| Prepared, not deployed | Prepare stacks *_COMPLETE, deploy stacks missing |
Run /ipa-deploy |
| Fully deployed | All stacks *_COMPLETE |
Deployment complete. Use /ipa-destroy to tear down. |
Output Format
One-line state summary, followed by a single "Next:" line naming the suggested skill
with a minimal invocation example. No stack listings, no .env dump.
Example outputs:
State: Initialized, not composed.
Next: Run `/ipa-compose frontend backend` to compose your infrastructure.
State: Composed, prepare stacks not deployed.
Next: Run `/ipa-prepare` to deploy one-time prerequisites.
State: Fully deployed (all stacks active).
Next: Deployment complete. Use `/ipa-destroy` to tear down when done.
State: Initialized, security not configured.
Next: Run `/ipa-compose` — security configuration runs on first compose.