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.
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.
Open your coding agent and start talking through the change, pointing it at relevant files.
Copy
> 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.
At this point, the developer wants the agent to go ahead and make the changes — and track what it’s doing.
Copy
> 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 agent moves the issue to in_progress and starts making changes, recording what it finds along the way as feedback on the issue.
Copy
⏺ 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.
While reviewing the agent’s work, the developer spots a related change.
Copy
> 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
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.
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.
