autogen-guide

# AutoGen Guide from Source Code Generate an interactive guide `content.json` by analyzing UI source code. This skill orchestrates a multi-phase pipeline where **each phase runs in a sub-agent that loads only the context it needs**. The orchestrator (you) manages the workflow, user interactions, and handoffs. **Do NOT read external reference files upfront.** Each phase's sub-agent loads its own references. Everything the orchestrator needs is inline below. This skill implements the **skill-memory convention**. See `.cursor/skills/skill-memory.md` for the shared `assets/`, manifest, and frontmatter standards that this skill extends. --- ## Workflow Overview ``` Input (GitHub URLs) │ ├─ Phase 0: Check for Prior Run ── orchestrator │ Output: skip or warm-start based on manifest │ ├─ Phase 1: Acquire & Scope ────── orchestrator (no external reads) │ Runs: extract_components.py → assets/component-extraction.json │ Writes: source files fetched, scope confirmed by user │ Creates: {guide_dir}/assets/ │ ├─ Phase 2: Extract & Assess ───── sub-agent loads shared/critical-rules.md │ │ + extraction-patterns.md + selector-strategies.md │ │ + reads assets/component-extraction.json │ Writes: {guide_dir}/assets/extraction-report.md │ ├─ Checkpoint: Plan ────────────── orchestrator builds plan, user confirms │ Writes: {guide_dir}/assets/guide-plan.md │ ├─ Checkpoint: Package Metadata ── orchestrator gathers manifest fields from user │ Writes: {guide_dir}/assets/package-metadata.json │ ├─ Phase 3: Generate Guide ──────── per-section sub-agents, each loads authoring-guide.mdc │ │ + shared/critical-rules.md │ │ + receives component-extraction.json context for its section │ │ 3.1 Create guide shell (orchestrator) │ │ 3.2 For each section → sub-agent generates section JSON │ │ 3.3 Assemble via assemble_guide.py → content.json (with validation) │ │ 3.4 Generate assets/selector-report.md (orchestrator) │ Writes: {guide_dir}/content.json + {guide_dir}/assets/selector-report.md │ ├─ Phase 4: Review & Fix ──────── sub-agent loads review-guide-pr.mdc │ Writes: fixed content.json + change report │ ├─ Phase 5a: Write Skill Memory ── orchestrator │ Writes: {guide_dir}/assets/manifest.yaml │ ├─ Phase 5b: Generate Package Manifest ── orchestrator │ Runs: generate_manifest.py → {guide_dir}/manifest.json │ └─ Phase 6: Validate Package ──── orchestrator Runs: assemble_guide.py --validate-only + optional CLI validate --package ``` --- ## Critical Rules Read `.cursor/skills/shared/critical-rules.md` for rules 1–15. These apply to ALL generated guides and are passed to sub-agents in their prompts. --- ## Generated Files The skill's deliverable lives at the output directory root. Everything in `assets/` is skill-internal context — not consumed by the end product. ``` {guide_dir}/ content.json ← the deliverable (Pathfinder guide) manifest.json ← the package manifest (generated in Phase 5b) assets/ extraction-report.md ← component analysis, fields, selectors, grades guide-plan.md ← section structure and source file assignments selector-report.md ← selector quality assessment package-metadata.json ← manifest fields gathered at Package Metadata checkpoint manifest.yaml ← provenance, drift detection, skill memory ``` `assets/` files are auto-generated and should not be edited manually. ### Frontmatter disclaimer Every generated markdown file in `assets/` **must** start with the standard frontmatter from the skill-memory convention, extended with source-specific fields: ```markdown --- disclaimer: Auto-generated by autogen-guide skill. Do not edit manually. notice: To regenerate, re-run the skill against this source. input_sha256: {hex digest} source: {owner}/{repo}@{commit_sha}:{path} --- ``` ### Manifest file After all phases complete, write `{guide_dir}/assets/manifest.yaml`: ```yaml # Auto-generated by autogen-guide skill. Do not edit manually. schema_version: 1 skill_name: "autogen-guide" generated_at: "{ISO 8601 timestamp}" input_sha256: "{hex digest — see below}" source: repo: "{owner}/{repo}" branch: "{branch}" path: "{path}" commit_sha: "{sha}" guide: id: "{guide_id}" sections: - "{section-id-1}" - "{section-id-2}" total_steps: {N} selector_quality: green: {N} yellow: {N} red: {N} files: extraction_report: "assets/extraction-report.md" guide_plan: "assets/guide-plan.md" selector_report: "assets/selector-report.md" ``` Compute `input_sha256` by hashing the source identity — the commit SHA is the natural fingerprint for source code drift: ```bash echo -n "{owner}/{repo}:{path}@{commit_sha}" | shasum -a 256 ``` This means cosmetic guide edits (title wording, step reordering) do not trigger re-extraction — only an actual source code change does. --- ## Golden Examples These examples show the target output quality for common UI patterns. Pass the relevant ones to each section's sub-agent. ### Example A: Tab with conditional fields The most common section pattern. Tab click → fields → conditional fields with `skippable` + `hint`. ```json { "intro": { "type": "markdown", "content": "Choose how the datasource authenticates with your API. Most public APIs need no auth; private APIs typically use Bearer tokens or API keys." }, "section": { "type": "section", "id": "authentication-settings", "title": "Authentication Settings", "requirements": ["on-page:/connections/datasources/edit"], "blocks": [ { "type": "interactive", "action": "button", "reftarget": "Authentication", "content": "Click the **Authentication** tab.", "tooltip": "Configure credentials for APIs that require authentication." }, { "type": "interactive", "action": "button", "reftarget": "Bearer Token", "doIt": false, "content": "**Bearer Token** sends a static token in the Authorization header.", "tooltip": "Use for JWT-based APIs or personal access tokens.", "skippable": true, "hint": "Select the auth method that matches your API." }, { "type": "interactive", "action": "highlight", "reftarget": "[aria-label='bearer token']", "doIt": false, "content": "Paste your **Bearer token** here.", "tooltip": "Stored encrypted. Sent as Authorization: Bearer <token> with every request.", "skippable": true, "hint": "Select Bearer Token auth first to reveal this field." } ] }, "summary": { "type": "markdown", "content": "Each auth method reveals its own credential fields when selected." } } ``` Key things: section bookends (intro markdown immediately before each section, summary immediately after — not inside), tab-click before fields, `skippable: true` with `hint` on conditional fields, `doIt: false` on secrets, include `exists-reftarget` in requirements for selector-targeting steps, concise tooltips that don't name the highlighted element. ### Example B: Card grid selection When the UI uses clickable cards (not a dropdown) for choosing an option. Each card is a `button` action with `doIt: false`. ```json { "type": "interactive", "action": "button", "reftarget": "Basic Authentication", "doIt": false, "content": "**Basic Authentication** encodes username and password in the Authorization header.", "tooltip": "Sends credentials with every request. Use for simple APIs.", "skippable": true, "hint": "Click any auth card to see its fields." } ``` Key things: `action: "button"` with the card's visible text, `doIt: false` so the user makes the choice, `skippable` because only one card applies. ### Example C: Toggle switches and field arrays Toggles get `doIt: false` with an explanatory tooltip. Field arrays (add/remove) get the "Add" button highlighted with `doIt: false`. ```json [ { "type": "interactive", "action": "highlight", "reftarget": "label:has(span:contains('Skip TLS Verify'))", "doIt": false, "content": "**Skip TLS Verify** disables certificate validation.", "tooltip": "Not recommended for production. Only for dev with self-signed certs.", "skippable": true, "hint": "Scroll to TLS / SSL Settings within the Network tab." }, { "type": "interactive", "action": "button", "reftarget": "Add Custom HTTP Header", "doIt": false, "content": "Click **Add Custom HTTP Header** to add key-value headers sent with every request.", "tooltip": "Common uses: API versioning, content type, request tracing.", "skippable": true } ] ``` Key things: toggles always `doIt: false`, field array uses button action on "Add" text with `doIt: false` (don't try to interact with dynamic row items). ### Example D: Tab navigation when tab has no stable selector When a tab has no `data-testid`, use `:contains()` pseudo-selector with `doIt: false` and a `hint`. If the tab text is unique, `action: "button"` with the tab text can work. ```json { "type": "interactive", "action": "button", "reftarget": "Network", "doIt": false, "content": "Click the **Network** tab for timeout, TLS/SSL, and proxy settings.", "tooltip": "Configure connection behavior and security certificates." } ``` Key things: `action: "button"` with the tab label text. If the text isn't unique on the page, use `"reftarget": "div[role='tab']:contains('Network')"` or similar structural selector. Always `doIt: false` when the selector is fragile. ### Example E: markdown for complex concepts When no single element can be targeted but the user needs context. Prefer `markdown` over `noop` so Pathfinder does not number the prose as a step. Use `noop` only for an intentional numbered pause that is not a click/type instruction. ```json { "type": "markdown", "content": "**Proxy Settings** offer three modes: **Default** (uses environment vars), **None** (direct), and **URL** (custom proxy). Choose **URL** when you need custom proxy fields." } ``` Key things: `markdown` for explanation without a selector. Do not use `noop` as a flaky-selector fallback or for “click / enter / select …” copy. Keep it brief. --- ## Phase 0: Check for Prior Run (Orchestrator) Before starting the full generation pipeline, check whether this guide has been generated before. 1. Check whether `{guide_dir}/assets/manifest.yaml` exists 2. If it does: read the manifest, extract `input_sha256` and `generated_at` 3. Re-hash the current input: `echo -n "{owner}/{repo}:{path}@{current_commit_sha}" | shasum -a 256` 4. Compare hashes: - **Match** → no drift; tell the user the guide is up to date and offer options: skip to Phase 4 review, re-generate a specific section, or proceed with a full fresh run - **Mismatch** → drift detected; tell the user the source has changed since `{generated_at}` (commit `{stored_sha}` → `{current_sha}`), then proceed with a delta-aware re-run using prior `assets/extraction-report.md` as warm-start context for the Phase 2 sub-agent 5. If manifest does not exist: fresh run — proceed to Phase 1 ``` assets/manifest.yaml exists? No → full generation pipeline (Phase 1 onward) Yes → re-hash input matches stored hash? Yes → offer user: skip to review, re-gen section, or fresh run No → delta re-run (use prior assets/ as warm start, then Phase 1 onward) ``` --- ## Phase 1: Acquire and Scope (Orchestrator) You handle this phase directly. No sub-agent needed -- it's mostly tool calls. ### 1.1 Parse the Input The user provides GitHub references: - **File URL**: `https://github.com/org/repo/blob/main/src/ConfigEditor.tsx` - **Directory URL**: `https://github.com/org/repo/tree/main/src/editors/config/` - **Repo + path hint**: `https://github.com/org/repo` with "look at `src/editors/`" Extract: `owner`, `repo`, `branch`, `path(s)`. ### 1.2 Fetch the Source Code Shallow-clone the repo: ```bash git clone --depth 1 --single-branch --branch <branch> https://github.com/<owner>/<repo>.git /tmp/autogen-<repo> ``` Or for individual files, use the GitHub MCP tools (`get_file_contents`) or `gh` CLI. If the user has already cloned the repo or provides local file paths, use those directly. ### 1.3 Assess Scope After fetching the source files, run the component extraction script to get a deterministic count: ```bash python .cursor/tools/extract_components.py {source_file_1} {source_file_2} ... > {guide_dir}/assets/component-extraction.json ``` Use the `scopeEstimate` output to present scope to the user: > "The linked directory contains {totalFieldSets} field groups and {totalComponents} interactive elements. This will produce a guide with approximately {N} sections and {M} steps. Should I proceed, narrow, or expand?" Scope guidelines: - **< 5 elements**: Too small. Suggest expanding. - **5-40 elements**: Good scope for one guide. - **40-80 elements**: Large. Consider splitting into multiple guides. - **> 80 elements**: Must split or narrow. ### 1.4 Identify the Entry Point Look for: - The file the user linked directly - Default exports named `ConfigEditor`, `QueryEditor`, `SettingsPage`, or similar - The component registered in `module.ts` or `plugin.json` ### 1.5 Map the Component Tree From the entry point: 1. Read the entry file, identify local imports (skip `@grafana/*`, `react`, etc.) 2. For each imported component, read its file (one level deep max) 3. Note which file renders which sub-components Record the commit SHA for provenance: ```bash git -C /tmp/autogen-<repo> rev-parse HEAD ``` ### 1.6 Create the Guide Directory Create `{guide-id}/` in the workspace root and `{guide-id}/assets/` for generated analysis files. The `guide-id` should be kebab-case, derived from the component's purpose (e.g., `infinity-config-tour`).