@flydocs/cli 0.6.0-alpha.4 → 0.6.0-alpha.6

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

@@ -20,6 +20,7 @@ Build, test, simplify, and hand off to code review.
 ### 2. Show Implementation Checklist
 
 Present to the user:
+
 - Issue ID and title
 - All acceptance criteria
 - Estimate
@@ -46,7 +47,18 @@ Rationale: [Why this choice over alternatives]
 
 For significant architectural decisions, also create a record in `knowledge/decisions/`.
 
-### 5. TODO to Issue
+### 5. Knowledge Capture Check
+
+Before moving to self-review, check if any of these occurred during implementation:
+
+- **Architectural decision** — framework choice, pattern established, approach rejected
+- **Discovery** — API quirk, debugging technique, non-obvious behavior
+- **Workaround** — limitation found, temporary fix applied
+- **Pattern** — reusable approach that future work should follow
+
+If yes, prompt the user: "Should we capture this in a knowledge doc?" Use `/knowledge` to create the doc, or note it for session wrap if the user wants to defer.
+
+### 6. TODO to Issue
 
 When adding a TODO comment in code:
 
@@ -56,7 +68,7 @@ When adding a TODO comment in code:
 
 Every TODO must have a tracked issue. No orphaned TODOs.
 
-### 6. Simplify
+### 7. Simplify
 
 After implementation is functionally complete, review modified files for:
 
@@ -67,7 +79,7 @@ After implementation is functionally complete, review modified files for:
 
 Apply standards from installed community skills and `preferences.md`. Preserve all functionality.
 
-### 7. Self-Review
+### 8. Self-Review
 
 Before handing off:
 
@@ -77,7 +89,18 @@ Before handing off:
 - [ ] No obvious security issues
 - [ ] No orphaned TODOs
 
-### 8. Hand Off to Review
+### 9. Create PR (if applicable)
+
+See `reference/pr-workflow.md` for full conventions. If changes warrant a PR:
+
+1. Create branch: `git checkout -b <type>/<ref>-<slug>`
+2. Stage and commit with a descriptive message: `<type>: <description> (<ref>)`
+3. Push: `git push -u origin <branch>`
+4. Create PR linking the issue, using the PR description template
+
+If the user requested a direct commit or changes are trivial, skip the PR and commit directly.
+
+### 10. Hand Off to Review
 
 Transition to Review via `transition.py` with the "Ready for Review" comment from `reference/comment-templates.md`. Include:
 
@@ -85,6 +108,7 @@ Transition to Review via `transition.py` with the "Ready for Review" comment fro
 - File count
 - How it was tested
 - Criteria completion count
+- PR link (if PR was created)
 
 ## Checkbox Protocol
 

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

@@ -32,14 +32,30 @@ For backlog items that need fleshing out before activation:
 5. **Add technical notes** — Implementation guidance, dependencies, affected areas.
 6. **Set estimate and priority** — If not already set. See `reference/priority-estimates.md`.
 7. **Check dependencies** — Blocked by other issues? Related work?
-8. **Update description** — `update_description.py` with refined content.
-9. **Transition to Ready** — `transition.py` with Refine comment from `reference/comment-templates.md`.
+8. **Assign milestone** — If the issue fits a current or upcoming milestone, assign it via `--milestone` on `update_issue.py`. If no milestone is appropriate, leave unassigned but note it.
+9. **Update description** — `update_description.py` with refined content.
+10. **Quality gate check** — Verify all criteria pass before transitioning:
+
+| Gate                | Check                                            | Required |
+| ------------------- | ------------------------------------------------ | -------- |
+| Description         | Context section filled, not just a title         | Yes      |
+| Acceptance criteria | Specific, testable, written as checkboxes        | Yes      |
+| Estimate            | Set (see `reference/priority-estimates.md`)      | Yes      |
+| Priority            | Set (P1-P4)                                      | Yes      |
+| Labels              | Category label applied, repo label if multi-repo | Yes      |
+| Dependencies        | Identified and documented, or explicitly "none"  | Yes      |
+| Milestone           | Assigned if applicable                           | No       |
+
+If any required gate fails, address it before transitioning.
+
+11. **Transition to Ready** — `transition.py` with Refine comment from `reference/comment-templates.md`.
 
 ## Gates
 
+- All quality gate checks pass (see table above)
 - Acceptance criteria defined (specific, testable, as checkboxes)
-- Estimate set (1-5)
-- Priority set (1-4)
+- Estimate set
+- Priority set (P1-P4)
 
 ## Outputs
 

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,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.4",
+  "version": "0.6.0-alpha.6",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,
@@ -21,7 +21,7 @@
     }
   },
   "issueLabels": {
-    "_note": "Run /flydocs-setup to populate these from your Linear team",
+    "_note": "Run /flydocs-setup to populate these from your provider",
     "category": {
       "feature": null,
       "bug": null,

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.4
+0.6.0-alpha.6

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/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.4",
+  "version": "0.6.0-alpha.6",
   "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"]