WikiSpec

This repository contains Wikispec - a spec-driven development framework that maintains a "Karpathy style" LLM wiki. Wikispec is to a large extent inspired by OpenSpec (and in fact, wikispec has been bootstrapped with OpenSpec), but also influenced by Superpowers and of course the LLM wiki idea.

Spec driven development with AI is still a new and rapidly evolving area, and you will probably not find any two developers on this planet that share the same set of principles and opinions on this. Still, here is my take.

• Spec drift is inevitable. I am struggling to believe that in a larger software project, we will ever be able to keep a full, consolidated written specification in-sync with the code. So let us accept this and specs as a tool to organize thoughts (ours and that of the agent) and to implement a change in a structured way, capturing its intent as precisely as possible and unveiling decisions that the agent would otherwise silently take without us ever noticing
• I do, however, strongly believe in the importance of traceability and testing. Once a change has been implemented, the truth is in the code and the automated test cases (after all, this is how you decide whether you push the code into production), so let us spend our time and effort in making sure that every requirement is properly reflected in the test cases
• The key to applying AI-driven development at scale will be the availability of knowledge for agents and humans that is sufficiently condensed to not pollute the context but still provides starting points for agents and human workers for deeper research if required
• A workflow is a tool and should not be mandatory - if you want to do smaller changes directly or even manually that is completely fine and you should be able to do so as long as you know what you are doing

This is of course experimental - at the time of writing, nobody really knows how these ideas will work at scale and one or two years into a large project. Still, I thought it is worth giving it a try. If you like the idea take it, play with it, apply it - and let me know how if it works for you.

Quick start

You will need a fairly recent version of Node.js installed (I have used v24.14.0)

git clone https://github.com/christianb93/wikispec.git
cd wikispec
npm install
npm link
cd ...              # head over to your project directory
wikispec init       # create wikispec directory structure
wikispec install    # install skills and agents in .claude

and then, in Claude

/wikispec-propose my-first-change

Note that, for the time being, wikispec is designed to work with Claude, but it should be easy to adapt it to other agents (adapt skills and agent definitions, adapt src/commands/install.js to install in whatever directory your agent uses).

The default workflow

┌──────────┐       ┌──────────┐       ┌──────────┐       ┌──────────┐       ┌─────────────┐
│  propose │──────▶│   plan   │──────▶│   apply  │──────▶│ validate │──────▶│   archive   │
└──────────┘       └──────────┘       └──────────┘       └──────────┘       └─────────────┘
     │                  │                  │                  │                    │
  spec.md            tasks.md         implement        validation-report.md  update wiki
 design.md                               test                                archive files

To start the workflow, run the /wikispec-propose skill and describe what you want to build. This will create two documents:

• spec.md - this is the specification capturing intent, goals and non-goals and spelling out the requirements
• design.md - this is focussed on how to implement the requirements

At this point, you have a chance to review both documents. If you want to make changes, there are several options to do so.

• change an artefact manually, delete all downstream artefacts and re-run. If, for instance, you make a change to spec.md, you can simply delete design.md and repeat /wikispec-propose.
• ask the agent to make changes to both documents in a consistent manner
• edit both documents manually - then it is on you to preserve consistency

Once you are happy with specs and design, run /wikispec-plan to create the task list. Again, feel free to add, remove or change tasks as you like, then run /wikispec-apply.

This will trigger the implementation phase, where wikispec will create instructions to implement using the wikispec-coding-agent and to write unit tests using the wikispec-tester-agent. The tester agent is instructed to link test cases to requirements using comments.

Once implementation is complete, move on to the validation phase by running /wikispec-validate. This will spawn the wikispec-validator-agent that

• checks whether all requirements are covered by tests
• re-runs all tests
• performs a code review
• creates a validation report

Finally, the last step - /wikispec-archive - will archive the created markdown files and ingest the change into the wiki. Future proposals, specs and design will then query the wiki and use the information that they find, and future /wikispec-archive commands will update the wiki, feeding the changes back, so that over time, your knowledge base grows and stays up-to-date.

How it works: workflows, steps and artifacts

Here, a workflow defines how we implement a change. A workflow defines artifacts and steps. An artifact is defined by an ID (the key in workflows.json), a path which is the file name of the artifact that it generates (relative to the project root directory), for instance

wikispec/changes/active/{change}/design.md

and instructions for the agent how to create the artifact. When the path is evaluated by wikispec, the string {change} is replaced by the name of the current change.

A step consists of instructions how to run this step which apply if all artefacts have already been created for this step (or if a step has no artifacts), a list of artifacts, a list of other steps on which this step depends and a completion strategy which defines when this step is considered to be complete.

When an agent works on a change, it repeatedly invokes wikispec instructions with the step and change as argument (similar to how OpenSpec works, I really like the idea - probably wikispec could also be re-implemented as an OpenSpec workflow). This command works as follows.

• if the step is already complete, it prints a completion message
• if the step is not yet complete, it checks whether there are any artifacts that have not yet been created, i.e. are not present on the file system
• if yes, it picks the first artifact that does not yet exist and prints out the instructions for this artifact
• if no, it prints the instructions for the step

As the artifacts within a step are created sequentially, you can, at any time, delete an artifact and re-run the step, and the workflow will re-generate the missing artifact.

Directory structure

When wikispec is initialized for a given project by running wikispec init, the following directory structure is established in the project root

wikispec/
├── changes/
│   ├── active/       ← changes currently in progress
│   └── archived/     ← completed and archived changes
└── wiki/
    ├── <topic 1>/    ← documentation for one topic
    ├── .../
    └── <topic n>/