Skip to content

/arch-init: architect auto-state-saving — save to codev/state/<name>.md at checkpoints, then suggest /clear (supersedes #1212) #1220

Closed

Description

@waleedkadous

/arch-init: architect auto-state-saving — save to codev/state/.md at checkpoints, then suggest /clear

Supersedes #1212 (closed wontfix — we're switching approach from "add a save command / standing instruction" to architect auto-saving built into /arch-init itself).

Design

/arch-init currently reads state at session start and never writes. This change makes the skill instruct a complete context-lifecycle loop:

/arch-init (recover) → work → auto-save at checkpoint → "good time to /clear" → human /clears → /arch-init (recover) → …

The state file stops being crash insurance and becomes the architect's deliberate memory-management mechanism: a curated summary written at a moment the architect chooses, at a resumable boundary — better than auto-compaction because both the timing and the content are intentional.

Save-then-suggest ordering is the core safety property. The agent cannot clear its own context and must not decide unilaterally to lose it. The skill instructs: save first, then tell the human it's a good time to /clear. The irreversible action stays behind a human keystroke, and accepting the suggestion can never lose anything because the save already happened.

Skill-text requirements (add to BOTH trees' arch-init SKILL.md)

  1. When to save — at resumable boundaries, judged by the architect: a gate approval, a PR merge, a completed investigation, the end of a long tool-heavy stretch. NEVER mid-task: the state file must describe a point a fresh session can pick up from.
  2. Write format = read format (symmetry with the Spec 1134 minimum contract): rewrite the current-state/open-loops section in place; append a short dated log entry. The recovery flow reads "banner + most recent dated section", so that is exactly what a save must leave behind.
  3. Compaction discipline — the file must stay readable in one screen: prune stale dated sections when appending; the state file is a summary, not a transcript.
  4. The suggestion is advisory, never nagging: e.g. "State saved to codev/state/main.md — good time to /clear if this session is feeling heavy." Suggest only right after a save.
  5. Content guardrails: no secrets, no transcript dumps; open loops + resume instructions + current focus.

Why in /arch-init rather than a separate /arch-save skill

Self-reinforcement: every recovery re-reads the skill and re-primes the save habit — the durability gap named in #1212 (recovery assumes a file nothing instructs anyone to write) closes automatically after each architect's first /arch-init.

Deliverables

  • Updated codev-skeleton/.claude/skills/arch-init/SKILL.md + byte-identical .claude/skills/arch-init/SKILL.md (two-tree rule).
  • Updated skill-text assertions in packages/codev/src/agent-farm/__tests__/spec-1134-arch-init-skill.test.ts: keep all existing assertions passing (byte-equality, required/forbidden content), add required-content assertions for the save instruction (e.g. mentions saving to codev/state/<name>.md at checkpoints, mentions suggesting /clear after save, mentions never saving mid-task).

Acceptance criteria (mechanically checkable, per the [From 1134] lesson: pin the shipped text)

  • Both SKILL.md copies byte-identical, tests green.
  • Skill text instructs: save at resumable checkpoints → then suggest /clear; save = rewrite current-state section + append dated entry; prune stale sections; never mid-task; no secrets.
  • Existing recovery behavior (identity resolution, missing-file flow, four guardrails) unchanged.

Area: area/scaffold. Protocol suggestion: AIR (small, fully specified here, no plan gate needed).

Activity

  1. added
    area/scaffoldArea: Install path — codev init/adopt/update/doctor, codev-skeleton, four-tier resolver
    on Jul 22, 2026
  2. added 3 commits that reference this issue on Jul 22, 2026
  3. added a commit that references this issue on Jul 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/scaffoldArea: Install path — codev init/adopt/update/doctor, codev-skeleton, four-tier resolver

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions