@flydocs/cli 0.6.0-alpha.2 → 0.6.0-alpha.21

package/template/.flydocs/templates/README.md

@@ -1,31 +1,33 @@
 # Issue Templates
 
-This folder contains templates for creating and refining Linear issues. Each template includes agent instructions to ensure consistent, high-quality issue structure.
+This folder contains templates for creating and refining issues. Each template includes agent instructions to ensure consistent, high-quality issue structure.
 
 ## Template Usage
 
 **Agents use these templates when:**
+
 - Creating new issues via `/capture`
 - Refining issues via `/refine`
 - Triaging quick captures with `triage` label
 
-**Humans use `quick-capture.md` in Linear** as the default template for fast idea/bug capture.
+**Humans use `quick-capture.md` in their issue tracker** as the default template for fast idea/bug capture.
 
 ## Available Templates
 
-| Template | Purpose | When to Use |
-|----------|---------|-------------|
-| `feature.md` | New functionality | Building something new with user story |
-| `bug.md` | Fix defects | Something is broken |
-| `chore.md` | Maintenance/cleanup | Refactoring, polish, improvements |
-| `idea.md` | Capture concepts | Rough ideas for future exploration |
-| `quick-capture.md` | Fast capture | Human entry in Linear (default template) |
+| Template           | Purpose             | When to Use                                     |
+| ------------------ | ------------------- | ----------------------------------------------- |
+| `feature.md`       | New functionality   | Building something new with user story          |
+| `bug.md`           | Fix defects         | Something is broken                             |
+| `chore.md`         | Maintenance/cleanup | Refactoring, polish, improvements               |
+| `idea.md`          | Capture concepts    | Rough ideas for future exploration              |
+| `quick-capture.md` | Fast capture        | Human entry in issue tracker (default template) |
 
 ## Agent Instructions
 
-Each template contains `<!-- AGENT: ... -->` comments that guide the AI when filling out sections. These instructions are removed from the final issue in Linear.
+Each template contains `<!-- AGENT: ... -->` comments that guide the AI when filling out sections. These instructions are removed from the final issue in your provider.
 
 **Key principles:**
+
 1. Fill all `[bracketed]` sections with specific content
 2. Don't remove sections - mark as "N/A" if not applicable
 3. Be specific in acceptance criteria (testable, measurable)
@@ -35,12 +37,9 @@ Each template contains `<!-- AGENT: ... -->` comments that guide the AI when fil
 ## Template Evolution
 
 Update these templates as your workflow evolves:
+
 - Add sections that are consistently needed
 - Remove sections that are never used
 - Improve agent instructions based on what works
 
 Changes here apply to all future issues.
-
-
-
-

package/template/.flydocs/templates/quick-capture.md

@@ -1,8 +1,8 @@
-<!-- 
-LINEAR DEFAULT TEMPLATE
+<!--
+PROVIDER DEFAULT TEMPLATE
 ========================
-Copy this to Linear as the default issue template.
-This is the ONLY template humans need in Linear.
+Copy this to your issue tracker as the default issue template.
+This is the ONLY template humans need in their issue tracker.
 Agents apply full templates via /refine.
 -->
 
@@ -29,7 +29,3 @@ Agents apply full templates via /refine.
 ---
 
 _Add `triage` label. Agent will classify and structure via `/refine`._
-
-
-
-

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.2
+0.6.0-alpha.21

package/template/AGENTS.md

@@ -1,17 +1,24 @@
 # FlyDocs Agent Instructions
 
-Prefer reading project documentation over guessing from training data.
-When performing workflow, issue management, or process tasks, consult the
-relevant documentation files before acting.
+## Automatic Workflow Behavior
 
-## Rules
+These behaviors are **always on**. Execute them automatically as part of doing
+the work — do not wait for explicit commands.
 
-1. **Use scripts for all issue operations.** Create, transition, comment, assign — execute scripts, don't describe actions.
-2. **Every status transition gets a comment.** No silent moves.
-3. **Assignment required before In Progress.** Always assign before starting work.
-4. **Checkboxes live in issue description, never comments.** Update the description to track progress.
-5. **Session wrap posts a summary.** Summarize progress at end of session.
-6. **No secrets in commits.** Never commit `.env`, credentials, or API keys.
+- **Starting work on an issue** → transition to In Progress (assign first if needed)
+- **Completing implementation** → transition to Review with summary
+- **Closing** → verify acceptance criteria, transition to Complete
+- **Every transition gets a comment** — no silent moves, no exceptions
+- **Checkboxes in description, never comments** — update AC as you go
+- **Session wrap posts a summary** via `session.py project-update`
+
+Use dispatcher scripts for all issue operations — execute, don't describe.
+
+## Efficiency
+
+Do NOT read skill files or workflow documentation before writing code.
+The rules above are already in your context. For general coding, research,
+and building features — just do the work.
 
 ## Workflow
 
@@ -37,16 +44,20 @@ Detailed procedures: `.claude/skills/flydocs-workflow/`
 
 Scripts handle all issue management. The active backend (local files or cloud provider) determines the implementation.
 
-**Available operations:** create issue, transition status, add comment, list issues, get issue details, assign, update description, status summary.
+**Available operations:** create issue, transition status, add comment, list issues, get issue details, assign, update description, estimate, priority, link, block, project update, status summary.
 
-Script location: `.claude/skills/flydocs-local/scripts/` or `.claude/skills/flydocs-cloud/scripts/`
+Scripts use grouped dispatchers in `.claude/skills/flydocs-workflow/scripts/`:
 
-## Premium Skills
+| Dispatcher       | Operations                                                   |
+| ---------------- | ------------------------------------------------------------ |
+| `issues.py`      | create, get, list, transition, assign, update, comment, etc. |
+| `projects.py`    | list-projects, create-project, milestones, cycles            |
+| `workspace.py`   | validate, labels, statuses, teams, config, identity          |
+| `session.py`     | project-update, status-summary                               |
+| `graph_*.py`     | build, query, update, session recording                      |
+| `push/pull_*.py` | Service descriptor sync (cloud tier)                         |
 
-| Skill             | Documentation                                                           |
-| ----------------- | ----------------------------------------------------------------------- |
-| Figma Integration | `.claude/skills/flydocs-figma/` — design extraction, token mapping      |
-| Cost Estimation   | `.claude/skills/flydocs-estimates/` — AI token/labor estimates (opt-in) |
+The unified client auto-detects tier (cloud vs local) — scripts never check tier directly.
 
 ## Writing Style
 
@@ -80,26 +91,22 @@ Follow these rules in every response for consistent, scannable output.
 
 ## Project Context
 
-| File                         | Purpose                                                 |
-| ---------------------------- | ------------------------------------------------------- |
-| `flydocs/context/project.md` | Product scope, tech stack, active priorities            |
-| `.flydocs/config.json`       | Configuration — tier, provider, labels, active projects |
+| File                           | Purpose                                           |
+| ------------------------------ | ------------------------------------------------- |
+| `flydocs/context/project.md`   | Product scope, tech stack, active priorities      |
+| `flydocs/context/service.json` | Service descriptor, topology, cross-repo context  |
+| `.flydocs/config.json`         | Tier, provider, labels, active projects, topology |
 
 <!-- flydocs:skills-manifest:start -->
 
 ## Skills Index
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
-Consult the relevant skill BEFORE writing code or making workflow decisions.
-
-| Skill             | Triggers                                                                                                                | Entry                                     |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, Linear, cloud | .claude/skills/flydocs-cloud/SKILL.md     |
-| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                               | .claude/skills/flydocs-context7/SKILL.md  |
-| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                   | .claude/skills/flydocs-estimates/SKILL.md |
-| flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                           | .claude/skills/flydocs-figma/SKILL.md     |
-| flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                       | .claude/skills/flydocs-local/SKILL.md     |
-| flydocs-workflow  | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue             | .claude/skills/flydocs-workflow/SKILL.md  |
+Consult the workflow skill for **issue operations and status transitions only**.
+For general coding tasks, skip this — just write code.
+
+| Skill            | Triggers                                                                                                                                                                                                                         | Entry                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| flydocs-workflow | create issue, capture issue, log a bug, add to backlog, transition, move to, mark as, set status, assign issue, close issue, start session, wrap session, project update, status update, add comment, set priority, set estimate | .claude/skills/flydocs-workflow/SKILL.md |
 
 <!-- flydocs:skills-manifest:end -->
 

package/template/CHANGELOG.md

@@ -7,6 +7,45 @@ Versioning: [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.6.0-alpha.4] — 2026-03-13
+
+### Added
+
+- **Status mapping** — new `list_statuses.py` and `set_status_mapping.py`
+  scripts. Setup flow auto-maps provider workflow states to FlyDocs statuses
+  after label config, warns on unmapped statuses without blocking.
+
+---
+
+## [0.6.0-alpha.3] — 2026-03-13
+
+### Added
+
+- **Provider selection** — new `list_providers.py` and `set_provider.py`
+  scripts for multi-provider support (Linear + Jira). Setup flow detects
+  connected providers before team selection.
+- **Inline API key prompt** — `flydocs install` now prompts for FlyDocs API
+  key when cloud tier is selected. No separate `flydocs connect` step needed.
+- **Existing config detection** — install detects pre-existing `.claude/CLAUDE.md`,
+  `settings.json`, `hooks.json`, and `AGENTS.md`. Prompts user to overwrite
+  (with backup) or preserve.
+- **`--project` flag** — `create_issue.py` accepts `--project <id>` to scope
+  issues to a specific project. Fixes milestone/project mismatch during setup.
+- **Team creation** — `create_team.py` with `--parent` flag for sub-teams.
+
+### Changed
+
+- **Setup flow restructured** — Phase 2 now starts with provider detection,
+  then team selection, project, labels. Milestones and issues pass `--project`.
+- **Community skill output** — install shows one line per skill instead of
+  4-5 verbose lines. "No triggers" warning suppressed for community skills.
+- **`/flydocs-upgrade` streamlined** — Phase 1 inlines API key handling
+  instead of requiring a separate terminal step.
+- **API key helpers extracted** — shared `api-key.ts` module used by both
+  `install` and `connect` commands.
+
+---
+
 ## [0.6.0-alpha.1] — 2026-03-12
 
 ### Added

package/template/flydocs/README.md

@@ -30,8 +30,6 @@ FlyDocs will **never overwrite** these files during updates - they're yours to m
 ├── config.json            # Tier, 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)
@@ -153,7 +151,7 @@ See `.flydocs/config.json` for:
 - FlyDocs version
 - `tier` - "local" (free) or "cloud" (connected to provider)
 - `paths.content` - This folder name (default: "flydocs")
-- `provider.type` - Issue tracker provider (null for local, "linear" for cloud)
+- `provider.type` - Issue tracker provider (null for local, e.g. "linear", "jira" for cloud)
 - `workspace.activeProjects` - Array of active project IDs (cloud tier)
 - `workspace.product` - Product identity (name, labelIds, icon, color)
 - `statusMapping` - Workflow state names

package/template/flydocs/context/project.md

@@ -3,11 +3,13 @@
 ## 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]
@@ -20,8 +22,8 @@
 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`.
+Installed community skills provide domain-specific patterns. List them with
+`npx flydocs skills list`.
 
 ### Project-Specific Standards
 
@@ -36,6 +38,7 @@ 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]
@@ -48,4 +51,4 @@ Project notes: `flydocs/knowledge/notes/`
 
 ---
 
-*Last Updated: YYYY-MM-DD*
+_Last Updated: YYYY-MM-DD_

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

@@ -6,7 +6,7 @@
 
 ## Purpose
 
-When using the `flydocs-figma` skill to extract designs, the AI needs to know:
+When using the workflow skill's Figma capabilities 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)
@@ -83,9 +83,9 @@ flydocs/design-system/
 
 ---
 
-## Integration with flydocs-figma Skill
+## Integration with Figma Workflow
 
-The `flydocs-figma` skill references this directory:
+The `flydocs-workflow` skill's Figma capabilities reference this directory:
 
 1. **Before extraction** - Loads token-mapping.md for translation rules
 2. **During extraction** - Matches Figma elements to documented patterns

package/template/flydocs/knowledge/INDEX.md

@@ -4,97 +4,82 @@
 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
+- Update this index when adding or modifying knowledge docs
+- Always use real dates, never leave as YYYY-MM-DD
 -->
 
 ## Quick Reference
 
-| Category | Count | Last Updated |
-|----------|-------|--------------|
-| Decisions | 0 | - |
-| Features | 0 | - |
-| Notes | 0 | - |
-| Product | 2 | YYYY-MM-DD |
+| Category  | Count | Last Updated |
+| --------- | ----- | ------------ |
+| Decisions | 0     | -            |
+| Features  | 0     | -            |
+| Notes     | 0     | -            |
+| Product   | 2     | -            |
 
 ---
 
-## 📋 Decisions (ADRs)
+## Decisions (ADRs)
 
-Architecture Decision Records - why we made key technical choices.
+Architecture Decision Records — why we made key technical choices.
 
-| ID | Title | Status | Date |
-|----|-------|--------|------|
-| - | No decisions recorded yet | - | - |
+| 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
+| 001 | Use Convex for Backend | Accepted | 2026-01-15 |
+  -> Explains why we chose Convex over traditional REST API
 -->
 
 ---
 
-## 🔧 Features
+## Features
 
 Documentation for complex features that need more than a spec.
 
-| Feature | Description | Last Updated |
-|---------|-------------|--------------|
-| - | No feature docs yet | - |
+| 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
+| auth-system | Complete auth flow documentation | 2026-02-01 |
+  -> OAuth setup, session handling, role-based access
 -->
 
 ---
 
-## 📝 Notes
+## Notes
 
 Technical discoveries, gotchas, learnings.
 
-| Topic | Description | Added |
-|-------|-------------|-------|
-| - | No notes yet | - |
+| 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.
+| api-rate-limits | Third-party API quirks and workarounds | 2026-01-20 |
+  -> Stripe webhook retries, Figma API limits, etc.
 -->
 
 ---
 
-## 👥 Product
+## 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 |
+| Document      | Description          | Last Updated |
+| ------------- | -------------------- | ------------ |
+| personas.md   | Target user profiles | -            |
+| user-flows.md | Key user journeys    | -            |
 
 ---
 
 ## 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*
-
+1. Choose the category: decision, feature, note, or product
+2. Copy the template from `templates/<category>.md`
+3. Fill in the frontmatter (title, created date, related issues)
+4. Write the content following the template structure
+5. Add an entry to this index with a concise description
+6. Use the `/knowledge` command for a guided flow

package/template/flydocs/knowledge/README.md

@@ -6,42 +6,78 @@ This directory contains project knowledge that accumulates over time.
 
 ```
 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
+├── INDEX.md       # Start here — inventory of all knowledge
+├── templates/     # Structural templates for each category
+├── decisions/     # Architecture Decision Records (ADRs)
+├── features/      # Complex feature documentation
+├── notes/         # Technical discoveries and learnings
+└── product/       # User research and product docs
 ```
 
-## When to Add Knowledge
+## Templates
+
+Use templates from `templates/` when creating new knowledge docs. Each template includes
+a frontmatter block with required metadata fields.
+
+### Required Frontmatter
+
+All knowledge docs must include YAML frontmatter:
+
+```yaml
+---
+title: "Descriptive title"
+created: 2026-03-17
+lastUpdated: 2026-03-17
+relatedIssues: [FLY-123, FLY-456]
+---
+```
+
+Additional fields vary by category — see the template for each type.
+
+**Always update `lastUpdated`** when modifying an existing doc.
+
+## When to Create 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
+- Rejecting an approach (document why, so others don't repeat the investigation)
 
 **Format**: `NNN-title.md` (e.g., `001-use-convex.md`)
+**Template**: `templates/decision.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`)
+**Template**: `templates/feature.md`
 
 ### Notes (`notes/`)
+
 Add notes when you discover:
+
 - API quirks or gotchas
 - Performance optimizations
 - Debugging techniques
 - Third-party service behaviors
+- Workarounds that aren't obvious from code
 
 **Format**: `topic-name.md` (e.g., `stripe-webhooks.md`)
+**Template**: `templates/note.md`
 
 ### Product (`product/`)
+
 Add product docs for:
+
 - User personas
 - User flows and journeys
 - Research findings
@@ -49,14 +85,29 @@ Add product docs for:
 
 **Format**: `document-name.md` (e.g., `personas.md`)
 
+## When to Prompt for Knowledge Capture
+
+Proactively suggest creating a knowledge doc when:
+
+- An architectural decision was made during implementation
+- A non-obvious workaround or debugging technique was discovered
+- A third-party API or integration behavior was learned through trial and error
+- A pattern was established that future work should follow
+- A significant feature was completed that spans multiple issues
+
+The `/knowledge` command provides a guided flow for creating docs.
+
 ## Always Update INDEX.md
 
-When adding any knowledge document, update `INDEX.md` so agents can discover it.
+When adding or modifying any knowledge document:
+
+1. Add or update the entry in `INDEX.md`
+2. Set the date to the current date (never leave as `YYYY-MM-DD`)
+3. Write a concise description that helps agents assess relevance without loading the full doc
 
 ## Relationship to Specs
 
-- **Specs** (in Linear) = What we're building now
+- **Specs** (in issue tracker) = 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/templates/decision.md

@@ -0,0 +1,47 @@
+---
+id: NNN
+title: "[Decision title]"
+status: proposed | accepted | deprecated | superseded
+created: YYYY-MM-DD
+lastUpdated: YYYY-MM-DD
+relatedIssues: []
+supersededBy: null
+---
+
+# NNN — [Decision Title]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by NNN]
+
+## Context
+
+[What is the problem or situation that requires a decision? Include relevant constraints, requirements, and prior art.]
+
+## Decision
+
+[What was decided. Be specific — name the technology, pattern, or approach chosen.]
+
+## Alternatives Considered
+
+| Option          | Pros         | Cons                 |
+| --------------- | ------------ | -------------------- |
+| [Chosen option] | [Advantages] | [Tradeoffs accepted] |
+| [Alternative 1] | [Advantages] | [Why not chosen]     |
+| [Alternative 2] | [Advantages] | [Why not chosen]     |
+
+## Consequences
+
+**Positive:**
+
+- [Benefit 1]
+- [Benefit 2]
+
+**Negative / Tradeoffs:**
+
+- [Tradeoff 1]
+- [Tradeoff 2]
+
+**Follow-up actions:**
+
+- [Action needed as a result of this decision]

package/template/flydocs/knowledge/templates/feature.md

@@ -0,0 +1,35 @@
+---
+title: "[Feature name]"
+status: draft | current | deprecated
+created: YYYY-MM-DD
+lastUpdated: YYYY-MM-DD
+relatedIssues: []
+---
+
+# [Feature Name]
+
+## Overview
+
+[What this feature does and why it exists. 2-3 sentences.]
+
+## Architecture
+
+[How the feature is structured — key components, data flow, integration points.]
+
+## Key Files
+
+| File           | Purpose                        |
+| -------------- | ------------------------------ |
+| `path/to/file` | [What it does in this feature] |
+
+## Behaviors
+
+[Important behaviors, edge cases, or business rules that aren't obvious from code alone.]
+
+## Configuration
+
+[Any config, env vars, or feature flags that affect this feature.]
+
+## Related
+
+- [Links to related issues, decisions, or other knowledge docs]