@flydocs/cli 0.6.0-alpha.2 → 0.6.0-alpha.21

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?"

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

@@ -0,0 +1,251 @@
+# Service Descriptor Schema
+
+Reference for `flydocs/context/service.json` — the dual-purpose descriptor that
+provides cross-repo context AND intra-repo orientation.
+
+## Purpose
+
+The service descriptor serves two roles from a single file:
+
+- **Cross-repo export** — `apis`, `dependencies`, `purpose`, `stack` tell
+  sibling repos what this service does and how it connects. Stored by relay,
+  queried by workspace composite.
+- **Intra-repo orientation** — `structure` section tells THIS repo's agent
+  where things are: entry points, shared types, build system, package boundaries.
+  Not exported cross-repo.
+
+Generated by the user's coding agent during `/flydocs-setup` Phase 1.5.
+
+## Schema
+
+```typescript
+interface ServiceDescriptor {
+  version: 1;
+  name: string; // Human-readable service name
+  repoSlug: string; // owner/repo format (matches workspace.repoSlug)
+  purpose: string; // One-sentence description of what this service does
+  stack: string[]; // Key technologies: ["next", "convex", "typescript"]
+
+  // Cross-repo export surface (what siblings see)
+  apis: ApiSurface[];
+  dependencies: ServiceDependency[];
+
+  // Intra-repo orientation (what THIS repo's agent uses)
+  structure: ServiceStructure;
+}
+
+interface ApiSurface {
+  type: "rest" | "graphql" | "grpc" | "event" | "package";
+  path: string; // Route prefix, event topic, or package path
+  description: string; // What this API surface does
+  methods?: string[]; // HTTP methods for REST (optional)
+}
+
+interface ServiceDependency {
+  service: string; // Repo slug or service name of the dependency
+  interface: string; // What interface is consumed (e.g., "REST /api/relay/*")
+  description: string; // Why this dependency exists
+}
+
+interface ServiceStructure {
+  entryPoints: string[]; // Where request handling or app logic starts
+  sharedTypes: string[]; // Where shared type definitions live
+  buildSystem: string; // "turbo", "nx", "next", "tsup", "vite", "cargo", etc.
+  packages?: PackageInfo[]; // Monorepo only: name, path, purpose per package
+}
+
+interface PackageInfo {
+  name: string; // Package name (e.g., "@flydocs/cli")
+  path: string; // Relative path from repo root
+  purpose: string; // What this package does
+}
+```
+
+## Field Notes
+
+- `version` is always `1`. Will increment on breaking schema changes.
+- `repoSlug` must match the slug registered in the workspace dashboard.
+- `structure` is local-only — not pushed to relay or included in workspace composite.
+- `apis` and `dependencies` create PROVIDES/CONSUMES edges in the graph.
+- `stack` is a flat array of lowercase identifiers (framework names, languages).
+- Agent scans the codebase to populate all fields during setup Phase 1.5.
+
+## Examples
+
+### Example 1: Single-App CLI Tool (Type 1)
+
+```json
+{
+  "version": 1,
+  "name": "FlyDocs CLI",
+  "repoSlug": "plastrlab/flydocs-core",
+  "purpose": "CLI tool that installs and manages FlyDocs skill templates, hooks, and configuration in user projects",
+  "stack": ["typescript", "node", "commander"],
+  "apis": [
+    {
+      "type": "package",
+      "path": "@flydocs/cli",
+      "description": "npm package providing the flydocs CLI binary"
+    }
+  ],
+  "dependencies": [
+    {
+      "service": "plastrlab/flydocs-app",
+      "interface": "REST /api/relay/*",
+      "description": "Cloud tier pushes config, descriptors, and issue operations to relay API"
+    }
+  ],
+  "structure": {
+    "entryPoints": ["src/cli.ts"],
+    "sharedTypes": ["src/lib/types.ts"],
+    "buildSystem": "tsup"
+  }
+}
+```
+
+### Example 2: Full-Stack Web App (Type 1)
+
+```json
+{
+  "version": 1,
+  "name": "FlyDocs App",
+  "repoSlug": "plastrlab/flydocs-app",
+  "purpose": "Web dashboard and relay API for FlyDocs cloud tier — workspace management, issue relay, and service descriptor storage",
+  "stack": ["next", "react", "convex", "typescript", "tailwind"],
+  "apis": [
+    {
+      "type": "rest",
+      "path": "/api/relay",
+      "description": "Relay API for CLI operations — config generation, issue proxy, service descriptors",
+      "methods": ["GET", "POST", "PUT", "PATCH"]
+    },
+    {
+      "type": "rest",
+      "path": "/api/auth",
+      "description": "Authentication endpoints for CLI and dashboard login",
+      "methods": ["GET", "POST"]
+    }
+  ],
+  "dependencies": [
+    {
+      "service": "linear",
+      "interface": "GraphQL API",
+      "description": "Issue tracker backend — all issue CRUD proxied through relay"
+    },
+    {
+      "service": "convex",
+      "interface": "Convex functions",
+      "description": "Real-time database for workspaces, repos, user state"
+    }
+  ],
+  "structure": {
+    "entryPoints": ["src/app/api/", "convex/"],
+    "sharedTypes": ["src/types/", "convex/schema.ts"],
+    "buildSystem": "next"
+  }
+}
+```
+
+### Example 3: Monorepo Multi-Service (Type 3)
+
+```json
+{
+  "version": 1,
+  "name": "Acme Platform",
+  "repoSlug": "acme/platform",
+  "purpose": "Monorepo containing API server, worker service, and shared packages for the Acme SaaS platform",
+  "stack": ["typescript", "express", "prisma", "redis", "turborepo"],
+  "apis": [
+    {
+      "type": "rest",
+      "path": "/api/v2",
+      "description": "Public REST API for client applications",
+      "methods": ["GET", "POST", "PUT", "DELETE"]
+    },
+    {
+      "type": "event",
+      "path": "jobs.*",
+      "description": "Redis pub/sub events consumed by worker service"
+    },
+    {
+      "type": "package",
+      "path": "@acme/sdk",
+      "description": "Published TypeScript SDK for API consumers"
+    }
+  ],
+  "dependencies": [
+    {
+      "service": "stripe",
+      "interface": "REST API + webhooks",
+      "description": "Payment processing and subscription management"
+    },
+    {
+      "service": "acme/marketing-site",
+      "interface": "REST /api/v2/pricing",
+      "description": "Marketing site fetches pricing data from API"
+    }
+  ],
+  "structure": {
+    "entryPoints": ["apps/api/src/server.ts", "apps/worker/src/index.ts"],
+    "sharedTypes": ["packages/shared/src/types/"],
+    "buildSystem": "turbo",
+    "packages": [
+      {
+        "name": "@acme/api",
+        "path": "apps/api",
+        "purpose": "Express API server — handles all client requests"
+      },
+      {
+        "name": "@acme/worker",
+        "path": "apps/worker",
+        "purpose": "Background job processor — email, billing, data sync"
+      },
+      {
+        "name": "@acme/shared",
+        "path": "packages/shared",
+        "purpose": "Shared types, utilities, and validation schemas"
+      },
+      {
+        "name": "@acme/sdk",
+        "path": "packages/sdk",
+        "purpose": "Published TypeScript SDK for external API consumers"
+      }
+    ]
+  }
+}
+```
+
+## Graph Integration
+
+When `graph_build.py` processes `service.json`:
+
+1. Creates a `repo:{repoSlug}` node with `purpose` and `stack` as properties
+2. For each entry in `apis`: creates a PROVIDES edge from this repo to any
+   repo that lists it in their `dependencies`
+3. For each entry in `dependencies`: creates a CONSUMES edge from this repo
+   to the dependency's repo node
+4. Edge properties include `interface` and `description` from the source data
+
+Cross-repo edges are only created when both repos have service descriptors in
+the graph (either from local sibling reads or relay workspace composite).
+
+## Relay Integration
+
+- **Push:** `push_service.py` sends this repo's descriptor via
+  `PUT /api/relay/workspace/service` (excludes `structure` section)
+- **Pull:** `pull_services.py` fetches workspace composite via
+  `GET /api/relay/workspace/services` (returns all repos with descriptors)
+- **Local fallback:** Read sibling `flydocs/context/service.json` files directly
+
+## Topology Context
+
+The service descriptor works alongside topology detection (stored in config).
+Topology tells the agent HOW repos are laid out; the descriptor tells it WHAT
+each repo does and how they connect.
+
+| Topology Type | Layout                  | Detection Signal                             |
+| ------------- | ----------------------- | -------------------------------------------- |
+| 1             | Single repo, single app | One `.git`, no workspace config              |
+| 2             | Monorepo, single app    | One `.git`, one root app                     |
+| 3             | Monorepo, multi-service | One `.git`, workspace config (pnpm/nx/turbo) |
+| 4             | Sibling repos           | Parent dir has multiple `.git` children      |

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

@@ -10,41 +10,41 @@ BACKLOG ──→ READY ──→ IMPLEMENTING ──→ REVIEW ──→ TESTIN
 
 ## State Meanings
 
-| FlyDocs State | Intent | Assignment Required |
-|---------------|--------|---------------------|
-| BACKLOG | Raw capture, not yet refined | No |
-| READY | Refined spec, ready to pick up | No |
-| IMPLEMENTING | Active work in progress | **Yes** |
-| BLOCKED | Cannot proceed, waiting on resolution | Yes |
-| REVIEW | Code complete, awaiting quality review | Yes |
-| TESTING | Review passed, awaiting user acceptance | Yes |
-| COMPLETE | All stages passed, work delivered | Yes |
+| FlyDocs State | Intent                                  | Assignment Required |
+| ------------- | --------------------------------------- | ------------------- |
+| BACKLOG       | Raw capture, not yet refined            | No                  |
+| READY         | Refined spec, ready to pick up          | No                  |
+| IMPLEMENTING  | Active work in progress                 | **Yes**             |
+| BLOCKED       | Cannot proceed, waiting on resolution   | Yes                 |
+| REVIEW        | Code complete, awaiting quality review  | Yes                 |
+| TESTING       | Review passed, awaiting user acceptance | Yes                 |
+| COMPLETE      | All stages passed, work delivered       | Yes                 |
 
 ## Valid Transitions
 
-| From | To | Trigger |
-|------|----|---------|
-| BACKLOG | READY | Refine stage completes |
-| READY | IMPLEMENTING | Activate stage completes |
-| IMPLEMENTING | REVIEW | Implement stage completes |
-| IMPLEMENTING | BLOCKED | Blocker identified |
-| BLOCKED | IMPLEMENTING | Blocker resolved |
-| REVIEW | TESTING | Code review passes |
-| REVIEW | IMPLEMENTING | Code review finds issues |
-| TESTING | COMPLETE | QE approves, PM closes |
-| TESTING | IMPLEMENTING | QE finds issues |
+| From         | To           | Trigger                   |
+| ------------ | ------------ | ------------------------- |
+| BACKLOG      | READY        | Refine stage completes    |
+| READY        | IMPLEMENTING | Activate stage completes  |
+| IMPLEMENTING | REVIEW       | Implement stage completes |
+| IMPLEMENTING | BLOCKED      | Blocker identified        |
+| BLOCKED      | IMPLEMENTING | Blocker resolved          |
+| REVIEW       | TESTING      | Code review passes        |
+| REVIEW       | IMPLEMENTING | Code review finds issues  |
+| TESTING      | COMPLETE     | QE approves, PM closes    |
+| TESTING      | IMPLEMENTING | QE finds issues           |
 
 ## Terminal States
 
-| State | When |
-|-------|------|
+| State           | When                        |
+| --------------- | --------------------------- |
 | COMPLETE (Done) | Work delivered and verified |
-| ARCHIVED | Deferred — may return later |
-| CANCELED | Not pursuing |
-| DUPLICATE | See referenced issue |
+| ARCHIVED        | Deferred — may return later |
+| CANCELED        | Not pursuing                |
+| DUPLICATE       | See referenced issue        |
 
 ## Provider Mapping
 
-FlyDocs states are provider-agnostic. The mechanism skill maps them to provider-specific
+FlyDocs states are provider-agnostic. The workflow scripts map them to provider-specific
 state names via `statusMapping` in `.flydocs/config.json`. The workflow never references
 provider-specific names directly.