codexkit 1.0.3 → 1.0.5

package/.codex/skills/compaction/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: compaction
 description: >
-  Use when context is growing large during long-running tasks and needs server-side or client-side
-  summarization to continue effectively. Covers compaction triggers, custom summarization patterns,
-  session handoff, and context preservation strategies.
-version: 1.0.0
+  Use when context is growing large during long-running tasks and needs
+  summarization to continue effectively. Covers compaction triggers, custom
+  summarization patterns, session handoff, and context preservation strategies.
+  Uses Codex-native /compact command.
+version: 2.0.0
 tags: [context, workflow]
 dependencies: []
 ---
@@ -19,7 +20,6 @@ dependencies: []
 
 - Short sessions with low context usage where no compaction is needed.
 
-
 ## Overview
 
 **Compaction = Summarization + Preservation + Continuity**
@@ -32,54 +32,53 @@ Long-running sessions accumulate context (tool outputs, code reads, exploration
 
 | Context Usage | Status      | Action                                        |
 | ------------- | ----------- | --------------------------------------------- |
-| 0-50%         | 🟢 Normal   | Work freely                                   |
-| 50-70%        | 🟡 Watch    | Start compressing completed explorations      |
-| 70-85%        | 🟠 Compact  | Actively compress and sweep stale noise       |
-| 85-95%        | 🔴 Critical | Emergency compaction, prepare session handoff |
-| 95%+          | ⛔ Limit    | Session handoff required                      |
+| 0-50%         | Normal      | Work freely                                   |
+| 50-70%        | Watch       | Start compressing completed explorations      |
+| 70-85%        | Compact     | Actively compress; write summaries to durable files |
+| 85-95%        | Critical    | Emergency compaction, prepare session handoff |
+| 95%+          | Limit       | Session handoff required                      |
 
 ### Monitoring
 
 Pay attention to these signals:
 
-- Completed phases accumulating without being compressed
+- Completed phases accumulating without being summarized
 - Repeated file reads of the same content
 - Large bash outputs from builds/tests
 - Multiple exploration rounds without synthesis
 
 ## Compaction Strategies
 
-### Strategy 1: Phase Compression (Preferred)
-
-Compress completed conversation phases into dense summaries. This is the primary DCP instrument in the installed beta.
+### Strategy 1: Codex-Native `/compact` (Preferred)
 
-
-Compress completed conversation phases into dense summaries.
+Use the built-in `/compact` command to summarize conversation history while preserving key context.
 
 ```
-WHEN: A research phase is complete and findings are clear
-DO: compress({
-  topic: "Auth Research Complete",
-  content: {
-    startString: "unique text at phase start",
-    endString: "unique text at phase end",
-    summary: "Complete technical summary of findings..."
-  }
-})
+WHEN: A research or implementation phase is complete
+DO: /compact focus on [completed phase topic]
 ```
 
-**Key principle**: Only compress CLOSED chapters. Never compress active work.
+The `/compact` command:
+- Summarizes conversation history server-side
+- Preserves key decisions and findings
+- Frees context budget for new work
+- Accepts an optional focus instruction to guide what it preserves
 
-### Strategy 2: Sweep Stale Noise
+**Key principle**: Only compact CLOSED chapters. Never compact active work.
 
-Use `/dcp sweep` after a phase is complete to remove stale/noisy content automatically.
+### Strategy 2: Manual Phase Summarization
+
+When `/compact` is too broad, manually write a dense summary to a durable file before the context is lost.
 
 ```
-WHEN: Wrong-target searches or superseded outputs are no longer needed
-DO: /dcp sweep
+WHEN: A research phase is complete and findings are clear
+DO:
+  1. Write summary to `.codex/context/worklog.md` or `.codex/memory/research/`
+  2. Record key decisions in `.codex/context/decision-log.md`
+  3. The summarized content can now be safely forgotten by the session
 ```
 
-**Key principle**: Sweep only after the relevant phase is closed. If in doubt, keep it.
+**Key principle**: Persist durable findings to repo files before they leave the context window.
 
 ### Strategy 3: Session Handoff
 
@@ -88,10 +87,10 @@ When context is too large to compact further, hand off to a new session.
 ```
 WHEN: Context > 85% and significant work remains
 DO:
-  1. Create handoff document with memory-update
-  2. Save all decisions with observation tool
-  3. Document current state and remaining work
-  4. Start new session with handoff reference
+  1. Update `.codex/context/session-context.md` with exact stop point
+  2. Update `.codex/memory/project/state.md` with durable state
+  3. Append milestone to `.codex/context/worklog.md`
+  4. Start new session with `/prompts:resume`
 ```
 
 ## Compaction Decision Tree
@@ -100,8 +99,8 @@ DO:
 Is context growing large?
 ├── NO → Continue working normally
 └── YES → What type of content is consuming space?
-    ├── Completed conversation phases → COMPRESS
-    ├── Stale/noisy closed-phase outputs → SWEEP
+    ├── Completed conversation phases → /compact
+    ├── Research findings not yet persisted → Write to memory/research/, then /compact
     └── Everything is still relevant → SESSION HANDOFF
 ```
 
@@ -150,9 +149,9 @@ Is context growing large?
 
 ### Verification
 
-- TypeScript: ✅ passing
-- Tests: ✅ 12/12 passing
-- Lint: ✅ no issues
+- TypeScript: passing
+- Tests: 12/12 passing
+- Lint: no issues
 
 ### Remaining
 
@@ -187,131 +186,83 @@ Is context growing large?
 
 - Added null check in middleware (src/auth/middleware.ts:42)
 - Added token refresh attempt before rejecting (src/auth/refresh.ts)
-- Added test for expired token scenario (src/auth/**tests**/middleware.test.ts)
+- Added test for expired token scenario (src/auth/tests/middleware.test.ts)
 
 ### Verification
 
-- Tests: ✅ all passing including new test
-- Manual: ✅ expired token now triggers refresh
+- Tests: all passing including new test
+- Manual: expired token now triggers refresh
 ```
 
 ## Session Handoff Protocol
 
 When you must hand off to a new session:
 
-### 1. Create Handoff Document
+### 1. Persist Durable Findings
 
-```typescript
-memory -
-  update({
-    file: "handoffs/YYYY-MM-DD-feature-name",
-    content: `# Session Handoff: [Feature Name]
+Write key findings and decisions to the appropriate repo files:
 
-## Context
-[Why this session started, what was the goal]
+- `.codex/context/session-context.md` — exact stop point and first next action
+- `.codex/memory/project/state.md` — durable current state and blockers
+- `.codex/context/worklog.md` — milestone summary
+- `.codex/context/decision-log.md` — architecture/workflow decisions with rationale
+- `.codex/memory/research/*.md` — deep investigation notes
 
-## Completed Work
-[What was done, files changed, decisions made]
+### 2. Create Handoff Summary
 
-## Current State
-[Where things stand right now]
+Use `/prompts:handoff` or write directly to `session-context.md`:
 
-## Remaining Work
-[What still needs to be done]
-
-## Key Decisions
-[Important choices made and why]
-
-## Files Modified
-[List of all files changed with brief description]
-
-## Gotchas
-[Things the next session should know]
-  `,
-    mode: "replace",
-  });
-```
+```markdown
+## Resume: [task-id]
 
-### 2. Save Key Observations
-
-```typescript
-observation({
-  type: "decision",
-  title: "Auth implementation approach",
-  narrative: "Chose JWT with Redis sessions because...",
-  facts: "JWT 15min expiry, Redis 24h TTL, bcrypt 12 rounds",
-  concepts: "authentication, sessions, tokens",
-  confidence: "high",
-});
+- Branch: [branch]
+- Commit: [short hash]
+- Stop point: [exact step in progress]
+- First next action: [single best next action]
+- Blockers: [none or short list]
 ```
 
 ### 3. Resume in New Session
 
-```typescript
-// In new session:
-memory - read({ file: "handoffs/YYYY-MM-DD-feature-name" });
-memory - search({ query: "auth implementation" });
-```
+```bash
+# Native Codex resume (thread-based):
+codex resume
 
-## Integration with DCP Plugin
-
-This project uses DCP-style context management for always-on context discipline:
-
-- **compress**: Phase-level conversation compression (primary DCP tool in the installed beta)
-- **/dcp sweep**: Cleanup command for stale/noisy content after a phase is complete
-- **Prunable-tools list**: Auto-injected into messages with token estimates
-- **Nudge system**: Reminders every N tool calls + critical limit warnings
-
-**Division of responsibility:**
-
-- **DCP plugin**: Context budget rules, tool guidance, prunable-tools list, nudges (always present via system prompt)
-- **Compaction workflow** (`.codex/context/session-context.md` + handoff/resume prompts): Session continuity, beads state, handoff recovery, post-compaction protocol
+# Or file-based resume via Codexkit:
+/prompts:resume [task-id]
+```
 
 ## Anti-Patterns
 
-### ❌ Premature Compaction
-
-```
-// DON'T compress a file you're about to edit
-compress({ ... })  // Loses exact line numbers you need
-edit({ ... })      // Now you can't find the right location
-```
+### Premature Compaction
 
-**Fix**: Keep raw content while actively editing. Compress AFTER the edit phase.
+Don't compact a file you're about to edit — you'll lose exact line numbers. Keep raw content while actively editing. Compact AFTER the edit phase.
 
-### ❌ Compressing Active Work
+### Compacting Active Work
 
-```
-// DON'T compress a conversation phase you might return to
-compress({ summary: "Explored auth options" })
-// Later: "Wait, which options did we consider?"
-```
+Don't compact a conversation phase you might return to. Only compact CLOSED chapters where findings are crystallized.
 
-**Fix**: Only compress CLOSED chapters where findings are crystallized.
+### Ignoring Context Growth
 
-### ❌ Ignoring Context Growth
+Don't let context grow unchecked until hitting limits. By the time you notice, emergency compaction loses information. Monitor regularly and compact at natural breakpoints.
 
-```
-// DON'T let context grow unchecked until hitting limits
-// By the time you notice, emergency compaction loses information
-```
+### Persisting Only to Session Memory
 
-**Fix**: Monitor regularly. Compress at natural breakpoints and use `/dcp sweep` after closed phases.
+Don't rely on session history for durable findings. Write important decisions and state to repo-visible files before compacting, so they survive session boundaries.
 
 ## Checklist
 
 Before compacting:
 
 - [ ] Identified what type of content is consuming context
-- [ ] Chosen appropriate strategy (compress/sweep/handoff)
+- [ ] Chosen appropriate strategy (/compact, manual summary, or handoff)
 - [ ] Verified raw content is no longer needed for active work
-- [ ] Captured all key details in the compression summary or handoff
-- [ ] Saved important decisions as observations
+- [ ] Persisted key findings to durable repo files
 - [ ] Created handoff document if switching sessions
 
 During long sessions:
 
-- [ ] Compressing completed phases at natural breakpoints
-- [ ] Sweeping stale/noisy outputs after phase completion
+- [ ] Running `/compact` at natural phase boundaries
+- [ ] Writing durable findings to context/memory files before they leave the window
 - [ ] Monitoring context usage trends
 - [ ] Planning session handoff if approaching limits

package/.codex/skills/context-management/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: context-management
-description: Unified protocol for context health and session lifecycle management using DCP tools, thresholds, handoff, and resume workflows
-version: 2.0.0
+description: Unified protocol for context health and session lifecycle management using Codex-native /compact, repo-visible memory files, thresholds, handoff, and resume workflows
+version: 3.0.0
 tags: [context, workflow, session]
 dependencies: []
 ---
 
 # Context Management
 
-> **Replaces** manual context tracking and ad-hoc session management — unified protocol for context health across a session lifecycle
+> Unified protocol for context health across a session lifecycle using Codex-native primitives.
 
 Use this skill to keep context useful from first turn to final handoff.
 
@@ -17,7 +17,7 @@ Use this skill to keep context useful from first turn to final handoff.
 - Context size is growing and you need to reduce noise without losing critical details
 - You are finishing a work phase and want to compress completed exploration/implementation
 - You are preparing `/handoff` or resuming a prior session
-- You need to recover relevant prior context with `find_sessions`, `read_session`, and memory files
+- You need to recover relevant prior context from repo files or session history
 
 ## When NOT to Use
 
@@ -29,61 +29,69 @@ Use this skill to keep context useful from first turn to final handoff.
 Prefer **phase-level compression** over reactive cleanup.
 
 ```text
-compress > sweep > handoff
+/compact > persist to files > handoff
 ```
 
-- **compress**: Best default when a phase is complete
-- **sweep**: Use `/dcp sweep` to clean stale/noisy content after completion
-- **handoff**: Use when context pressure remains high even after compression
+- **/compact**: Use the Codex-native command when a phase is complete
+- **persist**: Write durable findings to repo files before they leave the context window
+- **handoff**: Use when context pressure remains high even after compaction
 
-## DCP Command Usage
+## Codex-Native Compaction
 
-### `/dcp compress`
+### `/compact`
 
-Use for completed chapters of work (research, implementation wave, review sweep).
+The built-in Codex CLI command that summarizes conversation history server-side.
+
+Use for completed chapters of work (research, implementation wave, review sweep):
+
+```
+/compact focus on the authentication refactor
+```
 
 - Best for large ranges of now-stable outputs
 - Lowest cognitive overhead on later turns
+- Accepts optional focus instructions to guide what it preserves
 - Usually lowest risk of deleting needed details
 
-### `/dcp sweep`
-
-Use after a phase is complete to let DCP remove stale/noisy content automatically.
+### `codex resume`
 
-Good candidates for sweep-driven cleanup:
+Resume a previous Codex session by thread ID:
 
-- wrong-target searches
-- failed dead-end exploration no longer needed
-- duplicate or superseded junk output
+```bash
+codex resume
+```
 
-Do **not** sweep because output is merely "long". Length alone is not noise.
+This restores the session transcript from `~/.codex/sessions/`. Useful for short interruptions where the full session context is still relevant.
 
 ## Session Lifecycle Protocol
 
 ### 1) Start Session
 
 1. Load task spec and essential policy docs only
-2. Check context health (`/dcp context`)
-3. Pull prior work only if needed:
-   - `find_sessions({ query })`
-   - `read_session({ session_id, focus })`
-   - `memory-read({ file })` or `memory-search({ query })`
+2. Pull prior work only if needed:
+   - Read `.codex/context/session-context.md` for the last stop point
+   - Read `.codex/memory/project/state.md` for durable state
+   - Search repo memory: `bash .codex/scripts/memory_search.sh "query"`
+   - Use `codex resume` if continuing from the same thread
 
 ### 2) During Active Work
 
 - Keep active files readable until edits are done
-- At each natural boundary, evaluate compress candidates
-- Compress completed phases before starting the next chapter
+- At each natural boundary, evaluate `/compact` candidates
+- Persist durable findings to repo files before compacting
 
 ### 3) Pre-Handoff / Closeout
 
-1. Compress completed phase ranges
-2. Persist key decisions/learnings to memory (observation or memory-update)
-3. Create concise handoff summary (what changed, what is pending, known risks)
+1. Run `/compact` on completed phase ranges
+2. Persist key decisions/learnings to durable repo files:
+   - `.codex/context/decision-log.md` for architecture decisions
+   - `.codex/context/worklog.md` for milestone trail
+   - `.codex/memory/project/state.md` for durable state
+3. Create concise handoff in `.codex/context/session-context.md`
 
 ### 4) Resume Session
 
-1. Rehydrate only relevant context (don’t replay everything)
+1. Rehydrate only relevant context (don't replay everything)
 2. Validate assumptions against current files/git state
 3. Continue with fresh context budget, not accumulated clutter
 
@@ -94,8 +102,8 @@ Use these thresholds as operational triggers:
 | Threshold | Interpretation | Required Action |
 | --- | --- | --- |
 | <50k | Healthy start | Keep inputs minimal, avoid unnecessary reads |
-| 50k–100k | Moderate growth | Compress completed phases, keep active files intact |
-| >100k | High pressure | Aggressively compress by phase; run `/dcp sweep` on stale noise |
+| 50k-100k | Moderate growth | `/compact` completed phases, keep active files intact |
+| >100k | High pressure | Aggressively compact by phase; persist findings to repo files |
 | >150k | Near capacity | Perform handoff and resume in a fresh session |
 
 Secondary guardrails:
@@ -106,23 +114,25 @@ Secondary guardrails:
 
 ## Phase Boundary Triggers
 
-Compress at these boundaries:
+Compact at these boundaries:
 
-- Research complete → compress exploration + search outputs
-- Implementation wave complete → compress completed read/edit/test cycles
-- Review complete → compress raw reviewer outputs, keep synthesized findings
-- Before `/handoff` → compress everything non-essential since last checkpoint
+- Research complete -> persist findings to `memory/research/`, then `/compact`
+- Implementation wave complete -> `/compact` completed read/edit/test cycles
+- Review complete -> persist synthesized findings, `/compact` raw outputs
+- Before `/handoff` -> compact everything non-essential since last checkpoint
 
-Rule: **Completed phases should not remain uncompressed for long.**
+Rule: **Completed phases should not remain uncompacted for long.**
 
 ## Context Transfer Sources (Cross-Session)
 
 Use in priority order:
 
-1. Memory artifacts (`memory-search`, `memory-read`, observations)
-2. Session history (`find_sessions`, `read_session`)
-3. Task tracker state (`br show <id>` when applicable)
-4. Git evidence (`git diff`, `git log`, test output)
+1. Repo-visible files: `.codex/context/`, `.codex/memory/project/`, `.codex/memory/research/`
+2. Local retrieval: `bash .codex/scripts/memory_search.sh "query"`
+3. Codex session history: `codex resume` for thread-based recall
+4. Task tracker state: `br show <id>` when applicable
+5. Git evidence: `git diff`, `git log`, test output
+6. Optional MCP memory: only when repo docs are insufficient (requires MCP setup)
 
 Carry forward decisions and constraints, not every intermediate log.
 
@@ -130,31 +140,31 @@ Carry forward decisions and constraints, not every intermediate log.
 
 | Anti-Pattern | Why It Hurts | Correct Pattern |
 | --- | --- | --- |
-| Compressing active work areas (losing precision needed for edits) | Removes exact lines needed for safe edits | Keep active file/tool outputs until edit + verification complete |
-| Sweeping content you still need | Forces rework and increases error risk | Keep active files/tool outputs until phase is complete |
-| Not compressing completed exploration phases | Bloats context and degrades later turns | Compress immediately at phase completion |
-| Session handoff without persisting key decisions to memory | Next session loses rationale and constraints | Write observations/memory updates before handoff |
+| Compacting active work areas | Removes exact lines needed for safe edits | Keep active file/tool outputs until edit + verification complete |
+| Not compacting completed phases | Bloats context and degrades later turns | `/compact` immediately at phase completion |
+| Session handoff without persisting to repo files | Next session loses rationale and constraints | Write to decision-log, state, worklog before handoff |
+| Relying only on session memory for durable facts | Facts are lost when session ends | Persist to `.codex/context/` or `.codex/memory/` |
 
 ## Verification
 
-Check context health: are completed phases compressed? Are active files still readable?
+Check context health: are completed phases compacted? Are active files still readable?
 
 Before claiming cleanup done, confirm:
 
 - Active edit targets are still present in readable form
-- Completed phases are compressed or intentionally kept for active work
-- No critical decision exists only in transient tool output
-- Handoff includes next actions and blockers
+- Completed phases are compacted or intentionally kept for active work
+- No critical decision exists only in transient session output
+- Handoff includes next actions and blockers in repo-visible files
 
 ## Quick Playbook
 
 ```text
-1) Start turn: /dcp context
+1) Start: read session-context.md + state.md
 2) Identify completed phase ranges
-3) /dcp compress completed ranges
-4) /dcp sweep stale/noisy outputs after phase completion
-5) persist key decisions to memory
-6) handoff/resume with focused rehydration
+3) Persist durable findings to repo files
+4) /compact completed ranges
+5) At session end: update session-context.md, state.md, worklog.md
+6) Resume: /prompts:resume or codex resume
 ```
 
 ## See Also

package/.codex/skills/session-management/SKILL.md

@@ -1,10 +1,17 @@
 ---
 name: session-management
-description: "Merged into context-management. Load that skill instead."
+description: "Deprecated: merged into context-management. Load $context-management instead."
+deprecated: true
 ---
 
-# Session Management
+# Session Management (Deprecated)
 
-> This skill has been merged into `context-management` which now covers both context and session lifecycle management.
-> 
-> Load `context-management` instead.
+This skill has been merged into `$context-management` which now covers both context health and session lifecycle management.
+
+**Load `$context-management` instead.**
+
+The merged skill covers:
+- Session start, pause, resume lifecycle
+- Context budget thresholds and `/compact` usage
+- Handoff/resume protocol with repo-visible files
+- Cross-session context transfer strategies