Skip to content

Development Workflow

This section describes how the maintainers actually build IOU Architecture features — day to day, AI-assisted, and distinct from the human contribution process that outside contributors follow. If you read only one page in this subsection, read this one.

The pipeline, stage by stage:

1. Design

For medium-to-large features where fundamental UX is at stake, design comes first, in Claude Design. Small changes skip this stage entirely and go straight to implementation.

2. Handoff

A design leaves Claude Design as a handoff package: the design itself, standalone HTML, screenshots, a README, and a PROMPT. The package is briefing material for the next stage, not something that enters the repository as-is.

3. Implementation

Implementation happens in Claude Code, with claude-mem capturing session memory by default. Depending on the size of the change, work proceeds either inline or through the superpowers plugin. Either way it follows red/green TDD: the failing test comes first, then the minimum code needed to make it pass.

4. Release

A release is cut with /bump-release, a command defined per repository — each component keeps its own version, tailored to its own changelog format. It also regenerates the release's SBOM in all three repositories, and in the RONL Business API it runs the full test suite before the release commit, because a version bump is input to tests that read a package.json.

A release lands through a pull request, not a local fast-forward. The supply-chain gate is in place in all three application repositories — the CPSV Editor and the RONL Business API from August 2026, the Linked Data Explorer since v2026.08.7 — so acc requires a pull request with no bypass actors, and the older flow of merging acc locally and pushing it is rejected outright: a locally created bump commit has never been through CI. Merging the pull request is the push, and triggers the acceptance deploy.

Since 19 September 2026 that pull request must also pass the build and deploy checks, not only audit and scan — so a release whose suite is red cannot be merged. Expect the release pull request to sit until CI is green rather than to be waved through.

A release pull request is merged, never squashed and never rebased — the changelog entry cites each commit by SHA, and both alternatives rewrite those hashes. Squashing collapses the commits into one new commit; rebasing replays them as new commits, deceptively, since it preserves the commit count while replacing every hash. Either orphans every citation in the entry.

Since September 2026 that is enforced by repository settings rather than by remembering: all three repositories allow merge commits only, with delete_branch_on_merge enabled. GitHub's default button is Squash and merge, so without the setting one absent-minded click would orphan a release's entire entry. A side effect is that Renovate's dependency pull requests land as merge commits too, which costs nothing — the changelog range already excludes merge commits, and the underlying update commit is what an entry should name.

Production is a second pull request, acc → main, and what a push to main then does differs by repository. In the Linked Data Explorer (since v2026.09.7) and the RONL Business API (since v2026.09.10) it starts one ordered workflow, Promote to Production: a changes job decides which targets the promotion touches, the backend deploys first, and each site deploys only if the backend succeeded or was skipped. The production deploy workflows no longer trigger on the push themselves; they are called by the promotion. The CPSV Editor has no backend and keeps a single Deploy PROD workflow that runs on the push to main.

5. Documentation

Once a component has shipped, /iou-document-patch — defined once, in this documentation repository — brings that component's pages into sync with the new release. Its weekly pass re-checks these contributing pages against the repositories themselves.

Where to go next

This page is a map, not the territory. The rest of the subsection covers each stage in more depth:

  • Design & Handoff — when a feature warrants Claude Design, and what the handoff package contains
  • Working with Claude Code — claude-mem, inline work versus the superpowers plugin, and red/green TDD in practice
  • Skills & Boundaries — user-level versus project-level capabilities, the plugin set, and the working rules every session follows
  • Code Standards — what lint, format, hooks and CI actually enforce, measured per repository
  • Supply-Chain Pinning — what makes a CI check a gate, and what the gate deliberately does not protect

For the process outside contributors follow instead, see the Contributing overview.