@flydocs/cli 0.5.0-beta.0

package/template/flydocs/knowledge/INDEX.md

@@ -0,0 +1,100 @@
+# Knowledge Base Index
+
+<!--
+AGENT INSTRUCTIONS:
+- Scan this file FIRST when looking for existing knowledge
+- Use descriptions to assess relevance before loading full docs
+- Update this index when adding new knowledge docs
+-->
+
+## Quick Reference
+
+| Category | Count | Last Updated |
+|----------|-------|--------------|
+| Decisions | 0 | - |
+| Features | 0 | - |
+| Notes | 0 | - |
+| Product | 2 | YYYY-MM-DD |
+
+---
+
+## 📋 Decisions (ADRs)
+
+Architecture Decision Records - why we made key technical choices.
+
+| ID | Title | Status | Date |
+|----|-------|--------|------|
+| - | No decisions recorded yet | - | - |
+
+<!-- Example:
+| 001 | Use Convex for Backend | Accepted | 2024-01-15 |
+  → Explains why we chose Convex over traditional REST API
+-->
+
+---
+
+## 🔧 Features
+
+Documentation for complex features that need more than a spec.
+
+| Feature | Description | Last Updated |
+|---------|-------------|--------------|
+| - | No feature docs yet | - |
+
+<!-- Example:
+| auth-system | Complete auth flow documentation | 2024-02-01 |
+  → OAuth setup, session handling, role-based access
+-->
+
+---
+
+## 📝 Notes
+
+Technical discoveries, gotchas, learnings.
+
+| Topic | Description | Added |
+|-------|-------------|-------|
+| - | No notes yet | - |
+
+<!-- Example:
+| api-rate-limits | Third-party API quirks and workarounds | 2024-01-20 |
+  → Stripe webhook retries, Figma API limits, etc.
+-->
+
+---
+
+## 👥 Product
+
+User research and product documentation.
+
+| Document | Description | Last Updated |
+|----------|-------------|--------------|
+| personas.md | Target user profiles | YYYY-MM-DD |
+| user-flows.md | Key user journeys | YYYY-MM-DD |
+
+---
+
+## How to Add Knowledge
+
+### New Decision (ADR)
+```bash
+# Create: flydocs/knowledge/decisions/NNN-title.md
+# Update: This index with new entry
+```
+
+### New Feature Doc
+```bash
+# Create: flydocs/knowledge/features/feature-name.md
+# Update: This index with new entry
+```
+
+### New Note
+```bash
+# Create: flydocs/knowledge/notes/topic-name.md
+# Update: This index with new entry
+```
+
+---
+
+*Last Updated: YYYY-MM-DD*
+

package/template/flydocs/knowledge/README.md

@@ -0,0 +1,62 @@
+# Knowledge Base
+
+This directory contains project knowledge that accumulates over time.
+
+## Structure
+
+```
+knowledge/
+├── INDEX.md      # Start here - inventory of all knowledge
+├── decisions/    # Architecture Decision Records (ADRs)
+├── features/     # Complex feature documentation
+├── notes/        # Technical discoveries and learnings
+└── product/      # User research and product docs
+```
+
+## When to Add Knowledge
+
+### Decisions (`decisions/`)
+Add an ADR when you make a significant technical choice:
+- Choosing a framework or library
+- Designing a system architecture
+- Establishing a pattern that others should follow
+
+**Format**: `NNN-title.md` (e.g., `001-use-convex.md`)
+
+### Features (`features/`)
+Add feature documentation when:
+- A feature is too complex for just a spec
+- Multiple specs relate to one system
+- Future developers will need deep context
+
+**Format**: `feature-name.md` (e.g., `auth-system.md`)
+
+### Notes (`notes/`)
+Add notes when you discover:
+- API quirks or gotchas
+- Performance optimizations
+- Debugging techniques
+- Third-party service behaviors
+
+**Format**: `topic-name.md` (e.g., `stripe-webhooks.md`)
+
+### Product (`product/`)
+Add product docs for:
+- User personas
+- User flows and journeys
+- Research findings
+- Product requirements
+
+**Format**: `document-name.md` (e.g., `personas.md`)
+
+## Always Update INDEX.md
+
+When adding any knowledge document, update `INDEX.md` so agents can discover it.
+
+## Relationship to Specs
+
+- **Specs** (in Linear) = What we're building now
+- **Knowledge** (here) = What we've learned that persists
+
+Specs reference knowledge. Knowledge grows from implementing specs.
+

package/template/flydocs/knowledge/product/personas.md

@@ -0,0 +1,79 @@
+# User Personas
+
+<!--
+AGENT INSTRUCTIONS:
+- Reference when creating user-facing features
+- Ensure features address real user needs
+- Update as user research evolves
+-->
+
+## Primary Personas
+
+### Persona 1: [Name]
+
+**Role**: [Job title or role]
+**Experience Level**: [Beginner / Intermediate / Expert]
+
+**Goals**:
+- [What they want to achieve]
+- [What they want to achieve]
+
+**Pain Points**:
+- [Current frustration]
+- [Current frustration]
+
+**Behaviors**:
+- [How they currently work]
+- [Tools they use]
+
+**Quote**: "[Something they might say that captures their mindset]"
+
+---
+
+### Persona 2: [Name]
+
+**Role**: [Job title or role]
+**Experience Level**: [Beginner / Intermediate / Expert]
+
+**Goals**:
+- [What they want to achieve]
+- [What they want to achieve]
+
+**Pain Points**:
+- [Current frustration]
+- [Current frustration]
+
+**Behaviors**:
+- [How they currently work]
+- [Tools they use]
+
+**Quote**: "[Something they might say that captures their mindset]"
+
+---
+
+## Secondary Personas
+
+### [Name]
+[Brief description - less detail than primary personas]
+
+---
+
+## Anti-Personas (Who We're NOT Building For)
+
+### [Type]
+[Why this user type is out of scope]
+
+---
+
+## Persona Usage
+
+When creating specs, reference personas:
+- "As a [Persona Name], I want to..."
+- Consider: Would this feature help [Persona]?
+- Prioritize features that serve primary personas
+
+---
+
+*Last Updated: YYYY-MM-DD*
+*Source: [How this was researched - interviews, analytics, etc.]*
+

package/template/flydocs/knowledge/product/user-flows.md

@@ -0,0 +1,88 @@
+# User Flows
+
+<!--
+AGENT INSTRUCTIONS:
+- Reference when implementing user-facing features
+- Ensure implementations follow expected user journeys
+- Update as product evolves
+-->
+
+## Core Flows
+
+### Flow 1: [Flow Name, e.g., "User Onboarding"]
+
+**Trigger**: [What initiates this flow]
+**Goal**: [What user accomplishes]
+**Persona**: [Which persona - link to personas.md]
+
+```
+[Entry Point]
+     │
+     ▼
+[Step 1: Action/Screen]
+     │
+     ├── [Happy path] ──▶ [Step 2]
+     │                        │
+     │                        ▼
+     │                   [Step 3: Success]
+     │
+     └── [Error case] ──▶ [Error handling]
+```
+
+**Key Considerations**:
+- [Important UX consideration]
+- [Edge case to handle]
+
+**Success Metrics**:
+- [How we measure this flow works]
+
+---
+
+### Flow 2: [Flow Name]
+
+**Trigger**: [What initiates this flow]
+**Goal**: [What user accomplishes]
+**Persona**: [Which persona]
+
+```
+[Entry Point]
+     │
+     ▼
+[Steps...]
+```
+
+**Key Considerations**:
+- [Important UX consideration]
+
+---
+
+## Secondary Flows
+
+### [Flow Name]
+[Brief description of less critical flows]
+
+---
+
+## Flow Patterns
+
+### Error Handling
+[Standard approach to errors across flows]
+
+### Loading States
+[Standard approach to loading states]
+
+### Empty States
+[Standard approach to empty states]
+
+---
+
+## Cross-References
+
+| Flow | Related Specs | Related Features |
+|------|---------------|------------------|
+| [Flow] | LIN-XXX | [feature doc] |
+
+---
+
+*Last Updated: YYYY-MM-DD*
+

package/template/manifest.json

@@ -0,0 +1,221 @@
+{
+  "version": "0.4.0",
+  "description": "FlyDocs Core - Manifest of all managed files",
+  "repository": "github.com/plastrlab/flydocs-core",
+
+  "ownership": {
+    "description": "Defines what FlyDocs owns vs what users can customize",
+
+    "owned_directories": {
+      "description": "Entire directories owned by FlyDocs - contents replaced on update",
+      "paths": [
+        ".flydocs/hooks",
+        ".flydocs/templates",
+        ".claude/agents",
+        ".claude/skills/flydocs-workflow",
+        ".claude/skills/flydocs-cloud",
+        ".claude/skills/flydocs-local",
+        ".claude/skills/flydocs-figma",
+        ".claude/skills/flydocs-estimates",
+        ".claude/skills/flydocs-context-graph",
+        ".claude/skills/implementation-flow",
+        ".claude/skills/review-workflow",
+        ".claude/skills/spec-templates",
+        ".flydocs/scripts",
+        ".cursor/agents"
+      ]
+    },
+
+    "owned_files": {
+      "description": "Individual files owned by FlyDocs - overwritten on update",
+      "paths": [
+        ".claude/CLAUDE.md",
+        ".claude/settings.json",
+        ".claude/commands/activate.md",
+        ".claude/commands/attach.md",
+        ".claude/commands/block.md",
+        ".claude/commands/capture.md",
+        ".claude/commands/close.md",
+        ".claude/commands/flydocs-setup.md",
+        ".claude/commands/flydocs-update.md",
+        ".claude/commands/implement.md",
+        ".claude/commands/new-project.md",
+        ".claude/commands/project-update.md",
+        ".claude/commands/refine.md",
+        ".claude/commands/review.md",
+        ".claude/commands/start-session.md",
+        ".claude/commands/status.md",
+        ".claude/commands/validate.md",
+        ".claude/commands/wrap-session.md",
+        ".claude/skills/README.md",
+        ".cursor/hooks.json",
+        ".flydocs/version",
+        ".flydocs/CHANGELOG.md",
+        "AGENTS.md"
+      ]
+    },
+
+    "preserved_files": {
+      "description": "User's living documentation - evolves with project, protected from FlyDocs updates",
+      "paths": [
+        ".env",
+        ".env.local",
+        ".cursor/mcp.json",
+        "flydocs/context/project.md",
+        "flydocs/knowledge/**",
+        "flydocs/design-system/**"
+      ]
+    },
+
+    "merged_files": {
+      "description": "Files where specific keys are preserved during update",
+      "files": {
+        ".flydocs/config.json": {
+          "preserve_keys": [
+            "tier",
+            "provider.teamId",
+            "workspace.activeProjects",
+            "workspace.defaultMilestoneId",
+            "workspace.product",
+            "issueLabels",
+            "statusMapping",
+            "detectedStack",
+            "mcp",
+            "skills",
+            "designSystem",
+            "aiLabor"
+          ]
+        }
+      }
+    },
+
+    "template_files": {
+      "description": "Initial scaffolding - created on setup, then maintained by user as project evolves",
+      "paths": [
+        ".env.example",
+        "flydocs/context/project.md",
+        "flydocs/knowledge/INDEX.md",
+        "flydocs/knowledge/README.md",
+        "flydocs/knowledge/product/personas.md",
+        "flydocs/knowledge/product/user-flows.md",
+        "flydocs/README.md",
+        "flydocs/design-system/README.md",
+        "flydocs/design-system/token-mapping.md",
+        "flydocs/design-system/component-patterns.md"
+      ]
+    }
+  },
+
+  "files": {
+    "description": "Complete file tree for integrity verification",
+    "tree": {
+      ".claude": {
+        "root": ["CLAUDE.md", "settings.json"],
+        "agents": [
+          "README.md",
+          "pm-agent.md",
+          "implementation-agent.md",
+          "review-agent.md",
+          "research-agent.md"
+        ],
+        "commands": [
+          "activate.md",
+          "attach.md",
+          "block.md",
+          "capture.md",
+          "close.md",
+          "flydocs-setup.md",
+          "flydocs-update.md",
+          "implement.md",
+          "new-project.md",
+          "project-update.md",
+          "refine.md",
+          "review.md",
+          "start-session.md",
+          "status.md",
+          "validate.md",
+          "wrap-session.md"
+        ],
+        "skills": {
+          "root": ["README.md"],
+          "flydocs-workflow": [
+            "SKILL.md",
+            "session.md",
+            "cursor-rule.mdc",
+            "stages/",
+            "templates/",
+            "reference/"
+          ],
+          "flydocs-cloud": [
+            "SKILL.md",
+            "cursor-rule.mdc",
+            "scripts/"
+          ],
+          "flydocs-local": [
+            "SKILL.md",
+            "cursor-rule.mdc",
+            "scripts/"
+          ],
+          "flydocs-figma": [
+            "SKILL.md",
+            "references/"
+          ],
+          "flydocs-estimates": [
+            "SKILL.md",
+            "references/"
+          ],
+          "flydocs-context-graph": [
+            "SKILL.md",
+            "schema.md",
+            "scripts/"
+          ],
+          "implementation-flow": ["SKILL.md"],
+          "review-workflow": ["SKILL.md"],
+          "spec-templates": ["SKILL.md"]
+        }
+      },
+      ".cursor": {
+        "root": ["hooks.json", "mcp.json"],
+        "agents": [
+          "pm-agent.md",
+          "implementation-agent.md",
+          "review-agent.md",
+          "research-agent.md"
+        ]
+      },
+      ".flydocs": {
+        "root": ["config.json", "version", "CHANGELOG.md"],
+        "scripts": [
+          "generate_manifest.py",
+          "skill_manager.py"
+        ],
+        "hooks": [
+          "auto-approve.py",
+          "prefer-scripts.py",
+          "post-edit.py",
+          "prompt-submit.py"
+        ],
+        "templates": [
+          "bug.md",
+          "chore.md",
+          "feature.md",
+          "idea.md"
+        ]
+      },
+      "flydocs": {
+        "root": ["README.md"],
+        "context": ["project.md"],
+        "design-system": [
+          "README.md",
+          "token-mapping.md",
+          "component-patterns.md"
+        ],
+        "knowledge": {
+          "root": ["INDEX.md", "README.md"],
+          "product": ["personas.md", "user-flows.md"]
+        }
+      },
+      "root": ["AGENTS.md", ".env.example"]
+    }
+  }
+}