refactor(workflow): remove all .active marker file references and sync documentation

Core Changes (10 files): - commands: cli/execute.md, memory/docs.md, workflow/review.md, workflow/brainstorm/*.md - agents: cli-execution-agent.md - workflows: task-core.md, workflow-architecture.md Transformations: - Removed all .active-* marker file operations (touch/rm/find) - Updated session discovery to directory-based (.workflow/sessions/) - Updated directory structure examples to show sessions/ subdirectory - Replaced marker-based state with location-based state Reference Documentation (57 files): - Auto-synced via analyze_commands.py script - Includes all core file changes - Updated command indexes (all-commands.json, by-category.json, etc.) Migration complete: 100% .active marker references removed Session state now determined by directory location only
2026-02-12 02:37:45 +08:00 · 2025-11-19 20:24:14 +08:00
parent bc5ddb3670
commit 487b359266
71 changed files with 3742 additions and 4069 deletions
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md
@@ -3,8 +3,8 @@ name: conflict-resolution
 description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
 argument-hint: "--session WFS-session-id --context path/to/context-package.json"
 examples:
-  - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
-  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
+  - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/sessions/WFS-auth/.process/context-package.json
+  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/sessions/WFS-payment/.process/context-package.json
 ---

 # Conflict Resolution Command
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md
@@ -71,9 +71,10 @@ You are executing as context-search-agent (.claude/agents/context-search-agent.m
 Execute complete context-search-agent workflow for implementation planning:

 ### Phase 1: Initialization & Pre-Analysis
-1. **Detection**: Check for existing context-package (early exit if valid)
-2. **Foundation**: Initialize code-index, get project structure, load docs
-3. **Analysis**: Extract keywords, determine scope, classify complexity
+1. **Project State Loading**: Read and parse `.workflow/project.json`. Use its `overview` section as the foundational `project_context`. This is your primary source for architecture, tech stack, and key components. If file doesn't exist, proceed with fresh analysis.
+2. **Detection**: Check for existing context-package (early exit if valid)
+3. **Foundation**: Initialize code-index, get project structure, load docs
+4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state

 ### Phase 2: Multi-Source Context Discovery
 Execute all 4 discovery tracks:
@@ -84,16 +85,17 @@ Execute all 4 discovery tracks:

 ### Phase 3: Synthesis, Assessment & Packaging
 1. Apply relevance scoring and build dependency graph
-2. Synthesize 4-source data (archive > docs > code > web)
-3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
-4. Perform conflict detection with risk assessment
-5. **Inject historical conflicts** from archive analysis into conflict_detection
-6. Generate and validate context-package.json
+2. **Synthesize 4-source data**: Merge findings from all sources (archive > docs > code > web). **Prioritize the context from `project.json`** for architecture and tech stack unless code analysis reveals it's outdated.
+3. **Populate `project_context`**: Directly use the `overview` from `project.json` to fill the `project_context` section of the output `context-package.json`. Include technology_stack, architecture, key_components, and entry_points.
+4. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+5. Perform conflict detection with risk assessment
+6. **Inject historical conflicts** from archive analysis into conflict_detection
+7. Generate and validate context-package.json

 ## Output Requirements
 Complete context-package.json with:
 - **metadata**: task_description, keywords, complexity, tech_stack, session_id
- **project_context**: architecture_patterns, coding_conventions, tech_stack
+- **project_context**: architecture_patterns, coding_conventions, tech_stack (sourced from `project.json` overview)
 - **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
 - **dependencies**: {internal[], external[]} with dependency graph
 - **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
@@ -139,7 +141,7 @@ Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json`

 **Key Sections**:
 - **metadata**: Session info, keywords, complexity, tech stack
- **project_context**: Architecture patterns, conventions, tech stack
+- **project_context**: Architecture patterns, conventions, tech stack (populated from `project.json` overview)
 - **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
 - **dependencies**: Internal and external dependency graphs
 - **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
@@ -154,7 +156,7 @@ The context-search-agent MUST perform historical archive analysis as Track 1 in
 **Step 1: Check for Archive Manifest**
 ```bash
 # Check if archive manifest exists
-if [[ -f .workflow/.archives/manifest.json ]]; then
+if [[ -f .workflow/archives/manifest.json ]]; then
  # Manifest available for querying
 fi
 ```
@@ -233,7 +235,7 @@ if (historicalConflicts.length > 0 && currentRisk === "low") {
 ### Archive Query Algorithm

 ```markdown
-1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
+1. IF .workflow/archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
 2. IF manifest exists:
   a. Load manifest.json
   b. Extract keywords from task_description (nouns, verbs, technical terms)
@@ -250,33 +252,10 @@ if (historicalConflicts.length > 0 && currentRisk === "low") {
 3. Continue to Track 2 (reference documentation)
 ```

-## Usage Examples
-
-### Basic Usage
-```bash
-/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
-```
-## Success Criteria
-
- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
- ✅ Contains >80% relevant files based on task keywords
- ✅ Execution completes within 2 minutes
- ✅ All required schema fields present and valid
- ✅ Conflict risk accurately assessed
- ✅ Agent reports completion with statistics
-
-## Error Handling
-
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Package validation failed | Invalid session_id in existing package | Re-run agent to regenerate |
-| Agent execution timeout | Large codebase or slow MCP | Increase timeout, check code-index status |
-| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
-| File count exceeds limit | Too many relevant files | Agent should auto-prioritize top 50 by relevance |
-
 ## Notes

 - **Detection-first**: Always check for existing package before invoking agent
+- **Project.json integration**: Agent reads `.workflow/project.json` as primary source for project context, avoiding redundant analysis
 - **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
 - **No redundancy**: This command is a thin orchestrator, all logic in agent
 - **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md
@@ -231,13 +231,13 @@ const agentContext = {
  // Use memory if available, else load
  session_metadata: memory.has("workflow-session.json")
    ? memory.get("workflow-session.json")
-    : Read(.workflow/WFS-[id]/workflow-session.json),
+    : Read(.workflow/sessions/WFS-[id]/workflow-session.json),

-  context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
+  context_package_path: ".workflow/sessions/WFS-[id]/.process/context-package.json",

  context_package: memory.has("context-package.json")
    ? memory.get("context-package.json")
-    : Read(".workflow/WFS-[id]/.process/context-package.json"),
+    : Read(".workflow/sessions/WFS-[id]/.process/context-package.json"),

  // Extract brainstorm artifacts from context package
  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md
@@ -338,19 +338,19 @@ const agentContext = {
  // Use memory if available, else load
  session_metadata: memory.has("workflow-session.json")
    ? memory.get("workflow-session.json")
-    : Read(.workflow/WFS-[id]/workflow-session.json),
+    : Read(.workflow/sessions/WFS-[id]/workflow-session.json),

-  context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
+  context_package_path: ".workflow/sessions/WFS-[id]/.process/context-package.json",

  context_package: memory.has("context-package.json")
    ? memory.get("context-package.json")
-    : Read(".workflow/WFS-[id]/.process/context-package.json"),
+    : Read(".workflow/sessions/WFS-[id]/.process/context-package.json"),

-  test_context_package_path: ".workflow/WFS-[id]/.process/test-context-package.json",
+  test_context_package_path: ".workflow/sessions/WFS-[id]/.process/test-context-package.json",

  test_context_package: memory.has("test-context-package.json")
    ? memory.get("test-context-package.json")
-    : Read(".workflow/WFS-[id]/.process/test-context-package.json"),
+    : Read(".workflow/sessions/WFS-[id]/.process/test-context-package.json"),

  // Extract brainstorm artifacts from context package
  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md
@@ -224,7 +224,7 @@ Each task JSON embeds all necessary context, artifacts, and execution steps usin
 - `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks)
 - `title`: Descriptive task name
 - `status`: Task state (`pending|active|completed|blocked|container`)
- `context_package_path`: Path to context package (`.workflow/WFS-[session]/.process/context-package.json`)
+- `context_package_path`: Path to context package (`.workflow/sessions/WFS-[session]/.process/context-package.json`)
 - `meta`: Task metadata
 - `context`: Task-specific context and requirements
 - `flow_control`: Execution steps and workflow
@@ -269,7 +269,7 @@ Each task JSON embeds all necessary context, artifacts, and execution steps usin
  "id": "IMPL-1",
  "title": "Implement feature X with Y components",
  "status": "pending",
-  "context_package_path": ".workflow/WFS-session/.process/context-package.json",
+  "context_package_path": ".workflow/sessions/WFS-session/.process/context-package.json",
  "meta": {
    "type": "feature",
    "agent": "@code-developer",
@@ -291,7 +291,7 @@ Each task JSON embeds all necessary context, artifacts, and execution steps usin
    "depends_on": [],
    "artifacts": [
      {
-        "path": ".workflow/WFS-session/.brainstorming/system-architect/analysis.md",
+        "path": ".workflow/sessions/WFS-session/.brainstorming/system-architect/analysis.md",
        "priority": "highest",
        "usage": "Architecture decisions and API specifications"
      }
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md
@@ -272,6 +272,6 @@ Function Coverage: 91%

 Overall Compliance: 93/100

-Detailed report: .workflow/WFS-auth/.process/tdd-cycle-report.md
+Detailed report: .workflow/sessions/WFS-auth/.process/tdd-cycle-report.md
 ```

--- a/.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md
@@ -3,7 +3,7 @@ name: test-concept-enhanced
 description: Analyze test requirements and generate test generation strategy using Gemini with test-context package
 argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
 examples:
-  - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json
+  - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/sessions/WFS-test-auth/.process/test-context-package.json
 ---

 # Test Concept Enhanced Command
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md
@@ -273,19 +273,19 @@ const agentContext = {
  // Use memory if available, else load
  session_metadata: memory.has("workflow-session.json")
    ? memory.get("workflow-session.json")
-    : Read(.workflow/WFS-test-[id]/workflow-session.json),
+    : Read(.workflow/sessions/WFS-test-[id]/workflow-session.json),

-  test_analysis_results_path: ".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md",
+  test_analysis_results_path: ".workflow/sessions/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md",

  test_analysis_results: memory.has("TEST_ANALYSIS_RESULTS.md")
    ? memory.get("TEST_ANALYSIS_RESULTS.md")
-    : Read(".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),
+    : Read(".workflow/sessions/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),

-  test_context_package_path: ".workflow/WFS-test-[id]/.process/test-context-package.json",
+  test_context_package_path: ".workflow/sessions/WFS-test-[id]/.process/test-context-package.json",

  test_context_package: memory.has("test-context-package.json")
    ? memory.get("test-context-package.json")
-    : Read(".workflow/WFS-test-[id]/.process/test-context-package.json"),
+    : Read(".workflow/sessions/WFS-test-[id]/.process/test-context-package.json"),

  // Load source session summaries if exists
  source_session_id: session_metadata.source_session_id || null,
@@ -312,7 +312,7 @@ This section provides quick reference for test task JSON structure. For complete

 ## Output Files Structure
 ```
-.workflow/WFS-test-[session]/
+.workflow/sessions/WFS-test-[session]/
 ├── workflow-session.json           # Test session metadata
 ├── IMPL_PLAN.md                    # Test validation plan
 ├── TODO_LIST.md                    # Progress tracking