---
name: eck:list-project-catalog
version: "0.7.4"
description: Read-only display of a managed project's catalog with component statuses and health score.
disable-model-invocation: false
---

# List Project Catalog

Display the contents of `.claude/project-catalog.yaml` in the current project with component statuses and health scoring. **Read-only** — never modifies any files.

---

## Visual Framework

Follow these conventions for all terminal output displayed to the user via the Bash tool.

### Output Mode Awareness

Before producing output, read the user's preferred output mode:

```bash
cat $ECK_HOME/user-preferences.json 2>/dev/null
```

Extract the `outputMode` field and adapt verbosity:

- **guided** — Add explanatory prose after key steps. Describe what is happening and why.
- **standard** (default) — Balanced. Show steps with brief context for non-obvious decisions.
- **concise** — Steps and summary box only. No prose, no explanations.

If the file is missing or `outputMode` is absent, use **standard**.

### ANSI Colors

Declare these variables at the top of **every** Bash tool call (shell state does not persist between calls):

```bash
source $ECK_HOME/colors.sh
```

Every color sequence **must** end with `${RESET}`. No exceptions.

### Stage Banners

Mark major stage transitions with a bold banner. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}STAGE NAME${RESET}"
echo ""
```

### Status Symbols

| Symbol | Meaning          | Color       |
| ------ | ---------------- | ----------- |
| `[*]`  | Active / running | `${CYAN}`   |
| `[x]`  | Completed        | `${GREEN}`  |
| `[!]`  | Error            | `${RED}`    |
| `[-]`  | Skipped          | `${DIM}`    |
| `[>]`  | In progress      | `${YELLOW}` |
| `[ ]`  | Pending          | `${DIM}`    |

```bash
printf '%b\n' "${GREEN}[x]${RESET} Step completed"
printf '%b\n' "${RED}[!]${RESET} Something failed"
```

No emoji in output. Use only these bracket symbols for status.

### Summary Boxes

Display at checkpoints and at the end of the skill. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}Title${RESET}"
echo ""
printf '%b\n' "Label: Value"
echo ""
```

### Error Format

```bash
printf '%b\n' "${RED}[!]${RESET} Error message here"
printf '%b\n' "    ${DIM}Recovery guidance here.${RESET}"
```

### Spacing Rules

- One blank line before and after stage banners and summary boxes.
- No blank lines within step lists.
- Maximum output line width: 70 characters.

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Task Registration

| Stage | Subject                 | Active Form        | Statusline      |
| ----- | ----------------------- | ------------------ | --------------- |
| 1     | Stage 1: Pre-Flight     | Verifying catalog  | Preflight (1/3) |
| 2     | Stage 2: Load and Parse | Parsing catalog    | Parse (2/3)     |
| 3     | Stage 3: Display        | Displaying catalog | Display (3/3)   |

## Usage

```bash
/eck:list-project-catalog                     # Show current project catalog
```

---

## Stage 1: Pre-Flight

### Inputs

- `.claude/project-catalog.yaml` in the current directory
- `$ECK_HOME/global-catalog.yaml` (optional, for comparison)

### Activities

```bash
ls .claude/project-catalog.yaml
```

**If not found:**

```bash
printf '%b\n' "${RED}[!]${RESET} No project-catalog.yaml found in current directory"
printf '%b\n' "    ${DIM}This project doesn't appear to be managed by evolv-coder-kit.${RESET}"
echo ""
printf '%b\n' "    ${DIM}Options:${RESET}"
printf '%b\n' "    ${DIM}- Run /eck:audit-unmanaged-project to discover and register${RESET}"
printf '%b\n' "    ${DIM}- Run /eck:new-project to scaffold a new managed project${RESET}"
printf '%b\n' "    ${DIM}- Run /eck:migrate-project to onboard an existing project${RESET}"
```

### Outputs

- Confirmation that `project-catalog.yaml` exists

### Exit Criteria

- Project catalog is found, or error is displayed and skill stops

---

## Stage 2: Load & Parse

### Inputs

- `.claude/project-catalog.yaml`
- `$ECK_HOME/global-catalog.yaml` (if available)

### Activities

Read and parse:

1. `.claude/project-catalog.yaml` — project component states
2. `$ECK_HOME/global-catalog.yaml` — for comparison (if available)

### Outputs

- Parsed project catalog with component statuses
- Global catalog data for version/status comparison (if available)

### Exit Criteria

- Project catalog fully parsed and ready for display

---

## Stage 3: Display

### Inputs

- Parsed project catalog from Stage 2

### Activities

### 3.1: Header

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}Project Catalog${RESET}"
echo ""
printf '%b\n' "Project: {PROJECT_NAME}"
printf '%b\n' "Components: {TOTAL_COUNT}"
printf '%b\n' "Health: {GRADE} ({SCORE}%)"
echo ""
```

### 3.2: Component Table

```
| Name | Type | Version | Checksum | Status |
|------|------|---------|----------|--------|
| {name} | {type} | {version} | {checksum_short} | {status_icon} |
```

Status symbols:

```bash
printf '%b\n' "${GREEN}[x]${RESET} synced"
printf '%b\n' "${YELLOW}[>]${RESET} modified"
printf '%b\n' "${CYAN}[*]${RESET} outdated"
printf '%b\n' "${RED}[!]${RESET} missing"
printf '%b\n' "${DIM}[-]${RESET} custom"
```

### 3.3: Status Breakdown

```bash
echo ""
printf '%b\n' "${BOLD}Status Summary${RESET}"
printf '%b\n' "  ${GREEN}[x]${RESET} Synced:   {N}  ({pct}%)"
printf '%b\n' "  ${YELLOW}[>]${RESET} Modified: {N}  ({pct}%)"
printf '%b\n' "  ${CYAN}[*]${RESET} Outdated: {N}  ({pct}%)"
printf '%b\n' "  ${RED}[!]${RESET} Missing:  {N}  ({pct}%)"
printf '%b\n' "  ${DIM}[-]${RESET} Custom:   {N}"
echo ""
printf '%b\n' "${BOLD}Actions${RESET}"
printf '%b\n' "  ${DIM}- {N} components can be updated:${RESET} /eck:pull-from-global-catalog"
printf '%b\n' "  ${DIM}- {N} components can be harvested:${RESET} /eck:push-to-user-catalog"
printf '%b\n' "  ${DIM}- Run /eck:audit-current-project to refresh checksums${RESET}"
```

### Outputs

- Formatted project catalog display in terminal with health score and action guidance

### Exit Criteria

- All components displayed; statusline reset

---

## Error Recovery

| Error                     | Recovery                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------ |
| Project catalog not found | Project not managed — run `/eck:audit-unmanaged-project`                             |
| Global catalog not found  | Status comparison unavailable — show catalog contents only                           |
| Parse error               | Report malformed YAML and suggest running `/refresh-project-catalog` (project skill) |

---

## Related Documents

- [List Global Catalog](../list-global-catalog/SKILL.md)
- [List User Catalog](../list-user-catalog/SKILL.md)
- [Audit Current Project](../audit-current-project/SKILL.md)
- Refresh Project Catalog — `/refresh-project-catalog` (project skill, available in managed projects)
