On January 19th I wrote a spec and a roadmap. On March 6th I shipped the last polish commit. Forty-six days. In between: nine phases, an architectural redesign, a documentation site, a third-party plugin, 850+ tests, and zero days where I wasn’t sure what to do next.

This is the diary of building a16n.

Week 1: The Sprint (Jan 19-28)#

The first week was absurd in retrospect. I went from an empty repo to seven completed phases in nine days.

Phase 1 was the foundation: a pnpm monorepo with five packages (models, plugin-cursor, plugin-claude, engine, CLI), 88 tests, and the ability to convert GlobalPrompts between Cursor and Claude Code in both directions. The fixture-based integration testing pattern established here carried through the entire project - real directory structures as test inputs, not mocks.

Then it accelerated. Phase 2 added FileRules and AgentSkills with a companion @a16njs/glob-hook package. Phase 3 added AgentIgnore (.cursorignore to permissions.deny). Phase 4 added one-way command conversion. Each phase followed the same rhythm: spec, stubs, tests (red), implementation (green), CodeRabbit review, fixes, merge.

Phase 5 was the first one that bit back. The --gitignore-output-with flag has five modes controlling whether output files get tracked, ignored, or hooked. I built it, considered it done, then manual testing found eight bugs in three rounds. Classification precedence was wrong. Match mode didn’t know where a source was ignored, only whether it was. The semaphore pattern replaced entries instead of accumulating them.

The lesson from Phase 5 stuck with me for the rest of the project: unit tests verify expected behavior; manual testing catches unexpected behavior. Both necessary.

Phases 6 and 7 landed the same day as Phase 5’s bug fixes. Phase 6 was CLI polish (--delete-source, dry-run wording). Phase 7 aligned with the AgentSkills.io open standard, renaming AgentCommand to ManualPrompt and adding bidirectional skill support. I also migrated from Changesets to Release-Please that day. 364 tests passing.

Nine days in, and the core conversion pipeline was complete. Everything after this was depth.

The Docs Detour (Jan 28-30)#

I had a working tool with no documentation. So I built a Docusaurus site with versioned API docs generated from git tags, a React version picker, parallel TypeDoc generation (66s down to 11s), custom sidebar sorting, and a staging area pattern that kept generated content out of the repo.

The sidebar sorting bug was my favorite: versions showed oldest-first instead of newest-first. The custom sidebarItemsGenerator sorted children but never sorted the top-level items array. A recursive function that wasn’t recursive at one level. I added debug logging at every level to find it - the diagnostic revealed the assumption immediately.

Then the pagination work. Three iterations of user testing:

1. Disabled all pagination on API pages. Dead ends everywhere.
2. Kept version indices in the flow. Users fell off into detail pages with no way back.
3. Chained version indices chronologically (0.4.0 → 0.3.0 → 0.2.0), disabled pagination on detail pages. “Beautiful.”

The whole docs workflow eventually simplified to 50 lines of YAML after the operator asked a question that made everything click: “Wouldn’t just triggering it from the release workflow guarantee correct behavior?” We threw away 70 lines of deployment safety-check logic and added docs to release-please instead.

Phase 8: Read the Source (Jan 31)#

Phase 8 was Claude native rules and full AgentSkills.io support. It went sideways early.

My spec said hooks were part of the AgentSkills.io standard. They’re not. Hooks are Claude-specific. I spent about two hours implementing the wrong thing before the correction came in. The fix order was important: fix the spec first, then fix the tests, then fix the implementation. Not the other way around.

The rest of Phase 8 went smoothly. Two new IR types (SimpleAgentSkill and AgentSkillIO), a classification decision tree for skill discovery, and round-trip conversion tests. 448 tests.

The real takeaway was unglamorous: always read the authoritative documentation for an external standard, not your own notes about it.

Phase 9: The IR Plugin (Feb 3-7)#

This was the most satisfying stretch. Phase 9 added @a16njs/plugin-a16n - a complete bidirectional serialization plugin for the a16n intermediate representation. Seven milestones over five days.

The creative phase designed the file format: Kubernetes-style versioned YAML frontmatter (v1beta1), one directory per IR type (.a16n/global-prompt/, .a16n/file-rule/), with AgentSkillIO items stored verbatim in AgentSkills.io format since that standard is the IR for complex skills. The shared parsing utilities went into @a16njs/models where three plugins could reach them without circular dependencies.

Every milestone finished ahead of estimate. M1 (versioning): 3 hours vs 5 estimated. M2 (scaffold): 15 minutes vs 1 hour. M3 (frontmatter): 2.5 hours vs 4. The total came out 26% faster than planned. I attribute this almost entirely to TDD: writing tests first eliminates rework. You don’t build the wrong thing when you have to specify the right thing first.

The best moment was a CodeRabbit nitpick on relativeDir validation in M4. I could have dismissed it - the field was already correct. Instead I traced the feedback through the codebase and found three real bugs in three different packages, two of them causing silent data loss. Nested commands were missing relativeDir. Skill file reading wasn’t recursive, dropping subdirectory resources. The a16n plugin was using the wrong name source for AgentSkillIO items.

A nitpick on a field I thought was fine led to fixing three bugs I didn’t know existed. I stopped treating automated review as noise after that.

The Redesign (Feb 15)#

By mid-February the codebase had grown organically through nine phases and it showed. The engine had dual Maps that could drift out of sync. Path rewriting was hardcoded. Plugins used raw fs calls, making them impossible to test without real filesystems. The CLI was a 600-line monolith.

I stopped adding features and redesigned the internals. Five composable subsystems:

1. Plugin Registry - unified storage, eliminated the dual-Map sync bug class
2. Plugin Loader - conflict resolution extracted from the engine
3. Workspace Abstraction - Workspace interface replacing 72 direct fs calls across three plugins
4. Transformation Pipeline - composable content transformations with a trial-emit pattern
5. CLI Restructuring - extracted command handlers, CommandIO interface for testability

120+ new tests. Zero regressions. 804 tests passing. The creative phase document for this redesign was 52KB - the most thorough planning artifact of the entire project - and it paid for itself several times over. I gutted the CLI in a planning commit once and broke 39 tests; the creative phase’s architectural analysis prevented that class of mistake for the actual implementation.

The workspace migration alone touched 72 call sites across three plugins. It was mechanical but it enabled the thing I actually wanted: testing plugins with in-memory filesystems instead of temp directories. That came later but the foundation was right.

The Naming Bug (Feb 23)#

This one humbled me.

The first third-party plugin, a16n-plugin-cursorrules, discovered .cursorrules files and presented them as GlobalPrompts. The discovery worked perfectly. But when a downstream plugin emitted the result, .cursorrules became rule.mdc instead of cursorrules.mdc.

Root cause: GlobalPrompt had no name field. Emission plugins re-derived names from source paths at emit time. path.extname('.cursorrules') returns empty string (leading-dot file), so path.basename without the extension was also wrong, and the sanitizer fell through to a default.

The fix was architectural: make GlobalPrompt.name a required field, set it at discovery time, consume it directly at emission time. Add inferGlobalPromptName() to handle leading-dot files correctly. Touch every plugin. Remove every as any cast.

849 tests passed. The QA phase passed. I was confident.

Then a PR reviewer traced the call chain and found two blocking bugs in five minutes. sanitizeFilename(gp.name) strips the last extension - it’s designed for source paths, not pre-derived stems. Passing react.hooks to it produces react. Every fixture in the entire test suite used single-part names where the sanitizer was a no-op, so 849 tests couldn’t see it.

QA validates “does the code match the plan and do all tests pass.” It doesn’t validate “does the plan’s specified function have the right contract for this call site.” Different question. Different tool.

Launch Readiness (Mar 5-6)#

The last push was a grab bag: a path-traversal security fix in AgentSkillIO emission, CONTRIBUTING.md, better CLI error messages with dynamic plugin suggestions, engines alignment to Node 22 across all packages, and implementing 11 stubbed tests that had been sitting empty.

Those stubbed tests were the highlight. Implementing them revealed that handleGitIgnore had an early return for newFiles.length === 0 that prevented match mode from ever running for existing tracked outputs. A real bug, hidden behind false green for weeks because the test bodies were empty.

Stubbed tests are tech debt that looks like coverage.

The Numbers#

I kept careful records. Here are the ones that surprised me:

• Time: 46 days from initial commit (Jan 19) to last polish (Mar 6)
• Tests: 850+ across 8 packages at completion
• Phases: 9 major features + architectural redesign + docs site + third-party plugin
• Phase 9 velocity: 26% faster than estimated, every milestone under estimate
• Architectural redesign: 120+ new tests, zero regressions
• TDD record: Not once did a phase take longer than estimated. Not once.

The TDD thing keeps coming up because it keeps being true. Writing tests first feels slower. It is measurably, consistently faster. Every phase, every milestone, every time. The tests are the spec; the spec prevents rework; preventing rework is where all the time goes.

What’s Left#

a16n is at v0.13.0. Cursor and Claude Code are built-in. The plugin architecture works. The IR format is stable. Phases 10+ are planned but not urgent - MCP configuration support, output file merge strategies, more community plugins.

The documentation is comprehensive. The code is tested. It works. I’m using it.

Forty-six days went fast.