@flydocs/cli 0.6.0-alpha.1 → 0.6.0-alpha.11

package/template/.claude/skills/flydocs-workflow/stages/review.md

@@ -16,7 +16,8 @@ Validate code quality, standards compliance, and acceptance criteria completion.
 - Issue description (acceptance criteria)
 - Implementation summary comment (what was built)
 - Installed community skills relevant to the code (check `.claude/skills/` for available patterns)
-- Changed files (from git diff or implementation notes)
+- Changed files — prefer PR diff if a PR exists, otherwise git diff or implementation notes
+- `reference/pr-workflow.md` for branch and commit conventions
 
 ### 2. Verify Acceptance Criteria
 
@@ -47,7 +48,16 @@ Check against project standards and installed community skills:
 - Tests are meaningful (not just coverage)
 - Edge cases considered
 
-### 5. Decision
+### 5. Knowledge Verification
+
+If the issue template includes a Documentation section with "Knowledge base updated" checkbox:
+
+- Verify knowledge doc was created or updated (check `knowledge/INDEX.md` for new entries)
+- If the checkbox is unchecked and implementation involved significant decisions or discoveries, flag it
+
+This is a soft gate — not all issues require knowledge docs. Flag only when implementation clearly warrants documentation that wasn't captured.
+
+### 6. Decision
 
 **If approved:**
 
@@ -61,11 +71,13 @@ Check against project standards and installed community skills:
 ## Review Boundaries
 
 The review agent:
+
 - Analyzes code quality and documents findings
 - Validates against standards and criteria
 - Transitions issue state
 
 The review agent does NOT:
+
 - Edit or write code
 - Fix issues directly
 - Approve incomplete work

package/template/.flydocs/config.json

@@ -1,18 +1,16 @@
 {
-  "version": "0.6.0-alpha.1",
+  "version": "0.6.0-alpha.11",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,
+  "workspaceId": null,
   "paths": {
     "content": "flydocs"
   },
-  "provider": {
-    "type": null,
-    "teamId": null
-  },
   "workspace": {
     "activeProjects": [],
     "defaultMilestoneId": null,
+    "repoSlug": null,
     "product": {
       "name": null,
       "labelIds": [],
@@ -21,7 +19,7 @@
     }
   },
   "issueLabels": {
-    "_note": "Run /flydocs-setup to populate these from your Linear team",
+    "_note": "Run /flydocs-setup to populate these from your workspace",
     "category": {
       "feature": null,
       "bug": null,
@@ -50,18 +48,6 @@
     "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,

package/template/.flydocs/hooks/prompt-submit.py

@@ -168,15 +168,38 @@ def get_flydocs_version() -> str | None:
 
 
 def get_setup_nudge() -> str | None:
-    """Check if setup has been completed, return nudge if not."""
+    """Check if setup has been completed, return nudge if not.
+
+    Reads validation cache (written by validate_setup.py) for specific
+    missing items. Falls back to generic nudge if cache is absent.
+    """
     config_file = Path('.flydocs/config.json')
     if not config_file.exists():
         return None
     try:
         config = json.loads(config_file.read_text())
-        # Only nudge if field is explicitly set to false (not missing)
-        if 'setupComplete' in config and config['setupComplete'] is False:
-            return '[Setup incomplete — run /flydocs-setup to configure your project]'
+        if config.get('setupComplete') is not False:
+            return None
+
+        # Check validation cache for specific missing items
+        cache_file = Path('.flydocs/validation-cache.json')
+        if cache_file.exists():
+            try:
+                cache = json.loads(cache_file.read_text())
+                missing = cache.get('missing', [])
+                warnings = cache.get('warnings', [])
+                parts = []
+                if missing:
+                    parts.append(f'missing: {", ".join(missing)}')
+                if warnings:
+                    parts.append(f'warnings: {", ".join(warnings)}')
+                if parts:
+                    detail = '; '.join(parts)
+                    return f'[Setup incomplete — {detail}. Run /flydocs-setup or fix in dashboard]'
+            except (json.JSONDecodeError, OSError, IOError):
+                pass
+
+        return '[Setup incomplete — run /flydocs-setup to configure your project]'
     except (json.JSONDecodeError, OSError, IOError):
         pass
     return None

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.1
+0.6.0-alpha.11

package/template/AGENTS.md

@@ -92,14 +92,14 @@ Follow these rules in every response for consistent, scannable output.
 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  |
+| Skill             | Triggers                                                                                                                                           | Entry                                     |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, 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, knowledge, document, PR, pull request | .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/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]

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

@@ -0,0 +1,25 @@
+---
+title: "[Note title]"
+category: discovery | gotcha | optimization | debugging | integration
+created: YYYY-MM-DD
+lastUpdated: YYYY-MM-DD
+relatedIssues: []
+---
+
+# [Note Title]
+
+## Summary
+
+[One-paragraph summary of the discovery, gotcha, or learning.]
+
+## Details
+
+[Full explanation. Include code examples, error messages, or configuration details as relevant.]
+
+## Impact
+
+[What this affects — which parts of the system, which workflows, which developers need to know.]
+
+## Resolution / Workaround
+
+[If applicable — what was done to address this, or how to work around it.]

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.1",
+  "version": "0.6.0-alpha.11",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",
 
@@ -45,6 +45,7 @@
         ".claude/commands/start-session.md",
         ".claude/commands/status.md",
         ".claude/commands/validate.md",
+        ".claude/commands/knowledge.md",
         ".claude/commands/wrap-session.md",
         ".claude/skills/README.md",
         ".cursor/hooks.json",
@@ -96,6 +97,9 @@
         "flydocs/knowledge/product/personas.md",
         "flydocs/knowledge/product/user-flows.md",
         "flydocs/README.md",
+        "flydocs/knowledge/templates/decision.md",
+        "flydocs/knowledge/templates/feature.md",
+        "flydocs/knowledge/templates/note.md",
         "flydocs/design-system/README.md",
         "flydocs/design-system/token-mapping.md",
         "flydocs/design-system/component-patterns.md"
@@ -125,6 +129,7 @@
           "flydocs-update.md",
           "flydocs-upgrade.md",
           "implement.md",
+          "knowledge.md",
           "new-project.md",
           "project-update.md",
           "refine.md",
@@ -177,7 +182,8 @@
         ],
         "knowledge": {
           "root": ["INDEX.md", "README.md"],
-          "product": ["personas.md", "user-flows.md"]
+          "product": ["personas.md", "user-flows.md"],
+          "templates": ["decision.md", "feature.md", "note.md"]
         }
       },
       "root": ["AGENTS.md", ".env.example"]