OpenSpec Integration > Reference: OpenSpec delta specs use ADDED/MODIFIED/REMOVED sections to describe changes to existing system behavior. See .loki/openspec/delta-context.json for the parsed delta context injected into your prompt. --- ## When This Module Applies - Your prompt contains an OPENSPEC DELTA CONTEXT section - The project has .loki/openspec/delta-context.json - The session was started with --openspec flag - Tasks in .loki/queue/pending.json have metadata.openspec_group If none of the above are true, do not load this module. --- ## Delta-Aware Development Rules ### ADDED Requirements New behavior that does not exist in the codebase yet. 1. Create NEW files and functions following existing codebase patterns 2. Do NOT modify existing code unless the new feature integrates with it 3. Write tests for every scenario (GIVEN/WHEN/THEN from the delta spec) 4. Reference: delta-context.json → deltas.<domain>.added[] `` # Mental model for ADDED Read scenario -> Write test -> Implement -> Verify test passes ` ### MODIFIED Requirements Existing behavior that is changing. This is the most common delta type in brownfield work. 1. Find the EXISTING code that implements this requirement 2. Modify IN PLACE -- do NOT create new files for modified behavior 3. Check the (Previously: ...) annotation to understand what changed 4. Update existing tests to match the new behavior 5. Reference: delta-context.json → deltas.<domain>.modified[] (each entry has a "previously" field) ` # Mental model for MODIFIED Read "(Previously: ...)" -> Find existing code -> Update code -> Update tests -> Verify ` **Common mistake:** Treating MODIFIED as ADDED and creating new files. Always search the codebase first for the existing implementation. ### REMOVED Requirements Behavior that is being deprecated or deleted. 1. Find and remove or deprecate the code implementing this requirement 2. Check the (Deprecated: ...) annotation for the reason 3. Remove associated tests 4. Ensure no orphaned imports or dead code remains 5. Reference: delta-context.json → deltas.<domain>.removed[] (each entry has a "reason" field) ` # Mental model for REMOVED Read "(Deprecated: ...)" -> Find existing code -> Remove code -> Remove tests -> Verify no dead refs ` --- ## Task Execution Tasks are generated from OpenSpec tasks.md and loaded into .loki/queue/pending.json. - Each task has metadata.openspec_group indicating its group name (string, from ## N. Group Name headings in tasks.md) - Execute tasks in group order (group 1 before group 2, etc.) - Within a group, tasks can run in parallel if they touch different files - Mark tasks complete in the queue when done `json { "id": "openspec-1.3", "title": "Implement session timeout change", "description": "[OpenSpec] Authentication: Implement session timeout change", "priority": "medium", "status": "pending", "source": "openspec", "metadata": { "openspec_source": "tasks.md", "openspec_group": "Authentication" } } ` --- ## Scenario Verification After implementing a requirement, verify its scenarios. 1. Each scenario has GIVEN (precondition), WHEN (action), THEN (expected outcome) 2. Write test cases that map 1:1 to scenarios 3. Use the scenario name as the test name for traceability 4. Verification results are tracked in .loki/openspec/verification-map.json `python # Scenario: "Idle timeout" -> test name matches scenario def test_idle_timeout(): # GIVEN an authenticated session session = create_authenticated_session() # WHEN 15 minutes pass without activity advance_time(minutes=15) # THEN the session is invalidated assert session.is_expired() ` The verification map tracks each scenario with "verified": false initially. After tests pass, the orchestrator updates verified status. `json { "scenarios": [ { "domain": "auth", "requirement": "Session Expiration", "scenario": "Idle timeout", "given": "an authenticated session", "when": "15 minutes pass without activity", "then": "the session is invalidated", "verified": false } ] } ` --- ## Source Mapping .loki/openspec/source-map.json maps each task ID to its origin in tasks.md. | Field | Purpose | |-------|---------| | file | Source file (always tasks.md) | | line | Line number in tasks.md (1-indexed) | | group | Task group name from ## N. Group Name heading | `json { "openspec-1.1": { "file": "tasks.md", "line": 3, "group": "Authentication" }, "openspec-1.2": { "file": "tasks.md", "line": 4, "group": "Authentication" }, "openspec-2.1": { "file": "tasks.md", "line": 7, "group": "Dashboard" } } `` Use this to trace implementation decisions back to the specification. --- ## Complexity Levels The adapter classifies complexity based on task count, spec file count, and design.md presence. Checked in order (first match wins): | Level | Cond