Show HN: sudocode – manage specs, tasks, and context-as-code for coding agents

[alexsngai]

sudocode is a lightweight context management system for coding agents that lives in your repo. It helps organize the chaos of human-AI collaboration by capturing user intent as durable specs and tracking agent activity as issues, all version-controlled with Git. This "context-as-code" approach reduces agent amnesia and accelerates development on long-horizon tasks.

[wintonzheng]

Does "durable spec" mean writing the spec in a MD file and committing to a repo?

The big problem of ai generated docs for me is that it takes time to read and understand whether they are correct or not. Same with human written docs, which is why you need spec reviewers.

I assume the purpose of sudocode is to help me reduce the time to review and manage specs. How can sudocode help me solve the trust problem here while i don't want to spend so much time reading and managing specs? Solving the spec generation is one part, but the other big problem to solve here is to help speed up the spec review/validation process.

[alexsngai]

I think of specs as a combination of user intent + context that might be relevant for the issue. The expansion of the spec into a full-fledged document, whether thats agent-written or human-written can be flexible as long as it contains the original user intent and requirements (so it becomes useful input to any coding agents handling the implementation).

In this case, what sudocode aims to preserve is the human intent that might be lost in agent chat logs, etc. It then provides utilities to turn those specs into implementation plans (issues). And specs in this case are mutable and designed to be iterated on (just like code).

Or with a physics analogy, the code is the position of a particle while the specs capture velocity information. You can iteratively work on changing the velocity which will then change the position (code changes).

As for the spec review burden, the sudocode provides an interface for coding agents to provide bi-directional feedback onto the original spec, so you can fire off a few coding agents and see how they performed relative to your specified requirements. You can let the execution of the coding agents speak for themselves!

[ishita159]

have tried it, i think's focusing on spec-driven development?

[alexsngai]

yes! sudocode manages agents at different levels of abstraction. You can steer agents at the `spec` level by building up a spec that contains your intent and requirements, then generate `issues` that capture the implementation details. However you aren't limited to that pattern. You can also just manage agents at the `issue` level to better manage their execution state (think something like a kanban board).

In general, sudocode aims to preserve some of this implementation/planning state (context-as-code) in your codebase so it isn't lost in your chat logs. Keeping this context in your repo makes it accessible to coding agents long after code changes were made, so it functions as a sort of episodic memory for your codebase.

[arcticampic]

nice