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.
It started as four places
Before creating the public repository, my first rough structure was very simple:
docs/
etc/
prototypes/
src/
The idea was mostly about separating responsibilities.
docs/ held the formal project documentation.
etc/ held development and execution environment configuration.
prototypes/ held temporary experiments and proofs of concept.
src/ held the formal implementation.
At that point, I was still thinking in fairly familiar repository terms.
Documentation goes here.
Source code goes there.
Experiments should not be confused with production code.
Environment configuration should have its own place.
The important part was not the names themselves.
It was the idea that an AI agent should not create new top-level structures simply because they were convenient for the task immediately in front of it.
Before creating something, it should first ask:
What responsibility does this belong to?
That was the first boundary I wanted the repository to provide.
Reference material turned out to be a different kind of information
The four-way split quickly exposed another category.
Projects often contain material that matters, but is not itself a project decision:
- documents supplied by a user,
- sample data,
- screenshots or designs,
- external specifications,
- PDFs,
- information from another system.
Putting those materials beside formal project documentation made their status ambiguous.
A supplied specification can influence a requirement without automatically becoming the requirement.
A sample file can be evidence without becoming part of the implementation.
So I added a separate area:
references/
The structure became:
docs/
etc/
prototypes/
references/
src/
That distinction was small, but important.
I wanted the repository to distinguish between:
information the project received
and:
information the project had actually adopted.
docs/ and src/ described file types better than responsibilities
The next problem was naming.
docs/ sounds like a place for documents.
But what I wanted to manage there was not "documents" as a file type.
It was the project's adopted knowledge:
requirements, design, testing expectations, project state, and other information that the implementation was supposed to follow.
Likewise, src/ sounded narrower than what I meant.
The formal output of a project could include implementation, tests, generated artifacts, packages, applications, or other deliverables.
So I changed the names:
docs/ → plans/
src/ → products/
The structure became:
plans/
etc/
prototypes/
references/
products/
By the time I created the public AIDD Skeleton repository on July 29, 2026, this was already the model I was using.
This was the point where the repository started moving away from classification by file type and toward classification by responsibility.
A src/ directory could still exist.
A tests/ directory could still exist.
They just belonged inside the area responsible for formal project outputs.
The first public version was still mostly about places
At that point, the public repository had five top-level areas:
plans/
etc/
prototypes/
references/
products/
Each had a different responsibility.
plans/ was for adopted 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 and other project outputs.
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 something did not fit anywhere, the first response should not automatically be to invent a sixth category.
Maybe the classification itself needed to be reconsidered.
A few hours after the public repository was created, I also simplified the README around an intentionally minimal workflow:
- Clone the repository.
- Open it in an AI development environment.
- Send the first message.
The conversation could begin normally.
The difference was that the project underneath it already had a shared structure for the developer and the agent.
At this stage, I thought the main problem was organization.
That assumption was challenged almost immediately.
Documentation could become part of the problem
One of the first things I added was traceability.
If requirements, design, implementation, and verification were related, it seemed useful to record those relationships.
But a single global traceability document had an obvious failure mode.
More requirements.
More implementation units.
More tests.
More identifiers.
More relationships.
More history.
The document intended to make the project easier to understand could eventually become another source of complexity.
So one of the first public changes was specifically about preventing TRACEABILITY.md from growing without bound.
Reference:
Prevent TRACEABILITY.md from growing without bound
This introduced an important constraint very early:
More documentation does not automatically create more order.
Documentation itself needs boundaries.
The repository also needed rules for distrusting its own documentation
Another early problem appeared when documentation and implementation disagreed.
Suppose the requirements say one thing, the design says another, and the implementation behaves differently again.
A tempting response is:
The code doesn't match the documentation. Fix the code.
But that assumes the documentation is correct.
I did not want an AI agent to silently repair implementation against an outdated, incomplete, or internally inconsistent document.
So I added an explicit ordering:
- Check whether the relevant source of truth is complete, current, and internally consistent.
- Check whether the implementation conforms to that validated source.
- Check whether verification actually demonstrates that conformity.
That was an important change in what I thought the repository needed to do.
Folders alone were not enough.
The agent also needed rules for deciding what information it was allowed to trust.
prototypes/ turned out to be too small an idea
The next structural change came from the way conversations actually produced intermediate work.
Originally, prototypes/ was intended for things like:
- proofs of concept,
- technical spikes,
- UI experiments,
- alternative implementations used to answer a question.
That seemed reasonable.
But AI-assisted development produced many useful intermediate artifacts that were not prototypes.
An investigation.
A comparison.
A design draft.
An implementation plan.
A transformed copy of supplied material.
Temporary analysis.
Context needed to continue the work in another conversation.
These things were useful, but they were not formal project knowledge.
Putting them into plans/ created a much more dangerous ambiguity:
an unfinished thought could start looking like an adopted decision simply because it lived beside the real sources of truth.
So prototypes/ became workbench/.
prototypes/
↓
workbench/
Reference:
Replace prototypes with a project workbench
The distinction became roughly:
plans/ adopted project knowledge
workbench/ work that is still being investigated, prepared, or evaluated
A prototype could live in the workbench.
So could an investigation.
So could a candidate design.
So could temporary context for continuing work later.
The important rule was:
Something did not become authoritative merely because an AI had written it down.
The structure at the time of the first article
By the time I wrote about AIDD Skeleton in early August 2026, the top-level structure had become:
plans/
products/
references/
workbench/
etc/
The names had changed from the earliest sketch, but the underlying separation was becoming clearer.
formal project knowledge → plans/
formal project outputs → products/
supplied source material → references/
intermediate project work → workbench/
execution environment → etc/
The repository was not trying to replace familiar structures such as src/, tests/, or application directories.
It was trying to put those structures inside a clearer ownership model.
The question was no longer simply:
What kind of file is this?
It was becoming:
What responsibility does this information have?
Verification needed its own boundary too
Another rule I wanted from the beginning was a strict separation between implementation and verification.
Creating a file does not prove that the program works.
Passing a syntax check does not prove that a feature works.
Passing a unit test does not prove behavior that the test never exercised.
So completion reports were expected to separate things such as:
Changes:
- Implemented the expense registration API
- Added input validation
- Added unit tests
Verification:
- Unit tests passed
- Static analysis passed
Not verified:
- Behavior against a production-like database
- Concurrent use by multiple users
The important rule was simple:
Do not claim a broader result than the available evidence demonstrates.
That rule was tightened during the same early development period.
Reference:
Tighten verification evidence scope
This mattered because AI-generated completion summaries can sound much more certain than the underlying verification actually justifies.
I wanted that boundary to exist in the repository rather than depending on the wording of a particular conversation.
Turning it into a repository template
The initial workflow was deliberately simple.
The goal was not to require a large setup prompt or a special orchestration system.
A developer could create a repository from the template, open it in an AI development environment, and begin the conversation normally.
The repository itself supplied the shared structure and working rules.
On August 7, 2026, I updated the README to make GitHub Repository Template usage the primary path.
Reference:
Make template usage the primary README path
The basic idea remained the same:
The conversation should not have to carry the entire project.
Requirements, design, implementation, experiments, supplied material, environment configuration, and verification all needed places and boundaries that could survive the current session.
What AIDD Skeleton was trying to solve at this stage
The early version of AIDD Skeleton was still fairly small in concept.
It was not an attempt to automate every part of software development.
It was an attempt to establish a few durable boundaries:
- adopted project knowledge should be distinguishable from work in progress,
- external material should be distinguishable from adopted requirements,
- formal implementation should be distinguishable from experiments,
- implementation should be distinguishable from verification,
- AI working rules should live with the repository rather than only in conversation history.
The directory names changed several times while I was figuring out those boundaries.
The progression was roughly:
docs → plans
src → products
prototypes → workbench
references → added as a separate responsibility
etc → retained
The important part was not the final names.
It was the shift from asking:
Where should I put this file?
to asking:
What responsibility does this information have?
That was the point where what began as a repository layout started to feel more like a development framework.
AIDD Skeleton:
https://github.com/joyrswd/AIDDSkeleton
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)