Add documentation for new CLI commands: docs-related-cli and lite-fix

- Implemented the `docs-related-cli` command for context-aware documentation generation and update for changed modules using CLI execution with tool fallback.
- Introduced the `lite-fix` command for lightweight bug diagnosis and fix workflow, featuring intelligent severity assessment and optional hotfix mode for production incidents.
This commit is contained in:
catlog22
2025-11-23 22:18:39 +08:00
parent 4bb4bdc124
commit 7453987cfe
76 changed files with 3848 additions and 2013 deletions

View File

@@ -428,15 +428,6 @@ docker-compose.override.yml
/cli:cli-init --tool all --preview
```
## Key Benefits
- **Automatic Detection**: No manual configuration needed
- **Multi-Tool Support**: Configure Gemini and Qwen simultaneously
- **Technology Aware**: Rules adapted to actual project stack
- **Maintainable**: Clear sections for easy customization
- **Consistent**: Follows gitignore syntax standards
- **Safe**: Creates backups of existing files
- **Flexible**: Initialize specific tools or all at once
## Tool Selection Guide

View File

@@ -728,18 +728,6 @@ User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index)
---
## Benefits
- **Per-Feature SKILL**: Independent packages for each analyzed feature
- **Specialized Agent**: cli-explore-agent with Deep Scan mode (Bash + Gemini dual-source)
- **Professional Analysis**: Pre-defined workflow for code exploration and structure analysis
- **Clear Separation**: Agent analyzes (JSON) → Orchestrator documents (Mermaid markdown)
- **Multi-Level Detail**: 4 levels (architecture → function → data → conditional)
- **Visual Flow**: Embedded Mermaid diagrams for all flow types
- **Progressive Loading**: Token-efficient context loading (2K → 30K)
- **Auto-Continue**: Fully autonomous 3-phase execution
- **Smart Skip**: Detects existing codemap, 10x faster index updates
- **CLI Integration**: Gemini/Qwen for deep semantic understanding
## Architecture
@@ -753,12 +741,5 @@ code-map-memory (orchestrator)
│ └─ Transform JSON → 5 Mermaid markdown files + metadata.json
└─ Phase 3: Write SKILL.md (index generation, always runs)
Benefits:
✅ Specialized agent: cli-explore-agent with dual-source strategy (Bash + Gemini)
✅ Professional analysis: Pre-defined Deep Scan workflow
✅ Clear separation: Agent analyzes (JSON) → Orchestrator documents (Mermaid)
✅ Smart skip logic: 10x faster when codemap exists
✅ Multi-level detail: Architecture → Functions → Data → Conditionals
Output: .claude/skills/codemap-{feature}/
```

View File

@@ -37,14 +37,13 @@ Orchestrates project-wide documentation generation using CLI-based execution wit
- **Behavior**: Generates API.md + README.md for current directory AND subdirectories containing code
- **Context**: All files in current directory tree (`@**/*`)
- **Output**: `.workflow/docs/{project_name}/{path}/API.md` + `README.md`
- **Benefits**: Creates foundation documentation for upper layers to reference
#### Single Strategy (Layers 1-2)
- **Use Case**: Upper layers that aggregate from existing documentation
- **Behavior**: Generates API.md + README.md only in current directory
- **Context**: Direct children docs + current directory code files
- **Output**: `.workflow/docs/{project_name}/{path}/API.md` + `README.md`
- **Benefits**: Minimal context consumption, clear layer separation
### Example Flow
```

View File

@@ -36,7 +36,6 @@ Lightweight planner that analyzes project structure, decomposes documentation wo
| `my_app/src/modules/auth/` | `my_app` | `.workflow/docs/my_app/src/modules/auth/API.md` |
| `another_project/lib/utils/` | `another_project` | `.workflow/docs/another_project/lib/utils/API.md` |
**Benefits**: Easy to locate documentation, maintains logical organization, clear 1:1 mapping, supports any project structure.
## Parameters
@@ -181,7 +180,6 @@ Large Projects (single dir >10 docs):
4. If single dir exceeds 10 docs, split by subdirectories
5. Create parallel Level 1 tasks with ≤10 docs each
**Benefits**: Parallel execution, failure isolation, progress visibility, context sharing, document count control.
**Commands**:

View File

@@ -508,16 +508,7 @@ User triggers command
---
## Benefits
- **Pure Orchestrator**: No task JSON generation, delegates to /memory:docs
- **Auto-Continue**: Autonomous 4-phase execution without user interaction
- **Intelligent Skip**: Detects existing docs and skips regeneration for fast SKILL updates
- **Always Fresh Index**: Phase 4 always executes to ensure SKILL.md stays synchronized
- **Simplified**: ~70% less code than previous version
- **Maintainable**: Changes to /memory:docs automatically apply
- **Direct Generation**: Phase 4 directly writes SKILL.md
- **Flexible**: Supports all /memory:docs options (tool, mode, cli-execute)
## Architecture

View File

@@ -36,13 +36,12 @@ Orchestrates project-wide CLAUDE.md updates using batched agent execution with a
- **Use Case**: Deepest directories with unstructured file layouts
- **Behavior**: Generates CLAUDE.md for current directory AND each subdirectory containing files
- **Context**: All files in current directory tree (`@**/*`)
- **Benefits**: Creates foundation documentation for upper layers to reference
#### Single-Layer Strategy (Layers 1-2)
- **Use Case**: Upper layers that aggregate from existing documentation
- **Behavior**: Generates CLAUDE.md only for current directory
- **Context**: Direct children CLAUDE.md files + current directory code files
- **Benefits**: Minimal context consumption, clear layer separation
### Example Flow
```

View File

@@ -324,14 +324,6 @@ Synthesis: .workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.m
- **Dynamic Role Count**: `--count N` parameter determines number of Phase 2 parallel tasks (default: 3, max: 9)
- **Mixed Execution**: Sequential (Phase 1, 3) and Parallel (Phase 2) task execution
**Benefits**:
- Real-time visibility into attached tasks during execution
- Clean orchestrator-level summary after tasks complete
- Clear mental model: SlashCommand/Task = attach tasks, not delegate work
- Parallel execution support for concurrent role analysis
- Dynamic attachment/collapse maintains clarity
**Note**: See individual Phase descriptions (Phase 1, 2, 3) for detailed TodoWrite Update examples with full JSON structures.
## Input Processing

View File

@@ -711,11 +711,7 @@ Each lite-fix execution creates a dedicated session folder to organize all artif
- **User**: Can inspect artifacts for debugging or reference
- **Reuse**: Pass `task.json` path to `/workflow:lite-execute {path}` for re-execution
**Benefits**:
- Clean separation between different bug fixes
- Easy to find and inspect artifacts for specific bugs
- Natural history/audit trail of fixes
- Supports concurrent lite-fix executions without conflicts
**Legacy Cache** (deprecated, use session folder instead):
```

View File

@@ -604,11 +604,6 @@ Each lite-plan execution creates a dedicated session folder to organize all arti
- **User**: Can inspect artifacts for debugging or reference
- **Reuse**: Pass `task.json` path to `/workflow:lite-execute {path}` for re-execution
**Benefits**:
- Clean separation between different task executions
- Easy to find and inspect artifacts for specific tasks
- Natural history/audit trail of planning sessions
- Supports concurrent lite-plan executions without conflicts
## Data Structures

View File

@@ -305,12 +305,7 @@ Quality Gate: Consider running /workflow:action-plan-verify to catch issues earl
**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary for Phase 2/3, or marked completed for Phase 4) → Next phase begins → Repeat until all phases complete.
### Benefits
- ✓ Real-time visibility into sub-task execution
- ✓ Clear mental model: SlashCommand = attach → execute → collapse (Phase 2/3) or complete (Phase 4)
- ✓ Clean summary after completion
- ✓ Easy to track workflow progress
**Note**: See individual Phase descriptions for detailed TodoWrite Update examples:
- **Phase 2, 3**: Multiple sub-tasks with attach/collapse pattern
@@ -389,11 +384,6 @@ Return summary to user
- Brainstorming artifacts (potentially modified by Phase 3)
- Session-specific configuration
**Structured Description Benefits**:
- **Clarity**: Clear separation of goal, scope, and context
- **Consistency**: Same format across all phases
- **Traceability**: Easy to track what was requested
- **Precision**: Better context gathering and analysis
## Execution Flow Diagram

View File

@@ -476,15 +476,4 @@ Session state: PARTIALLY COMPLETE (session archived, manifest needs update)
- Resume from Phase 2 (skip marker creation)
- Idempotent operations (safe to retry)
### Benefits Over Previous Design
**Old Design Weakness**:
- Move first → agent second
- Agent failure → session moved but metadata incomplete
- Inconsistent state requires manual cleanup
**New Design Strengths**:
- Agent first → move second
- Agent failure → session still active, safe to retry
- Transactional commit → all-or-nothing file operations
- Marker-based state → resume capability

View File

@@ -93,11 +93,7 @@ TEST_FOCUS: [Test scenarios]
**Parse**: Extract testContextPath (`.workflow/active/[sessionId]/.process/test-context-package.json`)
**Benefits**:
- Makes TDD aware of existing environment
- Identifies reusable test patterns
- Prevents duplicate test creation
- Enables integration with existing tests
<!-- TodoWrite: When test-context-gather invoked, INSERT 3 test-context-gather tasks -->
@@ -345,12 +341,7 @@ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task
- **Phase 5**: Generated IMPL tasks contain internal Red-Green-Refactor cycles
- **Conditional Phase 4**: Conflict resolution only if conflict_risk ≥ medium
### Benefits
- ✓ Real-time visibility into TDD workflow execution
- ✓ Clear mental model: SlashCommand = attach → execute → collapse
- ✓ Test-aware planning with coverage analysis
- ✓ Self-contained TDD cycles within each IMPL task
**Note**: See individual Phase descriptions (Phase 3, 4, 5) for detailed TodoWrite Update examples with full JSON structures.

View File

@@ -374,14 +374,6 @@ CRITICAL - Next Steps:
- **Phase 4**: Multi-task generation with quality gate (IMPL-001, IMPL-001.5-review, IMPL-002)
- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
**Benefits**:
- Real-time visibility into attached tasks during execution
- Clean orchestrator-level summary after tasks complete
- Clear mental model: SlashCommand = attach tasks, not delegate work
- Dual-mode support: Both Session Mode and Prompt Mode use same attachment pattern
- Dynamic attachment/collapse maintains clarity
**Note**: Unlike other workflow orchestrators, this file consolidates TodoWrite examples in this section rather than distributing them across Phase descriptions for better dual-mode clarity.
---

View File

@@ -355,11 +355,7 @@ Ready for execution. Use appropriate workflow commands to proceed.
- **Phase 4**: Dual-task generation (IMPL-001 for test generation, IMPL-002 for test execution)
- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
**Benefits**:
- Real-time visibility into attached tasks during execution
- Clean orchestrator-level summary after tasks complete
- Clear mental model: SlashCommand = attach tasks, not delegate work
- Dynamic attachment/collapse maintains clarity
**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.

View File

@@ -30,11 +30,6 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
- **1 feature = 1 task** containing complete TDD cycle internally
- Each task executes Red-Green-Refactor phases sequentially
- Task count = Feature count (typically 5 features = 5 tasks)
- **Benefits**:
- 70% reduction in task management overhead
- Continuous context per feature (no switching between TEST/IMPL/REFACTOR)
- Simpler dependency management
- Maintains TDD rigor through internal phase structure
**Previous Approach** (Deprecated):
- 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
@@ -499,11 +494,7 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
- **Repeat**: Up to max_iterations (default: 3)
5. **Safety Net**: Auto-revert all changes if max iterations reached
**Key Benefits**:
- Faster feedback loop within Green phase
- Autonomous recovery from initial implementation errors
- Systematic debugging with Gemini's bug-fix template
- Safe rollback prevents broken TDD state
## Configuration Options
- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)

View File

@@ -120,11 +120,7 @@ ELSE:
- Infers animation patterns from UI element positioning and design style
- Generates context-aware animation specifications based on visual analysis
**Benefits**:
- ✅ Flexible input - works with screenshots, mockups, or design files
- ✅ AI-driven inference from visual cues
- ✅ No external dependencies on MCP tools
- ✅ Combines visual analysis with industry best practices
### Step 3: Load Design Tokens Context

View File

@@ -480,11 +480,7 @@ TodoWrite({todos: [
// - Orchestrator's own task (no SlashCommand attachment)
// - Mark Phase 3 as completed
// - Final state: All 4 orchestrator tasks completed
//
// Benefits:
// ✓ Real-time visibility into attached tasks during execution
// ✓ Clean orchestrator-level summary after tasks complete
// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
// ✓ Dynamic attachment/collapse maintains clarity
```
@@ -623,17 +619,7 @@ File discovery is fully automatic - no glob patterns needed.
---
## Benefits
- **Simplified Interface**: Single path parameter with intelligent defaults
- **Auto-Generation**: Package names auto-generated from directory names
- **Automatic Discovery**: No need to specify file patterns - finds all style files automatically
- **Pure Orchestrator**: No direct agent execution, delegates to specialized commands
- **Auto-Continue**: Autonomous 4-phase execution without user interaction
- **Safety First**: Overwrite protection, validation checks, error handling
- **Code Reuse**: Leverages existing `import-from-code` and `reference-page-generator` commands
- **Clean Separation**: Each command has single responsibility
- **Easy Maintenance**: Changes to sub-commands automatically apply
## Architecture

View File

@@ -548,12 +548,6 @@ TodoWrite({todos: [
// 6. IMMEDIATELY execute next phase (auto-continue)
// 7. After Phase 10 completes, workflow finishes (generate command handles preview files)
//
// Benefits:
// ✓ Real-time visibility into sub-command task progress
// ✓ Clean orchestrator-level summary after each phase
// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
// ✓ Generate command handles preview generation autonomously
// ✓ Dynamic attachment/collapse maintains clarity
```
## Completion Output

View File

@@ -591,11 +591,6 @@ TodoWrite({todos: [
// 5. Update next phase to in_progress
// 6. IMMEDIATELY execute next phase SlashCommand (auto-continue)
//
// Benefits:
// ✓ Real-time visibility into sub-command task progress
// ✓ Clean orchestrator-level summary after each phase
// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
// ✓ Dynamic attachment/collapse maintains clarity
```
## Error Handling