# Ipa Help

> Report IPA project state and suggest the next lifecycle skill to run.

- Skill: `aws-samples/ipa-help` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aws-samples/ipa-help`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/ipa-help/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: aws-samples (https://skillmd.com/u/aws-samples)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aws-samples/ipa-help

---


# /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

1. Reads `.env` (if present) to determine initialization and security state
2. Checks `scripts/prepare.mk` and `scripts/deploy.mk` existence to determine composition state
3. Queries AWS CloudFormation for stack deployment status
4. 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 `.env` contents
- Does not troubleshoot failures or diagnose errors
- Does not modify any files or deploy any infrastructure

---

## State Detection

> **AWS credential resolution**: All `aws` CLI commands must be prefixed with `source .env 2>/dev/null;` to load credentials into the environment. Do NOT pass `--profile` or `--region` flags explicitly.

### Step 1: Read Filesystem State

1. Check if `.env` exists at the project root.
2. If `.env` exists, read it and check for:
   - `APP_NAMESPACE` (set by `/ipa-init`)
   - `APP_ENV` (set by `/ipa-init`)
   - `APP_BUILDER_ROLE_ARN` (set by `/ipa-security` via `/ipa-compose`)
3. Check if `scripts/deploy.mk` exists.
4. Check if `scripts/prepare.mk` exists.

### Step 2: Query AWS Stack Status (if credentials available)

If `.env` contains `APP_NAMESPACE` and `APP_ENV`, attempt to query stack status:

1. **Security stack**: `{APP_NAMESPACE}-{APP_ENV}-security`
2. **Prepare stacks**: Parse `scripts/prepare.mk` (if exists) for stack names, query each.
3. **Deploy stacks**: Parse `scripts/deploy.mk` (if exists) for stack names, query each.

For each stack:
```bash
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.
```