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

package/template/.flydocs/templates/idea.md

@@ -1,122 +1,22 @@
-<!-- AGENT INSTRUCTIONS
-When creating or refining an idea issue:
+<!-- AGENT: Use this template when creating idea issues. Fill all [bracketed] sections. -->
 
-1. SKETCH SECTION:
-   - Keep it light - this is brainstorming
-   - What/Why/How should each be one sentence
-   - Details can be rough notes
+## What
 
-2. POTENTIAL VALUE:
-   - Think about user benefit first
-   - Business value second
-   - Be honest about impact uncertainty
+[One sentence describing the idea]
 
-3. QUESTIONS TO ANSWER:
-   - Capture what you don't know
-   - These become research tasks before refinement
-   - Include feasibility, effort, and value questions
+## Why
 
-4. COMPLEXITY:
-   - If XL or larger, note how to break it down
-   - Ideas often seem smaller until investigated
+[Problem or opportunity this addresses]
 
-5. STATUS TRACKING:
-   - Ideas follow: Captured → Researched → Validated → Refined or Declined
-   - "Refined" means it became a full feature issue
-   - "Declined" with reason is valuable documentation
+## Rough Shape
 
-6. CONVERSION:
-   - When idea is validated, create feature issue
-   - Link the feature issue in "Refined" status
+[Initial thinking on approach — does not need to be detailed]
 
-Remove these instructions when creating the final issue.
--->
+## Open Questions
 
-## Sketch
-
-**Quick Description:**
-- **What:** [One sentence - what is this?]
-- **Why:** [One sentence - why might this be valuable?]
-- **How:** [One sentence - rough idea of how it might work]
-
-**Details:**
-[Additional thoughts, context, inspiration, related ideas]
-
----
-
-## Potential Value
-
-**For Users:**
-- [Benefit 1]
-- [Benefit 2]
-
-**For Business/Product:**
-- [Value 1]
-- [Value 2]
-
-**Estimated Impact:** 🔥 High | 📊 Medium | 💡 Low | ❓ Unknown
-
----
-
-## Questions to Answer
-
-**Unknowns:**
-- [ ] What needs research or investigation?
-- [ ] What's the technical feasibility?
-- [ ] What's the rough effort estimate?
-- [ ] Does this already exist elsewhere?
-
-**Dependencies:**
-- [ ] Does this depend on other work?
-- [ ] Are there technical constraints?
-
-**Risks:**
-- [ ] What could go wrong?
-
----
-
-## Rough Complexity
-
-**Complexity:** XS | S | M | L | XL | ❓ Unknown
-
-**If XL or larger:**
-[How could this be broken into smaller features?]
-
----
+- [Question 1]
+- [Question 2]
 
 ## Next Steps
 
-**To Validate This Idea:**
-1. [Research step 1]
-2. [User validation needed]
-3. [Technical spike or prototype]
-
-**To Turn Into a Feature:**
-1. [ ] Answer the questions above
-2. [ ] Define clear user story and acceptance criteria
-3. [ ] Get stakeholder buy-in
-4. [ ] Create feature issue with full template
-
----
-
-## Status Tracking
-
-- [ ] **Captured** - Idea written down ✅
-- [ ] **Researched** - Questions answered, feasibility checked
-- [ ] **Validated** - Worth pursuing
-- [ ] **Refined** - Converted to full feature issue
-- [ ] **Declined** - Decided not to pursue
-
-**If Declined:**
-- **Reason:** [Why we decided not to do this]
-
-**If Refined:**
-- **New Issue:** [Link to feature issue created from this idea]
-
----
-
-_Captured: YYYY-MM-DD_
-
-
-
-
+- [ ] [First step to explore or validate this idea]

package/template/.flydocs/templates/quick-capture.md

@@ -1,8 +1,8 @@
-<!-- 
-LINEAR DEFAULT TEMPLATE
+<!--
+PROVIDER DEFAULT TEMPLATE
 ========================
-Copy this to Linear as the default issue template.
-This is the ONLY template humans need in Linear.
+Copy this to your issue tracker as the default issue template.
+This is the ONLY template humans need in their issue tracker.
 Agents apply full templates via /refine.
 -->
 
@@ -29,7 +29,3 @@ Agents apply full templates via /refine.
 ---
 
 _Add `triage` label. Agent will classify and structure via `/refine`._
-
-
-
-

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.3
+0.6.0-alpha.30

package/template/AGENTS.md

@@ -1,17 +1,29 @@
 # FlyDocs Agent Instructions
 
-Prefer reading project documentation over guessing from training data.
-When performing workflow, issue management, or process tasks, consult the
-relevant documentation files before acting.
+## Automatic Workflow Behavior
 
-## Rules
+These behaviors are **always on**. Execute them automatically as part of doing
+the work — do not wait for explicit commands.
 
-1. **Use scripts for all issue operations.** Create, transition, comment, assign — execute scripts, don't describe actions.
-2. **Every status transition gets a comment.** No silent moves.
-3. **Assignment required before In Progress.** Always assign before starting work.
-4. **Checkboxes live in issue description, never comments.** Update the description to track progress.
-5. **Session wrap posts a summary.** Summarize progress at end of session.
-6. **No secrets in commits.** Never commit `.env`, credentials, or API keys.
+- **Starting work** → assign if needed, then transition:
+  `issues.py assign REF ASSIGNEE`
+  `issues.py transition REF IMPLEMENTING "Starting implementation"`
+- **Completing implementation** → transition with summary:
+  `issues.py transition REF REVIEW "Implementation complete — [summary]"`
+- **Closing** → verify AC, then transition:
+  `issues.py transition REF COMPLETE "All acceptance criteria verified"`
+- **Every transition gets a comment** — no silent moves, no exceptions
+- **Checkboxes in description, never comments** — update AC as you go:
+  `issues.py description REF --text "updated description with checked boxes"`
+- **Session wrap posts a summary** via `session.py project-update`
+
+All scripts: `python3 .claude/skills/flydocs-workflow/scripts/<dispatcher>`
+
+## Efficiency
+
+Do NOT read skill files or workflow documentation before writing code.
+The rules above are already in your context. For general coding, research,
+and building features — just do the work.
 
 ## Workflow
 
@@ -37,16 +49,20 @@ Detailed procedures: `.claude/skills/flydocs-workflow/`
 
 Scripts handle all issue management. The active backend (local files or cloud provider) determines the implementation.
 
-**Available operations:** create issue, transition status, add comment, list issues, get issue details, assign, update description, status summary.
+**Available operations:** create issue, transition status, add comment, list issues, get issue details, assign, update description, estimate, priority, link, block, project update, status summary.
 
-Script location: `.claude/skills/flydocs-local/scripts/` or `.claude/skills/flydocs-cloud/scripts/`
+Scripts use grouped dispatchers in `.claude/skills/flydocs-workflow/scripts/`:
 
-## Premium Skills
+| 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)                         |
 
-| Skill             | Documentation                                                           |
-| ----------------- | ----------------------------------------------------------------------- |
-| Figma Integration | `.claude/skills/flydocs-figma/` — design extraction, token mapping      |
-| Cost Estimation   | `.claude/skills/flydocs-estimates/` — AI token/labor estimates (opt-in) |
+The unified client auto-detects tier (cloud vs local) — scripts never check tier directly.
 
 ## Writing Style
 
@@ -80,26 +96,22 @@ Follow these rules in every response for consistent, scannable output.
 
 ## Project Context
 
-| File                         | Purpose                                                 |
-| ---------------------------- | ------------------------------------------------------- |
-| `flydocs/context/project.md` | Product scope, tech stack, active priorities            |
-| `.flydocs/config.json`       | Configuration — 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 |
 
 <!-- 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-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  |
+Consult the workflow skill for **issue operations and status transitions only**.
+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/CHANGELOG.md

@@ -7,6 +7,43 @@ Versioning: [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.6.0-alpha.24] — 2026-03-30
+
+### Added
+
+- **Auto-resolve provider identity** — `workspace.py validate` now attempts
+  `GET /auth/me` before requiring manual `set-identity` step. If the relay
+  returns a provider identity, `me.json` is written automatically (FLY-520)
+
+### Changed
+
+- **Friendlier identity fallback** — when auto-resolve fails, the validation
+  message now points to the dashboard profile page instead of showing a raw
+  script command
+
+---
+
+## [0.6.0-alpha.23] — 2026-03-29
+
+### Changed
+
+- **CLAUDE.md** — scoped skill-led reasoning to workflow operations only; general
+  coding no longer triggers skill file reads (FLY-450)
+- **AGENTS.md** — added exact script commands to Automatic Workflow Behavior section
+  for deterministic issue transitions (FLY-450)
+
+---
+
+## [0.6.0-alpha.4] — 2026-03-13
+
+### Added
+
+- **Status mapping** — new `list_statuses.py` and `set_status_mapping.py`
+  scripts. Setup flow auto-maps provider workflow states to FlyDocs statuses
+  after label config, warns on unmapped statuses without blocking.
+
+---
+
 ## [0.6.0-alpha.3] — 2026-03-13
 
 ### Added

package/template/flydocs/README.md

@@ -30,8 +30,6 @@ FlyDocs will **never overwrite** these files during updates - they're yours to m
 ├── config.json            # Tier, provider settings, workspace config
 ├── version                # For upgrade detection
 ├── rules/                 # Workflow rules
-├── scripts/               # Automation scripts
-├── hooks/                 # Workflow hooks
 └── templates/             # Issue templates (source)
 
 flydocs/                   # PROJECT CONTENT (evolves with project)
@@ -153,7 +151,7 @@ See `.flydocs/config.json` for:
 - FlyDocs version
 - `tier` - "local" (free) or "cloud" (connected to provider)
 - `paths.content` - This folder name (default: "flydocs")
-- `provider.type` - Issue tracker provider (null for local, "linear" for cloud)
+- `provider.type` - Issue tracker provider (null for local, e.g. "linear", "jira" for cloud)
 - `workspace.activeProjects` - Array of active project IDs (cloud tier)
 - `workspace.product` - Product identity (name, labelIds, icon, color)
 - `statusMapping` - Workflow state names

package/template/flydocs/context/project.md

@@ -3,11 +3,13 @@
 ## What This Is
 
 <!-- Fill during setup: 2-3 sentences describing the project -->
+
 [Project name] — [what it does and who it's for].
 
 ## Stack
 
 <!-- Fill during setup: auto-detected or manual -->
+
 - **Framework**: [e.g., Next.js 14 / React 18]
 - **Language**: [e.g., TypeScript 5.x]
 - **Styling**: [e.g., Tailwind CSS]
@@ -20,8 +22,8 @@
 Code standards are defined by installed community skills. Skills are installed
 based on detected stack during setup or manually via `npx flydocs skills add`.
 
-Read the relevant skill before writing code in that domain. List installed skills
-with `npx flydocs skills list`.
+Installed community skills provide domain-specific patterns. List them with
+`npx flydocs skills list`.
 
 ### Project-Specific Standards
 
@@ -36,6 +38,7 @@ Project notes: `flydocs/knowledge/notes/`
 ## Active Priorities
 
 <!-- Updated by session-wrap or manually -->
+
 1. [Current priority 1]
 2. [Current priority 2]
 3. [Current priority 3]
@@ -48,4 +51,4 @@ Project notes: `flydocs/knowledge/notes/`
 
 ---
 
-*Last Updated: YYYY-MM-DD*
+_Last Updated: YYYY-MM-DD_

package/template/flydocs/design-system/README.md

@@ -6,7 +6,7 @@
 
 ## Purpose
 
-When using the `flydocs-figma` skill to extract designs, the AI needs to know:
+When using the workflow skill's Figma capabilities to extract designs, the AI needs to know:
 
 1. **How Figma tokens map to code** (colors, spacing, typography)
 2. **What component patterns exist** (and how to match them)
@@ -83,9 +83,9 @@ flydocs/design-system/
 
 ---
 
-## Integration with flydocs-figma Skill
+## Integration with Figma Workflow
 
-The `flydocs-figma` skill references this directory:
+The `flydocs-workflow` skill's Figma capabilities reference this directory:
 
 1. **Before extraction** - Loads token-mapping.md for translation rules
 2. **During extraction** - Matches Figma elements to documented patterns

package/template/flydocs/knowledge/INDEX.md

@@ -4,97 +4,82 @@
 AGENT INSTRUCTIONS:
 - Scan this file FIRST when looking for existing knowledge
 - Use descriptions to assess relevance before loading full docs
-- Update this index when adding new knowledge docs
+- Update this index when adding or modifying knowledge docs
+- Always use real dates, never leave as YYYY-MM-DD
 -->
 
 ## Quick Reference
 
-| Category | Count | Last Updated |
-|----------|-------|--------------|
-| Decisions | 0 | - |
-| Features | 0 | - |
-| Notes | 0 | - |
-| Product | 2 | YYYY-MM-DD |
+| Category  | Count | Last Updated |
+| --------- | ----- | ------------ |
+| Decisions | 0     | -            |
+| Features  | 0     | -            |
+| Notes     | 0     | -            |
+| Product   | 2     | -            |
 
 ---
 
-## 📋 Decisions (ADRs)
+## Decisions (ADRs)
 
-Architecture Decision Records - why we made key technical choices.
+Architecture Decision Records — why we made key technical choices.
 
-| ID | Title | Status | Date |
-|----|-------|--------|------|
-| - | No decisions recorded yet | - | - |
+| ID  | Title                     | Status | Date |
+| --- | ------------------------- | ------ | ---- |
+| -   | No decisions recorded yet | -      | -    |
 
 <!-- Example:
-| 001 | Use Convex for Backend | Accepted | 2024-01-15 |
-  → Explains why we chose Convex over traditional REST API
+| 001 | Use Convex for Backend | Accepted | 2026-01-15 |
+  -> Explains why we chose Convex over traditional REST API
 -->
 
 ---
 
-## 🔧 Features
+## Features
 
 Documentation for complex features that need more than a spec.
 
-| Feature | Description | Last Updated |
-|---------|-------------|--------------|
-| - | No feature docs yet | - |
+| Feature | Description         | Last Updated |
+| ------- | ------------------- | ------------ |
+| -       | No feature docs yet | -            |
 
 <!-- Example:
-| auth-system | Complete auth flow documentation | 2024-02-01 |
-  → OAuth setup, session handling, role-based access
+| auth-system | Complete auth flow documentation | 2026-02-01 |
+  -> OAuth setup, session handling, role-based access
 -->
 
 ---
 
-## 📝 Notes
+## Notes
 
 Technical discoveries, gotchas, learnings.
 
-| Topic | Description | Added |
-|-------|-------------|-------|
-| - | No notes yet | - |
+| Topic | Description  | Added |
+| ----- | ------------ | ----- |
+| -     | No notes yet | -     |
 
 <!-- Example:
-| api-rate-limits | Third-party API quirks and workarounds | 2024-01-20 |
-  → Stripe webhook retries, Figma API limits, etc.
+| api-rate-limits | Third-party API quirks and workarounds | 2026-01-20 |
+  -> Stripe webhook retries, Figma API limits, etc.
 -->
 
 ---
 
-## 👥 Product
+## Product
 
 User research and product documentation.
 
-| Document | Description | Last Updated |
-|----------|-------------|--------------|
-| personas.md | Target user profiles | YYYY-MM-DD |
-| user-flows.md | Key user journeys | YYYY-MM-DD |
+| Document      | Description          | Last Updated |
+| ------------- | -------------------- | ------------ |
+| personas.md   | Target user profiles | -            |
+| user-flows.md | Key user journeys    | -            |
 
 ---
 
 ## How to Add Knowledge
 
-### New Decision (ADR)
-```bash
-# Create: flydocs/knowledge/decisions/NNN-title.md
-# Update: This index with new entry
-```
-
-### New Feature Doc
-```bash
-# Create: flydocs/knowledge/features/feature-name.md
-# Update: This index with new entry
-```
-
-### New Note
-```bash
-# Create: flydocs/knowledge/notes/topic-name.md
-# Update: This index with new entry
-```
-
----
-
-*Last Updated: YYYY-MM-DD*
-
+1. Choose the category: decision, feature, note, or product
+2. Copy the template from `templates/<category>.md`
+3. Fill in the frontmatter (title, created date, related issues)
+4. Write the content following the template structure
+5. Add an entry to this index with a concise description
+6. Use the `/knowledge` command for a guided flow

package/template/flydocs/knowledge/README.md

@@ -6,42 +6,78 @@ This directory contains project knowledge that accumulates over time.
 
 ```
 knowledge/
-├── INDEX.md      # Start here - inventory of all knowledge
-├── decisions/    # Architecture Decision Records (ADRs)
-├── features/     # Complex feature documentation
-├── notes/        # Technical discoveries and learnings
-└── product/      # User research and product docs
+├── INDEX.md       # Start here — inventory of all knowledge
+├── templates/     # Structural templates for each category
+├── decisions/     # Architecture Decision Records (ADRs)
+├── features/      # Complex feature documentation
+├── notes/         # Technical discoveries and learnings
+└── product/       # User research and product docs
 ```
 
-## When to Add Knowledge
+## Templates
+
+Use templates from `templates/` when creating new knowledge docs. Each template includes
+a frontmatter block with required metadata fields.
+
+### Required Frontmatter
+
+All knowledge docs must include YAML frontmatter:
+
+```yaml
+---
+title: "Descriptive title"
+created: 2026-03-17
+lastUpdated: 2026-03-17
+relatedIssues: [FLY-123, FLY-456]
+---
+```
+
+Additional fields vary by category — see the template for each type.
+
+**Always update `lastUpdated`** when modifying an existing doc.
+
+## When to Create Knowledge
 
 ### Decisions (`decisions/`)
+
 Add an ADR when you make a significant technical choice:
+
 - Choosing a framework or library
 - Designing a system architecture
 - Establishing a pattern that others should follow
+- Rejecting an approach (document why, so others don't repeat the investigation)
 
 **Format**: `NNN-title.md` (e.g., `001-use-convex.md`)
+**Template**: `templates/decision.md`
 
 ### Features (`features/`)
+
 Add feature documentation when:
+
 - A feature is too complex for just a spec
 - Multiple specs relate to one system
 - Future developers will need deep context
 
 **Format**: `feature-name.md` (e.g., `auth-system.md`)
+**Template**: `templates/feature.md`
 
 ### Notes (`notes/`)
+
 Add notes when you discover:
+
 - API quirks or gotchas
 - Performance optimizations
 - Debugging techniques
 - Third-party service behaviors
+- Workarounds that aren't obvious from code
 
 **Format**: `topic-name.md` (e.g., `stripe-webhooks.md`)
+**Template**: `templates/note.md`
 
 ### Product (`product/`)
+
 Add product docs for:
+
 - User personas
 - User flows and journeys
 - Research findings
@@ -49,14 +85,29 @@ Add product docs for:
 
 **Format**: `document-name.md` (e.g., `personas.md`)
 
+## When to Prompt for Knowledge Capture
+
+Proactively suggest creating a knowledge doc when:
+
+- An architectural decision was made during implementation
+- A non-obvious workaround or debugging technique was discovered
+- A third-party API or integration behavior was learned through trial and error
+- A pattern was established that future work should follow
+- A significant feature was completed that spans multiple issues
+
+The `/knowledge` command provides a guided flow for creating docs.
+
 ## Always Update INDEX.md
 
-When adding any knowledge document, update `INDEX.md` so agents can discover it.
+When adding or modifying any knowledge document:
+
+1. Add or update the entry in `INDEX.md`
+2. Set the date to the current date (never leave as `YYYY-MM-DD`)
+3. Write a concise description that helps agents assess relevance without loading the full doc
 
 ## Relationship to Specs
 
-- **Specs** (in Linear) = What we're building now
+- **Specs** (in issue tracker) = What we're building now
 - **Knowledge** (here) = What we've learned that persists
 
 Specs reference knowledge. Knowledge grows from implementing specs.
-