feat: enhance search, ranking, reranker and CLI tooling across ccw and codex-lens

Major improvements to smart-search, chain-search cascade, ranking pipeline, reranker factory, CLI history store, codex-lens integration, and uv-manager. Simplify command-generator skill by inlining phases. Add comprehensive tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-19 18:58:47 +08:00 · 2026-03-16 20:35:08 +08:00
parent 1cd96b90e8
commit 5a4b18d9b1
73 changed files with 14684 additions and 2442 deletions
--- a/.claude/skills/command-generator/SKILL.md
+++ b/.claude/skills/command-generator/SKILL.md
@@ -1,190 +1,307 @@
 ---
 name: command-generator
 description: Command file generator - 5 phase workflow for creating Claude Code command files with YAML frontmatter. Generates .md command files for project or user scope. Triggers on "create command", "new command", "command generator".
-allowed-tools: Read, Write, Edit, Bash, Glob
+allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
 ---

-# Command Generator
+<purpose>
+Generate Claude Code command .md files with concrete, domain-specific content in GSD style. Produces command files at project-level (`.claude/commands/`) or user-level (`~/.claude/commands/`) with YAML frontmatter, XML semantic tags (`<purpose>`, `<process>`, `<step>`, `<error_codes>`, `<success_criteria>`), and actionable execution logic — NOT empty placeholders.

-CLI-based command file generator producing Claude Code command .md files through a structured 5-phase workflow. Supports both project-level (`.claude/commands/`) and user-level (`~/.claude/commands/`) command locations.
+Invoked when user requests "create command", "new command", or "command generator".
+</purpose>

-## Architecture Overview
+<required_reading>
+- @.claude/skills/command-generator/specs/command-design-spec.md
+- @.claude/skills/command-generator/templates/command-md.md
+</required_reading>
+
+<process>
+
+<step name="validate_params" priority="first">
+**Parse and validate all input parameters.**
+
+Extract from `$ARGUMENTS` or skill args:
+
+| Parameter | Required | Validation | Example |
+|-----------|----------|------------|---------|
+| `$SKILL_NAME` | Yes | `/^[a-z][a-z0-9-]*$/`, min 1 char | `deploy`, `create` |
+| `$DESCRIPTION` | Yes | min 10 chars | `"Deploy application to production"` |
+| `$LOCATION` | Yes | `"project"` or `"user"` | `project` |
+| `$GROUP` | No | `/^[a-z][a-z0-9-]*$/` or null | `issue`, `workflow` |
+| `$ARGUMENT_HINT` | No | any string or empty | `"<url> [--priority 1-5]"` |
+
+**Validation rules:**
+- Missing required param → Error with specific message (e.g., `"skillName is required"`)
+- Invalid `$SKILL_NAME` pattern → Error: `"skillName must be lowercase alphanumeric with hyphens, starting with a letter"`
+- Invalid `$LOCATION` → Error: `"location must be 'project' or 'user'"`
+- Invalid `$GROUP` pattern → Warning, continue
+
+**Normalize:** trim + lowercase for `$SKILL_NAME`, `$LOCATION`, `$GROUP`.
+</step>
+
+<step name="resolve_target_path">
+**Resolve target file path based on location and group.**
+
+Path mapping:
+
+| Location | Base Directory |
+|----------|---------------|
+| `project` | `.claude/commands` |
+| `user` | `~/.claude/commands` (expand `~` to `$HOME`) |
+
+Path construction:

 ```
-+-----------------------------------------------------------+
-|                    Command Generator                        |
-|                                                            |
-|  Input: skillName, description, location, [group], [hint]  |
-|                         |                                  |
-|  +-------------------------------------------------+      |
-|  |  Phase 1-5: Sequential Pipeline                 |      |
-|  |                                                 |      |
-|  |  [P1] --> [P2] --> [P3] --> [P4] --> [P5]      |      |
-|  |  Param   Target   Template  Content   File     |      |
-|  |  Valid   Path     Loading   Format    Gen      |      |
-|  +-------------------------------------------------+      |
-|                         |                                  |
-|  Output: {scope}/.claude/commands/{group}/{name}.md       |
-|                                                            |
-+-----------------------------------------------------------+
+If $GROUP:
+  $TARGET_DIR = {base}/{$GROUP}
+  $TARGET_PATH = {base}/{$GROUP}/{$SKILL_NAME}.md
+Else:
+  $TARGET_DIR = {base}
+  $TARGET_PATH = {base}/{$SKILL_NAME}.md
 ```

-## Key Design Principles
+Check if `$TARGET_PATH` already exists → store as `$FILE_EXISTS` (true/false).
+</step>

-1. **Single Responsibility**: Generates one command file per invocation
-2. **Scope Awareness**: Supports project and user-level command locations
-3. **Template-Driven**: Uses consistent template for all generated commands
-4. **Validation First**: Validates all required parameters before file operations
-5. **Non-Destructive**: Warns if command file already exists
+<step name="gather_requirements">
+**Gather domain-specific requirements to generate concrete content.**

+Infer the command's domain from `$SKILL_NAME`, `$DESCRIPTION`, and `$ARGUMENT_HINT`:
+
+| Signal | Extract |
+|--------|---------|
+| `$SKILL_NAME` | Action verb (deploy, create, analyze, sync) → step naming |
+| `$DESCRIPTION` | Domain keywords → execution logic, error scenarios |
+| `$ARGUMENT_HINT` | Flags/args → parse_input step details, validation rules |
+| `$GROUP` | Command family → related commands, shared patterns |
+
+**Determine command complexity:**
+
+| Complexity | Criteria | Steps to Generate |
+|------------|----------|-------------------|
+| Simple | Single action, no flags | 2-3 steps |
+| Standard | 1-2 flags, clear workflow | 3-4 steps |
+| Complex | Multiple flags, multi-phase | 4-6 steps |
+
+**If complexity is unclear**, ask user:
+
+```
+AskUserQuestion(
+  header: "Command Scope",
+  question: "What are the main execution steps for this command?",
+  options: [
+    { label: "Simple", description: "Single action: validate → execute → report" },
+    { label: "Standard", description: "Multi-step: parse → process → verify → report" },
+    { label: "Complex", description: "Full workflow: parse → explore → execute → verify → report" },
+    { label: "I'll describe", description: "Let me specify the steps" }
+  ]
+)
+```
+
+Store as `$COMMAND_STEPS`, `$ERROR_SCENARIOS`, `$SUCCESS_CONDITIONS`.
+</step>
+
+<step name="draft_content">
+**Generate concrete, domain-specific command content in GSD style.**
+
+This is the core generation step. Draft the COMPLETE command file — not a template with placeholders — using the gathered requirements.
+
+**YAML Frontmatter:**
+```yaml
 ---
-
-## Execution Flow
-
-```
-Phase 1: Parameter Validation
-   - Ref: phases/01-parameter-validation.md
-   - Validate: skillName (required), description (required), location (required)
-   - Optional: group, argumentHint
-   - Output: validated params object
-
-Phase 2: Target Path Resolution
-   - Ref: phases/02-target-path-resolution.md
-   - Resolve: location -> target commands directory
-   - Support: project (.claude/commands/) vs user (~/.claude/commands/)
-   - Handle: group subdirectory if provided
-   - Output: targetPath string
-
-Phase 3: Template Loading
-   - Ref: phases/03-template-loading.md
-   - Load: templates/command-md.md
-   - Template contains YAML frontmatter with placeholders
-   - Output: templateContent string
-
-Phase 4: Content Formatting
-   - Ref: phases/04-content-formatting.md
-   - Substitute: {{name}}, {{description}}, {{group}}, {{argumentHint}}
-   - Handle: optional fields (group, argumentHint)
-   - Output: formattedContent string
-
-Phase 5: File Generation
-   - Ref: phases/05-file-generation.md
-   - Check: file existence (warn if exists)
-   - Write: formatted content to target path
-   - Output: success confirmation with file path
-```
-
-## Usage Examples
-
-### Basic Command (Project Scope)
-```javascript
-Skill(skill="command-generator", args={
-  skillName: "deploy",
-  description: "Deploy application to production environment",
-  location: "project"
-})
-// Output: .claude/commands/deploy.md
-```
-
-### Grouped Command with Argument Hint
-```javascript
-Skill(skill="command-generator", args={
-  skillName: "create",
-  description: "Create new issue from GitHub URL or text",
-  location: "project",
-  group: "issue",
-  argumentHint: "[-y|--yes] <github-url | text-description> [--priority 1-5]"
-})
-// Output: .claude/commands/issue/create.md
-```
-
-### User-Level Command
-```javascript
-Skill(skill="command-generator", args={
-  skillName: "global-status",
-  description: "Show global Claude Code status",
-  location: "user"
-})
-// Output: ~/.claude/commands/global-status.md
-```
-
+name: $SKILL_NAME
+description: $DESCRIPTION
+argument-hint: $ARGUMENT_HINT  # only if provided
 ---
+```

-## Reference Documents by Phase
+**`<purpose>` section:** Write 2-3 sentences describing:
+- What the command does (action + target)
+- When it's invoked (trigger conditions)
+- What it produces (output artifacts or effects)

-### Phase 1: Parameter Validation
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/01-parameter-validation.md](phases/01-parameter-validation.md) | Validate required parameters | Phase 1 execution |
+**`<required_reading>` section:** Infer from domain:
+- If command reads config → `@.claude/CLAUDE.md` or relevant config files
+- If command modifies code → relevant source directories
+- If command is part of a group → other commands in the same group

-### Phase 2: Target Path Resolution
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/02-target-path-resolution.md](phases/02-target-path-resolution.md) | Resolve target directory | Phase 2 execution |
+**`<process>` section with `<step>` blocks:**

-### Phase 3: Template Loading
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/03-template-loading.md](phases/03-template-loading.md) | Load command template | Phase 3 execution |
-| [templates/command-md.md](templates/command-md.md) | Command file template | Template reference |
+For each step in `$COMMAND_STEPS`, generate a `<step name="snake_case">` block containing:

-### Phase 4: Content Formatting
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/04-content-formatting.md](phases/04-content-formatting.md) | Format content with params | Phase 4 execution |
+1. **`parse_input`** (always first, `priority="first"`):
+   - Parse `$ARGUMENTS` for flags and positional args derived from `$ARGUMENT_HINT`
+   - Include specific flag detection logic (e.g., `if arguments contain "--env"`)
+   - Include validation with specific error messages
+   - Include decision routing table if multiple modes exist

-### Phase 5: File Generation
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/05-file-generation.md](phases/05-file-generation.md) | Write final file | Phase 5 execution |
+2. **Domain-specific execution steps** (2-4 steps):
+   - Each step has a **bold action description**
+   - Include concrete shell commands, file operations, or tool calls
+   - Use `$UPPER_CASE` variables for user input, `${computed}` for derived values
+   - Include conditional logic with specific conditions (not generic)
+   - Reference actual file paths and tool names

-### Design Specifications
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [specs/command-design-spec.md](specs/command-design-spec.md) | Command design guidelines | Understanding best practices |
+3. **`report`** (always last):
+   - Format output with banner and status
+   - Include file paths, timestamps, next step suggestions

---
+**Shell Correctness Checklist (MANDATORY for every shell block):**

-## Output Structure
+| Rule | Wrong | Correct |
+|------|-------|---------|
+| Multi-line output | `echo "{ ... }"` (unquoted multi-line) | `cat <<'EOF' > file`...`EOF` (heredoc) |
+| Variable init | Use `$VAR` after conditional | `VAR="default"` BEFORE any conditional that sets it |
+| Error exit | `echo "Error: ..."` (no exit) | `echo "Error: ..." # (see code: E00X)` + `exit 1` |
+| Quoting | `$VAR` in commands | `"$VAR"` (double-quoted in all expansions) |
+| Exit on fail | Command chain without checks | `set -e` or explicit `|| { echo "Failed"; exit 1; }` |
+| Command from var | `$CMD --flag` (word-split fragile) | `eval "$CMD" --flag` or use array: `cmd=(...); "${cmd[@]}"` |
+| Prerequisites | Implicit `git`/`curl` usage | Declare in `<prerequisites>` section |

-### Generated Command File
+**Golden Example — a correctly-written execution step:**

 ```markdown
---
-name: {skillName}
-description: {description}
-{group} {argumentHint}
---
+<step name="run_deployment">
+**Execute deployment to target environment.**

-# {skillName} Command
+$DEPLOY_STATUS="pending"  # Initialize before conditional

-## Overview
-{Auto-generated placeholder for command overview}
+```bash
+# Save current state for rollback
+cp .deploy/latest.json .deploy/previous.json 2>/dev/null || true

-## Usage
-{Auto-generated placeholder for usage examples}
+# Write deployment manifest via heredoc
+cat <<EOF > .deploy/latest.json
+{
+  "env": "$ENV",
+  "tag": "$DEPLOY_TAG",
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "commit": "$(git rev-parse --short HEAD)",
+  "status": "deploying"
+}
+EOF

-## Execution Flow
-{Auto-generated placeholder for execution steps}
+# Execute deployment
+if ! deploy_cmd --env "$ENV" --tag "$DEPLOY_TAG" 2>&1 | tee .deploy/latest.log; then
+  echo "Error: Deployment to $ENV failed" # (see code: E004)
+  exit 1
+fi
+
+$DEPLOY_STATUS="success"
 ```

---
+| Condition | Action |
+|-----------|--------|
+| Deploy succeeds | Update status → `"deployed"`, continue to verify |
+| Deploy fails | Log error `# (see code: E004)`, exit 1 |
+| `$ROLLBACK_MODE` | Load `.deploy/previous.json`, redeploy prior version |
+</step>
+```

-## Error Handling
+**Optional `<prerequisites>` section** (include when command uses external tools):

-| Error | Stage | Action |
-|-------|-------|--------|
-| Missing skillName | Phase 1 | Error: "skillName is required" |
-| Missing description | Phase 1 | Error: "description is required" |
-| Missing location | Phase 1 | Error: "location is required (project or user)" |
-| Invalid location | Phase 2 | Error: "location must be 'project' or 'user'" |
-| Template not found | Phase 3 | Error: "Command template not found" |
-| File exists | Phase 5 | Warning: "Command file already exists, will overwrite" |
-| Write failure | Phase 5 | Error: "Failed to write command file" |
+```markdown
+<prerequisites>
+- git (2.20+) — version control operations
+- curl — health check endpoints
+- jq — JSON processing (optional)
+</prerequisites>
+```

---
+**`<error_codes>` table:** Generate 3-6 specific error codes:
+- Derive from `$ARGUMENT_HINT` validation failures (E001-E003)
+- Derive from domain-specific failure modes (E004+)
+- Include 1-2 warnings (W001+)
+- Each code has: Code, Severity, Description, **Stage** (which step triggers it)
+- **Cross-reference rule**: Every `# (see code: E00X)` comment in `<process>` MUST have a matching row in `<error_codes>`, and every error code row MUST be referenced by at least one inline comment

-## Related Skills
+**`<success_criteria>` checkboxes:** Generate 4-8 verifiable conditions:
+- Input validation passed
+- Each execution step completed its action
+- Output artifacts exist / effects applied
+- Report displayed

- **skill-generator**: Create complete skills with phases, templates, and specs
- **flow-coordinator**: Orchestrate multi-step command workflows
+**Quality rules for generated content:**
+- NO bracket placeholders (`[Describe...]`, `[List...]`) — all content must be concrete
+- Steps must contain actionable logic, not descriptions of what to do
+- Error codes must reference specific failure conditions from this command's domain
+- Success criteria must be verifiable (not "command works correctly")
+- Every shell block must pass the Shell Correctness Checklist above
+- Follow patterns from @.claude/skills/command-generator/templates/command-md.md for structural reference only
+</step>
+
+<step name="write_file">
+**Write generated content to target path.**
+
+**If `$FILE_EXISTS`:** Warn: `"Command file already exists at {path}. Will overwrite."`
+
+```bash
+mkdir -p "$TARGET_DIR"
+```
+
+Write the drafted content to `$TARGET_PATH` using Write tool.
+
+**Verify:** Read back the file and confirm:
+- File exists and is non-empty
+- Contains `<purpose>` tag with concrete content (no placeholders)
+- Contains at least 2 `<step name=` blocks with shell code or tool calls
+- Contains `<error_codes>` with at least 3 rows including Stage column
+- Contains `<success_criteria>` with at least 4 checkboxes
+- No unresolved `{{...}}` or `[...]` placeholders remain
+- Every `# (see code: E0XX)` has a matching `<error_codes>` row (cross-ref check)
+- Every shell block uses heredoc for multi-line output (no bare multi-line echo)
+- All state variables initialized before conditional use
+- All error paths include `exit 1` after error message
+
+**If verification fails:** Fix the content in-place using Edit tool.
+
+**Report completion:**
+
+```
+Command generated successfully!
+
+File: {$TARGET_PATH}
+Name: {$SKILL_NAME}
+Description: {$DESCRIPTION}
+Location: {$LOCATION}
+Group: {$GROUP or "(none)"}
+Steps: {number of <step> blocks generated}
+Error codes: {number of error codes}
+
+Next Steps:
+1. Review and customize {$TARGET_PATH}
+2. Test: /{$GROUP}:{$SKILL_NAME} or /{$SKILL_NAME}
+```
+</step>
+
+</process>
+
+<error_codes>
+
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | skillName is required | validate_params |
+| E002 | error | description is required (min 10 chars) | validate_params |
+| E003 | error | location is required ("project" or "user") | validate_params |
+| E004 | error | skillName must be lowercase alphanumeric with hyphens | validate_params |
+| E005 | error | Failed to infer command domain from description | gather_requirements |
+| E006 | error | Failed to write command file | write_file |
+| E007 | error | Generated content contains unresolved placeholders | write_file |
+| W001 | warning | group must be lowercase alphanumeric with hyphens | validate_params |
+| W002 | warning | Command file already exists, will overwrite | write_file |
+| W003 | warning | Could not infer required_reading, using defaults | draft_content |
+
+</error_codes>
+
+<success_criteria>
+- [ ] All required parameters validated ($SKILL_NAME, $DESCRIPTION, $LOCATION)
+- [ ] Target path resolved with correct scope (project vs user) and group
+- [ ] Command domain inferred from description and argument hint
+- [ ] Concrete `<purpose>` drafted (no placeholders)
+- [ ] 2-6 `<step>` blocks generated with domain-specific logic
+- [ ] `<error_codes>` table generated with 3+ specific codes
+- [ ] `<success_criteria>` generated with 4+ verifiable checkboxes
+- [ ] File written to $TARGET_PATH and verified
+- [ ] Zero bracket placeholders in final output
+- [ ] Completion report displayed
+</success_criteria>