@flydocs/cli 0.6.0-alpha.3 → 0.6.0-alpha.31

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

@@ -1,29 +1,38 @@
 ---
 name: flydocs-workflow
 description: |
-  FlyDocs development lifecycle — spec-driven workflow from capture to close.
-  Defines stages, gates, and handoffs. Provider-agnostic methodology.
-  Use when: managing issues, transitioning work, starting/ending sessions.
+  Unified FlyDocs skill — lifecycle workflow, issue operations, project
+  management, knowledge graph, and session context. Tier-aware: auto-detects
+  cloud (relay API) or local (filesystem) from config.
 triggers:
-  - capture
-  - refine
-  - activate
-  - implement
-  - review
-  - validate
-  - close
-  - session
-  - workflow
+  - create issue
+  - capture issue
+  - log a bug
+  - add to backlog
   - transition
-  - status
-  - issue
+  - move to
+  - mark as
+  - set status
+  - assign issue
+  - close issue
+  - start session
+  - wrap session
+  - project update
+  - status update
+  - add comment
+  - set priority
+  - set estimate
 ---
 
 # FlyDocs Workflow
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for all
-workflow, issue management, and process decisions. Read the relevant stage
-file before acting — do not guess procedures from training data.
+Unified skill for the FlyDocs development lifecycle, issue operations,
+project management, knowledge graph, and session context.
+
+When performing issue operations or status transitions, use the dispatcher
+scripts below. Slash commands (`/capture`, `/implement`, etc.) load stage
+files automatically — only read stage files manually when handling natural
+language workflow requests that bypass slash commands.
 
 ## Lifecycle
 
@@ -35,36 +44,115 @@ 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 |
 
+## Script Catalog
+
+All scripts: `python3 .claude/skills/flydocs-workflow/scripts/<script>`
+
+### Issue Operations — `issues.py`
+
+| Command            | Usage                                                                                                                                              | Notes                                            |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `create`           | `--title T --type feature\|bug\|chore\|idea [--description D] [--priority 0-4] [--estimate 0\|1\|2\|3\|5] [--assignee A] [--project P] [--triage]` | Also accepts `--description-file` or stdin       |
+| `get`              | `REF [--fields basic\|full]`                                                                                                                       | Full includes comments                           |
+| `list`             | `[--status S] [--active] [--project P] [--assignee A] [--milestone M] [--mine] [--limit N]`                                                        | `--active` = non-terminal states                 |
+| `transition`       | `REF STATUS COMMENT`                                                                                                                               | Status is uppercased automatically               |
+| `assign`           | `REF ASSIGNEE` or `REF --unassign`                                                                                                                 |                                                  |
+| `update`           | `REF [--title] [--priority] [--estimate] [--assignee] [--state] [--description] [--labels] [--milestone] [--comment]`                              | Bulk update, also accepts `--description-file`   |
+| `description`      | `REF [--text T] [--file F]`                                                                                                                        | Also accepts stdin                               |
+| `comment`          | `REF [BODY]`                                                                                                                                       | Also accepts stdin                               |
+| `estimate`         | `REF POINTS`                                                                                                                                       | Non-negative integer                             |
+| `priority`         | `REF LEVEL`                                                                                                                                        | 0 (none) to 4 (low)                              |
+| `link`             | `REF RELATED_REF TYPE`                                                                                                                             | Type: blocks, related, duplicate                 |
+| `assign-milestone` | `REF MILESTONE_ID`                                                                                                                                 | Cloud only                                       |
+| `assign-cycle`     | `REF [CYCLE_ID]`                                                                                                                                   | Cloud only                                       |
+| `pr`               | `[--issue REF] [--title T] [--base B] [--draft] [--dry-run]`                                                                                       | Detects GitHub/GitLab, auto-populates from issue |
+
+### Project Operations — `projects.py` (cloud only)
+
+| Command            | Usage                                         |
+| ------------------ | --------------------------------------------- |
+| `list-projects`    | `[--active] [--all]`                          |
+| `create-project`   | `--name N [--description D]`                  |
+| `list-milestones`  | `[--all]`                                     |
+| `create-milestone` | `--name N [--project P] [--target-date D]`    |
+| `update-milestone` | `ID [--name] [--target-date] [--description]` |
+| `delete-milestone` | `ID`                                          |
+| `list-cycles`      | `[--active]`                                  |
+
+### Workspace Operations — `workspace.py` (cloud only)
+
+| Command              | Usage                                                | Notes                                       |
+| -------------------- | ---------------------------------------------------- | ------------------------------------------- |
+| `validate`           | (no args)                                            | Writes validation cache, sets setupComplete |
+| `list-labels`        | (no args)                                            |                                             |
+| `refresh-labels`     | `[--fix]`                                            | Compare local config with provider          |
+| `list-statuses`      | (no args)                                            |                                             |
+| `list-providers`     | (no args)                                            |                                             |
+| `set-provider`       | `TYPE`                                               | linear, jira                                |
+| `list-teams`         | (no args)                                            |                                             |
+| `create-team`        | `--name N [--key K] [--description D] [--parent ID]` |                                             |
+| `set-team`           | `TEAM_ID`                                            |                                             |
+| `set-labels`         | `[--defaults JSON] [--type-map JSON]`                | Also accepts stdin                          |
+| `set-status-mapping` | `[--auto] [--mapping JSON]`                          | Also accepts stdin                          |
+| `set-identity`       | `PROVIDER PROVIDER_USER_ID`                          | Writes .flydocs/me.json                     |
+| `set-preferences`    | `[--workspace] [--assignee] [--display JSON]`        | No flags = GET                              |
+| `get-estimate-scale` | (no args)                                            |                                             |
+| `generate-config`    | `[--dry-run]`                                        | Merge server config with local              |
+| `get-me`             | (no args)                                            | Writes .flydocs/me.json                     |
+
+### Session Operations — `session.py`
+
+| Command          | Usage                                                           | Notes                  |
+| ---------------- | --------------------------------------------------------------- | ---------------------- |
+| `project-update` | `--health onTrack\|atRisk\|offTrack [--body B] [--body-file F]` | Also accepts stdin     |
+| `status-summary` | (no args)                                                       | Issue counts by status |
+
+### Knowledge Graph Scripts
+
+| Script             | Usage                                                                       | Notes                                                |
+| ------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `graph_build.py`   | `[--root PATH]`                                                             | Rebuild graph from skills, ADRs, service descriptors |
+| `graph_query.py`   | `--node ID [--depth N] [--rel TYPE] [--reverse] [--format json\|md]`        | BFS traversal                                        |
+| `graph_update.py`  | `add-node ID --type TYPE [--label STR]` / `add-edge FROM TO REL [--manual]` | Manual CRUD                                          |
+| `graph_session.py` | `--summary "..." [--issue REF]... [--decision NNN]...`                      | Called at session wrap                               |
+| `push_service.py`  | `[--root PATH]`                                                             | Push service descriptor to relay (cloud)             |
+| `pull_services.py` | `[--root PATH]`                                                             | Pull workspace composite (cloud)                     |
+
 ## Reference
 
-| 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 |
+| Topic                     | File                                   |
+| ------------------------- | -------------------------------------- |
+| Comment templates         | reference/comment-templates.md         |
+| Status transitions        | reference/status-workflow.md           |
+| Priority & estimates      | reference/priority-estimates.md        |
+| PR & git workflow         | reference/pr-workflow.md               |
+| Golden rules              | reference/golden-rules.md              |
+| Provider costs            | reference/provider-costs.md            |
+| Graph schema              | reference/graph-schema.md              |
+| Service descriptor schema | reference/service-descriptor-schema.md |
 
 ## Templates
 
-Issue templates in `templates/` — feature, bug, chore, idea.
+Issue templates in `templates/issues/` — feature, bug, chore, idea.
+PR templates in `templates/pr/` — pull request description structure.
 Stage files define how to fill templates; template files are pure structure.
 
 ## Golden Rules (Summary)
@@ -72,14 +160,18 @@ Stage files define how to fill templates; template files are pure structure.
 1. Every status transition gets a comment (see `reference/comment-templates.md`)
 2. Assignment required before In Progress
 3. Checkboxes live in issue description, never comments
-4. Use mechanism scripts for all issue operations — execute, don't describe
+4. Use dispatcher scripts for all issue operations — execute, don't describe
 5. Session wrap posts a project update
 6. Product scope filtering — only show projects/issues matching config labels
 
 For full rules with verification gates, see `reference/golden-rules.md`.
 
-## Mechanism Scripts
+## Architecture
+
+The unified client (`flydocs_api.py`) reads tier from `.flydocs/config.json`
+and routes operations automatically:
+
+- **Cloud tier** → RelayBackend (HTTP calls to FlyDocs relay API)
+- **Local tier** → LocalBackend (filesystem operations in `_local/file_store.py`)
 
-This skill references scripts by name (e.g., `transition.py`, `comment.py`).
-The active mechanism skill provides implementations and calling conventions.
-See the mechanism skill's SKILL.md for argument details and config reference.
+Scripts never check tier. The client handles routing transparently.

package/template/.claude/skills/flydocs-workflow/cursor-rule.mdc

@@ -12,7 +12,7 @@ alwaysApply: true
 1. Every status transition gets a comment — no silent moves
 2. Assignment required before In Progress
 3. Checkboxes live in issue description, never comments
-4. Use mechanism scripts for all issue operations — execute, don't describe
+4. Use workflow scripts for all issue operations — execute, don't describe
 5. Session wrap posts a project update
 6. Product scope filtering — only show projects/issues matching config labels
 
@@ -36,18 +36,19 @@ Capture → Refine → Activate → Implement → Review → Validate → Close
 | Validate | stages/validate.md | QE |
 | Close | stages/close.md | PM |
 
+## When This Applies
+
+These rules apply to **issue operations and status transitions only** — not
+general coding. For building features, fixing bugs, and writing code, skip
+this and just do the work.
+
 ## Intent Mapping
 
 - "create/capture/log an issue" → Capture stage
 - "triage/refine/spec out" → Refine stage
 - "start work/activate/assign" → Activate stage
-- "build/implement/fix" → Implement stage
-- "review/check code" → Review stage
-- "test/validate/QA" → Validate stage
 - "close/ship/done" → Close stage
 - "start session/wrap session" → Session management
 
-## Key Rule
-
-Read the relevant stage file before acting. Do not guess procedures from training data.
-Mechanism scripts handle all issue operations — see the active mechanism skill.
+Dispatcher scripts handle all issue operations — see the workflow skill's
+scripts directory. Slash commands load stage files automatically.

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/golden-rules.md

@@ -9,7 +9,7 @@ Non-negotiable rules enforced across all workflow stages.
 ### 1. Every Status Transition Gets a Comment
 
 No silent state changes. Use templates from `reference/comment-templates.md`.
-Mechanism scripts enforce this — `transition.py` requires a comment argument.
+Workflow scripts enforce this — `issues.py transition` requires a comment argument.
 
 ### 2. Assignment Before In Progress
 
@@ -22,20 +22,20 @@ Acceptance criteria progress is tracked by checking boxes in the issue descripti
 Never put completion marks in comments. Never create new checkboxes in comments.
 See the Checkbox Protocol in `stages/implement.md`.
 
-### 4. Use Mechanism Scripts — Execute, Don't Describe
+### 4. Use Workflow Scripts — Execute, Don't Describe
 
-For all issue operations (create, transition, comment, assign, query), use the scripts
-provided by the active mechanism skill. Run them. Do not say "you should run..." or
+For all issue operations (create, transition, comment, assign, query), use the dispatcher
+scripts provided by the workflow skill. Run them. Do not say "you should run..." or
 describe what a script would do. Execute and report the result.
 
 ### 5. Session Wrap Posts a Project Update
 
-Every session wrap posts a project update via `project_update.py`. Do not just
+Every session wrap posts a project update via `session.py project-update`. Do not just
 summarize in chat. Actually post. See `session.md` for the full protocol.
 
 ### 6. Product Scope Filtering
 
-`list_issues.py` automatically applies product scope from config using this cascade:
+`issues.py list` automatically applies product scope from config using this cascade:
 
 1. **`workspace.activeProjects` set** → scope to those projects (OR logic if multiple)
 2. **`workspace.product.labelIds` set** → scope to issues with ALL those labels (AND logic)
@@ -46,23 +46,34 @@ work within the scoped results — they do not bypass product scope.
 
 Never show out-of-scope issues, even if the user asks.
 
+### 7. Sequential Script Execution
+
+Run workflow scripts **one at a time, sequentially**. Never fire multiple
+`issues.py`, `projects.py`, or `session.py` commands in parallel. The relay
+API does not handle concurrent requests from the same workspace well — parallel
+calls may timeout, produce empty output, or silently fail.
+
+Wait for each script to return before running the next. If you need to create
+multiple issues, create them one by one and confirm each succeeds before
+proceeding.
+
 ---
 
 ## Verification Gates
 
 After executing any workflow command, verify the result before responding:
 
-| Action | Script Used | Verify |
-|--------|-------------|--------|
-| Capture | `create_issue.py` | Issue identifier returned |
-| Refine | `transition.py` → READY | Success response |
-| Activate | `assign.py` + `transition.py` | Both succeed |
-| Implement | `get_issue.py` | Issue details loaded |
-| Block | `transition.py` → BLOCKED | Success response |
-| Review | `transition.py` → REVIEW/TESTING | Success response |
-| Validate | `transition.py` → TESTING/IMPLEMENTING | Success response |
-| Close | `transition.py` → COMPLETE | Success response |
-| Wrap | `project_update.py` | Update ID returned |
+| Action    | Script Used                                   | Verify                    |
+| --------- | --------------------------------------------- | ------------------------- |
+| Capture   | `issues.py create`                            | Issue identifier returned |
+| Refine    | `issues.py transition` → READY                | Success response          |
+| Activate  | `issues.py assign` + `issues.py transition`   | Both succeed              |
+| Implement | `issues.py get`                               | Issue details loaded      |
+| Block     | `issues.py transition` → BLOCKED              | Success response          |
+| Review    | `issues.py transition` → REVIEW/TESTING       | Success response          |
+| Validate  | `issues.py transition` → TESTING/IMPLEMENTING | Success response          |
+| Close     | `issues.py transition` → COMPLETE             | Success response          |
+| Wrap      | `session.py project-update`                   | Update ID returned        |
 
 If any script fails: **stop, report, retry, escalate.** Do not continue to the next step.
 

package/template/.claude/skills/flydocs-workflow/reference/graph-schema.md

@@ -0,0 +1,116 @@
+# Context Graph Schema
+
+Reference for the graph JSON structure stored at `flydocs/context/graph.json`.
+
+## Top-Level Structure
+
+```json
+{
+  "version": 1,
+  "updated": "ISO-8601 timestamp",
+  "nodes": { "<id>": { ... } },
+  "edges": [ { ... } ]
+}
+```
+
+## Node Schema
+
+```json
+{
+  "type": "skill | decision | issue | module | session | concept",
+  "label": "Human-readable name",
+  "path": "Relative file path (optional)",
+  "status": "Node-specific status (optional)",
+  "date": "ISO date for temporal nodes (optional)",
+  "tier": "Skill tier: behavioral | mechanism | premium (optional)",
+  "manual": true
+}
+```
+
+**ID conventions:**
+
+| Type     | Pattern                     | Example                          |
+| -------- | --------------------------- | -------------------------------- |
+| skill    | `skill:{directory-name}`    | `skill:typescript-strict`        |
+| decision | `decision:{3-digit-number}` | `decision:001`                   |
+| issue    | `issue:{identifier}`        | `issue:FLY-56`                   |
+| module   | `module:{kebab-name}`       | `module:install-script`          |
+| session  | `session:{YYYY-MM-DD-seq}`  | `session:2026-02-03-a`           |
+| concept  | `concept:{kebab-name}`      | `concept:progressive-disclosure` |
+| repo     | `repo:{owner/name}`         | `repo:plastrlab/flydocs-app`     |
+
+## Edge Schema
+
+```json
+{
+  "from": "source node ID",
+  "to": "target node ID",
+  "rel": "RELATIONSHIP_TYPE",
+  "weight": 0.0-1.0,
+  "manual": true
+}
+```
+
+**Weight guidelines:**
+
+| Weight  | Meaning                     |
+| ------- | --------------------------- |
+| 1.0     | Direct, strong relationship |
+| 0.7-0.9 | Strong but indirect         |
+| 0.4-0.6 | Moderate association        |
+| 0.1-0.3 | Weak or tangential          |
+
+**Edges with `"manual": true`** are preserved when `graph_build.py` rebuilds
+the graph from sources. Auto-derived edges are regenerated on each build.
+
+## Relationship Types
+
+| Relationship   | Direction                      | Example                                   |
+| -------------- | ------------------------------ | ----------------------------------------- |
+| `EXTENDS`      | A extends B                    | ADR-004 extends ADR-001                   |
+| `IMPLEMENTS`   | A implements B                 | Issue implements a decision               |
+| `DELEGATES_TO` | A delegates to B               | Workflow delegates to mechanism           |
+| `PRECEDES`     | A should load before B         | typescript-strict precedes implementation |
+| `MODIFIES`     | A modifies B                   | Issue modifies a module                   |
+| `WORKED_ON`    | A worked on B                  | Session worked on an issue                |
+| `PRODUCED`     | A produced B                   | Session produced a decision               |
+| `RELATES_TO`   | A relates to B                 | General association                       |
+| `SUPERSEDES`   | A supersedes B                 | New decision replaces old                 |
+| `BLOCKS`       | A blocks B                     | Issue blocks another issue                |
+| `PROVIDES`     | A exposes interface B consumes | Repo provides REST API to sibling         |
+| `CONSUMES`     | A depends on B's interface     | Repo consumes another's API               |
+
+### Cross-Repo Edge Properties
+
+Edges of type `PROVIDES` and `CONSUMES` carry additional properties:
+
+```json
+{
+  "from": "repo:plastrlab/flydocs-core",
+  "to": "repo:plastrlab/flydocs-app",
+  "rel": "PROVIDES",
+  "weight": 1.0,
+  "interface": "REST API /api/relay/*",
+  "description": "Core CLI pushes config and descriptors to relay endpoints"
+}
+```
+
+| Property      | Type   | Description                                            |
+| ------------- | ------ | ------------------------------------------------------ |
+| `interface`   | string | What is exposed or consumed (endpoint, event, package) |
+| `description` | string | Brief context about the relationship                   |
+
+## Repo Node Schema
+
+Repo nodes are derived from `flydocs/context/service.json` by `graph_build.py`.
+See `service-descriptor-schema.md` for the full ServiceDescriptor interface.
+
+```json
+{
+  "type": "repo",
+  "label": "flydocs-app",
+  "path": "flydocs/context/service.json",
+  "purpose": "Web dashboard and relay API for FlyDocs cloud tier",
+  "stack": ["next", "convex", "typescript"]
+}
+```

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

@@ -0,0 +1,120 @@
+# 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
+
+The canonical PR template lives at `templates/pr/default.md`. Use the PR
+dispatcher to create PRs with auto-populated issue context:
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/issues.py pr --issue FLY-123
+```
+
+Options:
+
+| Flag        | Purpose                                   |
+| ----------- | ----------------------------------------- |
+| `--issue`   | Link to issue (auto-populates title + AC) |
+| `--title`   | Override PR title                         |
+| `--base`    | Target branch (defaults to main/master)   |
+| `--draft`   | Create as draft PR                        |
+| `--dry-run` | Preview without creating                  |
+
+The script:
+
+- Detects platform (GitHub, GitLab) from git remote
+- Reads the PR template and fills in issue context
+- Creates the PR via `gh pr create` or `glab mr create`
+- Posts a comment on the issue linking the PR
+
+**Enforcement:** A PostToolUse hook (`post-pr-check.py`) detects direct
+`gh pr create` or `glab mr create` calls and warns if required sections
+(Summary, Test Plan) are missing.
+
+### Template Sections
+
+| Section                 | Required | Auto-populated           |
+| ----------------------- | -------- | ------------------------ |
+| **Summary**             | Yes      | From issue title         |
+| **Changes**             | No       | Manual                   |
+| **Test Plan**           | Yes      | Manual                   |
+| **Acceptance Criteria** | No       | From issue AC checkboxes |
+| **Notes**               | No       | Manual                   |
+
+## 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: `python3 .claude/skills/flydocs-workflow/scripts/issues.py pr --issue <ref>`
+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 `issues.py link` 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?"