Claude Skill

best-project-memory

Use when restoring project context at the start of repo work, maintaining durable project memory across sessions, recording decisions, updating task state, preparing handoffs, or saving progress into repo-native memory files. Especially useful when users ask to continue previous

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download dengyie-awesome-skills-best-project-memory-a5d5e22.zip · 33 KB

Install

skills CLI npx skills add https://github.com/dengyie/awesome-skills/tree/main/best-project-memory
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dengyie-awesome-skills@llmmart
Git git clone https://github.com/dengyie/awesome-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole dengyie/awesome-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Best Project Memory

Mission

Maintain a lightweight, repo-native continuity layer that another Codex session can reload quickly.

Prefer filesystem truth over chat memory. Keep the memory compact, current, and handoff-ready.

Core Storage

Use .codex-memory/ in the current repository root.

Always maintain these core files:

  • .codex-memory/project-state.md
  • .codex-memory/session-log.md
  • .codex-memory/decisions.md
  • .codex-memory/todo.md

Use these optional directories when the work justifies them:

  • .codex-memory/phases/
  • .codex-memory/handoffs/
  • .codex-memory/workstreams/
  • .codex-memory/snapshots/

Read references/state-schema.md before creating or restructuring the files. Read references/surface-contract.md before changing the memory surface or deciding which objects are script-owned.

Required Workflow

  1. Restore context before project work.

    • Ensure .codex-memory/ exists.
    • Read the four core files when they exist.
    • If phase or handoff docs exist and are obviously relevant, read only the needed ones.
    • Give a short loaded-context recap covering objective, phase, active TODOs, latest decisions, and blockers.
    • For concrete project delivery work, establish the milestone execution contract before implementation starts.
  2. Establish a milestone execution contract for production work.

    • Use a milestone as the current-session scope container. It must deliver at least one of: user capability, release gate closure, core architecture boundary, or blocking defect fix.
    • Classify discovered work before editing:
      • P0: delivery blockers, severe bugs, security issues, build failures.
      • P1: required current-milestone functionality, tests, or refactors.
      • P2/P3: optimizations, enhancements, and long-term maintenance. Route these to backlog only.
      • Manual-required: external accounts, certificates, signing, notarization, real devices, production secrets, or third-party permissions.
    • Output and then obey this Step 0 contract:
Milestone:
Goal:
P0/P1 scope:
Out-of-scope P2/P3:
Manual-required:
Phase limit:
Phase split:
Acceptance criteria:
Stop conditions:
  • Freeze scope after the contract. Expand only for a true P0/P1 blocker.
  • Default to at most 3 phases; use at most 5 only for genuinely complex milestones.
  • Make each phase a deliverable closure around feature, architecture, defect fix, test gate, build chain, permission path, or release gate. Do not create phases for single files, fields, scripts, evidence snippets, or standalone paperwork.
  • Stop after the milestone's P0/P1 work passes necessary verification. Do not automatically open the next milestone.
  1. Keep the state panel current.

    • Treat project-state.md as the single current snapshot.
    • Overwrite only the live summary content there.
    • Keep it concise and operational.
    • Push workstream-level detail down into workstreams/*.md instead of bloating the global state.
  2. Append session history.

    • Add a new entry to session-log.md after meaningful progress, at session close, or when the user asks to save progress.
    • Do not rewrite old session entries unless correcting obvious factual mistakes.
  3. Record important decisions.

    • Add ADR-lite entries to decisions.md for meaningful choices, tradeoffs, or policy changes.
    • Include rationale and impact, not just the conclusion.
  4. Maintain actionable TODO state.

    • Keep todo.md focused on active work.
    • Mark completed items done instead of deleting them.
    • Move stale or obsolete items only when their status is clear.
    • Do not promote backlog items into new phases unless they block the current milestone's P0/P1 acceptance criteria.
    • Record Manual-required gaps with impact and validation entrypoint, but do not create development phases for them unless they materially shorten current-milestone verification.
  5. Summarize completed phases and milestone stops.

    • After each phase, record completed content, validation, review score/status, key decisions, new backlog, manual-required gaps, and remaining phase budget.
    • When stop conditions are met, write a milestone delivery summary or a manual-attention report. Do not continue into polish, extra evidence, or unrelated TODO cleanup after the stop condition is satisfied.
  6. Create handoff artifacts when the work spans sessions or people.

    • Use handoffs/ for compact continuation packs.
    • Use phases/ for milestone summaries.
    • Use workstreams/ for bounded parallel tracks inside larger projects.
    • Use snapshots/ for machine-oriented evidence captures.
    • Read references/handoff-patterns.md before writing a new handoff file.

Update Policy

Read references/update-policy.md before deciding where new information belongs. Read references/update-triggers.md when deciding what kind of event should create a state update, promotion, or compaction step.

Use this routing rule:

  • Current snapshot: project-state.md
  • Time-ordered work record: session-log.md
  • Durable choice with rationale: decisions.md
  • Action queue: todo.md
  • Milestone recap: phases/*.md
  • Session transfer pack: handoffs/*.md
  • Parallel task state: workstreams/*.md
  • Evidence snapshot: snapshots/*

Do not dump everything into session-log.md.

Deterministic Helpers

Use the helper scripts when they reduce repeated hand editing:

  • scripts/init_memory.py: initialize .codex-memory/ with the standard files and optional phase/handoff directories
  • scripts/append_session.py: append a structured session entry to session-log.md
  • scripts/handoff_pack.py: generate a compact handoff file from the current memory snapshot
  • scripts/compact_session.py: compact older session-log.md history into a shorter summary and optional phase recap

Resolve script paths relative to this skill directory. For a user-scope install, they are usually under $HOME/.agents/skills/best-project-memory/scripts/.

Reference Routing

  • references/state-schema.md: read before creating or normalizing memory files
  • references/surface-contract.md: read before changing structure, ownership, or script write boundaries
  • references/update-policy.md: read before deciding what to update
  • references/update-triggers.md: read when mapping work events to memory actions
  • references/quality-rules.md: read when checking whether the memory has drifted into low-quality patterns
  • references/integration-patterns.md: read when another skill should consume or update this memory model
  • references/examples.md: read when you want concrete memory-entry examples
  • references/handoff-patterns.md: read before writing handoff or phase summaries

Load only the references needed for the current task.

Completion Standard

A project-memory pass is complete only when:

  • the repo memory folder exists or has been intentionally confirmed unnecessary
  • concrete project work has a visible milestone contract or an explicit reason it is unnecessary
  • current objective, phase, blockers, and next step are easy to find
  • durable decisions are captured with rationale
  • TODOs reflect the real state of work
  • another Codex session could resume without rereading the whole conversation
Files (awesome-skills)
  • agents
    • openai.yaml 302 B
      Loading…
  • references
    • examples.md 2.7 KB
      Loading…
    • handoff-patterns.md 1.4 KB
      Loading…
    • integration-patterns.md 2.1 KB
      Loading…
    • quality-rules.md 2.9 KB
      Loading…
    • snapshot-schema.md 866 B
      Loading…
    • state-schema.md 3.2 KB
      Loading…
    • surface-contract.md 2.5 KB
      Loading…
    • update-policy.md 2.6 KB
      Loading…
    • update-triggers.md 2 KB
      Loading…
    • workstream-template.md 474 B
      Loading…
  • scripts
    • append_session.py 1.7 KB
      Loading…
    • compact_session.py 8.9 KB
      Loading…
    • generate_handoff.py 5.7 KB
      Loading…
    • handoff_pack.py 2.3 KB
      Loading…
    • init_memory.py 3.4 KB
      Loading…
    • memory_lint.py 7.7 KB
      Loading…
    • promote_decision.py 2.6 KB
      Loading…
    • snapshot_state.py 4.2 KB
      Loading…
    • stale_todo_check.py 3.5 KB
      Loading…
    • sync_workstream.py 2.9 KB
      Loading…
  • tests
    • test_skill_package.py 36.3 KB
      Loading…
  • SKILL.md 7.6 KB
    ---
    name: best-project-memory
    description: Use when restoring project context at the start of repo work, maintaining durable project memory across sessions, recording decisions, updating task state, preparing handoffs, or saving progress into repo-native memory files. Especially useful when users ask to continue previous work, save progress, summarize current state, capture decisions, or make another agent session resume cleanly.
    ---
    
    # Best Project Memory
    
    ## Mission
    
    Maintain a lightweight, repo-native continuity layer that another Codex session can reload quickly.
    
    Prefer filesystem truth over chat memory. Keep the memory compact, current, and handoff-ready.
    
    ## Core Storage
    
    Use `.codex-memory/` in the current repository root.
    
    Always maintain these core files:
    
    - `.codex-memory/project-state.md`
    - `.codex-memory/session-log.md`
    - `.codex-memory/decisions.md`
    - `.codex-memory/todo.md`
    
    Use these optional directories when the work justifies them:
    
    - `.codex-memory/phases/`
    - `.codex-memory/handoffs/`
    - `.codex-memory/workstreams/`
    - `.codex-memory/snapshots/`
    
    Read `references/state-schema.md` before creating or restructuring the files.
    Read `references/surface-contract.md` before changing the memory surface or deciding which objects are script-owned.
    
    ## Required Workflow
    
    1. Restore context before project work.
       - Ensure `.codex-memory/` exists.
       - Read the four core files when they exist.
       - If phase or handoff docs exist and are obviously relevant, read only the needed ones.
       - Give a short loaded-context recap covering objective, phase, active TODOs, latest decisions, and blockers.
       - For concrete project delivery work, establish the milestone execution contract before implementation starts.
    
    2. Establish a milestone execution contract for production work.
       - Use a milestone as the current-session scope container. It must deliver at least one of: user capability, release gate closure, core architecture boundary, or blocking defect fix.
       - Classify discovered work before editing:
         - `P0`: delivery blockers, severe bugs, security issues, build failures.
         - `P1`: required current-milestone functionality, tests, or refactors.
         - `P2/P3`: optimizations, enhancements, and long-term maintenance. Route these to backlog only.
         - `Manual-required`: external accounts, certificates, signing, notarization, real devices, production secrets, or third-party permissions.
       - Output and then obey this Step 0 contract:
    
    ```text
    Milestone:
    Goal:
    P0/P1 scope:
    Out-of-scope P2/P3:
    Manual-required:
    Phase limit:
    Phase split:
    Acceptance criteria:
    Stop conditions:
    ```
    
       - Freeze scope after the contract. Expand only for a true P0/P1 blocker.
       - Default to at most 3 phases; use at most 5 only for genuinely complex milestones.
       - Make each phase a deliverable closure around feature, architecture, defect fix, test gate, build chain, permission path, or release gate. Do not create phases for single files, fields, scripts, evidence snippets, or standalone paperwork.
       - Stop after the milestone's P0/P1 work passes necessary verification. Do not automatically open the next milestone.
    
    3. Keep the state panel current.
       - Treat `project-state.md` as the single current snapshot.
       - Overwrite only the live summary content there.
       - Keep it concise and operational.
       - Push workstream-level detail down into `workstreams/*.md` instead of bloating the global state.
    
    4. Append session history.
       - Add a new entry to `session-log.md` after meaningful progress, at session close, or when the user asks to save progress.
       - Do not rewrite old session entries unless correcting obvious factual mistakes.
    
    5. Record important decisions.
       - Add ADR-lite entries to `decisions.md` for meaningful choices, tradeoffs, or policy changes.
       - Include rationale and impact, not just the conclusion.
    
    6. Maintain actionable TODO state.
       - Keep `todo.md` focused on active work.
       - Mark completed items done instead of deleting them.
       - Move stale or obsolete items only when their status is clear.
       - Do not promote backlog items into new phases unless they block the current milestone's P0/P1 acceptance criteria.
       - Record `Manual-required` gaps with impact and validation entrypoint, but do not create development phases for them unless they materially shorten current-milestone verification.
    
    7. Summarize completed phases and milestone stops.
       - After each phase, record completed content, validation, review score/status, key decisions, new backlog, manual-required gaps, and remaining phase budget.
       - When stop conditions are met, write a milestone delivery summary or a manual-attention report. Do not continue into polish, extra evidence, or unrelated TODO cleanup after the stop condition is satisfied.
    
    8. Create handoff artifacts when the work spans sessions or people.
       - Use `handoffs/` for compact continuation packs.
       - Use `phases/` for milestone summaries.
       - Use `workstreams/` for bounded parallel tracks inside larger projects.
       - Use `snapshots/` for machine-oriented evidence captures.
       - Read `references/handoff-patterns.md` before writing a new handoff file.
    
    ## Update Policy
    
    Read `references/update-policy.md` before deciding where new information belongs.
    Read `references/update-triggers.md` when deciding what kind of event should create a state update, promotion, or compaction step.
    
    Use this routing rule:
    
    - Current snapshot: `project-state.md`
    - Time-ordered work record: `session-log.md`
    - Durable choice with rationale: `decisions.md`
    - Action queue: `todo.md`
    - Milestone recap: `phases/*.md`
    - Session transfer pack: `handoffs/*.md`
    - Parallel task state: `workstreams/*.md`
    - Evidence snapshot: `snapshots/*`
    
    Do not dump everything into `session-log.md`.
    
    ## Deterministic Helpers
    
    Use the helper scripts when they reduce repeated hand editing:
    
    - `scripts/init_memory.py`: initialize `.codex-memory/` with the standard files and optional phase/handoff directories
    - `scripts/append_session.py`: append a structured session entry to `session-log.md`
    - `scripts/handoff_pack.py`: generate a compact handoff file from the current memory snapshot
    - `scripts/compact_session.py`: compact older `session-log.md` history into a shorter summary and optional phase recap
    
    Resolve script paths relative to this skill directory. For a user-scope install, they are usually under `$HOME/.agents/skills/best-project-memory/scripts/`.
    
    ## Reference Routing
    
    - `references/state-schema.md`: read before creating or normalizing memory files
    - `references/surface-contract.md`: read before changing structure, ownership, or script write boundaries
    - `references/update-policy.md`: read before deciding what to update
    - `references/update-triggers.md`: read when mapping work events to memory actions
    - `references/quality-rules.md`: read when checking whether the memory has drifted into low-quality patterns
    - `references/integration-patterns.md`: read when another skill should consume or update this memory model
    - `references/examples.md`: read when you want concrete memory-entry examples
    - `references/handoff-patterns.md`: read before writing handoff or phase summaries
    
    Load only the references needed for the current task.
    
    ## Completion Standard
    
    A project-memory pass is complete only when:
    
    - the repo memory folder exists or has been intentionally confirmed unnecessary
    - concrete project work has a visible milestone contract or an explicit reason it is unnecessary
    - current objective, phase, blockers, and next step are easy to find
    - durable decisions are captured with rationale
    - TODOs reflect the real state of work
    - another Codex session could resume without rereading the whole conversation
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.