├── .context ├── AI_INSTRUCTIONS.md ├── README.md ├── ai │ └── operations │ │ ├── README.md │ │ ├── context.yaml │ │ ├── help.yaml │ │ ├── plan.yaml │ │ ├── reconcile.yaml │ │ ├── save.yaml │ │ ├── session_triggers.yaml │ │ ├── start.yaml │ │ ├── status.yaml │ │ ├── task.yaml │ │ ├── task_creation.yaml │ │ ├── task_transition.yaml │ │ └── validation.yaml ├── memory │ ├── OPERATIONS.md │ ├── README.md │ ├── RECOVERY.md │ ├── REFERENCES.md │ ├── SELF_IMPROVEMENT.md │ ├── STATE_TRACKING.md │ ├── STRUCTURE.md │ ├── core │ │ ├── config.json │ │ ├── rules.json │ │ └── state.json │ ├── project │ │ ├── context │ │ │ └── project.json │ │ └── self_improvement.json │ └── session │ │ └── active.json ├── plan │ └── planning_document.md ├── tasks │ ├── README.md │ ├── active │ │ └── .gitkeep │ ├── blocked │ │ └── .gitkeep │ ├── completed │ │ └── .gitkeep │ ├── hold │ │ └── .gitkeep │ └── planned │ │ └── .gitkeep └── templates │ ├── README.md │ ├── decisions │ ├── README.md │ ├── TEMPLATE.md │ └── example.md │ ├── sessions │ ├── README.md │ ├── TEMPLATE.md │ └── example.md │ ├── tasks │ ├── README.md │ ├── TEMPLATE.md │ └── example.md │ └── validation.md ├── COMMANDS.json ├── COMMANDS.md ├── LICENSE └── README.md /.context/README.md: -------------------------------------------------------------------------------- 1 | # Aegis Framework 2 | 3 | This directory contains the core Aegis framework implementation. Each subdirectory serves a specific purpose in maintaining project state and managing operations. 4 | 5 | ## Directory Structure 6 | 7 | ### ai/ 8 | Contains AI assistant operations and patterns: 9 | - `operations/`: Operation patterns and command implementation YAML files 10 | 11 | ### memory/ 12 | Stores framework and project memory in a structured, file-based system: 13 | - `core/`: Framework knowledge and operation patterns 14 | - `project/`: Project-specific memory and state 15 | - `context/`: Project context data 16 | - `self_improvement.json`: Self-improvement metrics and recommendations 17 | - `session/`: Temporary session state and context 18 | - Documentation files: 19 | - `SELF_IMPROVEMENT.md`: Documentation for the self-improvement system 20 | - `STRUCTURE.md`, `REFERENCES.md`, `STATE_TRACKING.md`, etc. 21 | 22 | ### templates/ 23 | Contains document templates for maintaining consistency: 24 | - `tasks/`: Task definition templates 25 | - `sessions/`: Session record templates 26 | - `decisions/`: Decision record templates 27 | 28 | ### plan/ 29 | Stores planning documents and resources: 30 | - `planning_document.md`: Current project plan 31 | 32 | ### tasks/ 33 | Manages tasks through their lifecycle: 34 | - `planned/`: Tasks ready for implementation 35 | - `active/`: Tasks currently in progress 36 | - `hold/`: Tasks waiting on dependencies 37 | - `completed/`: Finished tasks 38 | 39 | ### sessions/ 40 | Stores session records and progress: 41 | - Files named by date: `YYYY-MM-DD.md` 42 | 43 | ### decisions/ 44 | Stores important decision records: 45 | - Files named by ID: `DECISION-XXX.md` 46 | 47 | ## Key Files 48 | - `AI_INSTRUCTIONS.md`: Comprehensive framework instructions for the AI assistant 49 | 50 | ## TDD Integration 51 | The framework now supports Test-Driven Development with: 52 | - Test Status tracking in task documents 53 | - Conditional task completion based on test status 54 | - Support for test statuses: Not Started, Failing, Passing, Not Applicable 55 | 56 | ## Usage 57 | 1. Copy this `.context` directory to your project root 58 | 2. Initialize with `/aegis start` 59 | 3. Begin with `/aegis plan` 60 | -------------------------------------------------------------------------------- /.context/ai/operations/README.md: -------------------------------------------------------------------------------- 1 | # Operation Patterns 2 | 3 | ## Overview 4 | This directory contains the operation patterns for all framework commands. These patterns define how the framework processes commands through text-based operations. 5 | 6 | ## Command Processing 7 | Commands are processed entirely through text operations: 8 | 1. File system operations (mv, cp) 9 | 2. Content updates (front matter) 10 | 3. State tracking (memory system) 11 | 4. Template usage 12 | 13 | ## Directory Contents 14 | ``` 15 | operations/ 16 | ├── README.md # This file 17 | ├── plan.yaml # Planning operations 18 | ├── start.yaml # Session start 19 | ├── save.yaml # Progress saving 20 | ├── status.yaml # Status checking 21 | ├── task.yaml # Task management 22 | ├── task_creation.yaml # Task creation operations 23 | ├── task_transition.yaml # Task state transition operations 24 | ├── context.yaml # Context refresh 25 | ├── reconcile.yaml # State reconciliation 26 | ├── validation.yaml # Validation patterns 27 | └── help.yaml # Help system 28 | ``` 29 | 30 | ## Operation Pattern Structure 31 | Each YAML file defines: 32 | 1. Command inputs and options 33 | 2. Required validations 34 | 3. Step-by-step process 35 | 4. Error handling 36 | 5. Recovery procedures 37 | 6. Command templates with required components 38 | 39 | ### Example Pattern (plan.yaml) 40 | ```yaml 41 | name: plan 42 | description: Creates/updates planning document 43 | input: 44 | type: command 45 | pattern: /aegis plan 46 | steps: 47 | - validate framework 48 | - check permissions 49 | - process planning 50 | - create tasks 51 | ``` 52 | 53 | ## Command Templates 54 | Each operation YAML file includes a `command_template` section that defines: 55 | 56 | 1. **Required Components** for each execution phase: 57 | - Pre-execution: Validation and context loading 58 | - Execution: Core command functionality 59 | - Post-execution: Verification and reporting 60 | - Error handling: Error detection and resolution 61 | 62 | 2. **Component Definition** for each required component: 63 | - Description of the component's purpose 64 | - Validation rules for the component 65 | - Step-by-step implementation instructions 66 | 67 | 3. **Implementation Examples** showing: 68 | - How to implement each command correctly 69 | - How to handle common scenarios 70 | - How to validate and verify the implementation 71 | - How to handle errors and edge cases 72 | 73 | ### Example Command Template Structure 74 | ```yaml 75 | command_template: 76 | name: command_name 77 | description: "Template for implementing the command" 78 | version: 1.0 79 | 80 | required_components: 81 | pre_execution: 82 | - component_name: 83 | description: "Component description" 84 | validation: 85 | - validation_rule: "Rule description" 86 | implementation: | 87 | 1. Step one 88 | 2. Step two 89 | 3. Step three 90 | 91 | execution: 92 | # Execution components 93 | 94 | post_execution: 95 | # Post-execution components 96 | 97 | error_handling: 98 | # Error handling components 99 | 100 | implementation_example: | 101 | # Example implementation 102 | ``` 103 | 104 | ## Validation Patterns 105 | The `validation.yaml` file contains validation patterns for: 106 | 107 | 1. **Framework Validation**: Ensuring the framework structure is valid 108 | 2. **Task Validation**: Validating task states and transitions 109 | 3. **Session Validation**: Validating session states and content 110 | 4. **Project Validation**: Validating project context and state 111 | 5. **Self-Improvement Validation**: Validating self-improvement data 112 | 6. **Command Validation**: Ensuring complete and correct command implementation 113 | 114 | Command validation patterns define validation steps for: 115 | - Pre-execution validation 116 | - Execution validation 117 | - Post-execution validation 118 | - Completion validation 119 | 120 | ## Usage Rules 121 | 1. All operations must: 122 | - Follow YAML format 123 | - Include all sections 124 | - Define error handling 125 | - Specify recovery 126 | - Include command templates 127 | 128 | 2. Text Operations: 129 | - Use mv for file transitions 130 | - Update front matter for state 131 | - Follow template rules 132 | - Maintain references 133 | 134 | 3. State Management: 135 | - Track in memory system 136 | - Update consistently 137 | - Validate changes 138 | - Handle errors 139 | 140 | ## Command Flow 141 | 1. Pre-Operation: 142 | - Validate framework 143 | - Check permissions 144 | - Load context 145 | - Validate command inputs 146 | 147 | 2. Operation: 148 | - Follow YAML steps 149 | - Update state 150 | - Move files 151 | - Track changes 152 | - Create required artifacts 153 | 154 | 3. Post-Operation: 155 | - Verify changes 156 | - Update memory 157 | - Handle errors 158 | - Clean up 159 | - Validate completion 160 | 161 | ## Error Handling 162 | 1. Framework Errors: 163 | - Invalid structure 164 | - Missing files 165 | - Permission issues 166 | 167 | 2. Operation Errors: 168 | - Invalid state 169 | - Missing dependencies 170 | - Reference errors 171 | - Incomplete implementation 172 | 173 | 3. Recovery: 174 | - Follow YAML procedures 175 | - Maintain consistency 176 | - Log issues 177 | - Guide resolution 178 | - Apply recovery strategies 179 | 180 | ## Implementation Notes 181 | 1. Keep operations atomic 182 | 2. Validate all changes 183 | 3. Maintain consistency 184 | 4. Follow patterns exactly 185 | 5. Document changes 186 | 6. Test thoroughly 187 | 7. Follow command templates 188 | 8. Implement all required components 189 | 9. Verify implementation against templates 190 | 191 | ## Command Implementation Fail-Safes 192 | To ensure complete and correct implementation of commands, the framework includes: 193 | 194 | 1. **Command Checklists**: Detailed checklists for each command in AI_INSTRUCTIONS.md 195 | 2. **Command Validation Patterns**: Validation patterns in validation.yaml 196 | 3. **Command Templates**: Required components and implementation instructions 197 | 4. **Error Prevention Instructions**: Common failure points and prevention strategies 198 | 5. **Recovery Procedures**: Steps to recover from incomplete implementations 199 | 200 | These fail-safe mechanisms help prevent incomplete command implementations and ensure the integrity of the framework's memory system. 201 | 202 | ## References 203 | - See memory/STRUCTURE.md for memory system 204 | - See templates/README.md for templates 205 | - See tasks/README.md for task management 206 | - See AI_INSTRUCTIONS.md for framework rules and command checklists 207 | - See validation.yaml for validation patterns 208 | -------------------------------------------------------------------------------- /.context/ai/operations/context.yaml: -------------------------------------------------------------------------------- 1 | name: context 2 | description: Quick context refresh and memory update 3 | version: 1.0 4 | 5 | validation_source: 6 | file: validation.yaml 7 | type: command_validation 8 | rules: 9 | - context 10 | 11 | input: 12 | type: command 13 | pattern: /aegis context 14 | options: 15 | - name: --full 16 | description: Show full context 17 | required: false 18 | validation: 19 | type: context 20 | rules: 21 | - framework_ready 22 | - valid_permissions 23 | 24 | output: 25 | type: operation 26 | actions: 27 | - show_context 28 | - refresh_memory 29 | validation: 30 | context: 31 | - format_valid 32 | - sections_complete 33 | memory: 34 | - state_valid 35 | - updates_allowed 36 | 37 | steps: 38 | 1_validate: 39 | - check_framework: 40 | rules: 41 | - framework_structure 42 | - required_files 43 | - permissions 44 | - verify_permissions 45 | - load_state: 46 | rules: 47 | - memory_exists 48 | - state_valid 49 | 50 | 2_prepare: 51 | - get_context: 52 | type: memory 53 | required: 54 | - core 55 | - project 56 | - session 57 | optional: 58 | - decisions 59 | - get_decisions: 60 | directory: project/decisions 61 | filter: 62 | status: [accepted, proposed] 63 | sort: 64 | by: created 65 | order: desc 66 | limit: 5 67 | - get_project: 68 | from: memory/project 69 | required: true 70 | validation: 71 | - exists 72 | - readable 73 | - valid_format 74 | - get_session: 75 | from: memory/session 76 | required: false 77 | validation: 78 | - format_valid 79 | - state_valid 80 | - get_tasks: 81 | directory: tasks 82 | filter: 83 | status: [active, hold] 84 | sort: 85 | by: updated 86 | order: desc 87 | 88 | 3_execute: 89 | - load_context: 90 | type: framework 91 | scope: current 92 | content: 93 | - active_tasks 94 | - recent_changes 95 | - decisions 96 | - collect_context: 97 | sources: 98 | - active_tasks 99 | - recent_changes 100 | - decisions 101 | - state 102 | validation: 103 | - sources_exist 104 | - data_valid 105 | 106 | - show_context: 107 | sections: 108 | - active_task 109 | - recent_decisions 110 | - current_focus 111 | - next_steps 112 | format: 113 | decisions: 114 | - id 115 | - title 116 | - status 117 | - date 118 | - format_output: 119 | type: context 120 | format: markdown 121 | sections: 122 | - overview 123 | - tasks 124 | - changes 125 | - decisions 126 | validation: 127 | - format_valid 128 | - sections_complete 129 | 130 | - update_memory: 131 | type: session 132 | content: context 133 | time: current 134 | - refresh_memory: 135 | type: session 136 | content: 137 | - context 138 | - state 139 | validation: 140 | - state_valid 141 | - updates_allowed 142 | 143 | 4_verify: 144 | - validate_context: 145 | type: summary 146 | schema: context 147 | - validate_output: 148 | type: context 149 | rules: 150 | - format_valid 151 | - content_complete 152 | 153 | - check_memory: 154 | type: session 155 | rules: 156 | - state_valid 157 | - updates_complete 158 | 159 | errors: 160 | framework: 161 | structure: Framework structure invalid 162 | permissions: Missing required permissions 163 | state: Invalid framework state 164 | context: 165 | format: Invalid context format 166 | content: Missing required content 167 | sources: Invalid context sources 168 | memory: 169 | state: Invalid memory state 170 | update: Memory update failed 171 | sync: Memory sync failed 172 | 173 | recovery: 174 | framework: 175 | structure: Validate framework structure 176 | permissions: Check and fix permissions 177 | state: Restore framework state 178 | context: 179 | format: Fix context format 180 | content: Load required content 181 | sources: Validate sources 182 | memory: 183 | state: Fix memory state 184 | update: Retry memory update 185 | sync: Resync memory state 186 | 187 | templates: 188 | context: 189 | format: markdown 190 | required_sections: 191 | - overview 192 | - tasks 193 | - changes 194 | - decisions 195 | 196 | validation: 197 | rules: 198 | - framework_ready 199 | - context_valid 200 | - memory_valid 201 | requirements: 202 | framework: 203 | - valid_structure 204 | - valid_permissions 205 | context: 206 | - valid_format 207 | - complete_sections 208 | memory: 209 | - valid_state 210 | - allows_updates 211 | 212 | # Command Template with Required Components 213 | command_template: 214 | name: context 215 | description: "Template for implementing the context command" 216 | version: 1.0 217 | 218 | required_components: 219 | pre_execution: 220 | - project_context_loading: 221 | description: "Load project context" 222 | validation: 223 | - context_loaded: "Project context must be loaded" 224 | implementation: | 225 | 1. Load project context from memory/project/context/project.json 226 | 2. Verify project context is valid 227 | 3. Extract relevant information (name, version, phase, etc.) 228 | 229 | - active_task_loading: 230 | description: "Load active tasks" 231 | validation: 232 | - tasks_loaded: "Active tasks must be loaded" 233 | implementation: | 234 | 1. Load active tasks from tasks/active/ 235 | 2. Sort tasks by priority and updated timestamp 236 | 3. Extract relevant information (title, progress, etc.) 237 | 238 | - recent_decision_loading: 239 | description: "Load recent decisions" 240 | validation: 241 | - decisions_loaded: "Recent decisions must be loaded" 242 | implementation: | 243 | 1. Load recent decision documents from decisions/ 244 | 2. Sort by date (newest first) 245 | 3. Limit to most relevant decisions (5-10) 246 | 247 | execution: 248 | - context_report_generation: 249 | description: "Generate context report" 250 | validation: 251 | - report_generated: "Context report must be generated" 252 | implementation: | 253 | 1. Create context report structure 254 | 2. Include project overview section 255 | 3. Format information in a readable way 256 | 257 | - active_tasks_inclusion: 258 | description: "Include active tasks in report" 259 | validation: 260 | - tasks_included: "Active tasks must be included in report" 261 | implementation: | 262 | 1. Format active tasks information 263 | 2. Include task titles, IDs, and progress 264 | 3. Sort by priority and status 265 | 266 | - recent_decisions_inclusion: 267 | description: "Include recent decisions in report" 268 | validation: 269 | - decisions_included: "Recent decisions must be included in report" 270 | implementation: | 271 | 1. Format recent decisions information 272 | 2. Include decision titles, IDs, and status 273 | 3. Provide brief context for each decision 274 | 275 | - relevant_insights_inclusion: 276 | description: "Include relevant insights in report" 277 | validation: 278 | - insights_included: "Relevant insights must be included in report" 279 | implementation: | 280 | 1. Load insights from self_improvement.json 281 | 2. Filter for most relevant insights 282 | 3. Include in report with priority indicators 283 | 284 | - memory_refresh: 285 | description: "Refresh session memory with context" 286 | validation: 287 | - memory_refreshed: "Session memory must be refreshed" 288 | implementation: | 289 | 1. Update active.json with current context 290 | 2. Update context section with latest information 291 | 3. Update timestamps to current time 292 | 293 | post_execution: 294 | - report_verification: 295 | description: "Verify report is complete" 296 | validation: 297 | - report_complete: "Report must include all required sections" 298 | implementation: | 299 | 1. Verify all required sections are present 300 | 2. Check that information is current and accurate 301 | 3. Ensure report is properly formatted 302 | 303 | - memory_verification: 304 | description: "Verify memory has been refreshed" 305 | validation: 306 | - memory_verified: "Memory refresh must be verified" 307 | implementation: | 308 | 1. Verify active.json has been updated 309 | 2. Check that context information is current 310 | 3. Confirm timestamps are updated 311 | 312 | error_handling: 313 | - error_detection: 314 | description: "Detect and handle errors" 315 | validation: 316 | - errors_handled: "All potential errors must be handled" 317 | implementation: | 318 | 1. Check for common errors (missing files, invalid format) 319 | 2. Implement fallback mechanisms for missing data 320 | 3. Provide clear error messages if needed 321 | 322 | - data_validation: 323 | description: "Validate data completeness" 324 | validation: 325 | - data_valid: "All data must be valid" 326 | implementation: | 327 | 1. Verify all required data is available 328 | 2. Check for inconsistencies in data 329 | 3. Use default values for missing non-critical data 330 | 331 | implementation_example: | 332 | # Example implementation of /aegis context 333 | 334 | ## Pre-execution 335 | 1. Load project context: 336 | - Load project.json from memory/project/context/ 337 | - Extract project name, version, phase 338 | - Get lists of active, completed, and planned tasks 339 | 2. Load active tasks: 340 | - Read all files in tasks/active/ 341 | - Sort by priority (high to low) 342 | - Extract titles, IDs, and progress information 343 | 3. Load recent decisions: 344 | - Read recent decision files from decisions/ 345 | - Sort by date (newest first) 346 | - Limit to 5 most recent decisions 347 | 348 | ## Execution 349 | 1. Generate context report: 350 | - Create report structure with sections 351 | - Add project overview (name, version, phase) 352 | - Format in a readable way 353 | 2. Include active tasks: 354 | - Format list of active tasks 355 | - Include task titles, IDs, and progress 356 | - Highlight high-priority tasks 357 | 3. Include recent decisions: 358 | - Format list of recent decisions 359 | - Include decision titles, IDs, and status 360 | - Provide brief context for each decision 361 | 4. Include relevant insights: 362 | - Add relevant insights from self_improvement.json 363 | - Include high-priority recommendations 364 | 5. Refresh session memory: 365 | - Update active.json with current context 366 | - Update context section with latest information 367 | - Update timestamps to current time 368 | 369 | ## Post-execution 370 | 1. Verify report: 371 | - Check that all sections are present 372 | - Verify information is current and accurate 373 | - Ensure report is complete 374 | 2. Verify memory refresh: 375 | - Confirm active.json has been updated 376 | - Check that context information is current 377 | - Verify timestamps are updated 378 | 379 | ## Error handling 380 | 1. Handle missing data: 381 | - If project.json is missing, report error 382 | - If no active tasks, indicate "No active tasks" 383 | - If no recent decisions, indicate "No recent decisions" 384 | 2. Validate data: 385 | - Check for inconsistencies in task states 386 | - Verify timestamps are valid 387 | - Use default values for non-critical missing data 388 | -------------------------------------------------------------------------------- /.context/ai/operations/help.yaml: -------------------------------------------------------------------------------- 1 | name: help 2 | description: Show command help and guide usage 3 | version: 1.0 4 | 5 | validation_source: 6 | file: validation.yaml 7 | type: command_validation 8 | rules: 9 | - help 10 | 11 | input: 12 | type: command 13 | pattern: /aegis help [command] 14 | options: 15 | - name: command 16 | description: Specific command to get help for 17 | required: false 18 | validation: 19 | type: help 20 | rules: 21 | - framework_ready 22 | - valid_command 23 | 24 | output: 25 | type: operation 26 | actions: 27 | - show_help 28 | - display_examples 29 | validation: 30 | help: 31 | - format_valid 32 | - content_complete 33 | display: 34 | - readable 35 | - organized 36 | 37 | steps: 38 | 1_validate: 39 | - check_framework: 40 | rules: 41 | - framework_structure 42 | - required_files 43 | - verify_command: 44 | rules: 45 | - command_exists 46 | - help_available 47 | 48 | 2_prepare: 49 | - get_command: 50 | from: operations 51 | required: false 52 | validation: 53 | - exists 54 | - has_help 55 | - load_examples: 56 | from: examples 57 | required: false 58 | validation: 59 | - exists 60 | - valid_format 61 | 62 | 3_execute: 63 | - collect_help: 64 | sources: 65 | - command_info 66 | - usage_patterns 67 | - examples 68 | validation: 69 | - content_valid 70 | - format_valid 71 | 72 | - format_output: 73 | type: help 74 | format: markdown 75 | sections: 76 | - description 77 | - usage 78 | - options 79 | - examples 80 | validation: 81 | - format_valid 82 | - sections_complete 83 | 84 | 4_verify: 85 | - validate_output: 86 | type: help 87 | rules: 88 | - format_valid 89 | - content_complete 90 | 91 | - check_display: 92 | type: help 93 | rules: 94 | - readable 95 | - organized 96 | - helpful 97 | 98 | errors: 99 | framework: 100 | structure: Framework structure invalid 101 | files: Required files missing 102 | help: 103 | command: Invalid command specified 104 | content: Help content missing 105 | format: Invalid help format 106 | display: 107 | format: Display format error 108 | readability: Content not readable 109 | organization: Poor content organization 110 | 111 | recovery: 112 | framework: 113 | structure: Validate framework structure 114 | files: Check required files 115 | help: 116 | command: Show valid commands 117 | content: Load help content 118 | format: Fix help format 119 | display: 120 | format: Fix display format 121 | readability: Improve readability 122 | organization: Reorganize content 123 | 124 | templates: 125 | help: 126 | format: markdown 127 | required_sections: 128 | - description 129 | - usage 130 | - options 131 | - examples 132 | display_rules: 133 | - clear_headers 134 | - consistent_format 135 | - proper_indentation 136 | 137 | validation: 138 | rules: 139 | - framework_ready 140 | - help_valid 141 | - display_valid 142 | requirements: 143 | framework: 144 | - valid_structure 145 | - required_files 146 | help: 147 | - valid_format 148 | - complete_sections 149 | display: 150 | - readable 151 | - organized 152 | -------------------------------------------------------------------------------- /.context/ai/operations/plan.yaml: -------------------------------------------------------------------------------- 1 | name: plan 2 | description: Creates or updates project planning document and generates initial tasks 3 | version: 1.0 4 | 5 | validation_source: 6 | file: validation.yaml 7 | type: command_validation 8 | rules: 9 | - plan 10 | 11 | input: 12 | type: command 13 | pattern: /aegis plan 14 | options: 15 | - name: --update 16 | description: Update existing plan 17 | required: false 18 | validation: 19 | type: plan 20 | rules: 21 | - framework_ready 22 | - valid_command 23 | 24 | output: 25 | type: operation 26 | actions: 27 | - create_planning_doc 28 | - generate_tasks 29 | - update_state 30 | validation: 31 | planning_document: 32 | - format_valid 33 | - content_complete 34 | tasks: 35 | - valid_format 36 | - unique_ids 37 | 38 | steps: 39 | 1_validate: 40 | - check_framework: 41 | rules: 42 | - framework_structure 43 | - required_files 44 | - permissions 45 | - verify_permissions: 46 | rules: 47 | - state_valid 48 | - can_plan 49 | 50 | 2_prepare: 51 | - load_context: 52 | from: memory/project 53 | required: true 54 | validation: 55 | - exists 56 | - readable 57 | - valid_format 58 | - load_existing: 59 | file: planning_document.md 60 | required: false 61 | validation: 62 | - format_valid 63 | - state_valid 64 | 65 | 3_execute: 66 | - create_or_update: 67 | file: planning_document.md 68 | template: planning 69 | content: 70 | - project_overview 71 | - implementation_phases 72 | - task_breakdown 73 | - dependencies 74 | validation: 75 | - format_valid 76 | - content_complete 77 | 78 | - extract_tasks: 79 | from: planning_document.md 80 | pattern: task 81 | output: tasks/planned 82 | template: tasks/TEMPLATE.md 83 | required_fields: 84 | - title 85 | - type: task 86 | - status: planned 87 | - created 88 | - updated 89 | - id 90 | - priority 91 | - memory_types 92 | validation: 93 | - valid_format 94 | - unique_ids 95 | - required_fields 96 | 97 | - update_state: 98 | type: framework 99 | status: planning 100 | validation: 101 | - state_valid 102 | 103 | 4_verify: 104 | - validate_document: 105 | file: planning_document.md 106 | schema: planning 107 | rules: 108 | - exists 109 | - valid_format 110 | - complete 111 | 112 | - check_tasks: 113 | directory: tasks/planned 114 | validation: 115 | - format_valid 116 | - required_fields: 117 | - title 118 | - type 119 | - status 120 | - created 121 | - updated 122 | - id 123 | - priority 124 | - memory_types 125 | - valid_values: 126 | type: task 127 | status: planned 128 | memory_types: 129 | - procedural 130 | - semantic 131 | - episodic 132 | 133 | errors: 134 | framework: 135 | structure: Framework structure invalid 136 | permissions: Missing required permissions 137 | state: Invalid framework state 138 | document: 139 | creation: Plan creation failed 140 | format: Invalid plan format 141 | content: Missing required content 142 | tasks: 143 | generation: Task generation failed 144 | format: Invalid task format 145 | duplicates: Duplicate task IDs 146 | 147 | recovery: 148 | framework: 149 | structure: Validate framework structure 150 | permissions: Check and fix permissions 151 | state: Restore framework state 152 | document: 153 | creation: Retry plan creation 154 | format: Fix plan format 155 | content: Add required content 156 | tasks: 157 | generation: Retry task generation 158 | format: Fix task format 159 | duplicates: Fix duplicate IDs 160 | 161 | templates: 162 | planning: 163 | format: markdown 164 | required_sections: 165 | - overview 166 | - phases 167 | - tasks 168 | validation: 169 | - format_valid 170 | - sections_complete 171 | 172 | validation: 173 | rules: 174 | - framework_ready 175 | - plan_valid 176 | - tasks_valid 177 | requirements: 178 | framework: 179 | - valid_structure 180 | - valid_permissions 181 | plan: 182 | - valid_format 183 | - complete_sections 184 | tasks: 185 | - valid_format 186 | - unique_ids 187 | -------------------------------------------------------------------------------- /.context/ai/operations/reconcile.yaml: -------------------------------------------------------------------------------- 1 | name: reconcile 2 | description: Reconcile framework state with actual system state 3 | version: 1.0 4 | 5 | validation_source: 6 | file: validation.yaml 7 | type: command_validation 8 | rules: 9 | - reconcile 10 | 11 | input: 12 | type: command 13 | pattern: /aegis reconcile 14 | options: 15 | - name: --force 16 | description: Force reconciliation even if no issues detected 17 | required: false 18 | validation: 19 | type: reconcile 20 | rules: 21 | - framework_ready 22 | 23 | output: 24 | type: operation 25 | actions: 26 | - check_state 27 | - fix_inconsistencies 28 | - update_state_files 29 | validation: 30 | reconciliation: 31 | - state_consistent 32 | - files_updated 33 | 34 | steps: 35 | 1_validate: 36 | - check_framework: 37 | rules: 38 | - framework_structure 39 | - required_files 40 | - permissions 41 | 42 | 2_analyze: 43 | - check_task_consistency: 44 | compare: 45 | - directory: tasks/active 46 | state_field: activeTasks 47 | - directory: tasks/completed 48 | state_field: completedTasks 49 | - directory: tasks/hold 50 | state_field: holdTasks 51 | validation: 52 | - directories_exist 53 | - state_file_exists 54 | 55 | - check_decision_consistency: 56 | compare: 57 | - directory: decisions 58 | state_field: decisions 59 | validation: 60 | - directories_exist 61 | - state_file_exists 62 | 63 | - check_session_consistency: 64 | compare: 65 | - directory: sessions 66 | state_file: memory/session/active.json 67 | - directory: sessions 68 | state_directory: memory/session/history 69 | validation: 70 | - directories_exist 71 | - state_file_exists 72 | - history_directory_exists 73 | - session_files_match 74 | 75 | - check_timestamps: 76 | files: 77 | - memory/project/context/project.json 78 | - memory/project/self_improvement.json 79 | - memory/session/active.json 80 | validation: 81 | - timestamp_format_valid 82 | - timestamp_recent 83 | 84 | 3_reconcile: 85 | - update_project_context: 86 | file: memory/project/context/project.json 87 | fields: 88 | - updated: current_timestamp 89 | - activeTasks: from_directory_tasks/active 90 | - completedTasks: from_directory_tasks/completed 91 | - holdTasks: from_directory_tasks/hold 92 | - decisions: from_directory_decisions 93 | validation: 94 | - file_updated 95 | - content_valid 96 | 97 | - update_session_memory: 98 | file: memory/session/active.json 99 | source: sessions 100 | fields: 101 | - updated: current_timestamp 102 | - content.sessionId: from_latest_session 103 | - content.status: from_latest_session 104 | - content.started: from_latest_session 105 | - content.activeTask: from_latest_session 106 | - content.progress: from_latest_session 107 | - content.context: from_latest_session 108 | - content.decisions: from_latest_session 109 | - content.insights: from_latest_session 110 | validation: 111 | - file_updated 112 | - content_valid 113 | 114 | - update_session_history: 115 | directory: memory/session/history 116 | source: sessions 117 | for_each_session: 118 | - create_history_file: "YYYY-MM-DD-sessionId.json" 119 | - copy_session_data: "Extract and format session data" 120 | - validate_history_file: "Ensure file is valid JSON" 121 | validation: 122 | - directory_exists 123 | - files_created 124 | - content_valid 125 | 126 | - verify_self_improvement: 127 | file: memory/project/self_improvement.json 128 | validation: 129 | - file_exists 130 | - format_valid 131 | 132 | 4_report: 133 | - generate_reconciliation_report: 134 | format: markdown 135 | sections: 136 | - issues_found 137 | - changes_made 138 | - current_state 139 | validation: 140 | - report_complete 141 | 142 | errors: 143 | framework: 144 | structure: Framework structure invalid 145 | permissions: Missing required permissions 146 | state: Invalid framework state 147 | state: 148 | inconsistent: State inconsistent with directories 149 | format: Invalid state format 150 | update: State update failed 151 | 152 | recovery: 153 | framework: 154 | structure: Validate framework structure 155 | permissions: Check and fix permissions 156 | state: Restore framework state 157 | state: 158 | inconsistent: Reconcile state with directories 159 | format: Fix state format 160 | update: Retry state update 161 | 162 | # AI Assistant Implementation Guide 163 | ai_implementation: 164 | description: "This operation reconciles the framework's state files with the actual system state" 165 | 166 | execution_steps: 167 | 1: "Read the current project.json file" 168 | 2: "List all tasks in active, completed, and hold directories" 169 | 3: "Extract task IDs from filenames" 170 | 4: "Update project.json with current task lists" 171 | 5: "Update timestamp to current time" 172 | 6: "Find the most recent session file" 173 | 7: "Update active.json with information from the most recent session file" 174 | 8: "Create or update session history files" 175 | 9: "Save updated state files" 176 | 10: "Report changes made to the user" 177 | 178 | example_implementation: | 179 | 1. Read project.json and active.json 180 | 2. Get task lists: 181 | - activeTasks = [files in .context/tasks/active/] 182 | - completedTasks = [files in .context/tasks/completed/] 183 | - holdTasks = [files in .context/tasks/hold/] 184 | 3. Update project.json: 185 | - Set updated = current timestamp 186 | - Set activeTasks = [list of active task IDs] 187 | - Set completedTasks = [list of completed task IDs] 188 | - Set holdTasks = [list of hold task IDs] 189 | 4. Get most recent session: 190 | - Find most recent file in .context/sessions/ 191 | - Extract session information 192 | 5. Update active.json: 193 | - Set updated = current timestamp 194 | - Set content.sessionId = [session ID from most recent file] 195 | - Set content.status = [status from most recent file] 196 | - Set content.activeTask = [active task from most recent file] 197 | - Set content.progress = [progress from most recent file] 198 | - Set content.context = [context from most recent file] 199 | - Set content.decisions = [decisions from most recent file] 200 | - Set content.insights = [insights from most recent file] 201 | 6. Create session history: 202 | - Ensure memory/session/history/ directory exists 203 | - For each session file in .context/sessions/: 204 | - Extract session metadata (id, date, etc.) 205 | - Create JSON file in history directory: YYYY-MM-DD-sessionId.json 206 | - Copy relevant session data to history file 207 | 7. Save updated files 208 | 8. Report reconciliation results 209 | 210 | session_history_format: | 211 | { 212 | "type": "memory", 213 | "category": "session", 214 | "id": "SESSION-XXX", 215 | "created": "YYYY-MM-DDTHH:MM:SS", 216 | "updated": "YYYY-MM-DDTHH:MM:SS", 217 | "content": { 218 | "sessionId": "SESSION-XXX", 219 | "status": "completed", 220 | "started": "YYYY-MM-DDTHH:MM:SS", 221 | "ended": "YYYY-MM-DDTHH:MM:SS", 222 | "activeTask": "TASK-XXX", 223 | "progress": "Summary of progress made", 224 | "decisions": [ 225 | { 226 | "id": "DECISION-XXX", 227 | "title": "Decision title", 228 | "description": "Decision description", 229 | "timestamp": "YYYY-MM-DDTHH:MM:SS" 230 | } 231 | ], 232 | "insights": [ 233 | { 234 | "category": "process", 235 | "text": "Insight text", 236 | "timestamp": "YYYY-MM-DDTHH:MM:SS" 237 | } 238 | ] 239 | } 240 | } 241 | 242 | # Command Template with Required Components 243 | command_template: 244 | name: reconcile 245 | description: "Template for implementing the reconcile command" 246 | version: 1.0 247 | 248 | required_components: 249 | pre_execution: 250 | - framework_structure_check: 251 | description: "Check framework structure" 252 | validation: 253 | - structure_valid: "Framework structure must be valid" 254 | implementation: | 255 | 1. Verify all required directories exist 256 | 2. Check that required files are present 257 | 3. Validate file permissions 258 | 259 | - project_context_loading: 260 | description: "Load project context" 261 | validation: 262 | - context_loaded: "Project context must be loaded" 263 | implementation: | 264 | 1. Load project context from memory/project/context/project.json 265 | 2. Verify project context is valid 266 | 3. Extract task lists and other relevant information 267 | 268 | - session_memory_loading: 269 | description: "Load session memory" 270 | validation: 271 | - memory_loaded: "Session memory must be loaded" 272 | implementation: | 273 | 1. Load active session from memory/session/active.json 274 | 2. Check session history directory 275 | 3. Verify session memory format 276 | 277 | execution: 278 | - task_consistency_check: 279 | description: "Check task consistency" 280 | validation: 281 | - consistency_checked: "Task consistency must be checked" 282 | implementation: | 283 | 1. Compare task files in tasks/active/ with activeTasks in project.json 284 | 2. Compare task files in tasks/completed/ with completedTasks in project.json 285 | 3. Compare task files in tasks/hold/ with holdTasks in project.json 286 | 4. Identify inconsistencies 287 | 288 | - decision_consistency_check: 289 | description: "Check decision consistency" 290 | validation: 291 | - consistency_checked: "Decision consistency must be checked" 292 | implementation: | 293 | 1. Compare decision files in decisions/ with decisions list in project.json 294 | 2. Identify inconsistencies 295 | 296 | - session_consistency_check: 297 | description: "Check session consistency" 298 | validation: 299 | - consistency_checked: "Session consistency must be checked" 300 | implementation: | 301 | 1. Compare session files in sessions/ with active session 302 | 2. Check session history files 303 | 3. Identify inconsistencies 304 | 305 | - project_context_update: 306 | description: "Update project context" 307 | validation: 308 | - context_updated: "Project context must be updated" 309 | implementation: | 310 | 1. Update activeTasks list based on files in tasks/active/ 311 | 2. Update completedTasks list based on files in tasks/completed/ 312 | 3. Update holdTasks list based on files in tasks/hold/ 313 | 4. Update decisions list based on files in decisions/ 314 | 5. Update timestamp to current time 315 | 316 | - session_memory_update: 317 | description: "Update session memory" 318 | validation: 319 | - memory_updated: "Session memory must be updated" 320 | implementation: | 321 | 1. Update active.json with latest session information 322 | 2. Update session history files 323 | 3. Update timestamp to current time 324 | 325 | - session_history_update: 326 | description: "Update session history" 327 | validation: 328 | - history_updated: "Session history must be updated" 329 | implementation: | 330 | 1. Create history files for all sessions 331 | 2. Ensure history files match session files 332 | 3. Update timestamps 333 | 334 | post_execution: 335 | - project_context_verification: 336 | description: "Verify project context has been updated" 337 | validation: 338 | - context_verified: "Project context update must be verified" 339 | implementation: | 340 | 1. Verify project.json has been updated 341 | 2. Check that task lists match directory contents 342 | 3. Confirm timestamp is current 343 | 344 | - session_memory_verification: 345 | description: "Verify session memory has been updated" 346 | validation: 347 | - memory_verified: "Session memory update must be verified" 348 | implementation: | 349 | 1. Verify active.json has been updated 350 | 2. Check that session information is current 351 | 3. Confirm timestamp is current 352 | 353 | - session_history_verification: 354 | description: "Verify session history has been updated" 355 | validation: 356 | - history_verified: "Session history update must be verified" 357 | implementation: | 358 | 1. Verify history files exist for all sessions 359 | 2. Check that history files match session files 360 | 3. Confirm timestamps are current 361 | 362 | - reconciliation_report: 363 | description: "Generate reconciliation report" 364 | validation: 365 | - report_generated: "Reconciliation report must be generated" 366 | implementation: | 367 | 1. Create report of issues found 368 | 2. Document changes made 369 | 3. Summarize current state 370 | 371 | error_handling: 372 | - error_detection: 373 | description: "Detect and handle errors" 374 | validation: 375 | - errors_handled: "All potential errors must be handled" 376 | implementation: | 377 | 1. Check for common errors (missing files, invalid format) 378 | 2. Implement recovery procedures 379 | 3. Log errors and recovery attempts 380 | 381 | - consistency_enforcement: 382 | description: "Enforce system consistency" 383 | validation: 384 | - consistency_enforced: "System consistency must be enforced" 385 | implementation: | 386 | 1. Prioritize file system state over memory state 387 | 2. Update memory files to match file system 388 | 3. Document all inconsistencies and fixes 389 | 390 | implementation_example: | 391 | # Example implementation of /aegis reconcile 392 | 393 | ## Pre-execution 394 | 1. Check framework structure: 395 | - Verify all required directories exist 396 | - Check that required files are present 397 | - Validate file permissions 398 | 2. Load project context: 399 | - Load project.json from memory/project/context/ 400 | - Verify project context is valid 401 | - Extract task lists and other information 402 | 3. Load session memory: 403 | - Load active.json from memory/session/ 404 | - Check session history directory 405 | - Verify session memory format 406 | 407 | ## Execution 408 | 1. Check task consistency: 409 | - Compare task files in tasks/active/ with activeTasks in project.json 410 | - Compare task files in tasks/completed/ with completedTasks in project.json 411 | - Compare task files in tasks/hold/ with holdTasks in project.json 412 | - Found inconsistency: TASK-123 in tasks/active/ but not in activeTasks 413 | 2. Check decision consistency: 414 | - Compare decision files in decisions/ with decisions list in project.json 415 | - Found inconsistency: DEC-001 in decisions/ but not in decisions list 416 | 3. Check session consistency: 417 | - Compare session files in sessions/ with active session 418 | - Check session history files 419 | - Found inconsistency: Latest session not reflected in active.json 420 | 4. Update project context: 421 | - Update activeTasks to include TASK-123 422 | - Update decisions list to include DEC-001 423 | - Update timestamp to current time 424 | 5. Update session memory: 425 | - Update active.json with latest session information 426 | - Update timestamp to current time 427 | 6. Update session history: 428 | - Create history files for all sessions 429 | - Ensure history files match session files 430 | 431 | ## Post-execution 432 | 1. Verify project context: 433 | - Confirm project.json has been updated 434 | - Verify task lists match directory contents 435 | - Confirm timestamp is current 436 | 2. Verify session memory: 437 | - Confirm active.json has been updated 438 | - Verify session information is current 439 | - Confirm timestamp is current 440 | 3. Verify session history: 441 | - Confirm history files exist for all sessions 442 | - Verify history files match session files 443 | 4. Generate report: 444 | - Document inconsistencies found: 3 445 | - Document changes made: 3 446 | - Summarize current state 447 | 448 | ## Error handling 449 | 1. Handle errors: 450 | - If project.json is missing, create from directory contents 451 | - If active.json is invalid, recreate from latest session 452 | 2. Enforce consistency: 453 | - Prioritize file system state over memory state 454 | - Update memory files to match file system 455 | - Document all inconsistencies and fixes -------------------------------------------------------------------------------- /.context/ai/operations/save.yaml: -------------------------------------------------------------------------------- 1 | name: save 2 | description: Save current progress and update project state 3 | version: 1.0 4 | 5 | validation_source: 6 | file: validation.yaml 7 | type: command_validation 8 | rules: 9 | - save 10 | 11 | input: 12 | type: command 13 | pattern: /aegis save 14 | options: 15 | - name: --message 16 | description: Save message 17 | required: false 18 | validation: 19 | type: save 20 | rules: 21 | - active_session 22 | - changes_present 23 | 24 | output: 25 | type: operation 26 | actions: 27 | - save_progress 28 | - analyze_session 29 | - update_state 30 | - log_changes 31 | - extract_decisions 32 | - update_project 33 | validation: 34 | session: 35 | - format_valid 36 | - state_valid 37 | changes: 38 | - changes_exist 39 | - valid_format 40 | analysis: 41 | - insights_valid 42 | 43 | steps: 44 | 1_validate: 45 | - check_session: 46 | rules: 47 | - session_exists 48 | - session_active 49 | - verify_changes: 50 | rules: 51 | - changes_exist 52 | - changes_valid 53 | - load_state: 54 | rules: 55 | - memory_exists 56 | - state_valid 57 | 58 | 2_prepare: 59 | - get_session: 60 | from: memory/session 61 | required: true 62 | validation: 63 | - exists 64 | - readable 65 | - valid_format 66 | - collect_changes: 67 | from: active_session 68 | validation: 69 | - changes_exist 70 | - changes_valid 71 | - gather_analysis_data: 72 | from: 73 | - memory/session 74 | - memory/project 75 | - active_session 76 | documentation: memory/SELF_IMPROVEMENT.md 77 | validation: 78 | - data_sufficient 79 | - format_valid 80 | 81 | 3_execute: 82 | - save_progress: 83 | type: session 84 | content: 85 | - changes 86 | - decisions 87 | - state 88 | validation: 89 | - format_valid 90 | - content_complete 91 | 92 | - analyze_session: 93 | type: self_improvement 94 | data: 95 | - session_history 96 | - task_patterns 97 | - decision_patterns 98 | - time_allocation 99 | output: 100 | - insights 101 | - recommendations 102 | store: 103 | file: memory/project/self_improvement.json 104 | session_section: Self-Improvement 105 | documentation: memory/SELF_IMPROVEMENT.md 106 | validation: 107 | - analysis_complete 108 | - insights_valid 109 | 110 | - update_state: 111 | type: framework 112 | status: saved 113 | validation: 114 | - valid_state 115 | - valid_transition 116 | 117 | - log_changes: 118 | to: session_log 119 | format: markdown 120 | content: 121 | - timestamp 122 | - changes 123 | - decisions 124 | - insights 125 | validation: 126 | - format_valid 127 | - content_complete 128 | 129 | - extract_decisions: 130 | from: current_session 131 | pattern: "## Decisions" 132 | create: 133 | template: decisions/TEMPLATE.md 134 | location: project/decisions 135 | format: DECISION-[000] 136 | 137 | - update_project: 138 | file: project/context/project.json 139 | fields: 140 | - activeTasks 141 | - completedTasks 142 | - decisions 143 | - insights 144 | 145 | 4_verify: 146 | - validate_save: 147 | type: session 148 | rules: 149 | - state_saved 150 | - changes_recorded 151 | 152 | - check_log: 153 | file: session_log 154 | rules: 155 | - file_exists 156 | - content_valid 157 | 158 | - verify_analysis: 159 | type: self_improvement 160 | rules: 161 | - analysis_complete 162 | - insights_stored 163 | - session_updated 164 | documentation: memory/SELF_IMPROVEMENT.md 165 | 166 | - verify_state: 167 | type: framework 168 | rules: 169 | - state_valid 170 | - save_complete 171 | 172 | errors: 173 | framework: 174 | structure: Framework structure invalid 175 | permissions: Missing required permissions 176 | state: Invalid framework state 177 | session: 178 | save: Session save failed 179 | format: Invalid session format 180 | changes: Missing changes 181 | changes: 182 | missing: No changes to save 183 | format: Invalid changes format 184 | record: Change recording failed 185 | analysis: 186 | failed: Session analysis failed 187 | storage: Insight storage failed 188 | format: Invalid insight format 189 | 190 | recovery: 191 | framework: 192 | structure: Validate framework structure 193 | permissions: Check and fix permissions 194 | state: Restore framework state 195 | session: 196 | save: Retry session save 197 | format: Fix session format 198 | changes: Collect changes 199 | changes: 200 | missing: Check for changes 201 | format: Fix changes format 202 | record: Retry recording 203 | analysis: 204 | failed: Skip analysis, continue with save 205 | storage: Retry insight storage 206 | format: Fix insight format 207 | 208 | templates: 209 | session: 210 | format: json 211 | required_fields: 212 | - session_id 213 | - save_time 214 | - changes 215 | sections: 216 | - progress 217 | - decisions 218 | - state 219 | - self_improvement 220 | decision: 221 | base: decisions/TEMPLATE.md 222 | required: 223 | - title 224 | - context 225 | - decision 226 | - consequences 227 | analysis: 228 | format: json 229 | required_fields: 230 | - timestamp 231 | - session_id 232 | - insights 233 | sections: 234 | - metrics 235 | - patterns 236 | - recommendations 237 | documentation: memory/SELF_IMPROVEMENT.md 238 | 239 | validation: 240 | rules: 241 | - framework_ready 242 | - session_valid 243 | - changes_valid 244 | - analysis_valid 245 | - session_format: 246 | required_sections: 247 | - Overview 248 | - Progress 249 | - Decisions 250 | - Self-Improvement 251 | - Dependencies 252 | - Next Steps 253 | - decision_format: 254 | required_fields: 255 | - title 256 | - type: decision 257 | - status: [proposed, accepted, rejected] 258 | - created: date 259 | - id: DECISION-[000] 260 | requirements: 261 | framework: 262 | - valid_structure 263 | - valid_permissions 264 | session: 265 | - valid_format 266 | - complete_fields 267 | changes: 268 | - changes_exist 269 | - valid_format 270 | analysis: 271 | - insights_valid 272 | - session_updated 273 | 274 | # AI Assistant State Validation Checklist 275 | ai_validation: 276 | - check_project_json: 277 | file: memory/project/context/project.json 278 | verify: 279 | - updated_timestamp: "Current timestamp in YYYY-MM-DDTHH:MM:SS format" 280 | - active_tasks: "Match tasks in .context/tasks/active/" 281 | - completed_tasks: "Match tasks in .context/tasks/completed/" 282 | - decisions: "Include new decisions from current session" 283 | 284 | - check_self_improvement: 285 | file: memory/project/self_improvement.json 286 | verify: 287 | - updated_timestamp: "Current timestamp" 288 | - insights: "Include new insights from current session" 289 | - recommendations: "Include new recommendations" 290 | 291 | # AI Assistant Implementation Guide 292 | ai_implementation: 293 | description: "This operation saves the current session progress and updates project state" 294 | 295 | execution_steps: 296 | 1: "Validate the current session" 297 | 2: "Collect changes and progress" 298 | 3: "Identify decisions to record" 299 | 4: "Analyze session for self-improvement insights" 300 | 5: "Update session document" 301 | 6: "Create decision records" 302 | 7: "Update self-improvement record" 303 | 8: "Update task progress" 304 | 9: "Update project context" 305 | 10: "Verify all updates" 306 | 307 | execution_flowchart: | 308 | START 309 | | 310 | v 311 | [1. VALIDATE SESSION] --> [FAIL] --> [REPORT ERROR] 312 | | | 313 | v [SUCCESS] | 314 | [2. COLLECT CHANGES] --> [NO CHANGES] -+ 315 | | | 316 | v [CHANGES EXIST] | 317 | [3. IDENTIFY DECISIONS] | 318 | | | 319 | v | 320 | [4. ANALYZE SESSION] | 321 | | | 322 | v | 323 | [5. UPDATE SESSION DOCUMENT] --------->+ 324 | | | 325 | v | 326 | [6. CREATE DECISION RECORDS] --------->+ 327 | | | 328 | v | 329 | [7. UPDATE SELF-IMPROVEMENT] --------->+ 330 | | | 331 | v | 332 | [8. UPDATE TASK PROGRESS] ------------>+ 333 | | | 334 | v | 335 | [9. UPDATE PROJECT CONTEXT] ---------->+ 336 | | | 337 | v | 338 | [10. VERIFY ALL UPDATES] --> [FAIL] -->+ 339 | | | 340 | v [SUCCESS] | 341 | [REPORT SUCCESS] <---------------------+ 342 | | 343 | v 344 | END 345 | 346 | implementation_checklist: | 347 | /aegis save checklist: 348 | [ ] Update session document (status, progress, timestamps) 349 | [ ] Create decision record for significant decisions 350 | [ ] Update self-improvement record with new insights 351 | [ ] Update task progress and status 352 | [ ] Update project.json with current task lists 353 | [ ] Update timestamps to current time 354 | [ ] Verify all files have been properly updated 355 | [ ] Confirm completion only when ALL steps are checked 356 | 357 | example_implementation: | 358 | 1. Validate the current session: 359 | - Check if there's an active session 360 | - Verify session format is valid 361 | - Check if there are changes to save 362 | 363 | 2. Collect changes and progress: 364 | - Gather changes made during the session 365 | - Collect progress updates 366 | - Format for inclusion in session document 367 | 368 | 3. Identify decisions to record: 369 | - Look for decision markers in session content 370 | - Extract decision details (title, context, decision, consequences) 371 | - Prepare for decision record creation 372 | 373 | 4. Analyze session for self-improvement insights: 374 | - Identify patterns in session activity 375 | - Generate insights based on patterns 376 | - Create recommendations for future sessions 377 | 378 | 5. Update session document: 379 | - Update session status 380 | - Add progress information 381 | - Include decisions made 382 | - Add self-improvement insights 383 | - Update timestamps 384 | 385 | 6. Create decision records: 386 | - For each significant decision: 387 | - Create a new decision record 388 | - Include context and consequences 389 | - Link to related tasks 390 | - Set appropriate status 391 | 392 | 7. Update self-improvement record: 393 | - Add new insights to self-improvement record 394 | - Update metrics based on session activity 395 | - Add new recommendations 396 | - Update timestamps 397 | 398 | 8. Update task progress: 399 | - Update progress for tasks worked on 400 | - Update task status if needed 401 | - Update task timestamps 402 | 403 | 9. Update project context: 404 | - Update activeTasks list 405 | - Update completedTasks list 406 | - Add new decisions to decisions list 407 | - Update timestamps 408 | 409 | 10. Verify all updates: 410 | - Check that session document was updated 411 | - Verify decision records were created 412 | - Confirm self-improvement record was updated 413 | - Validate task progress updates 414 | - Ensure project context is consistent 415 | 416 | error_prevention: | 417 | Common failure points: 418 | 1. Missing decision records: Always check for decision markers and create records 419 | 2. Incomplete self-improvement updates: Always update insights and recommendations 420 | 3. Inconsistent task state: Verify task lists match directory contents 421 | 4. Outdated timestamps: Always use current timestamps for all updates 422 | 423 | Prevention strategies: 424 | 1. Follow the implementation checklist completely 425 | 2. Verify each step before proceeding to the next 426 | 3. Use the validation patterns in validation.yaml 427 | 4. Confirm all files are updated before completing 428 | 5. Never skip steps in the implementation 429 | 430 | Recovery procedures: 431 | 1. If a step fails, retry with more specific instructions 432 | 2. If a file update fails, check permissions and retry 433 | 3. If validation fails, fix the issues before proceeding 434 | 4. If the command is partially implemented, complete the missing steps 435 | 5. Document any issues in the session record 436 | -------------------------------------------------------------------------------- /.context/ai/operations/session_triggers.yaml: -------------------------------------------------------------------------------- 1 | # Session Update Triggers 2 | # This file defines trigger events that prompt session updates at meaningful points 3 | # rather than arbitrary intervals, optimizing documentation and performance. 4 | 5 | trigger_types: 6 | task_progress: 7 | description: "Significant progress on the current task" 8 | detection: 9 | - pattern: "completed [3+] steps in current task" 10 | - pattern: "finished [25%|50%|75%] of task objectives" 11 | - pattern: "major milestone in current task" 12 | prompt: "I notice you've completed several steps in the current task. Would you like me to update our session document to reflect this progress?" 13 | priority: high 14 | 15 | task_transition: 16 | description: "Task state changes" 17 | detection: 18 | - pattern: "moved task from [planned|active|hold] to [active|completed|hold]" 19 | - pattern: "completed TASK-\\d{3}" 20 | - pattern: "started new task TASK-\\d{3}" 21 | - pattern: "put TASK-\\d{3} on hold" 22 | prompt: "You've just {transition_type} TASK-{task_id}. Would you like me to update the session document with this milestone?" 23 | variables: 24 | - transition_type: ["completed", "started", "put on hold", "resumed"] 25 | - task_id: "\\d{3}" 26 | priority: high 27 | 28 | decision_point: 29 | description: "Important decisions made during development" 30 | detection: 31 | - pattern: "decided to [use|implement|adopt|choose]" 32 | - pattern: "made decision about" 33 | - pattern: "chose [option|approach|method|tool]" 34 | - pattern: "selected [option|approach|method|tool]" 35 | prompt: "I see you've made an important decision about {decision_topic}. Should I document this decision in our session file?" 36 | variables: 37 | - decision_topic: "the decision topic detected" 38 | priority: high 39 | 40 | content_creation: 41 | description: "Creation of significant content or code" 42 | detection: 43 | - pattern: "created [file|document|component|module]" 44 | - pattern: "implemented [feature|functionality]" 45 | - pattern: "wrote [documentation|code] for" 46 | - pattern: "completed implementation of" 47 | prompt: "You've created significant content ({content_type}). Would you like to update the session document to capture this progress?" 48 | variables: 49 | - content_type: "the type of content created" 50 | priority: medium 51 | 52 | problem_resolution: 53 | description: "Resolution of issues or blockers" 54 | detection: 55 | - pattern: "fixed [issue|bug|error|problem]" 56 | - pattern: "resolved [blocker|dependency]" 57 | - pattern: "found solution for" 58 | - pattern: "addressed [issue|concern]" 59 | prompt: "You've resolved an important issue ({issue_type}). Should I update our session document to reflect this progress?" 60 | variables: 61 | - issue_type: "the type of issue resolved" 62 | priority: medium 63 | 64 | time_based: 65 | description: "Time-based triggers (used sparingly)" 66 | detection: 67 | - pattern: "30+ minutes since last session update" 68 | - pattern: "significant work without session update" 69 | prompt: "We've been working for a while without updating the session document. Would you like to save our progress now?" 70 | priority: low 71 | 72 | context_switch: 73 | description: "Switching focus to a different area" 74 | detection: 75 | - pattern: "switching focus to" 76 | - pattern: "moving on to" 77 | - pattern: "changing focus from [A] to [B]" 78 | prompt: "I notice you're switching focus from {previous_focus} to {new_focus}. Would you like to update our session document to reflect this change?" 79 | variables: 80 | - previous_focus: "the previous focus area" 81 | - new_focus: "the new focus area" 82 | priority: medium 83 | 84 | implementation: 85 | detection_process: 86 | - monitor_user_messages: "Analyze user messages for trigger patterns" 87 | - check_task_state: "Monitor task state changes" 88 | - track_progress: "Track completed steps and milestones" 89 | - measure_time: "Track time since last session update" 90 | 91 | response_process: 92 | - detect_trigger: "Identify trigger event" 93 | - format_prompt: "Format appropriate prompt with variables" 94 | - suggest_update: "Present update suggestion to user" 95 | - handle_response: "Process user response (yes/no)" 96 | 97 | update_process: 98 | - if_approved: 99 | - update_session: "Update session document with progress" 100 | - confirm_update: "Confirm update to user" 101 | - if_declined: 102 | - note_preference: "Note user preference" 103 | - continue_work: "Continue with current task" 104 | 105 | best_practices: 106 | - prioritize_meaningful_events: "Focus on significant milestones over minor updates" 107 | - avoid_interruption: "Don't interrupt user flow for minor updates" 108 | - combine_triggers: "Combine multiple triggers into a single update suggestion" 109 | - respect_preferences: "Learn from user responses to refine trigger sensitivity" 110 | - provide_context: "Include specific progress details in update suggestions" 111 | - balance_frequency: "Avoid too frequent or too sparse update suggestions" -------------------------------------------------------------------------------- /.context/ai/operations/start.yaml: -------------------------------------------------------------------------------- 1 | name: start 2 | description: Begin development session and load project context 3 | version: 1.0 4 | 5 | natural_language_examples: 6 | - command: "/aegis start" 7 | variations: 8 | - "start a new development session" 9 | - "begin working on the project" 10 | - "initialize a new session" 11 | - "start development" 12 | - "create new session" 13 | - command: "/aegis start --task TASK-123" 14 | variations: 15 | - "start working on TASK-123" 16 | - "begin session focusing on TASK-123" 17 | - "start development with TASK-123" 18 | - "initialize session for TASK-123" 19 | - "create new session for TASK-123" 20 | - command: "/aegis start --continue" 21 | variations: 22 | - "continue the previous session" 23 | - "resume last development session" 24 | - "pick up where I left off" 25 | - "continue development" 26 | - "resume work" 27 | 28 | validation_source: 29 | file: validation.yaml 30 | type: command_validation 31 | rules: 32 | - start 33 | input: 34 | type: command 35 | pattern: /aegis start 36 | options: 37 | - name: --task 38 | description: Start with specific task 39 | required: false 40 | - name: --continue 41 | description: Continue last session 42 | required: false 43 | validation: 44 | type: start 45 | rules: 46 | - framework_ready 47 | - valid_permissions 48 | - valid_task 49 | 50 | output: 51 | type: operation 52 | actions: 53 | - load_context 54 | - set_focus 55 | - begin_session 56 | validation: 57 | session: 58 | - format_valid 59 | - state_valid 60 | task: 61 | - exists 62 | - valid_state 63 | 64 | steps: 65 | 1_validate: 66 | - check_framework: 67 | rules: 68 | - framework_structure 69 | - required_files 70 | - permissions 71 | - load_state: 72 | rules: 73 | - memory_exists 74 | - state_valid 75 | 76 | 2_prepare: 77 | - load_context: 78 | from: memory/project 79 | required: true 80 | validation: 81 | - exists 82 | - readable 83 | - valid_format 84 | - get_last_session: 85 | from: memory/session 86 | required: false 87 | validation: 88 | - format_valid 89 | - state_valid 90 | 91 | 3_load: 92 | - load_context: 93 | type: memory 94 | required: 95 | - core 96 | - project 97 | - session 98 | optional: 99 | - decisions 100 | validation: 101 | - memory_valid 102 | - state_valid 103 | 104 | - load_decisions: 105 | directory: project/decisions 106 | filter: 107 | status: [accepted, proposed] 108 | sort: 109 | by: created 110 | order: desc 111 | limit: 5 112 | 113 | - load_tasks: 114 | directory: tasks 115 | filter: 116 | status: [active, hold] 117 | sort: 118 | by: updated 119 | order: desc 120 | 121 | 3_execute: 122 | - create_session: 123 | type: development 124 | template: session 125 | content: 126 | - context_summary 127 | - active_tasks 128 | - recent_changes 129 | validation: 130 | - format_valid 131 | - required_fields 132 | 133 | - set_focus: 134 | type: task 135 | source: 136 | - option: --task 137 | - last: active_task 138 | - state: next_task 139 | validation: 140 | task: 141 | - exists 142 | - valid_state 143 | state: 144 | - valid_transition 145 | - allows_focus 146 | 147 | - update_state: 148 | type: framework 149 | status: development 150 | validation: 151 | - valid_state 152 | - valid_transition 153 | 154 | 4_present: 155 | - show_context: 156 | sections: 157 | - active_task 158 | - recent_decisions 159 | - current_focus 160 | - next_steps 161 | 162 | 4_verify: 163 | - validate_session: 164 | type: session 165 | rules: 166 | - format_valid 167 | - state_valid 168 | 169 | - check_focus: 170 | type: task 171 | rules: 172 | - task_exists 173 | - focus_valid 174 | 175 | - verify_state: 176 | type: framework 177 | rules: 178 | - state_valid 179 | - session_active 180 | 181 | errors: 182 | framework: 183 | structure: Framework structure invalid 184 | permissions: Missing required permissions 185 | state: Invalid framework state 186 | session: 187 | creation: Session creation failed 188 | format: Invalid session format 189 | focus: Missing task focus 190 | task: 191 | missing: Task not found 192 | state: Invalid task state 193 | focus: Task focus failed 194 | 195 | recovery: 196 | framework: 197 | structure: Validate framework structure 198 | permissions: Check and fix permissions 199 | state: Restore framework state 200 | session: 201 | creation: Retry session creation 202 | format: Fix session format 203 | focus: Set default focus 204 | task: 205 | missing: Select valid task 206 | state: Fix task state 207 | focus: Reset task focus 208 | 209 | templates: 210 | session: 211 | format: json 212 | source: .context/templates/sessions/TEMPLATE.md 213 | required_fields: 214 | - session_id 215 | - start_time 216 | - active_task 217 | sections: 218 | - context 219 | - focus 220 | - state 221 | 222 | validation: 223 | rules: 224 | - framework_ready 225 | - session_valid 226 | - task_valid 227 | requirements: 228 | framework: 229 | - valid_structure 230 | - valid_permissions 231 | session: 232 | - valid_format 233 | - complete_fields 234 | task: 235 | - valid_state 236 | - allows_focus 237 | 238 | # Command Template with Required Components 239 | command_template: 240 | name: start 241 | description: "Template for implementing the start command" 242 | version: 1.0 243 | 244 | required_components: 245 | pre_execution: 246 | - session_check: 247 | description: "Check if there's already an active session" 248 | validation: 249 | - session_status_valid: "Session status must be checked" 250 | implementation: | 251 | 1. Check if active.json exists in memory/session/ 252 | 2. Verify if there's an active session 253 | 3. If continuing a session, load the existing session data 254 | 4. If starting a new session, ensure no conflicts with existing sessions 255 | 256 | - focus_identification: 257 | description: "Identify the focus for the new session" 258 | validation: 259 | - focus_valid: "Focus must be valid" 260 | implementation: | 261 | 1. Check for --task option to set specific focus 262 | 2. If no task specified, identify most relevant active task 263 | 3. If no active tasks, suggest creating or starting a task 264 | 4. Validate that the focus task exists and is in a valid state 265 | 266 | - context_loading: 267 | description: "Load relevant context for the session" 268 | validation: 269 | - context_loaded: "Context must be loaded" 270 | implementation: | 271 | 1. Load project context from memory/project/context/project.json 272 | 2. Load active tasks from tasks/active/ 273 | 3. Load recent decisions from decisions/ 274 | 4. Load self-improvement recommendations 275 | 276 | execution: 277 | - session_creation: 278 | description: "Create a new session document" 279 | validation: 280 | - template_exists: "Session template must exist" 281 | - session_created: "Session document must be created" 282 | - format_valid: "Session must have valid format" 283 | implementation: | 284 | 1. Generate session ID from date 285 | 2. Copy session template to new file 286 | 3. Update session metadata (front matter) 287 | 4. Initialize session sections 288 | 289 | - focus_setting: 290 | description: "Set the session focus" 291 | validation: 292 | - focus_valid: "Focus must be valid" 293 | - task_exists: "Focus task must exist" 294 | - transition_valid: "Task state transition must be valid" 295 | implementation: | 296 | 1. Identify focus task 297 | 2. If needed, move task from planned to active 298 | 3. Set focus in session document 299 | 4. Update task state if needed 300 | 301 | - code_context_loading: 302 | description: "Load relevant code context for focused task" 303 | validation: 304 | - task_exists: "Task must exist to load code context" 305 | - context_valid: "Code context section must be valid" 306 | implementation: | 307 | 1. Read Code Context section from focused task 308 | 2. Prioritize code files by relevance score 309 | 3. Load high relevance (≥0.7) code immediately 310 | 4. Prepare search instructions for medium relevance (0.3-0.6) code 311 | 5. Note low relevance (<0.3) code for reference only when needed 312 | 6. Track loaded code in session for context management 313 | 7. Verify no .context/ directory files are included 314 | 8. Focus exclusively on source code files relevant to implementation 315 | 316 | - recommendations_loading: 317 | description: "Load self-improvement recommendations" 318 | validation: 319 | - recommendations_loaded: "Recommendations must be loaded" 320 | implementation: | 321 | 1. Load recommendations from self_improvement.json 322 | 2. Filter for relevant recommendations 323 | 3. Include recommendations in session document 324 | 325 | - session_memory_update: 326 | description: "Update session memory with new session" 327 | validation: 328 | - memory_updated: "Session memory must be updated" 329 | implementation: | 330 | 1. Update active.json with new session information 331 | 2. Set sessionId, status, started timestamp 332 | 3. Set activeTask and currentStep 333 | 4. Initialize progress tracking 334 | 335 | post_execution: 336 | - session_verification: 337 | description: "Verify session document has been created" 338 | validation: 339 | - file_exists: "Session file must exist" 340 | - content_valid: "Session content must be valid" 341 | implementation: | 342 | 1. Verify session document exists 343 | 2. Check that all required sections are present 344 | 3. Validate front matter and content 345 | 346 | - memory_verification: 347 | description: "Verify session memory has been updated" 348 | validation: 349 | - memory_updated: "Session memory must be updated" 350 | implementation: | 351 | 1. Verify active.json has been updated 352 | 2. Check that sessionId matches new session 353 | 3. Verify status is set to "active" 354 | 4. Confirm timestamps are current 355 | 356 | - reporting: 357 | description: "Report session start results" 358 | validation: 359 | - report_complete: "Report must include all session details" 360 | implementation: | 361 | 1. Generate summary of the session start 362 | 2. Include focus and context information 363 | 3. List active tasks and recommendations 364 | 365 | error_handling: 366 | - error_detection: 367 | description: "Detect and handle errors" 368 | validation: 369 | - errors_handled: "All potential errors must be handled" 370 | implementation: | 371 | 1. Check for common errors (missing files, invalid state) 372 | 2. Implement recovery procedures 373 | 3. Log errors and recovery attempts 374 | 375 | - consistency_check: 376 | description: "Ensure system consistency" 377 | validation: 378 | - state_consistent: "System state must be consistent" 379 | implementation: | 380 | 1. Verify session document and memory are in sync 381 | 2. Check that project context reflects current state 382 | 3. Fix inconsistencies if found 383 | 384 | implementation_example: | 385 | # Example implementation of /aegis start --task TASK-123 386 | 387 | ## Pre-execution 388 | 1. Check for active session: 389 | - Verify if there's an active session in memory/session/active.json 390 | - If continuing, load existing session data 391 | - If new session, ensure no conflicts 392 | 2. Identify focus: 393 | - Task TASK-123 specified via --task option 394 | - Verify TASK-123 exists and is in a valid state 395 | 3. Load context: 396 | - Load project context from memory/project/context/project.json 397 | - Load active tasks from tasks/active/ 398 | - Load recent decisions and recommendations 399 | 400 | ## Execution 401 | 1. Create session document: 402 | - Generate session ID: SESSION-2025-03-12 403 | - Copy template from .context/templates/sessions/TEMPLATE.md to sessions/2025-03-12-session.md 404 | - Set metadata (created, updated timestamps) 405 | - Set status to "active" 406 | 2. Set focus: 407 | - Set focus to TASK-123 408 | - If TASK-123 is in planned/, move to active/ 409 | - Document focus in session Progress section 410 | 3. Load code context: 411 | - Read Code Context section from TASK-123 412 | - Load high relevance code files immediately 413 | - Prepare search instructions for medium relevance files 414 | - Note low relevance files for reference only 415 | - Track loaded code in session for context management 416 | 4. Load recommendations: 417 | - Include relevant recommendations from self_improvement.json 418 | 5. Update session memory: 419 | - Update active.json with new session information 420 | - Set sessionId, status, started timestamp 421 | - Set activeTask to TASK-123 422 | 423 | ## Post-execution 424 | 1. Verify session document: 425 | - Confirm sessions/2025-03-12-session.md exists 426 | - Verify all required sections are present 427 | - Validate front matter and content 428 | 2. Verify session memory: 429 | - Confirm active.json has been updated 430 | - Verify sessionId matches SESSION-2025-03-12 431 | - Confirm status is "active" 432 | 3. Report results: 433 | - Generate summary of session start 434 | - Include focus on TASK-123 435 | - List active tasks and recommendations 436 | 437 | ## Error handling 438 | 1. Check for errors: 439 | - If TASK-123 doesn't exist, suggest alternatives 440 | - If session creation fails, retry or report error 441 | 2. Ensure consistency: 442 | - Verify session document and memory are in sync 443 | - Check that project context is up to date 444 | -------------------------------------------------------------------------------- /.context/ai/operations/status.yaml: -------------------------------------------------------------------------------- 1 | name: status 2 | description: Show current project state and progress 3 | version: 1.0 4 | 5 | validation_source: 6 | file: validation.yaml 7 | type: command_validation 8 | rules: 9 | - status 10 | 11 | input: 12 | type: command 13 | pattern: /aegis status 14 | options: 15 | - name: --detail 16 | description: Show detailed status 17 | required: false 18 | validation: 19 | type: status 20 | rules: 21 | - framework_ready 22 | - valid_permissions 23 | 24 | output: 25 | type: operation 26 | actions: 27 | - show_status 28 | - display_progress 29 | validation: 30 | status: 31 | - format_valid 32 | - content_complete 33 | display: 34 | - readable 35 | - organized 36 | 37 | steps: 38 | 1_validate: 39 | - check_framework: 40 | rules: 41 | - framework_structure 42 | - required_files 43 | - permissions 44 | - load_state: 45 | rules: 46 | - memory_exists 47 | - state_valid 48 | 49 | 2_prepare: 50 | - get_project: 51 | from: memory/project 52 | required: true 53 | validation: 54 | - exists 55 | - readable 56 | - valid_format 57 | - get_session: 58 | from: memory/session 59 | required: false 60 | validation: 61 | - format_valid 62 | - state_valid 63 | 64 | 3_execute: 65 | - collect_status: 66 | sources: 67 | - project_state 68 | - active_tasks 69 | - recent_changes 70 | validation: 71 | - sources_exist 72 | - data_valid 73 | 74 | - format_output: 75 | type: status 76 | format: markdown 77 | sections: 78 | - overview 79 | - tasks 80 | - changes 81 | validation: 82 | - format_valid 83 | - sections_complete 84 | 85 | 4_verify: 86 | - validate_output: 87 | type: status 88 | rules: 89 | - format_valid 90 | - content_complete 91 | 92 | - check_content: 93 | type: display 94 | rules: 95 | - readable 96 | - organized 97 | - accurate 98 | 99 | errors: 100 | framework: 101 | structure: Framework structure invalid 102 | permissions: Missing required permissions 103 | state: Invalid framework state 104 | status: 105 | collection: Status collection failed 106 | format: Invalid status format 107 | content: Missing required content 108 | display: 109 | format: Display format error 110 | readability: Content not readable 111 | organization: Poor content organization 112 | 113 | recovery: 114 | framework: 115 | structure: Validate framework structure 116 | permissions: Check and fix permissions 117 | state: Restore framework state 118 | status: 119 | collection: Retry status collection 120 | format: Fix status format 121 | content: Load required content 122 | display: 123 | format: Fix display format 124 | readability: Improve readability 125 | organization: Reorganize content 126 | 127 | templates: 128 | status: 129 | format: markdown 130 | required_sections: 131 | - overview 132 | - tasks 133 | - changes 134 | display_rules: 135 | - clear_headers 136 | - consistent_format 137 | - proper_indentation 138 | 139 | validation: 140 | rules: 141 | - framework_ready 142 | - status_valid 143 | - display_valid 144 | requirements: 145 | framework: 146 | - valid_structure 147 | - valid_permissions 148 | status: 149 | - valid_format 150 | - complete_sections 151 | display: 152 | - readable 153 | - organized 154 | 155 | # Command Template with Required Components 156 | command_template: 157 | name: status 158 | description: "Template for implementing the status command" 159 | version: 1.0 160 | 161 | required_components: 162 | pre_execution: 163 | - project_context_loading: 164 | description: "Load project context" 165 | validation: 166 | - context_loaded: "Project context must be loaded" 167 | implementation: | 168 | 1. Load project context from memory/project/context/project.json 169 | 2. Verify project context is valid 170 | 3. Extract relevant information (name, version, phase, etc.) 171 | 172 | - active_task_loading: 173 | description: "Load active tasks" 174 | validation: 175 | - tasks_loaded: "Active tasks must be loaded" 176 | implementation: | 177 | 1. Load active tasks from tasks/active/ 178 | 2. Sort tasks by priority and updated timestamp 179 | 3. Extract relevant information (title, progress, etc.) 180 | 181 | - recent_changes_loading: 182 | description: "Load recent changes" 183 | validation: 184 | - changes_loaded: "Recent changes must be loaded" 185 | implementation: | 186 | 1. Load recent session documents from sessions/ 187 | 2. Extract changes and progress information 188 | 3. Sort by timestamp (most recent first) 189 | 190 | execution: 191 | - status_report_generation: 192 | description: "Generate status report" 193 | validation: 194 | - report_generated: "Status report must be generated" 195 | implementation: | 196 | 1. Create status report structure 197 | 2. Include project overview section 198 | 3. Format information in a readable way 199 | 200 | - active_tasks_inclusion: 201 | description: "Include active tasks in report" 202 | validation: 203 | - tasks_included: "Active tasks must be included in report" 204 | implementation: | 205 | 1. Format active tasks information 206 | 2. Include task titles, IDs, and progress 207 | 3. Sort by priority and status 208 | 209 | - recent_changes_inclusion: 210 | description: "Include recent changes in report" 211 | validation: 212 | - changes_included: "Recent changes must be included in report" 213 | implementation: | 214 | 1. Format recent changes information 215 | 2. Include session dates and key progress points 216 | 3. Limit to most relevant/recent changes 217 | 218 | - self_improvement_inclusion: 219 | description: "Include self-improvement insights in report" 220 | validation: 221 | - insights_included: "Self-improvement insights must be included in report" 222 | implementation: | 223 | 1. Load insights from self_improvement.json 224 | 2. Filter for most relevant insights 225 | 3. Include in report with priority indicators 226 | 227 | post_execution: 228 | - report_verification: 229 | description: "Verify report is complete" 230 | validation: 231 | - report_complete: "Report must include all required sections" 232 | implementation: | 233 | 1. Verify all required sections are present 234 | 2. Check that information is current and accurate 235 | 3. Ensure report is properly formatted 236 | 237 | - display_formatting: 238 | description: "Format report for display" 239 | validation: 240 | - format_valid: "Report format must be valid" 241 | implementation: | 242 | 1. Apply consistent formatting 243 | 2. Use clear section headers 244 | 3. Ensure proper indentation and spacing 245 | 246 | error_handling: 247 | - error_detection: 248 | description: "Detect and handle errors" 249 | validation: 250 | - errors_handled: "All potential errors must be handled" 251 | implementation: | 252 | 1. Check for common errors (missing files, invalid format) 253 | 2. Implement fallback mechanisms for missing data 254 | 3. Provide clear error messages if needed 255 | 256 | - data_validation: 257 | description: "Validate data completeness" 258 | validation: 259 | - data_valid: "All data must be valid" 260 | implementation: | 261 | 1. Verify all required data is available 262 | 2. Check for inconsistencies in data 263 | 3. Use default values for missing non-critical data 264 | 265 | implementation_example: | 266 | # Example implementation of /aegis status 267 | 268 | ## Pre-execution 269 | 1. Load project context: 270 | - Load project.json from memory/project/context/ 271 | - Extract project name, version, phase 272 | - Get lists of active, completed, and planned tasks 273 | 2. Load active tasks: 274 | - Read all files in tasks/active/ 275 | - Sort by priority (high to low) 276 | - Extract titles, IDs, and progress information 277 | 3. Load recent changes: 278 | - Read recent session files from sessions/ 279 | - Extract progress information 280 | - Sort by date (newest first) 281 | 282 | ## Execution 283 | 1. Generate status report: 284 | - Create report structure with sections 285 | - Add project overview (name, version, phase) 286 | - Format in a readable way 287 | 2. Include active tasks: 288 | - Format list of active tasks 289 | - Include task titles, IDs, and progress 290 | - Highlight high-priority tasks 291 | 3. Include recent changes: 292 | - Add section for recent changes 293 | - List sessions with dates and key progress 294 | - Limit to 3 most recent sessions 295 | 4. Include self-improvement insights: 296 | - Add relevant insights from self_improvement.json 297 | - Include high-priority recommendations 298 | 299 | ## Post-execution 300 | 1. Verify report: 301 | - Check that all sections are present 302 | - Verify information is current and accurate 303 | - Ensure report is complete 304 | 2. Format for display: 305 | - Apply consistent formatting 306 | - Use clear section headers 307 | - Ensure proper spacing and indentation 308 | 309 | ## Error handling 310 | 1. Handle missing data: 311 | - If project.json is missing, report error 312 | - If no active tasks, indicate "No active tasks" 313 | - If no recent sessions, indicate "No recent activity" 314 | 2. Validate data: 315 | - Check for inconsistencies in task states 316 | - Verify timestamps are valid 317 | - Use default values for non-critical missing data 318 | -------------------------------------------------------------------------------- /.context/ai/operations/task.yaml: -------------------------------------------------------------------------------- 1 | name: task 2 | description: Manage tasks and track progress 3 | version: 1.0 4 | 5 | natural_language_examples: 6 | - command: "/aegis task create" 7 | variations: 8 | - "create a new task" 9 | - "add a task to the project" 10 | - "make a new task" 11 | - "start tracking a new task" 12 | - "add work item" 13 | - command: "/aegis task start TASK-123" 14 | variations: 15 | - "start working on TASK-123" 16 | - "begin TASK-123" 17 | - "move TASK-123 to active" 18 | - "transition TASK-123 to active" 19 | - "activate TASK-123" 20 | - command: "/aegis task complete TASK-123" 21 | variations: 22 | - "complete TASK-123" 23 | - "mark TASK-123 as done" 24 | - "finish TASK-123" 25 | - "move TASK-123 to completed" 26 | - "TASK-123 is finished" 27 | - command: "/aegis task hold TASK-123" 28 | variations: 29 | - "put TASK-123 on hold" 30 | - "pause work on TASK-123" 31 | - "temporarily stop TASK-123" 32 | - "move TASK-123 to hold" 33 | - "block TASK-123" 34 | - command: "/aegis task resume TASK-123" 35 | variations: 36 | - "resume TASK-123" 37 | - "continue working on TASK-123" 38 | - "restart TASK-123" 39 | - "unblock TASK-123" 40 | - "move TASK-123 back to active" 41 | - command: "/aegis task update TASK-123 --priority high" 42 | variations: 43 | - "update TASK-123 priority to high" 44 | - "change TASK-123 priority to high" 45 | - "set TASK-123 as high priority" 46 | - "make TASK-123 high priority" 47 | - "TASK-123 should be high priority" 48 | 49 | validation_source: 50 | file: validation.yaml 51 | type: command_validation 52 | rules: 53 | - task 54 | 55 | input: 56 | type: command 57 | pattern: /aegis task 58 | options: 59 | - name: --start 60 | description: Start task 61 | required: false 62 | - name: --complete 63 | description: Complete task 64 | required: false 65 | - name: --hold 66 | description: Hold task 67 | required: false 68 | validation: 69 | type: task 70 | rules: 71 | - framework_ready 72 | - valid_task 73 | - valid_transition 74 | 75 | output: 76 | type: operation 77 | actions: 78 | - manage_task 79 | - update_state 80 | validation: 81 | task: 82 | - format_valid 83 | - state_valid 84 | transition: 85 | - valid_state 86 | - allowed_move 87 | 88 | steps: 89 | 1_validate: 90 | - check_framework: 91 | rules: 92 | - framework_structure 93 | - required_files 94 | - permissions 95 | - verify_task: 96 | rules: 97 | - exists 98 | - valid_format 99 | - correct_state 100 | 101 | 2_create_task: 102 | action: create_task 103 | use: task_creation.yaml 104 | validate: 105 | - template_valid 106 | - content_complete 107 | - location_correct 108 | 109 | 2_transition: 110 | action: task_transition 111 | use: task_transition.yaml 112 | validate: 113 | - transition_valid 114 | - no_duplicates 115 | 116 | 3_verify: 117 | action: verify_result 118 | checks: 119 | - file_location 120 | - state_updated 121 | - no_duplicates 122 | 123 | errors: 124 | framework: 125 | structure: Framework structure invalid 126 | permissions: Missing required permissions 127 | state: Invalid framework state 128 | task: 129 | missing: Task not found 130 | format: Invalid task format 131 | state: Invalid task state 132 | transition: 133 | invalid: Invalid state transition 134 | failed: Transition failed 135 | location: Wrong task location 136 | 137 | recovery: 138 | framework: 139 | structure: Validate framework structure 140 | permissions: Check and fix permissions 141 | state: Restore framework state 142 | task: 143 | missing: Locate or create task 144 | format: Fix task format 145 | state: Correct task state 146 | transition: 147 | invalid: Check valid transitions 148 | failed: Retry transition 149 | location: Move to correct location 150 | 151 | error_handling: 152 | duplicate_prevention: 153 | - check: "Find any duplicate task files" 154 | - action: "Remove duplicates, keep correct state version" 155 | - verify: "Only one copy exists in correct location" 156 | 157 | state_mismatch: 158 | - check: "Verify task state matches location" 159 | - action: "Move to correct location if needed" 160 | - verify: "State and location are consistent" 161 | 162 | templates: 163 | task: 164 | source: .context/templates/tasks/TEMPLATE.md 165 | required: true 166 | validation: 167 | - exists 168 | - format_valid 169 | - content_complete 170 | 171 | # Task Creation Rules 172 | rules: 173 | 1_template: 174 | - Always use TEMPLATE.md from templates/tasks/ 175 | - Copy entire template structure 176 | - Fill all required fields 177 | - Update front matter 178 | 179 | 2_location: 180 | - New tasks in planned/ 181 | - Transitions use mv command 182 | - Verify target exists 183 | - No duplicate files 184 | 185 | 3_content: 186 | - Use descriptive titles 187 | - Include objectives 188 | - List concrete steps 189 | - Note dependencies 190 | - Track progress 191 | 192 | # Error Prevention 193 | safeguards: 194 | - template_check: "Verify template exists" 195 | 196 | # Command Template with Required Components 197 | command_template: 198 | name: task 199 | description: "Template for implementing the task command" 200 | version: 1.0 201 | 202 | required_components: 203 | pre_execution: 204 | - task_identification: 205 | description: "Identify the task operation (create, start, complete, hold)" 206 | validation: 207 | - operation_valid: "Operation must be one of: create, start, complete, hold" 208 | - task_specified: "Task ID must be specified for start, complete, hold operations" 209 | implementation: | 210 | 1. Parse command options (--start, --complete, --hold) 211 | 2. Determine operation type 212 | 3. Validate operation parameters 213 | 4. Load task context if task ID is provided 214 | 215 | - state_validation: 216 | description: "Validate the current task state" 217 | validation: 218 | - task_exists: "Task must exist for start, complete, hold operations" 219 | - state_valid: "Current task state must be valid for the operation" 220 | - transition_allowed: "State transition must be allowed" 221 | implementation: | 222 | 1. Check if task file exists 223 | 2. Verify task format is valid 224 | 3. Check current task state 225 | 4. Validate that the requested transition is allowed 226 | 227 | execution: 228 | - task_operation: 229 | description: "Perform the requested task operation" 230 | validation: 231 | - operation_valid: "Operation must be valid" 232 | - parameters_valid: "Operation parameters must be valid" 233 | implementation: | 234 | 1. For create: Copy template and create new task file 235 | 2. For start: Move task from planned to active 236 | 3. For complete: 237 | - Check Test Status section value 238 | - If status is "Passing" or "Not Applicable", proceed normally 239 | - If status is "Failing" or "Not Started", prompt user for confirmation 240 | - Only after confirmation or if status is acceptable, move task from active to completed 241 | 4. For hold: Move task from active to hold 242 | 243 | - task_update: 244 | description: "Update the task document" 245 | validation: 246 | - file_exists: "Task file must exist" 247 | - format_valid: "Task format must be valid" 248 | implementation: | 249 | 1. Update task front matter (status, updated timestamp) 250 | 2. Update task progress section 251 | 3. Update task next steps section 252 | 4. Maintain Code Context section: 253 | - Add newly discovered relevant files 254 | - Update relevance scores based on usage 255 | - Add specific line number ranges when possible 256 | - Remove or downgrade irrelevant files 257 | - NEVER include files from .context/ directory 258 | - Focus exclusively on source code files relevant to implementation 259 | - For framework tasks, include only specific framework files being modified 260 | 261 | - project_update: 262 | description: "Update project context with task changes" 263 | validation: 264 | - file_exists: "Project context file must exist" 265 | - format_valid: "Project context format must be valid" 266 | implementation: | 267 | 1. Update activeTasks list 268 | 2. Update completedTasks list 269 | 3. Update plannedTasks list 270 | 4. Update project.json timestamp 271 | 272 | post_execution: 273 | - verification: 274 | description: "Verify task operation was successful" 275 | validation: 276 | - file_location: "Task file must be in the correct location" 277 | - content_valid: "Task content must be valid" 278 | - project_updated: "Project context must be updated" 279 | implementation: | 280 | 1. Verify task file is in the correct directory 281 | 2. Verify task front matter is updated correctly 282 | 3. Verify project.json is updated correctly 283 | 284 | - reporting: 285 | description: "Report task operation results" 286 | validation: 287 | - report_complete: "Report must include all operation details" 288 | implementation: | 289 | 1. Generate summary of the operation 290 | 2. Include task details 291 | 3. Include next steps 292 | 293 | error_handling: 294 | - error_detection: 295 | description: "Detect and handle errors" 296 | validation: 297 | - errors_handled: "All potential errors must be handled" 298 | implementation: | 299 | 1. Check for common errors (missing files, invalid state) 300 | 2. Implement recovery procedures 301 | 3. Log errors and recovery attempts 302 | 303 | - consistency_check: 304 | description: "Ensure system consistency" 305 | validation: 306 | - no_duplicates: "No duplicate task files" 307 | - state_consistent: "Task state consistent with location" 308 | implementation: | 309 | 1. Check for duplicate task files 310 | 2. Verify task state matches directory location 311 | 3. Fix inconsistencies if found 312 | 313 | implementation_example: | 314 | # Example implementation of /aegis task start TASK-123 315 | 316 | ## Pre-execution 317 | 1. Identify operation: start task TASK-123 318 | 2. Validate current state: 319 | - Check if TASK-123 exists in planned/ 320 | - Verify task format is valid 321 | - Confirm transition from planned to active is allowed 322 | 323 | ## Execution 324 | 1. Perform task operation: 325 | - Move TASK-123 from planned/ to active/ 326 | 2. Update task document: 327 | - Change status to "active" 328 | - Update timestamp to current time 329 | - Add entry to Progress section 330 | 3. Update project context: 331 | - Add TASK-123 to activeTasks list 332 | - Remove TASK-123 from plannedTasks list 333 | - Update project.json timestamp 334 | 335 | ## Post-execution 336 | 1. Verify operation: 337 | - Confirm TASK-123 is in active/ directory 338 | - Verify front matter is updated correctly 339 | - Verify project.json is updated correctly 340 | 2. Report results: 341 | - Generate summary of the operation 342 | - Include task details and next steps 343 | 344 | ## Error handling 345 | 1. Check for errors: 346 | - If task file is missing, report error 347 | - If state transition is invalid, report error 348 | 2. Ensure consistency: 349 | - Check for duplicate task files 350 | - Verify task state matches directory location 351 | 352 | # AI Assistant State Validation Checklist 353 | ai_validation: 354 | - after_task_transition: 355 | update_files: 356 | - file: memory/project/context/project.json 357 | fields: 358 | - updated: "Current timestamp in YYYY-MM-DDTHH:MM:SS format" 359 | - activeTasks: "Array of task IDs from .context/tasks/active/" 360 | - completedTasks: "Array of task IDs from .context/tasks/completed/" 361 | 362 | verification_steps: 363 | - "Verify project.json updated timestamp is current" 364 | - "Verify activeTasks array matches actual active tasks" 365 | - "Verify completedTasks array matches actual completed tasks" 366 | - "Verify no duplicate task entries exist in arrays" 367 | -------------------------------------------------------------------------------- /.context/ai/operations/task_creation.yaml: -------------------------------------------------------------------------------- 1 | # Task Creation Operation Pattern 2 | version: 1.0 3 | command: internal 4 | description: "Standardized task creation operation" 5 | 6 | template: 7 | source: .context/templates/tasks/TEMPLATE.md 8 | required: true 9 | validation: 10 | - exists: {error: "Template file not found"} 11 | - format: {error: "Invalid template format"} 12 | 13 | flow: 14 | pre_checks: 15 | - template_ready: {verify: template_check, error: "Template not ready"} 16 | - front_matter_valid: {verify: front_matter_check, error: "Invalid front matter"} 17 | 18 | steps: 19 | 1_load_template: 20 | action: load_template 21 | file: ${template.source} 22 | validate: 23 | - structure: {error: "Invalid template structure"} 24 | - front_matter: {error: "Invalid template front matter"} 25 | 26 | 2_create_task: 27 | action: create_task_file 28 | template: ${loaded_template} 29 | timestamps: 30 | created: "${local_time}" 31 | updated: "${local_time}" 32 | validate: 33 | - id_format: {pattern: "TASK-\\d{3}", error: "Invalid task ID format"} 34 | - required_fields: {error: "Missing required fields"} 35 | - front_matter: {error: "Invalid front matter"} 36 | - timestamps: {error: "Invalid timestamps"} 37 | required_fields: 38 | - type: task 39 | - status: [planned|active|hold|completed] 40 | - created: "${local_time}" 41 | - updated: "${local_time}" 42 | - id: TASK-[000] 43 | - priority: [high|medium|low] 44 | - memory_types: list 45 | 46 | 3_validate_task: 47 | action: validate_task 48 | checks: 49 | - file_exists: {error: "Task file not created"} 50 | - content_valid: {error: "Task content invalid"} 51 | - front_matter: {error: "Front matter invalid"} 52 | 53 | # Task Creation Rules 54 | rules: 55 | 1_template: 56 | - Always use TEMPLATE.md as base 57 | - Maintain template structure 58 | - Keep all sections 59 | 60 | 2_location: 61 | - New tasks go to planned/ 62 | - Use correct task ID format 63 | - Update front matter 64 | 65 | 3_content: 66 | - Fill all required fields 67 | - Use descriptive titles 68 | - Include clear objectives 69 | - List concrete steps 70 | - Note dependencies 71 | 72 | # Error Prevention 73 | safeguards: 74 | - template_check: "Verify template exists and is valid" 75 | - id_unique: "Ensure task ID is unique" 76 | - location_valid: "Verify target directory exists" 77 | - content_complete: "Check all required sections filled" 78 | -------------------------------------------------------------------------------- /.context/ai/operations/task_transition.yaml: -------------------------------------------------------------------------------- 1 | # Task Transition Operation Pattern 2 | version: 1.0 3 | command: internal 4 | description: "Standardized task state transition operation" 5 | 6 | validation: 7 | source: validation.yaml 8 | rules: 9 | - file_operations.move 10 | - state_transitions.task 11 | 12 | flow: 13 | pre_checks: 14 | - task_exists: {verify: file_exists, error: "Task file not found"} 15 | - valid_state: {verify: state_valid, error: "Invalid current state"} 16 | - allowed_transition: {verify: transition_allowed, error: "Transition not allowed"} 17 | 18 | steps: 19 | 1_prepare_transition: 20 | action: validate_transition 21 | checks: 22 | - current_state: {type: state_check} 23 | - target_state: {type: state_valid} 24 | - transition: {type: allowed_transition} 25 | 26 | 2_check_test_status: 27 | action: check_test_status 28 | condition: ${operation} == "complete" 29 | checks: 30 | - test_status_section: {type: section_exists, section: "Test Status", error: "Test Status section not found"} 31 | - test_status: {type: extract_value, pattern: "Status: ([\\w\\s]+)", section: "Test Status", error: "Test status not found"} 32 | responses: 33 | - condition: ${test_status} == "Passing" || ${test_status} == "Not Applicable" 34 | action: proceed 35 | - condition: ${test_status} == "Failing" || ${test_status} == "Not Started" 36 | action: user_prompt 37 | message: "Warning: Task has test status '${test_status}'. Do you want to complete it anyway? (yes/no)" 38 | responses: 39 | - yes: proceed 40 | - no: abort 41 | validate: 42 | - status_valid: {error: "Invalid test status value"} 43 | 44 | 3_update_task: 45 | action: update_frontmatter 46 | updates: 47 | - field: status 48 | value: ${target_state} 49 | - field: updated 50 | value: "${local_time}" 51 | - field: state_changed 52 | value: "${local_time}" 53 | validate: 54 | - timestamps: {error: "Invalid timestamps"} 55 | 56 | 4_move_file: 57 | action: move_file 58 | source: ${current_path} 59 | target: ${target_path} 60 | validate: 61 | - source_exists: {error: "Source file must exist"} 62 | - target_valid: {error: "Target directory must be valid"} 63 | - permissions_ok: {error: "Must have write permissions"} 64 | 65 | 5_verify: 66 | action: verify_transition 67 | checks: 68 | - file_moved: {type: file_check} 69 | - state_updated: {type: state_check} 70 | 71 | # Directory mappings for state transitions 72 | state_directories: 73 | planned: tasks/planned 74 | active: tasks/active 75 | completed: tasks/completed 76 | hold: tasks/hold 77 | 78 | # Explicit move operations 79 | move_operations: 80 | start: 81 | from: planned 82 | to: active 83 | command: mv ${source} ${target} 84 | 85 | complete: 86 | from: active 87 | to: completed 88 | command: mv ${source} ${target} 89 | 90 | hold: 91 | from: active 92 | to: hold 93 | command: mv ${source} ${target} 94 | 95 | resume: 96 | from: hold 97 | to: active 98 | command: mv ${source} ${target} 99 | 100 | # Error prevention 101 | safeguards: 102 | - no_copy: "Always use move operations, never copy" 103 | - verify_move: "Verify file exists in new location" 104 | - cleanup: "Remove any duplicate files" 105 | - state_check: "Verify state matches directory" 106 | 107 | # Test Status validation 108 | test_status: 109 | valid_values: 110 | - "Not Started" 111 | - "Failing" 112 | - "Passing" 113 | - "Not Applicable" 114 | completion_checks: 115 | auto_complete: 116 | - "Passing" 117 | - "Not Applicable" 118 | confirm_required: 119 | - "Failing" 120 | - "Not Started" 121 | error_messages: 122 | invalid_status: "Invalid test status: must be one of Not Started, Failing, Passing, or Not Applicable" 123 | missing_section: "Missing Test Status section: all tasks must include this section" 124 | confirmation_required: "Task has tests in '${status}' state. Confirmation required to complete." 125 | 126 | transitions: 127 | start: 128 | from: planned 129 | to: active 130 | update: 131 | - status 132 | - start_time 133 | 134 | complete: 135 | from: active 136 | to: completed 137 | update: 138 | - status 139 | - end_time 140 | 141 | hold: 142 | from: active 143 | to: hold 144 | update: 145 | - status 146 | - hold_time 147 | 148 | resume: 149 | from: hold 150 | to: active 151 | update: 152 | - status 153 | - resume_time 154 | -------------------------------------------------------------------------------- /.context/ai/operations/validation.yaml: -------------------------------------------------------------------------------- 1 | # Operation Validation Rules 2 | version: 1.0 3 | description: Central validation rules for framework operations 4 | 5 | # File System Operations 6 | file_operations: 7 | move: 8 | rules: 9 | - source_exists: "Source file must exist" 10 | - target_valid: "Target directory must be valid" 11 | - permissions_ok: "Must have write permissions" 12 | patterns: 13 | task_move: 14 | - from: "tasks/planned/" 15 | to: "tasks/active/" 16 | requires: "start" 17 | - from: "tasks/active/" 18 | to: "tasks/completed/" 19 | requires: "complete" 20 | - from: "tasks/active/" 21 | to: "tasks/hold/" 22 | requires: "hold" 23 | - from: "tasks/hold/" 24 | to: "tasks/active/" 25 | requires: "resume" 26 | validation: 27 | rules: 28 | file_operations: 29 | move: 30 | command: mv 31 | disallowed: 32 | - cp 33 | - copy 34 | error: "Must use mv command for task transitions, never cp or copy" 35 | validate: 36 | - source_exists 37 | - target_valid 38 | - no_duplicates 39 | 40 | # State Transitions 41 | state_transitions: 42 | task: 43 | states: 44 | - planned 45 | - active 46 | - completed 47 | - hold 48 | allowed: 49 | planned: 50 | - to: active 51 | command: start 52 | active: 53 | - to: completed 54 | command: complete 55 | - to: hold 56 | command: hold 57 | hold: 58 | - to: active 59 | command: resume 60 | timestamps: 61 | - field: updated 62 | value: "${local_time}" 63 | - field: state_changed 64 | value: "${local_time}" 65 | 66 | # Template Validation 67 | template_validation: 68 | task: 69 | required_fields: 70 | - title: string 71 | - type: task 72 | - status: [planned|active|hold|completed] 73 | - created: date 74 | - updated: date 75 | - id: TASK-[000] 76 | - priority: [high|medium|low] 77 | - memory_types: list 78 | 79 | optional_fields: 80 | - dependencies: list 81 | - tags: list 82 | - estimated_time: string 83 | - assignee: string 84 | 85 | field_validation: 86 | title: 87 | - required: true 88 | - type: string 89 | - min_length: 3 90 | type: 91 | - required: true 92 | - value: task 93 | status: 94 | - required: true 95 | - enum: [planned, active, hold, completed] 96 | created: 97 | - required: true 98 | - format: YYYY-MM-DDTHH:MM:SS 99 | updated: 100 | - required: true 101 | - format: YYYY-MM-DDTHH:MM:SS 102 | id: 103 | - required: true 104 | - pattern: "TASK-\\d{3}" 105 | priority: 106 | - required: true 107 | - enum: [high, medium, low] 108 | dependencies: 109 | - required: false 110 | - type: list 111 | tags: 112 | - required: false 113 | - type: list 114 | estimated_time: 115 | - required: false 116 | - type: string 117 | - pattern: "\\d+\\s+(hours|days)" 118 | assignee: 119 | - required: false 120 | - type: string 121 | memory_types: 122 | - required: true 123 | - type: list 124 | - min_items: 1 125 | - description: "Types of memory this task affects" 126 | - valid_values: 127 | - procedural 128 | - semantic 129 | - episodic 130 | 131 | required_sections: 132 | - Description 133 | - Objectives 134 | - Steps 135 | - Progress 136 | - Dependencies 137 | - Notes 138 | - Next Steps 139 | format: 140 | - markdown_valid 141 | - front_matter_valid 142 | - sections_complete 143 | 144 | session: 145 | required_fields: 146 | - type: session 147 | - status: [active|completed] 148 | - started: date 149 | - id: SESSION-[000] 150 | - memory_types: list 151 | 152 | optional_fields: 153 | - ended: date 154 | - tags: list 155 | 156 | field_validation: 157 | type: 158 | - required: true 159 | - value: session 160 | status: 161 | - required: true 162 | - enum: [active, completed] 163 | started: 164 | - required: true 165 | - format: YYYY-MM-DDTHH:MM:SS 166 | id: 167 | - required: true 168 | - pattern: "SESSION-\\d{3}" 169 | memory_types: 170 | - required: true 171 | - type: list 172 | - min_items: 1 173 | - valid_values: 174 | - procedural 175 | - semantic 176 | - episodic 177 | ended: 178 | - required: false 179 | - format: YYYY-MM-DDTHH:MM:SS 180 | tags: 181 | - required: false 182 | - type: list 183 | 184 | required_sections: 185 | - Focus 186 | - Context 187 | - Progress 188 | - Decisions 189 | - Self-Improvement 190 | - Dependencies 191 | - Next Steps 192 | - Notes 193 | format: 194 | - markdown_valid 195 | - front_matter_valid 196 | - sections_complete 197 | 198 | # Task Creation Validation 199 | task_creation: 200 | template: 201 | source: .context/templates/tasks/TEMPLATE.md 202 | validation: 203 | - exists: "Template file must exist" 204 | - readable: "Template must be readable" 205 | - format_valid: "Template must be valid markdown" 206 | 207 | content: 208 | front_matter: 209 | - required: "All required fields must be present" 210 | - format: "Fields must match expected format" 211 | - values: "Values must be from allowed set" 212 | sections: 213 | - required: "All template sections must be present" 214 | - order: "Sections must maintain template order" 215 | - format: "Section formatting must match template" 216 | 217 | location: 218 | new_tasks: 219 | - directory: "tasks/planned" 220 | - unique: "No duplicate task IDs" 221 | - writable: "Directory must be writable" 222 | 223 | # Session Creation Validation 224 | session_creation: 225 | template: 226 | source: .context/templates/sessions/TEMPLATE.md 227 | validation: 228 | - exists: "Template file must exist" 229 | - readable: "Template must be readable" 230 | - format_valid: "Template must be valid markdown" 231 | 232 | content: 233 | front_matter: 234 | - required: "All required fields must be present" 235 | - format: "Fields must match expected format" 236 | - values: "Values must be from allowed set" 237 | sections: 238 | - required: "All template sections must be present" 239 | - order: "Sections must maintain template order" 240 | - format: "Section formatting must match template" 241 | 242 | location: 243 | new_sessions: 244 | - directory: "sessions" 245 | - unique: "No duplicate session IDs" 246 | - writable: "Directory must be writable" 247 | 248 | # Time and Date Rules 249 | timestamps: 250 | format: "%Y-%m-%dT%H:%M:%S%z" # ISO-8601 format 251 | variables: 252 | current_time: "${local_time}" # Use local machine time 253 | created_time: "${local_time}" 254 | updated_time: "${local_time}" 255 | validation: 256 | - pattern: "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}" 257 | - timezone: required 258 | - source: local_machine 259 | 260 | # Task Validation Rules 261 | task_validation: 262 | timestamps: 263 | created: 264 | format: "${local_time}" 265 | immutable: true 266 | updated: 267 | format: "${local_time}" 268 | update_on: 269 | - content_change 270 | - state_change 271 | - metadata_change 272 | 273 | # Self-Improvement Validation 274 | self_improvement_validation: 275 | data_structure: 276 | self_improvement_json: 277 | required_fields: 278 | - metadata 279 | - insights 280 | - metrics 281 | - recommendations 282 | metadata: 283 | required: 284 | - version 285 | - last_updated 286 | format: 287 | version: string 288 | last_updated: YYYY-MM-DDTHH:MM:SS 289 | insights: 290 | required_categories: 291 | - process 292 | - efficiency 293 | - patterns 294 | - blockers 295 | format: array 296 | metrics: 297 | required_categories: 298 | - time_allocation 299 | - task_completion 300 | time_allocation: 301 | required: 302 | - categories 303 | - history 304 | categories: 305 | required: 306 | - implementation 307 | - planning 308 | - documentation 309 | - debugging 310 | - other 311 | format: numeric 312 | task_completion: 313 | required: 314 | - average_completion_time 315 | format: numeric 316 | recommendations: 317 | required_categories: 318 | - process_improvements 319 | - efficiency_improvements 320 | - risk_mitigations 321 | format: 322 | text: string 323 | priority: [high|medium|low] 324 | category: [process|efficiency|risk] 325 | created: YYYY-MM-DDTHH:MM:SS 326 | applied: boolean 327 | result: string 328 | 329 | session_validation: 330 | self_improvement_section: 331 | required: true 332 | subsections: 333 | - Insights 334 | - Metrics 335 | - Recommendations 336 | insights: 337 | min_count: 1 338 | max_count: 5 339 | format: "Bullet points" 340 | metrics: 341 | required_metrics: 342 | - "Task completion rate" 343 | - "Time allocation" 344 | optional_metrics: 345 | - "Decision efficiency" 346 | - "Pattern frequency" 347 | format: "Bullet points with numeric values" 348 | recommendations: 349 | min_count: 1 350 | max_count: 3 351 | format: "Prioritized bullet points ([Priority level] Recommendation text)" 352 | 353 | analysis_validation: 354 | data_requirements: 355 | minimum_sessions: 1 356 | minimum_tasks: 1 357 | minimum_decisions: 0 358 | insight_generation: 359 | minimum_insights: 1 360 | maximum_insights: 10 361 | required_categories: 362 | - process 363 | - efficiency 364 | optional_categories: 365 | - patterns 366 | - blockers 367 | recommendation_generation: 368 | minimum_recommendations: 1 369 | maximum_recommendations: 5 370 | priority_distribution: 371 | high: "maximum 1" 372 | medium: "maximum 2" 373 | low: "maximum 2" 374 | 375 | integration_validation: 376 | save_operation: 377 | required_steps: 378 | - analyze_session 379 | - update_session_with_insights 380 | output_validation: 381 | self_improvement_json: "updated" 382 | session_document: "contains Self-Improvement section" 383 | start_operation: 384 | required_steps: 385 | - load_recommendations 386 | - apply_to_session 387 | output_validation: 388 | session_document: "contains applied recommendations" 389 | 390 | # Error Messages 391 | error_messages: 392 | file: 393 | not_found: "File {path} does not exist" 394 | no_permission: "No permission to access {path}" 395 | invalid_target: "Invalid target directory {path}" 396 | 397 | template: 398 | missing: "Template {path} does not exist" 399 | invalid: "Template {path} is not valid" 400 | format_error: "Template format error in {path}: {error}" 401 | 402 | task: 403 | duplicate: "Task with ID {id} already exists" 404 | invalid_state: "Invalid task state: {state}" 405 | missing_field: "Required field missing in task: {field}" 406 | invalid_field: "Invalid field value in task: {field}" 407 | 408 | session: 409 | invalid_state: "Invalid session state: {state}" 410 | missing_field: "Required field missing in session: {field}" 411 | invalid_field: "Invalid field value in session: {field}" 412 | missing_section: "Required section missing in session: {section}" 413 | 414 | self_improvement: 415 | data_invalid: "Self-improvement data structure invalid: {error}" 416 | missing_field: "Required field missing in self-improvement data: {field}" 417 | invalid_insight: "Invalid insight format: {error}" 418 | missing_section: "Required Self-Improvement section missing in session" 419 | validation_failed: "Self-improvement validation failed: {error}" 420 | 421 | # Validation Commands 422 | validation_commands: 423 | task: 424 | validate_task: "Validate task structure and content" 425 | validate_state: "Validate task state transition" 426 | validate_fields: "Validate task fields" 427 | 428 | session: 429 | validate_session: "Validate session structure and content" 430 | validate_state: "Validate session state" 431 | validate_fields: "Validate session fields" 432 | 433 | self_improvement: 434 | validate_data: "Validate self-improvement data structure" 435 | validate_session_integration: "Validate self-improvement session integration" 436 | validate_analysis: "Validate self-improvement analysis results" 437 | 438 | # State Validation Rules 439 | state_validation: 440 | project_context: 441 | - file_exists: "memory/project/context/project.json exists" 442 | - format_valid: "JSON format is valid" 443 | - required_fields: 444 | - type 445 | - category 446 | - id 447 | - created 448 | - updated 449 | - content 450 | - content_fields: 451 | - name 452 | - version 453 | - description 454 | - status 455 | - phase 456 | - activeTasks 457 | - completedTasks 458 | - decisions 459 | - components 460 | - consistency: 461 | - activeTasks: "Match files in tasks/active/" 462 | - completedTasks: "Match files in tasks/completed/" 463 | - timestamp: "Updated timestamp is current" 464 | 465 | self_improvement: 466 | - file_exists: "memory/project/self_improvement.json exists" 467 | - format_valid: "JSON format is valid" 468 | - required_fields: 469 | - type 470 | - category 471 | - id 472 | - created 473 | - updated 474 | - content 475 | - content_fields: 476 | - metrics 477 | - patterns 478 | - recommendations 479 | - insights 480 | - consistency: 481 | - timestamp: "Updated timestamp is current" 482 | 483 | session_memory: 484 | - file_exists: "memory/session/active.json exists" 485 | - format_valid: "JSON format is valid" 486 | - required_fields: 487 | - type 488 | - category 489 | - id 490 | - created 491 | - updated 492 | - content 493 | - content_fields: 494 | - sessionId 495 | - status 496 | - started 497 | - activeTask 498 | - progress 499 | - context 500 | - decisions 501 | - insights 502 | - consistency: 503 | - sessionId: "Match most recent session file" 504 | - status: "Match most recent session file" 505 | - timestamp: "Updated timestamp is current" 506 | - activeTask: "Match current active task in project.json" 507 | - decisions: "Match decisions made in current session" 508 | - history: 509 | - directory_exists: "memory/session/history/ exists" 510 | - format: "YYYY-MM-DD-sessionId.json" 511 | - consistency: "History files match session files in sessions/" 512 | 513 | # Reconciliation Rules 514 | reconcile: 515 | - framework_ready: "Framework structure is valid" 516 | - state_files_exist: "All state files exist" 517 | - state_format_valid: "State file formats are valid" 518 | - task_consistency: "Task lists match directory contents" 519 | - decision_consistency: "Decision list matches directory contents" 520 | - session_consistency: "Session memory matches session files" 521 | - timestamp_valid: "Timestamps are in correct format and current" 522 | - session_memory_reconciliation: "Session memory is reconciled with session files" 523 | 524 | # Session Memory Reconciliation Steps 525 | session_memory_reconciliation: 526 | active_session: 527 | - find_latest_session: "Find the most recent session file in sessions/" 528 | - extract_metadata: "Extract session metadata (id, status, started, etc.)" 529 | - extract_content: "Extract session content (focus, progress, decisions, etc.)" 530 | - update_active_json: "Update memory/session/active.json with extracted data" 531 | - validate_update: "Validate that active.json is consistent with session file" 532 | 533 | session_history: 534 | - find_all_sessions: "Find all session files in sessions/" 535 | - create_history_dir: "Ensure memory/session/history/ exists" 536 | - for_each_session: 537 | - extract_metadata: "Extract session metadata" 538 | - extract_content: "Extract session content" 539 | - create_history_file: "Create history file in memory/session/history/" 540 | - validate_history_file: "Validate history file format and content" 541 | - validate_history: "Validate that history directory contains all sessions" 542 | 543 | # Command Validation Patterns 544 | command_validation: 545 | save: 546 | pre_execution: 547 | - identify_decisions_to_record: "Identify any significant decisions made during the session" 548 | - identify_self_improvement_updates: "Identify insights and metrics for self-improvement" 549 | - check_task_progress: "Check for task progress updates" 550 | execution: 551 | - update_session_document: "Update the session document with progress, decisions, and insights" 552 | - create_decision_records: "Create decision records for significant decisions" 553 | - update_self_improvement_record: "Update self-improvement record with new insights" 554 | - update_task_progress: "Update task progress and status" 555 | post_execution: 556 | - verify_session_document_updated: "Verify session document has been updated" 557 | - verify_decision_records_created: "Verify decision records have been created" 558 | - verify_self_improvement_updated: "Verify self-improvement record has been updated" 559 | - verify_task_progress_updated: "Verify task progress has been updated" 560 | completion: 561 | - only_if_all_steps_verified: true 562 | 563 | start: 564 | pre_execution: 565 | - check_active_session: "Check if there's already an active session" 566 | - identify_focus: "Identify the focus for the new session" 567 | - load_context: "Load relevant context for the session" 568 | execution: 569 | - create_session_document: "Create a new session document" 570 | - set_initial_focus: "Set the initial focus for the session" 571 | - load_recommendations: "Load recommendations from self-improvement" 572 | - update_session_memory: "Update session memory with new session" 573 | post_execution: 574 | - verify_session_document_created: "Verify session document has been created" 575 | - verify_session_memory_updated: "Verify session memory has been updated" 576 | completion: 577 | - only_if_all_steps_verified: true 578 | 579 | task: 580 | pre_execution: 581 | - identify_task_operation: "Identify the task operation (create, update, transition)" 582 | - load_task_context: "Load relevant task context" 583 | - validate_task_state: "Validate the current task state" 584 | execution: 585 | - perform_task_operation: "Perform the requested task operation" 586 | - update_task_document: "Update the task document" 587 | - update_project_context: "Update project context with task changes" 588 | post_execution: 589 | - verify_task_document_updated: "Verify task document has been updated" 590 | - verify_project_context_updated: "Verify project context has been updated" 591 | completion: 592 | - only_if_all_steps_verified: true 593 | 594 | status: 595 | pre_execution: 596 | - load_project_context: "Load project context" 597 | - load_active_tasks: "Load active tasks" 598 | - load_recent_changes: "Load recent changes" 599 | execution: 600 | - generate_status_report: "Generate status report" 601 | - include_active_tasks: "Include active tasks in report" 602 | - include_recent_changes: "Include recent changes in report" 603 | - include_self_improvement_insights: "Include self-improvement insights in report" 604 | post_execution: 605 | - verify_report_complete: "Verify report is complete" 606 | completion: 607 | - only_if_all_steps_verified: true 608 | 609 | context: 610 | pre_execution: 611 | - load_project_context: "Load project context" 612 | - load_active_tasks: "Load active tasks" 613 | - load_recent_decisions: "Load recent decisions" 614 | execution: 615 | - generate_context_report: "Generate context report" 616 | - include_active_tasks: "Include active tasks in report" 617 | - include_recent_decisions: "Include recent decisions in report" 618 | - include_relevant_insights: "Include relevant insights in report" 619 | post_execution: 620 | - verify_report_complete: "Verify report is complete" 621 | completion: 622 | - only_if_all_steps_verified: true 623 | 624 | reconcile: 625 | pre_execution: 626 | - check_framework_structure: "Check framework structure" 627 | - load_project_context: "Load project context" 628 | - load_session_memory: "Load session memory" 629 | execution: 630 | - check_task_consistency: "Check task consistency" 631 | - check_decision_consistency: "Check decision consistency" 632 | - check_session_consistency: "Check session consistency" 633 | - update_project_context: "Update project context" 634 | - update_session_memory: "Update session memory" 635 | - update_session_history: "Update session history" 636 | post_execution: 637 | - verify_project_context_updated: "Verify project context has been updated" 638 | - verify_session_memory_updated: "Verify session memory has been updated" 639 | - verify_session_history_updated: "Verify session history has been updated" 640 | completion: 641 | - only_if_all_steps_verified: true 642 | -------------------------------------------------------------------------------- /.context/memory/OPERATIONS.md: -------------------------------------------------------------------------------- 1 | # Memory Operations 2 | 3 | ## Overview 4 | Memory operations define how the framework interacts with memories, ensuring consistent state management and data integrity. 5 | 6 | ## Core Operations 7 | 8 | ### Read Operations 9 | 1. Load Memory 10 | ```yaml 11 | operation: load 12 | type: memory 13 | category: 14 | id: memory-id 15 | ``` 16 | - Validate permissions 17 | - Check existence 18 | - Load content 19 | - Verify schema 20 | 21 | 2. Query Memory 22 | ```yaml 23 | operation: query 24 | type: memory 25 | pattern: query-pattern 26 | filters: 27 | category: optional-category 28 | state: optional-state 29 | ``` 30 | - Match pattern 31 | - Apply filters 32 | - Return results 33 | - Sort by relevance 34 | 35 | 3. List Memories 36 | ```yaml 37 | operation: list 38 | type: memory 39 | category: optional-category 40 | recursive: boolean 41 | ``` 42 | - Get category 43 | - List contents 44 | - Filter results 45 | - Sort output 46 | 47 | ### Write Operations 48 | 1. Create Memory 49 | ```yaml 50 | operation: create 51 | type: memory 52 | category: required-category 53 | content: memory-content 54 | ``` 55 | - Validate schema 56 | - Check permissions 57 | - Create file 58 | - Set initial state 59 | 60 | 2. Update Memory 61 | ```yaml 62 | operation: update 63 | type: memory 64 | id: memory-id 65 | changes: content-changes 66 | ``` 67 | - Load current 68 | - Validate changes 69 | - Update content 70 | - Save state 71 | 72 | 3. Delete Memory 73 | ```yaml 74 | operation: delete 75 | type: memory 76 | id: memory-id 77 | force: boolean 78 | ``` 79 | - Check references 80 | - Validate deletion 81 | - Remove content 82 | - Update state 83 | 84 | ### State Operations 85 | 1. Change State 86 | ```yaml 87 | operation: state 88 | type: memory 89 | id: memory-id 90 | new_state: target-state 91 | reason: change-reason 92 | ``` 93 | - Verify transition 94 | - Update state 95 | - Record reason 96 | - Save changes 97 | 98 | 2. Track Changes 99 | ```yaml 100 | operation: track 101 | type: memory 102 | id: memory-id 103 | changes: change-list 104 | ``` 105 | - Record changes 106 | - Update history 107 | - Save metadata 108 | - Notify system 109 | 110 | 3. Validate State 111 | ```yaml 112 | operation: validate 113 | type: memory 114 | id: memory-id 115 | rules: validation-rules 116 | ``` 117 | - Check state 118 | - Verify rules 119 | - Report issues 120 | - Suggest fixes 121 | 122 | ## Operation Rules 123 | 124 | ### Access Control 125 | 1. Read Rules 126 | - Check permissions 127 | - Verify access 128 | - Load content 129 | - Return data 130 | 131 | 2. Write Rules 132 | - Validate changes 133 | - Check conflicts 134 | - Update content 135 | - Save state 136 | 137 | 3. Delete Rules 138 | - Check references 139 | - Verify permissions 140 | - Remove content 141 | - Update state 142 | 143 | ### Validation Rules 144 | 1. Schema Validation 145 | - Check format 146 | - Verify fields 147 | - Validate types 148 | - Check required 149 | 150 | 2. State Validation 151 | - Verify current 152 | - Check transition 153 | - Validate rules 154 | - Update state 155 | 156 | 3. Reference Validation 157 | - Check links 158 | - Verify targets 159 | - Update references 160 | - Maintain integrity 161 | 162 | ### Error Handling 163 | 1. Operation Errors 164 | - Log error 165 | - Report issue 166 | - Suggest fix 167 | - Roll back 168 | 169 | 2. Validation Errors 170 | - Show problem 171 | - Explain issue 172 | - Provide example 173 | - Guide fix 174 | 175 | 3. State Errors 176 | - Show current 177 | - Explain conflict 178 | - Suggest solution 179 | - Guide recovery 180 | 181 | ## Usage Patterns 182 | 183 | ### Basic Operations 184 | 1. Read Pattern 185 | ```javascript 186 | // Load memory 187 | memory = load(id) 188 | // Check content 189 | if (valid(memory)) { 190 | // Use content 191 | process(memory.content) 192 | } 193 | ``` 194 | 195 | 2. Write Pattern 196 | ```javascript 197 | // Create changes 198 | changes = prepare_changes() 199 | // Update memory 200 | if (valid(changes)) { 201 | update(memory, changes) 202 | save(memory) 203 | } 204 | ``` 205 | 206 | 3. State Pattern 207 | ```javascript 208 | // Change state 209 | if (can_transition(current, new)) { 210 | change_state(memory, new) 211 | track_change(memory) 212 | } 213 | ``` 214 | 215 | ### Complex Operations 216 | 1. Batch Operations 217 | ```javascript 218 | // Process multiple 219 | memories = list(category) 220 | for (memory in memories) { 221 | if (should_process(memory)) { 222 | process(memory) 223 | } 224 | } 225 | ``` 226 | 227 | 2. Reference Updates 228 | ```javascript 229 | // Update references 230 | refs = find_references(memory) 231 | for (ref in refs) { 232 | if (needs_update(ref)) { 233 | update_reference(ref) 234 | } 235 | } 236 | ``` 237 | 238 | 3. State Sync 239 | ```javascript 240 | // Synchronize states 241 | states = get_states(category) 242 | for (state in states) { 243 | if (out_of_sync(state)) { 244 | sync_state(state) 245 | } 246 | } 247 | ``` 248 | 249 | ## Implementation Notes 250 | 1. Always validate before write 251 | 2. Keep operations atomic 252 | 3. Maintain consistency 253 | 4. Handle errors gracefully 254 | 5. Track all changes 255 | 6. Update references 256 | 7. Preserve history 257 | 8. Follow patterns 258 | -------------------------------------------------------------------------------- /.context/memory/README.md: -------------------------------------------------------------------------------- 1 | # Memory System 2 | 3 | ## Overview 4 | The memory system manages framework state, configuration, and context across different scopes and lifetimes. 5 | 6 | ## Directory Structure 7 | ``` 8 | memory/ 9 | ├── README.md # This file 10 | ├── STRUCTURE.md # Memory system architecture 11 | ├── OPERATIONS.md # Memory operations guide 12 | ├── REFERENCES.md # Reference system spec 13 | ├── RECOVERY.md # Recovery procedures 14 | ├── core/ # Framework memories 15 | │ ├── state.json # Framework state 16 | │ ├── config.json # Framework config 17 | │ └── rules.json # Framework rules 18 | ├── project/ # Project memories 19 | │ └── context/ # Project context 20 | └── session/ # Session memories 21 | └── active.json # Current session 22 | ``` 23 | 24 | ## Implementation Files 25 | 26 | ### STRUCTURE.md 27 | Defines the memory system architecture including: 28 | - Directory organization 29 | - File formats 30 | - Memory categories 31 | - Storage patterns 32 | - Access rules 33 | 34 | ### OPERATIONS.md 35 | Documents memory operations: 36 | - Read operations 37 | - Write operations 38 | - State operations 39 | - Operation rules 40 | - Error handling 41 | - Usage patterns 42 | 43 | ### REFERENCES.md 44 | Specifies the reference system: 45 | - Reference types 46 | - Validation rules 47 | - Usage patterns 48 | - Error handling 49 | - Recovery procedures 50 | 51 | ### RECOVERY.md 52 | Details recovery procedures: 53 | - Recovery types 54 | - Automatic recovery 55 | - Manual procedures 56 | - Prevention measures 57 | - Recovery tools 58 | - Implementation notes 59 | 60 | ## Memory Categories 61 | 62 | ### Core Memories 63 | Location: `core/` 64 | Purpose: Framework configuration and state 65 | Files: 66 | - `state.json`: Current framework state 67 | - `config.json`: Framework configuration 68 | - `rules.json`: Framework rules and patterns 69 | 70 | ### Project Memories 71 | Location: `project/` 72 | Purpose: Project-specific information 73 | Files: 74 | - `context/project.json`: Project context and state 75 | 76 | ### Session Memories 77 | Location: `session/` 78 | Purpose: Active session tracking 79 | Files: 80 | - `active.json`: Current session state 81 | 82 | ### User Memories 83 | Location: `user/` 84 | Purpose: User preferences and settings 85 | Files: 86 | - `settings.json`: User configuration 87 | 88 | ## Usage 89 | 90 | ### Reading Memory 91 | 1. Check README.md for structure 92 | 2. Reference OPERATIONS.md for patterns 93 | 3. Follow REFERENCES.md for linking 94 | 4. Use RECOVERY.md if needed 95 | 96 | ### Writing Memory 97 | 1. Follow STRUCTURE.md patterns 98 | 2. Use OPERATIONS.md guidelines 99 | 3. Validate with REFERENCES.md 100 | 4. Ensure RECOVERY.md compliance 101 | 102 | ### Recovery 103 | 1. Check RECOVERY.md procedures 104 | 2. Follow documented steps 105 | 3. Use provided tools 106 | 4. Verify system state 107 | 108 | ## Implementation Notes 109 | 1. Keep memories organized by category 110 | 2. Follow defined patterns 111 | 3. Maintain proper references 112 | 4. Handle errors gracefully 113 | 5. Document all changes 114 | 6. Test recovery procedures 115 | -------------------------------------------------------------------------------- /.context/memory/RECOVERY.md: -------------------------------------------------------------------------------- 1 | # Memory Recovery Procedures 2 | 3 | ## Overview 4 | Recovery procedures ensure the memory system can handle errors, inconsistencies, and failures while maintaining data integrity. 5 | 6 | ## Recovery Types 7 | 8 | ### State Recovery 9 | 1. State Mismatch 10 | ```yaml 11 | issue: state_mismatch 12 | recovery: 13 | - load_last_valid_state 14 | - check_transition_log 15 | - resolve_conflicts 16 | - update_state 17 | ``` 18 | 19 | 2. Corrupted State 20 | ```yaml 21 | issue: corrupt_state 22 | recovery: 23 | - load_backup 24 | - validate_schema 25 | - repair_state 26 | - verify_integrity 27 | ``` 28 | 29 | 3. Invalid Transition 30 | ```yaml 31 | issue: invalid_transition 32 | recovery: 33 | - revert_to_previous 34 | - log_failure 35 | - notify_system 36 | - suggest_valid_paths 37 | ``` 38 | 39 | ### Reference Recovery 40 | 1. Missing Reference 41 | ```yaml 42 | issue: missing_reference 43 | recovery: 44 | - check_alternate_locations 45 | - search_backups 46 | - create_placeholder 47 | - mark_for_review 48 | ``` 49 | 50 | 2. Invalid Reference 51 | ```yaml 52 | issue: invalid_reference 53 | recovery: 54 | - validate_format 55 | - check_alternatives 56 | - update_reference 57 | - log_changes 58 | ``` 59 | 60 | 3. Circular Reference 61 | ```yaml 62 | issue: circular_reference 63 | recovery: 64 | - detect_cycle 65 | - break_loop 66 | - rebuild_chain 67 | - verify_links 68 | ``` 69 | 70 | ### Content Recovery 71 | 1. Corrupted Content 72 | ```yaml 73 | issue: corrupt_content 74 | recovery: 75 | - load_backup 76 | - validate_content 77 | - repair_structure 78 | - verify_data 79 | ``` 80 | 81 | 2. Schema Violation 82 | ```yaml 83 | issue: schema_violation 84 | recovery: 85 | - identify_violations 86 | - apply_fixes 87 | - validate_changes 88 | - update_schema 89 | ``` 90 | 91 | 3. Version Mismatch 92 | ```yaml 93 | issue: version_mismatch 94 | recovery: 95 | - check_compatibility 96 | - migrate_data 97 | - update_version 98 | - verify_format 99 | ``` 100 | 101 | ## Recovery Procedures 102 | 103 | ### Automatic Recovery 104 | 1. Detection 105 | ```javascript 106 | // Monitor system 107 | monitor_health() 108 | // Detect issues 109 | if (issue_detected()) { 110 | identify_problem() 111 | select_recovery() 112 | } 113 | ``` 114 | 115 | 2. Analysis 116 | ```javascript 117 | // Analyze issue 118 | analyze_problem() 119 | // Choose strategy 120 | strategy = select_strategy() 121 | // Prepare recovery 122 | prepare_recovery(strategy) 123 | ``` 124 | 125 | 3. Recovery 126 | ```javascript 127 | // Execute recovery 128 | try_recovery() 129 | // Verify success 130 | verify_recovery() 131 | // Update system 132 | update_state() 133 | ``` 134 | 135 | ### Manual Recovery 136 | 1. Backup Access 137 | ```yaml 138 | procedure: access_backup 139 | steps: 140 | - locate_backup 141 | - verify_integrity 142 | - load_content 143 | - check_state 144 | ``` 145 | 146 | 2. State Repair 147 | ```yaml 148 | procedure: repair_state 149 | steps: 150 | - check_current 151 | - load_valid 152 | - fix_issues 153 | - verify_fix 154 | ``` 155 | 156 | 3. Content Rebuild 157 | ```yaml 158 | procedure: rebuild_content 159 | steps: 160 | - gather_fragments 161 | - validate_parts 162 | - reconstruct_data 163 | - verify_result 164 | ``` 165 | 166 | ## Prevention Measures 167 | 168 | ### Backup System 169 | 1. Regular Backups 170 | ```yaml 171 | backup: 172 | frequency: hourly 173 | retention: 7_days 174 | format: compressed 175 | verify: true 176 | ``` 177 | 178 | 2. Incremental Saves 179 | ```yaml 180 | saves: 181 | frequency: on_change 182 | retention: 24_hours 183 | format: diff 184 | compress: true 185 | ``` 186 | 187 | 3. State Snapshots 188 | ```yaml 189 | snapshots: 190 | frequency: on_transition 191 | retention: 10_states 192 | format: full 193 | verify: true 194 | ``` 195 | 196 | ### Validation Checks 197 | 1. Pre-operation 198 | ```yaml 199 | checks: 200 | - schema_valid 201 | - state_consistent 202 | - refs_exist 203 | - perms_correct 204 | ``` 205 | 206 | 2. Post-operation 207 | ```yaml 208 | verify: 209 | - changes_applied 210 | - state_updated 211 | - refs_valid 212 | - data_consistent 213 | ``` 214 | 215 | 3. Periodic 216 | ```yaml 217 | periodic: 218 | - integrity_check 219 | - orphan_cleanup 220 | - ref_validation 221 | - state_verify 222 | ``` 223 | 224 | ## Recovery Tools 225 | 226 | ### Diagnostic Tools 227 | 1. State Check 228 | ```yaml 229 | tool: state_check 230 | checks: 231 | - current_state 232 | - transitions 233 | - references 234 | - integrity 235 | ``` 236 | 237 | 2. Reference Scan 238 | ```yaml 239 | tool: ref_scan 240 | checks: 241 | - missing_refs 242 | - invalid_refs 243 | - circular_refs 244 | - orphaned_refs 245 | ``` 246 | 247 | 3. Content Verify 248 | ```yaml 249 | tool: content_verify 250 | checks: 251 | - schema_valid 252 | - data_integrity 253 | - format_correct 254 | - values_valid 255 | ``` 256 | 257 | ### Repair Tools 258 | 1. State Repair 259 | ```yaml 260 | tool: state_repair 261 | actions: 262 | - fix_state 263 | - update_refs 264 | - verify_changes 265 | - log_repairs 266 | ``` 267 | 268 | 2. Reference Fix 269 | ```yaml 270 | tool: ref_fix 271 | actions: 272 | - update_refs 273 | - remove_invalid 274 | - add_missing 275 | - verify_links 276 | ``` 277 | 278 | 3. Content Repair 279 | ```yaml 280 | tool: content_repair 281 | actions: 282 | - fix_schema 283 | - repair_data 284 | - validate_fix 285 | - log_changes 286 | ``` 287 | 288 | ## Implementation Notes 289 | 1. Always backup before recovery 290 | 2. Log all recovery actions 291 | 3. Verify after each step 292 | 4. Keep recovery atomic 293 | 5. Maintain audit trail 294 | 6. Test recovery regularly 295 | 7. Document procedures 296 | 8. Train users properly 297 | -------------------------------------------------------------------------------- /.context/memory/REFERENCES.md: -------------------------------------------------------------------------------- 1 | # Memory Reference System 2 | 3 | ## Overview 4 | The reference system ensures proper linking between memories and documents, maintaining consistency and traceability across the framework. 5 | 6 | ## Reference Types 7 | 8 | ### Document References 9 | 1. Task References 10 | - Format: `TASK-[0-9]{3}` 11 | - Examples: TASK-001, TASK-002 12 | - Usage: Dependencies, related work 13 | 14 | 2. Session References 15 | - Format: `SESSION-[0-9]{3}` 16 | - Examples: SESSION-001, SESSION-002 17 | - Usage: Work tracking, context 18 | 19 | 3. Decision References 20 | - Format: `DECISION-[0-9]{3}` 21 | - Examples: DECISION-001, DECISION-002 22 | - Usage: Implementation choices 23 | 24 | ### Memory References 25 | 1. Core References 26 | - Format: `core::` 27 | - Examples: core:state:framework-state 28 | - Usage: Framework configuration 29 | 30 | 2. Project References 31 | - Format: `project::` 32 | - Examples: project:context:project-context 33 | - Usage: Project information 34 | 35 | 3. Session References 36 | - Format: `session::` 37 | - Examples: session:active:current-session 38 | - Usage: Session state 39 | 40 | 4. User References 41 | - Format: `user::` 42 | - Examples: user:settings:user-preferences 43 | - Usage: User configuration 44 | 45 | ## Reference Rules 46 | 47 | ### Validation Rules 48 | 1. Format Validation 49 | ```yaml 50 | task: ^TASK-\d{3}$ 51 | session: ^SESSION-\d{3}$ 52 | decision: ^DECISION-\d{3}$ 53 | memory: ^(core|project|session|user):[a-z-]+:[a-z-]+$ 54 | ``` 55 | 56 | 2. Existence Check 57 | - Document must exist 58 | - Memory must be valid 59 | - Path must be accessible 60 | 61 | 3. State Validation 62 | - Referenced item active 63 | - State transition valid 64 | - Permissions correct 65 | 66 | ### Reference Types 67 | 1. Strong References 68 | - Direct dependencies 69 | - Required links 70 | - State dependencies 71 | 72 | 2. Weak References 73 | - Related items 74 | - Optional links 75 | - Information only 76 | 77 | 3. Temporal References 78 | - Time-based links 79 | - Historical records 80 | - Version tracking 81 | 82 | ## Usage Patterns 83 | 84 | ### Document References 85 | 1. Front Matter 86 | ```yaml 87 | --- 88 | id: TASK-001 89 | dependencies: 90 | - TASK-002: Waiting on this task 91 | related: 92 | - SESSION-001 93 | - DECISION-001 94 | --- 95 | ``` 96 | 97 | 2. Content Links 98 | ```markdown 99 | See [TASK-001] for implementation details. 100 | Decided in [DECISION-001]. 101 | During [SESSION-001]. 102 | ``` 103 | 104 | 3. State Links 105 | ```yaml 106 | status: active 107 | dependencies: [TASK-002] 108 | implements: DECISION-001 109 | ``` 110 | 111 | ### Memory References 112 | 1. Direct References 113 | ```json 114 | { 115 | "type": "memory", 116 | "references": { 117 | "config": "core:config:framework-config", 118 | "state": "core:state:framework-state" 119 | } 120 | } 121 | ``` 122 | 123 | 2. Linked References 124 | ```json 125 | { 126 | "type": "memory", 127 | "links": [ 128 | { 129 | "type": "task", 130 | "id": "TASK-001", 131 | "relation": "implements" 132 | } 133 | ] 134 | } 135 | ``` 136 | 137 | 3. State References 138 | ```json 139 | { 140 | "type": "memory", 141 | "state": { 142 | "current": "active", 143 | "depends_on": "core:state:framework-state" 144 | } 145 | } 146 | ``` 147 | 148 | ## Validation Process 149 | 150 | ### Reference Check 151 | 1. Format Check 152 | - Match pattern 153 | - Validate syntax 154 | - Check format 155 | 156 | 2. Existence Check 157 | - Find target 158 | - Verify access 159 | - Check permissions 160 | 161 | 3. State Check 162 | - Validate state 163 | - Check transitions 164 | - Verify rules 165 | 166 | ### Error Handling 167 | 1. Missing References 168 | - Log error 169 | - Mark invalid 170 | - Suggest fixes 171 | 172 | 2. Invalid Format 173 | - Show pattern 174 | - Highlight error 175 | - Provide example 176 | 177 | 3. State Conflicts 178 | - Show current state 179 | - Explain conflict 180 | - Suggest resolution 181 | 182 | ## Recovery Procedures 183 | 184 | ### Reference Repair 185 | 1. Missing Target 186 | - Create if allowed 187 | - Remove reference 188 | - Update links 189 | 190 | 2. Invalid Format 191 | - Fix format 192 | - Update reference 193 | - Validate change 194 | 195 | 3. State Mismatch 196 | - Update state 197 | - Fix transition 198 | - Verify consistency 199 | 200 | ### Cleanup Process 201 | 1. Detect Orphans 202 | - Find unused 203 | - Check validity 204 | - Mark for cleanup 205 | 206 | 2. Fix References 207 | - Update links 208 | - Remove invalid 209 | - Add missing 210 | 211 | 3. Validate Changes 212 | - Check integrity 213 | - Verify states 214 | - Confirm fixes 215 | -------------------------------------------------------------------------------- /.context/memory/SELF_IMPROVEMENT.md: -------------------------------------------------------------------------------- 1 | # Self-Improvement Analysis 2 | 3 | ## Overview 4 | The self-improvement analysis is a core component of the Aegis framework that enables continuous improvement through systematic analysis of project patterns, task execution, and decision-making processes. This feature is integrated into the existing framework operations and memory structure. 5 | 6 | ## Implementation Approach 7 | 8 | ### 1. Single Data File 9 | All self-improvement data is stored in a single `self_improvement.json` file in the project memory, containing: 10 | - Insights (process, efficiency, patterns, blockers) 11 | - Metrics (time allocation, task completion, decision metrics) 12 | - Patterns (task, decision, session) 13 | - Recommendations (process, efficiency, risk) 14 | - History (analysis records) 15 | 16 | ### 2. Session Integration 17 | Self-improvement insights are embedded directly in session files: 18 | - A dedicated "Self-Improvement" section in each session 19 | - Key insights and recommendations highlighted 20 | - Metrics summarized for quick reference 21 | 22 | ### 3. Operation Integration 23 | The feature is integrated with minimal changes to existing operations: 24 | - `/aegis save`: Generates and stores insights 25 | - `/aegis start`: Applies relevant recommendations 26 | - `/aegis task`: Leverages pattern data 27 | 28 | ## Data Structure 29 | 30 | ### self_improvement.json 31 | 32 | ```json 33 | { 34 | "metadata": { 35 | "version": "1.0", 36 | "last_updated": "2025-03-08T12:05:00" 37 | }, 38 | "insights": { 39 | "process": [ 40 | { 41 | "id": "INSIGHT-001", 42 | "description": "Task transitions from active to hold frequently occur with dependency issues", 43 | "confidence": 0.85, 44 | "impact": "medium", 45 | "created": "2025-03-08T12:05:00", 46 | "related_data": ["TASK-023", "TASK-045"] 47 | } 48 | ], 49 | "efficiency": [], 50 | "patterns": [], 51 | "blockers": [] 52 | }, 53 | "metrics": { 54 | "time_allocation": { 55 | "categories": { 56 | "implementation": 120, 57 | "planning": 45, 58 | "documentation": 30, 59 | "debugging": 15, 60 | "other": 10 61 | }, 62 | "history": [] 63 | }, 64 | "task_completion": { 65 | "average_completion_time": { 66 | "high_priority": 45, 67 | "medium_priority": 60, 68 | "low_priority": 90 69 | }, 70 | "completion_rate": 0.85, 71 | "history": [] 72 | }, 73 | "decision_metrics": { 74 | "average_decisions_per_session": 2.5, 75 | "decision_categories": { 76 | "architecture": 1, 77 | "implementation": 3, 78 | "process": 2 79 | } 80 | } 81 | }, 82 | "patterns": { 83 | "task_patterns": { 84 | "duration": [], 85 | "dependencies": [] 86 | }, 87 | "decision_patterns": [], 88 | "session_patterns": [] 89 | }, 90 | "recommendations": { 91 | "process_improvements": [], 92 | "efficiency_improvements": [], 93 | "risk_mitigations": [] 94 | }, 95 | "history": { 96 | "analysis_history": [] 97 | } 98 | } 99 | ``` 100 | 101 | ### Session Format 102 | 103 | ```markdown 104 | # Session 2025-03-08 105 | 106 | ## Overview 107 | ... 108 | 109 | ## Progress 110 | ... 111 | 112 | ## Decisions 113 | ... 114 | 115 | ## Self-Improvement 116 | ### Insights 117 | - Documentation tasks consistently take 30% longer than initially estimated 118 | - Tasks with more than 2 dependencies have a 60% chance of being moved to hold status 119 | 120 | ### Metrics 121 | - Task completion rate: 75% (3/4 planned tasks completed) 122 | - Time allocation: implementation: 55%, planning: 20%, documentation: 15%, debugging: 10% 123 | - Decision efficiency: 2 key decisions made, both implemented successfully 124 | 125 | ### Recommendations 126 | - [High priority] Start each session with a 10-minute planning period to improve task completion rates 127 | - [Medium priority] Allocate 30% more time for documentation tasks than initially estimated 128 | - [Low priority] Review tasks with more than 2 dependencies before starting to reduce hold transitions 129 | 130 | ## Dependencies 131 | ... 132 | 133 | ## Next Steps 134 | ... 135 | ``` 136 | 137 | ## Analysis Process 138 | 139 | ### 1. Data Collection 140 | During the `/aegis save` operation, the framework collects: 141 | - Current session information 142 | - Task history and transitions 143 | - Decision records 144 | - Time allocation across activities 145 | 146 | ### 2. Analysis Categories 147 | The analysis covers: 148 | - Process analysis (workflow patterns, bottlenecks) 149 | - Efficiency analysis (time allocation, completion rates) 150 | - Pattern recognition (recurring behaviors) 151 | - Blocker identification (obstacles, resolution strategies) 152 | 153 | ### 3. Insight Generation 154 | Based on the analysis, the framework generates: 155 | - Process insights 156 | - Efficiency insights 157 | - Pattern insights 158 | - Blocker insights 159 | 160 | ### 4. Recommendation Formation 161 | The framework forms actionable recommendations: 162 | - Process improvements 163 | - Efficiency enhancements 164 | - Risk mitigations 165 | 166 | ### 5. Storage and Integration 167 | Insights and recommendations are: 168 | - Stored in the `self_improvement.json` file 169 | - Included in the session log 170 | - Applied to future operations 171 | 172 | ## Validation 173 | 174 | ### Validation Schema 175 | A comprehensive validation schema is defined in `self_improvement_validation.json` to ensure data integrity and proper integration: 176 | 177 | - **Data Validation**: Ensures the `self_improvement.json` file adheres to the required structure 178 | - **Session Validation**: Verifies that session documents contain properly formatted Self-Improvement sections 179 | - **Analysis Validation**: Confirms that the analysis process meets minimum requirements for insight generation 180 | - **Integration Validation**: Ensures proper integration with framework operations 181 | 182 | ### Validation Process 183 | The validation occurs at multiple points: 184 | 185 | 1. **Pre-Analysis**: Validates input data before analysis begins 186 | 2. **Post-Analysis**: Validates generated insights and recommendations 187 | 3. **Integration Check**: Verifies proper integration with session documents 188 | 4. **Operation Validation**: Ensures operations correctly handle self-improvement data 189 | 190 | ### Error Handling 191 | When validation fails, the framework: 192 | 1. Logs the specific validation error 193 | 2. Attempts recovery based on the error type 194 | 3. Falls back to safe defaults if recovery fails 195 | 4. Ensures core operations continue even if self-improvement analysis is incomplete 196 | 197 | ## Usage 198 | 199 | ### Accessing Insights 200 | - Review the "Self-Improvement" section in session logs 201 | - Examine the `self_improvement.json` file for detailed data 202 | 203 | ### Applying Recommendations 204 | - Consider recommendations at session start 205 | - Apply suggested improvements incrementally 206 | - Track the impact of implemented recommendations 207 | 208 | ### Interpreting Insights 209 | - Process insights highlight workflow patterns 210 | - Efficiency insights focus on productivity 211 | - Pattern insights identify recurring behaviors 212 | - Blocker insights highlight obstacles 213 | 214 | ## Implementation Notes 215 | 216 | 1. All timestamps use the format: YYYY-MM-DDTHH:MM:SS 217 | 2. Confidence values range from 0.0 to 1.0 218 | 3. Impact levels: low, medium, high 219 | 4. Recommendation status: pending, implemented, rejected 220 | 5. IDs follow the pattern TYPE-XXX (e.g., INSIGHT-001, REC-001) 221 | 6. Self-improvement section is a required part of all session documents 222 | 7. Validation ensures data integrity across the framework 223 | -------------------------------------------------------------------------------- /.context/memory/STATE_TRACKING.md: -------------------------------------------------------------------------------- 1 | # Memory State Tracking 2 | 3 | ## Overview 4 | The state tracking system maintains consistency across the framework's memory system by tracking changes, validating updates, and ensuring proper state transitions. 5 | 6 | ## State Types 7 | 8 | ### Document States 9 | 1. Task States 10 | - planned → active: Task started 11 | - active → completed: Task finished 12 | - active → hold: Task paused 13 | - hold → active: Task resumed 14 | 15 | 2. Session States 16 | - created → active: Session started 17 | - active → paused: Work paused 18 | - paused → active: Work resumed 19 | - active → completed: Session ended 20 | 21 | 3. Decision States 22 | - draft → review: Ready for review 23 | - review → accepted/rejected: Decision made 24 | - rejected → draft: Revision needed 25 | 26 | ### Memory States 27 | 1. Core Memory 28 | - read-only: Framework rules 29 | - mutable: Framework state 30 | - configurable: Settings 31 | 32 | 2. Project Memory 33 | - append-only: Decisions 34 | - mutable: Context 35 | - cumulative: Progress 36 | 37 | 3. Session Memory 38 | - volatile: Active state 39 | - persistent: History 40 | - temporary: Cache 41 | 42 | ## State Changes 43 | 44 | ### Change Types 45 | 1. Direct Changes 46 | - Document status updates 47 | - Configuration changes 48 | - User preferences 49 | 50 | 2. Indirect Changes 51 | - Reference updates 52 | - Dependency changes 53 | - State propagation 54 | 55 | 3. System Changes 56 | - Framework updates 57 | - Session transitions 58 | - Cleanup operations 59 | 60 | ### Change Rules 61 | 1. Validation 62 | - Check state transition allowed 63 | - Verify references valid 64 | - Ensure consistency 65 | 66 | 2. Updates 67 | - Record timestamp 68 | - Update references 69 | - Maintain history 70 | 71 | 3. Propagation 72 | - Update dependencies 73 | - Notify related items 74 | - Maintain consistency 75 | 76 | ## Implementation 77 | 78 | ### State Tracking 79 | 1. Document Level 80 | ```yaml 81 | status: current_state 82 | updated: timestamp 83 | history: 84 | - state: previous_state 85 | timestamp: when_changed 86 | reason: why_changed 87 | ``` 88 | 89 | 2. Memory Level 90 | ```yaml 91 | type: memory_type 92 | state: current_state 93 | content: memory_data 94 | metadata: 95 | created: creation_time 96 | updated: last_update 97 | history: state_changes 98 | ``` 99 | 100 | ### State Operations 101 | 1. Read State 102 | - Check permissions 103 | - Load current state 104 | - Validate schema 105 | 106 | 2. Update State 107 | - Verify transition 108 | - Record change 109 | - Update timestamps 110 | 111 | 3. Track History 112 | - Save previous state 113 | - Record reason 114 | - Maintain log 115 | 116 | ## Usage Rules 117 | 118 | ### State Access 119 | 1. Read Operations 120 | - Always check current state 121 | - Verify permissions 122 | - Validate schema 123 | 124 | 2. Write Operations 125 | - Follow state transitions 126 | - Update all references 127 | - Maintain history 128 | 129 | 3. Update Operations 130 | - Check transition allowed 131 | - Record change reason 132 | - Update dependencies 133 | 134 | ### Recovery Procedures 135 | 1. State Mismatch 136 | - Load last valid state 137 | - Check history log 138 | - Resolve conflicts 139 | 140 | 2. Failed Updates 141 | - Revert to previous 142 | - Log failure reason 143 | - Retry if safe 144 | 145 | 3. Inconsistencies 146 | - Detect conflicts 147 | - Resolve references 148 | - Rebuild state 149 | -------------------------------------------------------------------------------- /.context/memory/STRUCTURE.md: -------------------------------------------------------------------------------- 1 | # Memory System Structure 2 | 3 | ## Overview 4 | The memory system maintains state across sessions using a hierarchical file structure. 5 | 6 | ## Directory Layout 7 | ``` 8 | memory/ 9 | ├── core/ # Framework core memories 10 | │ ├── state.json # Framework state 11 | │ ├── config.json # Framework configuration 12 | │ └── rules.json # Framework rules 13 | ├── project/ # Project-specific memories 14 | │ └── context/ # Project context and metadata 15 | └── session/ # Session state 16 | ├── active.json # Active session state 17 | └── history/ # Session history 18 | ``` 19 | 20 | ## File Formats 21 | 22 | ### JSON Schema 23 | All memory files use JSON format with the following base schema: 24 | ```json 25 | { 26 | "type": "memory", 27 | "category": "", 28 | "id": "unique-identifier", 29 | "created": "ISO-8601-date", 30 | "updated": "ISO-8601-date", 31 | "content": { 32 | // Memory-specific content 33 | } 34 | } 35 | ``` 36 | 37 | ### Memory Categories 38 | 39 | #### Core Memories 40 | - Immutable framework rules 41 | - Configuration settings 42 | - State tracking 43 | - Operation patterns 44 | 45 | #### Project Memories 46 | - Project context and metadata 47 | - Project state tracking 48 | - Project configuration 49 | - Dependencies 50 | 51 | #### Session Memories 52 | - Active session state 53 | - Command history 54 | - Recent changes 55 | - Temporary data 56 | 57 | ## Usage Rules 58 | 59 | ### Memory Operations 60 | 1. Read Operations 61 | - Always validate schema 62 | - Check memory category 63 | - Verify permissions 64 | 65 | 2. Write Operations 66 | - Follow schema exactly 67 | - Update timestamps 68 | - Maintain history 69 | - Validate content 70 | 71 | 3. Update Operations 72 | - Preserve existing fields 73 | - Track changes 74 | - Update references 75 | - Maintain consistency 76 | 77 | ### Access Patterns 78 | 1. Core Access 79 | - Read-only for most operations 80 | - Updates through framework only 81 | - Version controlled 82 | 83 | 2. Project Access 84 | - Read-write during sessions 85 | - History preserved 86 | - References maintained 87 | 88 | 3. Session Access 89 | - Active session read-write 90 | - History append-only 91 | - Cleanup on completion 92 | 93 | ## Implementation Notes 94 | 1. Use atomic operations 95 | 2. Maintain backups 96 | 3. Handle conflicts 97 | 4. Validate references 98 | 5. Track dependencies 99 | -------------------------------------------------------------------------------- /.context/memory/core/config.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "memory", 3 | "category": "core", 4 | "id": "framework-config", 5 | "created": "2025-02-17T10:17:54-05:00", 6 | "updated": "2025-02-24T10:28:55-05:00", 7 | "content": { 8 | "framework": { 9 | "rootDir": ".context", 10 | "memoryDir": "memory", 11 | "templatesDir": "templates", 12 | "operationsDir": "operations" 13 | }, 14 | "validation": { 15 | "enforceSchema": true, 16 | "requireFrontMatter": true, 17 | "checkReferences": true 18 | }, 19 | "backup": { 20 | "enabled": true, 21 | "interval": "1h", 22 | "maxBackups": 10 23 | } 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /.context/memory/core/rules.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "memory", 3 | "category": "core", 4 | "id": "framework-rules", 5 | "created": "2025-02-17T10:17:54-05:00", 6 | "updated": "2025-02-24T10:29:33-05:00", 7 | "content": { 8 | "taskStates": ["planned", "active", "hold", "completed"], 9 | "sessionStates": ["active", "paused", "completed"], 10 | "decisionStates": ["draft", "review", "accepted", "rejected"], 11 | "referencePatterns": { 12 | "task": "TASK-\\d{3}", 13 | "session": "(SESSION-\\d{3}|SESSION-\\d{4}-\\d{2}-\\d{2}-\\d{4})", 14 | "decision": "DECISION-\\d{3}" 15 | }, 16 | "requiredFiles": { 17 | "root": ["README.md"], 18 | "templates": { 19 | "tasks": ["README.md", "TEMPLATE.md", "example.md"], 20 | "sessions": ["README.md", "TEMPLATE.md", "example.md"], 21 | "decisions": ["README.md", "TEMPLATE.md", "example.md"] 22 | }, 23 | "operations": ["README.md"], 24 | "memory": ["README.md"] 25 | } 26 | } 27 | } 28 | -------------------------------------------------------------------------------- /.context/memory/core/state.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "memory", 3 | "category": "core", 4 | "id": "framework-state", 5 | "created": "2025-02-17T10:17:54-05:00", 6 | "updated": "2025-02-24T11:12:00-05:00", 7 | "content": { 8 | "version": "0.1.0", 9 | "status": "initializing", 10 | "activeTask": "TASK-003", 11 | "activeSession": "SESSION-001", 12 | "lastOperation": null, 13 | "lastSession": "SESSION-009", 14 | "decisions": [], 15 | "directories": { 16 | "root": ".context", 17 | "tasks": { 18 | "active": "tasks/active", 19 | "planned": "tasks/planned", 20 | "hold": "tasks/hold", 21 | "completed": "tasks/completed" 22 | }, 23 | "sessions": "sessions", 24 | "decisions": "project/decisions", 25 | "templates": "templates" 26 | } 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /.context/memory/project/context/project.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "memory", 3 | "category": "project", 4 | "id": "project-context", 5 | "created": "2025-03-15T14:55:00", 6 | "updated": "2025-03-15T14:55:00", 7 | "content": { 8 | "name": "Aegis Framework", 9 | "version": "1.0.0", 10 | "description": "AI-enhanced development framework", 11 | "status": "active", 12 | "phase": "initial", 13 | "activeTasks": [], 14 | "completedTasks": [], 15 | "plannedTasks": [], 16 | "decisions": [], 17 | "components": [ 18 | "memory-system", 19 | "template-system", 20 | "operation-patterns", 21 | "self-improvement-system", 22 | "code-context-management" 23 | ] 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /.context/memory/project/self_improvement.json: -------------------------------------------------------------------------------- 1 | { 2 | "metadata": { 3 | "version": "1.0", 4 | "last_updated": "2025-03-15T14:58:00" 5 | }, 6 | "insights": { 7 | "process": [], 8 | "efficiency": [], 9 | "patterns": [], 10 | "blockers": [] 11 | }, 12 | "metrics": { 13 | "time_allocation": { 14 | "categories": { 15 | "implementation": 0, 16 | "planning": 0, 17 | "documentation": 0, 18 | "debugging": 0, 19 | "other": 0 20 | }, 21 | "history": [] 22 | }, 23 | "task_completion": { 24 | "average_completion_time": { 25 | "high_priority": 0, 26 | "medium_priority": 0, 27 | "low_priority": 0 28 | }, 29 | "completion_rate": 0, 30 | "history": [] 31 | }, 32 | "decision_metrics": { 33 | "average_decisions_per_session": 0, 34 | "decision_categories": { 35 | "architecture": 0, 36 | "implementation": 0, 37 | "process": 0 38 | } 39 | } 40 | }, 41 | "patterns": { 42 | "task_patterns": { 43 | "duration": [], 44 | "dependencies": [] 45 | }, 46 | "decision_patterns": [], 47 | "session_patterns": [] 48 | }, 49 | "recommendations": { 50 | "process_improvements": [], 51 | "efficiency_improvements": [], 52 | "risk_mitigations": [] 53 | }, 54 | "history": { 55 | "analysis_history": [] 56 | } 57 | } 58 | -------------------------------------------------------------------------------- /.context/memory/session/active.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "memory", 3 | "category": "session", 4 | "id": "active-session", 5 | "created": "2025-03-11T16:30:00-05:00", 6 | "updated": "2025-03-11T19:35:00-05:00", 7 | "content": { 8 | "sessionId": "SESSION-2025-03-11", 9 | "status": "active", 10 | "started": "2025-03-11T16:30:00-05:00", 11 | "activeTask": "TASK-017", 12 | "currentStep": "test-planning", 13 | "progress": { 14 | "completed": [ 15 | "analyze-command-patterns", 16 | "create-command-checklists", 17 | "develop-validation-patterns", 18 | "create-execution-flowcharts", 19 | "document-recovery-procedures", 20 | "implement-command-templates", 21 | "plan-testing-approach" 22 | ], 23 | "inProgress": [ 24 | "test-failsafe-mechanisms" 25 | ], 26 | "pending": [ 27 | "update-framework-documentation" 28 | ] 29 | }, 30 | "context": { 31 | "lastCommand": "/aegis save", 32 | "lastFile": "README.md", 33 | "openFiles": [ 34 | "README.md", 35 | "TASK-017.md", 36 | "DEC-003.md", 37 | "2025-03-11-session.md", 38 | "project.json", 39 | "active.json" 40 | ], 41 | "decisions": [ 42 | "DEC-001", 43 | "DEC-002", 44 | "DEC-003" 45 | ] 46 | } 47 | } 48 | } 49 | -------------------------------------------------------------------------------- /.context/plan/planning_document.md: -------------------------------------------------------------------------------- 1 | # [Project Name] Plan 2 | --- 3 | title: [Project Name] Plan 4 | type: plan 5 | status: active 6 | created: YYYY-MM-DDTHH:MM:SS 7 | updated: YYYY-MM-DDTHH:MM:SS 8 | id: PLAN-XXX 9 | priority: [high|medium|low] 10 | dependencies: [] 11 | memory_types: [procedural, semantic] 12 | assignee: [assignee] 13 | estimated_time: [time estimate] 14 | tags: [tag1, tag2, tag3] 15 | --- 16 | 17 | ## Overview 18 | [Replace with a concise description of the project, its purpose, and goals. Include context about why this project is being undertaken and what problem it solves.] 19 | 20 | ## Objectives 21 | - [Objective 1: Replace with specific, measurable objective] 22 | - [Objective 2: Replace with specific, measurable objective] 23 | - [Objective 3: Replace with specific, measurable objective] 24 | - [Add more objectives as needed] 25 | 26 | ## Components 27 | 1. **[Component 1 Name]** 28 | - Description: [Brief description of this component] 29 | - Tasks: 30 | - [Task related to this component] 31 | - [Another task related to this component] 32 | - [Add more tasks as needed] 33 | 34 | 2. **[Component 2 Name]** 35 | - Description: [Brief description of this component] 36 | - Tasks: 37 | - [Task related to this component] 38 | - [Another task related to this component] 39 | - [Add more tasks as needed] 40 | 41 | 3. **[Add more components as needed]** 42 | 43 | ## Dependencies 44 | - [Task 2] depends on [Task 1] 45 | - [Task 4] depends on [Task 3] 46 | - [Add more dependencies as needed] 47 | 48 | ## Timeline 49 | - Phase 1 ([timeframe]): [Tasks to complete in this phase] 50 | - Phase 2 ([timeframe]): [Tasks to complete in this phase] 51 | - Phase 3 ([timeframe]): [Tasks to complete in this phase] 52 | - [Add more phases as needed] 53 | 54 | ## Success Criteria 55 | - [Criterion 1: How will you know the project is successful?] 56 | - [Criterion 2: How will you know the project is successful?] 57 | - [Criterion 3: How will you know the project is successful?] 58 | - [Add more criteria as needed] 59 | 60 | ## Notes 61 | - [Important note or consideration about the project] 62 | - [Another important note or consideration] 63 | - [Add more notes as needed] 64 | 65 | ## Next Steps 66 | - [Immediate next step to take] 67 | - [Another immediate next step to take] 68 | - [Add more next steps as needed] -------------------------------------------------------------------------------- /.context/tasks/README.md: -------------------------------------------------------------------------------- 1 | # Task Management 2 | 3 | This directory manages tasks through their entire lifecycle. 4 | 5 | ## States 6 | 7 | ### planned/ 8 | Tasks ready for implementation: 9 | - Defined scope 10 | - Clear objectives 11 | - Known dependencies 12 | - Ready for work 13 | 14 | ### active/ 15 | Tasks currently in progress: 16 | - Being worked on 17 | - Progress tracked 18 | - Status updated 19 | - Dependencies met 20 | 21 | ### hold/ 22 | Tasks waiting on dependencies: 23 | - Hold status 24 | - Resolve dependencies 25 | - Track dependencies 26 | - Document resolution path 27 | 28 | ### completed/ 29 | Finished tasks: 30 | - Work completed 31 | - Validated results 32 | - Documentation updated 33 | - References maintained 34 | 35 | ## Usage 36 | - Move tasks between states 37 | - Update status in front matter 38 | - Track progress 39 | - Maintain dependencies 40 | -------------------------------------------------------------------------------- /.context/tasks/active/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/BuildSomethingAI/aegis-framework/f055d798d9954beed08f0a23635b539b26ebfc07/.context/tasks/active/.gitkeep -------------------------------------------------------------------------------- /.context/tasks/blocked/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/BuildSomethingAI/aegis-framework/f055d798d9954beed08f0a23635b539b26ebfc07/.context/tasks/blocked/.gitkeep -------------------------------------------------------------------------------- /.context/tasks/completed/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/BuildSomethingAI/aegis-framework/f055d798d9954beed08f0a23635b539b26ebfc07/.context/tasks/completed/.gitkeep -------------------------------------------------------------------------------- /.context/tasks/hold/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/BuildSomethingAI/aegis-framework/f055d798d9954beed08f0a23635b539b26ebfc07/.context/tasks/hold/.gitkeep -------------------------------------------------------------------------------- /.context/tasks/planned/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/BuildSomethingAI/aegis-framework/f055d798d9954beed08f0a23635b539b26ebfc07/.context/tasks/planned/.gitkeep -------------------------------------------------------------------------------- /.context/templates/README.md: -------------------------------------------------------------------------------- 1 | # Document Templates 2 | 3 | This directory contains templates for maintaining consistency across all framework documents. 4 | 5 | ## Templates 6 | 7 | ### tasks/ 8 | Task definition templates: 9 | - Required sections 10 | - Front matter schema 11 | - Progress tracking 12 | - Dependency management 13 | - Example: `tasks/example.md` - Memory system implementation 14 | 15 | ### sessions/ 16 | Session record templates: 17 | - Context tracking 18 | - Progress recording 19 | - Decision logging 20 | - Next steps 21 | - Example: `sessions/example.md` - Memory system development session 22 | 23 | ### decisions/ 24 | Decision record templates: 25 | - Context capture 26 | - Options considered 27 | - Implementation details 28 | - Impact assessment 29 | - Example: `decisions/example.md` - Memory system architecture decision 30 | 31 | ## Usage 32 | - Copy appropriate template 33 | - Fill in all required fields 34 | - Follow front matter schema 35 | - Include all necessary sections 36 | - Reference examples for guidance 37 | 38 | ## Examples 39 | Each template directory contains an example document that demonstrates: 40 | 1. Proper front matter usage 41 | 2. Required sections 42 | 3. Correct formatting 43 | 4. Cross-referencing 44 | 5. Status tracking 45 | 46 | The examples form a cohesive narrative around implementing a memory system, 47 | showing how different document types work together in the framework. 48 | See framework memory for detailed documentation of examples. 49 | -------------------------------------------------------------------------------- /.context/templates/decisions/README.md: -------------------------------------------------------------------------------- 1 | # Decision Templates 2 | 3 | This directory contains templates for recording architectural and implementation decisions. 4 | 5 | ## Files 6 | - `TEMPLATE.md`: Base template for creating new decision records 7 | - `example.md`: Example decision record (Memory System Architecture) 8 | 9 | ## Usage 10 | 1. Copy TEMPLATE.md when making a new decision 11 | 2. Follow front matter requirements 12 | 3. Document all options considered 13 | 4. Include implementation plan 14 | 5. Reference example.md for proper format 15 | 16 | ## Validation Rules 17 | See `../validation.md` for detailed rules on: 18 | - Front matter requirements 19 | - Section requirements 20 | - Option documentation 21 | - Implementation tracking 22 | 23 | ## Related Documents 24 | Decisions should reference: 25 | - Related tasks using TASK-[000] 26 | - Other decisions using DECISION-[000] 27 | - Implementation sessions using SESSION-[000] 28 | - Documentation using relative paths 29 | -------------------------------------------------------------------------------- /.context/templates/decisions/TEMPLATE.md: -------------------------------------------------------------------------------- 1 | # Decision: [Title] 2 | --- 3 | type: decision 4 | status: [proposed|accepted|rejected|superseded] 5 | created: [YYYY-MM-DDTHH:MM:SS] 6 | updated: [YYYY-MM-DDTHH:MM:SS] 7 | id: DECISION-[000] 8 | relates_to: [TASK-000] 9 | supersedes: [DECISION-000] 10 | memory_types: [semantic, episodic] 11 | --- 12 | 13 | ## Context 14 | [What is the issue that we're seeing that is motivating this decision or change?] 15 | 16 | ## Problem Statement 17 | [What problem are we trying to solve?] 18 | 19 | ## Drivers 20 | - [Driver 1] 21 | - [Driver 2] 22 | - [Driver 3] 23 | 24 | ## Options Considered 25 | ### Option 1: [Title] 26 | - Pros 27 | - [Pro 1] 28 | - [Pro 2] 29 | - Cons 30 | - [Con 1] 31 | - [Con 2] 32 | 33 | ### Option 2: [Title] 34 | - Pros 35 | - [Pro 1] 36 | - [Pro 2] 37 | - Cons 38 | - [Con 1] 39 | - [Con 2] 40 | 41 | ## Decision 42 | [What is the change that we're proposing and/or doing?] 43 | 44 | ## Rationale 45 | [Why are we doing this? What evidence supports this decision?] 46 | 47 | ## Implementation 48 | - [ ] [Step 1] 49 | - [ ] [Step 2] 50 | - [ ] [Step 3] 51 | 52 | ## Consequences 53 | ### Positive 54 | - [Positive consequence 1] 55 | - [Positive consequence 2] 56 | 57 | ### Negative 58 | - [Negative consequence 1] 59 | - [Negative consequence 2] 60 | 61 | ## Related 62 | - Tasks: [TASK-000] 63 | - Decisions: [DECISION-000] 64 | - Documentation: [links to docs] 65 | -------------------------------------------------------------------------------- /.context/templates/decisions/example.md: -------------------------------------------------------------------------------- 1 | # Decision: Memory System Implementation 2 | --- 3 | type: decision 4 | status: accepted 5 | created: 2025-02-17 6 | updated: 2025-02-17 7 | id: DECISION-001 8 | relates_to: TASK-003 9 | memory_types: [semantic, episodic] 10 | --- 11 | 12 | ## Context 13 | The framework needs a reliable system for storing and managing different types of memory, including framework state, project context, and session information. The implementation choice will affect all framework operations. 14 | 15 | ## Problem Statement 16 | We need to choose an implementation approach for the memory system that ensures data consistency, provides easy access, and maintains reliability across all framework operations. 17 | 18 | ## Drivers 19 | - Data consistency is critical 20 | - Must support multiple memory types 21 | - Need concurrent access 22 | - Must be reliable and recoverable 23 | - Should be easy to debug 24 | 25 | ## Options Considered 26 | ### Option 1: File-based YAML Storage 27 | - Pros 28 | - Human-readable format 29 | - Easy to version control 30 | - Simple to implement 31 | - Good tooling support 32 | - Cons 33 | - Slower than binary formats 34 | - No built-in transactions 35 | - Needs careful concurrent access 36 | 37 | ### Option 2: SQLite Database 38 | - Pros 39 | - ACID compliance 40 | - Better performance 41 | - Built-in concurrent access 42 | - Transaction support 43 | - Cons 44 | - Less transparent 45 | - Harder to version control 46 | - Requires migration system 47 | - More complex implementation 48 | 49 | ## Decision 50 | Implement a file-based system using YAML format with additional safeguards: 51 | 1. Use atomic writes for updates 52 | 2. Implement transaction logging 53 | 3. Add file locking for concurrent access 54 | 4. Create backup system 55 | 56 | ## Rationale 57 | - YAML format provides better transparency 58 | - File-based system works well with git 59 | - Atomic writes ensure consistency 60 | - Transaction logs enable recovery 61 | - Simpler to implement and maintain 62 | 63 | ## Implementation 64 | - [x] Create directory structure 65 | - [x] Define memory types 66 | - [ ] Implement atomic writes 67 | - [ ] Add transaction logging 68 | - [ ] Create utility functions 69 | - [ ] Add backup system 70 | 71 | ## Consequences 72 | ### Positive 73 | - Easy to inspect and debug 74 | - Works well with version control 75 | - Simple to understand 76 | - Easy to modify 77 | 78 | ### Negative 79 | - Slower than database 80 | - Manual concurrent access 81 | - More code for safety 82 | - Need careful error handling 83 | 84 | ## Related 85 | - Tasks: TASK-003 86 | - Decisions: None 87 | - Documentation: memory_system.md 88 | -------------------------------------------------------------------------------- /.context/templates/sessions/README.md: -------------------------------------------------------------------------------- 1 | # Session Templates 2 | 3 | This directory contains templates for recording development sessions. 4 | 5 | ## Files 6 | - `TEMPLATE.md`: Base template for creating new session records 7 | - `example.md`: Example session record (Memory System Development) 8 | 9 | ## Usage 10 | 1. Copy TEMPLATE.md when starting a new session 11 | 2. Follow front matter requirements 12 | 3. Update progress during session 13 | 4. Record decisions and dependencies 14 | 5. Reference example.md for proper format 15 | 16 | ## Validation Rules 17 | See `../validation.md` for detailed rules on: 18 | - Front matter requirements 19 | - Section requirements 20 | - Progress tracking 21 | - Decision recording 22 | 23 | ## Cross-References 24 | Sessions must reference: 25 | - Active task using TASK-[000] 26 | - Decisions made using DECISION-[000] 27 | - Related sessions using SESSION-[000] 28 | - Dependencies 29 | -------------------------------------------------------------------------------- /.context/templates/sessions/TEMPLATE.md: -------------------------------------------------------------------------------- 1 | # Session: [YYYY-MM-DD] 2 | --- 3 | type: session 4 | status: [active|completed] 5 | started: [YYYY-MM-DDTHH:MM:SS] 6 | ended: [YYYY-MM-DDTHH:MM:SS] 7 | id: SESSION-[000] 8 | memory_types: [episodic, procedural] 9 | --- 10 | 11 | ## Focus 12 | [Current task or objective] 13 | 14 | ## Context 15 | - Active Task: [TASK-000] 16 | - Branch: [current git branch] 17 | - Related Issues: [issue references] 18 | 19 | ## Progress 20 | ### Completed 21 | - [Achievement 1] 22 | - [Achievement 2] 23 | 24 | ### In Progress 25 | - [ ] [Current work 1] 26 | - [ ] [Current work 2] 27 | 28 | ## Decisions 29 | 1. [Decision 1] 30 | - Context: [Why was this decision needed] 31 | - Options: [What options were considered] 32 | - Choice: [What was chosen and why] 33 | 34 | 2. [Decision 2] 35 | - Context: [Why was this decision needed] 36 | - Options: [What options were considered] 37 | - Choice: [What was chosen and why] 38 | 39 | ## Self-Improvement 40 | ### Insights 41 | - [Key insight about process or efficiency] 42 | - [Pattern identified in task execution or decision-making] 43 | 44 | ### Metrics 45 | - Task completion rate: [percentage] 46 | - Time allocation: [implementation: X%, planning: Y%, documentation: Z%] 47 | - Decision efficiency: [metric] 48 | 49 | ### Recommendations 50 | - [High priority] [Recommendation for process improvement] 51 | - [Medium priority] [Recommendation for efficiency enhancement] 52 | - [Low priority] [Recommendation for risk mitigation] 53 | 54 | ## Dependencies 55 | - [ ] [Dependency 1] 56 | - Impact: [Tasks affected] 57 | - Resolution: [How to resolve] 58 | - Status: [Tasks on hold] 59 | 60 | ## Next Steps 61 | 1. [Next step 1] 62 | 2. [Next step 2] 63 | 64 | ## Notes 65 | [Important notes about the session] 66 | -------------------------------------------------------------------------------- /.context/templates/sessions/example.md: -------------------------------------------------------------------------------- 1 | # Session: 2025-02-17 2 | --- 3 | type: session 4 | status: active 5 | started: 2025-02-17T09:00:00 6 | id: SESSION-001 7 | memory_types: [episodic, procedural] 8 | --- 9 | 10 | ## Focus 11 | Implement core memory system components and establish state management. 12 | 13 | ## Context 14 | - Active Task: TASK-003 15 | - Branch: feature/memory-system 16 | - Related Issues: #45, #46 17 | 18 | ## Progress 19 | ### Completed 20 | - Created memory directory structure 21 | - Defined memory types 22 | - Implemented basic validation 23 | - Added type schemas 24 | 25 | ### In Progress 26 | - [ ] Implementing state management 27 | - [ ] Creating utility functions 28 | - [ ] Writing test cases 29 | 30 | ## Decisions 31 | 1. Memory Storage Format 32 | - Context: Need to choose a storage format for memory files 33 | - Options: JSON, YAML, Custom Format 34 | - Choice: YAML for readability and existing parser support 35 | 36 | 2. State Management 37 | - Context: Need to handle concurrent state updates 38 | - Options: File locks, Transaction log, Atomic writes 39 | - Choice: Atomic writes with transaction log for safety 40 | 41 | ## Self-Improvement 42 | ### Insights 43 | - Documentation tasks consistently take 30% longer than initially estimated 44 | - Tasks with more than 2 dependencies have a 60% chance of being moved to hold status 45 | 46 | ### Metrics 47 | - Task completion rate: 75% (3/4 planned tasks completed) 48 | - Time allocation: implementation: 55%, planning: 20%, documentation: 15%, debugging: 10% 49 | - Decision efficiency: 2 key decisions made, both implemented successfully 50 | 51 | ### Recommendations 52 | - [High priority] Start each session with a 10-minute planning period to improve task completion rates 53 | - [Medium priority] Allocate 30% more time for documentation tasks than initially estimated 54 | - [Low priority] Review tasks with more than 2 dependencies before starting to reduce hold transitions 55 | 56 | ## Dependencies 57 | - [ ] Need to finalize template system 58 | - Impact: State validation rules depend on templates 59 | - Resolution: Waiting for TASK-002 completion 60 | 61 | ## Next Steps 62 | 1. Complete state management implementation 63 | 2. Add memory validation rules 64 | 3. Create utility functions 65 | 4. Begin testing 66 | 67 | ## Notes 68 | Consider adding a memory migration system for future updates. 69 | -------------------------------------------------------------------------------- /.context/templates/tasks/README.md: -------------------------------------------------------------------------------- 1 | # Task Templates 2 | 3 | This directory contains templates for creating and managing tasks. 4 | 5 | ## Files 6 | - `TEMPLATE.md`: Base template for creating new tasks 7 | - `example.md`: Example task implementation (Memory System) 8 | 9 | ## Usage 10 | 1. Copy TEMPLATE.md when creating a new task 11 | 2. Follow front matter requirements 12 | 3. Fill in all required sections 13 | 4. Reference example.md for proper format 14 | 15 | ## Validation Rules 16 | See `../validation.md` for detailed rules on: 17 | - Front matter requirements 18 | - Section requirements 19 | - Content formatting 20 | - Status transitions 21 | 22 | ## Dependencies 23 | Tasks can reference: 24 | - Other tasks using TASK-[000] 25 | - Decisions using DECISION-[000] 26 | - Sessions using SESSION-[000] 27 | -------------------------------------------------------------------------------- /.context/templates/tasks/TEMPLATE.md: -------------------------------------------------------------------------------- 1 | # Task: [Title] 2 | --- 3 | title: [Task Title] 4 | type: task 5 | status: planned 6 | created: [YYYY-MM-DDTHH:MM:SS] 7 | updated: [YYYY-MM-DDTHH:MM:SS] 8 | id: TASK-[000] 9 | priority: [high|medium|low] 10 | dependencies: [] 11 | memory_types: [procedural, semantic] 12 | assignee: [username] 13 | estimated_time: [X hours/days] 14 | tags: [] 15 | --- 16 | 17 | ## Description 18 | [Clear, concise description of the task] 19 | 20 | ## Objectives 21 | - [Specific objective 1] 22 | - [Specific objective 2] 23 | - [Specific objective 3] 24 | 25 | ## Steps 26 | - [ ] [Step 1] 27 | - [ ] [Step 2] 28 | - [ ] [Step 3] 29 | 30 | ## Progress 31 | [Current progress, updated regularly] 32 | 33 | ## Dependencies 34 | - [Dependency 1: Description] 35 | - [Dependency 2: Description] 36 | 37 | ## Code Context 38 | - file: [src/component/file.js] 39 | relevance: [0.9] 40 | sections: [10-45] 41 | reason: "[Core implementation for this feature]" 42 | - file: [src/utils/helper.js] 43 | relevance: [0.7] 44 | sections: [all] 45 | reason: "[Contains utility functions needed for implementation]" 46 | 47 | ## Notes 48 | [Important notes about implementation, constraints, or considerations] 49 | 50 | ## Next Steps 51 | 1. [Next step 1] 52 | 2. [Next step 2] 53 | 54 | ## Completion Notes 55 | [Added when task is completed, describing final state and any important outcomes] 56 | -------------------------------------------------------------------------------- /.context/templates/tasks/example.md: -------------------------------------------------------------------------------- 1 | # Task: Implement Memory System 2 | --- 3 | type: task 4 | status: active 5 | created: 2025-02-17 6 | updated: 2025-02-17 7 | id: TASK-003 8 | priority: high 9 | memory_types: [procedural, semantic] 10 | --- 11 | 12 | ## Description 13 | Create a robust memory system for storing and managing framework state, project context, and session information using a file-based approach. 14 | 15 | ## Objectives 16 | - Create memory storage structure 17 | - Implement memory types 18 | - Add state management 19 | - Ensure data consistency 20 | 21 | ## Steps 22 | - [x] Design memory directory structure 23 | - [x] Define memory types and schemas 24 | - [ ] Implement state management 25 | - [ ] Add validation rules 26 | - [ ] Create memory utilities 27 | - [ ] Test memory operations 28 | 29 | ## Progress 30 | - Completed memory system design 31 | - Created directory structure 32 | - Defined core memory types: 33 | - Framework memory 34 | - Project memory 35 | - Session memory 36 | - Implemented basic validation 37 | 38 | ## Dependencies 39 | - TASK-001: Framework structure 40 | - TASK-002: Document templates 41 | 42 | ## Notes 43 | Memory system must be reliable and maintain consistency across all operations. 44 | Consider implementing backup and recovery mechanisms. 45 | 46 | ## Next Steps 47 | 1. Implement state management system 48 | 2. Create memory validation rules 49 | 3. Build utility functions 50 | 4. Add test cases 51 | -------------------------------------------------------------------------------- /.context/templates/validation.md: -------------------------------------------------------------------------------- 1 | # Template Validation Rules 2 | 3 | ## Front Matter Requirements 4 | 5 | ### Task Template 6 | ```yaml 7 | required: 8 | type: 9 | value: "task" 10 | description: "Document type, must be 'task'" 11 | status: 12 | values: ["planned", "active", "hold", "completed"] 13 | description: "Current task status" 14 | created: 15 | format: "YYYY-MM-DD" 16 | description: "Creation date" 17 | updated: 18 | format: "YYYY-MM-DD" 19 | description: "Last update date" 20 | id: 21 | pattern: "TASK-\\d{3}" 22 | description: "Unique task identifier" 23 | memory_types: 24 | type: "array" 25 | values: ["procedural", "semantic", "episodic"] 26 | description: "Types of memory this task affects" 27 | optional: 28 | priority: 29 | values: ["high", "medium", "low"] 30 | description: "Task priority level" 31 | ``` 32 | 33 | ### Session Template 34 | ```yaml 35 | required: 36 | type: 37 | value: "session" 38 | description: "Document type, must be 'session'" 39 | status: 40 | values: ["active", "completed"] 41 | description: "Current session status" 42 | started: 43 | format: "YYYY-MM-DD HH:MM:SS" 44 | description: "Session start time" 45 | id: 46 | pattern: "SESSION-\\d{3}" 47 | description: "Unique session identifier" 48 | optional: 49 | ended: 50 | format: "YYYY-MM-DD HH:MM:SS" 51 | description: "Session end time" 52 | ``` 53 | 54 | ### Decision Template 55 | ```yaml 56 | required: 57 | type: 58 | value: "decision" 59 | description: "Document type, must be 'decision'" 60 | status: 61 | values: ["proposed", "accepted", "rejected", "superseded"] 62 | description: "Current decision status" 63 | created: 64 | format: "YYYY-MM-DD" 65 | description: "Creation date" 66 | updated: 67 | format: "YYYY-MM-DD" 68 | description: "Last update date" 69 | id: 70 | pattern: "DECISION-\\d{3}" 71 | description: "Unique decision identifier" 72 | optional: 73 | relates_to: 74 | pattern: "TASK-\\d{3}" 75 | description: "Related task identifier" 76 | supersedes: 77 | pattern: "DECISION-\\d{3}" 78 | description: "Identifier of decision this supersedes" 79 | ``` 80 | 81 | ## Validation Rules 82 | 83 | ### Common Rules 84 | 1. Front matter must be enclosed in triple-dashes (`---`) 85 | 2. All dates must use the specified format 86 | 3. IDs must follow the specified pattern 87 | 4. Status values must be from the allowed set 88 | 5. Required fields cannot be empty 89 | 6. Optional fields can be omitted but must be valid if present 90 | 91 | ### Task-Specific Rules 92 | 1. Status transitions must be valid: 93 | - planned → active 94 | - active → hold 95 | - active → completed 96 | - hold → active 97 | 2. Updated date must be >= created date 98 | 3. Priority must be specified for high-priority tasks 99 | 100 | ### Session-Specific Rules 101 | 1. Ended time must be > started time 102 | 2. Ended time required if status is completed 103 | 3. Cannot have ended time if status is active 104 | 105 | ### Decision-Specific Rules 106 | 1. Must include rationale if status is accepted 107 | 2. Must include consequences if status is accepted 108 | 3. Updated date must be >= created date 109 | 4. Must include supersedes reference if status is superseded 110 | 111 | ## Content Validation Rules 112 | 113 | ### Section Requirements 114 | 115 | #### Task Template 116 | ```yaml 117 | required_sections: 118 | Description: 119 | min_length: 20 120 | max_length: 500 121 | rules: 122 | - Must clearly state the task purpose 123 | - Must be written in present tense 124 | - Must be actionable 125 | 126 | Objectives: 127 | min_items: 1 128 | max_items: 5 129 | rules: 130 | - Each objective must be measurable 131 | - Must use bullet points 132 | - Must start with action verbs 133 | 134 | Steps: 135 | min_items: 1 136 | rules: 137 | - Must use checkbox format: "- [ ]" 138 | - Must be ordered logically 139 | - Must be atomic actions 140 | 141 | Progress: 142 | rules: 143 | - Must use bullet points 144 | - Must be updated with each change 145 | - Must reflect current state 146 | 147 | Dependencies: 148 | rules: 149 | - Must reference valid task IDs 150 | - Must indicate status ( or ) 151 | - Must be ordered by dependency chain 152 | 153 | optional_sections: 154 | Notes: 155 | rules: 156 | - Should provide context 157 | - Should highlight constraints 158 | 159 | Next Steps: 160 | min_items: 1 161 | max_items: 5 162 | rules: 163 | - Must be numbered list 164 | - Must be actionable items 165 | 166 | Completion Notes: 167 | required_if: "status == completed" 168 | rules: 169 | - Must summarize achievements 170 | - Must list any follow-up tasks 171 | ``` 172 | 173 | #### Session Template 174 | ```yaml 175 | required_sections: 176 | Focus: 177 | min_length: 10 178 | max_length: 100 179 | rules: 180 | - Must state primary objective 181 | - Must be specific to session 182 | 183 | Context: 184 | required_fields: 185 | - Active Task 186 | - Branch 187 | rules: 188 | - Must reference valid tasks 189 | - Must include current state 190 | 191 | Progress: 192 | subsections: 193 | Completed: 194 | min_items: 0 195 | rules: 196 | - Must use bullet points 197 | - Must be verifiable actions 198 | In Progress: 199 | min_items: 0 200 | rules: 201 | - Must use checkbox format 202 | - Must be current work items 203 | 204 | optional_sections: 205 | Decisions: 206 | rules: 207 | - Must be numbered 208 | - Must include context 209 | - Must state rationale 210 | 211 | Dependencies: 212 | rules: 213 | - Must use checkbox format 214 | - Must include impact 215 | - Must list resolution steps 216 | 217 | Next Steps: 218 | min_items: 1 219 | rules: 220 | - Must be numbered 221 | - Must be actionable 222 | ``` 223 | 224 | #### Decision Template 225 | ```yaml 226 | required_sections: 227 | Context: 228 | min_length: 50 229 | rules: 230 | - Must explain motivation 231 | - Must provide background 232 | 233 | Problem Statement: 234 | min_length: 20 235 | rules: 236 | - Must be clear and specific 237 | - Must identify key issues 238 | 239 | Options Considered: 240 | min_items: 2 241 | rules: 242 | - Must list pros and cons 243 | - Must be viable options 244 | - Must be comparable 245 | 246 | Decision: 247 | required_if: "status in [accepted, rejected]" 248 | rules: 249 | - Must state clear choice 250 | - Must reference chosen option 251 | 252 | Rationale: 253 | required_if: "status in [accepted, rejected]" 254 | rules: 255 | - Must justify decision 256 | - Must address key factors 257 | 258 | optional_sections: 259 | Implementation: 260 | required_if: "status == accepted" 261 | rules: 262 | - Must use checkbox format 263 | - Must be actionable steps 264 | 265 | Consequences: 266 | required_if: "status == accepted" 267 | subsections: 268 | Positive: 269 | min_items: 1 270 | rules: 271 | - Must use bullet points 272 | Negative: 273 | min_items: 1 274 | rules: 275 | - Must use bullet points 276 | ``` 277 | 278 | ### Content Rules 279 | 280 | 1. General Format Rules: 281 | - Use consistent markdown formatting 282 | - Maintain section hierarchy 283 | - Use appropriate list formats 284 | - Keep content concise and clear 285 | 286 | 2. Writing Style: 287 | - Use active voice 288 | - Be specific and measurable 289 | - Use consistent terminology 290 | - Maintain professional tone 291 | 292 | 3. References: 293 | - Use correct ID formats 294 | - Link to existing documents 295 | - Maintain reference integrity 296 | - Update references when needed 297 | 298 | 4. Updates: 299 | - Preserve document history 300 | - Mark completed items 301 | - Update status correctly 302 | - Maintain timestamps 303 | 304 | ### Implementation Notes 305 | 306 | 1. Section Validation: 307 | ```python 308 | def validate_section(section, rules): 309 | # Check required fields 310 | for field in rules.required_fields: 311 | if field not in section: 312 | raise Error(f"Missing required field: {field}") 313 | 314 | # Check content rules 315 | if len(section) < rules.min_length: 316 | raise Error(f"Section too short: {len(section)}") 317 | 318 | # Check list items 319 | if rules.min_items and len(section.items) < rules.min_items: 320 | raise Error(f"Not enough items: {len(section.items)}") 321 | ``` 322 | 323 | 2. Content Validation: 324 | ```python 325 | def validate_content(content, template_type): 326 | # Load template rules 327 | rules = load_rules(template_type) 328 | 329 | # Check required sections 330 | for section in rules.required_sections: 331 | if section not in content: 332 | raise Error(f"Missing section: {section}") 333 | 334 | validate_section(content[section], rules[section]) 335 | 336 | # Check conditional sections 337 | for section, condition in rules.conditional_sections: 338 | if eval(condition) and section not in content: 339 | raise Error(f"Required section missing: {section}") 340 | ``` 341 | 342 | 3. Error Messages: 343 | ``` 344 | Error: Section '[name]' validation failed 345 | - Required field '[field]' is missing 346 | - Content length ([length]) below minimum ([min]) 347 | - Not enough items ([count]) in list ([min] required) 348 | - Invalid format in item [item]: [details] 349 | ``` 350 | 351 | ## Implementation Notes 352 | 353 | ### Front Matter Parsing 354 | ```markdown 355 | --- 356 | type: [document_type] 357 | other_fields: values 358 | --- 359 | ``` 360 | 361 | 1. Extract content between `---` markers 362 | 2. Parse as YAML 363 | 3. Validate required fields 364 | 4. Validate field values 365 | 5. Check relationships 366 | 6. Verify dates and times 367 | 368 | ### Error Handling 369 | 1. Missing required field: 370 | ``` 371 | Error: Required field '[field]' is missing 372 | ``` 373 | 374 | 2. Invalid value: 375 | ``` 376 | Error: Field '[field]' has invalid value '[value]' 377 | Valid values are: [valid_values] 378 | ``` 379 | 380 | 3. Invalid format: 381 | ``` 382 | Error: Field '[field]' does not match required format 383 | Expected: [format] 384 | Found: [value] 385 | ``` 386 | 387 | 4. Invalid relationship: 388 | ``` 389 | Error: Invalid reference in field '[field]' 390 | Referenced [type] '[id]' does not exist 391 | ``` 392 | -------------------------------------------------------------------------------- /COMMANDS.json: -------------------------------------------------------------------------------- 1 | { 2 | "Framework": "Aegis Framework: Complete Reference", 3 | "CriticalRules": [ 4 | "Use .context/ (leading dot), never context/", 5 | "Use mv for task transitions (never cp)", 6 | "Update front matter after moves", 7 | "Assume dirs exist (no mkdir -p)", 8 | "No duplicate task files", 9 | "ALWAYS use current year for all timestamps", 10 | "ALWAYS use EXACT current time from metadata (hours:minutes:seconds)" 11 | ], 12 | "CoreCommands": { 13 | "/aegis plan": [ 14 | "Create/update .context/plan/planning_document.md", 15 | "Generate tasks in .context/tasks/planned/", 16 | "Maintain task dependencies" 17 | ], 18 | "/aegis start": [ 19 | "Begin dev session", 20 | "Load project context", 21 | "Set initial focus", 22 | "Validate task states", 23 | "Apply self-improvement recommendations" 24 | ], 25 | "/aegis save": [ 26 | "Preserve session progress", 27 | "Log in .context/sessions/", 28 | "Record decisions in .context/decisions/", 29 | "Update task progress", 30 | "Perform self-improvement analysis", 31 | "Generate insights and recommendations" 32 | ], 33 | "/aegis status": [ 34 | "Show current project state", 35 | "List active tasks", 36 | "Show recent changes + current focus", 37 | "Display key self-improvement insights" 38 | ], 39 | "/aegis task": [ 40 | "Manage tasks/transitions with mv", 41 | "Update task metadata", 42 | "Track progress", 43 | "Apply pattern-based recommendations" 44 | ], 45 | "/aegis context": [ 46 | "Quick context refresh", 47 | "Show active tasks, changes, decisions", 48 | "Highlight relevant self-improvement insights" 49 | ], 50 | "/aegis help": [ 51 | "Show command help/usage" 52 | ] 53 | }, 54 | "TaskStateFlow": [ 55 | ".context/tasks/planned/ → .context/tasks/active/ (start work)", 56 | ".context/tasks/active/ → .context/tasks/completed/ (done)", 57 | ".context/tasks/active/ → .context/tasks/hold/ (blocked)", 58 | ".context/tasks/hold/ → .context/tasks/active/ (unblocked)" 59 | ], 60 | "FrameworkStructure": [ 61 | ".context/ (root, with dot)", 62 | "AI_INSTRUCTIONS.md (framework instructions)", 63 | "ai/operations/ (command patterns)", 64 | "memory/ (core/project/session memory)", 65 | "memory/project/self_improvement.json (self-improvement data)", 66 | "memory/SELF_IMPROVEMENT.md (self-improvement documentation)", 67 | "templates/ (document templates)", 68 | "tasks/ (planned, active, hold, completed)", 69 | "sessions/ (progress logs)", 70 | "decisions/ (key decisions)" 71 | ], 72 | "TaskOperations": { 73 | "CreateTask": [ 74 | "cp .context/templates/tasks/TEMPLATE.md → .context/tasks/planned/TASK-XXX.md", 75 | "Then update content + front matter" 76 | ], 77 | "MoveTask": [ 78 | "mv .context/tasks/planned/TASK-XXX.md → .context/tasks/active/TASK-XXX.md (correct)", 79 | "Never cp tasks" 80 | ], 81 | "UpdateFrontMatter": [ 82 | "Update 'status' to match target dir", 83 | "Update 'updated' with YYYY-MM-DDTHH:MM:SS (current year, EXACT current time)" 84 | ], 85 | "TimestampGeneration": [ 86 | "ALWAYS use current year", 87 | "ALWAYS use EXACT current time from metadata (hours:minutes:seconds)", 88 | "NEVER use default or placeholder times", 89 | "Front matter: YYYY-MM-DDTHH:MM:SS (ISO 8601 with T separator)", 90 | "Example: 2025-03-05T12:41:19", 91 | "Include timezone when available" 92 | ] 93 | }, 94 | "TaskTemplate": { 95 | "FrontMatter": [ 96 | "title, type=task", 97 | "status=[planned|active|completed|hold]", 98 | "created=YYYY-MM-DDTHH:MM:SS", 99 | "updated=YYYY-MM-DDTHH:MM:SS", 100 | "id=TASK-XXX", 101 | "priority=[high|medium|low]", 102 | "memory_types=[procedural|semantic|episodic]", 103 | "dependencies, tags" 104 | ] 105 | }, 106 | "RequiredTaskSections": [ 107 | "Description", 108 | "Objectives", 109 | "Steps", 110 | "Progress", 111 | "Dependencies", 112 | "Notes", 113 | "Next Steps" 114 | ], 115 | "SessionSections": [ 116 | "Focus", 117 | "Context", 118 | "Progress", 119 | "Decisions", 120 | "Self-Improvement", 121 | "Dependencies", 122 | "Next Steps", 123 | "Notes" 124 | ], 125 | "SelfImprovementFeatures": { 126 | "DataStorage": [ 127 | "Single self_improvement.json file in memory/project/", 128 | "Self-Improvement section in session documents", 129 | "Documentation in memory/SELF_IMPROVEMENT.md" 130 | ], 131 | "AnalysisCategories": [ 132 | "Process insights", 133 | "Efficiency insights", 134 | "Pattern insights", 135 | "Blocker insights" 136 | ], 137 | "MetricsTracked": [ 138 | "Time allocation across activities", 139 | "Task completion rates and times", 140 | "Decision metrics" 141 | ], 142 | "RecommendationTypes": [ 143 | "Process improvements", 144 | "Efficiency enhancements", 145 | "Risk mitigations" 146 | ], 147 | "PriorityLevels": [ 148 | "High priority", 149 | "Medium priority", 150 | "Low priority" 151 | ] 152 | }, 153 | "CommonMistakes": [ 154 | "Creating context/ without dot", 155 | "Using cp instead of mv", 156 | "mkdir -p for existing dirs", 157 | "Skipping template for new tasks", 158 | "Modifying template structure", 159 | "Missing required fields", 160 | "Duplicate tasks", 161 | "Using incorrect year in timestamps", 162 | "Using default/placeholder times instead of exact current time", 163 | "Omitting Self-Improvement section in sessions" 164 | ], 165 | "ValidationChecklist": [ 166 | "Paths start with .context/ (dot)", 167 | "Use mv (not cp) for transitions", 168 | "No mkdir -p", 169 | "Update front matter after moves", 170 | "Front Matter Timestamps: YYYY-MM-DDTHH:MM:SS (current year, with T separator, EXACT current time)", 171 | "File Names: YYYY-MM-DD", 172 | "Always use current year for all timestamps", 173 | "Always use EXACT current time from metadata for timestamps", 174 | "Include Self-Improvement section in session documents" 175 | ], 176 | "DirectoryDocumentation": [ 177 | "Each directory has a README.md", 178 | "README.md forms a hierarchical doc system", 179 | "Root README.md: framework overview", 180 | "Component README.md: deeper documentation", 181 | "Subdirectory README.md: usage instructions" 182 | ], 183 | "InstructionPrioritization": [ 184 | "1. User Instructions", 185 | "2. Framework Documentation", 186 | "3. Template Usage", 187 | "4. Framework Defaults (lowest)" 188 | ], 189 | "FrameworkValidation": [ 190 | "Check .context structure exists", 191 | "Check required files present", 192 | "Validate file permissions", 193 | "Verify README.md files exist", 194 | "Follow README.md hierarchy", 195 | "Validate self_improvement.json format" 196 | ] 197 | } 198 | -------------------------------------------------------------------------------- /COMMANDS.md: -------------------------------------------------------------------------------- 1 | # Aegis Framework: Complete Reference 2 | 3 | ## ⚠️ CRITICAL RULES ⚠️ 4 | 5 | 1. **ALWAYS use `.context/` with leading dot** (NEVER `context/` without dot) 6 | 2. **ALWAYS use `mv` for task transitions** (NEVER `cp`) 7 | 3. **ALWAYS update front matter after moves** 8 | 4. **ALWAYS assume directories exist** (NO `mkdir -p` needed) 9 | 5. **NEVER create duplicate task files** 10 | 6. **ALWAYS use current year for all timestamps** 11 | 7. **ALWAYS use EXACT current time from metadata for timestamps** 12 | 13 | ## Core Commands 14 | 15 | ### `/aegis plan` 16 | Create/update project planning document and tasks 17 | - Creates/updates `.context/plan/planning_document.md` 18 | - Generates tasks in `.context/tasks/planned/` 19 | - Maintains task dependencies 20 | 21 | ### `/aegis start` 22 | Begin development session 23 | - Loads project context 24 | - Sets initial focus 25 | - Validates task states 26 | 27 | ### `/aegis save` 28 | Preserve session progress 29 | - Creates session log in `.context/sessions/` 30 | - Records decisions in `.context/decisions/` 31 | - Updates task progress 32 | 33 | ### `/aegis status` 34 | Show current project state 35 | - Shows active tasks 36 | - Lists recent changes 37 | - Displays current focus 38 | 39 | ### `/aegis task` 40 | Manage tasks and transitions 41 | - Move between states using `mv` (NEVER `cp`) 42 | - Update task metadata 43 | - Track progress 44 | 45 | ### `/aegis context` 46 | Quick context refresh 47 | - Shows active tasks 48 | - Lists recent changes 49 | - Displays decisions 50 | 51 | ### `/aegis help` 52 | Show command help and usage 53 | 54 | ## Task State Flow 55 | ``` 56 | .context/tasks/planned/ → .context/tasks/active/ (Starting work) 57 | .context/tasks/active/ → .context/tasks/completed/ (Work done) 58 | .context/tasks/active/ → .context/tasks/hold/ (Work blocked) 59 | .context/tasks/hold/ → .context/tasks/active/ (Block resolved) 60 | ``` 61 | 62 | ## Framework Structure 63 | ``` 64 | .context/ # ROOT DIRECTORY (with dot) 65 | ├── AI_INSTRUCTIONS.md # Framework instructions 66 | ├── ai/operations/ # Command patterns 67 | ├── memory/ # Memory system 68 | │ ├── core/ # Framework memory 69 | │ ├── project/ # Project memory 70 | │ └── session/ # Session state 71 | ├── templates/ # Document templates 72 | │ ├── tasks/ # Task templates 73 | │ ├── sessions/ # Session templates 74 | │ └── decisions/ # Decision templates 75 | ├── tasks/ # Task management 76 | │ ├── active/ # Current work 77 | │ ├── planned/ # Future work 78 | │ ├── hold/ # Blocked 79 | │ └── completed/ # Done 80 | ├── sessions/ # Progress logs 81 | └── decisions/ # Key decisions 82 | ``` 83 | 84 | ## Task Operations 85 | 86 | ### Creating Tasks 87 | ```bash 88 | # CORRECT: Create new task from template 89 | cp .context/templates/tasks/TEMPLATE.md .context/tasks/planned/TASK-XXX.md 90 | 91 | # Then update content and front matter 92 | ``` 93 | 94 | ### Moving Tasks 95 | ```bash 96 | # ✅ CORRECT: Move task to active 97 | mv .context/tasks/planned/TASK-XXX.md .context/tasks/active/TASK-XXX.md 98 | 99 | # ❌ INCORRECT: Never copy tasks 100 | cp .context/tasks/planned/TASK-XXX.md .context/tasks/active/TASK-XXX.md 101 | ``` 102 | 103 | ### Updating Front Matter 104 | Always update these fields after moving: 105 | ```yaml 106 | --- 107 | status: [new-status] # Match target directory 108 | updated: YYYY-MM-DDTHH:MM:SS # Current timestamp with T separator 109 | --- 110 | ``` 111 | 112 | ### Timestamp Generation 113 | When generating timestamps: 114 | - ALWAYS use the current year (2025) 115 | - ALWAYS use the EXACT current time from metadata (hours:minutes:seconds) 116 | - NEVER use default or placeholder times 117 | - Front matter requires full ISO 8601 format with T separator 118 | - Example: `2025-03-05T12:41:19` (using exact current time) 119 | - Include timezone offset when available 120 | 121 | ## Task Template 122 | ```yaml 123 | --- 124 | title: [Task Title] 125 | type: task 126 | status: [planned|active|completed|hold] 127 | created: YYYY-MM-DDTHH:MM:SS 128 | updated: YYYY-MM-DDTHH:MM:SS 129 | id: TASK-XXX 130 | priority: [high|medium|low] 131 | memory_types: [procedural|semantic|episodic] 132 | dependencies: [] 133 | tags: [] 134 | --- 135 | ``` 136 | 137 | ## Required Task Sections 138 | - Description 139 | - Objectives 140 | - Steps 141 | - Progress 142 | - Dependencies 143 | - Notes 144 | - Next Steps 145 | 146 | ## Common Mistakes to Avoid 147 | 1. ❌ Creating a `context/` directory (without leading dot) 148 | 2. ❌ Using `cp` instead of `mv` for task transitions 149 | 3. ❌ Using `mkdir -p` for existing directories 150 | 4. ❌ Creating tasks without using template 151 | 5. ❌ Modifying template structure 152 | 6. ❌ Skipping required fields 153 | 7. ❌ Creating duplicate tasks 154 | 155 | ## Validation Checklist 156 | Before executing any command: 157 | 1. Verify path starts with `.context/` (with dot) 158 | 2. Use `mv` (not `cp`) for task transitions 159 | 3. Skip `mkdir -p` commands - directories exist 160 | 4. Update front matter after task moves 161 | 5. Use correct timestamp formats: 162 | - Front Matter: `YYYY-MM-DDTHH:MM:SS` 163 | - File Names: `YYYY-MM-DD` 164 | 165 | ## Directory Documentation 166 | 1. Every directory contains a README.md that MUST be consulted first 167 | 2. README.md files form a hierarchical documentation system: 168 | - Root README.md: Framework overview 169 | - Component README.md: Component documentation 170 | - Subdirectory README.md: Specific usage instructions 171 | 172 | ## Instruction Prioritization 173 | When working with the framework, follow this priority order: 174 | 1. User Instructions (highest priority) 175 | 2. Framework Documentation 176 | 3. Template Usage 177 | 4. Framework Defaults (lowest priority) 178 | 179 | ## Framework Validation 180 | Before executing any command: 181 | 1. Verify `.context` directory structure exists 182 | 2. Check all required files are present 183 | 3. Validate file permissions 184 | 4. Verify README.md files exist and are accessible 185 | 5. Follow README.md hierarchy for operations 186 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 BuildSomethingAI 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Welcome to Aegis 2 | 3 | > An AI-powered framework for managing complex software projects. 4 | 5 | ## Watch the Quick Start Video: 6 | [![Watch the video](https://img.youtube.com/vi/1BA5jCPous4/hqdefault.jpg)](https://www.youtube.com/watch?v=1BA5jCPous4) 7 | 8 | 9 | ## What is Aegis? 10 | 11 | Aegis is a powerful framework that combines AI capabilities with structured project management to help teams build better software. It provides: 12 | 13 | - 🤖 AI-assisted project planning and execution 14 | - 📋 Structured task management 15 | - 🧠 Intelligent memory system 16 | - 🔄 State tracking and validation 17 | - 📝 Comprehensive documentation 18 | 19 | ## Collaborative Philosophy 20 | 21 | Aegis is built on a collaborative philosophy where humans and AI work together with a shared understanding of principles and practices. This is reflected in our documentation approach: 22 | 23 | - **Best Practices Documents**: Serve a dual purpose - they guide Aegis's behavior and provide reference for human collaboration 24 | - **Shared Understanding**: The framework creates an environment where humans and AI operate from the same playbook 25 | - **Transparent Operation**: Documentation explains not just what to do, but why and how Aegis approaches different aspects of project management 26 | 27 | For more details on this collaborative approach, see [Understanding Best Practices in the Aegis Framework](https://buildsomething.ai/aegis/user-guide/best-practices-purpose/). 28 | 29 | ## Quick Links 30 | 31 | - [Quick Start Guide](https://buildsomething.ai/aegis/quick-start/installation/) 32 | - [User Guide](https://buildsomething.ai/aegis/user-guide/concepts/framework-structure/) 33 | - [Developer Guide](https://buildsomething.ai/aegis/developer-guide/architecture/directory-structure/) 34 | - [Tutorials](https://buildsomething.ai/aegis/tutorials/getting-started/) 35 | - [Reference](https://buildsomething.ai/aegis/reference/templates/task-templates/) 36 | 37 | ## Key Features 38 | 39 | ### AI-Powered Planning 40 | Let AI help you break down complex projects into manageable tasks. 41 | 42 | ### Smart Task Management 43 | Track progress, manage dependencies, and ensure nothing falls through the cracks. 44 | 45 | ### Memory System 46 | Maintain context across sessions and team members with an intelligent memory system. 47 | 48 | ### Validation & State Tracking 49 | Ensure consistency and correctness with built-in validation rules. 50 | 51 | ## Getting Started 52 | 53 | 1. [Install Aegis](https://buildsomething.ai/aegis/quick-start/installation/) 54 | 2. [Create Your First Project](https://buildsomething.ai/aegis/quick-start/first-project/) 55 | 3. [Learn Basic Commands](https://buildsomething.ai/aegis/quick-start/basic-commands/) 56 | 4. [Explore Common Workflows](https://buildsomething.ai/aegis/quick-start/common-workflows/) 57 | 58 | ## Support & Community 59 | 60 | - [GitHub Repository](https://github.com/BuildSomethingAI/aegis-framework) 61 | - [Documentation](https://buildsomething.ai/aegis) 62 | - [Issue Tracker](https://github.com/BuildSomethingAI/aegis-framework/issues) 63 | --------------------------------------------------------------------------------