shenxingy/map

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $skill-name skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

/map Skill: Generate Project Architecture Diagram

Purpose

Automatically scan the project structure and generate ARCHITECTURE.md with a module relationship diagram using Mermaid.

Execution Steps

1. Read existing ARCHITECTURE.md

   • If ARCHITECTURE.md exists at the project root, read it first
   • This helps preserve any existing documentation and allows you to update rather than overwrite

2. Scan project structure

   • Use Glob to find major directories: find . -maxdepth 2 -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*'
   • For each top-level directory (src/, lib/, app/, components/, etc.), identify:
     • What it contains (modules, libraries, features)
     • Its primary responsibility
     • Key files or sub-modules within it

3. Identify modules and dependencies

   • Scan key files with Grep/Read to understand module structure
   • Map logical dependencies (imports, API calls, shared state)
   • Identify which modules depend on which others
   • Look for: package.json, setup.py, .go files, main entry points

4. Generate Mermaid diagram

   • Create a graph TD (top-down) Mermaid diagram showing:
     • Each major module as a node (use clear, short names)
     • Arrows showing dependencies: ModuleA --> ModuleB means ModuleA imports/uses ModuleB
     • Group related modules if they form a subsystem
   • Keep the diagram readable (max ~10-15 nodes for clarity)
   • Example structure:

     graph TD
       API["API Layer"]
       DB["Database"]
       Auth["Authentication"]
       UI["Frontend"]
     
       UI --> API
       API --> Auth
       API --> DB
       Auth --> DB
     

5. Write ARCHITECTURE.md

   • Create or update ARCHITECTURE.md at the project root

   • Structure:

     # Project Architecture
     
     ## Overview
     [1-2 sentence high-level description of what the project does]
     
     ## Directory Structure
     
     ### src/
     [Description of what this directory contains]
     - Key files: file1.ts, file2.ts
     
     ### lib/
     [Description]
     - Key files: ...
     
     [... repeat for each top-level directory ...]
     
     ## Module Relationships
     
     ```mermaid
     [Your generated Mermaid graph]
     

     Key Components

     Module Name

     • Location: src/module/
     • Responsibility: What this module does
     • Exports: Key functions/classes
     • Depends on: Other modules it uses

     [... repeat for each major module ...]

     Data Flow

     [Optional: describe how data flows through the system, if applicable]

   • Keep descriptions concise (1-3 lines per section)

   • Focus on "why" not "what" — what problem does each module solve?

6. Report success

   • Tell the user: "Updated ARCHITECTURE.md"
   • If the diagram is complex, add a note about what the diagram shows

Implementation Notes

• Diagram scope: Show the 5-10 most important modules, not every single file
• Avoid noise: Don't include vendored code (node_modules, venv, .git)
• Update strategy: If ARCHITECTURE.md exists, preserve existing descriptions and update the diagram + file list
• Language: Use English for all documentation
• Mermaid syntax: Use valid Mermaid graph TD syntax; test the diagram visually if possible

Success Criteria

✓ ARCHITECTURE.md exists at project root ✓ Diagram renders without syntax errors ✓ All major modules are represented ✓ Dependencies are correctly shown ✓ Descriptions are clear and concise

Completion Status

• ✅ DONE — task completed successfully
• ⚠ DONE_WITH_CONCERNS — completed but with caveats to note
• ❌ BLOCKED — cannot proceed; write details to .clade/blockers.md
• ❓ NEEDS_CONTEXT — missing information; use AskUserQuestion

3-strike rule: If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.