claude-code-workflow 7.2.27 → 7.2.28

package/.ccw/specs/architecture-constraints.md

@@ -14,3 +14,8 @@ keywords: [architecture, constraint, schema, compatibility, portability, design,
 
 - [compatibility] When enhancing existing schemas, use optional fields and additionalProperties rather than creating new schemas. Avoid breaking changes.
 - [portability] Use relative paths for cross-artifact navigation to ensure portability across different environments and installations.
+
+## Skill Design
+
+- [decision:skills] All skills must follow Completion Status Protocol (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT) defined in SKILL-DESIGN-SPEC.md sections 13-14. New skills created via skill-generator auto-include the protocol reference. (2026-03-29)
+- [decision:hooks] Hook safety guardrails use TypeScript HookTemplate pattern (not standalone bash scripts) for integration with CCW hook endpoint system. Templates: careful-destructive-guard, freeze-edit-boundary. (2026-03-29)

package/.claude/skills/_shared/SKILL-DESIGN-SPEC.md

@@ -18,6 +18,8 @@
 10. [质量控制规范](#10-质量控制规范)
 11. [最佳实践清单](#11-最佳实践清单)
 12. [示例模板](#12-示例模板)
+13. [Completion Status Protocol](#13-completion-status-protocol)
+14. [Escalation Protocol](#14-escalation-protocol)
 
 ---
 
@@ -665,6 +667,144 @@ Generate XXX through multi-phase analysis.
 
 ---
 
+## 13. Completion Status Protocol
+
+### 13.1 Status Definitions
+
+Every Skill execution MUST terminate with one of the following four statuses:
+
+| Status | Exit Code | Definition |
+|--------|-----------|------------|
+| **DONE** | 0 | All acceptance criteria met, outputs generated successfully |
+| **DONE_WITH_CONCERNS** | 0 | Completed but with warnings or non-blocking issues |
+| **BLOCKED** | 1 | Cannot proceed, requires external action or resource |
+| **NEEDS_CONTEXT** | 2 | Missing information needed to make a decision |
+
+### 13.2 When to Use
+
+| Status | Use When |
+|--------|----------|
+| **DONE** | All phases completed, quality gates passed, outputs validated |
+| **DONE_WITH_CONCERNS** | Core task completed but: deprecation warnings found, quality score 60-79%, non-critical checks failed, partial data used as fallback |
+| **BLOCKED** | Required file/service unavailable, dependency not installed, permission denied, prerequisite task not completed |
+| **NEEDS_CONTEXT** | Ambiguous user requirement, multiple valid interpretations, missing configuration value, unclear scope boundary |
+
+### 13.3 Output Format
+
+Each status MUST use the following structured output at the end of Skill execution:
+
+```
+## STATUS: {DONE|DONE_WITH_CONCERNS|BLOCKED|NEEDS_CONTEXT}
+
+**Summary**: {one-line description of outcome}
+
+### Details
+{status-specific content — see below}
+
+### Outputs
+- {list of files created/modified, if any}
+```
+
+**DONE details**:
+```
+### Details
+- Phases completed: {N}/{N}
+- Quality score: {score}%
+- Key outputs: {list of primary deliverables}
+```
+
+**DONE_WITH_CONCERNS details**:
+```
+### Details
+- Phases completed: {N}/{N}
+- Concerns:
+  1. {concern description} — Impact: {low|medium} — Suggested fix: {action}
+  2. ...
+```
+
+**BLOCKED details**:
+```
+### Details
+- Blocked at: Phase {N}, Step {M}
+- Blocker: {specific description of what is blocking}
+- Need: {specific action or resource required to unblock}
+- Attempted: {what was tried before declaring blocked}
+```
+
+**NEEDS_CONTEXT details**:
+```
+### Details
+- Paused at: Phase {N}, Step {M}
+- Questions:
+  1. {specific question requiring user/caller input}
+  2. ...
+- Context available: {what is already known}
+- Impact: {what cannot proceed without answers}
+```
+
+---
+
+## 14. Escalation Protocol
+
+### 14.1 Three-Strike Rule
+
+When a Skill encounters consecutive failures on the **same step**, the following escalation applies:
+
+| Strike | Action |
+|--------|--------|
+| 1st failure | Log error, retry with adjusted approach |
+| 2nd failure | Log error, try alternative strategy |
+| 3rd failure | **STOP execution immediately**, output diagnostic dump, request human intervention |
+
+### 14.2 Failure Tracking
+
+Track failures per step, not globally. A success on any step resets that step's failure counter.
+
+```
+Step failure counter:
+  Phase 2, Step 3: [fail] [fail] [STOP]  → escalate
+  Phase 2, Step 4: [fail] [success]       → counter reset, continue
+```
+
+### 14.3 Diagnostic Dump Format
+
+On the 3rd consecutive failure, output the following diagnostic block:
+
+```
+## ESCALATION: 3-Strike Limit Reached
+
+### Failed Step
+- Phase: {phase_number} — {phase_name}
+- Step: {step_number} — {step_name}
+
+### Error History
+1. Attempt 1: {error message or description}
+   Strategy: {what was tried}
+2. Attempt 2: {error message or description}
+   Strategy: {alternative approach tried}
+3. Attempt 3: {error message or description}
+   Strategy: {final approach tried}
+
+### Current State
+- Last successful phase/step: {phase.step}
+- Files generated so far: {list}
+- Files touched in failed attempts: {list}
+
+### Diagnosis
+- Likely root cause: {assessment}
+- Suggested human action: {specific recommendation}
+```
+
+### 14.4 Post-Escalation Behavior
+
+After outputting the diagnostic dump:
+1. Set Skill status to **BLOCKED** (see Section 13)
+2. Do NOT attempt further retries
+3. Preserve all intermediate outputs for debugging
+4. Wait for human intervention before resuming
+
+---
+
 ## 附录 A: 设计对比
 
 | 设计点 | software-manual | copyright-docs |

package/.claude/skills/investigate/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: investigate
+description: Systematic debugging with Iron Law methodology. 5-phase investigation from evidence collection to verified fix. Triggers on "investigate", "debug", "root cause".
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Investigate
+
+Systematic debugging skill that enforces the Iron Law: never fix without a confirmed root cause. Produces a structured debug report with full evidence chain, minimal fix, and regression test.
+
+## Iron Law Principle
+
+**No fix without confirmed root cause.** Every investigation follows a strict evidence chain:
+1. Reproduce the bug with concrete evidence
+2. Analyze patterns to assess scope
+3. Form and test hypotheses (max 3 strikes)
+4. Implement minimal fix ONLY after root cause is confirmed
+5. Verify fix and generate structured report
+
+Violation of the Iron Law (skipping to Phase 4 without Phase 3 confirmation) is prohibited.
+
+## Key Design Principles
+
+1. **Evidence-First**: Collect before theorizing. Logs, stack traces, and reproduction steps are mandatory inputs.
+2. **Minimal Fix**: Change only what is necessary. Refactoring is not debugging.
+3. **3-Strike Escalation**: If 3 consecutive hypothesis tests fail, STOP and escalate with a diagnostic dump.
+4. **Regression Coverage**: Every fix must include a test that fails without the fix and passes with it.
+5. **Structured Output**: All findings are recorded in machine-readable JSON for future reference.
+
+## Execution Flow
+
+```
+Phase 1: Root Cause Investigation
+  Reproduce bug, collect evidence (errors, logs, traces)
+  Use ccw cli --tool gemini --mode analysis for initial diagnosis
+  Output: investigation-report.json
+      |
+      v
+Phase 2: Pattern Analysis
+  Search codebase for similar patterns (same error, module, antipattern)
+  Assess scope: isolated vs systemic
+  Output: pattern-analysis section in report
+      |
+      v
+Phase 3: Hypothesis Testing
+  Form max 3 hypotheses from evidence
+  Test each with minimal read-only probes
+  3-strike rule: STOP and escalate on 3 consecutive failures
+  Output: confirmed root cause with evidence chain
+      |
+      v
+Phase 4: Implementation  [GATE: requires Phase 3 confirmed root cause]
+  Implement minimal fix
+  Add regression test
+  Verify fix resolves reproduction case
+      |
+      v
+Phase 5: Verification & Report
+  Run full test suite
+  Check for regressions
+  Generate structured debug report to .workflow/.debug/
+```
+
+## Directory Setup
+
+```bash
+mkdir -p .workflow/.debug
+```
+
+## Output Structure
+
+```
+.workflow/.debug/
+  debug-report-{YYYY-MM-DD}-{slug}.json    # Structured debug report
+```
+
+## Completion Status Protocol
+
+This skill follows the Completion Status Protocol defined in `_shared/SKILL-DESIGN-SPEC.md` sections 13-14.
+
+| Status | When |
+|--------|------|
+| **DONE** | Root cause confirmed, fix applied, regression test passes, no regressions |
+| **DONE_WITH_CONCERNS** | Fix applied but partial test coverage or minor warnings |
+| **BLOCKED** | Cannot reproduce bug, or 3-strike escalation triggered in Phase 3 |
+| **NEEDS_CONTEXT** | Missing reproduction steps, unclear error conditions |
+
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| [phases/01-root-cause-investigation.md](phases/01-root-cause-investigation.md) | Evidence collection and reproduction |
+| [phases/02-pattern-analysis.md](phases/02-pattern-analysis.md) | Codebase pattern search and scope assessment |
+| [phases/03-hypothesis-testing.md](phases/03-hypothesis-testing.md) | Hypothesis formation, testing, and 3-strike rule |
+| [phases/04-implementation.md](phases/04-implementation.md) | Minimal fix with Iron Law gate |
+| [phases/05-verification-report.md](phases/05-verification-report.md) | Test suite, regression check, report generation |
+| [specs/iron-law.md](specs/iron-law.md) | Iron Law rules definition |
+| [specs/debug-report-format.md](specs/debug-report-format.md) | Structured debug report JSON schema |
+
+## CLI Integration
+
+This skill leverages `ccw cli` for multi-model analysis at key points:
+
+| Phase | CLI Usage | Mode |
+|-------|-----------|------|
+| Phase 1 | Initial diagnosis from error evidence | `--mode analysis` |
+| Phase 2 | Cross-file pattern search | `--mode analysis` |
+| Phase 3 | Hypothesis validation assistance | `--mode analysis` |
+
+All CLI calls use `--mode analysis` (read-only). No write-mode CLI calls during investigation phases 1-3.

package/.claude/skills/investigate/phases/01-root-cause-investigation.md

@@ -0,0 +1,132 @@
+# Phase 1: Root Cause Investigation
+
+Reproduce the bug and collect all available evidence before forming any theories.
+
+## Objective
+
+- Reproduce the bug with concrete, observable symptoms
+- Collect all evidence: error messages, logs, stack traces, affected files
+- Establish a baseline understanding of what goes wrong and where
+- Use CLI analysis for initial diagnosis
+
+## Execution Steps
+
+### Step 1: Understand the Bug Report
+
+Parse the user's description to extract:
+- **Symptom**: What observable behavior is wrong?
+- **Expected**: What should happen instead?
+- **Context**: When/where does it occur? (specific input, environment, timing)
+
+```javascript
+const bugReport = {
+  symptom: "extracted from user description",
+  expected_behavior: "what should happen",
+  context: "when/where it occurs",
+  user_provided_files: ["files mentioned by user"],
+  user_provided_errors: ["error messages provided"]
+}
+```
+
+### Step 2: Reproduce the Bug
+
+Attempt to reproduce using the most direct method available:
+
+1. **Run the failing test** (if one exists):
+   ```bash
+   # Identify and run the specific failing test
+   ```
+
+2. **Run the failing command** (if CLI/script):
+   ```bash
+   # Execute the command that triggers the bug
+   ```
+
+3. **Read error-producing code path** (if reproduction requires complex setup):
+   - Use `Grep` to find the error message in source code
+   - Use `Read` to trace the code path that produces the error
+   - Document the theoretical reproduction path
+
+**If reproduction fails**: Document what was attempted. The investigation can continue with static analysis, but note this as a concern.
+
+### Step 3: Collect Evidence
+
+Gather all available evidence using project tools:
+
+```javascript
+// 1. Find error messages in source
+Grep({ pattern: "error message text", path: "src/" })
+
+// 2. Find related log output
+Grep({ pattern: "relevant log pattern", path: "." })
+
+// 3. Read stack trace files or test output
+Read({ file_path: "path/to/failing-test-output" })
+
+// 4. Identify affected files and modules
+Glob({ pattern: "**/*relevant-module*" })
+```
+
+### Step 4: Initial Diagnosis via CLI Analysis
+
+Use `ccw cli` for a broader diagnostic perspective:
+
+```bash
+ccw cli -p "PURPOSE: Diagnose root cause of bug from collected evidence
+TASK: Analyze error context | Trace data flow | Identify suspicious code patterns
+MODE: analysis
+CONTEXT: @{affected_files} | Evidence: {error_messages_and_traces}
+EXPECTED: Top 3 likely root causes ranked by evidence strength
+CONSTRAINTS: Read-only analysis | Focus on {affected_module}" \
+  --tool gemini --mode analysis
+```
+
+### Step 5: Write Investigation Report
+
+Generate `investigation-report.json` in memory (carried to next phase):
+
+```json
+{
+  "phase": 1,
+  "bug_description": "concise description of the bug",
+  "reproduction": {
+    "reproducible": true,
+    "steps": [
+      "step 1: ...",
+      "step 2: ...",
+      "step 3: observe error"
+    ],
+    "reproduction_method": "test|command|static_analysis"
+  },
+  "evidence": {
+    "error_messages": ["exact error text"],
+    "stack_traces": ["relevant stack trace"],
+    "affected_files": ["file1.ts", "file2.ts"],
+    "affected_modules": ["module-name"],
+    "log_output": ["relevant log lines"]
+  },
+  "initial_diagnosis": {
+    "cli_tool_used": "gemini",
+    "top_suspects": [
+      { "description": "suspect 1", "evidence_strength": "strong|moderate|weak", "files": [] }
+    ]
+  }
+}
+```
+
+## Output
+
+- **Data**: `investigation-report` (in-memory, passed to Phase 2)
+- **Format**: JSON structure as defined above
+
+## Quality Checks
+
+- [ ] Bug symptom clearly documented
+- [ ] Reproduction attempted (success or documented failure)
+- [ ] At least one piece of concrete evidence collected (error message, stack trace, or failing test)
+- [ ] Affected files identified
+- [ ] Initial diagnosis generated
+
+## Next Phase
+
+Proceed to [Phase 2: Pattern Analysis](02-pattern-analysis.md) with the investigation report.

package/.claude/skills/investigate/phases/02-pattern-analysis.md

@@ -0,0 +1,126 @@
+# Phase 2: Pattern Analysis
+
+Search for similar patterns in the codebase to determine if the bug is isolated or systemic.
+
+## Objective
+
+- Search for similar error patterns, antipatterns, or code smells across the codebase
+- Determine if the bug is an isolated incident or part of a systemic issue
+- Identify related code that may be affected by the same root cause
+- Refine the scope of the investigation
+
+## Execution Steps
+
+### Step 1: Search for Similar Error Patterns
+
+Look for the same error type or message elsewhere in the codebase:
+
+```javascript
+// Search for identical or similar error messages
+Grep({ pattern: "error_message_fragment", path: "src/", output_mode: "content", context: 3 })
+
+// Search for the same exception/error type
+Grep({ pattern: "ErrorClassName|error_code", path: "src/", output_mode: "files_with_matches" })
+
+// Search for similar error handling patterns
+Grep({ pattern: "catch.*{similar_pattern}", path: "src/", output_mode: "content" })
+```
+
+### Step 2: Search for Same Antipattern
+
+If the initial diagnosis suggests a coding antipattern, search for it globally:
+
+```javascript
+// Examples of antipattern searches:
+// Missing null checks
+Grep({ pattern: "variable\\.property", path: "src/", glob: "*.ts" })
+
+// Unchecked async operations
+Grep({ pattern: "async.*without.*await", path: "src/" })
+
+// Direct mutation of shared state
+Grep({ pattern: "shared_state_pattern", path: "src/" })
+```
+
+### Step 3: Module-Level Analysis
+
+Examine the affected module for structural issues:
+
+```javascript
+// List all files in the affected module
+Glob({ pattern: "src/affected-module/**/*" })
+
+// Check imports and dependencies
+Grep({ pattern: "import.*from.*affected-module", path: "src/" })
+
+// Check for circular dependencies or unusual patterns
+Grep({ pattern: "require.*affected-module", path: "src/" })
+```
+
+### Step 4: CLI Cross-File Pattern Analysis (Optional)
+
+For complex patterns that span multiple files, use CLI analysis:
+
+```bash
+ccw cli -p "PURPOSE: Identify all instances of antipattern across codebase; success = complete scope map
+TASK: Search for pattern '{antipattern_description}' | Map all occurrences | Assess systemic risk
+MODE: analysis
+CONTEXT: @src/**/*.{ext} | Bug in {module}, pattern: {pattern_description}
+EXPECTED: List of all files with same pattern, risk assessment per occurrence
+CONSTRAINTS: Focus on {antipattern} pattern only | Ignore test files for scope" \
+  --tool gemini --mode analysis
+```
+
+### Step 5: Scope Assessment
+
+Classify the bug scope based on findings:
+
+```json
+{
+  "phase": 2,
+  "pattern_analysis": {
+    "scope": "isolated|module-wide|systemic",
+    "similar_occurrences": [
+      {
+        "file": "path/to/file.ts",
+        "line": 42,
+        "pattern": "description of similar pattern",
+        "risk": "same_bug|potential_bug|safe"
+      }
+    ],
+    "total_occurrences": 1,
+    "affected_modules": ["module-name"],
+    "antipattern_identified": "description or null",
+    "scope_justification": "why this scope classification"
+  }
+}
+```
+
+**Scope Definitions**:
+- **isolated**: Bug exists in a single location, no similar patterns found
+- **module-wide**: Same pattern exists in multiple files within the same module
+- **systemic**: Pattern spans multiple modules, may require broader fix
+
+## Output
+
+- **Data**: `pattern-analysis` section added to investigation report (in-memory)
+- **Format**: JSON structure as defined above
+
+## Decision Point
+
+| Scope | Action |
+|-------|--------|
+| isolated | Proceed to Phase 3 with narrow focus |
+| module-wide | Proceed to Phase 3, note all occurrences for Phase 4 fix |
+| systemic | Proceed to Phase 3, but flag for potential multi-phase fix or separate tracking |
+
+## Quality Checks
+
+- [ ] At least 3 search queries executed against the codebase
+- [ ] Scope classified as isolated, module-wide, or systemic
+- [ ] Similar occurrences documented with file:line references
+- [ ] Scope justification provided with evidence
+
+## Next Phase
+
+Proceed to [Phase 3: Hypothesis Testing](03-hypothesis-testing.md) with the pattern analysis results.