@dtt_siye/atool 1.3.1 → 1.5.0

package/skills/agent-audit/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: agent-audit
+description: "Use when multiple agents or parallel tasks are running — tracks each agent's modifications, detects file conflicts, and provides audit trail. 在多Agent并行工作时使用 — 追踪每个Agent的修改、检测文件冲突、提供审计记录."
+version: 0.1.0
+category: quality
+---
+
+# Agent Audit — Multi-Agent Modification Tracking
+
+Tracks file modifications across multiple AI agents or parallel tasks, detects conflicts, and provides a complete audit trail for coordination.
+
+## When to Use
+
+- When using `/smart-dispatch` for parallel agent execution
+- When using `/dispatching-parallel-agents` for independent tasks
+- When using `/subagent-driven-development` for implementation plans
+- After parallel agents complete, before merging results
+- When reviewing what changes each agent made
+
+## How It Works
+
+### Audit Log Format
+
+Each agent's modifications are recorded in `.claude/agent-audit.json`:
+
+```json
+{
+  "audit_entries": [
+    {
+      "agent_id": "agent-1",
+      "task": "Implement user authentication",
+      "started_at": 1712649600,
+      "completed_at": 1712649900,
+      "files_modified": [
+        {
+          "path": "src/auth/UserService.java",
+          "action": "modified",
+          "lines_added": 45,
+          "lines_removed": 12,
+          "intent": "Add JWT token generation"
+        }
+      ],
+      "files_planned": ["src/auth/UserService.java", "src/auth/AuthController.java"],
+      "files_unexpected": [],
+      "impact_scope": ["auth", "api"],
+      "status": "completed"
+    }
+  ],
+  "conflicts": [],
+  "summary": {
+    "total_agents": 3,
+    "total_files_modified": 8,
+    "conflicts_detected": 0
+  }
+}
+```
+
+### Step 1: Agent Registration
+
+Before dispatching an agent, register it:
+
+```
+Read: agent-audit.json (or create if not exists)
+Add entry:
+{
+  "agent_id": "{agent-N}",
+  "task": "{task description}",
+  "files_planned": [{list of expected files}],
+  "started_at": {timestamp}
+}
+```
+
+### Step 2: Modification Tracking
+
+Each agent should record its modifications. Use git diff or task-state data:
+
+```
+After agent completes:
+  git diff --stat HEAD → extract file list and line changes
+  Compare with files_planned → flag unexpected files
+  Cross-reference with knowledge-graph → compute impact_scope
+```
+
+### Step 3: Conflict Detection
+
+After all agents complete, detect file-level conflicts:
+
+```
+For each pair of agents (A, B):
+  overlap = A.files_modified ∩ B.files_modified
+  if overlap is not empty:
+    CONFLICT: agents A and B both modified: {overlap}
+    severity = check if changes are in same lines (git merge-base)
+```
+
+Conflict severity levels:
+- **Critical**: Same file, same lines → merge conflict likely
+- **Warning**: Same file, different sections → manual review needed
+- **Info**: Different files, same module → review for logical consistency
+
+### Step 4: Impact Analysis
+
+Using knowledge-graph.json (from project-analyze):
+
+```
+For each agent's modified files:
+  1. Find the module each file belongs to
+  2. Find upstream dependents (who depends on this module)
+  3. Find downstream dependencies (what this module depends on)
+  4. Compute impact scope = module + direct dependents
+```
+
+### Step 5: Consolidated Audit Report
+
+```
+## Agent Audit Report
+
+### Execution Summary
+| Agent | Task | Files | Status | Duration |
+|-------|------|-------|--------|----------|
+| agent-1 | User auth | 3 | completed | 5m |
+| agent-2 | Payment API | 4 | completed | 7m |
+| agent-3 | Tests | 5 | completed | 4m |
+
+### File Overlap
+| File | Agent-1 | Agent-2 | Agent-3 |
+|------|---------|---------|---------|
+| src/common/Utils.java | modified | - | modified |
+
+### Conflicts
+| Severity | File | Details |
+|----------|------|---------|
+| Warning | src/common/Utils.java | Both agent-1 and agent-3 modified this file |
+
+### Impact Scope
+| Agent | Modules Affected | Downstream Impact |
+|-------|-----------------|-------------------|
+| agent-1 | auth, api | gateway, frontend |
+| agent-2 | payment, billing | notification, reporting |
+
+### Recommendations
+1. Review src/common/Utils.java for merge conflicts before integrating
+2. Run integration tests after merging all agent changes
+3. Update documentation for auth and payment modules
+```
+
+## Integration with task-state
+
+The agent-audit reads from and writes to `.claude/task-state.json`:
+
+```json
+{
+  "active_agents": 3,
+  "completed_agents": 2,
+  "agent_conflicts": ["src/common/Utils.java"],
+  "pending_actions": ["resolve_conflict:Utils.java", "run_integration_tests", "update_docs"]
+}
+```
+
+## Smart-Dispatch Integration
+
+When using `/smart-dispatch`:
+
+1. **Before dispatch**: Register each chunk as an agent entry
+2. **During execution**: Each agent records its modifications
+3. **After all complete**: Run conflict detection
+4. **Review phase**: Present consolidated audit report
+5. **Integration**: User resolves conflicts, then merge
+
+## Skill 协作
+
+| 协作 Skill | 触发条件 | 交互方式 |
+|-----------|---------|---------|
+| smart-dispatch | Parallel execution | 每个chunk注册为agent，完成后审计 |
+| dispatching-parallel-agents | Independent tasks | 跟踪每个后台agent的修改 |
+| subagent-driven-development | Implementation plans | 追踪sub-agent修改范围 |
+| project-analyze | Knowledge-graph available | 使用图谱计算impact scope |
+| architecture-guard | Conflicts detected | 检查冲突是否违反架构约束 |
+| verification-before-completion | After agent merge | 合并后验证整体完整性 |
+| ci-feedback | After merge | 运行集成测试验证 |