wogiflow 1.0.0

package/templates/hybrid/_patterns.md

@@ -0,0 +1,45 @@
+# Project Patterns
+
+This file will be auto-generated during onboarding based on your actual codebase patterns.
+
+Run `./scripts/flow templates generate` to populate this file with real examples from your project.
+
+## Naming Conventions
+
+- Components: PascalCase (e.g., `UserProfile.tsx`)
+- Hooks: camelCase with `use` prefix (e.g., `useAuth.ts`)
+- Services: camelCase with `Service` suffix (e.g., `authService.ts`)
+- Utilities: camelCase (e.g., `formatDate.ts`)
+- Types/Interfaces: PascalCase (e.g., `UserProfile`, `AuthResponse`)
+
+## Import Order
+
+1. React/framework imports
+2. Third-party libraries
+3. Aliased imports (@/ or ~/)
+4. Relative imports
+5. Type imports (with `type` keyword)
+
+## Project-Specific Import Patterns
+
+{{#if importPatterns}}
+{{importPatterns}}
+{{else}}
+Use the import patterns you see in the existing file or context.
+{{/if}}
+
+## Available Shared Components
+
+{{#if availableComponents}}
+These components exist in this project. Use them instead of creating new ones:
+{{availableComponents}}
+{{/if}}
+
+## Type Locations
+
+{{#if typeLocations}}
+{{typeLocations}}
+{{else}}
+- Feature types: Typically in `./types.ts` or `../api/types.ts` relative to the feature
+- Shared types: `@/types/` or `src/types/`
+{{/if}}

package/templates/hybrid/create-component.md

@@ -0,0 +1,127 @@
+{{include _base.md}}
+
+# Task: Create React Component
+
+{{include _patterns.md}}
+
+## Component Specification
+
+**CRITICAL - You are creating this component:**
+
+| Field | Value |
+|-------|-------|
+| **Component Name** | `{{name}}` |
+| **File Path** | `{{path}}` |
+| **Props Interface** | `{{name}}Props` |
+
+**Description:**
+{{description}}
+
+**Props (if any):**
+{{props}}
+
+**Must Use These Existing Components/Hooks:**
+{{uses}}
+
+**Expected Behavior:**
+{{behavior}}
+
+## What You MUST Create
+
+```
+// File: {{path}}
+// Component: {{name}}
+// Interface: {{name}}Props
+
+import { ... } from 'react';
+
+interface {{name}}Props {
+  // props here
+}
+
+/**
+ * [Brief description of {{name}}]
+ */
+export function {{name}}({ ...props }: {{name}}Props) {
+  return (
+    // JSX for {{name}} here
+  );
+}
+```
+
+## What NOT to Create
+
+❌ Do NOT create any component except `{{name}}`
+❌ Do NOT create types/interfaces from the project context section
+❌ Do NOT create components mentioned as "available" - those already exist
+❌ Do NOT output anything except the code for `{{name}}`
+
+## Requirements Checklist
+
+1. [ ] Component is named exactly `{{name}}` (not something else!)
+2. [ ] Props interface is named `{{name}}Props`
+3. [ ] Exported as: `export function {{name}}`
+4. [ ] Uses only imports from "Available Components" or standard React
+5. [ ] Follows the component pattern from _patterns.md
+6. [ ] Has JSDoc comment
+7. [ ] Contains JSX (this is a .tsx file)
+
+## Golden Example (Follow This Pattern)
+
+This example shows the CORRECT output format:
+
+```tsx
+'use client';
+
+import { useState, useCallback } from 'react';
+import { Button } from '@/components/ui/Button';
+
+interface UserCardProps {
+  name: string;
+  email: string;
+  onEdit?: () => void;
+}
+
+/**
+ * Displays user information with optional edit action.
+ */
+export function UserCard({ name, email, onEdit }: UserCardProps) {
+  const [isHovered, setIsHovered] = useState(false);
+
+  const handleMouseEnter = useCallback(() => setIsHovered(true), []);
+  const handleMouseLeave = useCallback(() => setIsHovered(false), []);
+
+  return (
+    <div
+      className="p-4 rounded-lg border"
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+    >
+      <h3 className="font-medium">{name}</h3>
+      <p className="text-gray-600">{email}</p>
+      {onEdit && isHovered && (
+        <Button variant="ghost" size="sm" onClick={onEdit}>
+          Edit
+        </Button>
+      )}
+    </div>
+  );
+}
+```
+
+**Notice:**
+- 'use client' directive at the very top (if needed)
+- Standard React imports only (useState, useCallback)
+- Project imports use exact paths from "Available Components"
+- Props interface defined inline with Props suffix
+- JSDoc comment briefly describes the component
+- Function exported with `export function`
+- All variant/size props use string literals: `variant="ghost"` NOT `variant={variants.ghost}`
+
+## Output
+
+Output the complete file content starting with imports.
+No markdown code blocks. No explanations. Just the code.
+
+Start with imports (or 'use client'/'use server' directive if needed for Next.js).
+The code must define and export `{{name}}`.

package/templates/hybrid/create-file.md

@@ -0,0 +1,56 @@
+{{include _base.md}}
+
+# Task: Create File
+
+{{include _patterns.md}}
+
+## File Specification
+
+**CRITICAL - You are creating this file:**
+
+| Field | Value |
+|-------|-------|
+| **File Path** | `{{path}}` |
+| **File Type** | `{{fileType}}` |
+
+**Description:**
+{{description}}
+
+**Content Guidance:**
+{{content_guidance}}
+
+## What You MUST Create
+
+Create a complete, functional file at the specified path.
+
+{{#if isTypeScript}}
+- Include proper TypeScript types
+- Add necessary imports at the top
+- Export appropriately (named or default as needed)
+{{/if}}
+
+{{#if isConfig}}
+- Follow the format expected by the tool/framework
+- Include all required fields
+- Add comments explaining non-obvious settings
+{{/if}}
+
+## What NOT to Create
+
+❌ Do NOT create a different file than `{{path}}`
+❌ Do NOT output partial content
+❌ Do NOT wrap in markdown code blocks
+
+## Requirements
+
+1. Create the complete file content
+2. Follow project conventions and patterns from _patterns.md
+3. Include proper imports if TypeScript/JavaScript
+4. Add appropriate comments/JSDoc if needed
+5. Ensure the file is complete and functional
+
+## Output
+
+Output the complete file content.
+No markdown code blocks. No explanations. Just the raw file content.
+Start directly with the first line of the file.

package/templates/hybrid/create-hook.md

@@ -0,0 +1,145 @@
+{{include _base.md}}
+
+# Task: Create React Hook
+
+{{include _patterns.md}}
+
+## Hook Specification
+
+**CRITICAL - You are creating this hook:**
+
+| Field | Value |
+|-------|-------|
+| **Hook Name** | `{{name}}` |
+| **File Path** | `{{path}}` |
+| **Return Type** | `{{name}}Result` or similar |
+
+**Description:**
+{{description}}
+
+**Return Values:**
+{{returns}}
+
+**Dependencies/Uses:**
+{{uses}}
+
+## What You MUST Create
+
+```
+// File: {{path}}
+// Hook: {{name}}
+
+import { useState, useCallback, ... } from 'react';
+
+interface {{name}}Result {
+  // return properties
+}
+
+/**
+ * [Brief description of {{name}}]
+ */
+export function {{name}}(/* params */): {{name}}Result {
+  // implementation
+  return {
+    // returned values
+  };
+}
+```
+
+## What NOT to Create
+
+❌ Do NOT create any hook except `{{name}}`
+❌ Do NOT create types/interfaces from the project context section
+❌ Do NOT create a component - this is a HOOK file
+❌ Do NOT output anything except the code for `{{name}}`
+
+## Requirements Checklist
+
+1. [ ] Hook is named exactly `{{name}}` (must start with "use")
+2. [ ] Return type interface is defined
+3. [ ] Exported as: `export function {{name}}`
+4. [ ] Returns an object with named properties (not array)
+5. [ ] Handles loading/error states if applicable
+6. [ ] Follows the hook pattern from _patterns.md
+7. [ ] Has JSDoc comment
+
+## Golden Example (Follow This Pattern)
+
+This example shows the CORRECT output format for a data-fetching hook:
+
+```tsx
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+interface UseUserResult {
+  user: User | null;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/**
+ * Fetches and manages user data for the given user ID.
+ */
+export function useUser(userId: string): UseUserResult {
+  const [user, setUser] = useState<User | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchUser = useCallback(async () => {
+    if (!userId) return;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const response = await fetch(`/api/users/${userId}`);
+      if (!response.ok) {
+        throw new Error('Failed to fetch user');
+      }
+      const data = await response.json();
+      setUser(data);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Unknown error'));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userId]);
+
+  useEffect(() => {
+    fetchUser();
+  }, [fetchUser]);
+
+  return {
+    user,
+    isLoading,
+    error,
+    refetch: fetchUser,
+  };
+}
+```
+
+**Notice:**
+- 'use client' directive at the very top (if needed for client-side React)
+- Hook name starts with "use"
+- Return type interface clearly defines all returned values
+- JSDoc comment briefly describes the hook's purpose
+- Returns object with named properties (NOT array like `[user, setUser]`)
+- Handles loading and error states
+- Memoizes callbacks with useCallback
+- Exports with `export function`
+
+## Output
+
+Output the complete file content starting with imports.
+No markdown code blocks. No explanations. Just the code.
+
+Start with imports (or 'use client' directive if needed for Next.js client hooks).
+The code must define and export `{{name}}`.

package/templates/hybrid/create-service.md

@@ -0,0 +1,70 @@
+{{include _base.md}}
+
+# Task: Create Service
+
+{{include _patterns.md}}
+
+## Service Specification
+
+**CRITICAL - You are creating this service:**
+
+| Field | Value |
+|-------|-------|
+| **Service Name** | `{{name}}` |
+| **File Path** | `{{path}}` |
+
+**Description:**
+{{description}}
+
+**Methods:**
+{{methods}}
+
+**Types to Define:**
+{{types}}
+
+## What You MUST Create
+
+```
+// File: {{path}}
+// Service: {{name}}
+
+// Type definitions
+interface SomeInput { ... }
+interface SomeOutput { ... }
+
+/**
+ * [Brief description of {{name}}]
+ */
+export const {{name}} = {
+  /**
+   * [Method description]
+   */
+  async someMethod(input: SomeInput): Promise<SomeOutput> {
+    // implementation
+  },
+  // ... other methods
+};
+```
+
+## What NOT to Create
+
+❌ Do NOT create any service except `{{name}}`
+❌ Do NOT create types/interfaces from the project context section
+❌ Do NOT create a React component or hook - this is a SERVICE file
+❌ Do NOT output anything except the code for `{{name}}`
+
+## Requirements Checklist
+
+1. [ ] Service is named exactly `{{name}}`
+2. [ ] All TypeScript types are defined for parameters and returns
+3. [ ] Exported as: `export const {{name}}` or `export class {{name}}`
+4. [ ] Errors are handled appropriately
+5. [ ] Follows the service pattern from _patterns.md
+6. [ ] Has JSDoc comments for each method
+
+## Output
+
+Output the complete file content starting with imports (if any).
+No markdown code blocks. No explanations. Just the code.
+
+The code must define and export `{{name}}`.

package/templates/hybrid/fix-bug.md

@@ -0,0 +1,33 @@
+{{include _base.md}}
+
+# Task: Fix Bug
+
+## Bug Details
+
+**File:** {{path}}
+**Bug Description:** {{bugDescription}}
+**Expected Behavior:** {{expectedBehavior}}
+**Actual Behavior:** {{actualBehavior}}
+
+## Current File Content
+
+```
+{{currentContent}}
+```
+
+## Error Message (if any)
+
+{{errorMessage}}
+
+## Requirements
+
+1. Identify the root cause
+2. Fix ONLY what's necessary
+3. Don't refactor unrelated code
+4. Ensure the fix doesn't break other functionality
+5. Add a comment explaining the fix if it's not obvious
+
+## Output
+
+Output the COMPLETE fixed file.
+No markdown code blocks.

package/templates/hybrid/modify-file.md

@@ -0,0 +1,55 @@
+{{include _base.md}}
+
+{{include _patterns.md}}
+
+# Task: Modify Existing File
+
+## File to Modify
+
+**CRITICAL - You are modifying this file:**
+
+| Field | Value |
+|-------|-------|
+| **File Path** | `{{path}}` |
+| **Task** | Apply the changes described below |
+
+## Current File Content
+
+```
+{{currentContent}}
+```
+
+## Required Changes
+
+{{modifications}}
+
+## What You MUST Do
+
+1. Start with ALL existing imports from the current file
+2. Apply ONLY the specified changes
+3. Preserve ALL existing code not mentioned in changes
+4. Output the COMPLETE file (not a diff or snippet)
+
+## What NOT to Do
+
+❌ Do NOT remove existing code unless explicitly told to
+❌ Do NOT change import paths
+❌ Do NOT reorganize or reformat existing code
+❌ Do NOT add features not mentioned in Required Changes
+❌ Do NOT output partial code or diffs
+❌ Do NOT create new files - modify the existing one
+
+## CRITICAL Requirements
+
+1. [ ] Output is a COMPLETE valid TypeScript file
+2. [ ] ALL existing imports are preserved
+3. [ ] Only specified changes are applied
+4. [ ] File maintains its existing structure and style
+5. [ ] Output size is similar to original (not drastically smaller)
+
+## Output
+
+Output the COMPLETE modified file with all changes applied.
+The output must be the ENTIRE file content, not a partial snippet.
+Start directly with the first import statement.
+No markdown code blocks. No explanations.

package/templates/story.md

@@ -0,0 +1,68 @@
+# [wf-XXXXXXXX] [Title]
+
+## User Story
+**As a** [user type]
+**I want** [action/capability]
+**So that** [benefit/value]
+
+## Description
+[2-4 sentences explaining the context, what needs to be built, and why it matters.]
+
+## Acceptance Criteria
+
+### Scenario 1: [Happy path]
+**Given** [initial context/state]
+**When** [action taken]
+**Then** [expected outcome]
+**And** [additional outcome if needed]
+
+### Scenario 2: [Alternative path]
+**Given** [context]
+**When** [action]
+**Then** [outcome]
+
+### Scenario 3: [Error handling]
+**Given** [context]
+**When** [invalid action or error condition]
+**Then** [error handling behavior]
+
+## Technical Notes
+- **Components**: 
+  - Use existing: [from app-map]
+  - Create new: [add to app-map after]
+- **API**: [endpoints if any]
+- **State**: [state management notes]
+- **Constraints**: [technical limitations]
+
+## Test Strategy
+- [ ] Unit: [what to test]
+- [ ] Integration: [what to test]
+- [ ] E2E: [user flow to verify]
+
+## Test Steps (Verification Checklist)
+<!-- Quick verification steps to confirm the feature works -->
+1. [ ] [Step 1: Verify specific behavior]
+2. [ ] [Step 2: Verify another behavior]
+3. [ ] [Step 3: Verify edge case]
+
+## Dependencies
+- [wf-XXXXXXXX] - [why needed first]
+- None
+
+## Complexity
+[Low / Medium / High] - [justification]
+
+## Out of Scope
+- [What this does NOT include]
+
+---
+
+## Implementation Notes
+<!-- Developer fills this in during implementation -->
+
+## Completion Checklist
+- [ ] All acceptance criteria scenarios pass
+- [ ] Tests written per test strategy
+- [ ] Components added to app-map (if new)
+- [ ] Request-log updated
+- [ ] Code reviewed

package/templates/task.json

@@ -0,0 +1,56 @@
+{
+  "feature": "[feature-name]",
+  "created": "[ISO date]",
+  "tasks": [
+    {
+      "id": "TASK-001",
+      "title": "[Descriptive title]",
+      "type": "feature",
+      "status": "pending",
+      "priority": "high",
+      "complexity": "medium",
+      "phase": null,
+      "dependencies": [],
+      "userStory": {
+        "asA": "[user type]",
+        "iWant": "[action/capability]",
+        "soThat": "[benefit/value]"
+      },
+      "description": "[2-4 sentences of context explaining what and why]",
+      "acceptanceCriteria": [
+        {
+          "scenario": "Happy path",
+          "given": "[initial state]",
+          "when": "[action]",
+          "then": "[outcome]"
+        },
+        {
+          "scenario": "Error case",
+          "given": "[state]",
+          "when": "[invalid action]",
+          "then": "[error handling]"
+        }
+      ],
+      "testSteps": [
+        "Step 1: Verify [specific behavior]",
+        "Step 2: Verify [another behavior]"
+      ],
+      "technicalNotes": {
+        "componentsExisting": ["Button", "Input"],
+        "componentsNew": [],
+        "api": "",
+        "state": "",
+        "constraints": ""
+      },
+      "testStrategy": {
+        "unit": "[what to test]",
+        "integration": "[what to test]",
+        "e2e": "[flow to verify]"
+      },
+      "outOfScope": [],
+      "implemented": false,
+      "tested": false,
+      "commitHash": null
+    }
+  ]
+}