@flydocs/cli 0.5.0-beta.0

package/template/.flydocs/templates/feature.md

@@ -0,0 +1,173 @@
+<!-- AGENT INSTRUCTIONS
+When creating or refining a feature issue:
+
+1. CONTEXT SECTION:
+   - Explain the problem being solved, not just the solution
+   - Include business value or user impact
+   - Reference project goals from {content-folder}/context/overview.md if relevant
+
+2. USER STORY:
+   - Must follow "As a... I want... So that..." format
+   - Be specific about the user role (not just "user")
+   - Benefit should be concrete and measurable
+   - Include an example scenario for clarity
+
+3. ACCEPTANCE CRITERIA:
+   - Each criterion must be testable and specific
+   - Use checkboxes for tracking completion
+   - Include error handling scenarios
+   - "Must Have" = required for completion
+   - "Should Have" = nice to have, not blocking
+   - "Won't Have" = explicitly out of scope
+
+4. TECHNICAL NOTES:
+   - Reference patterns from {content-folder}/context/stack.md
+   - List specific components/files to create or modify
+   - Include data model changes if applicable
+   - Note any API changes needed
+
+5. DEPENDENCIES:
+   - List issues that must be completed first
+   - Note what future work this enables
+
+Remove these instructions when creating the final issue.
+-->
+
+## Context
+
+[Problem description - what user pain or business need does this address?]
+
+**Current Issues:**
+- [Issue or limitation 1]
+- [Issue or limitation 2]
+
+---
+
+## User Story
+
+**As a** [specific user role]
+**I want to** [specific goal or action]
+**So that** [concrete benefit or outcome]
+
+**Example Scenario:**
+[Real-world scenario where this feature would be used]
+
+---
+
+## Acceptance Criteria
+
+### Must Have
+- [ ] [Specific, measurable criterion 1]
+- [ ] [User can perform X action and see Y result]
+- [ ] [System behaves correctly when Z happens]
+- [ ] [Error handling: System shows helpful message when...]
+
+### Should Have
+- [ ] [Nice-to-have enhancement]
+
+### Won't Have (Out of Scope)
+- [Explicitly excluded functionality]
+
+### Tests
+- [ ] Tests written for core functionality
+- [ ] Edge cases and error scenarios covered
+- [ ] All tests passing
+
+### Documentation
+- [ ] Code documented (comments on complex logic)
+- [ ] Knowledge base updated (if significant decisions/patterns)
+- [ ] Context files updated (if architecture changes)
+- [ ] N/A - No significant documentation needed
+
+---
+
+## Technical Notes
+
+### Implementation Approach
+[High-level description of how this will be built]
+
+**Key Technical Decisions:**
+1. [Decision 1 and rationale]
+2. [Decision 2 and rationale]
+
+### Components Needed
+**New:**
+- `ComponentName` - [What it does]
+
+**Modify:**
+- `ExistingComponent` - [What changes needed]
+
+### Data Model
+```typescript
+// Schema changes if any
+// OR: No data model changes required
+```
+
+### API Endpoints
+- `POST /api/endpoint` - [Description]
+- OR: No new endpoints required
+
+---
+
+## Dependencies
+
+**Required Before Starting:**
+- [Feature or system that must exist first]
+- OR: No dependencies - can start immediately
+
+**Enables Future Work:**
+- [Feature that depends on this being complete]
+
+---
+
+## Design Reference
+<!-- Add Figma links as attachments -->
+
+---
+
+## AI Effort Estimate
+<!-- 
+AGENT: Fill this section during /refine using the flydocs-estimates skill.
+See .claude/skills/flydocs-estimates/SKILL.md for calculation details.
+Update Actuals section during /close for calibration.
+-->
+
+### Sizing Factors
+
+| Factor | Value | Multiplier |
+|--------|-------|------------|
+| **Task Type** | feature | base: 40k |
+| **Scope** | [S/M/L/XL] | ×[0.5/1.0/2.0/4.0] |
+| **Novelty** | [existing/partial/greenfield] | ×[0.7/1.2/2.0] |
+| **Clarity** | [defined/discovery/exploratory] | ×[0.8/1.5/2.5] |
+| **Codebase** | [simple/moderate/complex] | ×[0.8/1.0/1.5] |
+
+### Estimate
+
+**Provider**: [Claude Sonnet 4]  
+**Calculated Tokens**: ~[X]k  
+**Confidence**: ±[40-60]%  
+**Token Range**: [low]k - [high]k  
+**Cost Range**: $[low] - $[high]
+
+### Approach Comparison
+
+| Approach | Est. Cost | Est. Time | Recommendation |
+|----------|-----------|-----------|----------------|
+| **Full AI** | $[X] | [X] hrs | [When to use] |
+| **AI-Assisted** | $[X] + [X]hrs | [X] hrs | [When to use] |
+| **Human-Led** | $[X] (review) | [X] hrs | [When to use] |
+
+### Actuals (fill on /close)
+**Actual Tokens**: [fill after completion]  
+**Variance**: [+/-X]% [under/over estimate]  
+**Notes**: [what drove variance - blockers, scope changes, retries]
+
+---
+
+_Created: YYYY-MM-DD_
+
+
+
+
+

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

@@ -0,0 +1,122 @@
+<!-- AGENT INSTRUCTIONS
+When creating or refining an idea issue:
+
+1. SKETCH SECTION:
+   - Keep it light - this is brainstorming
+   - What/Why/How should each be one sentence
+   - Details can be rough notes
+
+2. POTENTIAL VALUE:
+   - Think about user benefit first
+   - Business value second
+   - Be honest about impact uncertainty
+
+3. QUESTIONS TO ANSWER:
+   - Capture what you don't know
+   - These become research tasks before refinement
+   - Include feasibility, effort, and value questions
+
+4. COMPLEXITY:
+   - If XL or larger, note how to break it down
+   - Ideas often seem smaller until investigated
+
+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
+
+6. CONVERSION:
+   - When idea is validated, create feature issue
+   - Link the feature issue in "Refined" status
+
+Remove these instructions when creating the final issue.
+-->
+
+## 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?]
+
+---
+
+## 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_
+
+
+
+

package/template/.flydocs/templates/instructions.md

@@ -0,0 +1,228 @@
+# Project Instructions
+
+> Auto-generated from detected stack. Update as your project evolves.
+> This file takes precedence over skill defaults for project-specific patterns.
+
+---
+
+## Tech Stack
+
+<!-- Auto-filled from detection. Update versions as needed. -->
+
+- **Framework:** {{framework}}
+- **Database:** {{database}}
+- **Auth:** {{auth}}
+- **Styling:** {{styling}}
+- **Language:** TypeScript (strict mode)
+
+---
+
+## Active Skills
+
+<!-- Skills installed based on detected stack -->
+
+{{#each skills}}
+- `{{this}}` - See `.claude/skills/{{this}}/SKILL.md`
+{{/each}}
+
+---
+
+## Project-Specific Patterns
+
+### Established Conventions
+
+<!-- Add patterns discovered during development -->
+
+```typescript
+// Example: API response format
+type ApiResponse<T> = {
+  data: T;
+  error?: string;
+  meta?: { page: number; total: number };
+};
+```
+
+### File Organization
+
+<!-- Document your project's structure conventions -->
+
+```
+src/
+├── app/              # Next.js App Router pages
+├── components/       # Shared UI components
+│   ├── ui/          # Primitives (Button, Input, etc.)
+│   └── features/    # Feature-specific components
+├── lib/             # Utilities and helpers
+├── hooks/           # Custom React hooks
+└── types/           # TypeScript type definitions
+```
+
+### Naming Conventions
+
+<!-- Project-specific naming rules -->
+
+- Components: PascalCase (`UserProfile.tsx`)
+- Hooks: camelCase with `use` prefix (`useAuth.ts`)
+- Utilities: camelCase (`formatDate.ts`)
+- Types: PascalCase with descriptive suffix (`UserResponse`, `CreateUserInput`)
+
+---
+
+## Decisions & Rationale
+
+<!-- Link to ADRs or explain key architectural choices -->
+
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| Use Server Components by default | Better performance, simpler mental model | {{date}} |
+| Convex for real-time | Built-in subscriptions, type safety | {{date}} |
+
+---
+
+## Anti-Patterns for This Project
+
+<!-- Things that don't work well in YOUR specific codebase -->
+
+### Don't Do This
+
+```typescript
+// ❌ Don't use client-side data fetching for initial data
+'use client';
+useEffect(() => { fetch('/api/data')... }, []);
+
+// ✓ Fetch in Server Component instead
+async function Page() {
+  const data = await getData();
+  return <ClientComponent initialData={data} />;
+}
+```
+
+### Avoid These Patterns
+
+- Don't create new API routes when direct DB access works
+- Don't use Context for data that should come from Server Components
+- Don't add `'use client'` unless interactivity is needed
+
+---
+
+## MCP Configuration
+
+<!-- Stack-specific MCP preferences for this project -->
+
+### MCP Strategy
+
+Configure in `.flydocs/config.json`:
+
+```json
+{
+  "mcp": {
+    "preferred": ["context7", "figma"],
+    "fallbackOnly": ["linear"],
+    "stackSpecific": {
+      "convex": {
+        "note": "Use Context7 for docs, CLI for schema changes"
+      }
+    }
+  }
+}
+```
+
+- **preferred**: MCPs to use proactively (unique capabilities like Figma visuals, Context7 docs)
+- **fallbackOnly**: MCPs with script alternatives (use scripts first, MCP if script fails)
+- **stackSpecific**: Per-stack notes and usage guidance
+
+### Stack-Specific MCP Notes
+
+<!-- Uncomment and customize for your stack -->
+
+<!--
+#### Convex
+- Use Context7 MCP for Convex API documentation
+- Prefer `convex dev` CLI for schema changes over direct mutations
+- Query patterns: Use `.collect()` for small datasets, pagination for large
+-->
+
+<!--
+#### Supabase
+- Use Supabase MCP for database operations when available
+- Prefer RLS policies over application-level auth checks
+- Use database functions for complex operations
+-->
+
+<!--
+#### Firebase
+- Use Firebase MCP for Firestore operations
+- Prefer security rules over client-side validation
+- Use batch operations for multiple writes
+-->
+
+---
+
+## Skill Overrides
+
+<!-- Override specific skill recommendations for this project -->
+
+### nextjs
+
+<!-- Example: Override default caching strategy -->
+
+```typescript
+// This project uses shorter cache times due to real-time requirements
+cacheLife('seconds');  // Instead of skill default 'hours'
+```
+
+### convex
+
+<!-- Example: Project-specific schema conventions -->
+
+```typescript
+// All tables must include audit fields
+defineTable({
+  // ... fields
+  createdAt: v.number(),
+  updatedAt: v.number(),
+  createdBy: v.optional(v.id('users')),
+});
+```
+
+---
+
+## Environment Variables
+
+<!-- Document required env vars for this project -->
+
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| `DATABASE_URL` | Database connection | Yes |
+| `NEXT_PUBLIC_API_URL` | Public API endpoint | Yes |
+| `AUTH_SECRET` | Auth session encryption | Yes |
+
+---
+
+## Testing Patterns
+
+<!-- Project-specific testing conventions -->
+
+```typescript
+// Test file naming: *.test.ts or *.spec.ts
+// Test location: Co-located with source files
+
+// Example test structure
+describe('UserService', () => {
+  it('creates a user with valid data', async () => {
+    // Arrange
+    const input = { name: 'Test', email: 'test@example.com' };
+
+    // Act
+    const result = await createUser(input);
+
+    // Assert
+    expect(result.id).toBeDefined();
+  });
+});
+```
+
+---
+
+*Last updated: {{date}}*
+*FlyDocs version: 6.3.0*

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

@@ -0,0 +1,35 @@
+<!-- 
+LINEAR DEFAULT TEMPLATE
+========================
+Copy this to Linear as the default issue template.
+This is the ONLY template humans need in Linear.
+Agents apply full templates via /refine.
+-->
+
+## What
+
+[One sentence - what is this about?]
+
+## Why
+
+[Why does this matter? What's the problem or opportunity?]
+
+## Context
+
+[Any additional details that would help understand this]
+
+- Who discovered/requested this?
+- When did it come up?
+- How urgent does it feel?
+
+## Notes
+
+[Anything else - links, screenshots, related issues]
+
+---
+
+_Add `triage` label. Agent will classify and structure via `/refine`._
+
+
+
+