Support nested flow directories (domain-based organization)

[maxfindel]

Problem

All flow discovery assumes a flat directory structure — flows live directly in .flowchad/flows/*.yml with no subdirectories. As projects grow, this becomes unwieldy. Users need to organize flows by domain, feature area, or user role.

Desired structure

.flowchad/flows/
├── auth/
│   ├── sign-up-with-email.yml
│   ├── login-with-password.yml
│   └── forgot-password.yml
├── checkout/
│   ├── guest-checkout.yml
│   └── returning-customer-checkout.yml
├── onboarding/
│   └── new-user-completes-onboarding.yml
└── admin/
    └── admin-disables-user-account.yml

Folders are purely organizational — no config files needed inside them. The name field in the YAML remains the source of truth for display; the folder just provides grouping.

What needs to change

Seven skills assume flat paths. Summary of required changes:

Skill	Current pattern	Needed
flow-add	ls .flowchad/flows/*.yml	Recursive glob (**/*.yml)
flow-walk	.flowchad/flows/{name}.yml	Search by filename across subdirs
flow-update	ls .flowchad/flows/*{name}*.yml	Recursive fuzzy match
flow-report	Direct path lookup	Resolve flow file from nested path
flow-diff	Snapshot listing by name	Preserve folder context in snapshot dir name
flow-diagram	Direct path lookup	Search across subdirs
flowchad-setup	Creates files in flows/ root	Prompt user for target folder or infer from domain

Snapshot & report naming

Snapshots currently use {date}-{flow-name}/. With nesting, use {date}-{folder}--{flow-name}/ (double-dash separator) so the folder context is preserved without ambiguity.

Flow resolution strategy

When a user passes a flow name (e.g. /flow-walk sign-up-with-email):

1. Try exact match: .flowchad/flows/sign-up-with-email.yml
2. Try recursive: .flowchad/flows/**/sign-up-with-email.yml
3. If multiple matches, list them and ask the user to disambiguate
4. Support qualified names: /flow-walk auth/sign-up-with-email

Backward compatibility

• Flat flows in flows/ root still work (no migration needed)
• Existing snapshots/reports remain valid
• No new config required — folders are opt-in

Tags filter bonus

With folders as implicit tags, flow-walk --folder auth could run all flows in a folder. This is orthogonal to the existing tags field.

---

🤖 Generated with Claude Code