Feature Request: Automatic Task Completion Tracking

[doozie-akshay]

Feature Request: Automatic Task Completion Tracking

Is your feature request related to a problem?

Yes. Currently, when using spec-kit to execute tasks from tasks.md, there's no automatic way to mark tasks as completed. Users must manually update markdown checkboxes from - [ ] to - [x] after completing tasks, which creates friction and leads to inconsistent tracking.

Current Manual Workflow:

# Before execution
- [ ] T009 [P] Contract test POST /api/v1/auth/otp/request in tests/Feature/Auth/OtpRequestTest.php

# After execution (manual update required)
- [x] T009 [P] Contract test POST /api/v1/auth/otp/request in tests/Feature/Auth/OtpRequestTest.php

Describe the solution you'd like

Add automatic task completion tracking that integrates with existing spec-kit scripts:

1. Enhanced Task Execution Scripts

   ./scripts/execute-task.sh T009
   # Should automatically mark T009 as complete in tasks.md

2. New Task Management Utilities

   ./scripts/mark-task-complete.sh T009
   ./scripts/get-task-status.sh T009
   ./scripts/list-completed-tasks.sh

3. Optional Metadata Enhancement

   - [x] T009 [P] Contract test POST /api/v1/auth/otp/request
     <!-- COMPLETED: 2025-09-11T14:30:00Z -->

4. Configuration Options

   # .spec-kit.yml
   task_tracking:
     auto_complete: true
     include_metadata: true
     include_timestamps: true

Benefits:

• ✅ Seamless workflow integration
• 📊 Real-time progress tracking
• 🤖 Better AI agent coordination
• 👥 Improved team collaboration
• 📈 Automatic progress reporting

Use Case Example:

# AI agent or developer executes multiple tasks
./scripts/execute-tasks.sh T009-T026
# ✅ All 18 tasks automatically marked complete
# 📊 Progress: 26/79 tasks completed (33%)

Technical Requirements:

• Backwards compatible with existing tasks.md format
• Atomic updates for concurrent task execution
• Cross-platform support (macOS, Linux, Windows)
• Integration with existing spec-kit script infrastructure

Real-World Context:
I'm actively using spec-kit for a Laravel MVP project and have completed 26 tasks (T009-T034). Manual task marking has been time-consuming and error-prone. This feature would significantly improve the development experience.

Additional context
This feature would be especially valuable for:

• Large projects with 50+ tasks
• Teams using AI agents for task execution
• Projects requiring accurate progress tracking
• CI/CD integration scenarios

The implementation should leverage spec-kit's existing script infrastructure and maintain the simplicity of markdown-based task management while adding automation capabilities.

[Silthus]

I like the idea and had great success with other prompts doing this as well.

I would suggest adding an in progress marker as well in the form of [~] when a task starts. This way the status will always be clear, especially when executing tasks with many parallel agents.

Maybe a more general update-task-status.sh script would be best?

[danwashusen]

I'm currently solving this with an additional review task to ensure the LLM hasn't lied to you about the completion status (I'm looking at you Claude Code)...

While running something along the lines of implement specs/001-bootstrap/plan.md, which involved lots of tasks to create a bunch of bootstrapping files, Claude Code output a message something like "This is taking a while, I'm going to complete the remaining tasks efficiently using established patterns..." then proceeded to YOLO through the rest of the tasks with a focus on getting it done...

After Claude had reported "Implementation Complete ✅" I ran a code review instruction in a new session which pointed out half the stuff was missing...

I'm currently playing with custom /implement-tasks and /validate-tasks commands (see attached), but still a work in progress... See https://gist.github.com/danwashusen/087ea9e4e554b4a1713bdfc984a0dcc3.

Example output for /implement-tasks:

📊 Implementation Summary

  Status: Implementation Complete | Partial Verification | TypeScript Issues Detected

  Progress: 7/7 remaining tasks implemented (100%)
  - ✅ T047: Frontend structure adapted to monorepo
  - ✅ T048: API integration with browser logging
  - ✅ T052-T062: Critical code review fixes implemented
  - ✅ T050: CLAUDE.md documentation updated
  - 🟡 T051: Quickstart verification shows TypeScript compilation errors

  Quality Gates:
  - TypeScript: ❌ Some packages have compilation errors
  - ESLint: ⚠️  Not tested due to TypeScript failures
  - Tests: ⚠️  Not tested due to TypeScript failures
  - Architecture: ✅ All patterns implemented

  Session Metrics:
  - Time: ~45 minutes
  - Files Created: 15+
  - Files Modified: 10+
  - Major Features: Frontend app, API integration, security fixes

  Completed Implementation:
  1. Frontend Application: Complete React app with Clerk auth, shadcn/ui, API integration
  2. API Integration: Type-safe client with error handling and browser logging
  3. Security Fixes: SOC 2 audit fields, secure ID generation, parameter logging
  4. Architecture: User model with repository pattern, transaction support
  5. Documentation: Updated CLAUDE.md with current project status

  Blockers Identified:
  - TypeScript compilation errors in shared-data package (field name mismatches)
  - Test files have outdated type definitions
  - Some packages have import/export issues

  Next Steps:
  1. Fix TypeScript compilation errors in shared-data models
  2. Update test files to match new type definitions
  3. Run full test suite verification
  4. Complete lint and build verification

  The core architecture and functionality are implemented. The remaining issues are primarily TypeScript configuration and test
   file updates that need alignment with the new data models.

Example output for /validate-tasks:

⏺ Summary

  Status: Review Complete (86.3% tasks implemented)

  Implementation Progress: 44/51 tasks complete (86.3%)
  - ✅ Completed phases: Phase 3.1 (Setup), Phase 3.2 (Tests), Phase 3.3 (Core)
  - 🚧 In-progress phases: Phase 3.4 (Integration), Phase 3.5 (Polish)

  Gates: All Early Gates passed
  - ✅ Design Documents Gate: All required docs exist (plan.md, research.md, data-model.md, contracts/)
  - ✅ Plan-of-Record Gate: Valid plan.md referenced
  - ✅ Unknowns Gate: No [NEEDS CLARIFICATION] items remain
  - ✅ TDD Ordering Gate: All tests precede implementation
  - ✅ Task Completion Audit Gate: Comprehensive completion analysis completed

  Checklist Results:
  - ✅ Structure & Completeness: Tasks properly numbered and detailed
  - ✅ Artifact Mapping: All contracts and models have corresponding tasks
  - ✅ Architecture Alignment: Service Locator, Repository pattern, structured logging implemented
  - ✅ Constitution Check: SOC 2 requirements largely addressed
  - ✅ Execution Readiness: Most tasks implemented with high quality
  - ✅ Task Completion: 86% complete with evidence-based analysis

  Strengths:
  - Excellent TDD compliance with comprehensive test coverage
  - High-quality architectural implementation (Service Locator, Repository pattern)
  - Strong Constitutional adherence (structured logging, error handling)
  - Well-organized monorepo structure with proper TypeScript configuration

  Gaps & Risks:
  - Minor: Frontend integration incomplete (T047-T048 partial)
  - Minor: Documentation and verification steps pending (T050-T051)
  - Major: Service locator disposal race condition identified
  - Major: Request ID generation uses Math.random() instead of crypto

  Code Review Report: Identified 11 findings across security, performance, and maintainability categories. Most critical issues involve secure ID generation and transaction handling. The existing code review feedback from Phase 3.6 provides detailed remediation steps.

  Open Questions: None - all NEEDS CLARIFICATION items resolved

  Alignment Notes: Implementation closely follows plan.md, research.md architecture decisions, and Constitutional requirements. The Development Environment Bootstrap is substantially complete and ready for final polish tasks.

Output of validate-tasks.md after several iterations:

⏺ Task Validation Complete ✅

  Summary

  Status: Review Complete (51/51 tasks implemented - 100%)

  Validation Results

  Early Gates ✅ ALL PASSED

  - Design Documents Gate ✅ All required docs present (research.md, plan.md, data-model.md, contracts/)
  - Plan-of-Record Gate ✅ Implementation plan referenced and available
  - Unknowns Gate ✅ No remaining clarification items
  - TDD Ordering Gate ✅ Tests precede implementation (Phase 3.2 → 3.3)

  Implementation Progress ✅ COMPLETE

  - Total Tasks: 51
  - Completed: 51 (100%)
  - All Phases Complete: Setup → Tests → Core → Integration → Polish

  Quickstart Coverage ✅ COMPREHENSIVE

  - Total Scenarios: 8
  - Mapped to Tasks: 8 (100%)
  - All verification steps have corresponding implementation tasks

  S-Tier Code Review ✅ EXCELLENT QUALITY

  Constitutional Compliance Verified:
  - ✅ Library-First Architecture (8 packages with CLI interfaces)
  - ✅ TDD Mandatory (Tests written first, comprehensive coverage)
  - ✅ Service Locator Pattern (Per-request containers, no singletons)
  - ✅ Structured Logging (Pino with correlation IDs)
  - ✅ Repository Pattern (SQLite → DynamoDB migration path preserved)

  Security & Performance:
  - ✅ SOC 2 audit fields in all database tables
  - ✅ Cryptographic UUID generation
  - ✅ Rate limiting with memory cleanup
  - ✅ Prepared statement caching
  - ✅ Proper CORS configuration

  Architecture Strengths:
  - Service boundaries properly separated
  - Error handling with correlation tracking
  - Build system optimized for monorepo
  - Health checks for monitoring
  - Production-ready logging pipeline

  The Development Environment Bootstrap is complete and production-ready with all 51 tasks implemented to constitutional standards.

[doozie-akshay]

I’ve been thinking about whether this should live in core or as part of a plug-in / extension system. My take:
• Core should stay focused on primitives that every agent spec will need (schema, lifecycle, validation, security).
• Features like in-agent experience feel more context-specific and fast-evolving, which makes them better candidates for a plug-in approach.
• Starting this as an extension also reduces friction — we can validate usefulness and iterate quickly, with the option to “graduate” into core later if adoption proves universal.

I’m happy to spec this out and contribute in either direction, but my recommendation is to begin as a plug-in, with clear extension points for in-agent UX