Building AiSE Kit: From Markdown Files to Multi-Agent Plugin

aisoftware-engineeringaiseopen-source

The theory is nice. But how do you actually ship it?

The AiSE Kit started life on March 23rd, 2026 as a directory called .forge/ that I manually copied into projects. Four months later it’s a plugin that works across five different coding agents. The evolution wasn’t planned. Each change was a response to something that didn’t work in practice.

Stage 1: A Pile of Markdown (March 2026)

The first commit was dead simple: a CLAUDE.md file that described the process, a set of Claude Code slash commands (forge:spec, forge:build, forge:review, forge:epic), and a .forge/ directory with folders for decisions, patterns, epics, and a log.

Everything was markdown. The process knowledge lived in CLAUDE.md. The commands were markdown files in .claude/commands/ that told the agent what to do at each step. The artifacts (specs, decisions, learnings) were markdown files the agent would create and read back later.

This worked surprisingly well for a single person on a single project. The agent had enough context from the CLAUDE.md to follow the process, and the slash commands gave it clear entry points. The .forge/ directory accumulated knowledge over time.

What didn’t work: the CLAUDE.md file kept growing. Every edge case and clarification made it longer, and longer meant more of the context window consumed before the agent even started working. I had to start slimming it down, moving process details into the command files themselves and keeping only the brief in CLAUDE.md.

Stage 2: Rename, Restructure, and the Init Script (April 2026)

By April, “Forge” wasn’t the right name anymore. The project had outgrown the metaphor. I renamed everything to AiSE, restructured the commands from colon-separated names (forge:spec) to directory-based ones (aise/spec), and added a shell script to install the kit into any project.

The bigger change was conceptual. I started writing BACKGROUND.md, the theoretical framework from Part 1 of this series. Articulating why the process worked the way it did helped me see what was essential and what was accidental complexity. The init script also mattered: it meant the kit wasn’t just something I used. Other people could install it.

Stage 3: Separating Planning from Execution (May 2026)

This was the revision that changed everything. Up to this point, the kit tried to do planning and implementation in the same flow. You’d create an epic and its stories, then immediately start speccing and building. In practice, this was a mess because planning and building have completely different rhythms.

The fix was to split into two independent tracks. The planning track creates the product brief, epics, and stories in a PM tool. The execution track picks up a story and runs it through spec-build-review-retro. The two tracks communicate through issue IDs, not shared state.

This is also when I realized that problem decomposition (breaking epics into stories, sequencing them, managing dependencies) belongs in an issue tracker, not in a pile of markdown files in the repo. The repo should own knowledge artifacts (specs, decisions, learnings, ADRs, patterns) but the planning graph (what to build, in what order, what’s blocked) should live where teams already manage work.

So I added PM provider profiles: markdown files that teach the agent how to talk to different project management tools. The first three were for Beats (our internal tool), GitHub Issues, and Linear. Each profile is a single markdown document, no code, no adapters. The agent reads the semantic instructions and translates them into the right MCP tool calls or CLI commands.

Stage 4: From Copy-Paste to Plugin (July 2026)

The init script worked, but it was fragile. It copied files into your project, which meant updates required re-running the script and hoping nothing conflicted. Worse, every project had its own copy of the process knowledge, and they’d drift apart over time.

The solution was to convert to a proper plugin architecture. Claude Code had recently shipped plugin support, so I restructured everything:

The session-start hook was the key insight. Instead of the developer remembering to load the right provider or configure the process, the hook runs automatically when you start a session. It looks at the project structure, figures out which PM tool is in use, and sets everything up. The developer just starts working.

Stage 5: Going Multi-Agent (July 2026)

The same day I shipped the plugin conversion, I realized Claude Code wasn’t the only agent people wanted to use this with. Cursor, GitHub Copilot CLI, OpenCode, and Pi all have different plugin formats, different hook systems, and different ways of injecting context.

Shell-hook harnesses (Cursor, Copilot CLI) got their own plugin manifests and the session-start hook learned to output the right JSON format per harness: snake_case for Cursor, camelCase for Copilot CLI, nested output for Claude Code.

In-process harnesses (OpenCode, Pi) got dedicated plugins that read the same bootstrap skill and inject it via message transform hooks.

The shared infrastructure is a package.json for npm-based discovery and a version-bump script to keep all four manifests in sync. The core process knowledge (the skills, providers, and behavioral contract) is written once and consumed by every harness.

What I Learned

Start with markdown. It’s tempting to build a CLI tool or a web app. Don’t. Markdown files in a repo are the only format that every coding agent can already read. Start there and only add infrastructure when the markdown approach breaks.

Separate what changes together. Planning and execution have different rhythms. Process knowledge and project knowledge have different lifetimes. Provider-specific details and universal principles belong in different files. Every time I merged things that changed at different rates, I created a maintenance burden.

The agent is the adapter layer. Traditional software needs explicit interfaces and concrete implementations. When your consumer is an LLM, a markdown file that describes how to use a tool is the adapter. This was the single most surprising insight, and the reason AiSE can support new PM tools and new coding agents with just a markdown file.

Hooks beat instructions. Telling developers “remember to run this command first” doesn’t work. Session-start hooks that auto-detect and configure are the difference between a tool that gets used and one that gets forgotten.

The compounding effect is real. Projects using AiSE for 20+ stories measurably need less per-story specification. The knowledge corpus (ADRs, patterns, learnings) genuinely accumulates and reduces the agent’s uncharted decision space. The theory from Part 1 holds up in practice.

AiSE Kit is open source: github.com/Palarix/aise-kit.