@flydocs/cli 0.5.0-beta.0

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

@@ -0,0 +1,46 @@
+# Activate
+
+## Intent
+
+Assign work to a person and move the issue to In Progress.
+
+## Prerequisites
+
+- Issue exists in Ready or Backlog state with a complete spec
+- Issue is not blocked
+
+## Steps
+
+### Recommendation Mode (no issue specified)
+
+When user asks "what should I work on?":
+
+1. **Query available issues** — `list_issues.py` for Ready and Backlog states.
+2. **Filter** — Exclude blocked issues and issues assigned to others.
+3. **Rank** — Priority (highest first) → unblocked → smaller estimate.
+4. **Present recommendation** — Show top candidates with reasoning.
+5. **Wait for selection** — Do not activate until user confirms.
+
+### Activation (specific issue)
+
+1. **Read full issue** — Load description and acceptance criteria.
+2. **Determine assignee** — MANDATORY. Ask "Who should this be assigned to?" if unclear. This is a hard gate.
+3. **Assign** — `assign.py` with user identifier. If assignment fails, STOP. Do not continue.
+4. **Set metadata** — Priority and estimate if not already set.
+5. **Transition** — `transition.py` to Implementing with Activate comment from `reference/comment-templates.md`.
+6. **Verify** — Confirm state = In Progress and assignee set.
+
+**Sequence matters:** Assign → metadata → transition. Never transition without an assignee.
+
+## Gates
+
+- Assignee set (hard gate — no exceptions)
+- State = In Progress
+
+## Outputs
+
+- Assigned issue in Implementing state with activation comment
+
+## Triggers
+
+- "activate" / "start work on" / "pick up" / "what should I work on?"

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

@@ -0,0 +1,50 @@
+# Capture
+
+## Intent
+
+Create a new issue from user input — either a full spec or a quick idea tagged for later refinement.
+
+## Prerequisites
+
+- Active project configured in `.flydocs/config.json`
+
+## Steps
+
+### Full Capture
+
+When the user has enough context to describe the issue:
+
+1. **Determine type** — feature, bug, chore, or idea. Ask if unclear.
+2. **Select project** — Single active project: use it. Multiple: ask user. None: error.
+3. **Fill template** — Read the appropriate template from `templates/`. Extract from user input:
+   - **What** — Context or problem description
+   - **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.
+
+### Quick Capture
+
+When logging an idea or observation during flow — flesh out later:
+
+1. **Determine type** — Default to `idea` if unclear.
+2. **Create issue** — `create_issue.py --triage` with minimal title and brief context.
+   Issue receives both the category label and the triage label.
+3. **Add comment** — "**Captured** — Quick capture, needs refinement."
+4. Issue sits in Backlog with triage tag. The Refine stage picks it up later.
+
+## Gates
+
+- Issue exists with a valid identifier
+- Capture comment posted
+
+## Outputs
+
+- New issue in Backlog (full or triage-tagged)
+
+## Triggers
+
+- "capture that" / "add to backlog" / "new issue" / "log this"
+- "quick capture" / "jot this down" / "idea:"

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

@@ -0,0 +1,32 @@
+# Close
+
+## Intent
+
+Archive verified and completed work.
+
+## Prerequisites
+
+- QE Approved comment exists on the issue
+
+## 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:**
+   - **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.
+
+## Gates
+
+- QE approval verified
+- Terminal state reached
+
+## Outputs
+
+- Issue in terminal state (Done, Archived, or Canceled)
+
+## Triggers
+
+- "close" / "done" / "archive" / "cancel"

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

@@ -0,0 +1,124 @@
+# Implement
+
+## Intent
+
+Build, test, simplify, and hand off to code review.
+
+## Prerequisites
+
+- Issue assigned and in Implementing state
+- Acceptance criteria defined in issue description
+
+## Steps
+
+### 1. Load Context
+
+- Issue description (full acceptance criteria)
+- `project.md` and `preferences.md` for project standards
+- Installed community skills relevant to the work (check `.claude/skills/` for available patterns)
+
+### 2. Show Implementation Checklist
+
+Present to the user:
+- Issue ID and title
+- All acceptance criteria
+- Estimate
+
+### 3. Implement Incrementally
+
+For each acceptance criterion:
+
+1. Write the code
+2. Write tests (if applicable for this criterion)
+3. Update the checkbox in the issue description (see Checkbox Protocol below)
+4. Add a progress comment if significant milestone reached
+
+### 4. Document Decisions
+
+When making non-obvious technical choices, add an issue comment:
+
+```
+**Decision: [Title]**
+Context: [Why this decision was needed]
+Decision: [What was decided]
+Rationale: [Why this choice over alternatives]
+```
+
+For significant architectural decisions, also create a record in `knowledge/decisions/`.
+
+### 5. TODO to Issue
+
+When adding a TODO comment in code:
+
+1. Write the initial comment: `// TODO: Description`
+2. Create a corresponding issue via `create_issue.py` with type `chore`
+3. Update the comment with the issue ID: `// TODO: Description (ENG-XXX)`
+
+Every TODO must have a tracked issue. No orphaned TODOs.
+
+### 6. Simplify
+
+After implementation is functionally complete, review modified files for:
+
+- Unnecessary complexity or abstraction
+- Redundant code
+- Unclear naming
+- Inconsistency with project patterns
+
+Apply standards from installed community skills and `preferences.md`. Preserve all functionality.
+
+### 7. Self-Review
+
+Before handing off:
+
+- [ ] All acceptance criteria checked in issue description
+- [ ] Tests written and passing
+- [ ] Code follows project standards
+- [ ] No obvious security issues
+- [ ] No orphaned TODOs
+
+### 8. Hand Off to Review
+
+Transition to Review via `transition.py` with the "Ready for Review" comment from `reference/comment-templates.md`. Include:
+
+- What changed (brief summary)
+- File count
+- How it was tested
+- Criteria completion count
+
+## Checkbox Protocol
+
+Checkboxes live in the issue description. Never in comments.
+
+1. Read current description via `get_issue.py`
+2. Find `- [ ] Criterion text`
+3. Change to `- [x] Criterion text`
+4. Save entire updated description via `update_description.py`
+
+**Never** put completion checkmarks in comments. **Never** create new checkboxes in comments.
+
+## Blocking
+
+If blocked during implementation:
+
+1. Document what is blocking and what is needed
+2. Transition via `transition.py` to Blocked with comment from `reference/comment-templates.md`
+3. If blocked by another issue, create a dependency relationship
+
+To unblock: transition back to Implementing with an Unblocked comment.
+
+## Gates
+
+- All acceptance criteria checked in description
+- Tests passing
+- Implementation summary comment posted
+
+## Outputs
+
+- Issue in Review state with summary comment
+- Code changes ready for review
+
+## Triggers
+
+- "implement" / "build" / "code this" / "let's work on"
+- "I'm blocked" / "can't proceed" (blocking path)

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

@@ -0,0 +1,51 @@
+# Refine
+
+## Intent
+
+Triage raw captures and refine issue specs to a "ready" state with complete acceptance criteria.
+
+## Prerequisites
+
+- Issue exists in Backlog
+
+## Steps
+
+### Triage Path (issue has triage tag)
+
+For quick captures that need classification and structure:
+
+1. **Read issue** — Load current content.
+2. **Classify type** — Determine category (feature/bug/chore/idea). Ask if unclear.
+3. **Apply template** — Read appropriate template from `templates/` and restructure the issue content to match.
+4. **Set priority** — P1-P4 based on urgency and impact.
+5. **Update description** — `update_description.py` with templated content.
+6. **Add comment** — Use Triage template from `reference/comment-templates.md`.
+
+### Refinement Path (issue already templated)
+
+For backlog items that need fleshing out before activation:
+
+1. **Load context** — Issue content, `project.md`, `knowledge/INDEX.md`.
+2. **Assess completeness** — Are acceptance criteria specific and testable? Is context clear?
+3. **Identify gaps** — Ask clarifying questions if needed. Don't guess.
+4. **Refine acceptance criteria** — Make each criterion specific, measurable, and testable as a checkbox.
+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`.
+
+## Gates
+
+- Acceptance criteria defined (specific, testable, as checkboxes)
+- Estimate set (1-5)
+- Priority set (1-4)
+
+## Outputs
+
+- Issue in Ready state with complete spec
+- Or triaged issue with template applied, ready for further refinement
+
+## Triggers
+
+- "refine" / "triage" / "flesh out this issue"

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

@@ -0,0 +1,86 @@
+# Review
+
+## Intent
+
+Validate code quality, standards compliance, and acceptance criteria completion.
+
+## Prerequisites
+
+- Issue in Review state
+- Implementation summary comment exists on the issue
+
+## Steps
+
+### 1. Load Context
+
+- 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)
+
+### 2. Verify Acceptance Criteria
+
+**Mandatory.** Check each criterion in the issue description:
+
+- Is it implemented?
+- Is the checkbox marked `[x]`?
+
+If ANY criterion is unchecked or unimplemented, review fails. Document which criteria are incomplete.
+
+### 3. Code Quality Analysis
+
+Check against project standards and installed community skills:
+
+**Structure** — Files in correct locations, naming conventions followed, appropriate separation of concerns.
+
+**Patterns** — Consistent with existing codebase and project patterns. No unnecessary abstractions.
+
+**Error handling** — Errors handled gracefully, user-facing errors are clear, no silent failures.
+
+**Security** — No hardcoded secrets, input validation where needed, no obvious vulnerabilities.
+
+**Performance** — No obvious performance issues, appropriate data fetching, no unnecessary re-renders.
+
+### 4. Test Coverage
+
+- Tests exist for new functionality
+- Tests are meaningful (not just coverage)
+- Edge cases considered
+
+### 5. Decision
+
+**If approved:**
+
+1. Transition to Testing via `transition.py` with "Code Review Passed" comment from `reference/comment-templates.md`.
+
+**If changes needed:**
+
+1. Document specific issues with file/location details.
+2. Transition to Implementing via `transition.py` with "Code Review: Changes Needed" comment listing each issue.
+
+## 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
+- Skip criteria validation
+
+## Gates
+
+- All acceptance criteria verified
+- Code quality analysis complete
+
+## Outputs
+
+- Issue in Testing state (pass) with review comment
+- Or issue in Implementing state (fail) with issues listed
+
+## Triggers
+
+- "review" / "check the code" / "ready for review"

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

@@ -0,0 +1,90 @@
+# Validate
+
+## Intent
+
+Guide the user through acceptance testing and document the results.
+
+## Prerequisites
+
+- Issue in Testing/QA state
+- Code review passed
+
+## Steps
+
+### 1. Load Issue
+
+Read issue description and acceptance criteria.
+
+### 2. Present Testing Session
+
+Show each criterion with testing guidance:
+
+```
+## QA Testing: [ISSUE-ID]
+Issue: [Title]
+
+### Acceptance Criteria to Verify:
+1. [ ] [Criterion 1]
+   → How to test: [guidance]
+2. [ ] [Criterion 2]
+   → How to test: [guidance]
+
+Please test each criterion and let me know:
+- "looks good" / "passes" for criteria that work
+- Describe any issues you find
+```
+
+### 3. Wait for User Feedback
+
+### 4. Process Results
+
+**On approval** — Recognition phrases: "looks good", "approve", "ship it", "all good", "works for me", "approved", "QE passed"
+
+1. Confirm with user: "Confirming QA approval for [ISSUE-ID]?"
+2. Add "QE Approved" comment from `reference/comment-templates.md`
+3. Respond: issue is ready for PM to close via `/close`
+
+**On issues found:**
+
+1. Document issues clearly. Ask clarifying questions if needed.
+2. Transition to Implementing via `transition.py` with "QE Issues Found" comment listing each issue.
+
+**On partial issues:**
+
+1. Clarify what passed vs what failed.
+2. Add "QE Partial" comment documenting both.
+3. Transition to Implementing.
+
+### 5. Re-Testing (issue returns to QA)
+
+1. Note this is a re-test.
+2. Show previous issues from the "QE Issues Found" comment.
+3. Focus re-test on the fixed items.
+4. Continue with normal approval/issues flow.
+
+## QE Boundaries
+
+The QE agent:
+- Guides user through testing
+- Documents approval or issues
+- Transitions back to Implementing if issues found
+
+The QE agent NEVER:
+- Moves issues to Done or closes them
+- Skips documenting results
+- Approves without user confirmation
+
+Closing is the PM agent's responsibility via the Close stage.
+
+## Gates
+
+- User explicitly approves, or issues are documented and returned to Implementing
+
+## Outputs
+
+- QE Approved comment (pass) — ready for Close stage
+- Or issue back in Implementing (fail) with issues documented
+
+## Triggers
+
+- "test this" / "QE test" / "validate"

package/template/.claude/skills/flydocs-workflow/templates/bug.md

@@ -0,0 +1,95 @@
+## Context
+
+**When Discovered:** [Date or event when bug was found]
+**Discovered By:** [User, developer, automated test, etc.]
+**Impact:** [How this affects users - be specific about scope]
+**Frequency:** [Always | Sometimes | Rarely | Under specific conditions]
+
+[Additional context about the bug]
+
+---
+
+## Bug Description
+
+### Expected Behavior
+[Describe what SHOULD happen - the correct behavior]
+
+### Actual Behavior
+[Describe what ACTUALLY happens - the broken behavior]
+
+### Steps to Reproduce
+1. [First action - be specific]
+2. [Second action - include any data/conditions needed]
+3. [Third action]
+4. [Observe the bug]
+
+### Environment
+- **Browser/Platform:** [Chrome, Safari, Mobile, etc.]
+- **OS:** [macOS, Windows, iOS, Android, etc.]
+- **User Role:** [Which user type experiences this]
+- **Data Conditions:** [Specific data state that triggers bug]
+
+### Screenshots/Evidence
+<!-- Add as attachments -->
+
+---
+
+## Acceptance Criteria
+
+### Fix Verification
+- [ ] Bug no longer reproducible using original steps
+- [ ] Expected behavior now works correctly
+- [ ] Fix doesn't break related functionality
+- [ ] No new error messages or console errors
+
+### Tests
+- [ ] Regression test added to prevent recurrence
+- [ ] Related edge cases tested
+- [ ] All tests passing
+
+### Documentation
+- [ ] Root cause documented (if significant pattern)
+- [ ] Prevention notes added to knowledge base (if applicable)
+- [ ] N/A - No significant documentation needed
+
+---
+
+## Technical Notes
+
+### Root Cause Analysis
+**Hypothesis:** [What you think is causing the bug]
+
+**Investigation Findings:**
+- [Finding 1 from debugging]
+- [Finding 2 from debugging]
+
+**Confirmed Cause:** [What's actually wrong - file, function, logic error]
+
+### Fix Approach
+[Describe the fix strategy - what needs to change]
+
+**Files to Modify:**
+- `path/to/file.tsx` - [What needs to change]
+
+**Risk Assessment:**
+- **Regression Risk:** Low | Medium | High
+- **Testing Required:** [What needs to be tested]
+
+---
+
+## Dependencies
+
+**Related Systems:**
+- [System or feature where bug occurs]
+
+**Blocks:**
+- [Work that can't proceed until bug is fixed]
+- OR: Nothing blocked
+
+**Related Bugs:**
+- [Link to related bug if applicable]
+- OR: No related issues
+
+---
+
+_Reported: YYYY-MM-DD_

package/template/.claude/skills/flydocs-workflow/templates/chore.md

@@ -0,0 +1,75 @@
+## Context
+
+**Why This Matters:**
+[Explanation of the value - cleaner code, better UX, faster performance, etc.]
+
+**Scope:**
+[What areas/pages/features does this touch? Be specific enough to stay focused.]
+
+**Type:** Ongoing | One-time
+
+---
+
+## Task List
+
+### Initial Tasks
+- [ ] [Task 1 - be specific]
+- [ ] [Task 2 - be specific]
+- [ ] [Task 3 - be specific]
+
+### Added During Work
+<!-- Add new tasks discovered while working -->
+
+### Out of Scope
+<!-- Tasks that don't fit - might become new issues -->
+- [Task that's too big or different focus]
+
+---
+
+## Acceptance Criteria
+
+### Completion
+- [ ] All initial tasks completed (or moved to out of scope)
+- [ ] Code quality acceptable
+- [ ] No regressions introduced
+
+### Tests
+- [ ] Tests updated if behavior changed
+- [ ] All tests passing
+- [ ] N/A - No behavior changes
+
+### Documentation
+- [ ] Patterns documented (if new approach discovered)
+- [ ] N/A - No significant documentation needed
+
+---
+
+## Technical Notes
+
+### Approach
+[How you'll tackle this work]
+
+### Files to Touch
+- `path/to/file.tsx` - [What changes]
+
+### Risk Assessment
+- **Regression Risk:** Low | Medium | High
+- **Related Areas:** [What else might be affected]
+
+---
+
+## Completion Criteria
+
+**This chore is done when:**
+- [ ] [Completion criterion 1]
+- [ ] [Completion criterion 2]
+- [ ] No obvious improvements remaining in scope
+
+**Signs this needs to be split:**
+- Work has been ongoing for 3+ weeks
+- Scope has grown significantly
+- New tasks are unrelated to original purpose
+
+---
+
+_Created: YYYY-MM-DD_