SDSection 6 →

Section 5 · Lesson 1

AgentOS — Persistent Memory & the Feature Lifecycle

Builder Methods AgentOS: /plan product for a project brain that survives every session, shape-spec and the requirements gate, atomic tasks, then implement or orchestrate with intention.

"How would your daily work change if your AI assistant never forgot the mission, roadmap, or stack?

What if your assistant had perfect memory?

You spend an hour explaining project context — mission, stack, roadmap — and the next session the AI has complete amnesia. Every new chat starts at square one. AgentOS from Builder Methods is less another AI gadget and more a discipline: a workflow that creates a persistent brain for the project in the repo, not in chat history.

Shared, permanent memory

The system rests on one idea: durable context that both you and any AI agent can reload anytime, regardless of which tool you use. Run it once at the beginning; the anchor survives across all future sessions.

/plan product — one command to anchor the project

At project start, run /plan product once. It establishes the permanent anchor — three simple plain-text files that form the persistent knowledge layer so a new developer or a brand-new agent gets up to speed almost instantly. The painful cycle of re-explaining goes away.

Three files, three headaches solved

plan.md ends feature drift. roadmap.md prevents priority hallucinations by spelling out what is next. techstack.md ends stack guessing. Together they are a lightweight governance layer humans and agents share.

shape-spec — ask before guess

With memory in place, the next phase forces understanding before code. shape-spec creates structured dialogue instead of wild guesses — a feedback loop where the agent asks questions, you make trade-offs, and every decision is saved to requirements.md. That clarity is locked in permanently.

The clarification gate

The rule is non-negotiable: you cannot move on until requirements.md has zero unresolved items. Eliminate ambiguity first — then implementation stands on clarified intent, not assumptions.

/create-tasks — atomic decomposition

Turn deep understanding into an actionable plan with /create-tasks. Break the feature into the smallest verifiable chunks — easy to review, test, and get right. tasks.md groups work by dependency, links each task to a requirement, includes verification steps, and can tag specialist agents. The output is a deterministic checklist, not a vague to-do list.

Implement vs orchestrate

AgentOS gives two paths and forces a conscious choice. Implement tasks: high control — one agent, one task at a time, sequential review. Orchestrate tasks: high speed — parallel specialist agents, each with only the context relevant to its job. Smaller attention scope reduces drift, prevents conflicts, and yields more reliable code.

The real payoff is consistency

This is not only about speed. You get a predictable rhythm where you focus on intent, trade-offs, and taste — architecting — while agents handle bounded, well-defined implementation. Lightweight governance: /plan product for context, shape-spec for discovery, /create-tasks for checklists, then a disciplined build path.

Never forget again

Strip away the hype: how would your daily work change if your AI assistant never forgot the project’s mission, priorities, or stack? AgentOS answers that with files in version control — memory that reloads every session.

Feature lifecycle (Agent OS)

Each stage is a system call — agents and humans run the same pipeline.

/plan product

Once at project start — plan.md, roadmap.md, techstack.md as durable context.

Documentation maintenance

Keep docs current and executable. Vague instructions produce vague agent behavior — use exact commands.

make sure tests pass

pnpm test && pnpm lint

check the build

pnpm build

run quality checks

npm run lint && npm run build

Approval gates (Tier Two)

Actions that may be valid but have significant blast radius — schema changes, new dependencies, public API changes — need a human sanity check before the agent proceeds.

Tier system in Section 4 →

Clarification — five buckets

Agents ask across these categories so requirements are complete before implementation.

  • Users & roles

    Who acts in the system — and who must never access what?

  • Data lifecycle

    Create, read, update, delete, retention — what happens to data over time?

  • Consistency

    What must stay true across sessions, devices, and concurrent users?

  • Error contracts

    Failure modes, messages, retries, and fallbacks — explicit, not implied.

  • Security & privacy

    PII, auth, logging boundaries — what is never allowed?

Formal checklist — ready for implementation

The spec is ready only when clarification is done and intent is verifiable — shift effort from debugging code to correcting specifications.

  • All clarification issues resolved (Clarification Gate open items = 0)
  • Success criteria are measurable — observable, not subjective
  • Roles and behaviors defined — who can do what
  • Constraints applied — DO NOT boundaries documented
  • Shift focus from debugging code to verifying spec intent
Ready for Plan Checklist (Section 4) →

Atomic decomposition

Break features into the smallest verifiable tasks. Document them in tasks.md — grouped by dependencies, each linked to specific requirements — so review, test, and implementation stay traceable.

/create-tasks (Section 2) →

Control vs speed

Implementation paths

Same AgentOS pipeline — different execution strategy.

High control

Implement Tasks

Execute one task at a time in order — ideal when you want tight review, Tier Two gates, and minimal parallel risk.

Best when

  • ·Learning the codebase
  • ·Risky or ambiguous work
  • ·Constitution-heavy changes

Persistent memory files

Created by /plan product — reload every session. Deeper walkthrough in Section 6. Kiro workflows may also use mission.md for the same product-focus role.

FileProblem it prevents
plan.mdFeature drift

Stops the AI from building features that do not matter — scope stays tied to product intent.

roadmap.mdPriority hallucinations

Makes what comes next explicit so agents and humans do not invent urgency or reorder work.

techstack.mdStack guessing

Single source of truth for frameworks, versions, and allowed tools — no improvised dependencies.

Loading AgentOS memory…

Practice

Check your understanding

A few minutes of recall now saves rereading later.

0 of 4 answered
  1. 1.When should /plan product run?

  2. 2.Which anchor file stops the agent from inventing its own priorities?

  3. 3.What must be true before you leave the clarification gate?

  4. 4.Which instruction is most reliable for an agent?