mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: add team-lifecycle-v5 with unified team-worker agent architecture
Replace v4's per-role boilerplate (7 role.md files sharing 60% code) with a single team-worker agent that handles Phase 1/5, message bus, consensus, and inner loop. Role-specific Phase 2-4 logic lives in lightweight role-spec files. Workers spawn as team-worker agents directly instead of general-purpose + Skill indirection, reducing total worker content by ~64%.
This commit is contained in:
catlog22
172
.claude/skills/team-lifecycle-v5/subagents/explore-subagent.md
Normal file
172
.claude/skills/team-lifecycle-v5/subagents/explore-subagent.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# Explore Subagent
|
||||
|
||||
Shared codebase exploration utility with centralized caching. Callable by any role needing code context. Replaces v3's standalone explorer role.
|
||||
|
||||
## Design Rationale
|
||||
|
||||
In v3, exploration happened in 3 separate places:
|
||||
- `analyst` Phase 3: ACE semantic search for architecture patterns
|
||||
- `planner` Phase 2: multi-angle cli-explore-agent
|
||||
- `explorer` role: standalone service with full spawn cycle
|
||||
|
||||
Results were scattered across different directories and never shared. In v4, all exploration routes through this subagent with a **unified cache** in `explorations/`.
|
||||
|
||||
## Invocation
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: "Explore <angle>",
|
||||
prompt: `Explore codebase for: <query>
|
||||
|
||||
Focus angle: <angle>
|
||||
Keywords: <keyword-list>
|
||||
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
|
||||
<angle-specific-focus-from-table-below>
|
||||
|
||||
## Output
|
||||
Write JSON to: <session-folder>/explorations/explore-<angle>.json
|
||||
Update cache-index.json with new entry
|
||||
|
||||
## Output Schema
|
||||
{
|
||||
"angle": "<angle>",
|
||||
"query": "<query>",
|
||||
"relevant_files": [
|
||||
{ "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] }
|
||||
],
|
||||
"patterns": [],
|
||||
"dependencies": [],
|
||||
"external_refs": [],
|
||||
"_metadata": { "created_by": "<calling-role>", "timestamp": "...", "cache_key": "..." }
|
||||
}
|
||||
|
||||
Return summary: file count, pattern count, top 5 files, output path`
|
||||
})
|
||||
```
|
||||
|
||||
## Cache Mechanism
|
||||
|
||||
### Cache Index Schema
|
||||
|
||||
`<session-folder>/explorations/cache-index.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"entries": [
|
||||
{
|
||||
"angle": "architecture",
|
||||
"keywords": ["auth", "middleware"],
|
||||
"file": "explore-architecture.json",
|
||||
"created_by": "analyst",
|
||||
"created_at": "2026-02-27T10:00:00Z",
|
||||
"file_count": 15
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Cache Lookup Rules
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Exact angle match exists | Return cached result |
|
||||
| No match | Execute exploration, cache result |
|
||||
| Cache file missing but index has entry | Remove stale entry, re-explore |
|
||||
|
||||
### Cache Invalidation
|
||||
|
||||
Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache.
|
||||
|
||||
## Angle Focus Guide
|
||||
|
||||
| Angle | Focus Points | Typical Caller |
|
||||
|-------|-------------|----------------|
|
||||
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | analyst, planner |
|
||||
| dependencies | Import chains, external libraries, circular dependencies, shared utilities | planner |
|
||||
| modularity | Module interfaces, separation of concerns, extraction opportunities | planner |
|
||||
| integration-points | API endpoints, data flow between modules, event systems | analyst, planner |
|
||||
| security | Auth/authz logic, input validation, sensitive data handling, middleware | planner |
|
||||
| auth-patterns | Auth flows, session management, token validation, permissions | planner |
|
||||
| dataflow | Data transformations, state propagation, validation points | planner |
|
||||
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | planner |
|
||||
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | planner |
|
||||
| patterns | Code conventions, design patterns, naming conventions, best practices | analyst, planner |
|
||||
| testing | Test files, coverage gaps, test patterns, mocking strategies | planner |
|
||||
| general | Broad semantic search for topic-related code | analyst |
|
||||
|
||||
## Exploration Strategies
|
||||
|
||||
### Low Complexity (direct search)
|
||||
|
||||
For simple queries, use ACE semantic search:
|
||||
|
||||
```
|
||||
mcp__ace-tool__search_context(project_root_path="<project-root>", query="<query>")
|
||||
```
|
||||
|
||||
ACE failure fallback: `rg -l '<keywords>' --type ts`
|
||||
|
||||
### Medium/High Complexity (multi-angle)
|
||||
|
||||
For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles (see planner's `commands/explore.md`).
|
||||
|
||||
## Search Tool Priority
|
||||
|
||||
| Tool | Priority | Use Case |
|
||||
|------|----------|----------|
|
||||
| mcp__ace-tool__search_context | P0 | Semantic search |
|
||||
| Grep / Glob | P1 | Pattern matching |
|
||||
| cli-explore-agent | Deep | Multi-angle exploration |
|
||||
| WebSearch | P3 | External docs |
|
||||
|
||||
## Integration with Roles
|
||||
|
||||
### analyst (RESEARCH-001)
|
||||
|
||||
```
|
||||
# After seed analysis, explore codebase context
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Explore general context",
|
||||
prompt: "Explore codebase for: <topic>\nFocus angle: general\n..."
|
||||
})
|
||||
# Result feeds into discovery-context.json
|
||||
```
|
||||
|
||||
### planner (PLAN-001)
|
||||
|
||||
```
|
||||
# Multi-angle exploration before plan generation
|
||||
for angle in selected_angles:
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Explore <angle>",
|
||||
prompt: "Explore codebase for: <task>\nFocus angle: <angle>\n..."
|
||||
})
|
||||
# Explorations manifest built from cache-index.json
|
||||
```
|
||||
|
||||
### Any role needing context
|
||||
|
||||
Any role can call explore subagent when needing codebase context for better decisions.
|
||||
|
||||
## Comparison with v3
|
||||
|
||||
| Aspect | v3 (explorer role) | v4 (explore subagent) |
|
||||
|--------|-------------------|----------------------|
|
||||
| Identity | Full team member | Utility subagent |
|
||||
| Task creation | Coordinator creates EXPLORE-* tasks | No tasks, direct call |
|
||||
| Spawn overhead | Full agent lifecycle | Subagent call (~5s) |
|
||||
| Result sharing | Isolated in explorations/ | Shared cache with index |
|
||||
| Caller | Only via coordinator dispatch | Any role directly |
|
||||
| Duplication | analyst + planner + explorer all explore | Single cached path |
|
||||
Reference in New Issue
Block a user