# dot-ai-workspace-scan

> Scan .ai/ directories and generate compact workspace overview

- Author: Jonathan Gelin
- Repository: jogelin/dot-ai
- Version: 20260207120425
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/jogelin/dot-ai
- Web: https://mule.run/skillshub/@@jogelin/dot-ai~dot-ai-workspace-scan:20260207120425

---

---
name: dot-ai-workspace-scan
description: Scan .ai/ directories and generate compact workspace overview
triggers: [boot]
internal: true
parent: dot-ai
---

# dot-ai-workspace-scan — Workspace Discovery

This sub-skill handles **Phase 2 of the boot sequence** from `dot-ai`.
It scans the workspace for `.ai/` directories and builds a compact overview
that stays in memory for prompt routing.

## When to Run

- At every session start (boot trigger)
- Called automatically by the `dot-ai` boot sequence after Phase 1 (root context)

## Scan Process

### Step 1 — Find all `.ai/` directories

```bash
find . -name ".ai" -type d -maxdepth 3
```

Exclude the root `.ai/` from results — it's already loaded in Phase 1.

### Step 2 — Read project metadata

For each `.ai/` directory found:

1. **Read frontmatter only** from `AGENT.md`:
   ```yaml
   ---
   name: <project-name>
   description: <one-line description>
   tags: [tag1, tag2]
   ---
   ```
   Stop reading after the closing `---`. Do NOT load the full file.

2. **List skill directories**:
   ```bash
   ls <project>/.ai/skills/
   ```

3. **Read skill frontmatter** for each skill found:
   ```yaml
   ---
   name: <skill-name>
   description: <one-line description>
   triggers: [manual, heartbeat, cron]
   ---
   ```
   Again, frontmatter only.

### Step 3 — Build the overview

Format each project as:
```
📁 <name> — <description> [<tags>]
   📋 <skill> — <description> [<triggers>]
```

Example output:
```
📁 pro — Blog smartsdlc.dev, DX consulting [blog, dx, ai]
   📋 medium-digest — Digest articles Medium/Substack [heartbeat, cron]
   📋 write-blog-article — Workflow article blog [manual]
📁 roule-caillou — Projet de vie, recherche terrain [immobilier, van]
   📋 property-search — Veille biens immobiliers [cron]
📁 todo — Tâches perso [tasks]
   📋 todo — Tâches rapides [manual]
```

## Output Rules

### In-Memory Overview
- **Target budget**: ~300 tokens for the entire overview
- Used by `dot-ai` routing during current session to match prompts to projects
- If a project has no `AGENT.md` or no frontmatter, skip it with a warning

### Persistent Index File

**ALSO write** the overview to `.ai/memory/projects-index.md` using markers:

```markdown
<!-- dot-ai-workspace-scan start -->
<!-- Auto-generated by dot-ai-workspace-scan. Do not edit between markers. -->

# 🗺️ Projects Index

Index auto-généré des projets du monorepo. Utilisé pour le routing contextuel.
Chaque projet vit dans `projects/<name>/` et a son propre `.ai/AGENT.md`.

## Projets

| Projet | Description | Keywords |
|--------|-------------|----------|
| dashboard | Dashboard monitoring Kiwi — Astro 5 + Tailwind SSG | dashboard, stats, monitoring |
| pro | Personal brand smartsdlc.dev — blog, CV, articles | blog, dx, ai, smartsdlc |
...

## Skills par projet

### pro
- `medium-digest` → collecte emails Medium/Substack, JSON | "medium", "digest"
- `write-blog-article` → workflow article blog | "écris un article", "blog post"
...

*Last updated: YYYY-MM-DD HH:MM*

<!-- dot-ai-workspace-scan end -->
```

**Rationale:**
- Persistent index allows quick routing without re-scanning at every boot
- Agents can read the cached index file (fast) instead of scanning entire workspace
- Audit compares this file vs actual scan to detect drift
- Humans can also read this file to understand workspace structure

**Update strategy:**
- Generate at boot if file missing or >7 days old
- Manual trigger: "rescan workspace", "update projects index"
- Audit triggers re-scan if drift detected

## Boot Log Integration

This sub-skill contributes to the **dot-ai boot log** (see `dot-ai` SKILL.md → Boot Log).

After scanning, return a compact summary for the boot log:
- **Project count** and **skill count** (totals)
- **Index status**: `fresh (Xd)` | `regenerated (stale)` | `created`
- **Warnings**: any projects with missing AGENT.md or frontmatter

The parent `dot-ai` skill assembles these into the final boot log output.

**Example contributions:**
```
├─ 📁 6 projects, 22 skills
├─ 📋 projects-index.md — fresh (3d)
```

Or with warnings:
```
├─ 📁 5 projects, 18 skills
├─ 📋 projects-index.md — regenerated (was 9d old)
├─ ⚠️ todo — missing AGENT.md frontmatter
```

## Error Handling

- Missing `AGENT.md` → log `⚠️ <path>/.ai/ has no AGENT.md` and skip
- Missing frontmatter → log `⚠️ <path>/AGENT.md has no frontmatter` and skip
- No skills found → show project with no skill lines (that's fine)

## Relationship to Other Sub-skills

- `dot-ai-audit` may call this scan to compare with cached indexes
- `dot-ai-agent-sync` generates the AGENT.md files that this skill reads