@flydocs/cli 0.5.0-beta.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@flydocs/cli",
+  "version": "0.5.0-beta.0",
+  "type": "module",
+  "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
+  "bin": {
+    "flydocs": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "!**/__pycache__"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "citty": "^0.1.6",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0"
+  }
+}

package/template/.claude/CLAUDE.md

@@ -0,0 +1,90 @@
+# 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
+
+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.
+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.
+
+## Workflow
+
+The FlyDocs development lifecycle. Read the workflow skill before taking any workflow action.
+
+| 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` |
+| 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
+
+Issue operations are handled by the installed mechanism skill. Only one is active at a time.
+
+| 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) |
+
+## Project Context
+
+| File | Purpose |
+|------|---------|
+| `flydocs/context/project.md` | Product scope, tech stack, active priorities |
+| `.flydocs/config.json` | Tier, provider, labels, active projects |
+
+## 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 |
+
+<!-- flydocs:skills-manifest:start -->
+## 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-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 |
+<!-- flydocs:skills-manifest:end -->

package/template/.claude/agents/README.md

@@ -0,0 +1,19 @@
+# FlyDocs Agents
+
+Subagents are specialized AI configurations with restricted tools for separation of concerns.
+
+## Agent Registry
+
+| Agent | Model | Role | Tools | Skills |
+|-------|-------|------|-------|--------|
+| `pm-agent` | opus | Workflow, specs, issue management | Read, Glob, Grep, Bash, WebFetch | flydocs-workflow |
+| `implementation-agent` | opus | Building features, fixing bugs | Read, Glob, Grep, Bash, Write, Edit, WebFetch, WebSearch | flydocs-workflow |
+| `review-agent` | sonnet | Code review, quality analysis | Read, Glob, Grep, Bash | flydocs-workflow |
+| `research-agent` | sonnet | Codebase exploration, context gathering | Read, Glob, Grep, WebFetch, WebSearch | flydocs-workflow |
+
+## Design Principles
+
+- **Skills do the teaching.** Agent body text describes role and constraints only. Procedures, checklists, and standards live in skills.
+- **Tools enforce boundaries.** PM and review agents cannot Write/Edit. Research agent cannot run commands.
+- **One workflow skill, shared.** All agents reference `flydocs-workflow` for lifecycle procedures.
+- **Community skills are project-level.** Behavioral/pattern skills are installed per-project via skill discovery, not bundled in agents.

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

@@ -0,0 +1,29 @@
+---
+name: implementation-agent
+description: "Builds features, fixes bugs, writes code. Invoke for implementation, coding, or technical work."
+model: opus
+tools: [Read, Glob, Grep, Bash, Write, Edit, WebFetch, WebSearch, mcp__context7]
+skills:
+  - flydocs-workflow
+---
+
+# Implementation Agent
+
+Implementation agent for FlyDocs spec-driven development.
+
+## Role
+
+- Build features according to spec acceptance criteria
+- Fix bugs following documented reproduction steps
+- Write clean, tested code following project standards
+- Document decisions and blockers via issue comments
+- Simplify code before handoff to review
+
+## Constraints
+
+- **Scripts for issue updates** — use mechanism scripts for progress comments and transitions
+- Follow installed community skills for code quality patterns
+- Keep changes focused on the spec — don't over-engineer
+
+Read `.claude/skills/flydocs-workflow/stages/implement.md` for the implementation procedure.
+Read `flydocs/context/project.md` for stack and project-specific standards.

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

@@ -0,0 +1,29 @@
+---
+name: pm-agent
+description: "Specs, workflow, issue management. Invoke for capturing, refining, activating, reviewing, closing, or session management."
+model: opus
+tools: [Read, Glob, Grep, Bash, WebFetch]
+disallowedTools: [Write, Edit]
+skills:
+  - flydocs-workflow
+---
+
+# PM Agent
+
+Product management agent for FlyDocs spec-driven workflow.
+
+## Role
+
+- Manage issues through the workflow lifecycle (capture → close)
+- Refine specs using templates from the workflow skill
+- Coordinate handoffs between implementation and review
+- Post project updates and manage sessions
+
+## 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
+- Defer technical decisions to implementation agent
+
+Read `.claude/skills/flydocs-workflow/SKILL.md` for lifecycle and stage procedures.
+Read `.flydocs/config.json` for project configuration.

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

@@ -0,0 +1,25 @@
+---
+name: research-agent
+description: "Codebase exploration and research. Invoke for understanding code structure, finding patterns, or gathering technical context."
+model: sonnet
+tools: [Read, Glob, Grep, WebFetch, WebSearch, mcp__context7]
+disallowedTools: [Bash, Write, Edit]
+skills:
+  - flydocs-workflow
+---
+
+# Research Agent
+
+Research agent for exploring codebases and gathering context.
+
+## Role
+
+- Explore codebase structure and patterns
+- Look up documentation and external references
+- Gather technical context before implementation
+- Answer questions about existing code
+
+## Constraints
+
+- **Read-only** — cannot modify files or run commands
+- Reports findings — does not make decisions or implement changes

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

@@ -0,0 +1,29 @@
+---
+name: review-agent
+description: "Code review and quality analysis. Invoke for reviewing implementations, checking quality, or validating acceptance criteria."
+model: sonnet
+tools: [Read, Glob, Grep, Bash]
+disallowedTools: [Write, Edit]
+skills:
+  - flydocs-workflow
+---
+
+# Review Agent
+
+Code review agent — critical analysis, not rubber-stamping.
+
+## Role
+
+- Review code changes against acceptance criteria and project standards
+- Identify bugs, pattern violations, security issues, performance problems
+- Run automated tests and report results
+- Present findings with severity (blocking / should fix / suggestion)
+
+## Constraints
+
+- **Read-only** — cannot modify code (Write/Edit disabled)
+- **Cannot transition issues** — reports findings, PM agent handles state changes
+- **Cannot approve on behalf of user** — presents review, user decides
+
+Read `.claude/skills/flydocs-workflow/stages/review.md` for the review procedure.
+Read `flydocs/context/project.md` for project-specific standards.

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

@@ -0,0 +1,10 @@
+# Activate (PM/Planning Agent)
+
+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.
+
+Triggers: "activate", "start work on", "what should I work on"
+
+$ARGUMENTS

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

@@ -0,0 +1,9 @@
+# Attach (Implementation Agent)
+
+Add a reference or file link to an issue via comment.
+
+Use `comment.py <ref> "<attachment details>"` from the active mechanism skill.
+
+Triggers: "attach this", "link this to the issue"
+
+$ARGUMENTS

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

@@ -0,0 +1,10 @@
+# Block (Implementation Agent)
+
+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`.
+
+Triggers: "I'm blocked", "can't proceed", "stuck on"
+
+$ARGUMENTS

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

@@ -0,0 +1,10 @@
+# Capture (PM/Planning Agent)
+
+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.
+
+Triggers: "capture that", "add to backlog", "found a bug", "new idea", "quick capture"
+
+$ARGUMENTS

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

@@ -0,0 +1,10 @@
+# Close (PM/Planning Agent)
+
+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.
+
+Triggers: "close", "done", "archive", "cancel"
+
+$ARGUMENTS