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
Files
9502741d5050933d5c581c1483063d0da548eb58
Claude-Code-Workflow/.claude/workflows/file-structure-standards.md
catlog22 9502741d50 Remove granular progress tracking across workflow system 
- Remove detailed progress views (Total Tasks: X, Completed: Y %) from all templates
- Simplify TODO_LIST.md structure by removing Progress Overview sections
- Remove stats tracking from session-management-principles.json schema
- Eliminate progress format and calculation logic from context command
- Remove percentage-based progress displays from action-planning-agent
- Simplify vibe command coordination by removing detailed task counts
- Focus on essential JSON state changes rather than UI progress metrics

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

Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-08 15:26:01 +08:00

9.4 KiB
Raw Blame History

Workflow File Structure Standards

Overview

This document defines directory layouts, file naming conventions, and progressive complexity structures for workflow sessions.

Progressive Structure System

Complexity → Structure Level

File structure scales with task complexity to minimize overhead for simple tasks while providing comprehensive organization for complex workflows.

Level 0: Minimal Structure (<5 tasks)

Target: Simple workflows with clear, limited scope

.workflow/WFS-[topic-slug]/
├── workflow-session.json        # Session metadata and state
├── [.brainstorming/]           # Optional brainstorming phase
├── [.chat/]                    # Gemini CLI interaction sessions
│   └── chat-*.md              # Saved chat sessions with timestamps
├── IMPL_PLAN.md                # Combined planning document
├── .summaries/                 # Task completion summaries
│   └── IMPL-*.md              # Individual task summaries
└── .task/
    └── impl-*.json             # Task definitions

Level 1: Enhanced Structure (5-15 tasks)

Target: Medium complexity workflows with multiple phases

.workflow/WFS-[topic-slug]/
├── workflow-session.json        # Session metadata and state
├── [.brainstorming/]          # Optional brainstorming phase
├── [.chat/]                   # Gemini CLI interaction sessions
│   └── chat-*.md             # Saved chat sessions with timestamps
├── IMPL_PLAN.md               # Combined planning document
├── TODO_LIST.md               # Auto-triggered progress tracking
├── .summaries/                # Task completion summaries
│   ├── IMPL-*.md             # Main task summaries
│   └── IMPL-*.*.md           # Subtask summaries
└── .task/
    ├── impl-*.json            # Main task definitions
    └── impl-*.*.json          # Subtask definitions (up to 3 levels)

Level 2: Complete Structure (>15 tasks)

Target: Complex workflows with extensive documentation needs

.workflow/WFS-[topic-slug]/
├── workflow-session.json        # Session metadata and state
├── [.brainstorming/]          # Optional brainstorming phase  
├── [.chat/]                   # Gemini CLI interaction sessions
│   ├── chat-*.md             # Saved chat sessions with timestamps
│   └── analysis-*.md         # Comprehensive analysis results
├── IMPL_PLAN.md               # Comprehensive planning document
├── TODO_LIST.md               # Progress tracking and monitoring
├── .summaries/                # Task completion summaries
│   ├── IMPL-*.md             # Main task summaries
│   ├── IMPL-*.*.md           # Subtask summaries
│   └── IMPL-*.*.*.md         # Detailed subtask summaries
└── .task/
    ├── impl-*.json            # Task hierarchy (max 3 levels deep)
    ├── impl-*.*.json          # Subtasks
    └── impl-*.*.*.json        # Detailed subtasks

File Naming Conventions

Session Identifiers

Format: WFS-[topic-slug]

  • Convert topic to lowercase with hyphens (e.g., "User Auth System" → WFS-user-auth-system)
  • Add -NNN suffix only if conflicts exist (e.g., WFS-payment-integration-002)

Task File Naming

Hierarchical ID Format:

impl-1              # Main task
impl-1.1            # Subtask of impl-1
impl-1.1.1          # Detailed subtask of impl-1.1
impl-1.2            # Another subtask of impl-1
impl-2              # Another main task

Maximum Depth: 3 levels (impl-N.M.P)

Document Naming

  • workflow-session.json - Session state (required)
  • IMPL_PLAN.md - Planning document (required)
  • TODO_LIST.md - Progress tracking (auto-generated when needed)
  • Chat sessions: chat-YYYYMMDD-HHMMSS.md
  • Analysis results: analysis-[topic].md
  • Task summaries: IMPL-[task-id]-summary.md

Directory Structure Rules

Required Directories

  • .task/ - Always present, contains JSON task definitions
  • .summaries/ - Always present, contains task completion documentation

Optional Directories

  • .brainstorming/ - Present when brainstorming phase was used
  • .chat/ - Present when Gemini CLI sessions were saved

Directory Permissions and Access

  • All workflow directories are project-local
  • Session registry at .workflow/session_status.jsonl (global)
  • Individual sessions in .workflow/WFS-[topic-slug]/ (session-specific)

Document Generation Triggers

Automatic Document Creation

Based on complexity assessment:

Complexity IMPL_PLAN.md TODO_LIST.md Task Files
Simple (<5 tasks) Always No impl-*.json
Medium (5-15 tasks) Always Auto-trigger* impl-..json
Complex (>15 tasks) Always Always impl-..*.json

Auto-trigger conditions (*):

  • Tasks > 5 OR modules > 3 OR estimated effort > 4h OR complex dependencies

Document Template Standards

IMPL_PLAN.md Structure

# Implementation Plan: [Session Topic]

## Overview
[High-level description]

## Requirements  
[Functional and non-functional requirements]

## [Brainstorming Integration]
[If .brainstorming/ exists - reference analysis results]

## Implementation Strategy
[Technical approach and phases]

## Success Criteria
[Acceptance criteria and validation]

## Risk Assessment
[Potential issues and mitigation strategies]

TODO_LIST.md Structure

# Task Progress List: [Session Topic]

## Implementation Tasks

### Main Tasks
- [ ] **IMPL-001**: [Task Description] → [📋 Details](./.task/impl-001.json)
- [x] **IMPL-002**: [Completed Task] → [📋 Details](./.task/impl-002.json) | [✅ Summary](./.summaries/IMPL-002-summary.md)

### Subtasks (Auto-expanded when active)
- [ ] **IMPL-001.1**: [Subtask Description] → [📋 Details](./.task/impl-001.1.json)

Chat Session Management

Chat Directory Structure

.chat/
├── chat-YYYYMMDD-HHMMSS.md      # Individual chat sessions with timestamps
├── analysis-[topic].md          # Comprehensive analysis results
└── context-[phase].md           # Phase-specific context gathering

Chat Session Template

# Chat Session: [Timestamp] - [Topic]

## Query
[Original user inquiry]

## Template Used
[Auto-selected template name and rationale]

## Context
[Files and patterns included in analysis]

## Gemini Response
[Complete response from Gemini CLI]

## Key Insights
- [Important findings]
- [Architectural insights]
- [Implementation recommendations]

## Links
- [🔙 Back to Workflow](../workflow-session.json)
- [📋 Implementation Plan](../IMPL_PLAN.md)

Summary Management

Summary Directory Structure

.summaries/
├── IMPL-001-summary.md         # Main task summaries  
├── IMPL-001.1-summary.md       # Subtask summaries
└── IMPL-001.1.1-summary.md     # Detailed subtask summaries

Summary Template

# Task Summary: [Task-ID] [Task Name]

## What Was Done
- [Files modified/created]
- [Functionality implemented]
- [Key changes made]

## Issues Resolved
- [Problems solved]
- [Bugs fixed]

## Links
- [🔙 Back to Task List](../TODO_LIST.md#[Task-ID])
- [📋 Implementation Plan](../IMPL_PLAN.md#[Task-ID])

Brainstorming Integration

When .brainstorming/ directory exists, documents MUST reference brainstorming results:

In IMPL_PLAN.md

## Brainstorming Integration
Based on multi-role analysis from `.brainstorming/`:
- **Architecture Insights**: [Reference system-architect/analysis.md]
- **User Experience Considerations**: [Reference ui-designer/analysis.md] 
- **Technical Requirements**: [Reference relevant role analyses]
- **Implementation Priorities**: [Reference synthesis-analysis.md]

In JSON Task Context

{
  "context": {
    "brainstorming_refs": [
      ".workflow/WFS-[topic-slug]/.brainstorming/system-architect/technical-specifications.md",
      ".workflow/WFS-[topic-slug]/.brainstorming/ui-designer/user-experience-plan.md"
    ],
    "requirements": ["derived from brainstorming analysis"]
  }
}

Quality Control

File System Validation

  • Verify directory structure matches complexity level
  • Validate file naming conventions
  • Check for required vs optional directories
  • Ensure proper file permissions

Cross-Reference Validation

  • All document links point to existing files
  • Task IDs consistent across JSON files and TODO_LIST.md
  • Brainstorming references are valid when .brainstorming/ exists
  • Summary links properly reference parent tasks

Performance Considerations

  • Lazy directory creation (create only when needed)
  • Efficient file structure scanning
  • Minimal overhead for simple workflows
  • Scalable organization for complex projects

Error Recovery

Missing File Scenarios

  • workflow-session.json missing: Recreate from available documents
  • Required directories missing: Auto-create with proper structure
  • Template files corrupted: Regenerate from templates
  • Naming convention violations: Auto-correct or flag for manual resolution

Structure Consistency

  • Validate structure level matches task complexity
  • Auto-upgrade structure when complexity increases
  • Maintain backward compatibility during transitions
  • Preserve existing content during structure changes

System ensures: Consistent, scalable file organization with minimal overhead for simple tasks → comprehensive structure for complex projects

Reference in New Issue View Git Blame Copy Permalink