@flydocs/cli 0.5.0-beta.0

package/template/flydocs/README.md

@@ -0,0 +1,186 @@
+# FlyDocs Cloud
+
+This project uses FlyDocs Cloud - a hybrid workflow where:
+- **Work items (specs)** live in Linear
+- **Project understanding** lives locally in this directory
+- **Framework config, rules & templates** live in `.flydocs/`
+
+---
+
+## This Directory is Living Documentation
+
+**This `flydocs/` directory is your project's evolving knowledge base.**
+
+It grows alongside your project:
+- Update `context/` as your vision, stack, and standards evolve
+- Add to `knowledge/` as you make decisions and learn things
+- Expand `patterns/` as you discover project-specific conventions
+- Maintain `design-system/` as design tokens change
+
+FlyDocs will **never overwrite** these files during updates - they're yours to maintain.
+
+---
+
+## Directory Structure
+
+```
+.flydocs/                  # FRAMEWORK (replaced on FlyDocs update)
+├── config.json            # Provider settings, workspace config
+├── version                # For upgrade detection
+├── rules/                 # Workflow rules
+├── scripts/               # Automation scripts
+├── hooks/                 # Workflow hooks
+└── templates/             # Issue templates (source)
+
+flydocs/                   # PROJECT CONTENT (evolves with project)
+├── context/               # Project fundamentals
+│   ├── overview.md        # Vision, goals, scope (update as it evolves)
+│   ├── stack.md           # Tech stack, architecture (update as it changes)
+│   ├── standards.md       # Code conventions (update as they mature)
+│   └── patterns/          # Project-specific patterns (grow over time)
+│
+├── design-system/         # Design tokens (if using /design-setup)
+│   ├── token-mapping.md   # Figma → code translations
+│   └── component-patterns.md
+│
+├── knowledge/             # Project knowledge (grows continuously)
+│   ├── INDEX.md           # Knowledge inventory
+│   ├── decisions/         # Architecture Decision Records
+│   ├── features/          # Complex feature documentation
+│   ├── notes/             # Learnings, gotchas, tips
+│   └── product/           # Personas, user flows
+│
+└── README.md              # This file
+
+.cursor/                   # Cursor IDE integration
+├── rules/*.mdc            # Cursor rules (flat .mdc files)
+├── agents/                # Cursor-native agents
+├── commands/              # Workflow commands
+└── hooks.json             # Cursor hooks
+
+.claude/                   # Claude Code integration
+├── agents/                # Subagent definitions
+├── skills/                # Workflow skills
+└── settings.json          # Claude hooks
+│   ├── pm-agent/RULE.md          # Planning triggers
+│   ├── implementation-agent/RULE.md  # Build triggers
+│   ├── qe-agent/RULE.md          # Testing triggers
+│   ├── linear-integration/RULE.md
+│   └── ...
+└── commands/              # Slash commands
+
+.claude/
+├── CLAUDE.md              # Claude Code instructions
+└── commands/              # Symlinks to .cursor/commands/
+```
+
+**Note:** Content folder name is configurable via `paths.content` in `.flydocs/config.json`.
+
+---
+
+## What Lives Where
+
+### LOCAL (This Directory)
+
+| Content | Location | Purpose |
+|---------|----------|---------|
+| Project overview | `context/overview.md` | Vision, goals, scope |
+| Tech stack | `context/stack.md` | Architecture, dependencies |
+| Code standards | `context/standards.md` | Conventions, patterns |
+| ADRs | `knowledge/decisions/` | Why we made choices |
+| Feature docs | `knowledge/features/` | How features work |
+| Notes | `knowledge/notes/` | Learnings, gotchas |
+| Product docs | `knowledge/product/` | Personas, user flows |
+
+**Why local?** Agent needs instant access, changes with code, developers need it in IDE.
+
+### LINEAR (Cloud)
+
+| Content | Linear Location | Purpose |
+|---------|-----------------|---------|
+| Specs | Issues | Features, bugs, chores, ideas |
+| Status | Workflow states | BACKLOG → DONE progression |
+| Priorities | Priority field | Urgent, High, Medium, Low |
+| Assignments | Assignee | Who's working on what |
+| Assets | Attachments | Figma links, screenshots |
+| Progress | Comments | Decision log, impl notes |
+
+**Why cloud?** Team collaboration, stakeholder visibility, AI agent integration.
+
+---
+
+## No Longer Exists
+
+These are **replaced by Linear**:
+
+- ~~`flydocs/specs/`~~ → Linear issues
+- ~~`flydocs/INDEX.md`~~ → Linear issue list
+- ~~`flydocs/ACTIVE.md`~~ → Linear "In Progress" view
+- ~~`flydocs/specs/assets/`~~ → Linear attachments
+
+---
+
+## Quick Commands
+
+```
+/start-session    - Check Linear status, plan work
+/capture          - Create new Linear issue
+/new-project      - Create project with product label/icon
+/implement        - Pick up issue from Linear
+/validate         - Test implementation
+/close            - Move issue to Done
+/flydocs-update   - Sync rules from source repo
+/design-setup     - (Optional) Initialize design system integration
+```
+
+---
+
+## Design System (Optional)
+
+If you have a Figma design system with tokens, run `/design-setup` to enable enhanced Figma integration:
+
+```
+/design-setup
+```
+
+This creates:
+- `flydocs/design-system/token-mapping.md` - Your Figma → code translations
+- `flydocs/design-system/component-patterns.md` - Your reusable components
+
+And updates `.flydocs/config.json` with:
+```json
+{
+  "designSystem": {
+    "enabled": true,
+    "figmaFiles": {
+      "designs": "your-designs-file-key",
+      "system": "your-design-system-file-key"
+    }
+  }
+}
+```
+
+**Without design system:** Baseline Figma workflow (5-phase, screenshot-first) always works.
+**With design system:** Token enforcement, validation, stricter design consistency.
+
+---
+
+## Configuration
+
+See `.flydocs/config.json` for:
+- FlyDocs version
+- `paths.content` - This folder name (default: "flydocs")
+- `provider.teamId` - Linear team ID
+- `workspace.activeProjects` - Array of active project IDs
+- `workspace.product` - Product identity (name, labelIds, icon, color)
+- `statusMapping` - Workflow state names
+
+See `.cursor/mcp.json` for MCP server configuration.
+
+---
+
+## More Information
+
+- `AGENTS.md` - AI agent instructions
+- `.claude/skills/` - Portable agent skills (platform + community)
+- `knowledge/INDEX.md` - Knowledge base inventory

package/template/flydocs/context/project.md

@@ -0,0 +1,51 @@
+# Project Context
+
+## What This Is
+
+<!-- Fill during setup: 2-3 sentences describing the project -->
+[Project name] — [what it does and who it's for].
+
+## Stack
+
+<!-- Fill during setup: auto-detected or manual -->
+- **Framework**: [e.g., Next.js 14 / React 18]
+- **Language**: [e.g., TypeScript 5.x]
+- **Styling**: [e.g., Tailwind CSS]
+- **Database**: [e.g., PostgreSQL / Convex]
+- **Hosting**: [e.g., Vercel]
+- **Testing**: [e.g., Vitest + Testing Library]
+
+## Standards
+
+Code standards are defined by installed community skills. Skills are installed
+based on detected stack during setup or manually via `npx flydocs skills add`.
+
+Read the relevant skill before writing code in that domain. List installed skills
+with `npx flydocs skills list`.
+
+### Project-Specific Standards
+
+<!-- Add project-specific rules, overrides, or clarifications here -->
+<!-- Example: "We use CSS Modules instead of Tailwind for this project" -->
+
+## Key Decisions
+
+Architectural decisions: `flydocs/knowledge/decisions/`
+Project notes: `flydocs/knowledge/notes/`
+
+## Active Priorities
+
+<!-- Updated by session-wrap or manually -->
+1. [Current priority 1]
+2. [Current priority 2]
+3. [Current priority 3]
+
+## Links
+
+- **Repository**: [URL]
+- **Design**: [Figma URL if applicable]
+- **Docs**: [External docs URL if applicable]
+
+---
+
+*Last Updated: YYYY-MM-DD*

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

@@ -0,0 +1,126 @@
+# Design System Configuration
+
+> This directory maps your Figma design system to code implementation.
+
+---
+
+## Purpose
+
+When using the `flydocs-figma` skill to extract designs, the AI needs to know:
+
+1. **How Figma tokens map to code** (colors, spacing, typography)
+2. **What component patterns exist** (and how to match them)
+3. **Design system constraints** (never invent, always map)
+
+---
+
+## Setup
+
+### 1. Run /design-setup
+
+The `/design-setup` command will:
+- Connect to your Figma file via MCP
+- Extract design tokens
+- Generate initial mappings
+- Create component pattern documentation
+
+### 2. Populate Token Mapping
+
+Edit `token-mapping.md` to define how Figma tokens translate to your code:
+
+```markdown
+## Colors
+
+| Figma Token | CSS Variable | Tailwind Class |
+|-------------|--------------|----------------|
+| Primary/500 | --color-primary-500 | bg-primary-500 |
+| Neutral/100 | --color-neutral-100 | bg-neutral-100 |
+```
+
+### 3. Document Component Patterns
+
+Edit `component-patterns.md` to map Figma components to code:
+
+```markdown
+## Button
+
+**Figma Component:** `Components/Button/Primary`
+
+**Code Pattern:**
+```tsx
+<Button variant="primary" size="md">
+  {children}
+</Button>
+```
+
+**Variants:**
+- Primary → variant="primary"
+- Secondary → variant="secondary"
+- Ghost → variant="ghost"
+```
+
+---
+
+## File Structure
+
+```
+flydocs/design-system/
+├── README.md              # This file
+├── token-mapping.md       # Figma token → code mapping
+├── component-patterns.md  # Figma component → code mapping
+└── tokens/                # Optional: extracted token JSON
+    ├── colors.json
+    ├── spacing.json
+    └── typography.json
+```
+
+---
+
+## Integration with flydocs-figma Skill
+
+The `flydocs-figma` skill references this directory:
+
+1. **Before extraction** - Loads token-mapping.md for translation rules
+2. **During extraction** - Matches Figma elements to documented patterns
+3. **After extraction** - Validates no tokens were invented
+
+### Strict Enforcement
+
+The skill enforces:
+- **NO inventing tokens** - Every value must map to documented token
+- **NO guessing components** - Every component must match documented pattern
+- **Ask if uncertain** - Prompt user when mapping is unclear
+
+---
+
+## Maintenance
+
+### When Design System Changes
+
+1. Update Figma file
+2. Re-run `/design-setup` to detect changes
+3. Update token-mapping.md with new/changed tokens
+4. Update component-patterns.md with new components
+
+### Version Tracking
+
+Add version notes to track design system evolution:
+
+```markdown
+## Changelog
+
+### v2.0 (2024-01)
+- Added new color palette (Primary → Brand)
+- Updated button variants
+
+### v1.0 (2023-06)
+- Initial design system
+```
+
+---
+
+## Templates
+
+See `.flydocs/templates/design-system/` for:
+- `token-mapping.md` - Template for token documentation
+- `component-patterns.md` - Template for component documentation

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

@@ -0,0 +1,173 @@
+# Component Patterns
+
+> Maps Figma components to code implementation patterns.
+> **Run /design-setup to auto-populate from your Figma file.**
+
+---
+
+## How to Use This Document
+
+When implementing from Figma designs:
+
+1. **Find the Figma component** in the design
+2. **Look up the pattern** in this document
+3. **Use the exact code pattern** provided
+4. **Never invent** - if no pattern exists, ask or document first
+
+---
+
+## Buttons
+
+### Primary Button
+
+**Figma Component:** `Components/Button/Primary`
+
+```tsx
+<Button variant="primary" size="md">
+  Label Text
+</Button>
+```
+
+**Variants:**
+| Figma Variant | Code Prop |
+|---------------|-----------|
+| Primary | `variant="primary"` |
+| Secondary | `variant="secondary"` |
+| Ghost | `variant="ghost"` |
+| Destructive | `variant="destructive"` |
+
+**Sizes:**
+| Figma Size | Code Prop |
+|------------|-----------|
+| Small | `size="sm"` |
+| Medium | `size="md"` |
+| Large | `size="lg"` |
+
+---
+
+## Form Inputs
+
+### Text Input
+
+**Figma Component:** `Components/Input/Text`
+
+```tsx
+<Input
+  type="text"
+  label="Field Label"
+  placeholder="Placeholder text"
+  error={errorMessage}
+/>
+```
+
+**States:**
+| Figma State | Code Prop |
+|-------------|-----------|
+| Default | (default) |
+| Focused | Handled by CSS |
+| Error | `error="Message"` |
+| Disabled | `disabled` |
+
+---
+
+## Cards
+
+### Content Card
+
+**Figma Component:** `Components/Card/Content`
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    {children}
+  </CardContent>
+  <CardFooter>
+    {actions}
+  </CardFooter>
+</Card>
+```
+
+---
+
+## Layout Patterns
+
+### Page Container
+
+**Figma Frame:** `Layout/Page`
+
+```tsx
+<div className="container mx-auto px-4 py-8 max-w-7xl">
+  {children}
+</div>
+```
+
+### Section
+
+**Figma Frame:** `Layout/Section`
+
+```tsx
+<section className="py-12 space-y-6">
+  <h2 className="text-2xl font-semibold">{title}</h2>
+  {children}
+</section>
+```
+
+---
+
+## Navigation
+
+### Nav Item
+
+**Figma Component:** `Components/Nav/Item`
+
+```tsx
+<NavLink
+  href={href}
+  active={isActive}
+>
+  {icon && <Icon name={icon} />}
+  {label}
+</NavLink>
+```
+
+---
+
+## Adding New Patterns
+
+When you encounter a Figma component without a documented pattern:
+
+1. **Stop** - Don't guess the implementation
+2. **Document** - Add the pattern to this file
+3. **Verify** - Ensure it matches existing code conventions
+4. **Then implement** - Use the documented pattern
+
+### Pattern Template
+
+```markdown
+### [Component Name]
+
+**Figma Component:** `[Exact Figma path]`
+
+```tsx
+// Code pattern here
+```
+
+**Variants:**
+| Figma Variant | Code Prop |
+|---------------|-----------|
+| ... | ... |
+```
+
+---
+
+## Validation Checklist
+
+Before implementing from Figma:
+- [ ] Component pattern exists in this document
+- [ ] All variants are documented
+- [ ] Token mappings exist for all design values
+- [ ] Pattern matches existing codebase conventions

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

@@ -0,0 +1,114 @@
+# Design Token Mapping
+
+> Maps Figma design tokens to code implementation.
+> **Run /design-setup to auto-populate from your Figma file.**
+
+---
+
+## Colors
+
+| Figma Token | CSS Variable | Tailwind Class | Hex Value |
+|-------------|--------------|----------------|-----------|
+| _Run /design-setup to populate_ | | | |
+
+### Example Format
+
+```markdown
+| Primary/500 | --color-primary-500 | bg-primary-500 | #3B82F6 |
+| Primary/600 | --color-primary-600 | bg-primary-600 | #2563EB |
+| Neutral/50 | --color-neutral-50 | bg-neutral-50 | #FAFAFA |
+| Neutral/900 | --color-neutral-900 | text-neutral-900 | #171717 |
+```
+
+---
+
+## Spacing
+
+| Figma Token | CSS Variable | Tailwind Class | Value |
+|-------------|--------------|----------------|-------|
+| _Run /design-setup to populate_ | | | |
+
+### Example Format
+
+```markdown
+| Space/1 | --space-1 | p-1 | 4px |
+| Space/2 | --space-2 | p-2 | 8px |
+| Space/4 | --space-4 | p-4 | 16px |
+| Space/8 | --space-8 | p-8 | 32px |
+```
+
+---
+
+## Typography
+
+| Figma Style | CSS Class | Tailwind Classes | Properties |
+|-------------|-----------|------------------|------------|
+| _Run /design-setup to populate_ | | | |
+
+### Example Format
+
+```markdown
+| Heading/H1 | .text-h1 | text-4xl font-bold | 36px/40px, 700 |
+| Heading/H2 | .text-h2 | text-3xl font-semibold | 30px/36px, 600 |
+| Body/Default | .text-body | text-base | 16px/24px, 400 |
+| Body/Small | .text-sm | text-sm | 14px/20px, 400 |
+```
+
+---
+
+## Border Radius
+
+| Figma Token | CSS Variable | Tailwind Class | Value |
+|-------------|--------------|----------------|-------|
+| _Run /design-setup to populate_ | | | |
+
+### Example Format
+
+```markdown
+| Radius/SM | --radius-sm | rounded-sm | 4px |
+| Radius/MD | --radius-md | rounded-md | 8px |
+| Radius/LG | --radius-lg | rounded-lg | 12px |
+| Radius/Full | --radius-full | rounded-full | 9999px |
+```
+
+---
+
+## Shadows
+
+| Figma Style | CSS Variable | Tailwind Class | Value |
+|-------------|--------------|----------------|-------|
+| _Run /design-setup to populate_ | | | |
+
+### Example Format
+
+```markdown
+| Shadow/SM | --shadow-sm | shadow-sm | 0 1px 2px rgba(0,0,0,0.05) |
+| Shadow/MD | --shadow-md | shadow-md | 0 4px 6px rgba(0,0,0,0.1) |
+| Shadow/LG | --shadow-lg | shadow-lg | 0 10px 15px rgba(0,0,0,0.1) |
+```
+
+---
+
+## Usage Notes
+
+### Figma Token Format
+- Tokens are typically in `Category/Name` format
+- Use exact Figma names for reliable extraction
+
+### CSS Variables
+- Define in your global CSS or theme file
+- Use `var(--token-name)` in components
+
+### Tailwind Integration
+- Map to existing Tailwind classes where possible
+- Extend Tailwind config for custom tokens
+
+---
+
+## Validation
+
+Before using these tokens, verify:
+- [ ] All Figma tokens have code mappings
+- [ ] CSS variables are defined in stylesheets
+- [ ] Tailwind config includes custom values
+- [ ] Component library uses these tokens consistently