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

package/template/.claude/skills/flydocs-workflow/SKILL.md

@@ -17,6 +17,10 @@ triggers:
   - transition
   - status
   - issue
+  - knowledge
+  - document
+  - PR
+  - pull request
 ---
 
 # FlyDocs Workflow
@@ -35,32 +39,33 @@ Capture → Refine → Activate → Implement → Review → Validate → Close
 
 ## Stage Index
 
-| Stage | File | Intent | Agent |
-|-------|------|--------|-------|
-| Capture | stages/capture.md | Create issue from input | PM |
-| Refine | stages/refine.md | Triage + spec completion | PM |
-| Activate | stages/activate.md | Assign + start work | PM |
-| Implement | stages/implement.md | Build + test + simplify | Implementation |
-| Review | stages/review.md | Code quality validation | Review |
-| Validate | stages/validate.md | User acceptance testing | QE |
-| Close | stages/close.md | Archive completed work | PM |
+| Stage     | File                | Intent                   | Agent          |
+| --------- | ------------------- | ------------------------ | -------------- |
+| Capture   | stages/capture.md   | Create issue from input  | PM             |
+| Refine    | stages/refine.md    | Triage + spec completion | PM             |
+| Activate  | stages/activate.md  | Assign + start work      | PM             |
+| Implement | stages/implement.md | Build + test + simplify  | Implementation |
+| Review    | stages/review.md    | Code quality validation  | Review         |
+| Validate  | stages/validate.md  | User acceptance testing  | QE             |
+| Close     | stages/close.md     | Archive completed work   | PM             |
 
 ## Session
 
-| Action | File |
-|--------|------|
-| Start session | session.md |
-| Wrap session | session.md |
+| Action          | File       |
+| --------------- | ---------- |
+| Start session   | session.md |
+| Wrap session    | session.md |
 | Stale detection | session.md |
 
 ## Reference
 
-| Topic | File |
-|-------|------|
-| Comment templates | reference/comment-templates.md |
-| Status transitions | reference/status-workflow.md |
+| Topic                | File                            |
+| -------------------- | ------------------------------- |
+| Comment templates    | reference/comment-templates.md  |
+| Status transitions   | reference/status-workflow.md    |
 | Priority & estimates | reference/priority-estimates.md |
-| Golden rules | reference/golden-rules.md |
+| PR & git workflow    | reference/pr-workflow.md        |
+| Golden rules         | reference/golden-rules.md       |
 
 ## Templates
 

package/template/.claude/skills/flydocs-workflow/reference/comment-templates.md

@@ -56,6 +56,7 @@ Canonical templates for all workflow transitions. Copy exactly, fill bracketed v
 **Files:** [count] modified
 **Testing:** [How it was verified]
 **Criteria:** [X]/[Y] complete
+**PR:** [link or "direct commit"]
 ```
 
 ## Code Review Passed

package/template/.claude/skills/flydocs-workflow/reference/pr-workflow.md

@@ -0,0 +1,105 @@
+# PR & Git Workflow
+
+## Branch Naming
+
+Format: `<type>/<ref>-<slug>`
+
+| Type      | When                                   |
+| --------- | -------------------------------------- |
+| `feature` | New functionality                      |
+| `fix`     | Bug fixes                              |
+| `chore`   | Maintenance, refactoring, dependencies |
+| `docs`    | Documentation only                     |
+
+Examples:
+
+- `feature/FLY-255-knowledge-capture`
+- `fix/FLY-301-login-timeout`
+- `chore/FLY-290-upgrade-deps`
+
+Keep the slug short (2-4 words, kebab-case). Include the issue reference.
+
+## Commit Messages
+
+Format: `<type>: <description> (<ref>)`
+
+- Lead with what changed, not how
+- Use imperative mood ("Add", not "Added")
+- Keep the first line under 72 characters
+- Add a body for non-obvious changes
+
+Examples:
+
+```
+feat: Add knowledge doc templates and /knowledge command (FLY-255)
+fix: Handle null milestone in create_issue response (FLY-301)
+chore: Remove deprecated auth middleware (FLY-290)
+```
+
+## When to Create a PR
+
+**Create a PR when:**
+
+- Changes affect shared code (not just local config or docs)
+- Multiple files changed across different concerns
+- Changes need review before merging
+- Working on a branch (not committing directly to main)
+
+**Commit directly when:**
+
+- Single-file documentation updates
+- Config changes for local development
+- Trivial fixes (typos, formatting)
+- The user explicitly requests direct commit
+
+When in doubt, create a PR. It's easier to merge a PR than to revert a direct commit.
+
+## PR Description Template
+
+```markdown
+## Summary
+
+[1-3 bullet points describing what changed and why]
+
+Closes [ISSUE-REF]
+
+## Changes
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+
+## Test Plan
+
+- [ ] [How to verify change 1]
+- [ ] [How to verify change 2]
+
+## Notes
+
+[Anything reviewers should know — tradeoffs, follow-up work, decisions made]
+```
+
+## PR Workflow in Practice
+
+### During Implement Stage
+
+After self-review (step 7 in `implement.md`), before handing off to review:
+
+1. Create branch: `git checkout -b <type>/<ref>-<slug>`
+2. Stage and commit changes with a descriptive message
+3. Push branch: `git push -u origin <branch>`
+4. Create PR with the template above, linking the issue
+5. Include the PR link in the "Ready for Review" comment
+
+### During Review Stage
+
+The reviewer should:
+
+- Review the PR diff (not just local git diff)
+- Leave comments on the PR for specific code feedback
+- Reference the PR in review comments on the issue
+
+### After Review
+
+- **Approved**: Merge the PR, then transition issue to Testing
+- **Changes needed**: Push fixes to the same branch, re-request review

package/template/.claude/skills/flydocs-workflow/reference/priority-estimates.md

@@ -2,27 +2,49 @@
 
 ## Priority Values
 
-| Value | Name | Use When |
-|-------|------|----------|
-| 0 | None | Not yet triaged |
-| 1 | Urgent | Drop everything, fix now |
-| 2 | High | Next up, unblocks others |
-| 3 | Medium | Normal priority (default) |
-| 4 | Low | Nice to have |
+| Value | Name   | Use When                  |
+| ----- | ------ | ------------------------- |
+| 0     | None   | Not yet triaged           |
+| 1     | Urgent | Drop everything, fix now  |
+| 2     | High   | Next up, unblocks others  |
+| 3     | Medium | Normal priority (default) |
+| 4     | Low    | Nice to have              |
 
 ## Estimate Values (Complexity)
 
-| Value | Name | Rough Effort |
-|-------|------|--------------|
-| 1 | XS | < 1 hour |
-| 2 | S | 1-4 hours |
-| 3 | M | Half day to full day |
-| 4 | L | 2-3 days |
-| 5 | XL | Week+ |
+| Value | Name | Rough Effort         |
+| ----- | ---- | -------------------- |
+| 1     | XS   | < 1 hour             |
+| 2     | S    | 1-4 hours            |
+| 3     | M    | Half day to full day |
+| 4     | L    | 2-3 days             |
+| 5     | XL   | Week+                |
 
 ## Guidance
 
 - Set priority during Refine or Activate stages
 - Set estimate during Refine stage (before Ready)
 - If estimate is missing at Activate, set it before transitioning
-- XL estimates often indicate the issue should be broken into smaller pieces
+- Estimate values may vary by provider — the relay translates per provider configuration
+
+## Decomposition
+
+When an estimate is large (XL / 5+ or provider equivalent), prompt for decomposition:
+
+1. **Identify natural boundaries** — separate concerns, independent deliverables, sequential phases
+2. **Create child issues** — each should be independently estimable at M or smaller
+3. **Link parent to children** — use `link.py` with type `blocks` (parent blocks children conceptually)
+4. **Re-estimate parent** — set to 0 or remove estimate, since children carry the work
+5. **Move parent to a tracking role** — it becomes the "epic" or summary issue
+
+**Split pattern:**
+
+```
+Original: FLY-100 "Build auth system" (XL)
+  → FLY-101 "Add login endpoint" (S)
+  → FLY-102 "Add session management" (M)
+  → FLY-103 "Add role-based access control" (M)
+  → FLY-104 "Add password reset flow" (S)
+```
+
+Don't force decomposition on every large issue — some are genuinely large and atomic. Use judgment. The prompt is: "This is estimated as XL. Can it be broken into smaller, independently deliverable pieces?"

package/template/.claude/skills/flydocs-workflow/session.md

@@ -52,6 +52,7 @@ When a conversation begins or the user returns after a gap:
 
 7. **Surface other product issues briefly** — If there are issues in the product scope
    but outside the active project, mention the count with a one-line summary:
+
    ```
    Also in [Product Name]: [N] issues across other projects (use --all to see)
    ```
@@ -69,10 +70,16 @@ automatically via the config cascade.
 When the user indicates they're done for the session:
 
 1. **Gather session data** — What was completed, what's in progress, what's blocked.
-2. **Compose summary** using the template below.
-3. **Determine health status** — See health table.
-4. **Post project update** — `project_update.py` with health and summary body.
-5. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
+2. **Knowledge capture check** — Review the session's work for uncaptured knowledge:
+   - Were any architectural decisions made?
+   - Were any non-obvious behaviors or workarounds discovered?
+   - Were any patterns established that future work should follow?
+   - Did debugging reveal something worth documenting?
+     If yes, prompt the user: "This session involved [specific discovery]. Should we capture it in a knowledge doc before wrapping?" Use `/knowledge` if they agree.
+3. **Compose summary** using the template below.
+4. **Determine health status** — See health table.
+5. **Post project update** — `project_update.py` with health and summary body.
+6. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
    ```
    python3 .claude/skills/flydocs-context-graph/scripts/graph_session.py \
        --summary "Brief summary of session outcomes" \
@@ -80,8 +87,8 @@ When the user indicates they're done for the session:
        [--decision NNN]
    ```
    This creates a session node for cross-session continuity. Skip silently if the script is not installed.
-6. **Verify** — Confirm the project update was posted (update ID returned).
-7. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
+7. **Verify** — Confirm the project update was posted (update ID returned).
+8. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
 
 Do not just summarize in chat. Actually post the update. Do not skip if the user seems in a hurry.
 
@@ -104,15 +111,16 @@ Do not just summarize in chat. Actually post the update. Do not skip if the user
 
 ### Health Status
 
-| Status | When to Use |
-|--------|-------------|
-| onTrack | Progress made, no blockers |
-| atRisk | Minor delays, attention needed |
+| Status   | When to Use                     |
+| -------- | ------------------------------- |
+| onTrack  | Progress made, no blockers      |
+| atRisk   | Minor delays, attention needed  |
 | offTrack | Major blockers, behind schedule |
 
 ### Wrap Detection Phrases
 
 Offer session wrap when the user says:
+
 - "I'm done for today" / "wrapping up" / "that's it for now"
 - "save progress" / "end of day" / "stopping here"
 
@@ -120,9 +128,9 @@ Offer session wrap when the user says:
 
 Proactively surface issues that may be stuck:
 
-| State | Threshold | Action |
-|-------|-----------|--------|
-| Implementing | > 7 days without activity | Warn |
-| Review | > 3 days without activity | Warn |
-| Testing/QA | > 3 days without activity | Warn |
-| Blocked | Any | Always surface |
+| State        | Threshold                 | Action         |
+| ------------ | ------------------------- | -------------- |
+| Implementing | > 7 days without activity | Warn           |
+| Review       | > 3 days without activity | Warn           |
+| Testing/QA   | > 3 days without activity | Warn           |
+| Blocked      | Any                       | Always surface |

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

@@ -21,9 +21,14 @@ When the user has enough context to describe the issue:
    - **Why** — User story or business value
    - **How** — Technical notes or approach (if known)
    - **Done when** — Acceptance criteria as checkboxes
-4. **Create issue** — `create_issue.py` with title, type, description, priority, and estimate (if known).
-5. **Add comment** — Use the Capture template from `reference/comment-templates.md`.
-6. **Verify** — Confirm issue identifier returned.
+4. **Apply labels** — Include appropriate labels from config:
+   - **Category label**: Automatic from issue type (feature, bug, chore, idea) via `issueLabels.category` in config
+   - **Repo label**: If multi-repo workspace, apply the repo label from `issueLabels.repo` in config
+   - **Product labels**: Applied automatically by the mechanism scripts from `workspace.product.labelIds`
+   - **Ad-hoc labels**: Only if explicitly relevant (e.g., "accessibility", "performance")
+5. **Create issue** — `create_issue.py` with title, type, description, priority, estimate (if known), and labels.
+6. **Add comment** — Use the Capture template from `reference/comment-templates.md`.
+7. **Verify** — Confirm issue identifier returned.
 
 ### Quick Capture
 

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

@@ -11,12 +11,13 @@ Archive verified and completed work.
 ## Steps
 
 1. **Verify QE approval** — Check issue comments for a "QE Approved" comment. If not found, do not close — direct to Validate stage first.
-2. **Determine terminal state:**
+2. **Final knowledge check** — If the issue involved significant implementation, verify `knowledge/INDEX.md` reflects any decisions or discoveries. This is informational — don't block close, but prompt the user if notable knowledge appears uncaptured.
+3. **Determine terminal state:**
    - **Done** — Work completed and verified (normal path)
    - **Archived** — Deferring to a later date (not cancelled, may return)
    - **Canceled** — Not pursuing (won't be done)
-3. **Transition** — `transition.py` with the appropriate Close comment from `reference/comment-templates.md`.
-4. **Verify** — Confirm terminal state reached.
+4. **Transition** — `transition.py` with the appropriate Close comment from `reference/comment-templates.md`.
+5. **Verify** — Confirm terminal state reached.
 
 ## Gates
 

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.5",
+  "version": "0.6.0-alpha.6",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.5
+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, 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 -->