myaidev-method 0.3.1 → 0.3.3

package/skills/infographic/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: generating-infographics
+description: Creates diagrams (architecture, flowcharts, timelines, sequences) from Mermaid code and inserts them into markdown articles as asset-referenced images (PNG by default for universal compatibility). Use when enriching articles with diagrams, adding infographics to blog posts, visualizing technical content, or when the user mentions diagrams, infographics, or visual content for markdown.
+argument-hint: "[article.md] [--style=modern] [--max-diagrams=8] [--theme=default]"
+allowed-tools: [Read, Write, Edit, Bash, Task, Glob, Grep, AskUserQuestion]
+context: fork
+---
+
+# Infographic Orchestrator
+
+Analyze articles, generate Mermaid diagrams, render via `mmdc`, save as assets, and reference from markdown.
+
+```
+Article.md → Analyze → Design Mermaid → Render → Save to assets/ → Reference in markdown
+```
+
+## Subagent Registry
+
+Each subagent is a real Claude Code subagent defined in `agents/` with its own tools and model:
+
+| Phase | Subagent Name | Model | Tools |
+|-------|--------------|-------|-------|
+| Analyze | `infographic-analyzer-agent` | haiku | Read, Write, Glob |
+| Design | `infographic-designer-agent` | haiku | Read, Write |
+
+## Parameters
+
+| Parameter | Default | Notes |
+|-----------|---------|-------|
+| `article` | Required | Path to markdown file |
+| `--style` | `modern` | `modern`, `minimal`, `corporate` |
+| `--max-diagrams` | `8` | Cap on diagrams |
+| `--theme` | `default` | Mermaid theme: `default`, `dark`, `forest`, `neutral` |
+| `--format` | `png` | Output format: `png` (recommended) or `svg` |
+| `--output` | input path | Output path |
+| `--dry-run` | `false` | Show plan without modifying |
+
+**Why PNG by default**: Mermaid generates SVGs using `<foreignObject>` HTML elements for text in most diagram types (sequence, timeline, state, etc.). The `htmlLabels: false` config only fixes flowcharts. This causes text to vanish in:
+- **WordPress** — the SVG sanitizer (`enshrined/svg-sanitize`) strips `<foreignObject>` on upload
+- **Zed/resvg** — no `foreignObject` support
+- **Inkscape, macOS Preview, Office** — same issue
+
+PNG is rendered by Puppeteer (real Chromium), so text always shows. At `-s 2` (2x scale) the output is sharp on retina displays. Use `--format=svg` only if you need scalable vectors and will serve them exclusively in web browsers (not through WordPress media library upload).
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+Progress:
+- [ ] Phase 0: Initialize (validate article, check mmdc)
+- [ ] Phase 1: Analyze (spawn analyzer agent)
+- [ ] Phase 2: Design (spawn designer agent)
+- [ ] Phase 3: Render & validate diagrams
+- [ ] Phase 4: Save to assets/ and insert references
+- [ ] Phase 5: Cleanup and report
+```
+
+### Phase 0: Initialize
+
+- Parse `$ARGUMENTS` for article path and flags
+- Validate file exists and is markdown
+- Create working directory: `.infographic-session/`
+- Verify mmdc: `npx -y @mermaid-js/mermaid-cli --version`
+- Determine output format from `--format` flag (default: `png`)
+- Write mmdc config:
+
+```bash
+cat > .infographic-session/mermaid-config.json << 'EOF'
+{
+  "flowchart": { "htmlLabels": false, "useMaxWidth": false },
+  "sequence": { "useMaxWidth": false },
+  "gantt": { "useMaxWidth": false }
+}
+EOF
+```
+
+The `htmlLabels: false` setting forces native SVG `<text>` elements instead of `<foreignObject>` HTML, improving compatibility with non-browser renderers. This config is used for both SVG and PNG output.
+
+### Phase 1: Analyze
+
+Spawn the analyzer subagent:
+
+```
+Task(subagent_type: "infographic-analyzer-agent", prompt: "
+  Analyze the article at '{article_path}' for diagram opportunities.
+  Max diagrams: {max_diagrams}.
+  Read the article, identify high-impact diagram opportunities,
+  and write your analysis to .infographic-session/analysis.json
+")
+```
+
+Review the analysis before proceeding. If `--dry-run`, report the plan and stop.
+
+### Phase 2: Design
+
+Read `.infographic-session/analysis.json`, then spawn the designer subagent:
+
+```
+Task(subagent_type: "infographic-designer-agent", prompt: "
+  Generate Mermaid diagrams based on the analysis.
+  Read the analysis from: .infographic-session/analysis.json
+  Read the article from: {article_path}
+  Style preset: {style}. Theme: {theme}.
+  Write your Mermaid diagrams to .infographic-session/diagrams.json
+")
+```
+
+### Phase 3: Render & Validate
+
+For each diagram in `diagrams.json`:
+
+1. Write Mermaid source to `.infographic-session/{id}.mmd`
+2. Render:
+   ```
+   npx -y @mermaid-js/mermaid-cli \
+     -i .infographic-session/{id}.mmd \
+     -o .infographic-session/{id}.{format} \
+     -t {theme} \
+     -c .infographic-session/mermaid-config.json \
+     -s 2 \
+     -b white \
+     --quiet
+   ```
+   The `-s 2` flag renders at 2x resolution for sharp output. Use `-b transparent` instead of `-b white` if the article has a dark theme.
+3. Validate the output file exists and has non-trivial size (>1KB)
+4. If render fails, log the error and skip that diagram
+
+### Phase 4: Save & Reference
+
+For each successfully rendered diagram:
+
+1. Create `assets/` directory next to the article file if it doesn't exist
+2. Copy `.infographic-session/{id}.{format}` to `{assets-dir}/{article-slug}-{id}.{format}` (slug = article filename without extension)
+3. Insert reference after the target heading's section content:
+
+```markdown
+<div class="infographic" data-diagram-id="{id}" data-type="{type}">
+
+![{alt_text}](assets/{article-slug}-{id}.{format})
+
+</div>
+
+*Figure {n}: {caption}*
+```
+
+### Phase 5: Cleanup & Report
+
+- Remove `.infographic-session/` working directory
+- Report:
+
+```
+Infographic Enrichment Complete
+  Article: {path}
+  Format: {format}
+  Assets: {assets-dir}/
+  Diagrams: {count}/{attempted}
+  Created:
+  1. [{type}] assets/{slug}-diag-1.{format} → after "## Heading"
+```
+
+## Error Handling
+
+- If a subagent fails, log the error and continue with what's available
+- Analyzer failure → ask user if they want to provide diagram ideas manually
+- Designer failure → attempt to generate Mermaid code directly in this context
+- Render failure → log and skip, never block the pipeline on a single diagram
+
+## Context Management
+
+Before dispatching each subagent, restate in the Task prompt:
+- Current phase and what's been completed
+- Key decisions made (chosen style, theme, article type)
+- What this subagent needs to accomplish
+
+## Progress Reporting
+
+At each phase transition, report to the user:
+
+```
+→ Phase 1/5: Analyzing "{article}"...
+  Done: Found {n} diagram opportunities ({high} high-impact)
+→ Phase 2/5: Designing Mermaid diagrams...
+  Done: {n} diagrams designed
+→ Phase 3/5: Rendering {format} files...
+  Done: {rendered}/{total} rendered successfully
+→ Phase 4/5: Saving assets and updating article...
+  Done: {n} diagrams inserted
+→ Phase 5/5: Cleanup...
+  Done.
+```

package/skills/myaidev-analyze/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: myaidev-analyze
+description: "Deep codebase analysis that detects patterns, conventions, tech stack, dependencies, and risk areas. Use before starting development on an existing project, for onboarding, or to generate a project profile for other MyAIDev skills."
+argument-hint: "[path] [--depth=quick|standard|deep] [--output=.dev-analysis] [--focus=patterns|dependencies|risks|all]"
+allowed-tools: [Read, Write, Glob, Grep, Bash, Task, AskUserQuestion]
+context: fork
+---
+
+# Codebase Analyzer Skill v1 — Orchestrator Pattern
+
+You are the **Codebase Analysis Orchestrator**, a coordinator that decomposes project analysis into specialized subagent tasks. You maintain a lightweight planning context while delegating intensive scanning and detection work to isolated subagents.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  ORCHESTRATOR (this skill)               │
+│  • Parses arguments & validates target path              │
+│  • Creates execution plan based on --depth               │
+│  • Dispatches subagents (parallel where possible)        │
+│  • Synthesizes results into unified profile              │
+│  • Generates human-readable analysis report              │
+└──────────────┬──────────────────────────────────────────┘
+               │ spawns (parallel)
+    ┌──────────┼──────────────┬─────────────────┐
+    ▼          ▼              ▼                 ▼
+┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐
+│Structure│ │ Pattern  │ │Dependency│ │    Tech      │
+│Scanner │ │ Detector │ │ Mapper   │ │  Profiler    │
+└────────┘ └──────────┘ └──────────┘ └──────────────┘
+    │          │              │                │
+    ▼          ▼              ▼                ▼
+┌─────────────────────────────────────────────────────┐
+│              SYNTHESIZER (orchestrator)              │
+│  • Reads all agent outputs                          │
+│  • Creates project-profile.json                     │
+│  • Generates analysis-report.md                     │
+└─────────────────────────────────────────────────────┘
+```
+
+## Execution Phases
+
+### Phase 0: Initialize
+- Parse `$ARGUMENTS` for target path, flags, and parameters
+- If no path provided, default to the current working directory
+- Verify the target directory exists (fail fast if it does not)
+- Determine analysis depth from `--depth` flag (default: `standard`)
+- Determine focus area from `--focus` flag (default: `all`)
+- Determine output directory from `--output` flag (default: `.dev-analysis`)
+- Create the output directory if it does not exist
+- Write parsed config to `{output}/config.json`
+
+### Phase 1: Parallel Analysis (Subagents)
+Dispatch subagents based on the `--depth` setting. All eligible agents run **in parallel** to maximize throughput.
+
+**Depth: quick** (fastest — 2 agents)
+```
+Task(subagent_type: "general-purpose", prompt: structure-scanner-agent.md)
+Task(subagent_type: "general-purpose", prompt: tech-profiler-agent.md)
+```
+
+**Depth: standard** (default — 4 agents)
+```
+Task(subagent_type: "general-purpose", prompt: structure-scanner-agent.md)
+Task(subagent_type: "general-purpose", prompt: pattern-detector-agent.md)
+Task(subagent_type: "general-purpose", prompt: dependency-mapper-agent.md)
+Task(subagent_type: "general-purpose", prompt: tech-profiler-agent.md)
+```
+
+**Depth: deep** (comprehensive — 4 agents with expanded scope)
+All 4 agents run with expanded analysis. Instruct each agent to:
+- Increase sample sizes (e.g., pattern detector samples 20-25 files instead of 10-15)
+- Include secondary analysis (e.g., dependency mapper also maps internal import graphs)
+- Report on edge cases and anomalies
+
+**Focus filtering**: When `--focus` is not `all`, still run all depth-eligible agents but instruct the orchestrator synthesis (Phase 2) to emphasize the requested focus area in the final report.
+
+Each subagent writes its output to the `{output}/` directory:
+
+| Agent | Output File |
+|-------|------------|
+| Structure Scanner | `{output}/structure.md` |
+| Pattern Detector | `{output}/conventions.md` |
+| Dependency Mapper | `{output}/dependencies.md` |
+| Tech Profiler | `{output}/project-profile.json` |
+
+### Phase 2: Synthesize
+The orchestrator reads all agent output files and creates:
+
+1. **`{output}/project-profile.json`** — Unified structured profile (merge tech profiler output with summaries from other agents):
+```json
+{
+  "project_name": "detected or directory name",
+  "analyzed_at": "ISO timestamp",
+  "depth": "quick|standard|deep",
+  "tech_stack": {
+    "languages": [],
+    "frameworks": [],
+    "runtime": "",
+    "package_manager": ""
+  },
+  "build": {
+    "bundler": "",
+    "test_framework": "",
+    "linting": [],
+    "ci_cd": ""
+  },
+  "structure": {
+    "organization_pattern": "",
+    "total_files": 0,
+    "files_by_language": {},
+    "entry_points": [],
+    "test_directories": [],
+    "config_files": []
+  },
+  "conventions": {
+    "file_naming": "",
+    "function_naming": "",
+    "import_style": "",
+    "error_handling": "",
+    "architecture_pattern": ""
+  },
+  "dependencies": {
+    "total": 0,
+    "by_category": {},
+    "risks": []
+  },
+  "risks": [],
+  "recommendations": []
+}
+```
+
+2. **`{output}/analysis-report.md`** — Human-readable report summarizing all findings with sections for structure, patterns, dependencies, tech stack, risks, and recommendations.
+
+### Phase 3: Report
+Present a summary to the user with key findings:
+
+```
+→ Codebase Analysis Complete: {project_name}
+  Depth: {depth} | Files: {total_files} | Languages: {languages}
+
+  Tech Stack:   {runtime} + {framework} | {package_manager}
+  Build:        {bundler} | Tests: {test_framework} | Lint: {linters}
+  Architecture: {architecture_pattern} | Organization: {org_pattern}
+
+  Risks Found:  {risk_count}
+  {risk_1}
+  {risk_2}
+  ...
+
+  Output: {output}/
+    ├── analysis-report.md      (human-readable report)
+    ├── project-profile.json    (structured profile)
+    ├── structure.md            (directory analysis)
+    ├── conventions.md          (patterns & conventions)
+    └── dependencies.md         (dependency analysis)
+```
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `path` | Target directory to analyze | Current working directory |
+| `--depth` | Analysis depth: `quick`, `standard`, `deep` | `standard` |
+| `--output` | Output directory for analysis results | `.dev-analysis` |
+| `--focus` | Focus area: `patterns`, `dependencies`, `risks`, `all` | `all` |
+
+## Subagent Prompt Templates
+
+Each subagent has a detailed prompt template in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting the dynamic variables.
+
+| Agent | Prompt File | Key Variables |
+|-------|-------------|---------------|
+| Structure Scanner | [agents/structure-scanner-agent.md](agents/structure-scanner-agent.md) | target_path, depth, output_dir |
+| Pattern Detector | [agents/pattern-detector-agent.md](agents/pattern-detector-agent.md) | target_path, depth, output_dir |
+| Dependency Mapper | [agents/dependency-mapper-agent.md](agents/dependency-mapper-agent.md) | target_path, depth, output_dir |
+| Tech Profiler | [agents/tech-profiler-agent.md](agents/tech-profiler-agent.md) | target_path, depth, output_dir |
+
+## State Management (Scratchpad Pattern)
+
+All intermediate work is written to the output directory:
+
+```
+{output}/
+├── config.json              # Parsed arguments and settings
+├── structure.md             # Structure scanner output
+├── conventions.md           # Pattern detector output
+├── dependencies.md          # Dependency mapper output
+├── project-profile.json     # Tech profiler output → merged unified profile
+└── analysis-report.md       # Final human-readable report
+```
+
+This keeps the orchestrator's context lean — it reads only what it needs for each phase.
+
+## Error Handling
+
+- If a subagent fails, log the error and continue with remaining agents
+- Structure scanner failure → report what other agents found, note incomplete structure data
+- Pattern detector failure → report "conventions not analyzed" in profile
+- Dependency mapper failure → report "dependencies not analyzed" in profile
+- Tech profiler failure → attempt basic detection from file extensions and config files
+- Always produce a `project-profile.json` and `analysis-report.md`, even if partial
+- Never block the entire pipeline on a single agent failure
+
+## Context Management
+
+### Context Regurgitation
+Before dispatching each subagent, include in its prompt:
+- The target path and depth setting
+- The output directory where it should write results
+- Any relevant config from Phase 0 parsing
+
+### File Buffering
+All subagent outputs go to `{output}/` files — never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for synthesis. This keeps the orchestrator's active context lean.
+
+## Integration with Other Skills
+
+This skill produces output that other MyAIDev skills can consume:
+
+- **myaidev-architect**: Reads `project-profile.json` to understand existing stack before designing new architecture
+- **myaidev-coder**: Reads `conventions.md` to match existing code patterns
+- **myaidev-debug**: Reads `dependencies.md` and `structure.md` for faster bug investigation
+- **myaidev-reviewer**: Uses `conventions.md` as a baseline for code review standards
+
+## Example Usage
+
+```bash
+# Analyze current project with default settings
+/myaidev-method:myaidev-analyze .
+
+# Quick scan of a specific directory
+/myaidev-method:myaidev-analyze ./backend --depth=quick
+
+# Deep analysis focused on risks
+/myaidev-method:myaidev-analyze /path/to/project --depth=deep --focus=risks
+
+# Custom output directory
+/myaidev-method:myaidev-analyze . --output=./docs/analysis
+
+# Analyze before starting work on an unfamiliar codebase
+/myaidev-method:myaidev-analyze /path/to/inherited-project --depth=deep
+```