FlineDev · fvadicamo · Dec 24, 2025
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -29,7 +29,8 @@ ContextKit/
 └── 🎯 Templates/                     # TEMPLATE DISTRIBUTION CENTER
     ├── Guidelines/                  # → GLOBAL CODING STANDARDS (copied by install.sh)
     │   ├── Swift.md                 # Swift patterns
-    │   └── SwiftUI.md               # SwiftUI patterns
+    │   ├── SwiftUI.md               # SwiftUI patterns
+    │   └── TaskCompletion.md        # Task completion criteria and ADR validation rules
     ├── Commands/                    # → CLAUDE CODE COMMANDS (get copied during /ctxk:proj:init)
     │   ├── proj/                    # Project management commands
     │   │   ├── init.md              # Project initialization
@@ -72,6 +73,8 @@ ContextKit/
     ├── Contexts/                    # → CONTEXT TEMPLATES (used by /ctxk:proj:init and /ctxk:proj:init-workspace)
     │   ├── Project.md               # Project-level Context.md with ContextKit configuration
     │   └── Workspace.md             # Workspace-level Context.md with client/company overrides
+    ├── Decisions/                   # → ARCHITECTURE DECISIONS (Context/Decisions/ created during /ctxk:proj:init)
+    │   └── ADR.md                   # Architecture Decision Record template
     ├── Backlog/                     # → BACKLOG TEMPLATES (used by /ctxk:bckl:add-idea and /ctxk:bckl:add-bug)
     │   ├── Ideas-Inbox.md           # New idea capture template with evaluation framework
     │   ├── Ideas-Backlog.md         # Prioritized idea backlog template with strategic organization
@@ -392,6 +395,7 @@ AGENT_LATEST_VERSION=$(sed -n '2p' ~/.ContextKit/Templates/Agents/check-modern-c
 - `build-project.md` - Execute builds, filter developer comments, report errors/warnings
 - `run-test-suite.md` - Execute complete test suite with build validation and structured failure reporting
 - `run-specific-test.md` - Execute specific test with build validation and focused failure analysis
+- `check-task-completion.md` - Validate task completion against ADRs and Spec
 
 **Incomplete Agents** (need rework for read-only reporting):
 - `check-accessibility.md` - VoiceOver labels, color contrast, dynamic type validation
@@ -767,6 +771,29 @@ Before committing template changes:
 
 ---
 
+## 🎯 ADR Integration System
+
+The repository includes a complete ADR (Architecture Decision Record) system for tracking deviations from planned specifications and managing architectural decisions:
+
+### Components
+- **Templates/Decisions/ADR.md** - Template for documenting architectural decisions and deviations
+- **Templates/Agents/check-task-completion.md** - Agent that validates task completion against ADRs
+- **Templates/Guidelines/TaskCompletion.md** - Validation criteria for task completion
+
+### Integration Points
+- **Context/Decisions/** directory created during `/ctxk:proj:init`
+- **start-working.md** loads ADRs at development session start
+- **Milestone validation** uses check-task-completion agent to verify ADR compliance
+- Deviations from Spec.md automatically trigger ADR creation prompts
+
+### Usage Pattern
+1. During planning (Spec/Tech/Steps): Decisions are documented
+2. During implementation (start-working): ADRs are loaded as context
+3. At milestones: check-task-completion validates against planning
+4. Deviations create ADRs for team visibility and future reference
+
+---
+
 ## 💡 Remember: Meta-Development Mindset
 
 You're building a system that creates development environments for other projects. Every template you create will guide AI assistants working on completely different codebases and project types.

diff --git a/Templates/Agents/check-task-completion.md b/Templates/Agents/check-task-completion.md
@@ -0,0 +1,215 @@
+---
+meta: "Template Version: 1 | ContextKit: 0.2.0 | Updated: 2025-12-24"
+name: check-task-completion
+description: Validate task completion criteria at milestones, detecting stub implementations and missing ADRs
+tools: Read, Grep, Glob
+color: yellow
+---
+
+# Agent: check-task-completion
+
+> [!WARNING]
+> **👩‍💻 FOR DEVELOPERS**: Do not edit the content above the developer customization section - changes will be overwritten during ContextKit updates.
+>
+> For project-specific customizations, use the designated section at the bottom of this file.
+>
+> Found a bug or improvement for everyone? Please report it: https://github.com/FlineDev/ContextKit/issues
+
+## Purpose
+
+Validate that tasks meet Definition of Done criteria before milestone commits.
+Analyze recent work against TaskCompletion.md guidelines and report violations.
+Detect stub implementations, missing integration points, and undocumented deviations.
+
+## Execution Flow (agent)
+
+0. **Read the "👩‍💻 DEVELOPER CUSTOMIZATIONS" section**
+   - Use `Grep` tool to find the start of the section
+   - Read everything below that line contained in this document til the end of the file
+   - Make sure to consider what was said there with high priority
+   - If anything conflicts with the rest of the workflow, prioritize the "developer customizations"
+
+### Phase 1: Load Context
+
+1. **Load TaskCompletion Guidelines**
+   - Use `Glob` to check: `Glob Context/Guidelines TaskCompletion.md`
+   - If found: Use `Read` to load project-specific completion criteria
+   - Extract validation checklist from Developer Customizations section
+   - Note any project-specific red flags or requirements
+
+2. **Load Existing ADRs**
+   - Use `Glob` to find ADRs: `Glob Context/Decisions *.md`
+   - Count existing ADRs for context
+   - Note most recent ADR number for reference
+
+### Phase 2: Analyze Recent Changes
+
+3. **Identify Changed Files**
+   - If FILES input provided: Parse provided file paths
+   - Otherwise: Check git status for uncommitted changes
+   - Focus on source files, exclude documentation-only changes
+
+4. **Scan for Stub Patterns**
+   - Use `Grep` to find stub indicators in changed files:
+     - `// handled elsewhere` - Assumed integration
+     - `// TODO:` or `// FIXME:` - Incomplete implementation
+     - `// will implement` - Deferred work
+     - Empty method bodies with only comments
+   - Record each violation with file path and line number
+
+5. **Scan for Integration Assumptions**
+   - Use `Grep` to find patterns like:
+     - Method calls to undefined methods
+     - References to external systems without verification
+     - `// connects to` or `// calls` comments without actual code
+   - For each reference found, attempt to verify target exists
+
+### Phase 3: Deviation Detection
+
+6. **Compare with Spec.md**
+   - Use `Glob` to find current feature: `Glob Context/Features/???-* Spec.md`
+   - If feature Spec.md found, note key requirements
+   - Flag significant changes that may need ADR documentation
+
+7. **Check ADR Coverage**
+   - For files with significant changes, check if ADR exists
+   - Look for commit messages referencing ADR-NNNN
+   - Flag potential undocumented deviations
+
+### Phase 4: Generate Report
+
+8. **Compile Validation Results**
+   - Count violations by category:
+     - Stub implementations
+     - TODO/FIXME without follow-up tasks
+     - Missing integration verification
+     - Potential undocumented deviations
+   - Determine overall status: PASS, FAIL, or WARNING
+
+9. **Generate Report**
+   - **If PASS**: Confirm all criteria met
+   - **If FAIL**: List violations with actionable fixes
+   - **If WARNING**: Note potential issues for review
+
+## Stub Pattern Detection
+
+### Patterns That Indicate Incomplete Work
+
+```
+// handled elsewhere
+// handled by [something]
+// TODO: implement
+// FIXME:
+// will implement later
+// placeholder
+// stub
+// mock implementation
+throw NotImplementedError
+pass  # Python empty block
+return nil // temporary
+```
+
+### Patterns That Are Acceptable
+
+```
+// TODO: tracked in Steps.md S###
+// See ADR-NNNN for rationale
+// Intentionally empty - no action needed
+// Deprecated - see ADR-NNNN
+```
+
+## Report Formats
+
+### Success Format
+```
+✅ Task Completion Validation PASSED
+
+All criteria met:
+- No stub implementations found
+- Integration points verified
+- ADRs exist for deviations (if any)
+
+Files analyzed: [count]
+Existing ADRs: [count]
+```
+
+### Failure Format
+```
+❌ Task Completion Validation FAILED
+
+Issues found:
+- File: src/services/DataManager.js:15
+  Issue: Stub method "cleanup()" with "// handled elsewhere"
+  Fix: Implement cleanup logic or remove if not needed
+
+- File: src/components/Form.js:42
+  Issue: TODO comment without follow-up task
+  Fix: Create task in Steps.md or backlog, or implement now
+
+- Deviation: Feature behavior differs from Spec.md Section 4.2
+  Fix: Create ADR to document the deviation
+
+Required actions before milestone commit:
+1. Resolve stub implementations
+2. Create ADRs for undocumented deviations
+3. Re-run validation
+```
+
+### Warning Format
+```
+⚠️ Task Completion Validation: REVIEW NEEDED
+
+Potential issues found:
+- File: src/utils/helpers.js:88
+  Warning: TODO comment - verify if task exists in backlog
+
+Recommendation: Review flagged items before proceeding.
+```
+
+## Error Conditions
+
+- **"No files to analyze"** → No changes detected, validation skipped
+- **"TaskCompletion.md not found"** → Using default validation rules
+- **"Context/Decisions/ not found"** → ADR tracking not initialized, recommend setup
+
+## Integration Points
+
+- **start-working.md**: Invokes this agent at milestone markers
+- **commit-changes**: May block commit if validation fails
+- **TaskCompletion.md**: Source of validation criteria
+- **ADR.md**: Template for creating missing ADRs
+
+## Success Messages
+
+### All Clear
+```
+🎉 Validation complete - ready for milestone commit!
+```
+
+### Issues Resolved
+```
+✅ All issues resolved. Validation now passes.
+```
+
+════════════════════════════════════════════════════════════════════════════════
+👩‍💻 DEVELOPER CUSTOMIZATIONS - EDITABLE SECTION
+════════════════════════════════════════════════════════════════════════════════
+
+This section is preserved during ContextKit migrations and updates.
+Add project-specific instructions, examples, and overrides below.
+
+## Project-Specific Stub Patterns
+<!-- Add language/framework-specific stub patterns to detect -->
+<!-- Example Swift: "fatalError(\"not implemented\")" -->
+<!-- Example Python: "raise NotImplementedError" -->
+
+## Integration Verification Exceptions
+<!-- Document cases where assumed integrations are acceptable -->
+<!-- Example: "External API calls mocked in development" -->
+
+## Custom Validation Rules
+<!-- Add any project-specific validation requirements -->
+<!-- Example: "All new components must have accessibility labels" -->
+
+## Override Behaviors
+<!-- Document any project-specific exceptions to default rules -->
diff --git a/Templates/Commands/impl/commit-changes.md b/Templates/Commands/impl/commit-changes.md
@@ -1,5 +1,5 @@
 # Commit Changes
-<!-- Template Version: 10 | ContextKit: 0.2.0 | Updated: 2025-10-02 -->
+<!-- Template Version: 11 | ContextKit: 0.2.0 | Updated: 2025-12-24 -->
 
 > [!WARNING]
 > **👩‍💻 FOR DEVELOPERS**: Do not edit the content above the developer customization section - changes will be overwritten during ContextKit updates.
@@ -51,6 +51,7 @@ Delegate to specialized commit-changes agent for intelligent git analysis, commi
 - **Quality Agents**: Works with other ContextKit agents for comprehensive development workflow
 - **Project Setup**: Requires `/ctxk:proj:init` to install the commit-changes agent
 - **Git Workflow**: Integrates with feature branch development and task completion
+- **ADR System**: Commit message may reference ADR numbers when changes involve documented decisions
 
 ════════════════════════════════════════════════════════════════════════════════
 👩‍💻 DEVELOPER CUSTOMIZATIONS - EDITABLE SECTION

diff --git a/Templates/Commands/impl/release-app.md b/Templates/Commands/impl/release-app.md
@@ -1,5 +1,5 @@
 # Release App to App Store
-<!-- Template Version: 3 | ContextKit: 0.2.0 | Updated: 2025-10-18 -->
+<!-- Template Version: 4 | ContextKit: 0.2.0 | Updated: 2025-12-24 -->
 
 > [!WARNING]
 > **👩‍💻 FOR DEVELOPERS**: Do not edit the content above the developer customization section - changes will be overwritten during ContextKit updates.
@@ -30,6 +30,11 @@ Execute iOS/macOS app release workflow with constitutional compliance validation
    - If uncommitted changes: ERROR "Commit all changes before release using /ctxk:impl:commit-changes" → EXIT
    - Use `Read` to verify `Context.md` exists: If missing, ERROR "Run /ctxk:proj:init to set up ContextKit first" → EXIT
 
+1.5 **Check ADR Compliance (Optional)**
+    - Use `Glob Context/Decisions *.md` to find ADRs
+    - If ADRs found: Review for any unresolved or blocking decisions
+    - If critical ADRs pending: WARN user "Unresolved ADRs found - review before release"
+
 ### Phase 2: Change Analysis and Version Planning
 2. **Analyze all changes since last release**
    - Use `Bash` to find latest release tag: `git tag --sort=-version:refname | head -1`

diff --git a/Templates/Commands/impl/release-package.md b/Templates/Commands/impl/release-package.md
@@ -1,5 +1,5 @@
 # Release Swift Package
-<!-- Template Version: 3 | ContextKit: 0.2.0 | Updated: 2025-10-18 -->
+<!-- Template Version: 4 | ContextKit: 0.2.0 | Updated: 2025-12-24 -->
 
 > [!WARNING]
 > **👩‍💻 FOR DEVELOPERS**: Do not edit the content above the developer customization section - changes will be overwritten during ContextKit updates.
@@ -52,6 +52,11 @@ Execute Swift Package release workflow with version management, release notes ge
    ```
    - If not authenticated: ERROR "Run 'gh auth login' to authenticate with GitHub."
 
+4.5 **Check ADR Compliance (Optional)**
+    - Use `Glob Context/Decisions *.md` to find ADRs
+    - If ADRs found: Review for any unresolved or blocking decisions
+    - If critical ADRs pending: WARN user "Unresolved ADRs found - review before release"
+
 ### Phase 2: Version Management
 
 5. **Extract Package Information**

diff --git a/Templates/Commands/impl/start-working.md b/Templates/Commands/impl/start-working.md
@@ -1,5 +1,5 @@
 # Begin Development with Context
-<!-- Template Version: 16 | ContextKit: 0.2.0 | Updated: 2025-10-18 -->
+<!-- Template Version: 17 | ContextKit: 0.2.0 | Updated: 2025-12-24 -->
 
 > [!WARNING]
 > **👩‍💻 FOR DEVELOPERS**: Do not edit the content above the developer customization section - changes will be overwritten during ContextKit updates.
@@ -118,6 +118,13 @@ Begin systematic development with context-aware setup, task analysis, and guided
    - If workspace Context.md found: Use `Read` tool to load workspace-specific overrides
    - **CRITICAL**: This context forms the foundation for understanding how to execute all Steps.md tasks
 
+3.5 **Load ADR Context**
+   - Use `Glob Context/Decisions *.md` to find existing Architecture Decision Records
+   - If ADRs found:
+     - Display: "📋 Active ADRs: [count] decisions loaded"
+     - Load recent decisions as context for implementation
+     - Reference ADRs when implementing features that follow established patterns
+
 4. **Verify Development Environment**
    ```bash
    git status --porcelain || echo "⚠️ Git not available"
@@ -359,6 +366,16 @@ Begin systematic development with context-aware setup, task analysis, and guided
     - Verify the checkbox update was successful before proceeding
     - **This enables session continuity**: Any new session can resume by reading Steps.md
 
+9.5 **Check for Deviations**
+    - If significant changes made to feature files:
+      - Compare implementation with Spec.md requirements
+      - If behavior differs from specification:
+        - Prompt user: "Potential deviation detected. Create ADR to document?"
+        - If user confirms:
+          - Determine next ADR number from `Glob Context/Decisions *.md`
+          - Create ADR from template in Context/Decisions/
+          - Reference ADR in subsequent commit message
+
 10. **Continue Sequential Execution - No Exit Until All Done**
     - **IMMEDIATELY after updating Steps.md**: Check for next sequential task
     - **Do NOT exit** - continue with next task in sequence according to Steps.md
@@ -414,6 +431,17 @@ Begin systematic development with context-aware setup, task analysis, and guided
       - The agent handles git analysis, formatting, and commit message generation
       - Users can also manually run /ctxk:impl:commit-changes command
 
+    - **Milestone Validation Procedure**:
+      - At 🏁 MILESTONE markers, BEFORE commit:
+        - Use Task tool to launch `check-task-completion` agent
+        - Input: Git diff since last milestone
+        - If validation FAILS:
+          - Display violations to user
+          - Options: Fix now / Create ADR and proceed / Skip (emergency only)
+        - If validation PASSES:
+          - Proceed with commit-changes agent
+          - Note validation status in commit message
+
     - **When to use run-test-* agents**:
       - When Steps.md Phase 5 tasks specify test execution
       - After implementing new test files
@@ -450,6 +478,8 @@ Begin systematic development with context-aware setup, task analysis, and guided
 - **Git Workflow**: Works within feature branch structure established by planning commands
 - **Development Hooks**: Enables PostToolUse formatting and SessionStart version checking
 - **Task Tracking**: Updates Steps.md progress tracking for systematic development workflow
+- **ADR System**: Loads existing ADRs at session start; detects deviations and prompts for ADR creation
+- **Validation Agent**: Uses `check-task-completion` agent at milestone markers before commits
 
 ## Success Messages