mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +08:00
docs: update workflow initialization documentation and add project metadata schema
This commit is contained in:
catlog22
@@ -10,555 +10,151 @@ examples:
|
|||||||
# Workflow Init Command (/workflow:init)
|
# Workflow Init Command (/workflow:init)
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
Initializes `.workflow/project.json` with comprehensive project understanding by leveraging **cli-explore-agent** for intelligent analysis and **memory discovery** for SKILL package indexing.
|
Initialize `.workflow/project.json` with comprehensive project understanding by delegating analysis to **cli-explore-agent**.
|
||||||
|
|
||||||
**Key Features**:
|
**Note**: This command may be called by other workflow commands. Upon completion, return immediately to continue the calling workflow without interrupting the task flow.
|
||||||
- **Intelligent Project Analysis**: Uses cli-explore-agent's Deep Scan mode
|
|
||||||
- **Technology Stack Detection**: Identifies languages, frameworks, build tools
|
|
||||||
- **Architecture Overview**: Discovers patterns, layers, key components
|
|
||||||
- **Memory Discovery**: Scans and indexes available SKILL packages
|
|
||||||
- **Smart Recommendations**: Suggests memory commands based on project state
|
|
||||||
- **One-time Initialization**: Skips if project.json exists (unless --regenerate)
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
```bash
|
```bash
|
||||||
/workflow:init # Initialize project state (skip if exists)
|
/workflow:init # Initialize (skip if exists)
|
||||||
/workflow:init --regenerate # Force regeneration of project.json
|
/workflow:init --regenerate # Force regeneration
|
||||||
```
|
```
|
||||||
|
|
||||||
## Implementation Flow
|
## Implementation
|
||||||
|
|
||||||
### Step 1: Check Existing State
|
### Step 1: Check Existing State
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Check if project.json already exists
|
|
||||||
bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
|
bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
|
||||||
```
|
```
|
||||||
|
|
||||||
**If EXISTS and no --regenerate flag**:
|
**If EXISTS and no --regenerate**: Exit early
|
||||||
```
|
```
|
||||||
Project already initialized at .workflow/project.json
|
Project already initialized at .workflow/project.json
|
||||||
Use /workflow:init --regenerate to rebuild project analysis
|
Use /workflow:init --regenerate to rebuild
|
||||||
Use /workflow:status --project to view current state
|
Use /workflow:status --project to view state
|
||||||
```
|
```
|
||||||
|
|
||||||
**If NOT_FOUND or --regenerate flag**: Proceed to initialization
|
### Step 2: Get Project Metadata
|
||||||
|
|
||||||
### Step 2: Project Discovery
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Get project name and root
|
|
||||||
bash(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
bash(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
||||||
bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||||
|
|
||||||
# Create .workflow directory
|
|
||||||
bash(mkdir -p .workflow)
|
bash(mkdir -p .workflow)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Step 3: Intelligent Project Analysis
|
### Step 3: Invoke cli-explore-agent
|
||||||
|
|
||||||
**Invoke cli-explore-agent** with Deep Scan mode for comprehensive understanding:
|
**For --regenerate**: Backup and preserve existing data
|
||||||
|
```bash
|
||||||
|
bash(cp .workflow/project.json .workflow/project.json.backup)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Delegate analysis to agent**:
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
Task(
|
Task(
|
||||||
subagent_type="cli-explore-agent",
|
subagent_type="cli-explore-agent",
|
||||||
description="Deep project analysis",
|
description="Deep project analysis",
|
||||||
prompt=`
|
prompt=`
|
||||||
Analyze project structure and technology stack for workflow initialization.
|
Analyze project for workflow initialization and generate .workflow/project.json.
|
||||||
|
|
||||||
## Analysis Objective
|
## Output Schema Reference
|
||||||
Perform Deep Scan analysis to build comprehensive project understanding for .workflow/project.json initialization.
|
~/.claude/workflows/cli-templates/schemas/project-json-schema.json
|
||||||
|
|
||||||
## Required Analysis
|
## Task
|
||||||
|
Generate complete project.json with:
|
||||||
|
- project_name: ${projectName}
|
||||||
|
- initialized_at: current ISO timestamp
|
||||||
|
- overview: {description, technology_stack, architecture, key_components, entry_points, metrics}
|
||||||
|
- features: ${regenerate ? 'preserve from backup' : '[] (empty)'}
|
||||||
|
- statistics: ${regenerate ? 'preserve from backup' : '{total_features: 0, total_sessions: 0, last_updated}'}
|
||||||
|
- memory_resources: {skills, documentation, module_docs, gaps, last_scanned}
|
||||||
|
- _metadata: {initialized_by: "cli-explore-agent", analysis_timestamp, analysis_mode}
|
||||||
|
|
||||||
### 1. Technology Stack Detection
|
## Analysis Requirements
|
||||||
- **Primary Languages**: Identify all programming languages with file counts
|
|
||||||
- **Frameworks**: Detect web frameworks (React, Vue, Express, Django, etc.)
|
|
||||||
- **Build Tools**: Identify build systems (npm, cargo, maven, gradle, etc.)
|
|
||||||
- **Test Frameworks**: Find testing tools (jest, pytest, go test, etc.)
|
|
||||||
|
|
||||||
### 2. Project Architecture
|
**Technology Stack**:
|
||||||
- **Architecture Style**: Identify patterns (MVC, microservices, monorepo, etc.)
|
- Languages: File counts, mark primary
|
||||||
- **Layer Structure**: Discover architectural layers (presentation, business, data)
|
- Frameworks: From package.json, requirements.txt, go.mod, etc.
|
||||||
- **Design Patterns**: Find common patterns (singleton, factory, repository, etc.)
|
- Build tools: npm, cargo, maven, webpack, vite
|
||||||
- **Key Components**: List 5-10 core modules/components with brief descriptions
|
- Test frameworks: jest, pytest, go test, junit
|
||||||
|
|
||||||
### 3. Project Metrics
|
**Architecture**:
|
||||||
- **Total Files**: Count source code files
|
- Style: MVC, microservices, layered (from structure & imports)
|
||||||
- **Lines of Code**: Estimate total LOC
|
- Layers: presentation, business-logic, data-access
|
||||||
- **Module Count**: Number of top-level modules/packages
|
- Patterns: singleton, factory, repository
|
||||||
- **Complexity**: Overall complexity rating (low/medium/high)
|
- Key components: 5-10 modules {name, path, description, importance}
|
||||||
|
|
||||||
### 4. Entry Points
|
**Metrics**:
|
||||||
- **Main Entry**: Identify primary application entry point(s)
|
- total_files: Source files (exclude tests/configs)
|
||||||
- **CLI Commands**: Discover available commands/scripts
|
- lines_of_code: Use find + wc -l
|
||||||
- **API Endpoints**: Find HTTP/REST/GraphQL endpoints (if applicable)
|
- module_count: Use ~/.claude/scripts/get_modules_by_depth.sh
|
||||||
|
- complexity: low | medium | high
|
||||||
|
|
||||||
## Execution Mode
|
**Entry Points**:
|
||||||
Use **Deep Scan** with Dual-Source Strategy:
|
- main: index.ts, main.py, main.go
|
||||||
- Phase 1: Bash structural scan (fast pattern discovery)
|
- cli_commands: package.json scripts, Makefile targets
|
||||||
- Phase 2: Gemini semantic analysis (design intent, patterns)
|
- api_endpoints: HTTP/REST routes (if applicable)
|
||||||
- Phase 3: Synthesis (merge findings with attribution)
|
|
||||||
|
|
||||||
## Analysis Scope
|
**Memory Resources**:
|
||||||
- Root directory: ${projectRoot}
|
- skills: Scan .claude/skills/ → [{name, type, path}]
|
||||||
- Exclude: node_modules, dist, build, .git, vendor, __pycache__
|
- documentation: Scan .workflow/docs/ → [{name, path, has_readme, has_architecture}]
|
||||||
- Focus: Source code directories (src, lib, pkg, app, etc.)
|
- module_docs: Find **/CLAUDE.md (exclude node_modules, .git)
|
||||||
|
- gaps: Identify missing resources
|
||||||
|
|
||||||
## Output Format
|
## Execution
|
||||||
Return JSON structure for programmatic processing:
|
1. Structural scan: get_modules_by_depth.sh, find, wc -l
|
||||||
|
2. Semantic analysis: Gemini for patterns/architecture
|
||||||
|
3. Synthesis: Merge findings
|
||||||
|
4. ${regenerate ? 'Merge with preserved features/statistics from .workflow/project.json.backup' : ''}
|
||||||
|
5. Write JSON: Write('.workflow/project.json', jsonContent)
|
||||||
|
6. Report: Return brief completion summary
|
||||||
|
|
||||||
\`\`\`json
|
Project root: ${projectRoot}
|
||||||
{
|
`
|
||||||
"technology_stack": {
|
|
||||||
"languages": [
|
|
||||||
{"name": "TypeScript", "file_count": 150, "primary": true},
|
|
||||||
{"name": "Python", "file_count": 30, "primary": false}
|
|
||||||
],
|
|
||||||
"frameworks": ["React", "Express", "TypeORM"],
|
|
||||||
"build_tools": ["npm", "webpack"],
|
|
||||||
"test_frameworks": ["Jest", "Supertest"]
|
|
||||||
},
|
|
||||||
"architecture": {
|
|
||||||
"style": "Layered MVC with Repository Pattern",
|
|
||||||
"layers": ["presentation", "business-logic", "data-access"],
|
|
||||||
"patterns": ["MVC", "Repository Pattern", "Dependency Injection"],
|
|
||||||
"key_components": [
|
|
||||||
{
|
|
||||||
"name": "Authentication Module",
|
|
||||||
"path": "src/auth",
|
|
||||||
"description": "JWT-based authentication with OAuth2 support",
|
|
||||||
"importance": "high"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "User Management",
|
|
||||||
"path": "src/users",
|
|
||||||
"description": "User CRUD operations and profile management",
|
|
||||||
"importance": "high"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"metrics": {
|
|
||||||
"total_files": 180,
|
|
||||||
"lines_of_code": 15000,
|
|
||||||
"module_count": 12,
|
|
||||||
"complexity": "medium"
|
|
||||||
},
|
|
||||||
"entry_points": {
|
|
||||||
"main": "src/index.ts",
|
|
||||||
"cli_commands": ["npm start", "npm test", "npm run build"],
|
|
||||||
"api_endpoints": ["/api/auth", "/api/users", "/api/posts"]
|
|
||||||
},
|
|
||||||
"analysis_metadata": {
|
|
||||||
"timestamp": "2025-01-18T10:30:00Z",
|
|
||||||
"mode": "deep-scan",
|
|
||||||
"source": "cli-explore-agent"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
\`\`\`
|
|
||||||
|
|
||||||
## Quality Requirements
|
|
||||||
- ✅ All technology stack items verified (no guessing)
|
|
||||||
- ✅ Key components include file paths for navigation
|
|
||||||
- ✅ Architecture style based on actual code patterns, not assumptions
|
|
||||||
- ✅ Metrics calculated from actual file counts/lines
|
|
||||||
- ✅ Entry points verified as executable
|
|
||||||
`
|
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
**Agent Output**: JSON structure with comprehensive project analysis
|
### Step 4: Display Summary
|
||||||
|
|
||||||
### Step 4: Build project.json from Analysis
|
|
||||||
|
|
||||||
**Data Processing**:
|
|
||||||
```javascript
|
```javascript
|
||||||
// Parse agent analysis output
|
const projectJson = JSON.parse(Read('.workflow/project.json'));
|
||||||
const analysis = JSON.parse(agentOutput);
|
|
||||||
|
|
||||||
// Build complete project.json structure
|
console.log(`
|
||||||
const projectMeta = {
|
|
||||||
// Basic metadata
|
|
||||||
project_name: projectName,
|
|
||||||
initialized_at: new Date().toISOString(),
|
|
||||||
|
|
||||||
// Project overview (from cli-explore-agent)
|
|
||||||
overview: {
|
|
||||||
description: generateDescription(analysis), // e.g., "TypeScript web application with React frontend"
|
|
||||||
technology_stack: analysis.technology_stack,
|
|
||||||
architecture: {
|
|
||||||
style: analysis.architecture.style,
|
|
||||||
layers: analysis.architecture.layers,
|
|
||||||
patterns: analysis.architecture.patterns
|
|
||||||
},
|
|
||||||
key_components: analysis.architecture.key_components,
|
|
||||||
entry_points: analysis.entry_points,
|
|
||||||
metrics: analysis.metrics
|
|
||||||
},
|
|
||||||
|
|
||||||
// Feature registry (initially empty, populated by complete)
|
|
||||||
features: [],
|
|
||||||
|
|
||||||
// Statistics
|
|
||||||
statistics: {
|
|
||||||
total_features: 0,
|
|
||||||
total_sessions: 0,
|
|
||||||
last_updated: new Date().toISOString()
|
|
||||||
},
|
|
||||||
|
|
||||||
// Analysis metadata
|
|
||||||
_metadata: {
|
|
||||||
initialized_by: "cli-explore-agent",
|
|
||||||
analysis_timestamp: analysis.analysis_metadata.timestamp,
|
|
||||||
analysis_mode: analysis.analysis_metadata.mode
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
// Helper: Generate project description
|
|
||||||
function generateDescription(analysis) {
|
|
||||||
const primaryLang = analysis.technology_stack.languages.find(l => l.primary);
|
|
||||||
const frameworks = analysis.technology_stack.frameworks.slice(0, 2).join(', ');
|
|
||||||
|
|
||||||
return `${primaryLang.name} project using ${frameworks}`;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Write to .workflow/project.json
|
|
||||||
Write('.workflow/project.json', JSON.stringify(projectMeta, null, 2));
|
|
||||||
```
|
|
||||||
|
|
||||||
### Step 5: Output Summary
|
|
||||||
|
|
||||||
```
|
|
||||||
✓ Project initialized successfully
|
✓ Project initialized successfully
|
||||||
|
|
||||||
## Project Overview
|
## Project Overview
|
||||||
Name: ${projectName}
|
Name: ${projectJson.project_name}
|
||||||
Description: ${overview.description}
|
Description: ${projectJson.overview.description}
|
||||||
|
|
||||||
### Technology Stack
|
### Technology Stack
|
||||||
Languages: ${languages.map(l => l.name).join(', ')}
|
Languages: ${projectJson.overview.technology_stack.languages.map(l => l.name).join(', ')}
|
||||||
Frameworks: ${frameworks.join(', ')}
|
Frameworks: ${projectJson.overview.technology_stack.frameworks.join(', ')}
|
||||||
|
|
||||||
### Architecture
|
### Architecture
|
||||||
Style: ${architecture.style}
|
Style: ${projectJson.overview.architecture.style}
|
||||||
Components: ${key_components.length} core modules identified
|
Components: ${projectJson.overview.key_components.length} core modules
|
||||||
|
|
||||||
### Project Metrics
|
### Metrics
|
||||||
Files: ${metrics.total_files}
|
Files: ${projectJson.overview.metrics.total_files}
|
||||||
LOC: ${metrics.lines_of_code}
|
LOC: ${projectJson.overview.metrics.lines_of_code}
|
||||||
Complexity: ${metrics.complexity}
|
Complexity: ${projectJson.overview.metrics.complexity}
|
||||||
|
|
||||||
### Memory Resources
|
### Memory Resources
|
||||||
SKILL Packages: ${memory_resources.skills.length}
|
SKILL Packages: ${projectJson.memory_resources.skills.length}
|
||||||
Documentation: ${memory_resources.documentation.length} project(s)
|
Documentation: ${projectJson.memory_resources.documentation.length}
|
||||||
Module Docs: ${memory_resources.module_docs.length} file(s)
|
Module Docs: ${projectJson.memory_resources.module_docs.length}
|
||||||
Gaps: ${memory_resources.gaps.join(', ') || 'none'}
|
Gaps: ${projectJson.memory_resources.gaps.join(', ') || 'none'}
|
||||||
|
|
||||||
## Quick Start
|
|
||||||
• /workflow:plan "feature description" - Start new workflow
|
|
||||||
• /workflow:status --project - View project state
|
|
||||||
|
|
||||||
---
|
---
|
||||||
Project state saved to: .workflow/project.json
|
Project state: .workflow/project.json
|
||||||
Memory index updated: ${memory_resources.last_scanned}
|
${regenerate ? 'Backup: .workflow/project.json.backup' : ''}
|
||||||
|
`);
|
||||||
```
|
```
|
||||||
|
|
||||||
## Extended project.json Schema
|
|
||||||
|
|
||||||
### Complete Structure
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"project_name": "claude_dms3",
|
|
||||||
"initialized_at": "2025-01-18T10:00:00Z",
|
|
||||||
|
|
||||||
"overview": {
|
|
||||||
"description": "TypeScript workflow automation system with AI agent orchestration",
|
|
||||||
"technology_stack": {
|
|
||||||
"languages": [
|
|
||||||
{"name": "TypeScript", "file_count": 150, "primary": true},
|
|
||||||
{"name": "Bash", "file_count": 30, "primary": false}
|
|
||||||
],
|
|
||||||
"frameworks": ["Node.js"],
|
|
||||||
"build_tools": ["npm"],
|
|
||||||
"test_frameworks": ["Jest"]
|
|
||||||
},
|
|
||||||
"architecture": {
|
|
||||||
"style": "Agent-based workflow orchestration with modular command system",
|
|
||||||
"layers": ["command-layer", "agent-orchestration", "cli-integration"],
|
|
||||||
"patterns": ["Command Pattern", "Agent Pattern", "Template Method"]
|
|
||||||
},
|
|
||||||
"key_components": [
|
|
||||||
{
|
|
||||||
"name": "Workflow Planning",
|
|
||||||
"path": ".claude/commands/workflow",
|
|
||||||
"description": "Multi-phase planning workflow with brainstorming and task generation",
|
|
||||||
"importance": "high"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "Agent System",
|
|
||||||
"path": ".claude/agents",
|
|
||||||
"description": "Specialized agents for code development, testing, documentation",
|
|
||||||
"importance": "high"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "CLI Tool Integration",
|
|
||||||
"path": ".claude/scripts",
|
|
||||||
"description": "Gemini, Qwen, Codex wrapper scripts for AI-powered analysis",
|
|
||||||
"importance": "medium"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"entry_points": {
|
|
||||||
"main": ".claude/commands/workflow/plan.md",
|
|
||||||
"cli_commands": ["/workflow:plan", "/workflow:execute", "/memory:docs"],
|
|
||||||
"api_endpoints": []
|
|
||||||
},
|
|
||||||
"metrics": {
|
|
||||||
"total_files": 180,
|
|
||||||
"lines_of_code": 15000,
|
|
||||||
"module_count": 12,
|
|
||||||
"complexity": "medium"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
|
|
||||||
"features": [],
|
|
||||||
|
|
||||||
"statistics": {
|
|
||||||
"total_features": 0,
|
|
||||||
"total_sessions": 0,
|
|
||||||
"last_updated": "2025-01-18T10:00:00Z"
|
|
||||||
},
|
|
||||||
|
|
||||||
"memory_resources": {
|
|
||||||
"skills": [
|
|
||||||
{"name": "claude_dms3", "type": "project_docs", "path": ".claude/skills/claude_dms3"},
|
|
||||||
{"name": "workflow-progress", "type": "workflow_progress", "path": ".claude/skills/workflow-progress"}
|
|
||||||
],
|
|
||||||
"documentation": [
|
|
||||||
{
|
|
||||||
"name": "claude_dms3",
|
|
||||||
"path": ".workflow/docs/claude_dms3",
|
|
||||||
"has_readme": true,
|
|
||||||
"has_architecture": true
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"module_docs": [
|
|
||||||
".claude/commands/workflow/CLAUDE.md",
|
|
||||||
".claude/agents/CLAUDE.md"
|
|
||||||
],
|
|
||||||
"gaps": ["tech_stack"],
|
|
||||||
"last_scanned": "2025-01-18T10:05:00Z"
|
|
||||||
},
|
|
||||||
|
|
||||||
"_metadata": {
|
|
||||||
"initialized_by": "cli-explore-agent",
|
|
||||||
"analysis_timestamp": "2025-01-18T10:00:00Z",
|
|
||||||
"analysis_mode": "deep-scan",
|
|
||||||
"memory_scan_timestamp": "2025-01-18T10:05:00Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Phase 5: Discover Memory Resources
|
|
||||||
|
|
||||||
**Goal**: Scan and index available SKILL packages (memory command products) using agent delegation
|
|
||||||
|
|
||||||
**Invoke general-purpose agent** to discover and catalog all memory products:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
Task(
|
|
||||||
subagent_type="general-purpose",
|
|
||||||
description="Discover memory resources",
|
|
||||||
prompt=`
|
|
||||||
Discover and index all memory command products: SKILL packages, documentation, and CLAUDE.md files.
|
|
||||||
|
|
||||||
## Discovery Scope
|
|
||||||
1. **SKILL Packages** (.claude/skills/) - Generated by /memory:skill-memory, /memory:tech-research, etc.
|
|
||||||
2. **Documentation** (.workflow/docs/) - Generated by /memory:docs
|
|
||||||
3. **Module Docs** (**/CLAUDE.md) - Generated by /memory:update-full, /memory:update-related
|
|
||||||
|
|
||||||
## Discovery Tasks
|
|
||||||
|
|
||||||
### 1. Scan SKILL Packages
|
|
||||||
- List all directories in .claude/skills/
|
|
||||||
- For each: extract name, classify type, record path
|
|
||||||
- Types: workflow-progress | codemap-* | style-* | tech_stacks | project_docs
|
|
||||||
|
|
||||||
### 2. Scan Documentation
|
|
||||||
- List directories in .workflow/docs/
|
|
||||||
- For each project: name, path, check README.md, ARCHITECTURE.md existence
|
|
||||||
|
|
||||||
### 3. Scan CLAUDE.md Files
|
|
||||||
- Find all **/CLAUDE.md (exclude: node_modules, .git, dist, build)
|
|
||||||
- Return path list only
|
|
||||||
|
|
||||||
### 4. Identify Gaps
|
|
||||||
- No project SKILL? → "project_skill"
|
|
||||||
- No documentation? → "documentation"
|
|
||||||
- Missing tech stack SKILL? → "tech_stack"
|
|
||||||
- No workflow-progress? → "workflow_history"
|
|
||||||
- <10% modules have CLAUDE.md? → "module_docs_low_coverage"
|
|
||||||
|
|
||||||
### 5. Return JSON:
|
|
||||||
{
|
|
||||||
"skills": [
|
|
||||||
{"name": "claude_dms3", "type": "project_docs", "path": ".claude/skills/claude_dms3"},
|
|
||||||
{"name": "workflow-progress", "type": "workflow_progress", "path": ".claude/skills/workflow-progress"}
|
|
||||||
],
|
|
||||||
"documentation": [
|
|
||||||
{
|
|
||||||
"name": "my_project",
|
|
||||||
"path": ".workflow/docs/my_project",
|
|
||||||
"has_readme": true,
|
|
||||||
"has_architecture": true
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"module_docs": [
|
|
||||||
"src/core/CLAUDE.md",
|
|
||||||
"lib/utils/CLAUDE.md"
|
|
||||||
],
|
|
||||||
"gaps": ["tech_stack", "module_docs_low_coverage"]
|
|
||||||
}
|
|
||||||
|
|
||||||
## Context
|
|
||||||
- Project tech stack: ${JSON.stringify(analysis.technology_stack)}
|
|
||||||
- Check .workflow/.archives for session history
|
|
||||||
- If directories missing, return empty state with recommendations
|
|
||||||
`
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Agent Output**: JSON structure with skills, documentation, module_docs, and gaps
|
|
||||||
|
|
||||||
**Update project.json**:
|
|
||||||
```javascript
|
|
||||||
const memoryDiscovery = JSON.parse(agentOutput);
|
|
||||||
|
|
||||||
projectMeta.memory_resources = {
|
|
||||||
...memoryDiscovery,
|
|
||||||
last_scanned: new Date().toISOString()
|
|
||||||
};
|
|
||||||
|
|
||||||
Write('.workflow/project.json', JSON.stringify(projectMeta, null, 2));
|
|
||||||
```
|
|
||||||
|
|
||||||
**Output Summary**:
|
|
||||||
```
|
|
||||||
Memory Resources Indexed:
|
|
||||||
- SKILL Packages: ${skills.length}
|
|
||||||
- Documentation: ${documentation.length} project(s)
|
|
||||||
- Module Docs: ${module_docs.length} file(s)
|
|
||||||
- Gaps: ${gaps.join(', ') || 'none'}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Regeneration Behavior
|
|
||||||
|
|
||||||
When using `--regenerate` flag:
|
|
||||||
|
|
||||||
1. **Backup existing file**:
|
|
||||||
```bash
|
|
||||||
bash(cp .workflow/project.json .workflow/project.json.backup)
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Preserve features array**:
|
|
||||||
```javascript
|
|
||||||
const existingMeta = JSON.parse(Read('.workflow/project.json'));
|
|
||||||
const preservedFeatures = existingMeta.features || [];
|
|
||||||
const preservedStats = existingMeta.statistics || {};
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Re-run cli-explore-agent analysis**
|
|
||||||
|
|
||||||
4. **Re-run memory discovery (Phase 5)**
|
|
||||||
|
|
||||||
5. **Merge preserved data with new analysis**:
|
|
||||||
```javascript
|
|
||||||
const newProjectMeta = {
|
|
||||||
...analysisResults,
|
|
||||||
features: preservedFeatures, // Keep existing features
|
|
||||||
statistics: preservedStats // Keep statistics
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
6. **Output**:
|
|
||||||
```
|
|
||||||
✓ Project analysis regenerated
|
|
||||||
Backup saved: .workflow/project.json.backup
|
|
||||||
|
|
||||||
Updated:
|
|
||||||
- Technology stack analysis
|
|
||||||
- Architecture overview
|
|
||||||
- Key components discovery
|
|
||||||
- Memory resources index
|
|
||||||
|
|
||||||
Preserved:
|
|
||||||
- ${preservedFeatures.length} existing features
|
|
||||||
- Session statistics
|
|
||||||
```
|
|
||||||
|
|
||||||
## Error Handling
|
## Error Handling
|
||||||
|
|
||||||
### Agent Failure
|
**Agent Failure**: Fall back to basic initialization with placeholder overview
|
||||||
```
|
**Missing Tools**: Agent uses Qwen fallback or bash-only
|
||||||
If cli-explore-agent fails:
|
**Empty Project**: Create minimal JSON with all gaps identified
|
||||||
1. Fall back to basic initialization
|
|
||||||
2. Use get_modules_by_depth.sh for structure
|
|
||||||
3. Create minimal project.json with placeholder overview
|
|
||||||
4. Log warning: "Project initialized with basic analysis. Run /workflow:init --regenerate for full analysis"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Missing Tools
|
|
||||||
```
|
|
||||||
If Gemini CLI unavailable:
|
|
||||||
1. Agent uses Qwen fallback
|
|
||||||
2. If both fail, use bash-only analysis
|
|
||||||
3. Mark in _metadata: "analysis_mode": "bash-fallback"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Invalid Project Root
|
|
||||||
```
|
|
||||||
If not in git repo and empty directory:
|
|
||||||
1. Warn user: "Empty project detected"
|
|
||||||
2. Create minimal project.json
|
|
||||||
3. Suggest: "Add code files and run /workflow:init --regenerate"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Memory Discovery Failures
|
|
||||||
|
|
||||||
**Missing Directories**:
|
|
||||||
```
|
|
||||||
If .claude/skills, .workflow/docs, or CLAUDE.md files not found:
|
|
||||||
1. Return empty state for that category
|
|
||||||
2. Mark in gaps.missing array
|
|
||||||
3. Continue initialization
|
|
||||||
```
|
|
||||||
|
|
||||||
**Metadata Read Failures**:
|
|
||||||
```
|
|
||||||
If SKILL.md files are unreadable:
|
|
||||||
1. Include SKILL with basic info: name (from directory), type (inferred), path
|
|
||||||
2. Log warning: "SKILL package {name} has invalid metadata"
|
|
||||||
3. Continue with other SKILLs
|
|
||||||
```
|
|
||||||
|
|
||||||
**Coverage Check Failures**:
|
|
||||||
```
|
|
||||||
If unable to determine module doc coverage:
|
|
||||||
1. Skip adding "module_docs_low_coverage" to gaps
|
|
||||||
2. Continue with other gap checks
|
|
||||||
```
|
|
||||||
|
|
||||||
**Default Empty State**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"memory_resources": {
|
|
||||||
"skills": [],
|
|
||||||
"documentation": [],
|
|
||||||
"module_docs": [],
|
|
||||||
"gaps": ["project_skill", "documentation", "tech_stack", "workflow_history", "module_docs"],
|
|
||||||
"last_scanned": "ISO_TIMESTAMP"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|||||||
321
.claude/workflows/cli-templates/schemas/project-json-schema.json
Normal file
321
.claude/workflows/cli-templates/schemas/project-json-schema.json
Normal file
@@ -0,0 +1,321 @@
|
|||||||
|
{
|
||||||
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||||
|
"title": "Project Metadata Schema",
|
||||||
|
"description": "Workflow initialization metadata for project-level context",
|
||||||
|
"type": "object",
|
||||||
|
"required": [
|
||||||
|
"project_name",
|
||||||
|
"initialized_at",
|
||||||
|
"overview",
|
||||||
|
"features",
|
||||||
|
"statistics",
|
||||||
|
"memory_resources",
|
||||||
|
"_metadata"
|
||||||
|
],
|
||||||
|
"properties": {
|
||||||
|
"project_name": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Project name extracted from git repo or directory"
|
||||||
|
},
|
||||||
|
"initialized_at": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "date-time",
|
||||||
|
"description": "ISO 8601 timestamp of initialization"
|
||||||
|
},
|
||||||
|
"overview": {
|
||||||
|
"type": "object",
|
||||||
|
"required": [
|
||||||
|
"description",
|
||||||
|
"technology_stack",
|
||||||
|
"architecture",
|
||||||
|
"key_components",
|
||||||
|
"entry_points",
|
||||||
|
"metrics"
|
||||||
|
],
|
||||||
|
"properties": {
|
||||||
|
"description": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Brief project description (e.g., 'TypeScript web application with React frontend')"
|
||||||
|
},
|
||||||
|
"technology_stack": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["languages", "frameworks", "build_tools", "test_frameworks"],
|
||||||
|
"properties": {
|
||||||
|
"languages": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["name", "file_count", "primary"],
|
||||||
|
"properties": {
|
||||||
|
"name": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Language name (e.g., TypeScript, Python)"
|
||||||
|
},
|
||||||
|
"file_count": {
|
||||||
|
"type": "integer",
|
||||||
|
"description": "Number of source files in this language"
|
||||||
|
},
|
||||||
|
"primary": {
|
||||||
|
"type": "boolean",
|
||||||
|
"description": "True if this is the primary language"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"frameworks": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "Detected frameworks (React, Express, Django, etc.)"
|
||||||
|
},
|
||||||
|
"build_tools": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "Build tools and package managers (npm, cargo, maven, etc.)"
|
||||||
|
},
|
||||||
|
"test_frameworks": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "Testing frameworks (jest, pytest, go test, etc.)"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"architecture": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["style", "layers", "patterns"],
|
||||||
|
"properties": {
|
||||||
|
"style": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Architecture style (MVC, microservices, layered, etc.)"
|
||||||
|
},
|
||||||
|
"layers": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "Architectural layers (presentation, business-logic, data-access)"
|
||||||
|
},
|
||||||
|
"patterns": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "Design patterns (Repository, Factory, Singleton, etc.)"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"key_components": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["name", "path", "description", "importance"],
|
||||||
|
"properties": {
|
||||||
|
"name": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Component name"
|
||||||
|
},
|
||||||
|
"path": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Relative path to component directory"
|
||||||
|
},
|
||||||
|
"description": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Brief description of component functionality"
|
||||||
|
},
|
||||||
|
"importance": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["high", "medium", "low"],
|
||||||
|
"description": "Component importance level"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"description": "5-10 core modules/components"
|
||||||
|
},
|
||||||
|
"entry_points": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["main", "cli_commands", "api_endpoints"],
|
||||||
|
"properties": {
|
||||||
|
"main": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Primary application entry point (index.ts, main.py, etc.)"
|
||||||
|
},
|
||||||
|
"cli_commands": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "Available CLI commands (npm start, make build, etc.)"
|
||||||
|
},
|
||||||
|
"api_endpoints": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "HTTP/REST/GraphQL endpoints (if applicable)"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"metrics": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["total_files", "lines_of_code", "module_count", "complexity"],
|
||||||
|
"properties": {
|
||||||
|
"total_files": {
|
||||||
|
"type": "integer",
|
||||||
|
"description": "Total source code files"
|
||||||
|
},
|
||||||
|
"lines_of_code": {
|
||||||
|
"type": "integer",
|
||||||
|
"description": "Estimated total lines of code"
|
||||||
|
},
|
||||||
|
"module_count": {
|
||||||
|
"type": "integer",
|
||||||
|
"description": "Number of top-level modules/packages"
|
||||||
|
},
|
||||||
|
"complexity": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["low", "medium", "high"],
|
||||||
|
"description": "Overall project complexity rating"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"features": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["session_id", "title", "completed_at", "tags"],
|
||||||
|
"properties": {
|
||||||
|
"session_id": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "WFS session identifier"
|
||||||
|
},
|
||||||
|
"title": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Feature title/description"
|
||||||
|
},
|
||||||
|
"completed_at": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "date-time",
|
||||||
|
"description": "ISO 8601 timestamp of completion"
|
||||||
|
},
|
||||||
|
"tags": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "Feature tags for categorization"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"description": "Completed workflow features (populated by /workflow:session:complete)"
|
||||||
|
},
|
||||||
|
"statistics": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["total_features", "total_sessions", "last_updated"],
|
||||||
|
"properties": {
|
||||||
|
"total_features": {
|
||||||
|
"type": "integer",
|
||||||
|
"description": "Count of completed features"
|
||||||
|
},
|
||||||
|
"total_sessions": {
|
||||||
|
"type": "integer",
|
||||||
|
"description": "Count of workflow sessions"
|
||||||
|
},
|
||||||
|
"last_updated": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "date-time",
|
||||||
|
"description": "ISO 8601 timestamp of last update"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"memory_resources": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["skills", "documentation", "module_docs", "gaps", "last_scanned"],
|
||||||
|
"properties": {
|
||||||
|
"skills": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["name", "type", "path"],
|
||||||
|
"properties": {
|
||||||
|
"name": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "SKILL package name"
|
||||||
|
},
|
||||||
|
"type": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["workflow_progress", "project_docs", "tech_stacks", "codemap", "style"],
|
||||||
|
"description": "SKILL package type"
|
||||||
|
},
|
||||||
|
"path": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Relative path to SKILL package directory"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"description": "SKILL packages generated by /memory:* commands"
|
||||||
|
},
|
||||||
|
"documentation": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["name", "path", "has_readme", "has_architecture"],
|
||||||
|
"properties": {
|
||||||
|
"name": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Documentation project name"
|
||||||
|
},
|
||||||
|
"path": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Path to documentation directory"
|
||||||
|
},
|
||||||
|
"has_readme": {
|
||||||
|
"type": "boolean",
|
||||||
|
"description": "README.md exists"
|
||||||
|
},
|
||||||
|
"has_architecture": {
|
||||||
|
"type": "boolean",
|
||||||
|
"description": "ARCHITECTURE.md exists"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"description": "Documentation generated by /memory:docs"
|
||||||
|
},
|
||||||
|
"module_docs": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {"type": "string"},
|
||||||
|
"description": "Paths to CLAUDE.md files generated by /memory:update-*"
|
||||||
|
},
|
||||||
|
"gaps": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": [
|
||||||
|
"project_skill",
|
||||||
|
"documentation",
|
||||||
|
"tech_stack",
|
||||||
|
"workflow_history",
|
||||||
|
"module_docs_low_coverage"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"description": "Missing memory resources"
|
||||||
|
},
|
||||||
|
"last_scanned": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "date-time",
|
||||||
|
"description": "ISO 8601 timestamp of last memory scan"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"_metadata": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["initialized_by", "analysis_timestamp", "analysis_mode"],
|
||||||
|
"properties": {
|
||||||
|
"initialized_by": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Agent or tool that performed initialization"
|
||||||
|
},
|
||||||
|
"analysis_timestamp": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "date-time",
|
||||||
|
"description": "ISO 8601 timestamp of analysis"
|
||||||
|
},
|
||||||
|
"analysis_mode": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["deep-scan", "quick-scan", "bash-fallback"],
|
||||||
|
"description": "Analysis mode used"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user