Skip to content

feat(context): refresh managed instructions per run + additive BEGIN/END managed block #300

@bradtaylorsf

Description

@bradtaylorsf

Problem

.alpha-loop/templates/instructions.md is synced whole-file into each harness's instruction file — claude → CLAUDE.md, codex/cursor/opencode/gemini/copilot/etc. → AGENTS.md (src/commands/sync.ts:42–82). Two problems:

  1. Stale. Instructions/context are generated once at init (often greenfield) and not refreshed as the repo grows. A repo that bootstraps its own stack in epic Setup pnpm, TypeScript, and basic Express server #1 keeps "no source code / stack TBD" guidance for every later epic, actively misleading Plan/Implement.
  2. All-or-nothing. sync overwrites a file only if it starts with <!-- managed by alpha-loop --> (sync.ts:9–10), then replaces the entire file. Users can't keep project-specific rules in CLAUDE.md/AGENTS.md alongside managed content — hand-edits are lost on the next sync.

Proposed change

  • Re-run scan (or a cheap drift check — e.g. "instructions say no package manager but a lockfile / non-empty packages/ exists") at session start and refresh instructions.md + context.md.
  • Replace the whole-file marker with an additive managed block:
    <!-- alpha-loop:begin (managed — do not edit) -->
    …managed content…
    <!-- alpha-loop:end -->
    
    sync replaces only the block; content above/below is preserved. For an unmarked file, append a block (or leave untouched — configurable).

Files

src/lib/context.ts, src/commands/scan.ts, src/commands/sync.ts, src/lib/scan-validation.ts, src/commands/run.ts (drift check at session start).

Metadata

Metadata

Assignees

No one assigned

    Labels

    engineLoop engine infrastructureenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions