---
stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
workflowComplete: true
---

# Workflow Creation Plan: update-component-spec

## Initial Project Context

- **Module:** custom
- **Target Location:** /home/hieutt50/projects/textiq-doc-extraction/bmad-custom-src/workflows/update-component-spec
- **Created:** 2025-12-08

## Workflow Purpose

**Problem Statement:** Source code updates frequently and component tech specs need to be changed accordingly to stay in sync.

**Target Users:** Developers

**Workflow Type:** Documentation generation/update workflow for existing source code components

## Initial Understanding

This workflow will help developers:
- Analyze an existing component in the source code
- Generate or update a technical specification document for that component
- Keep documentation synchronized with code changes over time

---

## Gathered Requirements

### 1. Workflow Classification

| Attribute | Value |
|-----------|-------|
| **Type** | Document Workflow |
| **Flow Pattern** | Linear |
| **Interaction Level** | Mostly Autonomous |
| **Instruction Style** | Intent-Based |

### 2. Input Requirements

- **Primary Input:** File or folder paths to source code components
- **Input Method:** User provides paths at workflow start
- **Prerequisites:** Valid source code files must exist at specified paths

### 3. Output Specifications

- **Output Type:** Markdown document (tech spec)
- **Output Location:** `/docs/specs/`
- **Naming Convention:** TBD (likely based on component name)
- **Update Behavior:** Overwrite existing spec with current state (no change highlighting needed)

### 4. Tech Spec Document Structure

The generated spec should include:

1. **Overview/Purpose** - What the component does and why it exists
2. **API/Interface** - Functions, methods, props, public interfaces
3. **Dependencies** - Imports, external services, related components
4. **Data Flow/State** - How data moves through the component
5. **Usage Examples** - How to use the component in practice

### 5. Success Criteria

- Accurate reflection of current code state
- Clear documentation of public interfaces
- Easy to understand for developers
- Keeps documentation in sync with code changes

---

## Tools Configuration

### Core BMAD Tools

- **Party-Mode**: Excluded - Not needed for autonomous workflow
- **Advanced Elicitation**: Excluded - Not needed for autonomous workflow
- **Brainstorming**: Excluded - Not needed for autonomous workflow

### LLM Features

- **File I/O**: **Included** - Essential for reading source code and writing specs
- **Web-Browsing**: Excluded - Not needed
- **Sub-Agents**: Optional - Available for large codebase analysis
- **Sub-Processes**: Excluded - Not needed

### Memory Systems

- **Sidecar File**: Excluded - Specs regenerated from current code state

### External Integrations

- None required

### Installation Requirements

- No additional installations needed
- All required tools are built-in LLM capabilities

---

## Plan Review

**Review Status:** Approved
**Review Date:** 2025-12-08

**Notes:**
- Plan approved by user without modifications
- Workflow produces documents (tech spec markdown files)
- Proceeding to output format design

---

## Output Format Design

**Format Type**: Structured

**Output Requirements**:
- Document type: Technical specification (Markdown)
- File format: `.md`
- Frequency: Single document per component
- Output location: `/docs/specs/{component-name}.md`

**Structure Specifications**:

```markdown
# Component Tech Spec: {component-name}

> Generated: {date} | Source: {file-path}

## Overview
What the component does and why it exists.

## API / Interface
### Functions
- Function signatures with parameters and return types

### Methods / Properties
- Public methods and properties exposed by the component

## Dependencies
### Internal
- Other project modules imported

### External
- Third-party packages and libraries

### Services
- APIs or services consumed

## Data Flow / State
- Input sources
- Data transformations
- Output destinations
- State management patterns (if applicable)

## Usage Examples
```{language}
// Code examples showing how to use the component
```
```

**Template Information**:
- Template source: AI-generated based on requirements
- Template file: Will be created as `template.md` in workflow folder
- Placeholders: `{component-name}`, `{date}`, `{file-path}`, `{language}`

**Special Considerations**:
- Auto-detect programming language for syntax highlighting
- Extract JSDoc/docstrings when available
- Infer purpose from code structure and naming

---

## Workflow Structure Design

### Step Sequence (3 steps - streamlined for autonomous workflow)

| Step | Name | Purpose | Type |
|------|------|---------|------|
| 1 | `step-01-init` | Collect component path(s), validate inputs, prepare for analysis | Initialization |
| 2 | `step-02-analyze` | Read source code, extract structure, identify patterns | Autonomous Analysis |
| 3 | `step-03-generate` | Generate tech spec document, write to output folder | Document Generation |

### Step Details

#### Step 1: Initialization (`step-01-init.md`)
**Goal:** Collect user input and validate component paths

**Actions:**
1. Welcome user and explain workflow purpose
2. Request file/folder path(s) to analyze
3. Validate paths exist and are readable
4. Detect programming language
5. Confirm analysis scope with user
6. Auto-proceed to analysis step

**Interaction:** Minimal - just path input and confirmation

#### Step 2: Analysis (`step-02-analyze.md`)
**Goal:** Autonomously analyze source code and extract documentation data

**Actions:**
1. Read all source files in specified path(s)
2. Parse code structure (functions, classes, methods, exports)
3. Extract existing documentation (JSDoc, docstrings, comments)
4. Identify imports and dependencies
5. Map data flow patterns
6. Identify usage patterns
7. Auto-proceed to generation step

**Interaction:** None - fully autonomous

#### Step 3: Generation (`step-03-generate.md`)
**Goal:** Generate and save the tech spec document

**Actions:**
1. Create tech spec from template structure
2. Populate all sections with analyzed data
3. Generate usage examples based on code patterns
4. Determine output filename from component name
5. Write to `/docs/specs/{component-name}.md`
6. Display success message with file location
7. End workflow

**Interaction:** None - fully autonomous with success confirmation

### Flow Diagram

```
[Start] → [Step 1: Get Path] → [Step 2: Analyze Code] → [Step 3: Generate Spec] → [End]
              ↓                        ↓                         ↓
         User provides           AI reads and              AI writes
         component path          parses code               markdown spec
```

### Data Flow

| From | To | Data |
|------|-----|------|
| User | Step 1 | File/folder path(s) |
| Step 1 | Step 2 | Validated paths, language detection |
| Step 2 | Step 3 | Extracted code structure, dependencies, patterns |
| Step 3 | Output | Completed tech spec markdown file |

### File Structure

```
update-component-spec/
├── workflow.md                 # Main workflow configuration
├── workflow-plan-*.md          # This planning document
├── templates/
│   └── tech-spec-template.md   # Output document template
└── steps/
    ├── step-01-init.md         # Initialization step
    ├── step-02-analyze.md      # Analysis step
    └── step-03-generate.md     # Generation step
```

### AI Role Definition

**Role:** Technical Documentation Specialist
**Expertise:** Code analysis, API documentation, technical writing
**Communication Style:** Concise, technical, professional
**Collaboration Level:** Minimal interaction - mostly autonomous execution

### Error Handling

| Error | Handling |
|-------|----------|
| Invalid path | Inform user, request valid path |
| Unreadable file | Skip with warning, continue with readable files |
| Empty component | Generate minimal spec with note |
| Unknown language | Default to generic code formatting |

### Success Criteria

- Tech spec accurately reflects current code state
- All sections populated with relevant information
- File saved to correct location
- User notified of completion

---

## Build Summary

**Build Date:** 2025-12-08
**Build Status:** Complete

### Files Created

| File | Path | Description |
|------|------|-------------|
| `workflow.md` | `bmad-custom-src/workflows/update-component-spec/workflow.md` | Main workflow configuration |
| `step-01-init.md` | `bmad-custom-src/workflows/update-component-spec/steps/step-01-init.md` | Initialization step |
| `step-02-analyze.md` | `bmad-custom-src/workflows/update-component-spec/steps/step-02-analyze.md` | Code analysis step |
| `step-03-generate.md` | `bmad-custom-src/workflows/update-component-spec/steps/step-03-generate.md` | Document generation step |
| `tech-spec-template.md` | `bmad-custom-src/workflows/update-component-spec/templates/tech-spec-template.md` | Output template |

### Directory Structure Created

```
bmad-custom-src/workflows/update-component-spec/
├── workflow.md
├── workflow-plan-update-component-spec.md
├── steps/
│   ├── step-01-init.md
│   ├── step-02-analyze.md
│   └── step-03-generate.md
└── templates/
    └── tech-spec-template.md
```

### Next Steps

1. ~~Create Claude Code slash command to invoke the workflow~~ **DONE**
2. Test the workflow with a sample component
3. Review generated output and adjust as needed

---

## Final Review

**Review Date:** 2025-12-08
**Review Status:** PASSED

### Validation Results

| Check | Status |
|-------|--------|
| File Structure | PASSED |
| Configuration | PASSED |
| Step Compliance | PASSED |
| Cross-File Consistency | PASSED |
| Requirements Met | PASSED |

### Files Verified

- `workflow.md` - Main workflow configuration with proper architecture
- `step-01-init.md` - Initialization with path validation (4.3 KB)
- `step-02-analyze.md` - Autonomous code analysis (5.2 KB)
- `step-03-generate.md` - Document generation (6.0 KB)
- `tech-spec-template.md` - Output template structure
- Slash command created at `.claude/commands/custom/workflows/update-component-spec.md`

### How to Use

**Invoke the workflow:**
```
/custom:workflows:update-component-spec
```

**Or run directly:**
Load `bmad-custom-src/workflows/update-component-spec/workflow.md` and follow instructions.

### Workflow Complete

The **update-component-spec** workflow has been successfully created and is ready for use.