@fifine/aim-studio 0.0.1

package/dist/templates/claude/commands/aim/update-spec.md

@@ -0,0 +1,285 @@
+# Update Spec - Capture Knowledge into Specifications
+
+When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant spec documents.
+
+**Timing**: After completing a task, fixing a bug, or discovering a new pattern
+
+---
+
+## When to Update Specs
+
+| Trigger | Example | Target Spec |
+|---------|---------|-------------|
+| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file |
+| **Made a design decision** | Used type field + mapping table for extensibility | Relevant spec + "Design Decisions" section |
+| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` |
+| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file |
+| **Hit a gotcha** | Learned that X must be done before Y | Relevant spec + "Common Mistakes" section |
+| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` |
+| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) |
+
+**Key Insight**: Spec updates are NOT just for problems. Every feature implementation contains design decisions and project conventions that future AI/developers need to know.
+
+---
+
+## Spec Structure Overview
+
+```
+.aim-studio/spec/
+├── backend/           # Backend coding standards
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+├── frontend/          # Frontend coding standards
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+└── guides/            # Thinking checklists (NOT coding specs!)
+    ├── index.md       # Guide index
+    └── *.md           # Topic-specific guides
+```
+
+### CRITICAL: Spec vs Guide - Know the Difference
+
+| Type | Location | Purpose | Content Style |
+|------|----------|---------|---------------|
+| **Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to write code" | Detailed rules, code examples, forbidden patterns |
+| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
+
+**Decision Rule**: Ask yourself:
+
+- "This is **how to write** the code" → Put in `backend/` or `frontend/`
+- "This is **what to consider** before writing" → Put in `guides/`
+
+**Example**:
+
+| Learning | Wrong Location | Correct Location |
+|----------|----------------|------------------|
+| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | ❌ `guides/cross-platform-thinking-guide.md` | ✅ `backend/script-conventions.md` |
+| "Remember to check encoding when writing cross-platform code" | ❌ `backend/script-conventions.md` | ✅ `guides/cross-platform-thinking-guide.md` |
+
+**Guides should be short checklists that point to specs**, not duplicate the detailed rules.
+
+---
+
+## Update Process
+
+### Step 1: Identify What You Learned
+
+Answer these questions:
+
+1. **What did you learn?** (Be specific)
+2. **Why is it important?** (What problem does it prevent?)
+3. **Where does it belong?** (Which spec file?)
+
+### Step 2: Classify the Update Type
+
+| Type | Description | Action |
+|------|-------------|--------|
+| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
+| **Project Convention** | How we do X in this project | Add to relevant section with examples |
+| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
+| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
+| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
+| **Convention** | Agreed-upon standard | Add to relevant section |
+| **Gotcha** | Non-obvious behavior | Add warning callout |
+
+### Step 3: Read the Target Spec
+
+Before editing, read the current spec to:
+- Understand existing structure
+- Avoid duplicating content
+- Find the right section for your update
+
+```bash
+cat .aim-studio/spec/<category>/<file>.md
+```
+
+### Step 4: Make the Update
+
+Follow these principles:
+
+1. **Be Specific**: Include concrete examples, not just abstract rules
+2. **Explain Why**: State the problem this prevents
+3. **Show Code**: Add code snippets for patterns
+4. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the spec status changed, update the category's `index.md`.
+
+---
+
+## Update Templates
+
+### Adding a Design Decision
+
+```markdown
+### Design Decision: [Decision Name]
+
+**Context**: What problem were we solving?
+
+**Options Considered**:
+1. Option A - brief description
+2. Option B - brief description
+
+**Decision**: We chose Option X because...
+
+**Example**:
+\`\`\`typescript
+// How it's implemented
+code example
+\`\`\`
+
+**Extensibility**: How to extend this in the future...
+```
+
+### Adding a Project Convention
+
+```markdown
+### Convention: [Convention Name]
+
+**What**: Brief description of the convention.
+
+**Why**: Why we do it this way in this project.
+
+**Example**:
+\`\`\`typescript
+// How to follow this convention
+code example
+\`\`\`
+
+**Related**: Links to related conventions or specs.
+```
+
+### Adding a New Pattern
+
+```markdown
+### Pattern Name
+
+**Problem**: What problem does this solve?
+
+**Solution**: Brief description of the approach.
+
+**Example**:
+\`\`\`
+// Good
+code example
+
+// Bad
+code example
+\`\`\`
+
+**Why**: Explanation of why this works better.
+```
+
+### Adding a Forbidden Pattern
+
+```markdown
+### Don't: Pattern Name
+
+**Problem**:
+\`\`\`
+// Don't do this
+bad code example
+\`\`\`
+
+**Why it's bad**: Explanation of the issue.
+
+**Instead**:
+\`\`\`
+// Do this instead
+good code example
+\`\`\`
+```
+
+### Adding a Common Mistake
+
+```markdown
+### Common Mistake: Description
+
+**Symptom**: What goes wrong
+
+**Cause**: Why this happens
+
+**Fix**: How to correct it
+
+**Prevention**: How to avoid it in the future
+```
+
+### Adding a Gotcha
+
+```markdown
+> **Warning**: Brief description of the non-obvious behavior.
+>
+> Details about when this happens and how to handle it.
+```
+
+---
+
+## Interactive Mode
+
+If you're unsure what to update, answer these prompts:
+
+1. **What did you just finish?**
+   - [ ] Fixed a bug
+   - [ ] Implemented a feature
+   - [ ] Refactored code
+   - [ ] Had a discussion about approach
+
+2. **What did you learn or decide?**
+   - Design decision (why X over Y)
+   - Project convention (how we do X)
+   - Non-obvious behavior (gotcha)
+   - Better approach (pattern)
+
+3. **Would future AI/developers need to know this?**
+   - To understand how the code works → Yes, update spec
+   - To maintain or extend the feature → Yes, update spec
+   - To avoid repeating mistakes → Yes, update spec
+   - Purely one-off implementation detail → Maybe skip
+
+4. **Which area does it relate to?**
+   - [ ] Backend code
+   - [ ] Frontend code
+   - [ ] Cross-layer data flow
+   - [ ] Code organization/reuse
+   - [ ] Quality/testing
+
+---
+
+## Quality Checklist
+
+Before finishing your spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Is it in the right spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Learn something → /aim:update-spec → Knowledge captured
+       ↑                                  ↓
+  /aim:break-loop ←──────────────────── Future sessions benefit
+  (deep bug analysis)
+```
+
+- `/aim:break-loop` - Analyzes bugs deeply, often reveals spec updates needed
+- `/aim:update-spec` - Actually makes the updates (this command)
+- `/aim:finish-work` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the spec better.**
+
+The goal is **institutional memory**:
+- What one person learns, everyone benefits from
+- What AI learns in one session, persists to future sessions
+- Mistakes become documented guardrails

package/dist/templates/claude/commands/aim/visualize.md

@@ -0,0 +1,182 @@
+---
+name: visualize
+description: 生成场景图片提示词（Qwen-Image优化）
+---
+
+# 场景图片生成
+
+将当前剧本段落转换为 AI 绘画提示词，针对 Qwen-Image 优化。
+
+## Qwen-Image 核心优势
+
+| 能力维度 | 技术特点 | 优势 |
+|---------|---------|------|
+| **复杂文本渲染** | 中英文多行文本、段落级语义 | 中文渲染 58.30%，远超竞品 |
+| **精准图像编辑** | 语义一致性与视觉保真度 | 支持链式编辑 |
+| **空间关系** | MSRoPE 位置编码 | 精确布局控制 |
+
+---
+
+## Prompt 结构原则
+
+Qwen-Image 使用 **Qwen2.5-VL 作为文本编码器**，最优 Prompt 应包含：
+
+```
+【主体对象】+ 【属性细节（颜色/数量/形状/材质）】+ 【空间关系】+ 【文本内容（如需要）】+ 【环境背景】+ 【风格/光影】
+```
+
+---
+
+## 执行步骤
+
+### 1. 生成提示词
+
+直接读取当前选中的剧本段落，将其转换为 Qwen-Image 优化的提示词。
+
+### 2. 输出格式
+
+每个场次生成以下格式的提示词：
+
+```markdown
+## 场次 X 图片提示词
+
+### 主体描述
+[主体对象]，[颜色]，[数量]，[形状]，[材质]
+
+### 属性细节
+- 面部特征：[脸型、眼睛、眉毛、发型等]
+- 服装：[颜色、材质、款式]
+- 配饰：[如有]
+
+### 空间关系
+[主体在画面中的位置]，[与其他物体的距离]，[前景/背景关系]
+
+### 文本内容（如需要）
+- 文字内容："需要渲染的文字"
+- 文字位置：[左上角/中央/底部等]
+- 字体样式：[手写体/宋体/霓虹灯管字体等]
+
+### 环境背景
+[场景描述]，[时间]，[天气]，[氛围]
+
+### 风格光影
+[整体风格]，[色调]，[光源方向]，[参考作品]
+
+### 完整英文提示词
+```
+{Subject}, {Appearance details}, {Clothing}, {Position}, 
+{Environment}, {Lighting}, {Style}, {Quality tags}
+```
+
+### 负面提示词
+```
+ugly, deformed, bad anatomy, extra limbs, blurry, low quality, 
+western style (if Chinese style needed), modern clothing (if period piece)
+```
+```
+
+---
+
+## 中文场景特化技巧
+
+### 1. 直接使用中文字符
+
+```
+✅ "招牌上写着'云计算'"
+❌ "sign with Chinese characters meaning cloud computing"
+```
+
+### 2. 利用成语、诗句、对联
+
+```
+一首古诗书法作品，内容为：
+"毕竟西湖六月中，风光不与四时同。
+接天莲叶无穷碧，映日荷花别样红。"
+字体为楷书，背景是水墨画风格的西湖景色。
+```
+
+### 3. 复杂排版布局
+
+```
+一张信息图表，标题为"情绪健康习惯"，周围环绕六个模块：
+左上："练习正念" - 莲花图标
+右上："持续学习" - 书本图标
+左中："培养感恩" - 双手图标
+右中："定期运动" - 跑步图标
+左下："保持联结" - 对话图标
+右下："优先睡眠" - 月亮图标
+整体为优雅的信息图风格，对称布局。
+```
+
+---
+
+## 避坑指南
+
+| ❌ 避免 | ✅ 替代 |
+|--------|--------|
+| "高质量"、"精美" 等空泛词 | 具体描述材质、光影、分辨率要求 |
+| 模糊的文本描述 | 用引号明确标注每个文字 |
+| 忽略空间位置词 | 使用"左上角"、"中央"、"底部"等明确位置 |
+| 过长的无结构句子 | 分段描述不同元素，使用分号或换行 |
+| 假设模型懂特定IP或风格 | 详细描述视觉特征 |
+
+---
+
+## 示例
+
+### 输入剧本
+
+```
+场次 1：青云峰主殿内 - 清晨 - 萧条落寞
+
+白衣中年沈安在瘫坐在太师椅上，神情苦涩。殿外，少年慕容天背着大包小包，站在门口。
+```
+
+### 输出提示词
+
+```markdown
+## 场次 1 图片提示词
+
+### 主体描述
+- 人物1：沈安在，白衣中年男子，两鬓霜白，面容俊俏，神情苦涩
+- 人物2：慕容天，少年身形，背着大包小包
+
+### 属性细节
+- 沈安在服装：白色道袍，材质为丝绸，款式宽松
+- 慕容天服装：青色布衣，背着布包裹
+- 场景道具：太师椅（深棕色木质）、残破窗棂
+
+### 空间关系
+沈安在位于画面中央偏左，瘫坐在太师椅上；慕容天位于画面右侧门口处，两人之间有一定距离
+
+### 环境背景
+青云峰主殿内部，破旧的大殿，阳光透过残破窗棂洒落，萧条冷清的氛围，清晨光线
+
+### 风格光影
+中国仙侠风格，水墨画质感，柔和晨光从左侧打入，产生柔和阴影，色调偏冷
+
+### 完整英文提示词
+```
+A middle-aged Chinese man in white Taoist robe, sitting slumped on a wooden chair, 
+bitter expression, white hair at temples, handsome face. 
+In the background, a young man in blue clothes standing at the doorway, carrying large cloth bundles.
+Dilapidated temple interior, morning sunlight through broken windows, 
+melancholic atmosphere, Chinese xianxia style, ink painting texture, 
+soft lighting from left, cool color tone, cinematic composition
+```
+
+### 负面提示词
+```
+ugly, deformed, bad anatomy, extra limbs, blurry, low quality, 
+modern clothing, western style, bright colors, happy expression
+```
+```
+
+---
+
+## 注意事项
+
+1. **文本渲染**：如需要在图片中渲染文字，必须用引号明确标注
+2. **中文优化**：Qwen-Image 对中文渲染有独特优势，直接使用汉字
+3. **空间布局**：使用明确的位置词（左上角、中央、底部等）
+4. **结构化描述**：分段描述不同元素，避免过长的无结构句子

package/dist/templates/claude/commands/trellis/before-backend-dev.md

@@ -0,0 +1,13 @@
+Read the backend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/backend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Database work → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging → `.trellis/spec/backend/logging-guidelines.md`
+   - Type questions → `.trellis/spec/backend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any backend code.

package/dist/templates/claude/commands/trellis/before-frontend-dev.md

@@ -0,0 +1,13 @@
+Read the frontend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/frontend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Component work → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook work → `.trellis/spec/frontend/hook-guidelines.md`
+   - State management → `.trellis/spec/frontend/state-management.md`
+   - Type questions → `.trellis/spec/frontend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any frontend code.

package/dist/templates/claude/commands/trellis/break-loop.md

@@ -0,0 +1,125 @@
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+
+---
+
+## Analysis Framework
+
+Analyze the bug you just fixed from these 5 dimensions:
+
+### 1. Root Cause Category
+
+Which category does this bug belong to?
+
+| Category | Characteristics | Example |
+|----------|-----------------|---------|
+| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
+| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
+| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
+| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
+| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
+
+### 2. Why Fixes Failed (if applicable)
+
+If you tried multiple fixes before succeeding, analyze each failure:
+
+- **Surface Fix**: Fixed symptom, not root cause
+- **Incomplete Scope**: Found root cause, didn't cover all cases
+- **Tool Limitation**: grep missed it, type check wasn't strict
+- **Mental Model**: Kept looking in same layer, didn't think cross-layer
+
+### 3. Prevention Mechanisms
+
+What mechanisms would prevent this from happening again?
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Documentation** | Write it down so people know | Update thinking guide |
+| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
+| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
+| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
+| **Test Coverage** | E2E tests, integration tests | Verify full flow |
+| **Code Review** | Checklist, PR template | "Did you check X?" |
+
+### 4. Systematic Expansion
+
+What broader problems does this bug reveal?
+
+- **Similar Issues**: Where else might this problem exist?
+- **Design Flaw**: Is there a fundamental architecture issue?
+- **Process Flaw**: Is there a development process improvement?
+- **Knowledge Gap**: Is the team missing some understanding?
+
+### 5. Knowledge Capture
+
+Solidify insights into the system:
+
+- [ ] Update `.trellis/spec/guides/` thinking guides
+- [ ] Update `.trellis/spec/backend/` or `frontend/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update check commands if needed
+
+---
+
+## Output Format
+
+Please output analysis in this format:
+
+```markdown
+## Bug Analysis: [Short Description]
+
+### 1. Root Cause Category
+- **Category**: [A/B/C/D/E] - [Category Name]
+- **Specific Cause**: [Detailed description]
+
+### 2. Why Fixes Failed (if applicable)
+1. [First attempt]: [Why it failed]
+2. [Second attempt]: [Why it failed]
+...
+
+### 3. Prevention Mechanisms
+| Priority | Mechanism | Specific Action | Status |
+|----------|-----------|-----------------|--------|
+| P0 | ... | ... | TODO/DONE |
+
+### 4. Systematic Expansion
+- **Similar Issues**: [List places with similar problems]
+- **Design Improvement**: [Architecture-level suggestions]
+- **Process Improvement**: [Development process suggestions]
+
+### 5. Knowledge Capture
+- [ ] [Documents to update / tickets to create]
+```
+
+---
+
+## Core Philosophy
+
+> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
+
+Three levels of insight:
+1. **Tactical**: How to fix THIS bug
+2. **Strategic**: How to prevent THIS CLASS of bugs
+3. **Philosophical**: How to expand thinking patterns
+
+30 minutes of analysis saves 30 hours of future debugging.
+
+---
+
+## After Analysis: Immediate Actions
+
+**IMPORTANT**: After completing the analysis above, you MUST immediately:
+
+1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
+   - If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
+   - If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
+   - If it's a code reuse issue → update `code-reuse-thinking-guide.md`
+   - If it's domain-specific → update `backend/*.md` or `frontend/*.md`
+
+2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
+
+3. **Commit the spec updates** - This is the primary output, not just the analysis text
+
+> **The analysis is worthless if it stays in chat. The value is in the updated specs.**

package/dist/templates/claude/commands/trellis/check-backend.md

@@ -0,0 +1,13 @@
+Check if the code you just wrote follows the backend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/backend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Database changes → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging changes → `.trellis/spec/backend/logging-guidelines.md`
+   - Type changes → `.trellis/spec/backend/type-safety.md`
+   - Any changes → `.trellis/spec/backend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found