Merge pull request #17 from ducdmdev/feat/dag-aligned-improvements

feat: DAG-aligned improvements (v2.6.0)

Author: ducdmdev

.claude-plugin/marketplace.json

@@ -1,14 +1,13 @@
 {
   "name": "agent-team-plugin",
-  "description": "Claude Code plugin for orchestrating parallel work via Agent Teams",
   "owner": {
     "name": "ducdmdev"
   },
   "plugins": [
     {
       "name": "agent-team",
       "description": "Orchestrates parallel work via Agent Teams with automated coordination, workspace tracking, and hook enforcement",
-      "version": "2.5.1",
+      "version": "2.6.0",
       "source": {
         "source": "url",
         "url": "https://github.com/ducdmdev/agent-team-plugin.git"

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-team",
   "description": "Orchestrates parallel work via Agent Teams with automated coordination, workspace tracking, and hook enforcement",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "author": {
     "name": "Duc Do"
   }

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0] - 2026-03-20
+
+### Added
+- **`task-graph.json` workspace file** — centralized DAG with task dependencies, critical path, and convergence points. Created in Phase 3, maintained by lead, read by 3 new hook scripts
+- **`compute-critical-path.sh` hook** (TaskCompleted) — recomputes and displays remaining critical path after each task completion, warns about blocked critical tasks
+- **`detect-resume.sh` hook** (SessionStart) — detects resumable workspaces with smart staleness validation via git timestamps (valid/stale/missing output files)
+- **`check-integration-point.sh` hook** (TaskCompleted) — detects when convergence points (diamond dependencies) become fully unblocked, nudges lead to verify interface compatibility
+- **Critical Path Awareness** in Phase 4 — lead prioritizes critical-path blockers over non-critical work
+- **Resume from Existing Workspace** coordination pattern — valid/stale/remaining protocol with archive option
+- **Integration Checkpoint Response** coordination pattern — lead response protocol for convergence nudges
+- **CP column** in `tasks.md` — ★ marks critical path tasks, convergence notes in the Notes column
+
+### Changed
+- Phase 1b gains convergence point marking (step 6 after integration points)
+- Phase 2 gains critical path display and integration checkpoint preview
+- Phase 3 gains resume detection (step 1a) and `task-graph.json` creation (step 4a)
+- Phase 4 gains critical-path-weighted prioritization and integration checkpoint processing
+- Deadline Escalation gains critical-path acceleration (skip Nudge, go to Warn)
+- Report gains critical path metrics (initial → final length, shift count) and integration checkpoint counts
+- All 5 archetype SKILL.md files reference step 4a
+- `agent-implement` completion gate check #4 gains convergence-point awareness
+
 ## [2.5.1] - 2026-03-17
 
 ### Changed

CLAUDE.md

@@ -32,8 +32,8 @@ docs/                  Shared phases + reference docs consumed by skills at runt
 |------|---------|----------------|
 | `.claude-plugin/plugin.json` | Plugin identity | Bump version here on release |
 | `.claude-plugin/marketplace.json` | Marketplace registry | Bump version here too, keep in sync with plugin.json |
-| `hooks/hooks.json` | Hook registration (6 hooks) | Update timeout values, add new hooks, or update hook command paths |
-| `scripts/*.sh` | Hook enforcement logic (7 scripts) | Written in bash (`#!/bin/bash`), degrade gracefully without `jq` |
+| `hooks/hooks.json` | Hook registration (9 hook entries) | Update timeout values, add new hooks, or update hook command paths |
+| `scripts/*.sh` | Hook enforcement logic (12 scripts) | Written in bash (`#!/bin/bash`), degrade gracefully without `jq` |
 | `skills/agent-team/SKILL.md` | Hybrid/catch-all skill | Archetype detection + hybrid-specific overrides |
 | `skills/agent-implement/SKILL.md` | Implementation skill | Implementation-specific Phase 3/5 |
 | `skills/agent-research/SKILL.md` | Research skill | Research-specific Phase 3/5 |
@@ -45,7 +45,7 @@ docs/                  Shared phases + reference docs consumed by skills at runt
 | `docs/communication-protocol.md` | Structured message formats | Update when changing protocol prefixes or role-specific formats |
 | `docs/coordination-patterns.md` | Core conflict resolution, handoffs | Update when adding new core coordination patterns |
 | `docs/coordination-advanced.md` | Advanced coordination patterns | Update when adding new advanced patterns |
-| `docs/workspace-templates.md` | Workspace file templates | Update when adding new workspace files |
+| `docs/workspace-templates.md` | Workspace file templates + `task-graph.json` schema | Update when adding new workspace files or changing DAG schema |
 | `docs/report-format.md` | Final report template | Update when changing report structure |
 | `docs/custom-roles.md` | Project-specific role template | Reference for users creating custom roles |
 | `docs/team-archetypes.md` | Team type definitions + phase profiles | Update when adding new archetypes or modifying phase overrides |
@@ -96,7 +96,7 @@ chore:    maintenance (CI, dependencies)
 bash tests/run-tests.sh
 ```
 
-Runs 9 test files (78 assertions) covering all hooks and plugin structure.
+Runs 12 test files (145 assertions) covering all hooks and plugin structure.
 
 ### Validate Plugin
 
@@ -114,14 +114,17 @@ Then trigger with: "use agent team to [task]"
 
 ### Verify Hooks
 
-Six hooks registered in `hooks/hooks.json`:
+Nine hook entries registered in `hooks/hooks.json`:
 
 1. **TaskCompleted** — try marking a task complete without file changes (should block)
 2. **TeammateIdle** — let a teammate go idle with in-progress tasks (should nudge)
 3. **SessionStart(compact)** — compact context in a team session (should recover workspace)
 4. **PreToolUse(Write|Edit)** — have a teammate edit another's file (should warn, then block)
 5. **SubagentStart** — spawn a teammate (should log to events.log)
 6. **SubagentStop** — teammate shuts down (should log to events.log)
+7. **ComputeCriticalPath** — complete a task and check stderr for critical path update
+8. **DetectResume** — start a new session with an incomplete workspace and check stdout for resume context
+9. **CheckIntegrationPoint** — complete both upstream tasks of a convergence point and check stderr for integration nudge
 
 ## Common Tasks
 
@@ -130,7 +133,7 @@ Six hooks registered in `hooks/hooks.json`:
 1. Add the script to `scripts/`
 2. Make it executable
 3. Register it in `hooks/hooks.json` using `${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh`
-4. Document in SKILL.md Hooks section and README
+4. Document in shared-phases.md Hooks section and README
 5. Test: run `claude plugin validate .` then test manually in a team session
 
 ### Adding a New Teammate Role

README.md

@@ -227,7 +227,7 @@ CHECKPOINT #N: intermediate results, artifacts, ready_for=[task IDs]
 
 ## Hooks
 
-Five hooks enforce team discipline automatically:
+Nine hooks enforce team discipline and provide DAG-aware coordination:
 
 ### TaskCompleted
 
@@ -261,6 +261,27 @@ Tracks teammate lifecycle in `events.log`:
 - Logs spawn and stop events with timestamps and teammate metadata
 - Provides post-mortem analysis data
 
+### ComputeCriticalPath (TaskCompleted)
+
+Recomputes and displays the critical path after each task completion:
+- Reads `task-graph.json` for the dependency graph
+- Outputs remaining critical path and identifies blocked critical tasks
+- Informational only — always allows task completion
+
+### DetectResume (SessionStart)
+
+Detects resumable workspaces at session start:
+- Scans for incomplete `task-graph.json` files in `.agent-team/`
+- Validates completed task output files via git timestamps (valid/stale/missing)
+- Outputs resume context with options to resume or start fresh
+
+### CheckIntegrationPoint (TaskCompleted)
+
+Detects when convergence points become fully unblocked:
+- Checks if all upstream tasks of a convergence point are completed
+- Nudges the lead to verify interface compatibility before downstream task starts
+- Informational only — silent when no convergence point is ready
+
 All hooks degrade gracefully — exit 0 if `jq` is missing.
 
 ## Workspace
@@ -270,9 +291,10 @@ Each team creates a persistent workspace at `.agent-team/{team-name}/` in your p
 ```
 .agent-team/0304-refactor-auth/
 ├── progress.md      # Team status, members, decisions, handoffs
-├── tasks.md         # Task ledger with status and dependencies
+├── tasks.md         # Task ledger with status tracking
 ├── issues.md        # Issue tracker with severity and resolution
 ├── file-locks.json  # File ownership map (teammate -> files/directories)
+├── task-graph.json  # DAG: task dependencies, critical path, convergence points
 ├── events.log       # Structured JSON event log for post-mortem analysis
 └── report.md        # Final report (generated at completion)
 ```
@@ -297,7 +319,12 @@ agent-team-plugin/
 │   ├── check-file-ownership.sh      # PreToolUse(Write|Edit) hook
 │   ├── track-teammate-lifecycle.sh  # SubagentStart/Stop hook
 │   ├── setup-worktree.sh            # Worktree creation for isolation mode
-│   └── merge-worktrees.sh           # Worktree merge in Phase 5
+│   ├── merge-worktrees.sh           # Worktree merge in Phase 5
+│   ├── compute-critical-path.sh     # ComputeCriticalPath hook
+│   ├── detect-resume.sh             # DetectResume hook
+│   ├── check-integration-point.sh   # CheckIntegrationPoint hook
+│   ├── record-demo.sh              # Demo recording utility
+│   └── generate-demo-cast.sh       # Demo asciicast generator
 ├── skills/
 │   ├── agent-team/
 │   │   └── SKILL.md             # Hybrid/catch-all orchestrator

docs/coordination-advanced.md

@@ -187,6 +187,11 @@ Proactive time-based escalation to prevent tasks from exceeding the user's time
    What's your progress? Use PROGRESS or COMPLETED format.
    If blocked, use BLOCKED so I can log and route it.
    ```
+
+   When checking stalled tasks, prioritize **critical-path tasks** (marked with `critical_path: true` in `task-graph.json`). A stalled critical-path task directly delays total completion. A stalled non-critical task has slack before it affects the timeline. Adjust escalation urgency accordingly:
+   - Critical-path task stalled → skip Nudge, go directly to **Warn**
+   - Non-critical task stalled → follow normal Nudge → Warn → Escalate ladder
+
 3. **Escalation ladder**:
    - **Nudge** (first check): request status update
    - **Warn** (second check, ~5 min later): "Task #N is at risk. Need status or BLOCKED report."

docs/coordination-patterns.md

@@ -19,7 +19,9 @@ Patterns for the lead to handle common coordination scenarios during Phase 4.
 - [Synthesis Pattern](#synthesis-pattern) — collecting final results
 - [Error Recovery](#error-recovery) — handling teammate errors
 - [Issue Triage After Context Recovery](#issue-triage-after-context-recovery) — post-compaction review
+- [Resume from Existing Workspace](#resume-from-existing-workspace) — recovering from a previous team session
 - [Direct Handoff](#direct-handoff) — authorized peer-to-peer messaging with audit trail
+- [Integration Checkpoint Response](#integration-checkpoint-response) — handling convergence point nudges
 - [Advanced Patterns](coordination-advanced.md) — re-plan, adversarial review, checkpoint/rollback, deadline escalation, and more
 
 ## Communication Protocol
@@ -35,10 +37,13 @@ When receiving structured messages:
 | Prefix | Lead Action |
 |--------|--------------|
 | STARTING | Update `tasks.md` status to `in_progress`, add note |
-| COMPLETED | Update `tasks.md` status to `completed`, add file list and notes. Check: does this unblock other tasks? If yes, message the dependent teammate |
+| COMPLETED | Update `tasks.md` status to `completed`, add file list and notes. Update `task-graph.json`: set node status to `completed`, record `completed_at` and `output_files`. **Self-check**: read `task-graph.json` back to verify valid JSON. Check: does this unblock other tasks? If yes, message the dependent teammate. The `compute-critical-path.sh` hook will output the updated critical path. |
 | BLOCKED | Add row to `issues.md` immediately. Acknowledge the teammate. Route to resolution |
 | HANDOFF | Extract key details, forward to dependent teammate with actionable context. Log in `progress.md` Handoffs |
 | QUESTION | Check if answer is in workspace files. If yes, answer with file reference. If no, investigate |
+| PROGRESS | Note milestone in `tasks.md` Notes column. If percent indicates near-completion, no action needed. If stalled, trigger Deadline Escalation |
+| CHECKPOINT | If `ready_for` lists task IDs, forward checkpoint details to dependent teammate. Log in `progress.md` Handoffs |
+| (hook: integration checkpoint) | Read the nudge from `check-integration-point.sh`. Before unblocking the convergence task, verify interface compatibility between upstream outputs. If compatible, message the convergence task owner to proceed. If unclear, log in `issues.md` as medium severity. Log checkpoint in `progress.md` Decision Log. |
 
 ### Shared Workspace as Bulletin Board
 
@@ -161,6 +166,29 @@ Recovery actions for common Phase 3 failures.
 | Teammate fails to spawn | Check the error. Common causes: tool not available, permission denied. Retry once. If still failing, log to `issues.md`, continue with remaining teammates, reassign orphaned tasks |
 | Context compaction during Phase 3 | On recovery, read workspace files. If they exist but tasks/teammates are incomplete, resume from where you left off. If workspace doesn't exist yet, restart Phase 3 |
 
+## Resume from Existing Workspace
+
+When starting a new team session and the `detect-resume.sh` hook reports a resumable workspace:
+
+### Valid Completed Tasks
+Tasks whose output files are unchanged since `completed_at`. Skip these entirely — do not re-create or re-assign. Their results carry forward.
+
+### Stale Completed Tasks
+Tasks whose output files were modified after `completed_at` (someone edited the files outside the team). These must be re-run:
+- Reset status to `pending` in `task-graph.json`
+- Create new TaskCreate entries for them
+- Assign to appropriate teammates
+- Log in `progress.md` Decision Log: "Resumed — task #N marked stale (output modified after completion)"
+
+### Remaining Tasks
+Tasks that were never completed. Create and assign normally.
+
+### Archive Protocol
+If the user chooses "start fresh" instead of resuming:
+- Rename `.agent-team/{team-name}/` to `.agent-team/{team-name}-archived/`
+- Proceed with normal Phase 3
+- The archived workspace is preserved for reference
+
 ## File Conflict Resolution
 
 When two teammates report working on the same file:
@@ -311,6 +339,16 @@ For pre-approved information transfers between specific teammates, bypassing the
 
 The audit trail MUST be maintained. Direct handoffs save time but must still be logged via the lead's workspace updates.
 
+## Integration Checkpoint Response
+
+When `check-integration-point.sh` fires an integration nudge after two converging streams complete:
+
+1. **Read the nudge** — identify which convergence point was unblocked and which upstream tasks produced the converging outputs
+2. **Quick compatibility check** — read the `output_files` from both upstream tasks in `task-graph.json`. Do they define compatible interfaces? (e.g., if task #1 exports `TokenResult` and task #2 imports `TokenResult`, do the types match?)
+3. **If compatible** — message the convergence task owner: "Upstream tasks #X and #Y both completed. Interfaces verified compatible. Proceed with task #Z."
+4. **If unclear or incompatible** — message both upstream owners and the convergence owner: "Integration issue at #Z: outputs from #X and #Y may conflict at [interface]. Verify before proceeding." Log in `issues.md` as **medium** severity.
+5. **Log** — record the checkpoint in `progress.md` Decision Log: "Integration checkpoint: #Z unblocked by #X + #Y, compatibility [verified|flagged]"
+
 ## See Also
 
 - [coordination-advanced.md](coordination-advanced.md) — Re-plan on Block, Adversarial Review, Quality Gate, Checkpoint/Rollback, Deadline Escalation, Circular Dependency Detection, Graceful Degradation, Auto-Block, Anti-Patterns