diff --git a/.claude/SKILLS.md b/.claude/SKILLS.md index 40b9462..08665dd 100644 --- a/.claude/SKILLS.md +++ b/.claude/SKILLS.md @@ -51,6 +51,7 @@ This document provides a comprehensive overview of all available Spec-Kit Comman │ │ ├── defect-report/ │ │ ├── traceability-matrix/ │ │ └── test-report/ +│ ├── xmind-import/ # Fetch XMind share URL → Mermaid │ ├── adamelliotfields-skills-d2-diagram/ # Diagramming │ └── ui-ux-pro-max/ # UI/UX Design Intelligence ├── agents/ # AI Agent definitions (35 agents) @@ -127,6 +128,15 @@ Skills for designing APIs, services, data models, and architecture. | `/flowchart` | Generate Mermaid flowcharts | `/flowchart annotation submission and async scoring flow` | | `/d2-diagram` | Generate D2 diagrams (architecture, flow, thesis chapter) | `/d2-diagram system architecture` | +### Diagramming (2 skills) + +Skills for importing and generating diagrams from external sources. + +| Skill | Purpose | Example Usage | +|-------|---------|---------------| +| `/d2-diagram` | Generate D2 diagrams (architecture, flow, thesis chapter) | `/d2-diagram system architecture` | +| `/xmind-import` | Fetch XMind share URL → parse JSON → output Mermaid `flowchart LR` | `/xmind-import https://app.xmind.com/share/PKjJEIHD docs/functional-map/functional-map.md` | + ### UI/UX Design (1 skill) Skills for UI design systems, component styling, and UX best practices. @@ -196,8 +206,8 @@ Skills for quality gates, defect management, traceability, and reporting. | Test Engineering | 6 | test-plan, test-coverage, test-data-strategy, test-tracking, exploratory-testing, regression-suite | | Quality Assurance | 4 | quality-gate, defect-report, traceability-matrix, test-report | | UI/UX Design | 1 | ui-ux-pro-max | -| Diagramming | 1 | d2-diagram (adamelliotfields) | -| **Total** | **30** | | +| Diagramming | 2 | d2-diagram (adamelliotfields), xmind-import | +| **Total** | **31** | | --- @@ -245,4 +255,4 @@ For the Label Suite project, these skills enforce additional constraints for the --- *Last Updated: 2026-03-25* -*Total Skills: 30 | Spec-Kit Commands: 9* +*Total Skills: 31 | Spec-Kit Commands: 9* diff --git a/.claude/skills/xmind-import/SKILL.md b/.claude/skills/xmind-import/SKILL.md new file mode 100644 index 0000000..f5e890f --- /dev/null +++ b/.claude/skills/xmind-import/SKILL.md @@ -0,0 +1,142 @@ +--- +name: xmind-import +description: Use this skill whenever the user shares an XMind share URL (app.xmind.com/share/...) and wants to import, convert, or export the mind map — even if they don't say "xmind-import" explicitly. Triggers on: "convert this XMind link", "import my mind map", "turn this XMind into Mermaid", "parse this XMind", or when the user pastes an app.xmind.com/share URL alongside any request involving diagrams or markdown. Fetches the mind map JSON via Playwright MCP, converts the tree structure to a Mermaid flowchart LR diagram, and writes it to a markdown file or prints it to the conversation. +--- + +# XMind Import + +Fetch a public XMind share link, extract the mind map JSON, and convert it to a `flowchart LR` Mermaid diagram. + +## Usage + +``` +/xmind-import [output-path] +``` + +**Examples:** + +``` +/xmind-import https://app.xmind.com/share/PKjJEIHD docs/functional-map/functional-map.md +/xmind-import https://app.xmind.com/share/ABC123 +``` + +If `output-path` is omitted, print the Mermaid source to the conversation. + +--- + +## Steps + +### Step 1 — Extract the file ID from the URL + +Parse the share URL to get `fileId`: + +``` +https://app.xmind.com/share/{fileId} + ↑ this part +``` + +For example, `https://app.xmind.com/share/PKjJEIHD` → `fileId = PKjJEIHD`. + +### Step 2 — Navigate with Playwright + +Use `mcp__plugin_playwright_playwright__browser_navigate` to open the share page. This establishes the session cookies that allow the API call in Step 3 to succeed without authentication. + +``` +url: https://app.xmind.com/share/{fileId} ← substitute real fileId +``` + +### Step 3 — Wait for the SPA to load + +Use `mcp__plugin_playwright_playwright__browser_wait_for` with `time: 3`. + +The page title changes from the generic XMind branding to the mind map name (e.g., "Label Suite - Xmind AI") once the JavaScript has fully loaded. + +### Step 4 — Fetch, parse, and convert in one browser call + +Use `mcp__plugin_playwright_playwright__browser_evaluate` to fetch the XMind content API, walk the topic tree, and produce Mermaid output — all in a single call. Substitute the actual `fileId` into the fetch URL string before running. + +```js +async () => { + const FILE_ID = 'PKjJEIHD'; // ← replace with actual fileId + + const res = await fetch(`/api/drive/share/${FILE_ID}/content`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({}) + }); + + if (!res.ok) return `ERROR: API returned ${res.status}`; + + const data = await res.json(); + const sheet = data[0]; + const mapTitle = sheet.title ?? 'Mind Map'; + const root = sheet.rootTopic; + + const lines = ['flowchart LR']; + let counter = 0; + + function sanitize(title) { + return (title ?? '').replace(/"/g, "'").replace(/\n/g, ' ').trim(); + } + + function walk(topic, parentId) { + const id = 'n' + counter++; + const label = sanitize(topic.title); + if (parentId === null) { + lines.push(` ${id}(["${label}"])`); + } else { + lines.push(` ${parentId} --> ${id}["${label}"]`); + } + if (topic.children?.attached) { + for (const child of topic.children.attached) { + walk(child, id); + } + } + } + + walk(root, null); + return JSON.stringify({ title: mapTitle, mermaid: lines.join('\n') }); +} +``` + +The function returns a JSON string with two fields: +- `title` — the mind map name (use this as the markdown heading) +- `mermaid` — the full `flowchart LR` source + +### Step 5 — Write or print output + +Parse the JSON string returned by Step 4, then: + +**If an output path was given**, write a markdown file using the `Write` tool with this structure: + +``` +# {title from Step 4} + +```mermaid +{mermaid from Step 4} +` `` +``` + +*(Note: close the fence with three backticks — the above uses a space before the last ` `` ` only to avoid nesting issues in this document.)* + +**If no output path was given**, print the mermaid source in the conversation inside a `mermaid` code fence. + +--- + +## Error Handling + +| Situation | Action | +|-----------|--------| +| API returns non-200 (e.g., 401, 403) | The map is private or requires login. Inform the user — public share links work without auth, private ones do not. | +| `rootTopic` is missing | The XMind API format may have changed. Print the raw API response so the user can inspect it. | +| Playwright tools unavailable | Inform the user that this skill requires the Playwright MCP plugin to be installed. `WebFetch` cannot load XMind's SPA content. | +| `title` field missing in response | Fall back to the browser page title (available via `browser_evaluate`: `() => document.title`). | + +--- + +## Notes + +- **Auth**: Public share links work without login. The browser session cookie from Step 2 is what grants access to the content API. +- **Layout**: `flowchart LR` is a horizontal left-to-right tree. XMind's balanced layout (branches on both sides) cannot be reproduced in Mermaid — all branches appear on the right. +- **Folded nodes**: XMind `"branch": "folded"` is purely visual. All children are present in the JSON and will appear in the output. +- **`fileId` substitution**: Always replace the `FILE_ID` constant in the evaluate script with the actual ID from the URL before running — do not leave it as `'PKjJEIHD'` which is the example from this skill's documentation. diff --git a/.gitignore b/.gitignore index cc4fa1d..a208825 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,9 @@ htmlcov/ # Generated assets (PNG files generated from SVG) assets/logo/*.png !assets/logo/social-preview.png + +# Playwright MCP working directory (browser snapshots, console logs, temp files) +.playwright-mcp/ + +# Qodo code review bot working directory +.qodo/ diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index eda2312..c9cf2f0 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -47,7 +47,8 @@ Evaluation results must be fair and reproducible. ### VI. English-First - Code, comments, docstrings, commit messages, and variable/function names are always written in English -- Traditional Chinese is permitted in `docs/`, `specs/`, `design/prototype/`, and `design/wireframes/` directories to accelerate research documentation and UI iteration +- Traditional Chinese is permitted in `docs/`, `specs/`, `design/prototype/`, `design/wireframes/`, and `design/system/inventory.md` to accelerate research documentation and UI iteration +- `design/system/MASTER.md` must be written in English only — it is consumed by AI agents and requires accurate token parsing - The only fully Chinese file outside those directories is `README.zh-TW.md` ## Governance diff --git a/.specify/templates/agent-file-template.md b/.specify/templates/agent-file-template.md index dc4501a..c5ea4d1 100644 --- a/.specify/templates/agent-file-template.md +++ b/.specify/templates/agent-file-template.md @@ -25,7 +25,7 @@ Auto-generated from feature plans. Last updated: [DATE] - **KISS & YAGNI**: Pursue extreme simplicity. Reject over-engineering; write code only for current, clearly defined needs. - **Config-Driven**: Task types and evaluation metrics are defined in YAML/JSON config — never hardcoded. - **Security First (NON-NEGOTIABLE)**: Test-set answers must never be exposed to annotators or included in any annotator-facing API response. -- **English-First**: Code, comments, and commit messages are written in English. Traditional Chinese is permitted in `docs/`, `specs/`, `design/prototype/`, and `design/wireframes/`. +- **English-First**: Code, comments, and commit messages are written in English. Traditional Chinese is permitted in `docs/`, `specs/`, `design/prototype/`, `design/wireframes/`, and `design/system/inventory.md`. `design/system/MASTER.md` must be English only. ## Protected Files diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 586ab8a..1fb272f 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -24,7 +24,7 @@ - [ ] III. Data Fairness: Does this involve test sets? If so, leakage prevention is planned - [ ] IV. Test-First: Test plan is listed - [ ] V. Simplicity: Any signs of over-engineering? -- [ ] VI. English-First: Code, comments, and commit messages in English; Traditional Chinese allowed in `docs/`, `specs/`, `design/prototype/`, and `design/wireframes/` +- [ ] VI. English-First: Code, comments, and commit messages in English; Traditional Chinese allowed in `docs/`, `specs/`, `design/prototype/`, `design/wireframes/`, and `design/system/inventory.md`; `design/system/MASTER.md` must be English only ## Project Structure diff --git a/CLAUDE.md b/CLAUDE.md index 3e9ae13..18f4d4b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -115,6 +115,9 @@ label-suite/ - `specs/` — all SDD spec files (`spec.md`, `plan.md`, `tasks.md`, `checklists/`) - `design/prototype/` — HTML/CSS UI prototypes demonstrating bilingual (zh-TW/en) features - `design/wireframes/` — Pencil wireframe files (`.pen`) demonstrating bilingual (zh-TW/en) UI designs + - `design/system/inventory.md` — component inventory tracking document +- **English only** (exceptions within otherwise Chinese-allowed directories): + - `design/system/MASTER.md` — consumed by AI agents (`ui-ux-pro-max`, Claude Code); must be in English for accurate token parsing - `README.zh-TW.md` is maintained in Traditional Chinese for Chinese-speaking users. - All conversations with Claude should be responded to in Traditional Chinese. diff --git a/design/prototype/pages/profile.html b/design/prototype/pages/profile.html index f6db0b6..605c1f3 100644 --- a/design/prototype/pages/profile.html +++ b/design/prototype/pages/profile.html @@ -63,7 +63,7 @@ -