@flydocs/cli 0.5.0-beta.0

package/template/.claude/skills/flydocs-workflow/templates/feature.md

@@ -0,0 +1,93 @@
+## Context
+
+[Problem description - what user pain or business need does this address?]
+
+**Current Issues:**
+- [Issue or limitation 1]
+- [Issue or limitation 2]
+
+---
+
+## User Story
+
+**As a** [specific user role]
+**I want to** [specific goal or action]
+**So that** [concrete benefit or outcome]
+
+**Example Scenario:**
+[Real-world scenario where this feature would be used]
+
+---
+
+## Acceptance Criteria
+
+### Must Have
+- [ ] [Specific, measurable criterion 1]
+- [ ] [User can perform X action and see Y result]
+- [ ] [System behaves correctly when Z happens]
+- [ ] [Error handling: System shows helpful message when...]
+
+### Should Have
+- [ ] [Nice-to-have enhancement]
+
+### Won't Have (Out of Scope)
+- [Explicitly excluded functionality]
+
+### Tests
+- [ ] Tests written for core functionality
+- [ ] Edge cases and error scenarios covered
+- [ ] All tests passing
+
+### Documentation
+- [ ] Code documented (comments on complex logic)
+- [ ] Knowledge base updated (if significant decisions/patterns)
+- [ ] Context files updated (if architecture changes)
+- [ ] N/A - No significant documentation needed
+
+---
+
+## Technical Notes
+
+### Implementation Approach
+[High-level description of how this will be built]
+
+**Key Technical Decisions:**
+1. [Decision 1 and rationale]
+2. [Decision 2 and rationale]
+
+### Components Needed
+**New:**
+- `ComponentName` - [What it does]
+
+**Modify:**
+- `ExistingComponent` - [What changes needed]
+
+### Data Model
+```typescript
+// Schema changes if any
+// OR: No data model changes required
+```
+
+### API Endpoints
+- `POST /api/endpoint` - [Description]
+- OR: No new endpoints required
+
+---
+
+## Dependencies
+
+**Required Before Starting:**
+- [Feature or system that must exist first]
+- OR: No dependencies - can start immediately
+
+**Enables Future Work:**
+- [Feature that depends on this being complete]
+
+---
+
+## Design Reference
+<!-- Add Figma links as attachments -->
+
+---
+
+_Created: YYYY-MM-DD_

package/template/.claude/skills/flydocs-workflow/templates/idea.md

@@ -0,0 +1,84 @@
+## Sketch
+
+**Quick Description:**
+- **What:** [One sentence - what is this?]
+- **Why:** [One sentence - why might this be valuable?]
+- **How:** [One sentence - rough idea of how it might work]
+
+**Details:**
+[Additional thoughts, context, inspiration, related ideas]
+
+---
+
+## Potential Value
+
+**For Users:**
+- [Benefit 1]
+- [Benefit 2]
+
+**For Business/Product:**
+- [Value 1]
+- [Value 2]
+
+**Estimated Impact:** High | Medium | Low | Unknown
+
+---
+
+## Questions to Answer
+
+**Unknowns:**
+- [ ] What needs research or investigation?
+- [ ] What's the technical feasibility?
+- [ ] What's the rough effort estimate?
+- [ ] Does this already exist elsewhere?
+
+**Dependencies:**
+- [ ] Does this depend on other work?
+- [ ] Are there technical constraints?
+
+**Risks:**
+- [ ] What could go wrong?
+
+---
+
+## Rough Complexity
+
+**Complexity:** XS | S | M | L | XL | Unknown
+
+**If XL or larger:**
+[How could this be broken into smaller features?]
+
+---
+
+## Next Steps
+
+**To Validate This Idea:**
+1. [Research step 1]
+2. [User validation needed]
+3. [Technical spike or prototype]
+
+**To Turn Into a Feature:**
+1. [ ] Answer the questions above
+2. [ ] Define clear user story and acceptance criteria
+3. [ ] Get stakeholder buy-in
+4. [ ] Create feature issue with full template
+
+---
+
+## Status Tracking
+
+- [ ] **Captured** - Idea written down
+- [ ] **Researched** - Questions answered, feasibility checked
+- [ ] **Validated** - Worth pursuing
+- [ ] **Refined** - Converted to full feature issue
+- [ ] **Declined** - Decided not to pursue
+
+**If Declined:**
+- **Reason:** [Why we decided not to do this]
+
+**If Refined:**
+- **New Issue:** [Link to feature issue created from this idea]
+
+---
+
+_Captured: YYYY-MM-DD_

package/template/.cursor/agents/implementation-agent.md

@@ -0,0 +1,28 @@
+---
+name: implementation-agent
+description: "Builds features, fixes bugs, writes code. Invoke for implementation, coding, or technical work."
+model: inherit
+readonly: false
+is_background: false
+---
+
+# Implementation Agent
+
+Implementation agent for FlyDocs spec-driven development.
+
+## Role
+
+- Build features according to spec acceptance criteria
+- Fix bugs following documented reproduction steps
+- Write clean, tested code following project standards
+- Document decisions and blockers via issue comments
+- Simplify code before handoff to review
+
+## Constraints
+
+- **Scripts for issue updates** — use mechanism scripts for progress comments and transitions
+- Follow installed community skills for code quality patterns
+- Keep changes focused on the spec — don't over-engineer
+
+Read `.claude/skills/flydocs-workflow/stages/implement.md` for the implementation procedure.
+Read `flydocs/context/project.md` for stack and project-specific standards.

package/template/.cursor/agents/pm-agent.md

@@ -0,0 +1,27 @@
+---
+name: pm-agent
+description: "Specs, workflow, issue management. Invoke for capturing, refining, activating, reviewing, closing, or session management."
+model: inherit
+readonly: false
+is_background: false
+---
+
+# PM Agent
+
+Product management agent for FlyDocs spec-driven workflow.
+
+## Role
+
+- Manage issues through the workflow lifecycle (capture → close)
+- Refine specs using templates from the workflow skill
+- Coordinate handoffs between implementation and review
+- Post project updates and manage sessions
+
+## Constraints
+
+- **Do not modify code files** — this agent handles workflow, not implementation
+- **Scripts for all issue ops** — read the mechanism skill's SKILL.md for calling conventions
+- Defer technical decisions to implementation agent
+
+Read `.claude/skills/flydocs-workflow/SKILL.md` for lifecycle and stage procedures.
+Read `.flydocs/config.json` for project configuration.

package/template/.cursor/agents/research-agent.md

@@ -0,0 +1,23 @@
+---
+name: research-agent
+description: "Codebase exploration and research. Invoke for understanding code structure, finding patterns, or gathering technical context."
+model: inherit
+readonly: true
+is_background: false
+---
+
+# Research Agent
+
+Research agent for exploring codebases and gathering context.
+
+## Role
+
+- Explore codebase structure and patterns
+- Look up documentation and external references
+- Gather technical context before implementation
+- Answer questions about existing code
+
+## Constraints
+
+- **Read-only** — cannot modify files or run commands
+- Reports findings — does not make decisions or implement changes

package/template/.cursor/agents/review-agent.md

@@ -0,0 +1,27 @@
+---
+name: review-agent
+description: "Code review and quality analysis. Invoke for reviewing implementations, checking quality, or validating acceptance criteria."
+model: inherit
+readonly: true
+is_background: false
+---
+
+# Review Agent
+
+Code review agent — critical analysis, not rubber-stamping.
+
+## Role
+
+- Review code changes against acceptance criteria and project standards
+- Identify bugs, pattern violations, security issues, performance problems
+- Run automated tests and report results
+- Present findings with severity (blocking / should fix / suggestion)
+
+## Constraints
+
+- **Read-only** — cannot modify code
+- **Cannot transition issues** — reports findings, PM agent handles state changes
+- **Cannot approve on behalf of user** — presents review, user decides
+
+Read `.claude/skills/flydocs-workflow/stages/review.md` for the review procedure.
+Read `flydocs/context/project.md` for project-specific standards.

package/template/.cursor/hooks.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "matcher": "Bash",
+        "command": "python3 ./.flydocs/hooks/auto-approve.py",
+        "timeout": 5
+      },
+      {
+        "matcher": "mcp__linear.*",
+        "command": "python3 ./.flydocs/hooks/prefer-scripts.py",
+        "timeout": 5
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "python3 ./.flydocs/hooks/post-edit.py",
+        "timeout": 30
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "python3 ./.flydocs/hooks/prompt-submit.py",
+        "timeout": 10
+      }
+    ]
+  }
+}

package/template/.cursor/mcp.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://cursor.sh/schemas/mcp.json",
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "@linear/mcp-server"],
+      "env": {
+        "LINEAR_API_KEY": "${LINEAR_API_KEY}"
+      }
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@anthropics/context7-mcp"]
+    }
+  }
+}

package/template/.env.example

@@ -0,0 +1,44 @@
+# FlyDocs Core - Environment Configuration
+# 
+# Copy this file to .env and fill in your value:
+#   cp .env.example .env
+# 
+# IMPORTANT: Never commit .env to git!
+#
+# HOW TO LOAD THIS VALUE:
+# ─────────────────────────
+# Option A (Recommended): Use direnv
+#   1. Install direnv: brew install direnv
+#   2. Add to ~/.zshrc: eval "$(direnv hook zsh)"
+#   3. Create .envrc file: echo "dotenv" > .envrc
+#   4. Allow it: direnv allow
+#   → Value auto-loads when you cd into the project!
+#
+# Option B: Add to shell profile (~/.zshrc)
+#   export LINEAR_API_KEY="your_key_here"
+#
+# Option C: Export manually before opening Cursor
+#   source .env && cursor .
+#
+
+# ===========================================
+# REQUIRED: Linear API Key
+# ===========================================
+# Get from: Linear → Settings → API → Personal API Keys
+# Format: lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+LINEAR_API_KEY=
+
+# ===========================================
+# OPTIONAL: Figma Access Token
+# ===========================================
+# Get from: Figma → Settings → Personal Access Tokens
+# Only needed if using Figma MCP for design integration
+FIGMA_ACCESS_TOKEN=
+
+# ===========================================
+# NOTE: Team ID and Project ID are discovered automatically
+# ===========================================
+# Run /flydocs-setup and the agent will:
+# 1. Query your Linear teams (you select one)
+# 2. Query projects in that team (you select one)
+# 3. Save both IDs to .flydocs/config.json

package/template/.flydocs/config.json

@@ -0,0 +1,104 @@
+{
+  "version": "0.4.0",
+  "sourceRepo": "github.com/plastrlab/flydocs-core",
+  "tier": "cloud",
+  "setupComplete": false,
+  "paths": {
+    "content": "flydocs"
+  },
+  "provider": {
+    "type": "linear",
+    "teamId": null
+  },
+  "workspace": {
+    "activeProjects": [],
+    "defaultMilestoneId": null,
+    "product": {
+      "name": null,
+      "labelIds": [],
+      "icon": null,
+      "color": null
+    }
+  },
+  "issueLabels": {
+    "_note": "Run /flydocs-setup to populate these from your Linear team",
+    "category": {
+      "feature": null,
+      "bug": null,
+      "chore": null,
+      "idea": null
+    },
+    "role": {
+      "design": null,
+      "development": null,
+      "operations": null,
+      "client": null
+    },
+    "other": {
+      "triage": null,
+      "internal": null
+    }
+  },
+  "detectedStack": {
+    "timestamp": null,
+    "frameworks": [],
+    "database": [],
+    "auth": [],
+    "styling": []
+  },
+  "mcp": {
+    "preferred": [],
+    "fallbackOnly": ["linear"],
+    "stackSpecific": {}
+  },
+  "skills": {
+    "installed": [],
+    "custom": []
+  },
+  "statusMapping": {
+    "BACKLOG": "Backlog",
+    "READY": "Todo",
+    "IMPLEMENTING": "In Progress",
+    "BLOCKED": "Blocked",
+    "REVIEW": "In Review",
+    "TESTING": "QA",
+    "COMPLETE": "Done",
+    "ARCHIVED": "Archived",
+    "CANCELED": "Canceled",
+    "DUPLICATE": "Duplicate"
+  },
+  "designSystem": null,
+  "aiLabor": {
+    "enabled": false,
+    "defaultProvider": "claude-sonnet-4",
+    "thresholds": {
+      "warnTokens": 200000,
+      "warnCost": 5.0,
+      "requireApproval": 10.0
+    },
+    "tracking": {
+      "recordActuals": true,
+      "calibrationEnabled": true
+    },
+    "providerRates": {
+      "claude-sonnet-4": {
+        "input": 3.0,
+        "output": 15.0,
+        "inputRatio": 0.7,
+        "outputRatio": 0.3
+      },
+      "claude-opus-4": {
+        "input": 15.0,
+        "output": 75.0,
+        "inputRatio": 0.7,
+        "outputRatio": 0.3
+      },
+      "gpt-4o": {
+        "input": 2.5,
+        "output": 10.0,
+        "inputRatio": 0.7,
+        "outputRatio": 0.3
+      }
+    }
+  }
+}

package/template/.flydocs/hooks/auto-approve.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+PreToolUse Hook: Auto-approve FlyDocs mechanism and workflow scripts
+
+Auto-approves Bash commands that execute scripts in any FlyDocs skill:
+- .claude/skills/flydocs-local/scripts/
+- .claude/skills/flydocs-cloud/scripts/
+- .claude/skills/flydocs-workflow/scripts/
+
+Exit codes:
+- 0 with JSON: Approved (decision in output)
+- 0 with no output: No opinion, continue normally
+- 2: Block (stderr shown to AI)
+"""
+
+import sys
+import json
+import re
+
+
+# Pattern matches any flydocs skill scripts directory
+# Covers: flydocs-local, flydocs-cloud, flydocs-workflow
+APPROVED_PATTERN = re.compile(
+    r'\.claude/skills/flydocs-(?:local|cloud|workflow)/scripts/\w+\.py'
+)
+
+
+def should_approve(command: str) -> bool:
+    """Check if command executes a FlyDocs skill script."""
+    return bool(APPROVED_PATTERN.search(command))
+
+
+def get_script_info(command: str) -> tuple[str, str]:
+    """Extract skill name and script name from command."""
+    match = re.search(
+        r'\.claude/skills/(flydocs-\w+)/scripts/(\w+\.py)', command
+    )
+    if match:
+        return match.group(1), match.group(2)
+    return "unknown", "unknown"
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        sys.exit(0)
+
+    tool_name = input_data.get('tool_name', '')
+    tool_input = input_data.get('tool_input', {})
+
+    if tool_name != 'Bash':
+        sys.exit(0)
+
+    command = tool_input.get('command', '')
+
+    if should_approve(command):
+        skill, script = get_script_info(command)
+        result = {
+            "decision": "approve",
+            "reason": f"Auto-approved FlyDocs script: {skill}/{script}"
+        }
+        print(json.dumps(result))
+        sys.exit(0)
+    else:
+        # No opinion — exit 0 with no output to avoid hook error
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/template/.flydocs/hooks/post-edit.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: post-edit.py
+Triggered: After Edit or Write tool completes
+Purpose: Auto-format code after agent edits
+
+Exit codes:
+  0 - Success (optional JSON output parsed)
+  2 - Blocking error (stderr shown to Claude)
+  Other - Non-blocking error (shown in verbose mode)
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def get_file_extension(file_path: str) -> str:
+    """Extract file extension from path."""
+    return Path(file_path).suffix.lstrip('.')
+
+
+def format_file(file_path: str, ext: str) -> None:
+    """Auto-format file based on extension (non-blocking)."""
+    try:
+        if ext in ('ts', 'tsx', 'js', 'jsx', 'json', 'md'):
+            # Check if package.json exists and npx is available
+            if Path('package.json').exists():
+                subprocess.run(
+                    ['npx', 'prettier', '--write', file_path],
+                    capture_output=True,
+                    timeout=30
+                )
+        elif ext == 'py':
+            # Use black if available
+            subprocess.run(
+                ['black', '--quiet', file_path],
+                capture_output=True,
+                timeout=30
+            )
+    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
+        # Non-blocking - silently skip formatting failures
+        pass
+
+
+def main() -> None:
+    """Main hook execution."""
+    # Read hook input from stdin
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        input_data = {}
+
+    file_path = input_data.get('tool_input', {}).get('file_path', '')
+
+    # Skip if no file path
+    if not file_path:
+        print('{}')
+        sys.exit(0)
+
+    # Get file extension and format
+    ext = get_file_extension(file_path)
+    format_file(file_path, ext)
+
+    # Return empty object to allow operation
+    print('{}')
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()