agent/docs/RFC.plan.md

RFC Plan — How to Start a core/agent Session

For future Claude sessions. Do this FIRST before touching code.

Step 1: Load the Domain

Read these files in order using ReadFile. Yes, all of them. The ~2000 tokens of boot cost pays for itself immediately — zero corrections, zero rediscovery.

1. ReadFile /Users/snider/Code/core/go/docs/RFC.md          (1278 lines — core/go contract, 21 sections)
2. ReadFile /Users/snider/Code/core/agent/docs/RFC.md        (~500 lines — core/agent contract, 22 sections)
3. ReadFile /Users/snider/Code/core/go-process/docs/RFC.md   (~224 lines — go-process contract, 8 sections)

After loading all three, you have the full domain model:

• Every core/go primitive and how core/agent uses it
• The current state of core/agent (what's migrated, what isn't)
• The file layout with per-file migration actions
• The quality gates (10 disallowed imports, test naming, string concat)
• The completion pipeline architecture
• The entitlement/permission model

Step 2: Verify Context

After loading, you should be able to answer without looking at code:

• What does c.Action("agentic.dispatch").Run(ctx, opts) do?
• How do direct s.Core().Process() calls replace the old process wrapper layer?
• What replaces the ACTION cascade in handlers.go?
• Which imports are disallowed and what replaces each one?
• What does c.Entitled("agentic.concurrency", 1) check?

If you can't answer these, re-read the RFCs.

Step 3: Work the Migration

The core/agent RFC Section "Current State" has the annotated file layout. Each file is marked DELETE, REWRITE, or MIGRATE with the specific action.

Priority order:

1. OnStartup/OnShutdown return Result (breaking, do first)
2. Replace unsafe.Pointer → Fs.NewUnrestricted() (paths.go)
3. Replace os.WriteFile → Fs.WriteAtomic (status.go)
4. Replace core.ValidateName / core.SanitisePath (prep.go, plan.go)
5. Replace core.ID() (plan.go)
6. Register capabilities as named Actions (OnStartup)
7. Replace ACTION cascade with Task pipeline (handlers.go)
8. Use s.Core().Process() directly in call sites. The old proc.go wrapper layer has been removed.
9. AX-7 test rename + gap fill
10. Example tests per source file

Step 4: Session Cadence

Follow the CLAUDE.md session cadence:

• 0-50%: Build — implement the migration
• 50%: Feature freeze — finish what's in progress
• 60%+: Refine — review passes on RFC.md, docs, CLAUDE.md, llm.txt
• 80%+: Save state — update RFCs with what shipped

What NOT to Do

• Don't guess the architecture — it's in the RFCs
• Don't use os, os/exec, fmt, errors, io, path/filepath, encoding/json, strings, log, unsafe — Core has primitives for all of these
• Don't use string concat with + — use core.Concat() or core.Path()
• Don't add fmt.Println — use core.Println()
• Don't write anonymous closures in command registration — extract to named methods
• Don't nest c.ACTION() calls — use c.Task() composition