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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.6.0-alpha.3",
+  "version": "0.6.0-alpha.31",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {

package/template/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # Claude Code Configuration
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for all
-workflow, issue management, process, and pattern decisions. Read the relevant
-skill file before acting — do not guess procedures from training data.
+IMPORTANT: For workflow operations (issue creation, status transitions,
+session management), prefer skill-led reasoning — read the relevant skill
+file before acting. For general coding tasks, just write code.
 
 > For cross-platform agent instructions, see `AGENTS.md`.
 
@@ -10,16 +10,18 @@ skill file before acting — do not guess procedures from training data.
 
 These are non-negotiable and enforced by hooks:
 
-1. **Scripts for all issue operations.** Use mechanism scripts (create, transition, comment, assign, etc.) — never describe actions you should execute.
+1. **Scripts for all issue operations.** Use workflow dispatcher scripts (`issues.py`, `projects.py`, etc.) — never describe actions you should execute.
 2. **Every status transition gets a comment.** No silent moves. Use the comment templates from the workflow skill.
-3. **Assignment required before In Progress.** Hard gate — transition.py enforces this for cloud tier.
-4. **Checkboxes live in issue description, never comments.** Use `update_description.py` to update acceptance criteria.
-5. **Session wrap posts a project update.** End-of-session summary via `project_update.py` (cloud) or local summary file.
+3. **Assignment required before In Progress.** Hard gate — `issues.py transition` enforces this for cloud tier.
+4. **Checkboxes live in issue description, never comments.** Use `issues.py description` to update acceptance criteria.
+5. **Session wrap posts a project update.** End-of-session summary via `session.py project-update`.
 6. **No secrets in commits.** Never commit `.env`, credentials, or API keys.
 
 ## Workflow
 
-The FlyDocs development lifecycle. Read the workflow skill before taking any workflow action.
+The FlyDocs development lifecycle. Slash commands (`/capture`, `/activate`,
+etc.) load stage procedures automatically. For manual workflow actions, the
+stage files contain required procedures, templates, and field requirements.
 
 | Action               | Skill              | Entry Point                       |
 | -------------------- | ------------------ | --------------------------------- |
@@ -31,48 +33,46 @@ The FlyDocs development lifecycle. Read the workflow skill before taking any wor
 | QE validation        | `flydocs-workflow` | `stages/validate.md`              |
 | Close issue          | `flydocs-workflow` | `stages/close.md`                 |
 | Start / wrap session | `flydocs-workflow` | `session.md`                      |
+| Knowledge capture    | `flydocs-workflow` | `/knowledge` command              |
+| PR & git workflow    | `flydocs-workflow` | `reference/pr-workflow.md`        |
 | Comment templates    | `flydocs-workflow` | `reference/comment-templates.md`  |
 | Status transitions   | `flydocs-workflow` | `reference/status-workflow.md`    |
 | Priority & estimates | `flydocs-workflow` | `reference/priority-estimates.md` |
 | Issue templates      | `flydocs-workflow` | `templates/`                      |
 
-## Mechanism Scripts
+## Scripts
 
-Issue operations are handled by the installed mechanism skill. Only one is active at a time.
+All issue, project, workspace, and graph operations use grouped dispatcher
+scripts in `flydocs-workflow/scripts/`. The unified client auto-detects tier
+(cloud vs local) — scripts never check tier directly.
 
-| Tier              | Skill           | Backend                        |
-| ----------------- | --------------- | ------------------------------ |
-| Local (free)      | `flydocs-local` | File-based (`flydocs/issues/`) |
-| Cloud (connected) | `flydocs-cloud` | Linear GraphQL API             |
-
-Read the active mechanism skill's `SKILL.md` for script catalog and calling conventions.
-
-**Shared contract scripts** (both tiers implement):
-`create_issue.py`, `transition.py`, `comment.py`, `list_issues.py`, `get_issue.py`, `assign.py`, `update_description.py`
-
-## Premium Skills
-
-FlyDocs platform skills with premium functionality.
-
-| Skill               | When to Read                                               |
-| ------------------- | ---------------------------------------------------------- |
-| `flydocs-figma`     | Building UI from Figma designs — extraction, token mapping |
-| `flydocs-estimates` | Estimating AI token usage and costs (opt-in via config)    |
+| Dispatcher       | Operations                                                         |
+| ---------------- | ------------------------------------------------------------------ |
+| `issues.py`      | create, get, list, transition, assign, update, comment, audit, fix |
+| `projects.py`    | list-projects, create-project, milestones, cycles                  |
+| `workspace.py`   | validate, labels, statuses, teams, config, identity                |
+| `session.py`     | project-update, status-summary                                     |
+| `graph_*.py`     | build, query, update, session recording                            |
+| `push/pull_*.py` | Service descriptor sync (cloud tier)                               |
 
 ## Project Context
 
-| File                         | Purpose                                      |
-| ---------------------------- | -------------------------------------------- |
-| `flydocs/context/project.md` | Product scope, tech stack, active priorities |
-| `.flydocs/config.json`       | Tier, provider, labels, active projects      |
+| File                           | Purpose                                           |
+| ------------------------------ | ------------------------------------------------- |
+| `flydocs/context/project.md`   | Product scope, tech stack, active priorities      |
+| `flydocs/context/service.json` | Service descriptor, topology, cross-repo context  |
+| `.flydocs/config.json`         | Tier, provider, labels, active projects, topology |
 
 ## Hooks
 
-| Hook                       | Trigger                 | Purpose                        |
-| -------------------------- | ----------------------- | ------------------------------ |
-| `PostToolUse` (Edit/Write) | After code changes      | Auto-format                    |
-| `UserPromptSubmit`         | Before prompt           | Inject git/issue context       |
-| `PreToolUse`               | Before script execution | Auto-approve mechanism scripts |
+| Hook                       | Trigger                 | Purpose                                                    |
+| -------------------------- | ----------------------- | ---------------------------------------------------------- |
+| `PreToolUse` (Bash/Edit)   | Before tool execution   | Auto-approve scripts, validate create args, comment hints  |
+| `PostToolUse` (Edit/Write) | After code changes      | Auto-format                                                |
+| `PostToolUse` (Bash)       | After shell commands    | Transition validation, session file updates, create audit  |
+| `UserPromptSubmit`         | Before prompt           | Directive workflow context, milestone/label injection      |
+| `Stop`                     | Agent finishes response | Full lifecycle gate (READY, IMPLEMENTING, REVIEW, BLOCKED) |
+| `SessionStart`             | New session begins      | Inject continuity context                                  |
 
 ## Output Formatting
 
@@ -110,16 +110,11 @@ response — session summaries, issue comments, status updates, and plans.
 
 ## Skills Index
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
-Consult the relevant skill BEFORE writing code or making workflow decisions.
-
-| Skill             | Triggers                                                                                                                | Entry                                     |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, Linear, cloud | .claude/skills/flydocs-cloud/SKILL.md     |
-| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                               | .claude/skills/flydocs-context7/SKILL.md  |
-| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                   | .claude/skills/flydocs-estimates/SKILL.md |
-| flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                           | .claude/skills/flydocs-figma/SKILL.md     |
-| flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                       | .claude/skills/flydocs-local/SKILL.md     |
-| flydocs-workflow  | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue             | .claude/skills/flydocs-workflow/SKILL.md  |
+For issue operations and status transitions only — not general coding.
+Slash commands load procedures automatically; use scripts directly for CRUD.
+
+| Skill            | Triggers                                                                                                                                                                                                                         | Entry                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| flydocs-workflow | create issue, capture issue, log a bug, add to backlog, transition, move to, mark as, set status, assign issue, close issue, start session, wrap session, project update, status update, add comment, set priority, set estimate | .claude/skills/flydocs-workflow/SKILL.md |
 
 <!-- flydocs:skills-manifest:end -->

package/template/.claude/agents/implementation-agent.md

@@ -20,7 +20,7 @@ Implementation agent for FlyDocs spec-driven development.
 
 ## Constraints
 
-- **Scripts for issue updates** — use mechanism scripts for progress comments and transitions
+- **Scripts for issue updates** — use workflow dispatcher scripts for progress comments and transitions
 - Follow installed community skills for code quality patterns
 - Keep changes focused on the spec — don't over-engineer
 

package/template/.claude/agents/pm-agent.md

@@ -21,7 +21,7 @@ Product management agent for FlyDocs spec-driven workflow.
 ## Constraints
 
 - **Read-only** — cannot modify code files (Write/Edit disabled)
-- **Scripts for all issue ops** — read the mechanism skill's SKILL.md for calling conventions
+- **Scripts for all issue ops** — use workflow dispatcher scripts (`issues.py`, `projects.py`, etc.) for all operations
 - Defer technical decisions to implementation agent
 
 Read `.claude/skills/flydocs-workflow/SKILL.md` for lifecycle and stage procedures.

package/template/.claude/commands/activate.md

@@ -3,7 +3,7 @@
 Recommend or assign work and transition to In Progress.
 
 Read `.claude/skills/flydocs-workflow/stages/activate.md` and follow the procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "activate", "start work on", "what should I work on"
 

package/template/.claude/commands/attach.md

@@ -2,7 +2,7 @@
 
 Add a reference or file link to an issue via comment.
 
-Use `comment.py <ref> "<attachment details>"` from the active mechanism skill.
+Use `issues.py comment <ref> "<attachment details>"` from `.claude/skills/flydocs-workflow/scripts/`.
 
 Triggers: "attach this", "link this to the issue"
 

package/template/.claude/commands/block.md

@@ -2,8 +2,8 @@
 
 Move an issue to Blocked status with reason and optional blocker link.
 
-Use `transition.py <ref> BLOCKED "<reason>"` from the active mechanism skill.
-For dependency links (cloud only): use `link.py <ref> <blocker_ref> blocks`.
+Use `issues.py transition <ref> BLOCKED "<reason>"` from `.claude/skills/flydocs-workflow/scripts/`.
+For dependency links (cloud only): use `issues.py link <ref> <blocker_ref> blocks`.
 
 Triggers: "I'm blocked", "can't proceed", "stuck on"
 

package/template/.claude/commands/capture.md

@@ -3,7 +3,7 @@
 Create a new issue from user input — feature, bug, chore, or idea.
 
 Read `.claude/skills/flydocs-workflow/stages/capture.md` and follow the procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "capture that", "add to backlog", "found a bug", "new idea", "quick capture"
 

package/template/.claude/commands/close.md

@@ -3,7 +3,7 @@
 Move a validated issue to its terminal state (Done, Archived, Canceled, Duplicate).
 
 Read `.claude/skills/flydocs-workflow/stages/close.md` and follow the procedure.
-Read the active mechanism skill's `SKILL.md` for script calling conventions.
+Read `.claude/skills/flydocs-workflow/SKILL.md` for script calling conventions.
 
 Triggers: "close", "done", "archive", "cancel"