planr-pipeline: Instructions file for Codex

planr-pipeline — Agent Instructions

Generated by OpenPlanr on 2026-05-03

This project follows a structured agile workflow. All planning artifacts are in .planr/.

Context-Gathering Protocol

Before implementing a task, gather the strongest available planning context. Use the artifact hierarchy when it exists; when it does not, use the explicit user request, repository ADRs/docs, and the existing code as the authoritative context. Missing .planr/ artifacts must never block an otherwise well-specified change.

Step 1: Read the Task List

• If .planr/tasks/ or .planr/quick/ exists, open the relevant task file
• Parse the frontmatter to find storyId or featureId
• Identify the target subtask (first unchecked - [ ] item)
• Read ALL subtasks to understand the full scope and dependencies
• If no task artifact exists, treat the user's explicit implementation plan as the task specification and continue to Step 3.

Step 2: Read the Parent Chain (when present)

Follow the artifact hierarchy upward — each level adds critical context:

1. User Story → .planr/stories/US-XXX-*.md

   • Read the full story (role, goal, benefit, acceptance criteria)
   • Find and read the matching Gherkin file: .planr/stories/US-XXX-gherkin.feature
   • Extract the parent featureId from frontmatter

2. Feature → .planr/features/FEAT-XXX-*.md

   • Read the full feature (overview, functional requirements, technical considerations)
   • Extract the parent epicId from frontmatter

3. Epic → .planr/epics/EPIC-XXX-*.md

   • Read the epic summary (business value, problem statement, success criteria)
   • This provides the WHY behind the work

Step 3: Read Architecture Context

• Read ALL ADRs in .planr/adrs/ — these are binding technical decisions
• Check .planr/checklists/AGILE-DEVELOPMENT-GUIDE.md for current progress

Step 4: Scan the Codebase

Before writing code, understand what exists:

1. Identify the tech stack — Read package.json, tsconfig.json, or equivalent
2. Scan the source tree — List directories under src/ (or project root)
3. Read architecture files — Look for these high-priority files:
   • Type definitions: src/models/types.ts, src/types/index.ts, or src/types.ts
   • Core services: src/services/ — understand CRUD patterns
   • Entry point: src/index.ts, src/main.ts, or src/app.ts — understand registration patterns
   • Config: src/config.ts or src/services/config-service.ts
4. Find related files — Search for files matching keywords from the task description
5. Check project rules — Read .planr/rules.md if it exists (MANDATORY rules)