---
name: fluent-workspace-tree
description: Read-only visualization of the workspace directory structure with annotations, artifact counts, and feature status overlays.
user-invocable: true
allowed-tools: Bash, Read, Glob, Grep
argument-hint: [--profile PROFILE] [--section source|workflows|features|reports|analysis|tasks|sessions] [--depth N]
cursor-tier: auto
---

# Workspace Tree Visualization

Render an annotated directory tree of the workspace showing where everything lives, what each directory contains, and how many artifacts exist in each category. This is a **read-only** skill -- it writes no files and makes no mutations.

## Ownership Boundary

This skill owns: workspace directory structure visualization, artifact counting, file-level annotations, section filtering, depth control.

Other skills own: feature lifecycle details (`/fluent-feature-status`), session changes (`/fluent-session`), source code analysis (`/fluent-custom-code`), workflow structure analysis (`/fluent-workflow-analyzer`).

**Delineation with `/fluent-feature-status --tree`:** This skill provides a structure-focused view with file-level annotations, section filtering, and depth control. `/fluent-feature-status --tree` provides a lifecycle-focused view with status priority sorting, attention flags, and next-action recommendations. Use this skill for "where is everything?"; use feature-status for "what should I work on next?"

## Purpose

Provide a visual map of the entire workspace organized by the three-axis layout (Feature, Module, Account). Help users understand where artifacts live, find specific files, and grasp the workspace structure at a glance.

## When to Use

- **Onboarding:** First time working with a workspace -- understand the layout before diving in.
- **Finding artifacts:** "Where are the workflows?" "Where did that build report go?"
- **Understanding workspace layout:** See the relationship between source code, workflows, features, and reports.
- **Session start:** Quick orientation alongside `/fluent-feature-status` for a complete picture.
- **After scaffolding:** Verify that new directories and files were created in the right places.

## No Planning Gate

This is a **read-only** diagnostic skill. No planning gate required. It can be invoked at any time without approval, writes no files, and makes no mutations.

## Invocation

```
/fluent-workspace-tree
/fluent-workspace-tree --profile <PROFILE>
/fluent-workspace-tree --section features
/fluent-workspace-tree --section source
/fluent-workspace-tree --depth 2
```

## How It Works

### Step 1: Discover Profiles

Scan `accounts/` for profile directories:

```
accounts/*/
```

If `--profile <PROFILE>` is specified, show only that profile. If no profiles exist, report:

```
No accounts/ directory found. Run /fluent-bootstrap to set up your first profile.
```

### Step 2: Scan Directory Structure

For each profile, scan and count artifacts in each category:

**SOURCE (plugin repositories and SDK projects):**
- Glob `accounts/<PROFILE>/SOURCE/backend/*/` for Java Maven plugin repos (identify by `pom.xml` or `module.json`)
- Glob `accounts/<PROFILE>/SOURCE/frontend/*/` for SDK component projects (identify by `package.json`)
- Count: number of backend repos + frontend projects

**Workflows (retailer-scoped):**
- Glob `accounts/<PROFILE>/workflows/*/` for retailer directories
- Within each retailer dir, count `.json` files (excluding `workflow-context.json`)
- Note the retailer ref from directory name

**Features (lifecycle-managed):**
- Glob `accounts/<PROFILE>/features/*/status.json`
- Parse each `status.json` to get feature name and status
- Count by status: N APPROVED, N PLANNING, etc.
- Glob `accounts/<PROFILE>/features/*/assets/*` for visual evidence (screenshots, GIFs, recordings)
- Count assets per feature: N screenshots (.png), N GIFs (.gif), N videos (.webm/.mp4), N reports (.html)

**Reports (ephemeral outputs):**
- Check for subdirectories: `build/`, `pre-deploy/`, `module-validate/`, `e2e-test/`
- Count files in each subdirectory
- Note: these are ephemeral and replaced on each run

**Analysis (persistent cross-cutting):**
- Check for subdirectories: `code/`, `modules/`, `scope/`, `topology/`, `settings/`
- Count files in each subdirectory

**Tasks (operational plans):**
- Count `.md` files in `accounts/<PROFILE>/tasks/`

**Sessions (audit trail):**
- Count `.json` files in `accounts/<PROFILE>/sessions/`

### Step 3: Render the Annotated Tree

Produce an indented tree with annotations:

```
accounts/<PROFILE>/
|-- SOURCE/                              (N backend repos, M frontend projects)
|   |-- backend/                         [Java Maven plugin repos]
|   |   |-- fluentcommerce-fc-module-name-1/
|   |   |   |-- pom.xml                  [Maven build config]
|   |   |   |-- resources/module.json    [module metadata + rule registrations]
|   |   |   |-- src/main/java/           [rule implementations]
|   |   |   |-- src/test/java/           [unit tests]
|   |   |   +-- dist/                    [build output JARs]
|   |   +-- fluentcommerce-fc-module-name-2/
|   |       +-- ...
|   +-- frontend/                        [Mystique SDK component projects]
|       +-- mystique-plugin/
|           |-- package.json             [npm project config]
|           |-- src/index.tsx            [ComponentRegistry registrations]
|           |-- manifests/               [manifest JSON files]
|           +-- dist/                    [bundle.[hash].js + version.json]
|-- workflows/<RETAILER_REF>/            (N workflows)
|   |-- ORDER__HD.json                   [Home Delivery order workflow]
|   |-- ORDER__MULTI.json                [Multi-location order workflow]
|   |-- FULFILMENT__HD.json              [Home Delivery fulfilment workflow]
|   +-- workflow-context.json            [download metadata: profile, retailer, timestamp]
|-- features/                            (N features)
|   |-- curbside-pickup/          [APPROVED] -> ready to build
|   |   |-- spec.md                      [business requirements]
|   |   |-- plan.md                      [implementation plan v1]
|   |   |-- architecture.md             [reverse-engineered architecture doc]
|   |   |-- status.json                  [lifecycle: APPROVED, next: /fluent-rule-scaffold]
|   |   +-- assets/                      (N files) [screenshots, recordings, visual evidence]
|   +-- discount-pricing/         [PLANNING] -> awaiting plan approval
|       |-- spec.md                      [business requirements]
|       +-- status.json                  [lifecycle: PLANNING]
|-- reports/                             (ephemeral build/test outputs)
|   |-- build/                           (N files) [Maven build logs, JAR metadata]
|   |-- pre-deploy/                      (N files) [deployment gate reports]
|   |-- module-validate/                 (N files) [module structure validation]
|   +-- e2e-test/                        (N files) [end-to-end test results]
|-- analysis/                            (persistent cross-cutting analysis)
|   |-- code/                            (N files) [custom code analysis reports]
|   |-- modules/                         (N files) [module inventory]
|   |-- scope/                           (N files) [scope decomposition]
|   |-- topology/                        (N files) [connection topology maps]
|   +-- settings/                        (N files) [settings audit]
|-- tasks/                               (N operational plans)
|   +-- 2026-02-23-module-scaffold-hm-curbside.md
+-- sessions/                            (N audit exports)
    +-- session-abc123.json
```

### Step 4: Add Summary Footer

Below the tree, show aggregate counts:

```
Workspace Summary -- <PROFILE>
  Plugin repos:    2
  Workflows:       18 (across 1 retailer)
  Features:        4 (1 APPROVED, 2 PLANNING, 1 IN_PROGRESS)
  Reports:         7 (3 build, 2 pre-deploy, 1 module-validate, 1 e2e-test)
  Analysis:        5 (2 code, 1 modules, 1 topology, 1 settings)
  Tasks:           3
  Sessions:        1
```

## Section Filtering

When `--section <SECTION>` is specified, show only that section in detail:

| Section | Shows |
|---------|-------|
| `source` | Expanded SOURCE/ tree with backend/ and frontend/ subtrees and file counts per repo/project |
| `workflows` | Expanded workflows/ tree with all workflow files listed |
| `features` | Expanded features/ tree with status details |
| `reports` | Expanded reports/ tree with file listings |
| `analysis` | Expanded analysis/ tree with file listings |
| `tasks` | List all task plan files with dates |
| `sessions` | List all session export files |

### Depth Control

`--depth <N>` controls how many levels deep to expand:
- `--depth 1` -- show only top-level directories with counts
- `--depth 2` -- show directories and immediate children (default)
- `--depth 3` -- show full expansion including individual files

## Multi-Profile View

When no `--profile` filter is specified and multiple profiles exist:

```
accounts/
|-- ACME_PROD/                           (2 repos, 18 workflows, 4 features)
|   +-- ...
|-- ACME_DEV/                            (1 repo, 12 workflows, 1 feature)
|   +-- ...

Workspace Total: 2 profiles, 3 repos, 30 workflows, 5 features
```

## Output Format

The output is always markdown-compatible text rendered directly in the conversation. No files are written.

### Annotations Legend

Annotations appear in brackets or parentheses after directory/file names:

| Annotation | Meaning |
|------------|---------|
| `(N items)` | Count of items in a directory |
| `[description]` | What the file/directory contains |
| `[STATUS]` | Feature lifecycle status from status.json |
| `-> action` | Recommended next action for a feature |

## Edge Cases

- **Empty directories:** Show the directory with `(empty)` annotation. Do not hide empty directories -- their absence is informative.
- **Missing accounts/ directory:** Report clearly and suggest running `/fluent-bootstrap`.
- **Very large workspaces:** If a directory contains more than 20 items, show the first 10 and a count: `... and 15 more`.
- **Decompiled source:** If `SOURCE/backend/.decompiled/` exists, annotate it as `[CFR decompiler output -- not a plugin]`.
- **Reference modules:** If `SOURCE/backend/reference-modules/` exists, annotate as `[OOTB JARs for comparison -- not deployable]`.
- **Permission errors:** Report which directories could not be read and continue with those accessible.
- **Broken symlinks:** Skip and note in a warning line.

## Integration

This skill pairs well with:

- `/fluent-feature-status` -- lifecycle-focused view (this skill is structure-focused)
- `/fluent-session` -- what changed vs. what exists
- `/fluent-custom-code` -- deep dive into source code analysis
- `/fluent-workflow-analyzer` -- deep dive into workflow structure

A common session-start pattern:

```
/fluent-workspace-tree --profile <PROFILE>
/fluent-feature-status --profile <PROFILE>
```

This gives both the structural layout and the feature lifecycle status in one view.

## Handoff Protocol

### Emitted Signals
- `-> READY: accounts/<PROFILE>/` -- Tree rendered successfully
- `-> NEXT: /fluent-use-case-discover` -- No features exist, suggest creating first feature
- `-> NEXT: /fluent-feature-status` -- Features exist, suggest lifecycle view for prioritization
- `-> SKIP: No accounts/ directory found` -- Empty workspace, suggest /fluent-bootstrap

### Consumed Signals
This skill does not consume handoff signals -- it reads directory structure directly.

### Advisory Recommendations

After rendering the tree, suggest next actions based on what's present:

- **No features exist:** "Run /fluent-use-case-discover to create your first feature"
- **No workflows downloaded:** "Run workflow download to get workflows from the live environment"
- **No source repos:** "Clone plugin repos into SOURCE/backend/ (or SDK projects into SOURCE/frontend/) or run /fluent-source-onboard"
- **Features ready to build:** "Feature <name> is APPROVED -- start with /fluent-rule-scaffold"
- **Reports exist:** "Recent build report found -- check /fluent-pre-deploy-check status"

## Error Reporting

| Severity | Code | Scenario | Recovery |
|----------|------|----------|----------|
| LOW | `PARSE_WARNING` | Malformed status.json in a feature directory | Show feature with `[PARSE ERROR]` annotation |
| MEDIUM | `NO_PROFILES` | No accounts/ directory found | Guide to /fluent-bootstrap |
| MEDIUM | `PROFILE_NOT_FOUND` | Specified --profile directory does not exist | Guide to /fluent-connect |
| LOW | `PERMISSION_ERROR` | Cannot read a directory | Report which directories were skipped |

## Session Tracking

When invoked, log:
```
SKILL: /fluent-workspace-tree
  args: [--profile PROFILE] [--section SECTION] [--depth N]
  outcome: completed | failed
  profiles_found: count
  total_repos: count
  total_workflows: count
  total_features: count
  total_reports: count
  total_analysis: count
  total_tasks: count
  total_sessions: count
```
