diff --git a/CLAUDE.md b/CLAUDE.md index b6555fc..a5f9d8d 100644 --- 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 new file mode 100644 index 0000000..64c9311 --- /dev/null +++ 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 + + + + +## Integration Verification Exceptions + + + +## Custom Validation Rules + + + +## Override Behaviors + diff --git a/Templates/Commands/impl/commit-changes.md b/Templates/Commands/impl/commit-changes.md index f14a38f..a71eea6 100644 --- a/Templates/Commands/impl/commit-changes.md +++ b/Templates/Commands/impl/commit-changes.md @@ -1,5 +1,5 @@ # Commit Changes - + > [!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 index b0e5659..d059e96 100644 --- a/Templates/Commands/impl/release-app.md +++ b/Templates/Commands/impl/release-app.md @@ -1,5 +1,5 @@ # Release App to App Store - + > [!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 index c3eb843..b936b49 100644 --- a/Templates/Commands/impl/release-package.md +++ b/Templates/Commands/impl/release-package.md @@ -1,5 +1,5 @@ # Release Swift Package - + > [!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 index 2e1644d..7fdf1b1 100644 --- a/Templates/Commands/impl/start-working.md +++ b/Templates/Commands/impl/start-working.md @@ -1,5 +1,5 @@ # Begin Development with Context - + > [!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 diff --git a/Templates/Commands/plan/1-spec.md b/Templates/Commands/plan/1-spec.md index 78f4f82..6563690 100644 --- a/Templates/Commands/plan/1-spec.md +++ b/Templates/Commands/plan/1-spec.md @@ -1,5 +1,5 @@ # Create Feature Specification - + > [!WARNING] > **👩‍💻 FOR DEVELOPERS**: Do not edit the content above the developer customization section - changes will be overwritten during ContextKit updates. @@ -228,6 +228,17 @@ Initialize feature specification by validating setup, confirming feature naming, ### Phase 3: Template Setup & Execution +7.5 **Load ADR Context for Specification** + - Create Context/Decisions/ directory if not exists: + ```bash + mkdir -p Context/Decisions + ``` + - Use `Glob Context/Decisions *.md` to find existing decisions + - If ADRs found: + - Review relevant ADRs that might affect new feature requirements + - Reference established patterns when creating specification + - If requirements conflict with existing ADRs, note for later ADR creation + 8. **Generate Sequential Feature Number & Create Workspace** ```bash # Find highest existing number in Context/Features/ (handles both files and folders with same prefix) @@ -349,6 +360,7 @@ Initialize feature specification by validating setup, confirming feature naming, - **Team Collaboration**: Creates committed specification for team review and stakeholder validation - **Git Integration**: Establishes feature branch for systematic development workflow - **Workspace Integration**: Template inherits coding standards and constitutional overrides from workspace Context.md +- **ADR System**: Creates Context/Decisions/ directory; loads existing ADRs to inform specification ## Success Messages diff --git a/Templates/Commands/plan/2-research-tech.md b/Templates/Commands/plan/2-research-tech.md index 14d4ce6..f9f69e9 100644 --- a/Templates/Commands/plan/2-research-tech.md +++ b/Templates/Commands/plan/2-research-tech.md @@ -1,5 +1,5 @@ # Technical Planning: Research & Architecture - + > [!WARNING] > **👩‍💻 FOR DEVELOPERS**: Do not edit the content above the developer customization section - changes will be overwritten during ContextKit updates. @@ -41,6 +41,14 @@ ``` → END (exit with error) +2.5 **Load ADR Context** + - Use `Glob Context/Decisions *.md` to find existing Architecture Decision Records + - If ADRs found: + - Understand architectural decisions already made + - Identify constraints from previous choices + - Technical choices in Tech.md must align with or explicitly supersede existing ADRs + - Reference relevant ADRs in architecture section + ### Phase 2: Template Execution 3. **Copy Technical Planning Template** @@ -142,6 +150,7 @@ - **Team Collaboration**: Creates committed technical plan for team review and development guidance - **Git Integration**: Works within existing feature branch for systematic development workflow - **Workspace Integration**: Template inherits coding standards and constitutional overrides from workspace Context.md +- **ADR System**: Loads existing ADRs to understand architectural constraints; technical choices must align with or supersede existing ADRs ## Success Messages diff --git a/Templates/Commands/plan/3-steps.md b/Templates/Commands/plan/3-steps.md index 785ec1a..1f7e2da 100644 --- a/Templates/Commands/plan/3-steps.md +++ b/Templates/Commands/plan/3-steps.md @@ -1,5 +1,5 @@ # Create Task List - + > [!WARNING] > **👩‍💻 FOR DEVELOPERS**: Do not edit the content above the developer customization section - changes will be overwritten during ContextKit updates. @@ -46,6 +46,13 @@ Generate implementation task breakdown by detecting current feature, validating ``` → END (exit with error) +2.5 **Load ADR Context** + - Use `Glob Context/Decisions *.md` to find existing Architecture Decision Records + - If ADRs found: + - Understand patterns established in previous features + - Reference ADRs when creating tasks that follow established patterns + - If feature will deviate from Spec.md or establish new patterns, include ADR creation task + ### Phase 2: Template Setup & Execution 3. **Copy Steps Template** @@ -61,6 +68,9 @@ Generate implementation task breakdown by detecting current feature, validating - Use tools (`Read`, `Edit`) as directed by the template instructions - **Template execution**: The copied Steps.md handles all task breakdown, dependency analysis, and parallel execution planning - **Progress tracking**: User can see checkboxes being completed in the copied file + - **ADR Integration**: When generating validation tasks, include: + - ADR review task: Verify all deviations from Spec.md documented in ADRs + - Task completion validation: Include check-task-completion agent at milestones 5. **Extract and Resolve Clarification Points Interactively** - Use `Grep` tool to find clarification markers in Steps.md: `Grep "🚨 \\[NEEDS CLARIFICATION:" [numbered-feature-directory]/Steps.md` @@ -122,6 +132,8 @@ Generate implementation task breakdown by detecting current feature, validating - **Team Collaboration**: Creates committed implementation plan for team review and development coordination - **Git Integration**: Works within existing feature branch for systematic development workflow - **Workspace Integration**: Template inherits coding standards and constitutional overrides from workspace Context.md +- **ADR System**: Loads existing ADRs to inform task generation; includes ADR creation tasks when patterns established +- **Validation Agent**: Integrates check-task-completion agent at milestone markers ## Success Messages diff --git a/Templates/Commands/proj/init.md b/Templates/Commands/proj/init.md index a4c5670..cd98142 100644 --- a/Templates/Commands/proj/init.md +++ b/Templates/Commands/proj/init.md @@ -224,7 +224,7 @@ Initialize current project with ContextKit development workflow system. Sets up 11. **Create Directory Structure** ```bash - mkdir -p .claude/commands/ctxk .claude/agents/ctxk Context/Features Context/Backlog Context/Scripts + mkdir -p .claude/commands/ctxk .claude/agents/ctxk Context/Features Context/Backlog Context/Scripts Context/Decisions ``` 12. **Copy Workflow Command Templates (Local Only)** @@ -495,6 +495,7 @@ Initialize current project with ContextKit development workflow system. Sets up ✓ Context.md - Comprehensive project analysis with validated build/test commands ✓ Context/Features/ - Systematic feature development ✓ Context/Backlog/ - Ideas and bugs with evaluation frameworks + ✓ Context/Decisions/ - Architecture Decision Records (ADRs) ✓ Context/Guidelines/ - Development standards relevant to project type ✓ Context/Scripts/ - Code formatting and status automation ✓ .claude/commands/ctxk/ - Workflow commands (plan/, impl/, bckl/) - global proj/ commands remain global diff --git a/Templates/Contexts/Project.md b/Templates/Contexts/Project.md index b7ee371..a6c00b1 100644 --- a/Templates/Contexts/Project.md +++ b/Templates/Contexts/Project.md @@ -1,5 +1,5 @@ # Project Context Template - + ## Description Project-level Context.md template providing project-specific investigation, development commands, project structure analysis, and ContextKit workflow configuration. @@ -182,6 +182,14 @@ Project-level Context.md template providing project-specific investigation, deve **Formatters** (configured): [Formatter configurations found and their settings] +## ContextKit Directories + +- **Context/Features/** - Feature specifications, technical plans, and implementation steps +- **Context/Backlog/** - Ideas and bugs with evaluation frameworks +- **Context/Decisions/** - Architecture Decision Records tracking deviations and strategic decisions +- **Context/Guidelines/** - Development standards relevant to project type +- **Context/Scripts/** - Code formatting and status automation + ## Development Guidelines **Applied Guidelines**: [List guidelines copied during project setup] diff --git a/Templates/Decisions/ADR.md b/Templates/Decisions/ADR.md new file mode 100644 index 0000000..82f2127 --- /dev/null +++ b/Templates/Decisions/ADR.md @@ -0,0 +1,152 @@ +# Architecture Decision Record Template + + +## Description +Template for creating Architecture Decision Records (ADRs) to document +significant architectural decisions and deviations from specifications. +ADRs provide a lightweight mechanism for capturing the context, decision, +and consequences of architecturally significant choices. + +════════════════════════════════════════════════════════════════════════════════ +║ 🤖 EXECUTION FLOW - ADR CREATION +════════════════════════════════════════════════════════════════════════════════ +║ +║ ## When to Create an ADR +║ +║ Create an ADR when: +║ - Making a significant architectural decision +║ - Deviating from the original Spec.md during implementation +║ - Choosing between multiple valid technical approaches +║ - Establishing a pattern that should be followed consistently +║ - Changing a previous decision (superseding an existing ADR) +║ +║ ## Execution Flow (main) +║ +║ ### Phase 1: Determine ADR Number +║ +║ 1. **Find Next Available Number** +║ - Use `Glob` tool: `Glob Context/Decisions *.md` +║ - Extract highest existing NNNN prefix from filenames +║ - Increment by 1 for new ADR +║ - If no existing ADRs, start with 0001 +║ +║ ### Phase 2: Create ADR File +║ +║ 2. **Copy Template** +║ - Create new file: `Context/Decisions/NNNN-decision-title.md` +║ - Use kebab-case for decision title (e.g., `0003-increase-power-up-duration.md`) +║ - Copy content from template section below +║ +║ 3. **Fill Required Sections** +║ - **Status**: Set to "Accepted" for implementation decisions +║ - **Context**: Document the problem or situation +║ - **Decision**: State what was decided +║ - **Consequences**: List trade-offs and implications +║ - **Related**: Link to features, files, and superseded ADRs +║ +║ ### Phase 3: Integration +║ +║ 4. **Reference in Commit Message** +║ - Include "ADR-NNNN" in commit message for traceability +║ - Example: "feat: increase power-up duration (ADR-0003)" +║ +║ 5. **Update Spec.md Revision History (if deviation)** +║ - If ADR documents a deviation from Spec.md +║ - Add entry to Spec.md Revision History section +║ - Format: `| Date | Change Description | ADR-NNNN |` +║ +════════════════════════════════════════════════════════════════════════════════ + +--- + +## ADR Template Content + +Copy the content below when creating a new ADR: + +--- + +# ADR-NNNN: [Decision Title] + +## Status +[Proposed | Accepted | Deprecated] + +## Context +[What is the issue or situation that motivated this decision?] + +[If this is a deviation from specification, reference the original requirement:] +[See Context/Features/###-FeatureName/Spec.md Section X.Y] + +## Decision +[What was decided?] + +[Include specific details:] +- [Specific choice or value] +- [Implementation approach] +- [Patterns to follow] + +## Consequences + +**Benefits:** +- [What becomes easier or better?] + +**Trade-offs:** +- [What becomes more difficult?] +- [What are we giving up?] + +**Risks:** +- [What could go wrong?] + +## Related + +- **Supersedes**: [ADR-NNNN, ADR-MMMM - if this decision replaces previous ones, leave empty otherwise] +- **Feature**: [Context/Features/###-FeatureName/] +- **Files Affected**: [src/path/to/file.ext, src/other/file.ext] +- **Spec Section**: [Context/Features/###-FeatureName/Spec.md Section X.Y - if deviation] + +--- + +## Error Conditions + +- **"No Context/Decisions/ directory"** → Create directory with `mkdir -p Context/Decisions` +- **"ADR number conflict"** → Re-check Glob results, use next available number +- **"Missing context section"** → ADR incomplete, add problem description + +## Integration Points + +- **Planning Commands**: `/ctxk:plan:*` commands load existing ADRs for context +- **Implementation**: `/ctxk:impl:start-working` suggests ADR creation on deviations +- **Quality Agents**: `check-task-completion` verifies ADRs exist for deviations +- **Commit Workflow**: ADR numbers referenced in commit messages + +## Success Messages + +### ADR Created +``` +✅ ADR-NNNN created: Context/Decisions/NNNN-decision-title.md + +📋 Decision documented: + Status: Accepted + Title: [Decision Title] + Supersedes: [Previous ADRs if any] + +💡 Remember to reference ADR-NNNN in your commit message. +``` + +════════════════════════════════════════════════════════════════════════════════ +👩‍💻 DEVELOPER CUSTOMIZATIONS - EDITABLE SECTION +════════════════════════════════════════════════════════════════════════════════ + +This section is preserved during ContextKit migrations and updates. +Add project-specific instructions, examples, and overrides below. + +## Project-Specific ADR Categories + + +## Additional Required Sections + + +## ADR Review Process + + +## Override Behaviors + diff --git a/Templates/Features/Spec.md b/Templates/Features/Spec.md index a9effcd..ce7e69d 100644 --- a/Templates/Features/Spec.md +++ b/Templates/Features/Spec.md @@ -1,5 +1,5 @@ # Feature Specification Template - + ## Description Feature specification template providing systematic business requirements generation with progress tracking and quality validation. @@ -25,6 +25,13 @@ Feature specification template providing systematic business requirements genera ║ - For workspace projects: Use `Read` tool on workspace Context.md for additional standards ║ - Document all loaded guidelines for comprehensive development pattern application ║ +║ 2.5 **Load Existing Architectural Decisions** +║ - Use `Glob Context/Decisions *.md` to find existing ADRs +║ - If ADRs found: +║ - Review decisions that might impact this feature +║ - Note if feature aligns with or challenges existing decisions +║ - Reference relevant ADRs in specification if applicable +║ ║ 3. **Extract User Requirements from Original Input** ║ - Parse original feature description provided by user ║ - Identify key concepts: primary functionality, user actors, data involved, platform targets diff --git a/Templates/Features/Steps.md b/Templates/Features/Steps.md index fe22c82..f8d5115 100644 --- a/Templates/Features/Steps.md +++ b/Templates/Features/Steps.md @@ -1,5 +1,5 @@ # Implementation Steps: [Feature from Tech.md] - + ## Description Implementation task breakdown template providing systematic S001-S999 task enumeration with parallel execution markers and dependency analysis for iOS/macOS development workflows. @@ -46,6 +46,12 @@ Implementation task breakdown template providing systematic S001-S999 task enume ║ - Extract: user stories, functional requirements, acceptance criteria ║ - Map requirements to implementation tasks with research-informed constraints ║ +║ 2.5 **Load ADR Context** +║ - Use `Glob Context/Decisions *.md` to find existing Architecture Decision Records +║ - If ADRs found: +║ - Reference established patterns when creating implementation tasks +║ - Note architectural constraints from previous decisions +║ ║ 3. **Analyze Implementation Complexity and Scope** ║ - Count: new files, modified files, new APIs, tests needed ║ - If scope > 25 tasks: WARN "Consider breaking into smaller features" @@ -318,6 +324,11 @@ Implementation task breakdown template providing systematic S001-S999 task enume - **Dependencies**: [All implementation tasks] - **Notes**: Use Task tool with build-project agent to validate compilation, check warnings, and ensure dependencies resolve correctly +- [ ] **S023** [P] [AI Generated: ADR compliance validation] + - **Path**: Verify deviations from Spec.md documented in Context/Decisions/ + - **Dependencies**: [Implementation tasks] + - **Notes**: Check all significant changes have corresponding ADRs; run check-task-completion agent + **🏁 MILESTONE: Automated Validation Complete** *Use Task tool with commit-changes agent to commit: "Complete [feature] automated testing and quality validation"* @@ -526,6 +537,8 @@ For complex Xcode operations (target creation, scheme setup), use standardized f - [ ] Error handling and edge cases covered in task breakdown? - [ ] Performance requirements addressed in implementation plan? - [ ] Platform-specific requirements integrated throughout phases? +- [ ] All deviations from Spec.md documented in Context/Decisions/ ADRs? +- [ ] ADRs reference affected Spec.md sections? ### Quality Standards - [ ] Each task specifies exact file paths and dependencies? diff --git a/Templates/Features/Tech.md b/Templates/Features/Tech.md index 7d2c323..639f93a 100644 --- a/Templates/Features/Tech.md +++ b/Templates/Features/Tech.md @@ -1,5 +1,5 @@ # Technical Planning: [Feature from Spec.md] - + ## Description Technical planning template combining research and architecture phases into single workflow. Executes systematic knowledge acquisition followed by technical architecture design in one continuous flow. @@ -22,6 +22,13 @@ Technical planning template combining research and architecture phases into sing ║ - Extract: current tech stack, existing dependencies, architecture patterns ║ - For workspace projects: Use `Read` tool on workspace Context.md for tech preferences ║ +║ 2.5 **Check Alignment with Existing ADRs** +║ - Use `Glob Context/Decisions *.md` to find existing decisions +║ - If ADRs found: +║ - Verify proposed architecture aligns with existing ADRs +║ - If conflict found: Document in Architecture section as deviation candidate +║ - Reference relevant ADRs in technical decisions +║ ║ 3. **Identify Research Targets** ║ - Scan specification for mentioned technologies (frameworks, libraries, APIs) ║ - Identify external services and integration requirements diff --git a/Templates/Guidelines/TaskCompletion.md b/Templates/Guidelines/TaskCompletion.md new file mode 100644 index 0000000..e5e4bdd --- /dev/null +++ b/Templates/Guidelines/TaskCompletion.md @@ -0,0 +1,213 @@ +# Task Completion Guidelines + + +> [!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. + +## Overview + +Strategic guidance for determining when implementation tasks are truly complete. +Focus on preventing partial implementations that compile but don't function. + +This guideline addresses a common problem: tasks marked complete when code compiles, +but features are non-functional due to missing integration points or stub implementations. + +--- + +## 1. Code Completeness + +### ✅ Prefer: Verified Integration Points + +- Integration points exist AND have been tested in real scenarios +- No "// handled elsewhere" comments without verified code at target location +- Manual testing confirms the feature actually works, not just compiles +- All method calls to external systems verified to exist and function +- Dependencies inject properly and produce expected results + +### ❌ Avoid: Assumed Integrations + +- Stub methods with comments assuming implementation exists elsewhere +- Code compiles but feature is non-functional when tested +- TODO comments without explicit follow-up tasks in Steps.md or backlog +- "Will connect this later" patterns without documented tasks +- Empty method bodies with "// handled by..." comments + +**Example - Generic Pattern**: +```javascript +// ❌ Avoid - Assumed integration +class DataManager { + invalidate(key) { + // Invalidation handled by background task ← Integration assumed but not verified + this.markStale(key) + } +} + +// ✅ Prefer - Verified integration +class DataManager { + invalidate(key) { + this.markStale(key) + this.scheduleCleanup() // ← Method exists and has been tested + } +} +``` + +--- + +## 2. Integration Verification + +### ✅ Prefer: Explicit Integration Testing + +- Break complex features into base implementation + integration subtasks +- Use S###-I enumeration pattern for integration checkpoints in Steps.md +- Document manual testing procedures for each integration point +- Verify data flows correctly between systems before marking complete +- Test complete workflows end-to-end, not just individual components + +### ❌ Avoid: Binary Task Completion + +- Marking feature "done" without integration verification +- Assuming systems communicate correctly without testing +- Skipping end-to-end flow testing to save time +- Checkbox completion based solely on code presence + +**Integration Testing Levels**: +1. **Component-level**: Feature works with its direct dependencies +2. **System-level**: Complete workflows function end-to-end +3. **Cross-system**: Multiple systems interact correctly + +--- + +## 3. Decision Documentation + +### ✅ Prefer: ADR for Deviations + +When implementation deviates from Spec.md: +1. Create ADR in `Context/Decisions/` immediately +2. Document: Context (why deviation needed), Decision (what changed), Consequences (trade-offs) +3. Reference ADR number in commit message for traceability +4. Update Spec.md Revision History section + +When establishing patterns: +1. Create ADR documenting the pattern +2. Future implementations should reference the ADR +3. If changing an established pattern, supersede the original ADR + +### ❌ Avoid: Undocumented Changes + +- Implementing differently from Spec.md without documentation +- "Will document later" mentality leading to lost context +- Behavior changes without any record of the decision +- Future sessions "fixing" intentional deviations back to spec + +**ADR Workflow**: +``` +Deviation discovered during implementation + ↓ +Create ADR-NNNN in Context/Decisions/ + ↓ +Reference in commit: "feat: change X (ADR-NNNN)" + ↓ +Update Spec.md Revision History +``` + +--- + +## 4. Quality Assurance + +### Validation Agents + +- `check-task-completion` - Validates completion criteria at milestones +- `check-accessibility` - Ensures accessibility compliance (if applicable) +- `check-modern-code` - Detects deprecated APIs (if applicable) + +### Manual Checkpoints + +Before marking ANY task complete, verify: + +1. **"Does it actually work?"** + - Manually tested in real usage scenario? + - Saw the feature function, not just compile? + +2. **"Are integrations verified?"** + - Checked that referenced methods exist? + - Tested system-to-system communication? + +3. **"Are deviations documented?"** + - Behavior differs from Spec.md → ADR created? + - Architecture differs from Tech.md → ADR created? + - Bugs found → `/ctxk:bckl:add-bug` used? + +4. **"Would this confuse future sessions?"** + - Context documented for AI sessions without memory? + - Assumptions explicit? + +--- + +## 5. Red Flags - Task NOT Complete + +If ANY of these are true, the task is NOT complete: + +- ⚠️ "// handled elsewhere" comment without verified code at that location +- ⚠️ TODO comments without follow-up tasks in Steps.md or backlog +- ⚠️ Code compiles but feature doesn't work when tested in application +- ⚠️ Integration assumed but not verified with actual testing +- ⚠️ Changed from plan but no ADR created to document deviation +- ⚠️ Stub method with "// will implement" but no explicit task created +- ⚠️ Works in isolation but fails when integrated with other systems + +--- + +## 6. Milestone Validation + +At every 🏁 MILESTONE marker in Steps.md: + +1. **Run Validation** + - Execute `check-task-completion` agent + - Review all changes since last milestone + - Verify no stub implementations remain + +2. **If Violations Found** + - BLOCK commit until resolved + - Options: + - Fix violations now + - Create ADR documenting why deviation is acceptable + - Skip with explicit documentation (emergency only) + +3. **Documentation Check** + - All deviations have ADRs? + - Spec.md Revision History updated? + - No undocumented behavior changes? + +--- + +## Resources + +- **ADR Pattern**: https://adr.github.io/ +- **AWS ADR Best Practices**: https://aws.amazon.com/blogs/architecture/master-architecture-decision-records-adrs/ +- **Google Cloud ADR Overview**: https://docs.cloud.google.com/architecture/architecture-decision-records + +════════════════════════════════════════════════════════════════════════════════ +👩‍💻 DEVELOPER CUSTOMIZATIONS - EDITABLE SECTION +════════════════════════════════════════════════════════════════════════════════ + +This section is preserved during ContextKit migrations and updates. +Add project-specific instructions, examples, and overrides below. + +## Project-Specific Completion Criteria + + + + +## Additional Red Flags + + + + +## Integration Testing Requirements + + + +## Override Behaviors +