I didn't start AIDD Skeleton because AI was bad at writing code.
Quite the opposite.
I was already using AI as a development partner.
We would discuss requirements, compare approaches, investigate problems, make design decisions, implement changes, and review the results.
The conversation itself worked surprisingly well.
The problem was everything around the conversation.
As a project continued, more and more things had to survive beyond the current chat:
- decisions we had already made,
- ideas we had considered but not adopted,
- requirements,
- design,
- implementation,
- experiments,
- reference material,
- environment configuration,
- verification results,
- and the current state of the project.
If all of that was handled casually, the repository could become just as chaotic as the conversation history I was trying not to depend on.
So the original idea was fairly modest:
I wanted a predictable format where a developer and an AI agent could keep building through conversation without slowly turning the project into a mess.
That was the beginning of AIDD Skeleton.
The first version was mostly about places
The first public commit was on July 29, 2026.
At that point, the repository already had a fairly strict idea of how an AI-driven project should be organized.
There were five top-level areas:
plans/
etc/
prototypes/
references/
products/
Each had a different responsibility.
plans/ was for project documentation and sources of truth.
etc/ was for execution-environment configuration.
prototypes/ was for temporary experiments.
references/ was for externally supplied material.
products/ was for formal implementation.
This may look like a directory convention, but the motivation was more defensive than aesthetic.
AI agents are very good at solving the problem directly in front of them.
A framework expects src/?
Create src/.
A tool wants scripts/?
Create scripts/.
A new service looks independent?
Create another top-level directory.
Each individual decision can be perfectly reasonable.
The repository as a whole can still gradually lose any coherent ownership model.
So the rule was intentionally strict:
Before creating something, classify what responsibility it serves.
If it doesn't fit anywhere, don't immediately create a sixth category.
First ask whether the classification itself is wrong.
That idea is still visible in the initial repository history:
Initial English AIDD skeleton — July 29, 2026
A few hours later, I updated the README with an almost comically simple quick start:
- Clone the repository.
- Open it in an AI development environment.
- Send the first message.
The idea was that the conversation would begin normally, but the project underneath it would already have a shared structure for the human and the agent.
At this stage, I thought the main problem was organization.
That didn't last very long.
The first PR was already about documentation getting out of control
The first merged pull request wasn't a new AI capability.
It was called:
Prevent TRACEABILITY.md from growing without bound
That happened on August 1.
Repository history — Prevent TRACEABILITY.md from growing without bound
This was an early warning.
Traceability sounded obviously useful.
If requirements, design, implementation, and verification were related, why not record those relationships?
The problem was that a single global traceability document could easily become the place where everything accumulated.
More implementation units.
More verification.
More history.
More identifiers.
More relationships.
The document intended to make the project easier to understand could eventually become another source of complexity.
So traceability was split by responsibility instead of allowing one file to grow forever.
It was a small change, but it introduced a theme that would come back repeatedly:
More documentation does not automatically create more order.
Sometimes documentation itself needs boundaries.
Then the framework had to learn to distrust its own documentation
Only minutes after that first PR, another change landed:
Review sources of truth before implementation
Repository history — Review sources of truth before implementation
This changed the way disagreements were supposed to be handled.
Imagine that the requirements say one thing, the design says another, and the implementation behaves differently again.
A very tempting response is:
The code doesn't match the documentation. Fix the code.
But that assumes the documentation is correct.
The new rule was to diagnose the disagreement in order:
- Is the source of truth complete, current, and internally consistent?
- Does the implementation conform to that validated source?
- Does the verification actually demonstrate that conformity?
That sounds obvious in retrospect.
It wasn't obvious enough that I trusted an AI agent to infer it every time.
The repository needed to say it explicitly.
This was probably the first point where AIDD Skeleton started becoming something more than a directory template.
The folders were not enough.
The agent also needed rules for deciding what information was allowed to mean.
prototypes/ turned out to be too small an idea
The next change was even more revealing.
Originally, one of the five areas was:
prototypes/
That seemed reasonable.
During development, you sometimes need a proof of concept, a technical spike, or an experiment before making a decision.
But conversations with AI produce many useful intermediate artifacts that are not prototypes.
An investigation.
A design draft.
A comparison.
An implementation plan.
A transformation of supplied material.
A handoff for the next conversation.
Notes that are useful right now, but should not silently become requirements or formal design.
None of those belonged comfortably in prototypes/.
And putting them directly into plans/ created a much more dangerous problem:
an unfinished thought could start looking like an adopted project decision simply because it lived beside the real sources of truth.
So on August 1, prototypes/ became workbench/.
Repository history — Replace prototypes with a project workbench
The rough distinction became:
plans/ adopted project knowledge
workbench/ things we are still working out
The actual rules were more nuanced, but that was the important part.
A prototype could live there.
So could an investigation.
So could a candidate design.
So could the context needed to continue work in another conversation.
Most importantly:
Something did not become authoritative merely because an AI had written it down.
That sounds like a small distinction.
It became one of the central ideas of the project.
The five boxes were now in place
By this point, the top-level model had become:
plans/
etc/
workbench/
references/
products/
Those five areas still exist today.
What changed later was not primarily the number of boxes.
It was our understanding of what could move between them, what could become authoritative, what counted as evidence, and what an AI agent was allowed to conclude from each kind of information.
But that came later.
At the beginning, the goal was much simpler.
I wanted to develop software through conversation with AI without depending on the conversation itself to hold the project together.
So I gave the project a structure.
Then, almost immediately, the structure started teaching me what the harder problems actually were.
The first problem had been:
Where should this information go?
The next one would be much harder:
What does this information actually have the authority to say?
That question changed AIDD Skeleton much more than the original five directories ever did.
AIDD Skeleton is still evolving:
https://github.com/joyrswd/AIDDSkeleton
This article covers only its earliest stage.
The next stage began when I started examining the contents of those five areas more critically:
- current vs. target state,
- adopted vs. proposed information,
- normative vs. non-normative knowledge,
- verification evidence,
- and eventually whether the framework itself could be wrong.
That part of the history would eventually lead to testing AIDD Skeleton against other repositories — and treating the framework itself as something that needed to be disproved.
AI disclosure: This article was written with AI assistance. The narrative was reconstructed from the AIDD Skeleton Git history and my development conversations, and the resulting account was reviewed against the repository history before publication.
Top comments (0)