@flydocs/cli 0.5.0-beta.0

package/template/.flydocs/templates/bug.md

@@ -0,0 +1,166 @@
+<!-- AGENT INSTRUCTIONS
+When creating or refining a bug issue:
+
+1. CONTEXT SECTION:
+   - Capture when/how the bug was discovered
+   - Assess user impact (how many affected, how severe)
+   - Note frequency (always, sometimes, specific conditions)
+
+2. BUG DESCRIPTION:
+   - Expected vs Actual must be crystal clear
+   - Steps to reproduce must be detailed enough for anyone to follow
+   - Include specific data conditions if relevant
+   - Note environment details (browser, OS, user role)
+
+3. ACCEPTANCE CRITERIA:
+   - "Fix Verification" should mirror the reproduction steps
+   - Include regression concerns (what else might break)
+   - Tests section should include regression test requirement
+
+4. TECHNICAL NOTES:
+   - Start with hypothesis if cause unknown
+   - Update "Confirmed Cause" after investigation
+   - Include specific file/function where bug exists
+   - Assess risk of the fix
+
+5. SEVERITY GUIDANCE:
+   - Critical: System unusable, data loss, security issue
+   - High: Major feature broken, no workaround
+   - Medium: Feature impaired but workaround exists
+   - Low: Minor issue, cosmetic, edge case
+
+Remove these instructions when creating the final issue.
+-->
+
+## Context
+
+**When Discovered:** [Date or event when bug was found]
+**Discovered By:** [User, developer, automated test, etc.]
+**Impact:** [How this affects users - be specific about scope]
+**Frequency:** [Always | Sometimes | Rarely | Under specific conditions]
+
+[Additional context about the bug]
+
+---
+
+## Bug Description
+
+### Expected Behavior
+[Describe what SHOULD happen - the correct behavior]
+
+### Actual Behavior
+[Describe what ACTUALLY happens - the broken behavior]
+
+### Steps to Reproduce
+1. [First action - be specific]
+2. [Second action - include any data/conditions needed]
+3. [Third action]
+4. [Observe the bug]
+
+### Environment
+- **Browser/Platform:** [Chrome, Safari, Mobile, etc.]
+- **OS:** [macOS, Windows, iOS, Android, etc.]
+- **User Role:** [Which user type experiences this]
+- **Data Conditions:** [Specific data state that triggers bug]
+
+### Screenshots/Evidence
+<!-- Add as attachments -->
+
+---
+
+## Acceptance Criteria
+
+### Fix Verification
+- [ ] Bug no longer reproducible using original steps
+- [ ] Expected behavior now works correctly
+- [ ] Fix doesn't break related functionality
+- [ ] No new error messages or console errors
+
+### Tests
+- [ ] Regression test added to prevent recurrence
+- [ ] Related edge cases tested
+- [ ] All tests passing
+
+### Documentation
+- [ ] Root cause documented (if significant pattern)
+- [ ] Prevention notes added to knowledge base (if applicable)
+- [ ] N/A - No significant documentation needed
+
+---
+
+## Technical Notes
+
+### Root Cause Analysis
+**Hypothesis:** [What you think is causing the bug]
+
+**Investigation Findings:**
+- [Finding 1 from debugging]
+- [Finding 2 from debugging]
+
+**Confirmed Cause:** [What's actually wrong - file, function, logic error]
+
+### Fix Approach
+[Describe the fix strategy - what needs to change]
+
+**Files to Modify:**
+- `path/to/file.tsx` - [What needs to change]
+
+**Risk Assessment:**
+- **Regression Risk:** Low | Medium | High
+- **Testing Required:** [What needs to be tested]
+
+---
+
+## Dependencies
+
+**Related Systems:**
+- [System or feature where bug occurs]
+
+**Blocks:**
+- [Work that can't proceed until bug is fixed]
+- OR: Nothing blocked
+
+**Related Bugs:**
+- [Link to related bug if applicable]
+- OR: No related issues
+
+---
+
+## AI Effort Estimate
+<!-- 
+AGENT: Fill this section during /refine using the flydocs-estimates skill.
+See .claude/skills/flydocs-estimates/SKILL.md for calculation details.
+Update Actuals section during /close for calibration.
+-->
+
+### Sizing Factors
+
+| Factor | Value | Multiplier |
+|--------|-------|------------|
+| **Task Type** | bug | base: 20k |
+| **Scope** | [S/M/L/XL] | ×[0.5/1.0/2.0/4.0] |
+| **Novelty** | [existing/partial/greenfield] | ×[0.7/1.2/2.0] |
+| **Clarity** | [defined/discovery/exploratory] | ×[0.8/1.5/2.5] |
+| **Codebase** | [simple/moderate/complex] | ×[0.8/1.0/1.5] |
+
+### Estimate
+
+**Provider**: [Claude Sonnet 4]  
+**Calculated Tokens**: ~[X]k  
+**Confidence**: ±[40-60]%  
+**Token Range**: [low]k - [high]k  
+**Cost Range**: $[low] - $[high]
+
+### Actuals (fill on /close)
+**Actual Tokens**: [fill after completion]  
+**Variance**: [+/-X]% [under/over estimate]  
+**Notes**: [what drove variance - investigation time, fix complexity, retries]
+
+---
+
+_Reported: YYYY-MM-DD_
+
+
+
+
+

package/template/.flydocs/templates/chore.md

@@ -0,0 +1,110 @@
+<!-- AGENT INSTRUCTIONS
+When creating or refining a chore issue:
+
+1. CONTEXT SECTION:
+   - Explain the value (cleaner code, better UX, faster performance)
+   - Be specific about scope to prevent scope creep
+   - Mark as "Ongoing" if this is iterative work
+
+2. TASK LIST:
+   - Be specific and actionable
+   - Add tasks as you discover them during work
+   - Move tasks to "Out of Scope" if they're too big
+   - Tasks should be completable in one session
+
+3. ACCEPTANCE CRITERIA:
+   - Focus on completion and quality
+   - Mark documentation as N/A if no new patterns
+   - Mark tests as N/A if no behavior changes
+
+4. COMPLETION CRITERIA:
+   - "Done when" should be clear stopping point
+   - If scope keeps growing, suggest splitting into multiple chores
+
+5. WORKFLOW:
+   - Chores often skip formal review/QA
+   - Use simplified flow: Backlog → In Progress → Done
+   - Use full flow only for significant refactors
+
+Remove these instructions when creating the final issue.
+-->
+
+## Context
+
+**Why This Matters:**
+[Explanation of the value - cleaner code, better UX, faster performance, etc.]
+
+**Scope:**
+[What areas/pages/features does this touch? Be specific enough to stay focused.]
+
+**Type:** Ongoing | One-time
+
+---
+
+## Task List
+
+### Initial Tasks
+- [ ] [Task 1 - be specific]
+- [ ] [Task 2 - be specific]
+- [ ] [Task 3 - be specific]
+
+### Added During Work
+<!-- Add new tasks discovered while working -->
+
+### Out of Scope
+<!-- Tasks that don't fit - might become new issues -->
+- [Task that's too big or different focus]
+
+---
+
+## Acceptance Criteria
+
+### Completion
+- [ ] All initial tasks completed (or moved to out of scope)
+- [ ] Code quality acceptable
+- [ ] No regressions introduced
+
+### Tests
+- [ ] Tests updated if behavior changed
+- [ ] All tests passing
+- [ ] N/A - No behavior changes
+
+### Documentation
+- [ ] Patterns documented (if new approach discovered)
+- [ ] N/A - No significant documentation needed
+
+---
+
+## Technical Notes
+
+### Approach
+[How you'll tackle this work]
+
+### Files to Touch
+- `path/to/file.tsx` - [What changes]
+
+### Risk Assessment
+- **Regression Risk:** Low | Medium | High
+- **Related Areas:** [What else might be affected]
+
+---
+
+## Completion Criteria
+
+**This chore is done when:**
+- [ ] [Completion criterion 1]
+- [ ] [Completion criterion 2]
+- [ ] No obvious improvements remaining in scope
+
+**Signs this needs to be split:**
+- Work has been ongoing for 3+ weeks
+- Scope has grown significantly
+- New tasks are unrelated to original purpose
+
+---
+
+_Created: YYYY-MM-DD_
+
+
+
+

package/template/.flydocs/templates/design-system/README.md

@@ -0,0 +1,27 @@
+# Design System Templates
+
+These templates are used when initializing a design system for your project.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `token-mapping.md` | Maps Figma values to project tokens |
+| `component-patterns.md` | Documents reusable components |
+
+## Usage
+
+When you run `/design-setup` and enable a design system:
+
+1. These templates are copied to `flydocs/design-system/` (your project content directory)
+2. Token mapping is populated from Figma (if file key provided)
+3. Component patterns are filled based on existing codebase
+
+## Customization
+
+After initialization, customize these files for your project:
+- Add project-specific tokens
+- Document your component library
+- Add usage examples
+
+

package/template/.flydocs/templates/design-system/component-patterns.md

@@ -0,0 +1,92 @@
+# Component Patterns
+
+Document your project's reusable components and patterns.
+
+> **Instructions:** Fill this file with your existing components.
+> Reference these before creating new components.
+
+---
+
+## Available Components
+
+### Buttons
+
+| Component | Import | Usage |
+|-----------|--------|-------|
+| `Button` | `@/components/buttons/Button` | Primary, secondary, ghost variants |
+| | | |
+
+#### Button Usage
+
+```tsx
+import { Button } from '@/components/buttons'
+
+// Primary (default)
+<Button variant="primary" size="md">Get started</Button>
+
+// Secondary
+<Button variant="secondary" size="md">Learn more</Button>
+
+// Full width
+<Button variant="primary" className="w-full">Submit</Button>
+```
+
+---
+
+### Cards
+
+| Component | Import | Usage |
+|-----------|--------|-------|
+| | | |
+
+---
+
+### Forms
+
+| Component | Import | Usage |
+|-----------|--------|-------|
+| | | |
+
+---
+
+### Navigation
+
+| Component | Import | Usage |
+|-----------|--------|-------|
+| | | |
+
+---
+
+### Sections
+
+| Component | Import | Usage |
+|-----------|--------|-------|
+| | | |
+
+---
+
+## Component Rules
+
+### DO
+- Use existing components before creating new ones
+- Extend existing components via props/className
+- Follow established patterns
+
+### DON'T
+- Write inline button styles when Button exists
+- Duplicate component code
+- Create new components without checking existing ones
+
+---
+
+## Red Flags
+
+```tsx
+// ❌ Inline button styling when Button component exists
+<button className="bg-blue-600 text-white px-4 py-2 rounded-md">
+
+// ✅ Use the Button component
+<Button variant="primary">Submit</Button>
+```
+
+

package/template/.flydocs/templates/design-system/token-mapping.md

@@ -0,0 +1,168 @@
+# Token Mapping (Figma → Project)
+
+Translate Figma values to project design tokens.
+
+> **Instructions:** Fill this file with your project's token mappings.
+> Run `/extract-tokens` with a Figma design system file to auto-populate.
+
+---
+
+## Quick Reference: Hex → Token
+
+| Hex | Token | Class |
+|-----|-------|-------|
+| | | |
+
+---
+
+## Colors
+
+### Background Colors
+
+| Figma Variable | Hex | Tailwind Class |
+|----------------|-----|----------------|
+| | | |
+
+### Text Colors
+
+| Figma Variable | Hex | Tailwind Class |
+|----------------|-----|----------------|
+| | | |
+
+### Border Colors
+
+| Figma Variable | Hex | Tailwind Class |
+|----------------|-----|----------------|
+| | | |
+
+### Brand Colors
+
+| Figma Variable | Hex | Tailwind Class |
+|----------------|-----|----------------|
+| | | |
+
+---
+
+## Typography
+
+### Font Families
+
+| Figma Font | Tailwind Class |
+|------------|----------------|
+| | |
+
+### Font Sizes
+
+| Figma Size | Tailwind Class | Line Height |
+|------------|----------------|-------------|
+| | | |
+
+### Font Weights
+
+| Figma Weight | Tailwind Class |
+|--------------|----------------|
+| 400 / Regular | `font-normal` |
+| 500 / Medium | `font-medium` |
+| 600 / SemiBold | `font-semibold` |
+| 700 / Bold | `font-bold` |
+
+### Common Typography Patterns
+
+| Use Case | Classes |
+|----------|---------|
+| Display heading | |
+| Section heading | |
+| Body text | |
+| Button text | |
+| Small text | |
+
+---
+
+## Spacing
+
+| Figma (px) | Token | Class Examples |
+|------------|-------|----------------|
+| 4px | | `p-1`, `gap-1` |
+| 8px | | `p-2`, `gap-2` |
+| 12px | | `p-3`, `gap-3` |
+| 16px | | `p-4`, `gap-4` |
+| 20px | | `p-5`, `gap-5` |
+| 24px | | `p-6`, `gap-6` |
+| 32px | | `p-8`, `gap-8` |
+| 40px | | `p-10`, `gap-10` |
+| 48px | | `p-12`, `gap-12` |
+| 64px | | `p-16`, `gap-16` |
+
+### Values Without Tokens
+
+| Figma (px) | Use Arbitrary Value |
+|------------|---------------------|
+| 18px | `px-[18px]` |
+| | |
+
+---
+
+## Border Radius
+
+| Figma (px) | Token | Tailwind Class |
+|------------|-------|----------------|
+| 4px | | `rounded-sm` |
+| 6px | | `rounded-md` |
+| 8px | | `rounded-lg` |
+| 12px | | `rounded-xl` |
+| 16px | | `rounded-2xl` |
+| 9999px | | `rounded-full` |
+
+---
+
+## Shadows
+
+| Figma Shadow | Tailwind Class |
+|--------------|----------------|
+| | |
+
+---
+
+## Figma Property → Tailwind Translation
+
+### Layout Properties
+
+| Figma Property | Value | Tailwind |
+|----------------|-------|----------|
+| `layoutMode` | `"VERTICAL"` | `flex flex-col` |
+| `layoutMode` | `"HORIZONTAL"` | `flex flex-row` |
+| `primaryAxisAlignItems` | `"MIN"` | `justify-start` |
+| `primaryAxisAlignItems` | `"CENTER"` | `justify-center` |
+| `primaryAxisAlignItems` | `"MAX"` | `justify-end` |
+| `primaryAxisAlignItems` | `"SPACE_BETWEEN"` | `justify-between` |
+| `counterAxisAlignItems` | `"MIN"` | `items-start` |
+| `counterAxisAlignItems` | `"CENTER"` | `items-center` |
+| `counterAxisAlignItems` | `"MAX"` | `items-end` |
+
+### Sizing Properties
+
+| Figma Property | Value | Tailwind |
+|----------------|-------|----------|
+| `layoutSizingHorizontal` | `"FIXED"` | `w-[Xpx]` |
+| `layoutSizingHorizontal` | `"FILL"` | `w-full` |
+| `layoutSizingHorizontal` | `"HUG"` | `w-fit` |
+| `layoutSizingVertical` | `"FIXED"` | `h-[Xpx]` |
+| `layoutSizingVertical` | `"FILL"` | `h-full` |
+| `layoutSizingVertical` | `"HUG"` | `h-fit` |
+
+---
+
+## When No Token Exists
+
+If a Figma value doesn't have a project token:
+
+1. **Document it** in your specification table
+2. **Use arbitrary value**: `p-[18px]`, `rounded-[10px]`
+3. **Note for future**: Consider adding token if used frequently
+
+```tsx
+// Documented exception: 18px padding (no token)
+className="px-[18px] py-3"
+```
+
+