catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: restore critical details to intelligent-tools-strategy.md

Browse Source 
Restore important detailed content that was removed in commit 1e79866:

Key restorations (106 lines added):
- Session Management: Detailed explanation and multi-task pattern examples (15 lines)
- Auto-Resume Decision Rules: Complete criteria for when to use/not use (12 lines)
- RULES Field Format: Critical "template reference only, never read" rule (14 lines)
- File Pattern Reference: Complete 3-step workflow with rg/MCP examples (33 lines)
- Common Scenarios: Full examples including Feature Development 3-step workflow (82 lines)
- Best Practices: Detailed guidelines with context optimization strategy (8 lines)

Additional improvements:
- Enhanced CLAUDE.md references throughout the document
- Added CLAUDE.md to Planning Checklist and File Pattern examples
- Restored execution timeout configuration with specific millisecond values

File changes:
- intelligent-tools-strategy.md: 325 → 431 lines (balanced detail/conciseness)
- Removed design-tokens-schema.md (obsolete)

The document now maintains conciseness while restoring all critical guidance.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-13 17:17:07 +08:00
parent 1e798660ab
commit a7a157d40e
2 changed files with 149 additions and 577 deletions
Download Patch File Download Diff File Expand all files Collapse all files

534
.claude/workflows/design-tokens-schema.md
View File

@@ -1,534 +0,0 @@
---
name: design-tokens-schema
description: Design tokens JSON schema specification for UI design workflow
type: specification
---
# Design Tokens Schema Specification
## Overview
Standardized JSON schema for design tokens used in `/workflow:design/*` commands. Ensures consistency across style extraction, consolidation, and UI generation phases.
## Core Principles
1. **OKLCH Color Format**: All colors use OKLCH color space for perceptual uniformity
2. **Semantic Naming**: User-centric token names (brand-primary, surface-elevated, not color-1, bg-2)
3. **rem-Based Sizing**: All spacing and typography use rem units for scalability
4. **Comprehensive Coverage**: Complete token set for production-ready design systems
5. **Accessibility First**: WCAG AA compliance validated and documented
## Full Schema
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Design Tokens",
"description": "Design token definitions for UI design workflow",
"type": "object",
"required": ["colors", "typography", "spacing", "border_radius", "shadow"],
"properties": {
"meta": {
"type": "object",
"properties": {
"version": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$"},
"generated_at": {"type": "string", "format": "date-time"},
"session_id": {"type": "string", "pattern": "^WFS-"},
"description": {"type": "string"}
}
},
"colors": {
"type": "object",
"required": ["brand", "surface", "semantic", "text"],
"properties": {
"brand": {
"type": "object",
"description": "Brand identity colors",
"required": ["primary", "secondary"],
"properties": {
"primary": {"$ref": "#/definitions/color"},
"secondary": {"$ref": "#/definitions/color"},
"accent": {"$ref": "#/definitions/color"}
}
},
"surface": {
"type": "object",
"description": "Surface and background colors",
"required": ["background", "elevated"],
"properties": {
"background": {"$ref": "#/definitions/color"},
"elevated": {"$ref": "#/definitions/color"},
"sunken": {"$ref": "#/definitions/color"},
"overlay": {"$ref": "#/definitions/color"}
}
},
"semantic": {
"type": "object",
"description": "Semantic state colors",
"required": ["success", "warning", "error", "info"],
"properties": {
"success": {"$ref": "#/definitions/color"},
"warning": {"$ref": "#/definitions/color"},
"error": {"$ref": "#/definitions/color"},
"info": {"$ref": "#/definitions/color"}
}
},
"text": {
"type": "object",
"description": "Text colors with WCAG AA validated contrast",
"required": ["primary", "secondary"],
"properties": {
"primary": {"$ref": "#/definitions/color"},
"secondary": {"$ref": "#/definitions/color"},
"tertiary": {"$ref": "#/definitions/color"},
"inverse": {"$ref": "#/definitions/color"},
"disabled": {"$ref": "#/definitions/color"}
}
},
"border": {
"type": "object",
"description": "Border and divider colors",
"properties": {
"subtle": {"$ref": "#/definitions/color"},
"default": {"$ref": "#/definitions/color"},
"strong": {"$ref": "#/definitions/color"}
}
}
}
},
"typography": {
"type": "object",
"required": ["font_family", "font_size", "line_height", "font_weight"],
"properties": {
"font_family": {
"type": "object",
"required": ["heading", "body"],
"properties": {
"heading": {"type": "string"},
"body": {"type": "string"},
"mono": {"type": "string"}
}
},
"font_size": {
"type": "object",
"required": ["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"],
"properties": {
"xs": {"$ref": "#/definitions/size_rem"},
"sm": {"$ref": "#/definitions/size_rem"},
"base": {"$ref": "#/definitions/size_rem"},
"lg": {"$ref": "#/definitions/size_rem"},
"xl": {"$ref": "#/definitions/size_rem"},
"2xl": {"$ref": "#/definitions/size_rem"},
"3xl": {"$ref": "#/definitions/size_rem"},
"4xl": {"$ref": "#/definitions/size_rem"},
"5xl": {"$ref": "#/definitions/size_rem"}
}
},
"line_height": {
"type": "object",
"required": ["tight", "normal", "relaxed"],
"properties": {
"tight": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"},
"normal": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"},
"relaxed": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"}
}
},
"font_weight": {
"type": "object",
"properties": {
"light": {"type": "integer", "enum": [300]},
"normal": {"type": "integer", "enum": [400]},
"medium": {"type": "integer", "enum": [500]},
"semibold": {"type": "integer", "enum": [600]},
"bold": {"type": "integer", "enum": [700]}
}
}
}
},
"spacing": {
"type": "object",
"description": "Spacing scale (rem-based)",
"required": ["0", "1", "2", "3", "4", "6", "8"],
"patternProperties": {
"^\\d+$": {"$ref": "#/definitions/size_rem"}
}
},
"border_radius": {
"type": "object",
"required": ["none", "sm", "md", "lg", "full"],
"properties": {
"none": {"type": "string", "const": "0"},
"sm": {"$ref": "#/definitions/size_rem"},
"md": {"$ref": "#/definitions/size_rem"},
"lg": {"$ref": "#/definitions/size_rem"},
"xl": {"$ref": "#/definitions/size_rem"},
"2xl": {"$ref": "#/definitions/size_rem"},
"full": {"type": "string", "const": "9999px"}
}
},
"shadow": {
"type": "object",
"required": ["sm", "md", "lg"],
"properties": {
"none": {"type": "string", "const": "none"},
"sm": {"type": "string"},
"md": {"type": "string"},
"lg": {"type": "string"},
"xl": {"type": "string"},
"2xl": {"type": "string"}
}
},
"breakpoint": {
"type": "object",
"description": "Responsive breakpoints",
"properties": {
"sm": {"type": "string", "pattern": "^\\d+px$"},
"md": {"type": "string", "pattern": "^\\d+px$"},
"lg": {"type": "string", "pattern": "^\\d+px$"},
"xl": {"type": "string", "pattern": "^\\d+px$"},
"2xl": {"type": "string", "pattern": "^\\d+px$"}
}
},
"accessibility": {
"type": "object",
"description": "WCAG AA compliance data",
"properties": {
"contrast_ratios": {
"type": "object",
"patternProperties": {
".*": {
"type": "object",
"properties": {
"background": {"type": "string"},
"foreground": {"type": "string"},
"ratio": {"type": "number"},
"wcag_aa_pass": {"type": "boolean"},
"wcag_aaa_pass": {"type": "boolean"}
}
}
}
}
}
}
},
"definitions": {
"color": {
"type": "string",
"pattern": "^oklch\\(\\s*\\d+(\\.\\d+)?\\s+\\d+(\\.\\d+)?\\s+\\d+(\\.\\d+)?\\s*(\\/\\s*\\d+(\\.\\d+)?)?\\s*\\)$",
"description": "OKLCH color format: oklch(L C H / A)"
},
"size_rem": {
"type": "string",
"pattern": "^\\d+(\\.\\d+)?rem$",
"description": "rem-based size value"
}
}
}
```
## Example: Complete Design Tokens
```json
{
"meta": {
"version": "1.0.0",
"generated_at": "2025-10-05T15:30:00Z",
"session_id": "WFS-auth-dashboard",
"description": "Modern minimalist design system with high contrast"
},
"colors": {
"brand": {
"primary": "oklch(0.45 0.20 270 / 1)",
"secondary": "oklch(0.60 0.15 200 / 1)",
"accent": "oklch(0.65 0.18 30 / 1)"
},
"surface": {
"background": "oklch(0.98 0.01 270 / 1)",
"elevated": "oklch(1.00 0.00 0 / 1)",
"sunken": "oklch(0.95 0.02 270 / 1)",
"overlay": "oklch(0.00 0.00 0 / 0.5)"
},
"semantic": {
"success": "oklch(0.55 0.15 150 / 1)",
"warning": "oklch(0.70 0.18 60 / 1)",
"error": "oklch(0.50 0.20 20 / 1)",
"info": "oklch(0.60 0.15 240 / 1)"
},
"text": {
"primary": "oklch(0.20 0.02 270 / 1)",
"secondary": "oklch(0.45 0.02 270 / 1)",
"tertiary": "oklch(0.60 0.02 270 / 1)",
"inverse": "oklch(0.98 0.01 270 / 1)",
"disabled": "oklch(0.70 0.01 270 / 0.5)"
},
"border": {
"subtle": "oklch(0.90 0.01 270 / 1)",
"default": "oklch(0.80 0.02 270 / 1)",
"strong": "oklch(0.60 0.05 270 / 1)"
}
},
"typography": {
"font_family": {
"heading": "Inter, system-ui, -apple-system, sans-serif",
"body": "Inter, system-ui, -apple-system, sans-serif",
"mono": "Fira Code, Consolas, monospace"
},
"font_size": {
"xs": "0.75rem",
"sm": "0.875rem",
"base": "1rem",
"lg": "1.125rem",
"xl": "1.25rem",
"2xl": "1.5rem",
"3xl": "1.875rem",
"4xl": "2.25rem",
"5xl": "3rem"
},
"line_height": {
"tight": "1.25",
"normal": "1.5",
"relaxed": "1.75"
},
"font_weight": {
"light": 300,
"normal": 400,
"medium": 500,
"semibold": 600,
"bold": 700
}
},
"spacing": {
"0": "0",
"1": "0.25rem",
"2": "0.5rem",
"3": "0.75rem",
"4": "1rem",
"5": "1.25rem",
"6": "1.5rem",
"8": "2rem",
"10": "2.5rem",
"12": "3rem",
"16": "4rem",
"20": "5rem",
"24": "6rem"
},
"border_radius": {
"none": "0",
"sm": "0.25rem",
"md": "0.5rem",
"lg": "0.75rem",
"xl": "1rem",
"2xl": "1.5rem",
"full": "9999px"
},
"shadow": {
"none": "none",
"sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)",
"md": "0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06)",
"lg": "0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05)",
"xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15), 0 10px 10px oklch(0.00 0.00 0 / 0.04)",
"2xl": "0 25px 50px oklch(0.00 0.00 0 / 0.25)"
},
"breakpoint": {
"sm": "640px",
"md": "768px",
"lg": "1024px",
"xl": "1280px",
"2xl": "1536px"
},
"accessibility": {
"contrast_ratios": {
"text_primary_on_background": {
"background": "oklch(0.98 0.01 270 / 1)",
"foreground": "oklch(0.20 0.02 270 / 1)",
"ratio": 14.2,
"wcag_aa_pass": true,
"wcag_aaa_pass": true
},
"brand_primary_on_background": {
"background": "oklch(0.98 0.01 270 / 1)",
"foreground": "oklch(0.45 0.20 270 / 1)",
"ratio": 6.8,
"wcag_aa_pass": true,
"wcag_aaa_pass": false
}
}
}
}
```
## CSS Custom Properties Generation
Design tokens should be converted to CSS custom properties for use in generated UI:
```css
:root {
/* Brand Colors */
--color-brand-primary: oklch(0.45 0.20 270 / 1);
--color-brand-secondary: oklch(0.60 0.15 200 / 1);
--color-brand-accent: oklch(0.65 0.18 30 / 1);
/* Surface Colors */
--color-surface-background: oklch(0.98 0.01 270 / 1);
--color-surface-elevated: oklch(1.00 0.00 0 / 1);
--color-surface-sunken: oklch(0.95 0.02 270 / 1);
/* Semantic Colors */
--color-semantic-success: oklch(0.55 0.15 150 / 1);
--color-semantic-warning: oklch(0.70 0.18 60 / 1);
--color-semantic-error: oklch(0.50 0.20 20 / 1);
--color-semantic-info: oklch(0.60 0.15 240 / 1);
/* Text Colors */
--color-text-primary: oklch(0.20 0.02 270 / 1);
--color-text-secondary: oklch(0.45 0.02 270 / 1);
--color-text-tertiary: oklch(0.60 0.02 270 / 1);
/* Typography */
--font-family-heading: Inter, system-ui, sans-serif;
--font-family-body: Inter, system-ui, sans-serif;
--font-family-mono: Fira Code, Consolas, monospace;
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.125rem;
--font-size-xl: 1.25rem;
--font-size-2xl: 1.5rem;
--font-size-3xl: 1.875rem;
--font-size-4xl: 2.25rem;
--line-height-tight: 1.25;
--line-height-normal: 1.5;
--line-height-relaxed: 1.75;
/* Spacing */
--spacing-0: 0;
--spacing-1: 0.25rem;
--spacing-2: 0.5rem;
--spacing-3: 0.75rem;
--spacing-4: 1rem;
--spacing-6: 1.5rem;
--spacing-8: 2rem;
--spacing-12: 3rem;
--spacing-16: 4rem;
/* Border Radius */
--border-radius-none: 0;
--border-radius-sm: 0.25rem;
--border-radius-md: 0.5rem;
--border-radius-lg: 0.75rem;
--border-radius-xl: 1rem;
--border-radius-full: 9999px;
/* Shadows */
--shadow-sm: 0 1px 2px oklch(0.00 0.00 0 / 0.05);
--shadow-md: 0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06);
--shadow-lg: 0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05);
}
```
## Tailwind Configuration Generation
```javascript
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
brand: {
primary: 'oklch(0.45 0.20 270 / <alpha-value>)',
secondary: 'oklch(0.60 0.15 200 / <alpha-value>)',
accent: 'oklch(0.65 0.18 30 / <alpha-value>)'
},
surface: {
background: 'oklch(0.98 0.01 270 / <alpha-value>)',
elevated: 'oklch(1.00 0.00 0 / <alpha-value>)',
sunken: 'oklch(0.95 0.02 270 / <alpha-value>)'
},
semantic: {
success: 'oklch(0.55 0.15 150 / <alpha-value>)',
warning: 'oklch(0.70 0.18 60 / <alpha-value>)',
error: 'oklch(0.50 0.20 20 / <alpha-value>)',
info: 'oklch(0.60 0.15 240 / <alpha-value>)'
}
},
fontFamily: {
heading: ['Inter', 'system-ui', 'sans-serif'],
body: ['Inter', 'system-ui', 'sans-serif'],
mono: ['Fira Code', 'Consolas', 'monospace']
},
fontSize: {
'xs': '0.75rem',
'sm': '0.875rem',
'base': '1rem',
'lg': '1.125rem',
'xl': '1.25rem',
'2xl': '1.5rem',
'3xl': '1.875rem',
'4xl': '2.25rem'
},
spacing: {
'1': '0.25rem',
'2': '0.5rem',
'3': '0.75rem',
'4': '1rem',
'6': '1.5rem',
'8': '2rem',
'12': '3rem',
'16': '4rem'
},
borderRadius: {
'sm': '0.25rem',
'md': '0.5rem',
'lg': '0.75rem',
'xl': '1rem',
'2xl': '1.5rem'
},
boxShadow: {
'sm': '0 1px 2px oklch(0.00 0.00 0 / 0.05)',
'md': '0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06)',
'lg': '0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05)'
}
}
}
}
```
## Validation Requirements
### Color Validation
- All colors MUST use OKLCH format
- Alpha channel optional (defaults to 1)
- Lightness: 0-1 (0% to 100%)
- Chroma: 0-0.4 (typical range, can exceed for vibrant colors)
- Hue: 0-360 (degrees)
### Accessibility Validation
- Text on background: minimum 4.5:1 contrast (WCAG AA)
- Large text (18pt+ or 14pt+ bold): minimum 3:1 contrast
- UI components: minimum 3:1 contrast
- Non-text focus indicators: minimum 3:1 contrast
### Consistency Validation
- Spacing scale maintains consistent ratio (e.g., 1.5x or 2x progression)
- Typography scale follows modular scale principles
- Border radius values progress logically
- Shadow layers increase in offset and blur systematically
## Usage in Commands
### style-extract Output
Generates initial `design-tokens.json` from visual analysis
### style-consolidate Output
Finalizes validated `design-tokens.json` with accessibility data
### ui-generate Input
Reads `design-tokens.json` to generate CSS custom properties
### design-update Integration
References `design-tokens.json` path in synthesis-specification.md
## Version History
- **1.0.0**: Initial schema with OKLCH colors, semantic naming, WCAG AA validation

192
.claude/workflows/intelligent-tools-strategy.md
View File

@@ -70,14 +70,33 @@ type: strategic-guideline
- **Default**: No default mode, MODE must be explicitly specified
#### Session Management
- `codex resume` - Resume with picker | `codex exec "task" resume --last` - Continue most recent
- `codex -i <image>` - Attach images for UI/design tasks
- **Multi-task Pattern**: First uses `exec`, subsequent use `exec "..." resume --last`
- **Position**: `resume --last` AFTER prompt string at command END
- `codex resume` - Resume previous interactive session (picker by default)
- `codex exec "task" resume --last` - Continue most recent session with new task (maintains context)
- `codex -i <image_file>` - Attach image(s) to initial prompt (useful for UI/design references)
- **Multi-task Pattern**: First task uses `exec`, subsequent tasks use `exec "..." resume --last` for context continuity
- **Parameter Position**: `resume --last` must be placed AFTER the prompt string at command END
- **Example**:
```bash
# First task - establish session
codex -C project --full-auto exec "Implement auth module" --skip-git-repo-check -s danger-full-access
# Subsequent tasks - continue same session
codex --full-auto exec "Add JWT validation" resume --last --skip-git-repo-check -s danger-full-access
codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s danger-full-access
```
#### Auto-Resume Decision Rules
**Use `resume --last`**: Related task, requires previous context, multi-step workflow on same module
**Don't use**: First task, independent task, different module, no recent Codex session
**When to use `resume --last`**:
- Current task is related to/extends previous Codex task in conversation memory
- Current task requires context from previous implementation
- Current task is part of multi-step workflow (e.g., implement → enhance → test)
- Session memory indicates recent Codex execution on same module/feature
**When NOT to use `resume --last`**:
- First Codex task in conversation
- New independent task unrelated to previous work
- Switching to different module/feature area
- No recent Codex task in conversation memory
---
@@ -158,21 +177,52 @@ RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].tx
```
**⚠️ CRITICAL: Command Substitution Rules**
- **NEVER use escape characters**: `\$`, `\"`, `\'` break command substitution
- **Correct**: `$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)`
- **WRONG**: `\$(cat ...)` or `$(cat \"...\")`
- **Why**: Shell subshell handles path expansion safely
When using `$(cat ...)` for template loading in actual CLI commands:
- **Template reference only, never read**: When user specifies template name, use `$(cat ...)` directly in RULES field, do NOT read template content first
- **NEVER use escape characters**: `\$`, `\"`, `\'` will break command substitution
- **In -p "..." context**: Path in `$(cat ...)` needs NO quotes (tilde expands correctly)
- **Correct**: `RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)`
- **WRONG**: `RULES: \$(cat ...)` or `RULES: $(cat \"...\")` or `RULES: $(cat '...')`
- **Why**: Shell executes `$(...)` in subshell where path is safe without quotes
**Examples**: `$(cat "template.txt") | Focus on security` | `@{src/**/*.ts,CLAUDE.md}`
**Examples**:
- Single template: `$(cat "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt") | Focus on security`
- Multiple templates: `$(cat "template1.txt") $(cat "template2.txt") | Enterprise standards`
- No template: `Focus on security patterns, include dependency analysis`
- File patterns: `@{src/**/*.ts,CLAUDE.md} - Stay within scope`
### File Pattern Reference
Common patterns: `@{**/*}` (all), `@{src/**/*}` (source), `@{*.ts,*.tsx}` (TypeScript), `@{**/*.test.*}` (tests)
Common patterns:
- All files: `@{**/*}`
- Source files: `@{src/**/*}`
- TypeScript: `@{*.ts,*.tsx}`
- With docs: `@{CLAUDE.md,**/*CLAUDE.md}`
- Tests: `@{src/**/*.test.*}`
**Complex Pattern Discovery**: Use semantic tools (rg, MCP) → Extract paths → Build CONTEXT
**Complex Pattern Discovery**:
For complex file pattern requirements, use semantic discovery tools BEFORE CLI execution:
- **rg (ripgrep)**: Content-based file discovery with regex patterns
- **Code Index MCP**: Semantic file search based on task requirements
- **Workflow**: Discover → Extract precise paths → Build CONTEXT field
**Example**:
```bash
# 1. Discover: rg "export.*Component" --files-with-matches --type ts
# 2. Build CONTEXT: @{src/components/Auth.tsx,src/types/auth.d.ts}
# 3. Execute CLI with precise file references
# Step 1: Discover files semantically
rg "export.*Component" --files-with-matches --type ts # Find component files
mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx") # Find interface files
# Step 2: Build precise CONTEXT from discovery results
CONTEXT: @{CLAUDE.md,src/components/Auth.tsx,src/types/auth.d.ts,src/hooks/useAuth.ts}
# Step 3: Execute CLI with precise file references
cd src && ~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Analyze authentication components
TASK: Review auth component patterns and props interfaces
MODE: analysis
CONTEXT: @{components/Auth.tsx,types/auth.d.ts,hooks/useAuth.ts,../CLAUDE.md}
EXPECTED: Pattern analysis and improvement suggestions
RULES: Focus on type safety and component composition
"
```
---
@@ -218,9 +268,33 @@ When planning any coding task, **ALWAYS** integrate CLI tools:
### Common Scenarios
#### Analysis Example
#### Code Analysis
```bash
# Architecture analysis using Analysis Tools
~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Understand codebase architecture
TASK: Analyze project structure and identify patterns
MODE: analysis
CONTEXT: @{src/**/*.ts,CLAUDE.md} Previous analysis of auth system
EXPECTED: Architecture overview and integration points
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on integration points
"
```
#### Documentation Generation
```bash
~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
PURPOSE: Generate API documentation
TASK: Create comprehensive API reference from code
MODE: write
CONTEXT: @{src/api/**/*,CLAUDE.md}
EXPECTED: API.md with all endpoints documented
RULES: Follow project documentation standards
"
```
#### Architecture Analysis
```bash
# Architecture analysis using Analysis Tools (Gemini primary)
cd src/auth && ~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Analyze authentication system architecture
TASK: Review JWT-based auth system design
@@ -233,21 +307,46 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt
# Note: Replace 'gemini-wrapper' with 'qwen-wrapper' if Gemini unavailable
```
#### Codex Development (Multi-task with Resume)
#### Feature Development (Multi-task with Resume)
```bash
# First task
codex -C project --full-auto exec "
# First task - establish session
codex -C path/to/project --full-auto exec "
PURPOSE: Implement user authentication
TASK: JWT-based auth system
TASK: Create JWT-based authentication system
MODE: auto
CONTEXT: @{src/auth/**/*}
EXPECTED: Complete auth module
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)
CONTEXT: @{src/auth/**/*,CLAUDE.md} Database schema from session memory
EXPECTED: Complete auth module with tests
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) | Follow security best practices
" --skip-git-repo-check -s danger-full-access
# Continue session
codex --full-auto exec "Add JWT validation" resume --last --skip-git-repo-check -s danger-full-access
codex --full-auto exec "Generate auth tests" resume --last --skip-git-repo-check -s danger-full-access
# Continue in same session - Add JWT validation
codex --full-auto exec "
PURPOSE: Enhance authentication security
TASK: Add JWT token validation and refresh logic
MODE: auto
CONTEXT: Previous auth implementation from current session
EXPECTED: JWT validation middleware and token refresh endpoints
RULES: Follow JWT best practices, maintain session context
" resume --last --skip-git-repo-check -s danger-full-access
# Continue in same session - Add tests
codex --full-auto exec "
PURPOSE: Increase test coverage
TASK: Generate comprehensive tests for auth module
MODE: write
CONTEXT: Auth implementation from current session
EXPECTED: Complete test suite with 80%+ coverage
RULES: Use Jest, follow existing patterns
" resume --last --skip-git-repo-check -s danger-full-access
```
#### Interactive Session Resume
```bash
# Resume previous session with picker
codex resume
# Or resume most recent session directly
codex resume --last
```
@@ -256,18 +355,21 @@ codex --full-auto exec "Generate auth tests" resume --last --skip-git-repo-check
## 🔧 Best Practices
### General Guidelines
- ✅ Use templates for consistency | Be specific in PURPOSE/TASK/EXPECTED
- ✅ Use rg/MCP for file discovery → Build precise CONTEXT
- ✅ Reference CLAUDE.md for project context
- ⚠️ NEVER use escape characters (`\$`, `\"`, `\'`) in CLI commands
- **Start with templates** - Use predefined templates for consistency
- **Be specific** - Clear PURPOSE, TASK, and EXPECTED fields
- **Include constraints** - File patterns, scope, requirements in RULES
- **Discover patterns first** - Use rg/MCP for complex file discovery before CLI execution
- **Build precise CONTEXT** - Convert discovery results to explicit file references
- **Document context** - Always reference CLAUDE.md for context
- **⚠️ No escape characters in CLI commands** - NEVER use `\$`, `\"`, `\'` in actual CLI execution (breaks command substitution and path expansion)
### Context Optimization Strategy
**Directory Navigation**: Use `cd [directory] &&` for focused analysis to reduce token usage
**Directory Navigation**: Use `cd [directory] &&` pattern when analyzing specific areas to reduce irrelevant context
**Decision Rules**:
- Specific directory → `cd directory &&` pattern
- Focused analysis → Target specific directory
- Multi-directory scope → Stay in root, use explicit paths
**When to change directory**:
- Specific directory mentioned → Use `cd directory &&` pattern
- Focused analysis needed → Target specific directory with cd
- Multi-directory scope → Stay in root, use explicit paths or multiple commands
**Example**:
```bash
@@ -298,22 +400,26 @@ For every development task:
- [ ] **Purpose defined** - Clear goal and intent
- [ ] **Mode selected** - Execution mode and permission level determined
- [ ] **Context gathered** - File references and session memory documented
- [ ] **Analysis completed** - Use Analysis Tools for understanding
- [ ] **Analysis completed** - Use Analysis Tools (Gemini/Qwen) for understanding
- [ ] **Template selected** - Appropriate template chosen
- [ ] **Constraints specified** - File patterns, scope, requirements
- [ ] **Implementation approach** - Tool selection and workflow
- [ ] **Quality measures** - Testing and validation plan
- [ ] **Tool configuration** - Review tool-specific configs if needed
- [ ] **Tool configuration** - Review CLAUDE.md or tool-specific configs if needed
---
## ⚙️ Execution Configuration
### Core Execution Rules
- **Dynamic Timeout**: 20-40min (simple), 40-60min (medium), 60-120min (complex)
- **Codex Multiplier**: 1.5x allocated time
- **Apply to**: All bash() wrapped commands (Analysis Tools, Codex)
- **Auto-detect**: Based on PURPOSE and TASK complexity
- **Dynamic Timeout (20-120min)**: Allocate execution time based on task complexity
- Simple tasks (analysis, search): 20-40min (1200000-2400000ms)
- Medium tasks (refactoring, documentation): 40-60min (2400000-3600000ms)
- Complex tasks (implementation, migration): 60-120min (3600000-7200000ms)
- **Codex Multiplier**: Codex commands use 1.5x of allocated time
- **Apply to All Tools**: All bash() wrapped commands including Gemini, Qwen wrapper and Codex executions
- **Command Examples**: `bash(~/.claude/scripts/gemini-wrapper -p "prompt")`, `bash(codex -C directory --full-auto exec "task")`
- **Auto-detect**: Analyze PURPOSE and TASK fields to determine appropriate timeout
### Permission Framework
- **⚠️ WRITE PROTECTION**: Codebase write/modify requires EXPLICIT user confirmation