@flydocs/cli 0.6.0-alpha.13 → 0.6.0-alpha.20

package/package.json

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

package/template/.claude/CLAUDE.md

@@ -1,80 +1,82 @@
 # 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.
-
 > For cross-platform agent instructions, see `AGENTS.md`.
 
-## Hard Rules
+## Automatic Workflow Behavior
+
+These behaviors are **always on**. Do not wait for slash commands — execute
+these automatically as a natural part of doing the work. Use the dispatcher
+scripts (see Scripts section) for all issue operations.
+
+**When starting work on an issue:**
+
+- Transition the issue to In Progress: `issues.py transition REF IMPLEMENTING "Starting implementation"`
+- Assignment is required first — assign if not already assigned
 
-These are non-negotiable and enforced by hooks:
+**While implementing:**
 
-1. **Scripts for all issue operations.** Use mechanism scripts (create, transition, comment, assign, 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.
-6. **No secrets in commits.** Never commit `.env`, credentials, or API keys.
+- Update acceptance criteria checkboxes in the issue description (never in comments) as you complete them
+- Add progress comments on the issue for significant milestones
 
-## Workflow
+**When implementation is complete:**
 
-The FlyDocs development lifecycle. Read the workflow skill before taking any workflow action.
+- Transition to Review: `issues.py transition REF REVIEW "Implementation complete — ready for review"`
+- Summarize what was done and what to verify
 
-| Action               | Skill              | Entry Point                       |
-| -------------------- | ------------------ | --------------------------------- |
-| Capture issue        | `flydocs-workflow` | `stages/capture.md`               |
-| Refine / triage      | `flydocs-workflow` | `stages/refine.md`                |
-| Activate work        | `flydocs-workflow` | `stages/activate.md`              |
-| Implement            | `flydocs-workflow` | `stages/implement.md`             |
-| Code review          | `flydocs-workflow` | `stages/review.md`                |
-| 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/`                      |
+**When closing:**
 
-## Mechanism Scripts
+- Verify all acceptance criteria are met
+- Transition to Complete: `issues.py transition REF COMPLETE "All AC verified"`
 
-Issue operations are handled by the installed mechanism skill. Only one is active at a time.
+**Every status transition gets a comment.** No silent moves. No exceptions.
 
-| Tier              | Skill           | Backend                        |
-| ----------------- | --------------- | ------------------------------ |
-| Local (free)      | `flydocs-local` | File-based (`flydocs/issues/`) |
-| Cloud (connected) | `flydocs-cloud` | FlyDocs Relay API              |
+## Efficiency Rule
 
-Read the active mechanism skill's `SKILL.md` for script catalog and calling conventions.
+Do NOT read skill files, stage files, or workflow documentation before
+writing code. The rules above are everything you need for automatic workflow
+behavior — they are already in your context.
 
-**Shared contract scripts** (both tiers implement):
-`create_issue.py`, `transition.py`, `comment.py`, `list_issues.py`, `get_issue.py`, `assign.py`, `update_description.py`
+Only consult `.claude/skills/flydocs-workflow/` stage files when:
 
-## Premium Skills
+- Running a slash command (`/capture`, `/implement`, etc.) — these load stage files automatically
+- You genuinely need the detailed procedure for a complex workflow operation
 
-FlyDocs platform skills with premium functionality.
+For general coding, research, debugging, and building features — just do the
+work. No preliminary file reads needed.
 
-| 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)    |
+## Scripts
+
+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.
+
+| Dispatcher       | Operations                                                   |
+| ---------------- | ------------------------------------------------------------ |
+| `issues.py`      | create, get, list, transition, assign, update, comment, etc. |
+| `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, workflow nudge |
+| `PostToolUse` (Edit/Write) | After code changes      | Auto-format                          |
+| `PostToolUse` (Bash)       | After shell commands    | PR check, transition validation      |
+| `UserPromptSubmit`         | Before prompt           | Inject git/issue/AC context          |
+| `Stop`                     | Agent finishes response | Gate on workflow state               |
+| `SessionStart`             | New session begins      | Inject continuity context            |
 
 ## Output Formatting
 
@@ -112,17 +114,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, 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-context-graph | context graph, knowledge graph, relationships, dependencies, architecture                                                                          | .claude/skills/flydocs-context-graph/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      |
+Consult the workflow skill when performing **issue operations or status
+transitions**. For general coding tasks, skip this — just write code.
+
+| 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"