mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat(workflow): add lightweight interactive planning workflow with in-memory execution and code exploration
- Introduced `lite-plan` command for intelligent task analysis and planning. - Implemented dynamic exploration and clarification phases based on task complexity. - Added support for auto mode and forced exploration flags. - Defined output artifacts and session structure for planning results. - Enhanced execution process with context handoff to `lite-execute`. chore(temp): create temporary memory content and import script - Added `.temp-memory-content.txt` to store session details and execution plan. - Implemented `temp-import-memory.cjs` to handle memory import using core-memory command. - Ensured cleanup of temporary files after execution.
This commit is contained in:
catlog22
@@ -0,0 +1,172 @@
|
||||
# Command: explore
|
||||
|
||||
## Purpose
|
||||
|
||||
Complexity-driven codebase exploration using shared explore subagent with centralized cache. v4 optimized: checks cache before exploring, avoids duplicate work across roles.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | PLAN-* task subject/description | Yes |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Spec context | `<session-folder>/spec/` (if exists) | No |
|
||||
| Plan directory | `<session-folder>/plan/` | Yes (create if missing) |
|
||||
| Project tech | `.workflow/project-tech.json` | No |
|
||||
| Cache index | `<session-folder>/explorations/cache-index.json` | No (create if missing) |
|
||||
|
||||
## Phase 3: Exploration
|
||||
|
||||
### Complexity Assessment
|
||||
|
||||
Score the task description against keyword indicators:
|
||||
|
||||
| Indicator | Keywords | Score |
|
||||
|-----------|----------|-------|
|
||||
| Structural change | refactor, architect, restructure, modular | +2 |
|
||||
| Multi-scope | multiple, across, cross-cutting | +2 |
|
||||
| Integration | integrate, api, database | +1 |
|
||||
| Non-functional | security, performance, auth | +1 |
|
||||
|
||||
**Complexity routing**:
|
||||
|
||||
| Score | Level | Strategy | Angle Count |
|
||||
|-------|-------|----------|-------------|
|
||||
| 0-1 | Low | ACE semantic search only | 1 |
|
||||
| 2-3 | Medium | Explore subagent per angle | 2-3 |
|
||||
| 4+ | High | Explore subagent per angle | 3-5 |
|
||||
|
||||
### Angle Presets
|
||||
|
||||
Select preset by dominant keyword match, then take first N angles per complexity:
|
||||
|
||||
| Preset | Trigger Keywords | Angles (priority order) |
|
||||
|--------|-----------------|------------------------|
|
||||
| architecture | refactor, architect, restructure, modular | architecture, dependencies, modularity, integration-points |
|
||||
| security | security, auth, permission, access | security, auth-patterns, dataflow, validation |
|
||||
| performance | performance, slow, optimize, cache | performance, bottlenecks, caching, data-access |
|
||||
| bugfix | fix, bug, error, issue, broken | error-handling, dataflow, state-management, edge-cases |
|
||||
| feature | (default) | patterns, integration-points, testing, dependencies |
|
||||
|
||||
### Cache-First Strategy (v4 new)
|
||||
|
||||
Before launching any exploration, check the shared cache:
|
||||
|
||||
```
|
||||
1. Read <session-folder>/explorations/cache-index.json
|
||||
2. For each selected angle:
|
||||
a. If angle exists in cache -> SKIP (reuse cached result)
|
||||
b. If angle not in cache -> explore via subagent
|
||||
3. Only explore uncached angles
|
||||
```
|
||||
|
||||
This avoids duplicating work done by analyst's `general` exploration or any prior role.
|
||||
|
||||
### Low Complexity: Direct Search
|
||||
|
||||
```bash
|
||||
mcp__ace-tool__search_context(project_root_path="<project-root>", query="<task-description>")
|
||||
```
|
||||
|
||||
Transform results into exploration JSON and write to `<session-folder>/explorations/explore-general.json`.
|
||||
Update cache-index.json.
|
||||
|
||||
**ACE failure fallback**:
|
||||
|
||||
```bash
|
||||
Bash(command="rg -l '<keywords>' --type ts", timeout=30000)
|
||||
```
|
||||
|
||||
### Medium/High Complexity: Explore Subagent per Angle
|
||||
|
||||
For each uncached angle, call the shared explore subagent:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "Explore",
|
||||
run_in_background: false,
|
||||
description: "Explore: <angle>",
|
||||
prompt: "Explore codebase for: <task-description>
|
||||
Focus angle: <angle>
|
||||
Keywords: <relevant-keywords>
|
||||
Session folder: <session-folder>
|
||||
|
||||
## Cache Check
|
||||
1. Read <session-folder>/explorations/cache-index.json (if exists)
|
||||
2. Look for entry with matching angle
|
||||
3. If found AND file exists -> read cached result, return summary
|
||||
4. If not found -> proceed to exploration
|
||||
|
||||
## Exploration Focus
|
||||
<angle-focus-from-table-below>
|
||||
|
||||
## Output
|
||||
Write JSON to: <session-folder>/explorations/explore-<angle>.json
|
||||
Update cache-index.json with new entry
|
||||
Each file in relevant_files MUST have: rationale (>10 chars), role, discovery_source, key_symbols"
|
||||
})
|
||||
```
|
||||
|
||||
### Angle Focus Guide
|
||||
|
||||
| Angle | Focus Points |
|
||||
|-------|-------------|
|
||||
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs |
|
||||
| dependencies | Import chains, external libraries, circular dependencies, shared utilities |
|
||||
| modularity | Module interfaces, separation of concerns, extraction opportunities |
|
||||
| integration-points | API endpoints, data flow between modules, event systems, service integrations |
|
||||
| security | Auth/authz logic, input validation, sensitive data handling, middleware |
|
||||
| auth-patterns | Auth flows (login/refresh), session management, token validation, permissions |
|
||||
| dataflow | Data transformations, state propagation, validation points, mutation paths |
|
||||
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity |
|
||||
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging |
|
||||
| patterns | Code conventions, design patterns, naming conventions, best practices |
|
||||
| testing | Test files, coverage gaps, test patterns (unit/integration/e2e), mocking |
|
||||
|
||||
### Explorations Manifest
|
||||
|
||||
After all explorations complete (both cached and new), write manifest to `<session-folder>/plan/explorations-manifest.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_description": "<description>",
|
||||
"complexity": "<Low|Medium|High>",
|
||||
"exploration_count": "<N>",
|
||||
"cached_count": "<M>",
|
||||
"explorations": [
|
||||
{ "angle": "<angle>", "file": "../explorations/explore-<angle>.json", "source": "cached|new" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Output Files
|
||||
|
||||
```
|
||||
<session-folder>/explorations/ (shared cache)
|
||||
+- cache-index.json (updated)
|
||||
+- explore-<angle>.json (per angle)
|
||||
|
||||
<session-folder>/plan/
|
||||
+- explorations-manifest.json (summary referencing shared cache)
|
||||
```
|
||||
|
||||
### Success Criteria
|
||||
|
||||
| Check | Criteria | Required |
|
||||
|-------|----------|----------|
|
||||
| At least 1 exploration | Non-empty exploration file exists | Yes |
|
||||
| Manifest written | explorations-manifest.json exists | Yes |
|
||||
| File roles assigned | Every relevant_file has role + rationale | Yes |
|
||||
| Cache updated | cache-index.json reflects all explorations | Yes |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Single exploration agent fails | Skip angle, remove from manifest, continue |
|
||||
| All explorations fail | Proceed to plan generation with task description only |
|
||||
| ACE search fails (Low) | Fallback to ripgrep keyword search |
|
||||
| Schema file not found | Use inline schema from Output section |
|
||||
| Cache index corrupt | Reset cache-index.json to empty, re-explore all |
|
||||
127
.claude/skills/team-lifecycle-v4/roles/planner/role.md
Normal file
127
.claude/skills/team-lifecycle-v4/roles/planner/role.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Role: planner
|
||||
|
||||
Multi-angle code exploration (via shared explore subagent with cache) and structured implementation planning.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `planner` | **Prefix**: `PLAN-*` | **Tag**: `[planner]`
|
||||
- **Responsibility**: Complexity assessment -> Code exploration (shared cache) -> Plan generation -> Approval
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process PLAN-* tasks
|
||||
- Assess complexity before planning
|
||||
- Use shared explore subagent for codebase exploration (cache-aware)
|
||||
- Generate plan.json + .task/TASK-*.json
|
||||
- Load spec context in full-lifecycle mode
|
||||
- Submit plan for coordinator approval
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks for other roles
|
||||
- Implement code
|
||||
- Modify spec documents
|
||||
- Skip complexity assessment
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| plan_ready | -> coordinator | Plan complete |
|
||||
| plan_revision | -> coordinator | Plan revised per feedback |
|
||||
| error | -> coordinator | Exploration or planning failure |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| commands/explore.md | Complexity-driven exploration via shared explore subagent |
|
||||
| Explore subagent | Per-angle exploration (shared cache) |
|
||||
| cli-lite-planning-agent | Plan generation |
|
||||
|
||||
---
|
||||
|
||||
## Phase 1.5: Load Spec Context (Full-Lifecycle)
|
||||
|
||||
If `<session-folder>/spec/` exists -> load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise -> impl-only mode.
|
||||
|
||||
**Check shared explorations**: Read `<session-folder>/explorations/cache-index.json` to see if analyst already cached useful explorations. Reuse rather than re-explore.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Multi-Angle Exploration
|
||||
|
||||
**Objective**: Explore codebase to inform planning.
|
||||
|
||||
**Complexity routing**:
|
||||
|
||||
| Complexity | Criteria | Strategy |
|
||||
|------------|----------|----------|
|
||||
| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only |
|
||||
| Medium | 200-500 chars or moderate scope | 2-3 angle explore subagent |
|
||||
| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle explore subagent |
|
||||
|
||||
Delegate to `commands/explore.md` for angle selection and execution.
|
||||
|
||||
**Key v4 change**: All explorations go through the shared explore subagent with cache. Before launching an exploration for an angle, check cache-index.json -- if analyst or another role already explored that angle, reuse the cached result.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Plan Generation
|
||||
|
||||
**Objective**: Generate structured implementation plan.
|
||||
|
||||
| Complexity | Strategy |
|
||||
|------------|----------|
|
||||
| Low | Direct planning -> single TASK-001 with plan.json |
|
||||
| Medium/High | cli-lite-planning-agent with exploration results |
|
||||
|
||||
**Agent call** (Medium/High):
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "cli-lite-planning-agent",
|
||||
run_in_background: false,
|
||||
description: "Generate implementation plan",
|
||||
prompt: "Generate plan.
|
||||
Output: <plan-dir>/plan.json + <plan-dir>/.task/TASK-*.json
|
||||
Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
|
||||
Task: <task-description>
|
||||
Explorations: <explorations-manifest>
|
||||
Complexity: <complexity>
|
||||
Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, depends_on"
|
||||
})
|
||||
```
|
||||
|
||||
**Spec context** (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Submit for Approval
|
||||
|
||||
1. Read plan.json and TASK-*.json
|
||||
2. Report to coordinator: complexity, task count, task list, approach, plan location
|
||||
3. Wait for response: approved -> complete; revision -> update and resubmit
|
||||
|
||||
**Session files**:
|
||||
```
|
||||
<session-folder>/plan/
|
||||
+-- exploration-<angle>.json (per angle, from shared cache)
|
||||
+-- explorations-manifest.json (summary)
|
||||
+-- plan.json
|
||||
+-- .task/TASK-*.json
|
||||
```
|
||||
|
||||
Note: exploration files may be symlinked or referenced from `<session-folder>/explorations/` (shared cache location).
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Exploration agent failure | Plan from description only |
|
||||
| Planning agent failure | Fallback to direct planning |
|
||||
| Plan rejected 3+ times | Notify coordinator, suggest alternative |
|
||||
| Schema not found | Use basic structure |
|
||||
| Cache index corrupt | Clear cache, re-explore all angles |
|
||||
Reference in New Issue
Block a user