Tracking Context Agentically

Overview

sudocode acts as the memory layer for your coding agent. Converse and work with your coding agent naturally, while sudocode captures your context as specs and issues that you and your agent can refer to in real time.

The Scenario

You need to add a fulfillment_priority field to your order processing pipeline — update the mapper to extract it from the upstream API, and update the DAO to persist it.

Starting the conversation

Open your coding agent and start talking through the change, pointing it at relevant files.

> User: Hey, I need to update our order processing pipeline. We're
  getting a new `fulfillment_priority` field from the upstream API
  that we need to map and persist. Can you look at
  src/mappers/order_mapper.ts and src/dao/order_dao.ts?

⏺ Agent: Let me look at those files.

⏺ Read(src/mappers/order_mapper.ts)
  ⎿  ...

⏺ Read(src/dao/order_dao.ts)
  ⎿  ...

⏺ Agent: I see the current setup. OrderMapper.toDomain() converts
  the upstream API response into your internal Order type, and
  OrderDAO handles inserts/updates against the orders table.

  To add fulfillment_priority, we'd need to:
  1. Add the field to the Order domain type
  2. Update OrderMapper.toDomain() to extract it from the API response
  3. Add a column to the DAO's insert/update queries
  4. Handle the case where the upstream API doesn't include it (older orders)

> User: Right. The upstream field is called `priority_level` and
  it's an integer 1-5. We want to map it to an enum on our side —
  LOW, MEDIUM, HIGH. 1-2 is LOW, 3 is MEDIUM, 4-5 is HIGH.

⏺ Agent: Got it — so this is a mapping with a transform, not a
  straight pass-through. Should the default for missing values be
  LOW, or should it be nullable?

> User: Default to LOW if it's missing.

Asking the agent to track and implement

At this point, the developer wants the agent to go ahead and make the changes — and track what it’s doing.

> User: Can you track an issue for this and work on it?

⏺ Agent: I'll create an issue and get started.

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Add fulfillment_priority to order pipeline",
   description: "Map upstream `priority_level` (int 1-5) to internal
   `fulfillment_priority` enum (LOW/MEDIUM/HIGH).

   ## Changes needed
   - Add FulfillmentPriority enum to domain types
   - Update OrderMapper.toDomain() with priority mapping logic
     - 1-2 → LOW, 3 → MEDIUM, 4-5 → HIGH
     - Default to LOW when field is missing
   - Update OrderDAO insert/update to persist the new field
   - Add `fulfillment_priority` column (assumes migration exists)

   ## Files
   - src/types/order.ts
   - src/mappers/order_mapper.ts
   - src/dao/order_dao.ts",
   status: "open",
   priority: 2,
   tags: ["orders", "mapping"])
  ⎿  { "id": "i-3k8w", ... }

The agent created the issue from the conversation context — the mapping logic, the files involved, and the relevant details are all captured. You can navigate to localhost:3000, open your project, and check the Issues board to see it:

The created issue on the sudocode issue board

Agent implements and tracks progress

The agent moves the issue to in_progress and starts making changes, recording what it finds along the way as feedback on the issue.

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (issue_id: "i-3k8w", status: "in_progress")

⏺ Agent: Starting with the domain type and mapper.

⏺ Edit(src/types/order.ts)
  ⎿  Added FulfillmentPriority enum and field to Order type

⏺ Edit(src/mappers/order_mapper.ts)
  ⎿  Added mapPriorityLevel() helper and updated toDomain()

⏺ plugin:sudocode:sudocode - add_feedback (MCP)
  (to_id: "i-3k8w",
   content: "Mapper updated. Added `mapPriorityLevel()` private
   method that handles the int→enum conversion. Placed it as a
   static method on OrderMapper since it's a pure transform.
   Defaults to LOW for undefined/null/out-of-range values.",
   type: "comment")

⏺ Agent: Mapper's done. Moving on to the DAO.

⏺ Edit(src/dao/order_dao.ts)
  ⎿  Updated insert() and update() queries to include fulfillment_priority

⏺ plugin:sudocode:sudocode - add_feedback (MCP)
  (to_id: "i-3k8w",
   content: "DAO updated — added fulfillment_priority to both
   insert and update queries. Note: this assumes the column already
   exists in the orders table. If the migration hasn't been run yet,
   inserts will fail.",
   type: "comment")

⏺ Agent: Both files are updated. One thing to flag — the DAO
  changes assume the database column exists. Do you have a migration
  for that, or should I create one?

> User: There's already a migration pending for it, we're good.

⏺ plugin:sudocode:sudocode - add_feedback (MCP)
  (to_id: "i-3k8w",
   content: "Confirmed: migration for fulfillment_priority column
   already exists. No additional migration needed.",
   type: "comment")

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (issue_id: "i-3k8w", status: "closed")

⏺ Agent: Issue closed. The fulfillment_priority field is mapped
  and persisted.

The agent made the code changes and left a trail of context on the issue — each comment captures a decision or finding that would otherwise evaporate after the session.

The closed issue with feedback comments on the sudocode issue board

A second change surfaces mid-session

While reviewing the agent’s work, the developer spots a related change.

> User: Actually, while you're in here — the OrderMapper also
  doesn't handle the `estimated_delivery` field that got added last
  sprint. It's in the API response but we're ignoring it. Can you
  handle that too? Same deal — track it and do it.

⏺ Agent: I'll create a separate issue for that.

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Map estimated_delivery field in OrderMapper",
   description: "The upstream API includes an `estimated_delivery`
   timestamp that we're currently ignoring in OrderMapper.toDomain().

   ## Changes needed
   - Add estimatedDelivery (Date | null) to Order type
   - Update OrderMapper.toDomain() to parse the ISO timestamp
   - Update OrderDAO to persist the field

   ## Files
   - src/types/order.ts
   - src/mappers/order_mapper.ts
   - src/dao/order_dao.ts",
   status: "in_progress",
   priority: 3,
   tags: ["orders", "mapping"])
  ⎿  { "id": "i-9f2v", ... }

⏺ plugin:sudocode:sudocode - link (MCP)
  (from_id: "i-9f2v", to_id: "i-3k8w", type: "related")

⏺ Edit(src/types/order.ts)
  ⎿  Added estimatedDelivery field

⏺ Edit(src/mappers/order_mapper.ts)
  ⎿  Added estimated_delivery parsing in toDomain()

⏺ Edit(src/dao/order_dao.ts)
  ⎿  Added estimated_delivery to insert/update queries

⏺ plugin:sudocode:sudocode - add_feedback (MCP)
  (to_id: "i-9f2v",
   content: "Mapped estimated_delivery as a nullable Date. The
   upstream field is an ISO 8601 string — parsing with new Date()
   and storing as TIMESTAMPTZ. Returns null if the field is missing
   or the date string is invalid.",
   type: "comment")

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (issue_id: "i-9f2v", status: "closed")

⏺ Agent: Done — issue closed. Here's what we covered this session:
  - i-3k8w: Added fulfillment_priority mapping (int→enum) and DAO persistence
  - i-9f2v: Added estimated_delivery parsing and DAO persistence

What you get

After this session, you have two closed issues in your sudocode/ directory, each with:

A clear description of what was changed and why
Feedback comments capturing implementation decisions (enum mapping strategy, null handling, migration assumptions)
File references showing what was touched

Both closed issues on the sudocode issue board

You don’t need to pre-plan everything. Start coding, and when something is worth tracking, just ask your agent to create an issue. The context accumulates naturally.

Key Takeaways

Issues capture decisions, not just tasks

The feedback on each issue records why things were done a certain way — the enum mapping logic, the null handling strategy, the migration dependency. The context that normally gets lost in sessions are now preserved as part of the issue chain.

One conversation, multiple issues

When related work surfaces mid-session, the agent creates separate issues. Each one is self-contained and trackable, even though they came from the same conversation.

No ceremony required

You don’t need to set up specs or plan issue dependencies upfront to get value from sudocode. Just start coding and track things as they come up. When you do need more structure, see Spec-Driven Development.

Creating Issues

More ways to create and organize issues

Feedback

How feedback captures implementation context

Spec-Driven Development

When you need more structure upfront

Getting Started

Examples & Tutorials

Core Concepts

Tracking Context Agentically

Overview

The Scenario

Starting the conversation

Asking the agent to track and implement

Agent implements and tracks progress

A second change surfaces mid-session

What you get

Key Takeaways

Creating Issues

Feedback

Spec-Driven Development

​Overview

​The Scenario

​Starting the conversation

​Asking the agent to track and implement

​Agent implements and tracks progress

​A second change surfaces mid-session

​What you get

​Key Takeaways

​Related Documentation

Creating Issues

Feedback

Spec-Driven Development

Overview

The Scenario

Starting the conversation

Asking the agent to track and implement

Agent implements and tracks progress

A second change surfaces mid-session

What you get

Key Takeaways

Related Documentation