@undeemed/get-shit-done-codex 1.6.12 → 1.20.3

package/get-shit-done/templates/codebase/structure.md

@@ -15,7 +15,7 @@ Template for `.planning/codebase/STRUCTURE.md` - captures physical file organiza
 
 ## Directory Layout
 
-[ASCII tree of top-level directories with purpose]
+[ASCII box-drawing tree of top-level directories with purpose - use ├── └── │ characters for tree structure only]
 
 ```
 [project-root]/
@@ -146,7 +146,7 @@ get-shit-done/
 - Subdirectories: None
 
 **commands/gsd/**
-- Purpose: Slash command definitions for Claude Code
+- Purpose: Slash command definitions for Codex CLI
 - Contains: *.md files (one per command)
 - Key files: new-project.md, plan-phase.md, execute-plan.md
 - Subdirectories: None (flat structure)
@@ -186,14 +186,14 @@ get-shit-done/
 
 **Documentation:**
 - `README.md` - User-facing installation and usage guide
-- `CLAUDE.md` - Instructions for Claude Code when working in this repo
+- `CODEX.md` - Instructions for Codex CLI when working in this repo
 
 ## Naming Conventions
 
 **Files:**
 - kebab-case.md: Markdown documents
 - kebab-case.js: JavaScript source files
-- UPPERCASE.md: Important project files (README, CLAUDE, CHANGELOG)
+- UPPERCASE.md: Important project files (README, CODEX, CHANGELOG)
 
 **Directories:**
 - kebab-case: All directories
@@ -216,7 +216,7 @@ get-shit-done/
 
 **New Workflow:**
 - Implementation: `get-shit-done/workflows/{name}.md`
-- Usage: Reference from command with `@~/.claude/get-shit-done/workflows/{name}.md`
+- Usage: Reference from command with `@~/.codex/get-shit-done/workflows/{name}.md`
 
 **New Reference Document:**
 - Implementation: `get-shit-done/references/{name}.md`
@@ -229,12 +229,12 @@ get-shit-done/
 ## Special Directories
 
 **get-shit-done/**
-- Purpose: Resources installed to ~/.claude/
+- Purpose: Resources installed to ~/.codex/
 - Source: Copied by bin/install.js during installation
 - Committed: Yes (source of truth)
 
 **commands/**
-- Purpose: Slash commands installed to ~/.claude/commands/
+- Purpose: Slash commands installed to ~/.codex/commands/
 - Source: Copied by bin/install.js during installation
 - Committed: Yes (source of truth)
 
@@ -247,7 +247,7 @@ get-shit-done/
 
 <guidelines>
 **What belongs in STRUCTURE.md:**
-- Directory layout (ASCII tree)
+- Directory layout (ASCII box-drawing tree for structure visualization)
 - Purpose of each directory
 - Key file locations (entry points, configs, core logic)
 - Naming conventions
@@ -267,7 +267,7 @@ get-shit-done/
 - Locate entry points, configs, and main logic areas
 - Keep directory tree concise (max 2-3 levels)
 
-**ASCII tree format:**
+**Tree format (ASCII box-drawing characters for structure only):**
 ```
 root/
 ├── dir1/           # Purpose

package/get-shit-done/templates/config.json

@@ -1,6 +1,16 @@
 {
   "mode": "interactive",
   "depth": "standard",
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "auto_advance": false
+  },
+  "planning": {
+    "commit_docs": true,
+    "search_gitignored": false
+  },
   "parallelization": {
     "enabled": true,
     "plan_level": true,

package/get-shit-done/templates/context.md

@@ -1,6 +1,6 @@
 # Phase Context Template
 
-Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementation decisions for a phase.
+Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implementation decisions for a phase.
 
 **Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
 
@@ -40,8 +40,8 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
 ### [Area 3 that was discussed]
 - [Specific decision made]
 
-### Claude's Discretion
-[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation]
+### Codex's Discretion
+[Areas where user explicitly said "you decide" — Codex has flexibility here during planning/implementation]
 
 </decisions>
 
@@ -103,7 +103,7 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 - Friendly illustration + "Follow people to see posts here"
 - Suggest 3-5 accounts to follow based on interests
 
-### Claude's Discretion
+### Codex's Discretion
 - Loading skeleton design
 - Exact spacing and typography
 - Error state handling
@@ -165,7 +165,7 @@ CLI command to backup database to local file or S3. Supports full and incrementa
 - --no-retry flag to fail fast
 - Partial backups are deleted on failure (no corrupt files)
 
-### Claude's Discretion
+### Codex's Discretion
 - Exact progress bar implementation
 - Compression algorithm choice
 - Temp file handling
@@ -227,7 +227,7 @@ Organize existing photo library into structured folders. Handle duplicates and a
 - Preserve original filename as suffix for searchability
 - Handle name collisions with incrementing suffix
 
-### Claude's Discretion
+### Codex's Discretion
 - Exact clustering algorithm
 - How to handle photos with no EXIF data
 - Folder emoji usage
@@ -275,16 +275,8 @@ The output should answer: "What does the researcher need to investigate? What ch
 - "Fast and responsive"
 - "Easy to use"
 
-**Sections explained:**
-
-- **Domain** — The scope anchor. Copied/derived from ROADMAP.md. Fixed boundary.
-- **Decisions** — Organized by areas discussed (NOT predefined categories). Section headers come from the actual discussion — "Layout style", "Flag design", "Grouping criteria", etc.
-- **Claude's Discretion** — Explicit acknowledgment of what Claude can decide during implementation.
-- **Specifics** — Product references, examples, "like X but..." statements.
-- **Deferred** — Ideas captured but explicitly out of scope. Prevents scope creep while preserving good ideas.
-
 **After creation:**
-- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-CONTEXT.md`
 - `gsd-phase-researcher` uses decisions to focus investigation
 - `gsd-planner` uses decisions + research to create executable tasks
 - Downstream agents should NOT need to ask the user again about captured decisions

package/get-shit-done/templates/continue-here.md

@@ -71,7 +71,7 @@ Required YAML frontmatter:
 </yaml_fields>
 
 <guidelines>
-- Be specific enough that a fresh Claude instance understands immediately
+- Be specific enough that a fresh Codex instance understands immediately
 - Include WHY decisions were made, not just what
 - The `<next_action>` should be actionable without reading anything else
 - This file gets DELETED after resume - it's not permanent storage

package/get-shit-done/templates/phase-prompt.md

@@ -20,7 +20,7 @@ wave: N                     # Execution wave (1, 2, 3...). Pre-computed at plan
 depends_on: []              # Plan IDs this plan requires (e.g., ["01-01"]).
 files_modified: []          # Files this plan modifies.
 autonomous: true            # false if plan has checkpoints requiring user interaction
-user_setup: []              # Human-required setup Claude cannot automate (see below)
+user_setup: []              # Human-required setup Codex cannot automate (see below)
 
 # Goal-backward verification (derived during planning, verified after execution)
 must_haves:
@@ -37,10 +37,10 @@ Output: [What artifacts will be created]
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/workflows/execute-plan.md
-@~/.claude/get-shit-done/templates/summary.md
+@~/.codex/get-shit-done/workflows/execute-plan.md
+@~/.codex/get-shit-done/templates/summary.md
 [If plan contains checkpoint tasks (type="checkpoint:*"), add:]
-@~/.claude/get-shit-done/references/checkpoints.md
+@~/.codex/get-shit-done/references/checkpoints.md
 </execution_context>
 
 <context>
@@ -75,33 +75,23 @@ Output: [What artifacts will be created]
   <done>[Acceptance criteria]</done>
 </task>
 
+<!-- For checkpoint task examples and patterns, see @~/.codex/get-shit-done/references/checkpoints.md -->
+<!-- Key rule: Codex starts dev server BEFORE human-verify checkpoints. User only visits URLs. -->
+
 <task type="checkpoint:decision" gate="blocking">
   <decision>[What needs deciding]</decision>
   <context>[Why this decision matters]</context>
   <options>
-    <option id="option-a">
-      <name>[Option name]</name>
-      <pros>[Benefits and advantages]</pros>
-      <cons>[Tradeoffs and limitations]</cons>
-    </option>
-    <option id="option-b">
-      <name>[Option name]</name>
-      <pros>[Benefits and advantages]</pros>
-      <cons>[Tradeoffs and limitations]</cons>
-    </option>
+    <option id="option-a"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
+    <option id="option-b"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
   </options>
-  <resume-signal>[How to indicate choice - "Select: option-a or option-b"]</resume-signal>
+  <resume-signal>Select: option-a or option-b</resume-signal>
 </task>
 
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>[What Claude just built that needs verification]</what-built>
-  <how-to-verify>
-    1. Run: [command to start dev server/app]
-    2. Visit: [URL to check]
-    3. Test: [Specific interactions]
-    4. Confirm: [Expected behaviors]
-  </how-to-verify>
-  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
+  <what-built>[What Codex built] - server running at [URL]</what-built>
+  <how-to-verify>Visit [URL] and verify: [visual checks only, NO CLI commands]</how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 
 </tasks>
@@ -278,7 +268,7 @@ TDD features get dedicated plans with `type: tdd`.
 → Yes: Create a TDD plan
 → No: Standard task in standard plan
 
-See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.
+See `~/.codex/get-shit-done/references/tdd.md` for TDD plan structure.
 
 ---
 
@@ -286,7 +276,7 @@ See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.
 
 | Type | Use For | Autonomy |
 |------|---------|----------|
-| `auto` | Everything Claude can do independently | Fully autonomous |
+| `auto` | Everything Codex can do independently | Fully autonomous |
 | `checkpoint:human-verify` | Visual/functional verification | Pauses, returns to orchestrator |
 | `checkpoint:decision` | Implementation choices | Pauses, returns to orchestrator |
 | `checkpoint:human-action` | Truly unavoidable manual steps (rare) | Pauses, returns to orchestrator |
@@ -382,9 +372,9 @@ Output: Working dashboard component.
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/workflows/execute-plan.md
-@~/.claude/get-shit-done/templates/summary.md
-@~/.claude/get-shit-done/references/checkpoints.md
+@~/.codex/get-shit-done/workflows/execute-plan.md
+@~/.codex/get-shit-done/templates/summary.md
+@~/.codex/get-shit-done/references/checkpoints.md
 </execution_context>
 
 <context>
@@ -403,15 +393,16 @@ Output: Working dashboard component.
   <done>Dashboard renders without errors</done>
 </task>
 
+<!-- Checkpoint pattern: Codex starts server, user visits URL. See checkpoints.md for full patterns. -->
+<task type="auto">
+  <name>Start dev server</name>
+  <action>Run `npm run dev` in background, wait for ready</action>
+  <verify>curl localhost:3000 returns 200</verify>
+</task>
+
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>Responsive dashboard with user and product sections</what-built>
-  <how-to-verify>
-    1. Run: npm run dev
-    2. Visit: http://localhost:3000/dashboard
-    3. Desktop: Verify two-column grid
-    4. Mobile: Verify stacked layout
-    5. Check: No layout shift, no scroll issues
-  </how-to-verify>
+  <what-built>Dashboard - server at http://localhost:3000</what-built>
+  <how-to-verify>Visit localhost:3000/dashboard. Check: desktop grid, mobile stack, no scroll issues.</how-to-verify>
   <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 </tasks>
@@ -467,7 +458,7 @@ files_modified: [...]
 
 ## Guidelines
 
-- Always use XML structure for Claude parsing
+- Always use XML structure for Codex parsing
 - Include `wave`, `depends_on`, `files_modified`, `autonomous` in every plan
 - Prefer vertical slices over horizontal layers
 - Only reference prior SUMMARYs when genuinely needed
@@ -497,16 +488,16 @@ user_setup:
       - "stripe listen --forward-to localhost:3000/api/webhooks/stripe"
 ```
 
-**The automation-first rule:** `user_setup` contains ONLY what Claude literally cannot do:
+**The automation-first rule:** `user_setup` contains ONLY what Codex literally cannot do:
 - Account creation (requires human signup)
 - Secret retrieval (requires dashboard access)
 - Dashboard configuration (requires human in browser)
 
-**NOT included:** Package installs, code changes, file creation, CLI commands Claude can run.
+**NOT included:** Package installs, code changes, file creation, CLI commands Codex can run.
 
 **Result:** Execute-plan generates `{phase}-USER-SETUP.md` with checklist for the user.
 
-See `~/.claude/get-shit-done/templates/user-setup.md` for full schema and examples
+See `~/.codex/get-shit-done/templates/user-setup.md` for full schema and examples
 
 ---
 
@@ -573,4 +564,4 @@ Task completion ≠ Goal achievement. A task "create chat component" can complet
 5. Gaps found → fix plans created → execute → re-verify
 6. All must_haves pass → phase complete
 
-See `~/.claude/get-shit-done/workflows/verify-phase.md` for verification logic.
+See `~/.codex/get-shit-done/workflows/verify-phase.md` for verification logic.

package/get-shit-done/templates/planner-subagent-prompt.md

@@ -22,14 +22,14 @@ Template for spawning gsd-planner agent. The agent contains all planning experti
 @.planning/REQUIREMENTS.md
 
 **Phase Context (if exists):**
-@.planning/phases/{phase_dir}/{phase}-CONTEXT.md
+@.planning/phases/{phase_dir}/{phase_num}-CONTEXT.md
 
 **Research (if exists):**
-@.planning/phases/{phase_dir}/{phase}-RESEARCH.md
+@.planning/phases/{phase_dir}/{phase_num}-RESEARCH.md
 
 **Gap Closure (if --gaps mode):**
-@.planning/phases/{phase_dir}/{phase}-VERIFICATION.md
-@.planning/phases/{phase_dir}/{phase}-UAT.md
+@.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+@.planning/phases/{phase_dir}/{phase_num}-UAT.md
 
 </planning_context>
 

package/get-shit-done/templates/project.md

@@ -179,6 +179,6 @@ See: .planning/PROJECT.md (updated [date])
 **Current focus:** [Current phase name]
 ```
 
-This ensures Claude reads current PROJECT.md context.
+This ensures Codex reads current PROJECT.md context.
 
 </state_reference>

package/get-shit-done/templates/research-project/ARCHITECTURE.md

@@ -177,7 +177,7 @@ src/
 <guidelines>
 
 **System Overview:**
-- Use ASCII diagrams for clarity
+- Use ASCII box-drawing diagrams for clarity (├── └── │ ─ for structure visualization only)
 - Show major components and their relationships
 - Don't over-detail — this is conceptual, not implementation
 

package/get-shit-done/templates/research.md

@@ -1,8 +1,8 @@
 # Research Template
 
-Template for `.planning/phases/XX-name/{phase}-RESEARCH.md` - comprehensive ecosystem research before planning.
+Template for `.planning/phases/XX-name/{phase_num}-RESEARCH.md` - comprehensive ecosystem research before planning.
 
-**Purpose:** Document what Claude needs to know to implement a phase well - not just "which library" but "how do experts build this."
+**Purpose:** Document what Codex needs to know to implement a phase well - not just "which library" but "how do experts build this."
 
 ---
 
@@ -15,6 +15,29 @@ Template for `.planning/phases/XX-name/{phase}-RESEARCH.md` - comprehensive ecos
 **Domain:** [primary technology/problem domain]
 **Confidence:** [HIGH/MEDIUM/LOW]
 
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+**CRITICAL:** If CONTEXT.md exists from /gsd:discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
+
+### Locked Decisions
+[Copy from CONTEXT.md `## Decisions` section - these are NON-NEGOTIABLE]
+- [Decision 1]
+- [Decision 2]
+
+### Codex's Discretion
+[Copy from CONTEXT.md - areas where researcher/planner can choose]
+- [Area 1]
+- [Area 2]
+
+### Deferred Ideas (OUT OF SCOPE)
+[Copy from CONTEXT.md - do NOT research or plan these]
+- [Deferred 1]
+- [Deferred 2]
+
+**If no CONTEXT.md exists:** Write "No user constraints - all decisions at Codex's discretion"
+</user_constraints>
+
 <research_summary>
 ## Summary
 
@@ -501,7 +524,7 @@ function useVehicleControls(rigidBodyRef) {
 
 **When to create:**
 - Before planning phases in niche/complex domains
-- When Claude's training data is likely stale or sparse
+- When Codex's training data is likely stale or sparse
 - When "how do experts do this" matters more than "which library"
 
 **Structure:**
@@ -524,6 +547,6 @@ function useVehicleControls(rigidBodyRef) {
 - Code examples can be referenced in task actions
 
 **After creation:**
-- File lives in phase directory: `.planning/phases/XX-name/{phase}-RESEARCH.md`
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-RESEARCH.md`
 - Referenced during planning workflow
 - plan-phase loads it automatically when present

package/get-shit-done/templates/state.md

@@ -120,7 +120,7 @@ Points to PROJECT.md for full context. Includes:
 - Current focus (which phase)
 - Last update date (triggers re-read if stale)
 
-Claude reads PROJECT.md directly for requirements, constraints, and decisions.
+Codex reads PROJECT.md directly for requirements, constraints, and decisions.
 
 ### Current Position
 Where we are right now:
@@ -174,33 +174,3 @@ It's a DIGEST, not an archive. If accumulated context grows too large:
 The goal is "read once, know where we are" — if it's too long, that fails.
 
 </size_constraint>
-
-<guidelines>
-
-**When created:**
-- During project initialization (after ROADMAP.md)
-- Reference PROJECT.md (extract core value and current focus)
-- Initialize empty sections
-
-**When read:**
-- Every workflow starts by reading STATE.md
-- Then read PROJECT.md for full context
-- Provides instant context restoration
-
-**When updated:**
-- After each plan execution (update position, note decisions, update issues/blockers)
-- After phase transitions (update progress bar, clear resolved blockers, refresh project reference)
-
-**Size management:**
-- Keep under 100 lines total
-- Recent decisions only in STATE.md (full log in PROJECT.md)
-- Keep only active blockers
-
-**Sections:**
-- Project Reference: Pointer to PROJECT.md with core value
-- Current Position: Where we are now (phase, plan, status)
-- Performance Metrics: Velocity tracking
-- Accumulated Context: Recent decisions, pending todos, blockers
-- Session Continuity: Resume information
-
-</guidelines>

package/get-shit-done/templates/summary-complex.md

@@ -0,0 +1,59 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category]
+tags: [searchable tech]
+requires:
+  - phase: [prior phase]
+    provides: [what that phase built]
+provides:
+  - [bullet list of what was built/delivered]
+affects: [list of phase names or keywords]
+tech-stack:
+  added: [libraries/tools]
+  patterns: [architectural/code patterns]
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+key-decisions:
+  - "Decision 1"
+patterns-established:
+  - "Pattern 1: description"
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary (Complex)
+
+**[Substantive one-liner describing outcome]**
+
+## Performance
+- **Duration:** [time]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Key outcome 1]
+- [Key outcome 2]
+
+## Task Commits
+1. **Task 1: [task name]** - `hash`
+2. **Task 2: [task name]** - `hash`
+3. **Task 3: [task name]** - `hash`
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+- `path/to/another.ts` - What it does
+
+## Decisions Made
+[Key decisions with brief rationale]
+
+## Deviations from Plan (Auto-fixed)
+[Detailed auto-fix records per GSD deviation rules]
+
+## Issues Encountered
+[Problems during planned work and resolutions]
+
+## Next Phase Readiness
+[What's ready for next phase]
+[Blockers or concerns]

package/get-shit-done/templates/summary-minimal.md

@@ -0,0 +1,41 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category]
+tags: [searchable tech]
+provides:
+  - [bullet list of what was built/delivered]
+affects: [list of phase names or keywords]
+tech-stack:
+  added: [libraries/tools]
+  patterns: [architectural/code patterns]
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+key-decisions: []
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary (Minimal)
+
+**[Substantive one-liner describing outcome]**
+
+## Performance
+- **Duration:** [time]
+- **Tasks:** [count]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Most important outcome]
+- [Second key accomplishment]
+
+## Task Commits
+1. **Task 1: [task name]** - `hash`
+2. **Task 2: [task name]** - `hash`
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+
+## Next Phase Readiness
+[Ready for next phase]

package/get-shit-done/templates/summary-standard.md

@@ -0,0 +1,48 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category]
+tags: [searchable tech]
+provides:
+  - [bullet list of what was built/delivered]
+affects: [list of phase names or keywords]
+tech-stack:
+  added: [libraries/tools]
+  patterns: [architectural/code patterns]
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+key-decisions:
+  - "Decision 1"
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary
+
+**[Substantive one-liner describing outcome]**
+
+## Performance
+- **Duration:** [time]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Key outcome 1]
+- [Key outcome 2]
+
+## Task Commits
+1. **Task 1: [task name]** - `hash`
+2. **Task 2: [task name]** - `hash`
+3. **Task 3: [task name]** - `hash`
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+- `path/to/another.ts` - What it does
+
+## Decisions & Deviations
+[Key decisions or "None - followed plan as specified"]
+[Minor deviations if any, or "None"]
+
+## Next Phase Readiness
+[What's ready for next phase]

package/get-shit-done/templates/summary.md

@@ -233,37 +233,14 @@ The one-liner should tell someone what actually shipped.
 </example>
 
 <guidelines>
-**When to create:**
-- After completing each phase plan
-- Required output from execute-plan workflow
-- Documents what actually happened vs what was planned
-
-**Frontmatter completion:**
-- MANDATORY: Complete all frontmatter fields during summary creation
-- See <frontmatter_guidance> for field purposes
-- Frontmatter enables automatic context assembly for future planning
-
-**One-liner requirements:**
-- Must be substantive (describe what shipped, not "phase complete")
-- Should tell someone what was accomplished
-- Examples: "JWT auth with refresh rotation using jose library" not "Authentication implemented"
-
-**Performance tracking:**
-- Include duration, start/end timestamps
-- Used for velocity metrics in STATE.md
-
-**Deviations section:**
-- Documents unplanned work handled via deviation rules
-- Separate from "Issues Encountered" (which is planned work problems)
-- Auto-fixed issues: What was wrong, how fixed, verification
+**Frontmatter:** MANDATORY - complete all fields. Enables automatic context assembly for future planning.
+
+**One-liner:** Must be substantive. "JWT auth with refresh rotation using jose library" not "Authentication implemented".
 
 **Decisions section:**
-- Key decisions made during execution
-- Include rationale (why this choice)
+- Key decisions made during execution with rationale
 - Extracted to STATE.md accumulated context
 - Use "None - followed plan as specified" if no deviations
 
-**After creation:**
-- STATE.md updated with position, decisions, issues
-- Next plan can reference decisions made
+**After creation:** STATE.md updated with position, decisions, issues.
 </guidelines>