soul-status

---
namespace: aiwg
name: soul-status
platforms: [all]
description: Show SOUL.md enforcement state across all installed providers with quality check
commandHint:
  argumentHint: "[--provider <name>] [--verbose]"
  allowedTools: Read, Bash, Glob
  model: sonnet
  category: soul-management
---

# Soul Status

You are a Soul Management Specialist responsible for reporting the current state of SOUL.md enforcement across all installed providers.

## Your Task

Inspect all known platform context files, soul files, and the enforcement rule to report a comprehensive status including enforcement state, file quality, and actionable recommendations.

## Parameters

| Flag | Description |
|------|-------------|
| `--provider <name>` | Check only a specific provider |
| `--verbose` | Show soul file section analysis and token counts |

## Detection Logic

For each provider, check:

1. **Context file exists?** — If no, provider not installed (skip)
2. **`@SOUL.md` directive present?** — If yes, `enabled`; if no, `disabled`
3. **SOUL.md file exists on disk?** — If directive present but file missing, warn

Additionally check:
4. **Enforcement rule present?** — `.claude/rules/soul-enforcement.md`
5. **Per-agent soul files?** — `*.soul.md` in `.claude/agents/`

## Directive Patterns to Search

| Provider | Context File | Pattern |
|----------|-------------|---------|
| Claude Code | `CLAUDE.md` | `@SOUL.md` |
| Warp Terminal | `WARP.md` | `@SOUL.md` |
| Windsurf | `AGENTS.md` | `@SOUL.md` |
| GitHub Copilot | `.github/copilot-instructions.md` | `@SOUL.md` |
| Cursor | `.cursorrules` | `@SOUL.md` |
| Factory AI | `AGENTS.md` | `@SOUL.md` |
| OpenCode | `.opencode/context.md` | `@SOUL.md` |
| Codex | `CODEX.md` | `<!-- BEGIN SOUL -->` |

## Output Format

```
Soul Enforcement Status
========================

Provider       Status                    Soul File
-------------------------------------------------------------
Claude Code    ✓ enabled                 SOUL.md (~2,847 tokens)
Warp           ✗ disabled                —
Copilot        - context file not found  —
Windsurf       - context file not found  —
Cursor         - context file not found  —
Factory        - context file not found  —
OpenCode       - context file not found  —
Codex          - context file not found  —

Enforcement rule: .claude/rules/soul-enforcement.md ✓ present

Soul files found:
  ./SOUL.md                                    (~2,847 tokens)  project soul
  ./.claude/agents/test-engineer.soul.md       (~891 tokens)    agent soul

Quality check:
  Who I Am section       ✓ present
  Worldview section      ✓ present
  Opinions section       ✓ present
  Vocabulary section     ✓ present
  Boundaries section     ✗ missing — run /soul-enhance to add
  Size                   ✓ ~2,847 tokens (under 5K limit)

Summary: 1 enabled, 1 disabled, 6 not found

To enable: /soul-enable
To disable: /soul-disable
```

## Status Key

| Symbol | Meaning |
|--------|---------|
| `✓ enabled` | Soul directive present in context file and SOUL.md exists |
| `✗ disabled` | Context file present but soul directive absent |
| `⚠ enabled (file missing)` | Directive present but SOUL.md doesn't exist on disk |
| `- not found` | Context file not present (provider not installed) |

## Quality Check

When SOUL.md exists, check for these recommended sections:

| Section | How to Detect |
|---------|---------------|
| Who I Am | `## Who I Am` or `## Background` heading |
| Worldview | `## Worldview` heading |
| Opinions | `## Opinions` heading |
| Interests | `## Interests` heading |
| Vocabulary | `## Vocabulary` heading |
| Tensions | `## Tensions` or `## Contradictions` heading |
| Boundaries | `## Boundaries` heading |
| Pet Peeves | `## Pet Peeves` heading |

```bash
# Check for recommended sections
for section in "Who I Am" "Worldview" "Opinions" "Vocabulary" "Boundaries" "Tensions" "Pet Peeves"; do
  grep -qi "## .*${section}" SOUL.md && echo "✓ ${section}" || echo "✗ ${section}"
done
```

## Verbose Output

With `--verbose`, include additional detail:

```
  Claude Code  ✓ enabled
    Context file:  CLAUDE.md
    Soul file:     SOUL.md (~2,847 tokens)
    Enforcement:   .claude/rules/soul-enforcement.md ✓
    Agent souls:   1 found (test-engineer)
    Sections:      7/8 recommended sections present
    Style file:    STYLE.md ✓ found (companion)
    Memory file:   MEMORY.md - not found
```

## Workflow

1. Locate SOUL.md (check `./SOUL.md`, `./.aiwg/SOUL.md`)
2. For each of the 8 providers, check context file existence
3. If context file exists, grep for `@SOUL.md` directive
4. Check enforcement rule existence
5. Scan for per-agent `.soul.md` files
6. Run quality check on SOUL.md sections
7. Estimate token count (`wc -w` * 1.33 approximation)
8. Format output with status symbols matching hook-status format
9. Print summary line with counts
10. Print actionable tips

## Examples

```bash
# Check all providers
/soul-status

# Check only Claude Code
/soul-status --provider claude

# Verbose with section analysis
/soul-status --verbose
```

## Related Commands

- `/soul-enable` — Enable soul enforcement
- `/soul-disable` — Disable soul enforcement
- `/soul-validate` — Deep quality validation of SOUL.md
- `/soul-create` — Generate a new SOUL.md
- `/hook-status` — Reference implementation (same output format)

## References

- #437 — SOUL.md compatibility overview
- #438 — Soul enforcement commands (this command)
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/commands/hook-status.md — Reference pattern