catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-12 17:21:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: update commands, specs, and ccw tools

Browse Source 
Update DDD commands (doc-generate, doc-refresh, sync), workflow commands
(session/sync, spec/add, spec/setup, spec/load), ccw specs, personal
preferences, and add generate-ddd-docs tool.
This commit is contained in:
catlog22
2026-03-09 23:20:39 +08:00
parent cbd1813ea7
commit 663620955c
13 changed files with 1942 additions and 455 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
.claude/commands/ddd/doc-generate.md
View File

@@ -48,8 +48,9 @@ doc-index.json → tech-registry/*.md (L3) → feature-maps/*.md (L2) → _index
├── tech-registry/ ← Component documentation (Layer 3)
│ ├── _index.md
│ └── {component-slug}.md
└── sessions/
└── _index.md ← Planning sessions index (Layer 1)
└── planning/ ← Planning sessions (Layer 1)
├── _index.md ← Planning sessions index
└── {task-slug}-{date}/ ← Individual session folders
```
## Phase 1: Load & Validate
@@ -87,147 +88,82 @@ IF docs already exist AND NOT --force:
Ask user (unless -y → overwrite)
```
## Phase 2: Layer 3 — Component Documentation
## Phase 2: Layer 3 -- Component Documentation
For each component in `technicalComponents[]`:
For each component in `technicalComponents[]`, call the generate_ddd_docs endpoint:
```bash
ccw cli -p "PURPOSE: Generate component documentation for {component.name}
TASK:
• Document component purpose and responsibility
• List exported symbols (classes, functions, types)
• Document dependencies (internal and external)
• Include code examples for key APIs
• Document integration points with other components
MODE: write
CONTEXT: @{component.codeLocations[].path}
EXPECTED: Markdown file with: Overview, API Reference, Dependencies, Usage Examples
CONSTRAINTS: Focus on public API | Include type signatures
" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/
for COMPONENT_ID in "${technicalComponents[@]}"; do
ccw tool exec generate_ddd_docs '{"strategy":"component","entityId":"'"$COMPONENT_ID"'","tool":"gemini"}'
done
```
The endpoint handles:
- Loading the component entity from doc-index.json
- Building YAML frontmatter (layer: 3, component_id, name, type, features, code_locations, generated_at)
- Constructing the CLI prompt with code context paths
- **Including Change History section**: Pull related entries from `doc-index.json.actions[]` where `affectedComponents` includes this component ID. Display as timeline (date, action type, description)
- Writing output to `.workflow/.doc-index/tech-registry/{slug}.md`
- Tool fallback (gemini -> qwen -> codex) on failure
Output: `.workflow/.doc-index/tech-registry/{component-slug}.md`
Frontmatter:
```markdown
---
layer: 3
component_id: tech-{slug}
name: ComponentName
type: service|controller|model|...
features: [feat-auth]
code_locations:
- path: src/services/auth.ts
symbols: [AuthService, AuthService.login]
generated_at: ISO8601
---
```
## Phase 3: Layer 2 -- Feature Documentation
Sections: Responsibility, Code Locations, Related Requirements, Architecture Decisions, Dependencies (in/out)
## Phase 3: Layer 2 — Feature Documentation
For each feature in `features[]`:
For each feature in `features[]`, call the generate_ddd_docs endpoint:
```bash
ccw cli -p "PURPOSE: Generate feature documentation for {feature.name}
TASK:
• Describe feature purpose and business value
• List requirements (from requirementIds)
• Document components involved (from techComponentIds)
• Include architecture decisions (from adrIds)
• Provide integration guide
MODE: write
CONTEXT: @.workflow/.doc-index/tech-registry/{related-components}.md
EXPECTED: Markdown file with: Overview, Requirements, Components, Architecture, Integration
CONSTRAINTS: Reference Layer 3 component docs | Business-focused language
" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/
for FEATURE_ID in "${features[@]}"; do
ccw tool exec generate_ddd_docs '{"strategy":"feature","entityId":"'"$FEATURE_ID"'","tool":"gemini"}'
done
```
The endpoint handles:
- Loading the feature entity from doc-index.json
- Building YAML frontmatter (layer: 2, feature_id, name, epic_id, status, requirements, components, tags, generated_at)
- Constructing the CLI prompt referencing Layer 3 component docs
- **Including Change History section**: Pull related entries from `doc-index.json.actions[]` where `affectedFeatures` includes this feature ID. Display as timeline (date, action type, description)
- Writing output to `.workflow/.doc-index/feature-maps/{slug}.md`
- Tool fallback (gemini -> qwen -> codex) on failure
Output: `.workflow/.doc-index/feature-maps/{feature-slug}.md`
Frontmatter:
```markdown
---
layer: 2
feature_id: feat-{slug}
name: Feature Name
epic_id: EPIC-NNN|null
status: implemented|in-progress|planned|partial
requirements: [REQ-001, REQ-002]
components: [tech-auth-service, tech-user-model]
depends_on_layer3: [tech-auth-service, tech-user-model]
tags: [auth, security]
generated_at: ISO8601
---
```
Sections: Overview, Requirements (with mapping status), Technical Components, Architecture Decisions, Change History
## Phase 4: Layer 1 — Index & Overview Documentation
## Phase 4: Layer 1 -- Index & Overview Documentation
### 4.1 Index Documents
Generate catalog files:
Generate catalog files for each subdirectory:
- **feature-maps/_index.md** — Feature overview table with status
- **tech-registry/_index.md** — Component registry table with types
- **action-logs/_index.md** — Action history table (empty initially for new projects)
```bash
# Feature maps index
ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"feature-maps","tool":"gemini"}'
# Tech registry index
ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"tech-registry","tool":"gemini"}'
# Action logs index
ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"action-logs","tool":"gemini"}'
# Planning sessions index
ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"planning","tool":"gemini"}'
```
Or generate all indexes at once (omit entityId):
```bash
ccw tool exec generate_ddd_docs '{"strategy":"index","tool":"gemini"}'
```
### 4.2 README.md (unless --skip-overview)
```bash
ccw cli -p "PURPOSE: Generate project README with overview and navigation
TASK:
• Project summary and purpose
• Quick start guide
• Navigation to features, components, and architecture
• Link to doc-index.json
MODE: write
CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/feature-maps/_index.md
EXPECTED: README.md with: Overview, Quick Start, Navigation, Links
CONSTRAINTS: High-level only | Entry point for new developers
" --tool gemini --mode write --cd .workflow/.doc-index/
ccw tool exec generate_ddd_docs '{"strategy":"overview","tool":"gemini"}'
```
### 4.3 ARCHITECTURE.md (unless --skip-overview)
```bash
ccw cli -p "PURPOSE: Generate architecture overview document
TASK:
• System design overview
• Component relationships and dependencies
• Key architecture decisions (from ADRs)
• Technology stack
MODE: write
CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/tech-registry/*.md
EXPECTED: ARCHITECTURE.md with: System Design, Component Diagram, ADRs, Tech Stack
CONSTRAINTS: Architecture-focused | Reference component docs for details
" --tool gemini --mode write --cd .workflow/.doc-index/
```
### 4.4 sessions/_index.md (unless --skip-overview)
```bash
ccw cli -p "PURPOSE: Generate planning sessions index
TASK:
• List all planning session folders chronologically
• Link to each session's plan.json
• Show session status and task count
MODE: write
CONTEXT: @.workflow/.doc-index/planning/*/plan.json
EXPECTED: sessions/_index.md with: Session List, Links, Status
CONSTRAINTS: Chronological order | Link to session folders
" --tool gemini --mode write --cd .workflow/.doc-index/sessions/
```
Layer 1 frontmatter:
```markdown
---
layer: 1
depends_on_layer2: [feat-auth, feat-orders]
generated_at: ISO8601
---
ccw tool exec generate_ddd_docs '{"strategy":"overview","entityId":"architecture","tool":"gemini"}'
```
## Phase 5: SCHEMA.md (unless --skip-schema)
@@ -235,17 +171,7 @@ generated_at: ISO8601
### 5.1 Generate Schema Documentation
```bash
ccw cli -p "PURPOSE: Document doc-index.json schema structure and versioning
TASK:
• Document current schema structure (all fields)
• Define versioning policy (semver: major.minor)
• Document migration protocol for version upgrades
• Provide examples for each schema section
MODE: write
CONTEXT: @.workflow/.doc-index/doc-index.json
EXPECTED: SCHEMA.md with: Schema Structure, Versioning Policy, Migration Protocol, Examples
CONSTRAINTS: Complete field documentation | Clear migration steps
" --tool gemini --mode write --cd .workflow/.doc-index/
ccw tool exec generate_ddd_docs '{"strategy":"schema","tool":"gemini"}'
```
### 5.2 Versioning Policy
@@ -284,7 +210,7 @@ Total: {N} documents generated
| `-y, --yes` | Auto-confirm all decisions |
| `--layer <3\|2\|1\|all>` | Generate specific layer only (default: all) |
| `--force` | Overwrite existing documents |
| `--skip-overview` | Skip README.md, ARCHITECTURE.md, sessions/_index.md |
| `--skip-overview` | Skip README.md, ARCHITECTURE.md, planning/_index.md |
| `--skip-schema` | Skip SCHEMA.md generation |
## Integration Points
@@ -293,3 +219,4 @@ Total: {N} documents generated
- **Called by**: `/ddd:scan` (after index assembly), `/ddd:index-build` (after index assembly)
- **Standalone**: Can be run independently on any project with existing doc-index.json
- **Output**: Complete document tree in `.workflow/.doc-index/`
- **Endpoint**: `ccw tool exec generate_ddd_docs` handles prompt construction, frontmatter, tool fallback, and file creation

2
.claude/commands/ddd/doc-refresh.md
View File

@@ -163,7 +163,7 @@ ccw cli -p "PURPOSE: Update project overview docs after feature changes
TASK:
• Update README.md feature list
• Update ARCHITECTURE.md if new components added
• Update sessions/_index.md with new planning sessions
• Update planning/_index.md with new planning sessions
MODE: write
CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json
EXPECTED: Updated overview docs with current project state

36
.claude/commands/ddd/sync.md
View File

@@ -37,11 +37,42 @@ After completing a development task, synchronize the document index with actual
- `doc-index.json` must exist
- Git repository with committed or staged changes
## Phase 0: Consistency Validation
Before processing changes, verify that `doc-index.json` entries are consistent with actual code state.
### 0.1 Validate Code Locations
For each `technicalComponents[].codeLocations[]`:
- Verify file exists on disk
- If file was deleted/moved → flag for removal or update
- If file exists → verify listed `symbols[]` still exist (quick grep/AST check)
### 0.2 Validate Symbols
For components with `codeLocations[].symbols[]`:
- Check each symbol still exists in the referenced file
- Detect new exported symbols not yet tracked
- Report: `{N} stale symbols, {N} untracked symbols`
### 0.3 Validation Report
```
Consistency Check:
Components validated: {N}
Files verified: {N}
Stale references: {N} (files missing or symbols removed)
Untracked symbols: {N} (new exports not in index)
```
If stale references found: warn and auto-fix during Phase 3 updates.
If `--dry-run`: report only, no fixes.
## Phase 1: Change Detection
### 0.1 Schema Version Check (TASK-006)
### 1.0.1 Schema Version Check
Before processing changes, verify doc-index schema compatibility:
Before processing changes, verify doc-index.json schema compatibility:
```javascript
const docIndex = JSON.parse(Read('.workflow/.doc-index/doc-index.json'));
@@ -201,6 +232,7 @@ For each affected component in `doc-index.json`:
- Update `codeLocations` if file paths or line ranges changed
- Update `symbols` if new exports were added
- Add new `actionIds` entry
- **Auto-update `responsibility`**: If symbols changed (new methods/exports added or removed), re-infer responsibility from current symbols list using Gemini analysis. This prevents stale descriptions (e.g., responsibility still says "登录、注册" after adding logout support)
### 3.2 Register New Components