From 6dc644d9fb9656d973bbe26be49aff12b4cb11b2 Mon Sep 17 00:00:00 2001 From: Marius Mutu Date: Mon, 22 Dec 2025 21:20:48 +0200 Subject: [PATCH] fix: Complete rewrite of progress tracking system (v1.0.9) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The /ab:build command was executing tasks but not tracking progress. This rewrite enforces dual progress tracking in BOTH status.json AND plan.md. Key changes: build.md - Complete restructure: - Step-by-step execution workflow (like migrate.md) - Step 4d MANDATORY: Update both status.json and plan.md - User confirmation required between tasks - Visual Progress Tracker table in plan template planner.md - New plan template: - Progress Tracker table at top with ⬜/✅ indicators - Each task has `- **Status**: ⬜ Pending` field - Status header shows overall progress coder.md - Dual file updates: - 5a: Update status.json (currentTask, tasksCompleted, history) - 5b: Update plan.md Progress Tracker (⬜ Pending → ✅ Done) Benefits: - Visual progress in plan.md (human readable) - JSON progress in status.json (programmatic) - Redundancy ensures progress is never lost - Team can see exactly which tasks are complete 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .claude-plugin/marketplace.json | 2 +- CHANGELOG.md | 38 +++ plugin/.claude-plugin/plugin.json | 2 +- plugin/agents/coder.md | 51 +++- plugin/agents/planner.md | 76 +++--- plugin/commands/build.md | 374 ++++++++++++++++++------------ 6 files changed, 357 insertions(+), 186 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7707adb..44ae927 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "name": "ab", "source": "./plugin", "description": "Spec-driven build orchestration with git worktree isolation and session memory", - "version": "1.0.7", + "version": "1.0.9", "keywords": ["build", "spec", "automation", "worktree", "qa"] } ] diff --git a/CHANGELOG.md b/CHANGELOG.md index 418648e..055a0a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,44 @@ All notable changes to Auto-Build plugin. +## [1.0.9] - 2024-12-22 + +### Fixed +- **Complete rewrite of progress tracking system** - now enforced at every step +- Progress is tracked in BOTH status.json AND plan.md (dual tracking) +- Plan now includes visual Progress Tracker table with ⬜/✅ status indicators + +### Changed +- **build.md**: Complete restructure with step-by-step execution workflow + - Step 4d now MANDATORY updates both status.json and plan.md + - Added Progress Tracker table format in plan template + - User confirmation required between tasks +- **planner.md**: New plan.md template with Progress Tracker table + - Each task now has `- **Status**: ⬜ Pending` field + - Table at top shows all tasks with status columns +- **coder.md**: Step 5 now requires updating both files + - 5a: Update status.json with currentTask, tasksCompleted + - 5b: Update plan.md Progress Tracker (⬜→✅) + +### Why This Matters +- Visual progress tracking in plan.md (can see at a glance) +- JSON progress in status.json (for programmatic access) +- Both files updated = redundancy and visibility +- Team members can see exactly which tasks are done + +## [1.0.8] - 2024-12-22 + +### Fixed +- **`/ab:build` now properly tracks task progress in status.json** +- Added explicit "MANDATORY" progress tracking instructions in build.md +- Added status.json update step to coder agent +- Progress is now visible for team collaboration (currentTask, history entries) + +### Changed +- build.md: Added "CRITICAL: Progress Tracking Requirements" section +- build.md: Detailed "Step 4c: MANDATORY - Update Progress After Task Completion" +- coder.md: New "Step 5: Update Progress (MANDATORY)" before reporting changes + ## [1.0.7] - 2024-12-22 ### Fixed diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 2224bab..7b495a2 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ab", "description": "Auto-Build: Spec-driven build orchestration with worktree isolation and session memory", - "version": "1.0.7", + "version": "1.0.9", "author": { "name": "ROA2WEB Team" } diff --git a/plugin/agents/coder.md b/plugin/agents/coder.md index 4d6042e..c092f19 100644 --- a/plugin/agents/coder.md +++ b/plugin/agents/coder.md @@ -68,13 +68,62 @@ After coding: - Verify changes match completion criteria - Ensure no unintended side effects -### 5. Report Changes +### 5. Update Progress (MANDATORY) + +**After completing the task, you MUST update BOTH files:** + +#### 5a. Update status.json + +Read and update `.auto-build/specs/{feature-name}/status.json`: +```json +{ + "status": "IMPLEMENTING", + "currentTask": {N+1}, + "tasksCompleted": {N}, + "totalTasks": {TOTAL}, + "updated": "{ISO timestamp}", + "history": [ + ...existing..., + {"status": "IMPLEMENTING", "at": "{timestamp}", "task": {N}, "title": "{title}", "completed": true} + ] +} +``` + +#### 5b. Update plan.md Progress Tracker + +Edit `.auto-build/specs/{feature-name}/plan.md` to mark task complete: + +1. In the Progress Tracker table, change: + ``` + | {N} | {Task title} | ⬜ Pending | | + ``` + to: + ``` + | {N} | {Task title} | ✅ Done | {timestamp} | + ``` + +2. In the task section, change: + ``` + - **Status**: ⬜ Pending + ``` + to: + ``` + - **Status**: ✅ Done ({timestamp}) + ``` + +**Both updates are MANDATORY. Skipping them breaks team collaboration and progress tracking.** + +### 6. Report Changes Provide a summary: ```markdown ## Task Completed: [Task Title] +### Progress Updated +- status.json updated: currentTask = {N+1} +- History entry added for task {N} + ### Changes Made #### `path/to/file1.ts` diff --git a/plugin/agents/planner.md b/plugin/agents/planner.md index 1a80a62..d1dd564 100644 --- a/plugin/agents/planner.md +++ b/plugin/agents/planner.md @@ -66,56 +66,54 @@ Create a plan.md with this structure: ```markdown # Implementation Plan: {feature-name} +**Status**: 🔄 In Progress +**Created**: {timestamp} +**Total Tasks**: {N} + +## Progress Tracker + +| # | Task | Status | Completed | +|---|------|--------|-----------| +| 1 | {Task 1 title} | ⬜ Pending | | +| 2 | {Task 2 title} | ⬜ Pending | | +| 3 | {Task 3 title} | ⬜ Pending | | +| ... | ... | ... | | + ## Overview + [Brief summary of the implementation approach] -## Task Order -1. Task 1 (no dependencies) -2. Task 2 (depends on 1) -3. Task 3 (depends on 1) -4. Task 4 (depends on 2, 3) -... - -## Detailed Tasks +## Tasks --- ### Task 1: [Clear Title] -**Objective**: [One sentence describing what this task accomplishes] - -**Files**: -- `path/to/file1.ts` - [what to do] -- `path/to/file2.ts` - [what to do] - -**Steps**: -1. [Specific step 1] -2. [Specific step 2] -3. [Specific step 3] - -**Dependencies**: None - -**Completion Criteria**: -- [ ] [How to verify this task is done] - -**Patterns to Follow**: -- See `existing/similar/file.ts` for reference +- **Status**: ⬜ Pending +- **Objective**: [One sentence describing what this task accomplishes] +- **Files**: + - `path/to/file1.ts` - [what to do] + - `path/to/file2.ts` - [what to do] +- **Steps**: + 1. [Specific step 1] + 2. [Specific step 2] + 3. [Specific step 3] +- **Dependencies**: None +- **Completion Criteria**: + - [ ] [How to verify this task is done] --- ### Task 2: [Clear Title] -**Objective**: [One sentence] - -**Files**: -- `path/to/file3.ts` - [what to do] - -**Steps**: -1. [Specific step 1] -2. [Specific step 2] - -**Dependencies**: Task 1 - -**Completion Criteria**: -- [ ] [Verification method] +- **Status**: ⬜ Pending +- **Objective**: [One sentence] +- **Files**: + - `path/to/file3.ts` - [what to do] +- **Steps**: + 1. [Specific step 1] + 2. [Specific step 2] +- **Dependencies**: Task 1 +- **Completion Criteria**: + - [ ] [Verification method] --- [Continue for all tasks...] diff --git a/plugin/commands/build.md b/plugin/commands/build.md index ee7f7a6..e57d199 100644 --- a/plugin/commands/build.md +++ b/plugin/commands/build.md @@ -5,212 +5,298 @@ argument-hint: # Build Feature from Specification -Orchestrate the complete implementation of a feature using its specification. This is the core command that coordinates planning, coding, and progress tracking. +Orchestrate the complete implementation of a feature using its specification. + +## IMPORTANT: Execute This Workflow Step-by-Step + +When this command is invoked, you MUST follow each step in order. After each task completion, you MUST update both status.json AND plan.md before proceeding. ## Input - **Feature name**: $ARGUMENTS (required, must match existing spec) -## Prerequisites +## Step 1: Load and Validate -- Spec must exist at `.auto-build/specs/{feature-name}/spec.md` -- Status must be `SPEC_COMPLETE` or `PLANNING_COMPLETE` or `IMPLEMENTING` +Execute immediately: -## Workflow +1. Read the spec file: + ``` + .auto-build/specs/{feature-name}/spec.md + ``` -### 1. Load Specification +2. Read the status file: + ``` + .auto-build/specs/{feature-name}/status.json + ``` -- Read `.auto-build/specs/{feature-name}/spec.md` -- Read `.auto-build/specs/{feature-name}/status.json` -- Validate spec exists and is complete -- If status is `IMPLEMENTING`, resume from current task +3. Read the plan file (if exists): + ``` + .auto-build/specs/{feature-name}/plan.md + ``` -### 2. Offer Worktree (for new builds) +4. Check status and determine next action: + - If `SPEC_COMPLETE` → Go to Step 2 (Worktree offer) then Step 3 (Planning) + - If `PLANNING_COMPLETE` → Go to Step 4 (Implementation) + - If `IMPLEMENTING` → Resume from `currentTask` in status.json -If status is `SPEC_COMPLETE`: +## Step 2: Offer Worktree (Only if SPEC_COMPLETE) + +Ask the user: ``` This feature may modify multiple files. Create an isolated git worktree? (recommended for larger features) [Yes] [No] ``` -If yes: -- Run: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/worktree-create.sh {feature-name}` -- Update status.json with worktree path -- Display next steps: - +If **Yes**: +1. Run: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/worktree-create.sh {feature-name}` +2. Update status.json with worktree path +3. Display: ``` ════════════════════════════════════════════════════════════════ - WORKTREE CREATED + WORKTREE CREATED - ACTION REQUIRED ════════════════════════════════════════════════════════════════ -✅ Worktree created at: ../ab-worktrees/{project}-{feature-name}/ +✅ Worktree: ../ab-worktrees/{project}-{feature-name}/ ✅ Branch: feature/ab-{feature-name} -⚠️ NEXT STEPS: - -1. Open a NEW VSCode window in the worktree: +⚠️ YOU MUST NOW: +1. Open NEW VSCode window: code ../ab-worktrees/{project}-{feature-name}/ -2. In the NEW window, continue the build: - +2. In the NEW window, run: /ab:build {feature-name} -──────────────────────────────────────────────────────────────── -Note: Specs and plans in .auto-build/ are already available in -the worktree (they're in git). No symlinks needed! ════════════════════════════════════════════════════════════════ ``` +4. **STOP** - Do not continue. Wait for user to switch directories. -- **STOP HERE** - Do not proceed with implementation in the current directory -- The user must switch to the worktree directory first +If **No**: Continue to Step 3. -### 3. Planning Phase +## Step 3: Create Plan (Only if SPEC_COMPLETE) -**If status is `PLANNING_COMPLETE`** (plan already exists): -- Skip directly to Implementation Loop (step 4) -- This happens when resuming in a worktree after plan was created in main repo +1. Update status.json: + ```json + { + "status": "PLANNING", + "updated": "{ISO timestamp}" + } + ``` -**If status is `SPEC_COMPLETE`**: +2. Load memory context: + - Read `.auto-build/memory/patterns.json` (if exists) + - Read `.auto-build/memory/gotchas.json` (if exists) -1. Load memory context (if exists): - - Read `.auto-build/memory/patterns.json` - - Read `.auto-build/memory/gotchas.json` - -2. Launch **planner** agent with: - - The complete spec.md content - - Relevant patterns from memory - - Instruction to create ordered implementation tasks - -3. The planner creates `.auto-build/specs/{feature-name}/plan.md`: +3. Create plan.md with this structure: ```markdown # Implementation Plan: {feature-name} + ## Progress Tracker + + | Task | Status | Completed | + |------|--------|-----------| + | Task 1: {title} | ⬜ Pending | | + | Task 2: {title} | ⬜ Pending | | + | ... | | | + ## Tasks - ### Task 1: [Title] - **Files**: file1.ts, file2.ts - **Description**: What to do - **Dependencies**: None + ### Task 1: {Title} + - **Status**: ⬜ Pending + - **Files**: file1.ts, file2.ts + - **Description**: What to do + - **Dependencies**: None - ### Task 2: [Title] - **Files**: file3.ts - **Description**: What to do - **Dependencies**: Task 1 + ### Task 2: {Title} + - **Status**: ⬜ Pending + - **Files**: file3.ts + - **Description**: What to do + - **Dependencies**: Task 1 ... ``` -4. Update status to `PLANNING_COMPLETE` - -### 4. Implementation Loop - -For each task in plan.md: - -1. Update status to `IMPLEMENTING`, set `currentTask` - -2. Display task info: - ``` - Task 3/7: Add API endpoint for user stats - Files: src/api/users.ts, src/types/user.ts +4. Update status.json: + ```json + { + "status": "PLANNING_COMPLETE", + "totalTasks": {number of tasks}, + "currentTask": 1, + "updated": "{ISO timestamp}", + "history": [..., {"status": "PLANNING_COMPLETE", "at": "{timestamp}"}] + } ``` -3. Launch **coder** agent with: - - Current task details - - Spec context - - Relevant patterns from memory - - Files to modify +5. Continue to Step 4. -4. After coder completes: - - Update status.json with task progress - - Ask: "Continue to next task? [Yes] [No] [Skip]" +## Step 4: Implementation Loop -5. Repeat until all tasks complete +**FOR EACH TASK, execute these sub-steps in order:** -### 5. Completion - -When all tasks done: -- Update status to `IMPLEMENTATION_COMPLETE` -- Display summary: - ``` - Build complete: {feature-name} - - Tasks completed: 7/7 - Files modified: 12 - - Next steps: - - Run QA review: /ab:qa-review - - Or test manually and save learnings: /ab:memory-save - ``` - -## State Machine +### 4a. Display Task Banner ``` -SPEC_COMPLETE - | - v -PLANNING (planner agent running) - | - v -PLANNING_COMPLETE - | - v -IMPLEMENTING (coder agent loop) - | - +---> [user skips/aborts] ---> PAUSED - | - v -IMPLEMENTATION_COMPLETE - | - v -[/ab:qa-review] ---> QA_REVIEW ---> COMPLETE +════════════════════════════════════════════════════════════════ + TASK {N}/{TOTAL}: {Task Title} +════════════════════════════════════════════════════════════════ +Status: Starting... +Files: {list of files} +──────────────────────────────────────────────────────────────── ``` -## Resume Logic - -If status is already `IMPLEMENTING`: -- Read `currentTask` from status.json -- Ask: "Resume from task {n}/{total}? [Yes] [Restart] [Cancel]" -- If yes: Continue from that task -- If restart: Reset to task 1 - -## Status JSON During Build +### 4b. Update Status to In-Progress +Write to `.auto-build/specs/{feature-name}/status.json`: ```json { - "feature": "user-dashboard", + "feature": "{feature-name}", "status": "IMPLEMENTING", - "currentTask": 3, - "totalTasks": 7, - "worktree": "../ab-worktrees/project-user-dashboard/", - "created": "2025-01-15T10:00:00Z", - "updated": "2025-01-15T14:30:00Z", + "currentTask": {N}, + "totalTasks": {TOTAL}, + "updated": "{ISO timestamp}", "history": [ - {"status": "SPEC_COMPLETE", "at": "..."}, - {"status": "PLANNING_COMPLETE", "at": "..."}, - {"status": "IMPLEMENTING", "at": "...", "task": 1}, - {"status": "IMPLEMENTING", "at": "...", "task": 2}, - {"status": "IMPLEMENTING", "at": "...", "task": 3} + ...existing..., + {"status": "IMPLEMENTING", "at": "{timestamp}", "task": {N}, "started": true} ] } ``` +### 4c. Execute Task + +Implement the task according to plan.md specifications. + +### 4d. MANDATORY: Update Progress Files + +**After completing each task, you MUST execute these updates before doing anything else:** + +**Update 1 - status.json:** +Write to `.auto-build/specs/{feature-name}/status.json`: +```json +{ + "feature": "{feature-name}", + "status": "IMPLEMENTING", + "currentTask": {N+1}, + "totalTasks": {TOTAL}, + "updated": "{ISO timestamp}", + "tasksCompleted": {N}, + "history": [ + ...existing..., + {"status": "IMPLEMENTING", "at": "{timestamp}", "task": {N}, "title": "{title}", "completed": true} + ] +} +``` + +**Update 2 - plan.md Progress Tracker:** +Edit the plan.md file to update the task status: +- Change `⬜ Pending` to `✅ Done` for the completed task +- Add completion timestamp + +Example edit in plan.md: +```markdown +## Progress Tracker + +| Task | Status | Completed | +|------|--------|-----------| +| Task 1: Setup | ✅ Done | 2025-01-15 14:30 | +| Task 2: API | ⬜ Pending | | +``` + +And in the task section: +```markdown +### Task 1: Setup +- **Status**: ✅ Done (2025-01-15 14:30) +``` + +### 4e. Display Completion and Confirm + +``` +════════════════════════════════════════════════════════════════ +✅ TASK {N}/{TOTAL} COMPLETED: {Task Title} +════════════════════════════════════════════════════════════════ + +Progress: {N}/{TOTAL} tasks done ({percentage}%) +Next task: {N+1}. {Next Task Title} + +Continue to next task? [Yes] [No] [Skip] +``` + +Wait for user confirmation before proceeding to next task. + +### 4f. Repeat + +Go back to 4a for the next task until all tasks are complete. + +## Step 5: Build Complete + +When all tasks are done: + +1. Update status.json: + ```json + { + "status": "IMPLEMENTATION_COMPLETE", + "currentTask": {TOTAL}, + "totalTasks": {TOTAL}, + "tasksCompleted": {TOTAL}, + "updated": "{ISO timestamp}", + "history": [..., {"status": "IMPLEMENTATION_COMPLETE", "at": "{timestamp}"}] + } + ``` + +2. Update plan.md header: + ```markdown + # Implementation Plan: {feature-name} + + **Status**: ✅ COMPLETE + **Completed**: {timestamp} + ``` + +3. Display summary: + ``` + ════════════════════════════════════════════════════════════════ + BUILD COMPLETE: {feature-name} + ════════════════════════════════════════════════════════════════ + + ✅ Tasks completed: {TOTAL}/{TOTAL} + 📁 Files modified: {count} + ⏱️ Duration: {time} + + NEXT STEPS: + 1. Test the implementation + 2. Run QA review: /ab:qa-review + 3. Save learnings: /ab:memory-save + + ════════════════════════════════════════════════════════════════ + ``` + +## Resume Logic + +If status is `IMPLEMENTING` with `currentTask > 1`: + +1. Display: + ``` + ════════════════════════════════════════════════════════════════ + RESUMING BUILD: {feature-name} + ════════════════════════════════════════════════════════════════ + + Previous progress: {tasksCompleted}/{TOTAL} tasks completed + Resume from: Task {currentTask} + + [Resume] [Restart from Task 1] [Cancel] + ``` + +2. If Resume: Continue from Step 4 at task {currentTask} +3. If Restart: Reset currentTask to 1, continue from Step 4 + +## Why Progress Tracking Matters + +- **Team collaboration**: Other developers can see progress and continue your work +- **Resume capability**: If interrupted, you can pick up where you left off +- **Visibility**: Users can check /ab:status to see current progress +- **History**: Complete audit trail of implementation + ## Error Handling -- If coder fails on a task: Mark task as failed, ask user to continue or fix manually -- If worktree creation fails: Continue without worktree, warn user -- If spec not found: "Spec not found. Create with: /ab:spec {name}" - -## Note on Team Collaboration - -Since specs and plans are stored in `.auto-build/` (committed to git), any team member can: -1. Clone the repo and see existing specs/plans -2. Continue implementation from where another developer left off -3. Share memory (patterns, gotchas) with the team - -After making progress, commit changes to share with team: -```bash -git add .auto-build/ -git commit -m "build: {feature-name} - completed task X/Y" -``` +- **Task fails**: Mark task as failed in history, ask user to fix manually or skip +- **Spec not found**: Display "Spec not found. Create with: /ab:spec {name}" +- **Plan not found but PLANNING_COMPLETE**: Re-run planning phase