@jahanxu/trellis 0.5.0 → 0.5.5

package/dist/templates/iflow/commands/trellis/handoff.md

@@ -1,148 +0,0 @@
-# Handoff - Complete Task and Add to Pool
-
-Complete the current task, generate a HANDOFF.md document, and add the deliverable to the appropriate pool.
-
----
-
-## Prerequisites
-
-- Must have a current task set (`.trellis/.current-task`)
-- Task must have deliverable files in the output directory
-
----
-
-## Process `[AI]`
-
-### Step 1: Read Current Task
-
-```bash
-python3 ./.trellis/scripts/get_context.py
-```
-
-Read the task's `task.json` to get:
-- `output_dir`: where deliverables are stored
-- `role`: which role completed this task
-- `title`: task title
-- `slug`: task slug / deliverable ID
-
-If no current task is set, inform the user and stop.
-
-### Step 2: Check Deliverables
-
-Verify that the output directory exists and contains files:
-
-```bash
-ls -la <output_dir>/
-```
-
-If empty or missing, warn the user:
-> "The output directory `<output_dir>` appears empty. Would you like to continue anyway?"
-
-### Step 3: Generate HANDOFF.md
-
-Analyze all files in the output directory and generate a `HANDOFF.md` document.
-
-**For PM role (requirements pool):**
-
-```markdown
-# {Title} - Requirements Handoff
-
-## Task Info
-- **Feature ID**: {slug}
-- **Title**: {title}
-- **Completed by**: {developer}
-- **Completed at**: {timestamp}
-
-## Core Requirements
-(AI-generated summary of PRD key points, 2-3 paragraphs)
-
-## Deliverable Files
-- `prd.md` - Product requirements document
-- (list all files)
-
-## Key Design Points
-1. (extracted from PRD)
-2. ...
-
-## Special Notes for Downstream
-- (important details the Designer should know)
-- (constraints, edge cases, specific UI requirements)
-
-## Related Resources
-- (links if any)
-```
-
-**For Designer role (prototypes pool):**
-
-```markdown
-# {Title} - Prototype Handoff
-
-## Task Info
-- **Feature ID**: {slug}
-- **Based on**: {source requirement}
-- **Completed by**: {developer}
-- **Completed at**: {timestamp}
-
-## Design Notes
-(AI-generated summary of design approach, 2-3 paragraphs)
-
-## Deliverable Files
-- (list all component files)
-
-## Component Structure
-(component tree overview)
-
-## Mock Data Notes
-Current mock data used:
-```typescript
-// Document all mock data and their locations
-// Include file name and line numbers
-```
-
-## Logic for Frontend to Implement
-1. Replace mock login handler with real API call (file:line)
-2. Add error handling for network failures
-3. Implement loading state management
-4. ...
-
-## Special Notes for Downstream
-- (interactions to preserve)
-- (SDK dependencies)
-- (form validation already implemented)
-```
-
-Write the generated HANDOFF.md to `<output_dir>/HANDOFF.md`.
-
-### Step 4: Ask for Handoff Message (Optional)
-
-Ask the user:
-> "Any additional notes for the downstream role? (Press Enter to skip)"
-
-If provided, append to the Special Notes section.
-
-### Step 5: Add to Pool
-
-Determine the target pool based on role:
-- `pm` -> `requirements`
-- `designer` -> `prototypes`
-- `frontend-impl` or `frontend` -> `implementations`
-
-```bash
-python3 ./.trellis/scripts/pool.py add <pool> <slug> "<title>" <output_dir>
-```
-
-### Step 6: Report
-
-Output a summary:
-```
-Handoff complete!
-- Deliverable: <slug>
-- Pool: <pool>
-- HANDOFF.md: <output_dir>/HANDOFF.md
-- Status: available
-
-Next: The downstream role can pick this up with:
-  /trellis:pick-task <pool> <slug>
-```
-
-Remind the user to commit and push so the downstream role can access the deliverables.

package/dist/templates/iflow/commands/trellis/pick-task.md

@@ -1,145 +0,0 @@
-# Pick Task - Select Upstream Deliverable and Start Working
-
-Pick a deliverable from an upstream pool, create a task directory, and inject upstream context.
-
----
-
-## Usage
-
-```
-/trellis:pick-task <pool> <id>
-```
-
-- `<pool>`: `requirements` (for Designers) or `prototypes` (for Frontend)
-- `<id>`: deliverable ID to pick (e.g., `user-login`)
-
----
-
-## Process `[AI]`
-
-### Step 1: Validate Role
-
-```bash
-python3 ./.trellis/scripts/get_context.py
-```
-
-Read the developer name from `.developer` file. Parse role from `{role}-{name}` convention.
-
-Validate role-pool match:
-- `designer` can pick from `requirements`
-- `frontend` / `frontend-impl` can pick from `prototypes`
-- `pm` should NOT pick from pools (PMs create tasks directly)
-
-If role cannot be parsed, warn but continue (soft detection).
-
-### Step 2: Check Pool Availability
-
-```bash
-python3 ./.trellis/scripts/pool.py status <pool> <id>
-```
-
-Verify the item:
-- Exists in the pool
-- Status is `available` (not `consumed`)
-
-If not available, list what IS available:
-```bash
-python3 ./.trellis/scripts/pool.py list <pool>
-```
-
-### Step 3: Check Current Task
-
-If there is already a current task set, ask:
-> "You have an active task: `<current-task>`. Would you like to finish it first, or switch to the new task?"
-
-If user wants to continue, proceed.
-
-### Step 4: Create Task Directory
-
-Determine task suffix based on pool:
-- `requirements` pool -> `{id}-prototype`
-- `prototypes` pool -> `{id}-impl`
-
-```bash
-TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <id>-<suffix>)
-```
-
-### Step 5: Write source.json
-
-Create `source.json` in the task directory to reference upstream:
-
-```json
-{
-  "based_on": {
-    "type": "<requirement|prototype>",
-    "id": "<id>",
-    "path": "<deliverable path>",
-    "handoff_doc": "<path>/HANDOFF.md"
-  }
-}
-```
-
-Write this file:
-```bash
-cat > "$TASK_DIR/source.json" << 'EOF'
-{content}
-EOF
-```
-
-### Step 6: Configure Context (JSONL)
-
-Initialize context files for the task:
-
-```bash
-python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" frontend
-```
-
-Add upstream deliverable files and role specs to context:
-
-```bash
-# Add role spec
-python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement ".trellis/spec/roles/<role>/index.md" "Role guidelines"
-
-# Add upstream HANDOFF doc
-python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<handoff_doc>" "Upstream handoff document"
-
-# Add upstream deliverable directory files
-# (add each significant file from the upstream output)
-python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<upstream_file>" "Upstream deliverable"
-```
-
-### Step 7: Consume from Pool
-
-```bash
-python3 ./.trellis/scripts/pool.py consume <pool> <id> <developer>
-```
-
-### Step 8: Activate Task
-
-```bash
-python3 ./.trellis/scripts/task.py start "$TASK_DIR"
-```
-
-### Step 9: Read Upstream Context
-
-Read and summarize the upstream deliverables for the user:
-
-1. Read the HANDOFF.md document
-2. List all upstream files
-3. Summarize key points the user should know
-
-### Step 10: Report
-
-```
-Task picked and ready!
-- Task: <task-dir>
-- Based on: <pool>/<id>
-- Upstream: <deliverable-path>
-- Role specs loaded: .trellis/spec/roles/<role>/
-
-Key points from upstream HANDOFF:
-- (summary point 1)
-- (summary point 2)
-
-What would you like to work on first?
-```

package/dist/templates/markdown/spec/roles/designer/index.md.txt

@@ -1,57 +0,0 @@
-# Designer Role Guidelines
-
-> Standards for interactive prototyping and mock data design.
-
----
-
-## Overview
-
-This directory contains guidelines for the Designer role in the three-role collaboration pipeline. Fill in each file with your project's specific conventions.
-
----
-
-## Guidelines Index
-
-| Guide | Description | Status |
-|-------|-------------|--------|
-| [Prototype Guidelines](./prototype-guidelines.md) | Component structure and interaction patterns | To fill |
-| [Mock Data Standards](./mock-data-standards.md) | How to create and document mock data | To fill |
-
----
-
-## Workflow
-
-1. Pick a requirement from the pool: `/trellis:pick-task requirements <id>`
-2. Read the upstream HANDOFF.md and PRD carefully
-3. Create runnable prototype code in `deliverables/prototypes/<feature-id>/`
-4. Run `/trellis:handoff` to generate HANDOFF.md and add to pool
-5. Downstream Frontend developer picks from the `prototypes` pool
-
----
-
-## Output Directory
-
-All Designer deliverables go to: `deliverables/prototypes/<feature-id>/`
-
-Required files:
-- Component files (`.tsx`, `.vue`, etc.) - runnable prototype code
-- Mock data inline or in separate files
-
-The prototype should:
-- Be runnable (renders correctly with mock data)
-- Follow the project's component conventions (see `spec/frontend/`)
-- Use clear `// TODO:` comments where real logic needs to be added
-- Document all mock data locations
-
----
-
-## Key Principle
-
-> **The prototype IS the spec for Frontend.**
->
-> Frontend developers should be able to run your prototype and understand
-> exactly what the final product should look like and behave like.
-
----
-
-**Language**: All documentation should be written in **English**.

package/dist/templates/markdown/spec/roles/designer/mock-data-standards.md.txt

@@ -1,63 +0,0 @@
-# Mock Data Standards
-
-> How to create, document, and organize mock data in prototypes.
-
----
-
-## Principles
-
-1. **Realistic**: Mock data should look like real data (realistic names, dates, amounts)
-2. **Documented**: Every mock data location must be clearly marked
-3. **Replaceable**: Mock data should be easy to find and replace with real API calls
-4. **Complete**: Cover all data states (populated, empty, error, boundary values)
-
----
-
-## Mock Data Location
-
-Place mock data at the top of the component file or in a separate `__mocks__/` directory:
-
-```typescript
-// === MOCK DATA (start) ===
-const mockUser = {
-  id: "1",
-  name: "Alice Johnson",
-  email: "alice@example.com",
-  avatar: "https://i.pravatar.cc/150?u=alice",
-};
-
-const mockProducts = [
-  { id: "p1", name: "Widget A", price: 29.99, stock: 150 },
-  { id: "p2", name: "Widget B", price: 49.99, stock: 0 },
-];
-// === MOCK DATA (end) ===
-```
-
----
-
-## Mock Handler Pattern
-
-```typescript
-// TODO: Replace with real API call - see api-integration.md
-const handleSubmit = async (formData: FormData) => {
-  // Mock: simulate network delay
-  await new Promise(resolve => setTimeout(resolve, 800));
-  // Mock: simulate success response
-  return { success: true, data: mockResponse };
-};
-```
-
----
-
-## Edge Case Data
-
-Always include mock data for edge cases:
-- Empty list / no results
-- Single item
-- Maximum items (test scrolling/pagination)
-- Long text (test text overflow)
-- Missing optional fields
-
----
-
-**Language**: All documentation should be written in **English**.

package/dist/templates/markdown/spec/roles/designer/prototype-guidelines.md.txt

@@ -1,49 +0,0 @@
-# Prototype Guidelines
-
-> Standards for creating interactive prototypes.
-
----
-
-## Component Structure
-
-1. **One feature per directory**: Each feature prototype lives in its own directory
-2. **Entry point**: Always have a clear entry component (e.g., `FeaturePage.tsx`)
-3. **Component hierarchy**: Break down into logical sub-components
-4. **Shared components**: Use project's existing shared components when possible
-
----
-
-## Interaction Patterns
-
-1. **All states**: Implement all UI states (loading, empty, error, success)
-2. **Animations**: Include transition animations if specified in PRD
-3. **Responsive**: Build mobile-first if the PRD requires responsive design
-4. **Accessibility**: Use semantic HTML, ARIA labels, keyboard navigation
-
----
-
-## Code Conventions
-
-1. Follow the project's existing component patterns (see `spec/frontend/component-guidelines.md`)
-2. Use the project's styling approach (Tailwind, CSS modules, etc.)
-3. Keep components focused and single-purpose
-4. Add clear comments for complex interactions
-
----
-
-## TODO Markers
-
-Mark all places where real implementation is needed:
-
-```typescript
-// TODO: Replace with real API call
-const data = mockData;
-
-// TODO: Add error handling
-// TODO: Implement loading state with skeleton
-// TODO: Connect to auth context
-```
-
----
-
-**Language**: All documentation should be written in **English**.

package/dist/templates/markdown/spec/roles/frontend-impl/api-integration.md.txt

@@ -1,63 +0,0 @@
-# API Integration Guide
-
-> How to replace mock data and handlers with real API calls.
-
----
-
-## Process
-
-### 1. Identify All Mock Points
-
-Search the prototype for:
-- `// TODO:` comments
-- `// Mock:` comments
-- `mock` variables and functions
-- `setTimeout` simulating API latency
-- Hardcoded data arrays/objects
-
-### 2. Map Mock to API
-
-For each mock point, determine:
-- Which API endpoint to call
-- Request format (method, headers, body)
-- Response format and how it maps to the component's expected data shape
-- Error responses and how to handle them
-
-### 3. Replace Pattern
-
-```typescript
-// BEFORE (mock):
-const handleLogin = async (email: string, password: string) => {
-  await new Promise(r => setTimeout(r, 800));
-  return { success: true, user: mockUser };
-};
-
-// AFTER (real):
-const handleLogin = async (email: string, password: string) => {
-  const response = await api.post('/auth/login', { email, password });
-  return response.data;
-};
-```
-
----
-
-## Error Handling
-
-Every API call must handle:
-1. **Network errors**: Connection timeout, server unreachable
-2. **HTTP errors**: 4xx (client error), 5xx (server error)
-3. **Business errors**: Invalid credentials, insufficient permissions
-4. **Loading states**: Show loading indicator during request
-
----
-
-## Testing
-
-- Test with real API responses
-- Test with simulated error responses
-- Test loading state transitions
-- Test retry behavior (if implemented)
-
----
-
-**Language**: All documentation should be written in **English**.

package/dist/templates/markdown/spec/roles/frontend-impl/index.md.txt

@@ -1,57 +0,0 @@
-# Frontend Implementation Role Guidelines
-
-> Standards for converting prototypes to production code.
-
----
-
-## Overview
-
-This directory contains guidelines for the Frontend Implementation role in the three-role collaboration pipeline. Fill in each file with your project's specific conventions.
-
----
-
-## Guidelines Index
-
-| Guide | Description | Status |
-|-------|-------------|--------|
-| [API Integration](./api-integration.md) | How to replace mock data with real APIs | To fill |
-| [Prototype to Production](./prototype-to-production.md) | Checklist for converting prototypes | To fill |
-
----
-
-## Workflow
-
-1. Pick a prototype from the pool: `/trellis:pick-task prototypes <id>`
-2. Read the upstream HANDOFF.md carefully - it lists all TODOs
-3. Replace mock data with real API calls
-4. Add error handling, loading states, and edge case handling
-5. Write tests for critical paths
-6. Run `/trellis:handoff` to complete
-
----
-
-## Output Directory
-
-Production code goes directly into the project source tree (e.g., `src/features/<feature>/`).
-
-A copy or reference is also placed in: `deliverables/production/<feature-id>/`
-
----
-
-## Key Principle
-
-> **Preserve the prototype's UX, replace the data layer.**
->
-> The Designer's prototype defines the look and interaction.
-> Your job is to make it work with real data and handle all edge cases.
-
----
-
-## Also Read
-
-- `spec/frontend/` - Project frontend conventions (components, hooks, state management)
-- `spec/backend/` - API conventions (if applicable)
-
----
-
-**Language**: All documentation should be written in **English**.

package/dist/templates/markdown/spec/roles/frontend-impl/prototype-to-production.md.txt

@@ -1,57 +0,0 @@
-# Prototype to Production Checklist
-
-> Step-by-step checklist for converting a Designer's prototype to production code.
-
----
-
-## Pre-Implementation
-
-- [ ] Read HANDOFF.md thoroughly - note all "Logic for Frontend to Implement" items
-- [ ] Identify all mock data locations (search for `// TODO:`, `// Mock:`, `mock` prefix)
-- [ ] Review prototype component structure - decide what to keep vs refactor
-- [ ] Check if prototype components follow project conventions (if not, note adjustments)
-
-## Data Layer
-
-- [ ] Replace all mock data with API calls or store connections
-- [ ] Add proper TypeScript types for API responses
-- [ ] Implement data fetching hooks (or use existing patterns)
-- [ ] Add caching strategy if needed (React Query, SWR, etc.)
-
-## Error Handling
-
-- [ ] Add error boundaries for component-level errors
-- [ ] Handle API errors with user-friendly messages
-- [ ] Implement retry logic for transient failures
-- [ ] Add fallback UI for error states
-
-## State Management
-
-- [ ] Connect to global state (auth, theme, etc.) as needed
-- [ ] Implement form state management
-- [ ] Handle optimistic updates if applicable
-- [ ] Clean up state on unmount
-
-## UX Polish
-
-- [ ] Loading skeletons for async content
-- [ ] Smooth transitions between states
-- [ ] Keyboard navigation works correctly
-- [ ] Focus management for modals/dialogs
-
-## Testing
-
-- [ ] Unit tests for business logic
-- [ ] Integration tests for API interactions
-- [ ] Accessibility testing (screen reader, keyboard-only)
-
-## Final Check
-
-- [ ] All TODO comments from prototype are resolved
-- [ ] No mock data remains in production code
-- [ ] Lint and type check pass
-- [ ] Visual diff with prototype (should look identical)
-
----
-
-**Language**: All documentation should be written in **English**.

package/dist/templates/markdown/spec/roles/pm/index.md.txt

@@ -1,45 +0,0 @@
-# PM (Product Manager) Role Guidelines
-
-> Standards for product requirements and feature specification.
-
----
-
-## Overview
-
-This directory contains guidelines for the PM role in the three-role collaboration pipeline. Fill in each file with your project's specific conventions.
-
----
-
-## Guidelines Index
-
-| Guide | Description | Status |
-|-------|-------------|--------|
-| [PRD Template](./prd-template.md) | Standard PRD structure and content requirements | To fill |
-| [Requirement Checklist](./requirement-checklist.md) | Quality checklist before handoff | To fill |
-
----
-
-## Workflow
-
-1. Create a task with `/trellis:start`
-2. Write PRD and supporting documents in `deliverables/requirements/<feature-id>/`
-3. Run `/trellis:handoff` to generate HANDOFF.md and add to pool
-4. Downstream Designer picks from the `requirements` pool
-
----
-
-## Output Directory
-
-All PM deliverables go to: `deliverables/requirements/<feature-id>/`
-
-Required files:
-- `prd.md` - Product requirements document
-
-Optional files:
-- `user-stories.md` - Detailed user stories
-- `wireframes/` - Low-fidelity wireframes
-- `acceptance-criteria.md` - Detailed acceptance criteria
-
----
-
-**Language**: All documentation should be written in **English**.