Why I Built KIS: AI Coding Agents Need More Than Memory
From losing context between conversations to building a method that keeps decisions, plans, and implementation aligned.
By Kamran Qadri
I kept running into the same problem while building software with AI coding agents.
A session would start well. We would discuss an idea, make decisions, agree on an approach, and begin implementing it. A few hours later, the context window would be getting full. I’d need to start a new conversation.
Then came the question I kept asking: would the next agent understand why we were building this, how we were building it, and what we had already decided?
Sometimes the previous agent prepared a good summary. Sometimes I had to explain things again. Even when the context survived, another problem remained: the plan, documentation, and implementation could tell different stories.
I wanted the project to stay understandable without making every conversation responsible for remembering everything.
That led me to KIS: Knowledge, Intent, State.
It’s a small, repository-based method for maintaining project context and giving AI coding agents a disciplined way to plan, execute, verify, and continue work.
The problem wasn’t just forgetting
I had experimented with approaches such as GSD, Superpowers, and Grill Me. Each contributed something useful to how I thought about working with agents: planning, engineering discipline, and asking better questions.
But I didn’t want to operate a complicated framework just to make progress on a product.
Saving more documentation wasn’t necessarily helping either.
A requirement could be updated in one file but remain unchanged in another. An agent might finish implementing something while the backlog still called it unfinished. A new conversation could recover a beautifully written plan that no longer matched the code.
I needed somewhere to keep stable understanding, somewhere to keep direction, and somewhere to describe what was happening right now.
Three layers, three different jobs
KIS stores its memory as Markdown inside the project repository.
Knowledge contains things that should remain true across tasks: architecture, constraints, terminology, engineering rules, and durable decisions.
Intent contains what we’re trying to achieve: the product direction, requirements, plans, and acceptance criteria.
State contains the current working reality: the branch, active task, blocker, verification evidence, and next action.
In one Tartib session, State said the local branch was 66 commits ahead of its remote. When the agent checked Git, the number was already 69. Committing updates to KIS kept making that number inaccurate.
We changed the record to say that the branch had unpushed work and let Git calculate the count whenever we needed it.
That’s a distinction I want KIS to preserve. Keep durable information where it belongs. Recalculate changing facts from their actual source.
A number doesn’t become reliable just because it’s written in a memory file.
I also try to give each fact one owner. If a changing status is copied into three documents, sooner or later one of them will be forgotten.
The workflow grew out of the same problem
The first version of project memory wasn’t enough. An agent could read KIS at the beginning of a long conversation and gradually drift away from its instructions as tool output and implementation details accumulated.
So I added explicit commands and mechanisms to reintroduce the project context.
The underlying loop is:
Load → Question → Challenge → Structure → Plan → Act → Synchronize.
In daily use, I think of it more simply: recover the context, agree on the work, implement it with proof, synchronize what changed, and check that the records still make sense.
KIS has three work modes so every change doesn’t require the same ceremony.
Fast is for small, clear changes. It skips the interview. Standard is for ordinary feature work that needs questions, planning, and approval. Phase breaks larger work into stages and verifies each one.
For a non-trivial feature, I want the agent to question my assumptions before implementing my first suggestion. I still make the final product decisions.
The other important rule is proof before done. A confident agent report or a passing code review isn’t sufficient on its own. The work needs evidence appropriate to the change: tests, builds, manual checks, browser inspection, or deployment verification.
Tartib taught me why decisions need their reasons
Tartib, my personal task and note application, has been a practical place to test this approach.
Its original scope deliberately excluded Pomodoro and push notifications. When I later asked to add them, the agent, working with KIS, surfaced the conflict with the project’s existing rules.
I could change those decisions. The point was to make the change deliberate.
We allowed Pomodoro as a limited session-logging feature. We also allowed specific notifications: reminders I requested, a daily digest at a configured time, and a notification when a session I started finishes.
The recorded rule preserves the reason for those limits: Tartib should not nag me. It should remind me of things I’ve asked it to remind me of.
A future agent needs that reasoning alongside the list of allowed features. It explains what I approved and what principle the exceptions should preserve.
A similar situation arose when I requested offline capture.
The specification explicitly listed an offline capture queue as out of scope. The agent identified my request as a change to the specification, rather than quietly treating it as an implementation detail.
The feature made sense. Losing something I had typed because the network disappeared would violate an important expectation of the application.
So we changed the scope and recorded the decision.
That’s the behavior I want: recognize a contradiction, explain it, and let me decide whether the earlier rule should change.
Passing tests wasn’t the whole answer
The same Tartib development session exposed a different problem.
We were building a new Markdown presentation and editing experience, followed by offline reading and queued actions. The agent ran automated checks, investigated failures, and recorded its verification.
But while working on the offline feature, it found a defect in the previous feature: a conflict message was 430 pixels wide on a 390-pixel phone viewport.
The earlier checks hadn’t displayed that particular conflict state.
The tests had covered part of the behavior. They hadn’t covered everything that mattered.
That reinforced a rule I want to follow: when we change something visual, somebody needs to look at the actual interface in the relevant states.
It also matters how we describe completion.
At the end of that session, those Tartib changes were implemented, tested, and committed locally. They had not yet been deployed or accepted on a physical device. KIS recorded those remaining checks instead of treating a successful local build as proof that users had received the feature.
Continuing without carrying the whole conversation
Another important part of KIS is being able to stop.
During a Llamaport redesign, repeated UI attempts weren’t converging. Continuing the same conversation was becoming unproductive.
The session prepared a clean baseline and a handoff pointing the next agent to the current State and redesign plan, with a smaller next task.
The restart gave us a clearer place to resume. We still had to solve the design problem.
I now use that principle deliberately.
In a recent Tartib session, we finished two feature slices and reconciled the project records. The handoff identified what had been committed, what remained undeployed, what still needed device verification, and which decisions were open.
A new session could use those files to recover the next action instead of relying on my memory of the conversation.
KIS also includes a session-start hook for Claude that reintroduces its instructions and the beginning of the current State file. Other supported environments use their own integration mechanisms.
The public skill supports Claude, Pi, OpenCode, Codex, and Antigravity. The project context lives in the repository, so it can travel between environments. That portability is part of the design; I haven’t yet demonstrated a specific three-agent handoff in the examples described here.
One product, several repositories
I have explored a related idea in my work at SimpliEd: a central product repository that holds product direction and coordinates information from implementation repositories.
I think of it as a product brain.
The product repository owns product decisions. Each implementation repository owns the truth about its technical work. Findings need to move between them without giving every agent permission to rewrite everything.
I have also been applying this approach in Namazee, across the product, backend, Flutter app, admin panel, and website.
The product repository provides the overall requirements and plan. An agent working in an implementation repository reads the relevant direction, examines its own code, and prepares its technical work.
When that agent discovers a contradiction, it should report it to the place that owns the decision.
One documented Flutter session found that the product repository’s implementation plan and execution brief disagreed about which backend tasks were prerequisites for certain milestones. It recorded the discrepancy locally and reported it for product-side reconciliation. A separate product-side session corrected the brief.
The process still requires explicit handoffs and review. KIS doesn’t automatically synchronize independent repositories.
Every repository needs to know what it owns, where to get decisions, and how to report that reality has changed.
Sync is not the same as Check
Updating memory after a task doesn’t guarantee that the memory is consistent.
Sync records what changed in Knowledge, Intent, and State.
Check audits the records for contradictions, duplication, stale information, and missing evidence.
One audit of my content workflow found publication status recorded in three places. A synchronization had updated two of them and missed the third.
Maintaining three copies of one changing fact had created the problem.
KIS has also failed at its own job. During the Tartib session, two checks reported good health while the backlog still listed completed work as open. A later check compared the records mechanically with the project’s actual history and caught the discrepancy.
That’s a limitation I don’t want to hide. KIS can become stale, and its audits can fail if they merely reread documentation instead of verifying claims against the repository.
It also needs regular cleanup. Otherwise, the memory system becomes the documentation pile I was trying to avoid.
What I’m taking forward
KIS is still evolving. I haven’t measured a productivity improvement or token-saving percentage, and I wouldn’t claim one.
What I can describe is a change in how I work.
I can deliberately end a conversation. I can expect an agent to challenge a request that contradicts an earlier decision. I can distinguish a completed implementation from an unverified deployment. And I have a process for finding out when project documentation has drifted away from reality.
I still need to exercise judgment throughout. KIS gives me a more consistent way to apply it.
The goal remains the same as when I began: keep the plan aligned with reality, without turning the framework into another job.
I want to spend less time managing the process and more time building the product.