@flydocs/cli 0.5.0-beta.0

package/template/.claude/commands/flydocs-setup.md

@@ -0,0 +1,598 @@
+# FlyDocs Setup (PM/Planning Agent)
+
+Initial project onboarding — define project context, connect to provider, and
+create an initial backlog. This command handles two scenarios: new projects
+and FlyDocs version updates (including legacy content migration).
+
+Read the active mechanism skill's `SKILL.md` for script calling conventions
+before executing any scripts.
+
+Triggers: "setup flydocs", "onboard project", "flydocs init"
+
+---
+
+## Phase 0: Scenario Detection
+
+Before starting, detect the project state by checking the filesystem:
+
+1. **FlyDocs Update** — Check that `.flydocs/config.json` exists AND any of
+   these signals indicate prior setup: `flydocs/context/project.md` has real
+   content beyond template placeholders (the "What This Is" section contains
+   more than `[Project name]`), OR `flydocs/issues/` contains issue files
+   (local tier), OR `workspace.activeProjects` is populated in config, OR
+   `detectedStack.timestamp` is non-null in config.
+2. **New Project** — Neither of the above. Fresh setup.
+
+Read `.flydocs/config.json` to determine the **tier** (`local` or `cloud`).
+This affects which phases apply and which scripts are available.
+
+**Announce the detected scenario and tier to the user. Confirm before proceeding.**
+
+Example:
+
+```
+Detected: New project setup (cloud tier)
+I'll walk you through project definition, Linear setup, and initial backlog.
+Ready to begin?
+```
+
+---
+
+## Phase 1: Project Definition
+
+The goal is to fill every section of `flydocs/context/project.md` with real
+content. The approach differs by scenario.
+
+### Phase 1A — New Project
+
+Collaborative discovery. The user may arrive with anything from a loose idea
+to a full PRD. Adapt accordingly.
+
+**Step 1: Scan for existing project documentation.**
+
+Before asking questions, proactively scan the repo for planning and vision docs:
+
+- Root directory: `PRD.md`, `README.md`, `BRIEF.md`, `SPEC.md`, `VISION.md`,
+  `OVERVIEW.md`, `REQUIREMENTS.md`
+- Common directories: `docs/`, `spec/`, `specs/`, `planning/`, `design/`
+- Any `.md` files in root that look like project descriptions
+
+If docs are found, offer to use them:
+
+```
+I found some existing documentation:
+- README.md (project overview)
+- docs/PRD.md (product requirements)
+
+Want me to read these and use them as a starting point for your project context?
+```
+
+Read any docs the user approves. Extract key details: vision, goals, target
+users, features, technical decisions, constraints.
+
+**Step 2: Fill gaps through conversation.**
+
+If no docs were found, or if the docs don't cover everything, ask questions:
+
+- "What are you building? Who is it for?"
+- "What problem does it solve?"
+- "Any technical constraints or preferences I should know about?"
+
+If the user references a file path or URL not yet read, read it and extract
+the key details.
+
+The goal is to build a complete picture by combining existing documentation
+with conversational discovery — not to re-ask things already documented.
+
+**Step 3: Stack detection.**
+
+Scan the project root for tech stack signals:
+
+- `package.json` → frameworks (React, Next.js, Vue, etc.), test runners
+- `tsconfig.json` → TypeScript version and config
+- `tailwind.config.*` → Tailwind CSS
+- `prisma/`, `drizzle.config.*` → ORM / database
+- `Dockerfile`, `fly.toml`, `vercel.json`, `netlify.toml` → hosting
+- `vitest.config.*`, `jest.config.*` → testing framework
+- `.python-version`, `requirements.txt`, `pyproject.toml` → Python projects
+- `go.mod` → Go projects
+- `Cargo.toml` → Rust projects
+
+Report what you find. Ask the user to confirm or correct.
+
+Update `.flydocs/config.json` field `detectedStack` with results:
+
+```json
+{
+  "timestamp": "YYYY-MM-DDTHH:MM:SSZ",
+  "frameworks": ["next.js"],
+  "database": ["postgresql"],
+  "auth": [],
+  "styling": ["tailwind"]
+}
+```
+
+**Step 4: Iterative refinement of project.md.**
+
+Fill each section of `flydocs/context/project.md`:
+
+- **What This Is** — 2-3 sentences: project name, what it does, who it's for.
+  Reflect your understanding back. Ask: "Does this capture it, or should I
+  adjust anything?"
+
+- **Stack** — Populate from detection results. Use the template format:
+
+  ```
+  - **Framework**: Next.js 14
+  - **Language**: TypeScript 5.x
+  - **Styling**: Tailwind CSS
+  - **Database**: PostgreSQL via Prisma
+  - **Hosting**: Vercel
+  - **Testing**: Vitest + Testing Library
+  ```
+
+- **Standards** — Note which community skills were installed during setup
+  (if any). Ask about project-specific standards or conventions:
+  "Any project-specific rules I should know? For example: naming conventions,
+  folder structure preferences, or libraries to prefer/avoid?"
+
+- **Active Priorities** — Ask: "What are the top 3 things you want to
+  accomplish first?" These become the initial priority list.
+
+- **Links** — Ask for repository URL, design files (Figma), documentation
+  links. Fill what's available, leave the rest as placeholders.
+
+- **Last Updated** — Set to today's date.
+
+**Step 5: Write project.md.**
+
+Show the user the complete filled project.md content. Ask for confirmation
+or corrections. Write the file only after approval.
+
+### Phase 1U — FlyDocs Update
+
+> **Note:** If the user just ran `/flydocs-update` (or `flydocs update`), the
+> framework files and changelog have already been refreshed. This phase focuses
+> on updating project _content_ (project.md, config), not framework files.
+
+The project already has a populated project.md. Check for staleness and
+offer updates.
+
+**Step 0: Check for legacy context files.**
+
+Before reading project.md, check if `flydocs/context/legacy/` exists. This
+directory is created by `install.sh` when it finds pre-v1.0 separate context
+files (`overview.md`, `stack.md`, `standards.md`) and moves them there for
+safe migration.
+
+If the legacy directory exists and contains files:
+
+- Read `flydocs/context/legacy/overview.md` → Extract vision, goals, scope
+- Read `flydocs/context/legacy/stack.md` → Extract tech stack details
+- Read `flydocs/context/legacy/standards.md` → Extract conventions
+
+Consolidate into project.md using the same mapping as Phase 1M Step 2.
+Show the user the merged result and confirm before writing.
+
+After successful migration, delete the files from `legacy/` so the next
+`install.sh` run will clean up the empty directory.
+
+**Step 1: Show what's new in this version.**
+
+Read `.flydocs/CHANGELOG.md` and `.flydocs/version`. Compare the installed
+version with what was previously installed (if the user knows, or check git
+history for the version file). Show a summary of changes since their last
+update:
+
+```
+Updated to FlyDocs v0.2.0. Here's what changed:
+- Scenario-aware setup command with proactive doc scanning
+- Deprecated file cleanup in install.sh
+- Legacy context migration for pre-v1.0 projects
+- Changelog and version tracking
+```
+
+If CHANGELOG.md doesn't exist (pre-0.2.0 install), skip this step.
+
+**Step 2: Read existing project.md.**
+
+Read `flydocs/context/project.md`. Check which sections are filled vs still
+using template placeholders.
+
+**Step 3: Report what's current.**
+
+Show the user a brief summary:
+
+```
+Your project.md looks good. Here's what I see:
+- What This Is: ✓ (filled)
+- Stack: ✓ (Next.js, TypeScript, Tailwind)
+- Standards: ✓ (has project-specific rules)
+- Active Priorities: ⚠ (last updated 3 weeks ago)
+- Links: ✓ (repo + Figma linked)
+```
+
+**Step 4: Offer updates.**
+
+- If any section uses placeholder text, offer to fill it.
+- If Active Priorities look stale, ask if they should be refreshed.
+- Ask: "Anything else you'd like to update in your project context?"
+
+**Step 5: Re-run stack detection.**
+
+New frameworks or tools may have been added. Run detection, compare with
+existing `detectedStack`, and report changes:
+
+```
+Stack changes detected:
+- Added: Drizzle ORM (new dependency)
+- Removed: Prisma (no longer in package.json)
+Update config? (y/n)
+```
+
+**Step 6: Check for new config options.**
+
+Read `.flydocs/config.json` and look for fields that are unconfigured but
+may be useful:
+
+- `aiLabor.enabled` — if false, mention it's available
+- `designSystem` — if null and the project has design files, mention setup
+- `workspace.product.name` — if null, offer to set it
+
+---
+
+## Phase 2: Provider Setup — Cloud Only
+
+> **Local tier:** Skip this phase entirely. Print: "Local tier — no provider
+> setup needed. Issues will be stored in `flydocs/issues/`."
+
+For cloud tier, connect to Linear:
+
+**Step 1: Verify API key.**
+
+Check that `LINEAR_API_KEY` is set in the environment (from `.env` or
+`.env.local`). If not:
+
+```
+LINEAR_API_KEY is not set. Add it to your .env file:
+LINEAR_API_KEY=lin_api_xxxxx
+
+Get your key from: Linear → Settings → API → Personal API keys
+```
+
+Do not proceed until the key is available.
+
+**Step 2: Select team.**
+
+If `provider.teamId` in config is null, discover available teams:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_projects.py --all
+```
+
+Present the teams to the user. Let them select. If only one team exists,
+confirm it.
+
+**Step 3: Get or create project.**
+
+Query existing projects:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_projects.py
+```
+
+If matching projects exist, let the user select one. Otherwise, offer to
+create a new project:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/create_project.py --name "Project Name"
+```
+
+**Step 4: Configure product identity.**
+
+Ask about product metadata for Linear:
+
+- **Product name** — how it appears in Linear (default: project name from
+  project.md)
+- **Labels** — auto-create category labels (feature, bug, chore, idea) and
+  role labels (design, development, operations) if they don't exist
+- **Icon and color** — optional, ask if they have preferences
+
+**Step 5: Save to config.**
+
+Update `.flydocs/config.json`:
+
+- `provider.teamId` — selected team ID
+- `workspace.activeProjects` — add the project ID
+- `workspace.product.name` — product name
+- `issueLabels` — map label IDs if created
+
+---
+
+## Phase 3: Milestones — Cloud Only
+
+> **Local tier:** Skip this phase entirely.
+> **FlyDocs Update:** Skip if milestones already exist.
+
+**Step 1: Check existing milestones.**
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_milestones.py
+```
+
+**Step 2: If milestones exist** — show them and confirm they'll be used for
+backlog assignment in the next phase.
+
+**Step 3: If no milestones exist** — offer to create a phased structure:
+
+Suggest the Foundation / Core / Polish pattern:
+
+```
+Suggested milestones:
+1. Phase 1: Foundation — Project setup, core infrastructure, auth
+2. Phase 2: Core Features — Primary user-facing functionality
+3. Phase 3: Polish — UX refinement, performance, edge cases
+
+Want me to create these, or would you prefer different phases?
+```
+
+Let the user customize names, descriptions, and target dates.
+
+**Step 4: Create milestones.**
+
+For each approved milestone:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/create_milestone.py \
+  --name "Phase 1: Foundation" --target-date YYYY-MM-DD
+```
+
+Record the milestone IDs for use in Phase 4.
+
+---
+
+## Phase 4: Initial Backlog
+
+Capture the first batch of work items. The approach varies by scenario.
+
+### For New Project (any tier)
+
+Guide the user through capturing 5-15 high-level work items. These don't need
+to be fully refined — they're the starting backlog.
+
+**Step 1: Seed from priorities.**
+
+Use the Active Priorities from project.md as starting points:
+"Based on your priorities, here are some issues I'd suggest capturing.
+Want to start with these, or do you have your own list?"
+
+**Step 2: Capture each item.**
+
+For each work item, follow the capture procedure from
+`.claude/skills/flydocs-workflow/stages/capture.md`:
+
+- Determine type (feature, bug, chore, idea)
+- Create via the mechanism script:
+  ```bash
+  python3 .claude/skills/flydocs-{tier}/scripts/create_issue.py \
+    --title "Issue title" --type feature --priority 3 --estimate 2
+  ```
+- For quick ideas, use `--triage` flag
+
+**Step 3: Milestone assignment (cloud only).**
+
+> **Local tier:** Skip this step.
+
+After creating issues, assign them to milestones:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/assign_milestone.py \
+  <issue-ref> <milestone-id>
+```
+
+Ask the user which milestone each issue belongs to, or suggest assignments
+based on the issue content.
+
+### For FlyDocs Update
+
+**Step 1: Check if backlog is populated.**
+
+```bash
+python3 .claude/skills/flydocs-{tier}/scripts/list_issues.py --limit 10
+```
+
+If issues exist, skip this phase:
+
+```
+Your backlog already has [N] issues. Skipping initial backlog creation.
+Want to capture any new items?
+```
+
+**Step 2: Capture new items if desired.**
+
+Only if the user wants to add more.
+
+---
+
+## Phase 5: Prioritization — Cloud Only
+
+> **Local tier:** Skip this phase. Local issues have priority set at creation.
+> **FlyDocs Update:** Skip if issues are already prioritized.
+
+**Step 1: Review captured items.**
+
+List all issues in Backlog status:
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/list_issues.py --status BACKLOG
+```
+
+**Step 2: Set priorities.**
+
+For each issue, suggest a priority and let the user confirm or adjust:
+
+- **1 (Urgent)** — Blocking other work or critical path
+- **2 (High)** — Important for current milestone
+- **3 (Medium)** — Standard priority (default)
+- **4 (Low)** — Nice to have, no urgency
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/priority.py <issue-ref> <0-4>
+```
+
+Note: Linear uses 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low.
+
+**Step 3: Set estimates.**
+
+For each issue, suggest a t-shirt size estimate:
+
+- **1** — Trivial (< 1 hour)
+- **2** — Small (half day)
+- **3** — Medium (1-2 days)
+- **4** — Large (3-5 days)
+- **5** — XL (1+ week, consider breaking down)
+
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/estimate.py <issue-ref> <1-5>
+```
+
+**Step 4: Identify dependencies.**
+
+Ask about blocking relationships between issues. If any exist, note them
+(Linear handles dependency tracking natively).
+
+**Step 5: Recommend implementation order.**
+
+Based on priorities, estimates, and dependencies, suggest an order:
+
+```
+Recommended implementation order:
+1. ENG-101 — Auth setup (blocks most features)
+2. ENG-102 — Database schema (foundation)
+3. ENG-105 — User profile page (high priority, small)
+...
+```
+
+---
+
+## Phase 6: Completion & Onboarding
+
+Summarize what was accomplished and provide a guided onboarding experience.
+
+### Step 1: Completion summary
+
+```
+Setup complete! Here's what we did:
+
+Scenario: [New Project / FlyDocs Update]
+Tier: [local / cloud]
+
+✓ Project context: flydocs/context/project.md
+✓ Stack detected: [framework list]
+✓ Provider: [Linear connected / Local file-based]      (if applicable)
+✓ Milestones: [N created]                               (cloud only)
+✓ Backlog: [N issues captured]
+✓ Priorities set                                         (cloud only)
+```
+
+**Mark setup as complete.**
+
+Update `.flydocs/config.json` to set `setupComplete` to `true`. This disables
+the setup reminder in the prompt hook. Read the config, set the field, and
+write it back:
+
+```json
+{ "setupComplete": true }
+```
+
+### Step 2: Quick-start guide
+
+Present the core workflow commands with brief descriptions:
+
+```
+Here's how to work with FlyDocs:
+
+Getting started:
+  /start-session        Begin a work session (sets focus, loads context)
+  /activate             Pick your next issue to work on
+  /capture              Capture a new issue or idea anytime
+
+During development:
+  /implement            Start implementation on your active issue
+  /status               Check current session and issue status
+  /block                Flag a blocker on the current issue
+
+Wrapping up:
+  /review               Submit work for code review
+  /validate             Run QE validation on completed work
+  /wrap-session         End your session (posts summary, saves progress)
+```
+
+### Step 3: Tier-specific notes
+
+**For cloud tier:**
+
+- Linear project URL (if available from create_project response)
+- Recommend reviewing milestones in Linear's UI for timeline view
+
+**For local tier:**
+
+- Issues live in `flydocs/issues/` as markdown files
+- No account or API key needed — everything is local and offline
+- Run `/status` anytime to see your backlog at a glance
+
+### Step 4: Beta CTA
+
+Always end with the beta call-to-action:
+
+```
+─────────────────────────────────────────────────────
+
+FlyDocs is in active development. Premium features coming soon:
+  → Cloud sync with Linear, Jira, and more
+  → AI-powered skills and automation
+  → Team analytics and cost intelligence
+
+Join the beta for early access and updates:
+  https://www.flydocs.ai?utm_source=cli&utm_medium=setup&utm_campaign=beta
+
+─────────────────────────────────────────────────────
+```
+
+---
+
+## Error Handling
+
+Throughout the setup flow:
+
+- **Script failures** — If any mechanism script returns exit code 1, show the
+  error message from stderr and ask the user how to proceed. Do not retry
+  silently.
+- **Missing API key** — For cloud tier, cannot proceed past Phase 2 without
+  `LINEAR_API_KEY`. Guide the user to set it up.
+- **Missing config** — If `.flydocs/config.json` doesn't exist, the user
+  likely needs to run `flydocs` (install) first. Advise them accordingly.
+- **Partial completion** — If the user needs to stop mid-setup, note which
+  phases are complete and which remain. They can re-run the command later
+  and Phase 0 will detect the current state (FlyDocs Update scenario).
+
+---
+
+## Key Rules
+
+1. **Always read the mechanism skill's `SKILL.md`** before running any script.
+   Script calling conventions may differ between tiers.
+2. **All script paths** follow the pattern:
+   `python3 .claude/skills/flydocs-{tier}/scripts/<script>.py`
+   where `{tier}` is read from `.flydocs/config.json`.
+3. **Never skip user confirmation** on project.md content. This is their
+   project definition — they must approve it.
+4. **Never hardcode tier** — always read from config. A project can switch
+   tiers via `flydocs --tier <tier>`.
+5. **Cloud scripts only for cloud tier.** Extended scripts (estimate, priority,
+   milestones, projects) only exist in `flydocs-cloud`. Do not attempt to call
+   them for local tier.
+6. **Capture procedure** — when creating issues during Phase 4, follow the
+   full capture procedure from `.claude/skills/flydocs-workflow/stages/capture.md`.
+
+$ARGUMENTS

package/template/.claude/commands/flydocs-update.md

@@ -0,0 +1,27 @@
+# FlyDocs Update (System)
+
+Check for and apply FlyDocs updates to this project.
+
+## Steps
+
+1. **Check current version** — read `.flydocs/version` and report it.
+2. **Show changelog** — read `.flydocs/CHANGELOG.md` and summarize recent changes
+   since the installed version.
+3. **Run update** — execute `flydocs update` (or `install.sh --update` if using
+   the bash CLI) to update skills, commands, hooks, and config to the latest
+   version. Preserves project-specific content in `flydocs/context/project.md`
+   and user config in `.flydocs/config.json`.
+4. **Post-update** — if version changed, suggest running `/flydocs-setup` to review
+   any new config options or migrate legacy content.
+5. **Beta reminder** — always end with:
+
+```
+─────────────────────────────────────────────────────
+
+Join the FlyDocs beta for early access to premium features and updates:
+  https://www.flydocs.ai?utm_source=cli&utm_medium=update&utm_campaign=beta
+
+─────────────────────────────────────────────────────
+```
+
+$ARGUMENTS

package/template/.claude/commands/implement.md

@@ -0,0 +1,10 @@
+# Implement (Implementation Agent)
+
+Build the feature or fix, following the implementation checklist.
+
+Read `.claude/skills/flydocs-workflow/stages/implement.md` and follow the procedure.
+Read the active mechanism skill's `SKILL.md` for script calling conventions.
+
+Triggers: "implement", "build this", "start coding", "pick up"
+
+$ARGUMENTS

package/template/.claude/commands/new-project.md

@@ -0,0 +1,11 @@
+# New Project (PM/Planning Agent)
+
+Create a new project and add it to active projects in config.
+
+Use `create_project.py` from the active mechanism skill (cloud only).
+For local tier: create project directory structure manually.
+Update `.flydocs/config.json` with the new project ID in `workspace.activeProjects`.
+
+Triggers: "new project", "create project", "start a new project"
+
+$ARGUMENTS

package/template/.claude/commands/project-update.md

@@ -0,0 +1,10 @@
+# Project Update (PM/Planning Agent)
+
+Post a project health update (onTrack, atRisk, offTrack).
+
+Use `project_update.py` from the active mechanism skill (cloud only).
+For local tier: append update to `flydocs/context/project.md` Active Priorities section.
+
+Triggers: "project update", "health update", "post update"
+
+$ARGUMENTS

package/template/.claude/commands/refine.md

@@ -0,0 +1,10 @@
+# Refine (PM/Planning Agent)
+
+Triage a raw capture or refine an existing issue's spec, priority, and estimate.
+
+Read `.claude/skills/flydocs-workflow/stages/refine.md` and follow the procedure.
+Read the active mechanism skill's `SKILL.md` for script calling conventions.
+
+Triggers: "refine this", "triage", "flesh out", "add details to"
+
+$ARGUMENTS

package/template/.claude/commands/review.md

@@ -0,0 +1,10 @@
+# Review (PM/Planning Agent)
+
+Code review — verify acceptance criteria, code quality, and test coverage.
+
+Read `.claude/skills/flydocs-workflow/stages/review.md` and follow the procedure.
+Read the active mechanism skill's `SKILL.md` for script calling conventions.
+
+Triggers: "review", "code review", "check this"
+
+$ARGUMENTS

package/template/.claude/commands/start-session.md

@@ -0,0 +1,10 @@
+# Start Session (PM/Planning Agent)
+
+Begin a work session — check active work, stale issues, and present a status dashboard.
+
+Read `.claude/skills/flydocs-workflow/session.md` and follow the session start procedure.
+Read the active mechanism skill's `SKILL.md` for script calling conventions.
+
+Triggers: "start session", "what's going on", "pick up where I left off"
+
+$ARGUMENTS