# FlyDocs

This project uses FlyDocs - a hybrid workflow where:

- **Work items (specs)** live in your issue tracker (local files or cloud provider)
- **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            # Tier, provider settings, workspace config
├── version                # For upgrade detection
├── rules/                 # Workflow rules
└── templates/             # Issue templates (source)

flydocs/                   # PROJECT CONTENT (evolves with project)
├── context/               # Project fundamentals
│   ├── project.md         # Vision, stack, scope (update as it evolves)
│   └── 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
├── CLAUDE.md              # Claude Code instructions
├── agents/                # Subagent definitions
├── skills/                # Workflow skills
├── commands/              # Slash commands
└── settings.json          # Claude hooks
```

**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/project.md`   | Vision, goals, scope |
| 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.

### ISSUE TRACKER (Local or Cloud)

| Content     | Purpose                            |
| ----------- | ---------------------------------- |
| Specs       | Features, bugs, chores, ideas      |
| Status      | BACKLOG → DONE progression         |
| Priorities  | Urgent, High, Medium, Low          |
| Assignments | Who's working on what              |
| Progress    | Decision log, implementation notes |

**Local tier:** Issues stored as files in `flydocs/issues/`.
**Cloud tier:** Issues stored in your provider (e.g., Linear). Enables team collaboration, stakeholder visibility, and AI agent integration.

---

## Quick Commands

```
/start-session    - Check issue status, plan work
/capture          - Create new issue
/new-project      - Create project with product label/icon (cloud tier)
/implement        - Pick up issue for implementation
/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:

- `tier` - "local" (free) or "cloud" (connected to provider)
- `paths.content` - This folder name (default: "flydocs")
- `provider.type` - Issue tracker provider (null for local, e.g. "linear", "jira" for cloud)
- `activeProjectId` - Active project ID (cloud tier)
- `workspace.product` - Product identity (name, labelIds, icon, color)
- `repoDefaults` - Per-repo labels, component, and custom fields
- `statusMapping` - Workflow state names

Version is stored in `.flydocs/version`, not in config.

---

## More Information

- `AGENTS.md` - AI agent instructions
- `.claude/skills/` - Portable agent skills (platform + community)
- `knowledge/INDEX.md` - Knowledge base inventory