mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-18 18:48:48 +08:00
feat: add MCP server for semantic code search with FastMCP integration
This commit is contained in:
catlog22
187
.claude/skills/wf-player/specs/node-executor.md
Normal file
187
.claude/skills/wf-player/specs/node-executor.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Node Executor — Execution Mechanisms per Node Type
|
||||
|
||||
## Overview
|
||||
|
||||
Each node type uses a specific execution mechanism. This spec defines the exact invocation pattern.
|
||||
|
||||
## 1. skill node
|
||||
|
||||
**Mechanism**: `Skill()` tool — synchronous, blocks until complete.
|
||||
|
||||
```
|
||||
Skill({
|
||||
skill: "<node.executor>",
|
||||
args: "<resolved_args>"
|
||||
})
|
||||
```
|
||||
|
||||
**Output extraction**: Parse Skill() result for:
|
||||
- Session ID pattern: `WFS-[a-z]+-\d{8}` or `TC-[a-z]+-\d{8}`
|
||||
- Output path: last `.md` or `.json` file path mentioned
|
||||
- Artifacts: all file paths in output
|
||||
|
||||
**Session ID sources**:
|
||||
- Explicit: "Session: WFS-plan-20260317" in output
|
||||
- Implicit: first session-like ID in output
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
// Planning skill
|
||||
Skill({ skill: "workflow-lite-plan", args: "Implement user authentication" })
|
||||
|
||||
// Execute skill (with prior session)
|
||||
Skill({ skill: "workflow-execute", args: "--resume-session WFS-plan-20260317" })
|
||||
|
||||
// Test skill (with prior session)
|
||||
Skill({ skill: "workflow-test-fix", args: "--session WFS-exec-20260317" })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. command node
|
||||
|
||||
**Mechanism**: `Skill()` tool with namespace command name — synchronous.
|
||||
|
||||
```
|
||||
Skill({
|
||||
skill: "<node.executor>", // e.g. "workflow:refactor-cycle"
|
||||
args: "<resolved_args>"
|
||||
})
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
Skill({ skill: "workflow:refactor-cycle", args: "Reduce coupling in auth module" })
|
||||
Skill({ skill: "workflow:debug-with-file", args: "Login fails with 401 on valid tokens" })
|
||||
Skill({ skill: "issue:discover", args: "" })
|
||||
Skill({ skill: "issue:queue", args: "" })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. cli node
|
||||
|
||||
**Mechanism**: `Bash()` with `run_in_background: true` — STOP after launch, resume via hook callback.
|
||||
|
||||
```
|
||||
// Build command
|
||||
const prompt = resolveArgs(node.args_template, ...)
|
||||
const cmd = `ccw cli -p "${escapeForShell(prompt)}" --tool ${node.cli_tool} --mode ${node.cli_mode} --rule ${node.cli_rule}`
|
||||
|
||||
// Launch background
|
||||
Bash({ command: cmd, run_in_background: true })
|
||||
|
||||
// Save CLI task ID to node state for hook matching
|
||||
node_state.cli_task_id = <captured from stderr CCW_EXEC_ID>
|
||||
|
||||
// Write session-state.json
|
||||
// STOP — do not proceed until hook callback fires
|
||||
```
|
||||
|
||||
**Hook callback** (triggered when ccw cli completes):
|
||||
```
|
||||
// Identify which node was running (status = "running" with cli_task_id set)
|
||||
// Extract from CLI output:
|
||||
// - output_path: file written by CLI
|
||||
// - cli_exec_id: from CCW_EXEC_ID
|
||||
// Mark node completed
|
||||
// Advance to next node
|
||||
```
|
||||
|
||||
**CLI output escaping**:
|
||||
```javascript
|
||||
function escapeForShell(s) {
|
||||
// Use single quotes with escaped single quotes inside
|
||||
return "'" + s.replace(/'/g, "'\\''") + "'"
|
||||
}
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Bash({
|
||||
command: `ccw cli -p 'PURPOSE: Analyze auth module architecture\nTASK: • Review class structure • Check dependencies\nMODE: analysis\nCONTEXT: @src/auth/**/*\nEXPECTED: Architecture report with issues list\nCONSTRAINTS: Read only' --tool gemini --mode analysis --rule analysis-review-architecture`,
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. agent node
|
||||
|
||||
**Mechanism**: `Agent()` tool.
|
||||
|
||||
Single agent (serial):
|
||||
```
|
||||
Agent({
|
||||
subagent_type: node.executor, // "general-purpose" or "code-reviewer"
|
||||
prompt: resolveArgs(node.args_template, ...),
|
||||
run_in_background: false, // blocks until complete
|
||||
description: node.name
|
||||
})
|
||||
```
|
||||
|
||||
Parallel agents (same parallel_group — use team-coordinate pattern):
|
||||
```
|
||||
// For 2-3 parallel agents: launch all with run_in_background: true
|
||||
// Use SendMessage/callback or wait with sequential Skill() calls
|
||||
// For complex parallel pipelines: delegate to team-coordinate
|
||||
|
||||
Skill({
|
||||
skill: "team-coordinate",
|
||||
args: "<description of parallel work>"
|
||||
})
|
||||
```
|
||||
|
||||
**Output extraction**:
|
||||
- Agent output is usually the full response text
|
||||
- Look for file paths in output for `output_path`
|
||||
|
||||
---
|
||||
|
||||
## 5. checkpoint node
|
||||
|
||||
**Mechanism**: Pure state management — no external calls unless `auto_continue: false`.
|
||||
|
||||
```
|
||||
// 1. Write checkpoint snapshot
|
||||
Write({
|
||||
file_path: "<session_dir>/checkpoints/<node.id>.json",
|
||||
content: JSON.stringify({
|
||||
session_id, checkpoint_id: node.id, checkpoint_name: node.name,
|
||||
saved_at: now(), context_snapshot: session_state.context,
|
||||
node_states_snapshot: session_state.node_states,
|
||||
last_completed_node: prev_node_id,
|
||||
next_node: next_node_id
|
||||
}, null, 2)
|
||||
})
|
||||
|
||||
// 2. Update session state
|
||||
session_state.last_checkpoint = node.id
|
||||
node_states[node.id].status = "completed"
|
||||
node_states[node.id].saved_at = now()
|
||||
node_states[node.id].snapshot_path = checkpointPath
|
||||
|
||||
Write({ file_path: session_state_path, content: JSON.stringify(session_state, null, 2) })
|
||||
|
||||
// 3. If auto_continue = false: pause for user (see 03-execute.md)
|
||||
// 4. If auto_continue = true: proceed immediately
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Passing Between Nodes
|
||||
|
||||
The runtime reference resolver in `03-execute.md` handles `{N-xxx.field}` substitution.
|
||||
|
||||
**Key resolved fields by node type**:
|
||||
|
||||
| Node type | Exposes | Referenced as |
|
||||
|-----------|---------|---------------|
|
||||
| skill | session_id | `{N-001.session_id}` |
|
||||
| skill | output_path | `{N-001.output_path}` |
|
||||
| skill | artifacts[0] | `{N-001.artifacts[0]}` |
|
||||
| cli | output_path | `{N-001.output_path}` |
|
||||
| agent | output_path | `{N-001.output_path}` |
|
||||
| any | shorthand prev | `{prev_session_id}`, `{prev_output_path}` |
|
||||
|
||||
**Fallback**: If referenced field is null/empty, the args_template substitution results in empty string. The executor should handle gracefully (most skills default to latest session).
|
||||
136
.claude/skills/wf-player/specs/state-schema.md
Normal file
136
.claude/skills/wf-player/specs/state-schema.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Session State Schema
|
||||
|
||||
## File Location
|
||||
|
||||
`.workflow/sessions/WFR-<slug>-<date>-<time>/session-state.json`
|
||||
|
||||
## Full Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFR-feature-tdd-review-20260317-143022",
|
||||
"template_id": "wft-feature-tdd-review-20260310",
|
||||
"template_path": ".workflow/templates/feature-tdd-review.json",
|
||||
"template_name": "Feature TDD with Review",
|
||||
|
||||
"status": "running | paused | completed | failed | aborted | archived",
|
||||
|
||||
"context": {
|
||||
"goal": "Implement user authentication",
|
||||
"scope": "src/auth"
|
||||
},
|
||||
|
||||
"execution_plan": [
|
||||
{ "batch": 1, "nodes": ["N-001"], "parallel": false },
|
||||
{ "batch": 2, "nodes": ["CP-01"], "parallel": false },
|
||||
{ "batch": 3, "nodes": ["N-002"], "parallel": false },
|
||||
{ "batch": 4, "nodes": ["CP-02"], "parallel": false },
|
||||
{ "batch": 5, "nodes": ["N-003a", "N-003b"], "parallel": true },
|
||||
{ "batch": 6, "nodes": ["N-004"], "parallel": false }
|
||||
],
|
||||
|
||||
"current_batch": 3,
|
||||
"current_node": "N-002",
|
||||
"last_checkpoint": "CP-01",
|
||||
|
||||
"node_states": {
|
||||
"N-001": {
|
||||
"status": "completed",
|
||||
"started_at": "2026-03-17T14:30:25Z",
|
||||
"completed_at": "2026-03-17T14:35:10Z",
|
||||
"session_id": "WFS-plan-20260317",
|
||||
"output_path": ".workflow/sessions/WFS-plan-20260317/IMPL_PLAN.md",
|
||||
"artifacts": [
|
||||
".workflow/sessions/WFS-plan-20260317/IMPL_PLAN.md"
|
||||
],
|
||||
"error": null
|
||||
},
|
||||
"CP-01": {
|
||||
"status": "completed",
|
||||
"saved_at": "2026-03-17T14:35:12Z",
|
||||
"snapshot_path": ".workflow/sessions/WFR-feature-tdd-review-20260317-143022/checkpoints/CP-01.json",
|
||||
"auto_continue": true
|
||||
},
|
||||
"N-002": {
|
||||
"status": "running",
|
||||
"started_at": "2026-03-17T14:35:14Z",
|
||||
"completed_at": null,
|
||||
"session_id": null,
|
||||
"output_path": null,
|
||||
"artifacts": [],
|
||||
"error": null,
|
||||
"cli_task_id": "gem-143514-x7k2"
|
||||
},
|
||||
"CP-02": {
|
||||
"status": "pending",
|
||||
"saved_at": null,
|
||||
"snapshot_path": null
|
||||
},
|
||||
"N-003a": {
|
||||
"status": "pending",
|
||||
"started_at": null,
|
||||
"completed_at": null,
|
||||
"session_id": null,
|
||||
"output_path": null,
|
||||
"artifacts": [],
|
||||
"error": null
|
||||
},
|
||||
"N-003b": { "status": "pending", "..." : "..." },
|
||||
"N-004": { "status": "pending", "..." : "..." }
|
||||
},
|
||||
|
||||
"created_at": "2026-03-17T14:30:22Z",
|
||||
"updated_at": "2026-03-17T14:35:14Z",
|
||||
"completed_at": null
|
||||
}
|
||||
```
|
||||
|
||||
## Status Values
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `running` | Active execution in progress |
|
||||
| `paused` | User paused at checkpoint — resume with `--resume` |
|
||||
| `completed` | All nodes executed successfully |
|
||||
| `failed` | A node failed and abort was chosen |
|
||||
| `aborted` | User aborted at checkpoint |
|
||||
| `archived` | Completed and moved to archive/ |
|
||||
|
||||
## Node State Status Values
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `pending` | Not yet started |
|
||||
| `running` | Currently executing (may be waiting for CLI callback) |
|
||||
| `completed` | Successfully finished |
|
||||
| `skipped` | Skipped due to `on_fail: skip` |
|
||||
| `failed` | Execution error |
|
||||
|
||||
## Checkpoint Snapshot Schema
|
||||
|
||||
`.workflow/sessions/<wfr-id>/checkpoints/<CP-id>.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFR-<id>",
|
||||
"checkpoint_id": "CP-01",
|
||||
"checkpoint_name": "After Plan",
|
||||
"saved_at": "2026-03-17T14:35:12Z",
|
||||
"context_snapshot": { "goal": "...", "scope": "..." },
|
||||
"node_states_snapshot": { /* full node_states at this point */ },
|
||||
"last_completed_node": "N-001",
|
||||
"next_node": "N-002"
|
||||
}
|
||||
```
|
||||
|
||||
## Session Directory Structure
|
||||
|
||||
```
|
||||
.workflow/sessions/WFR-<slug>-<date>-<time>/
|
||||
+-- session-state.json # Main state file, updated after every node
|
||||
+-- checkpoints/ # Checkpoint snapshots
|
||||
| +-- CP-01.json
|
||||
| +-- CP-02.json
|
||||
+-- artifacts/ # Optional: copies of key artifacts
|
||||
+-- N-001-output.md
|
||||
```
|
||||
Reference in New Issue
Block a user