36 posts tagged with "Tutorial series"

The first three parts of this series set up the registers, the files, and a public catalog for Dutch open-government data. Conduction also has a three-tutorial pipeline that teaches the same three apps from the ground up, end to end, on the canonical Pet Store sample:

1. Model and manage your data with OpenRegister — registers, schemas, relations, objects, search, versioning, permissions.
2. Pull external data into your register with OpenConnector — a source, a mapping, and a scheduled synchronisation.
3. Publish a public catalog with OpenCatalogi — scope a catalog, publish with a date rule, expose a DCAT-AP-NL feed.

This capstone is the Woo & DCAT overlay on that pipeline. Rather than repeat the mechanics, it points you at each deep tutorial and then layers the open-government specifics on top: the canonical registers you import instead of hand-building, the open-data source you map to a Dataset, and the DCAT-AP-NL feed that national portals harvest. The shape is identical to the Pet Store chain — grab data from a source, and publish it on a catalog — only the domain changes.

In Part 1 you imported a DCAT register for open data. In this tutorial you make its datasets findable: you scope a catalog to the register, set one date field that controls visibility, and expose the catalog as a DCAT-AP-NL feed. National portals like data.overheid.nl harvest that feed.

In part 5 you started Hydra by hand: build the images, run the supervisor, label an issue. That is the right way to learn Hydra, but it is not how it runs day to day. In production nobody runs hydra-supervisor.sh from a terminal. Instead the forge itself triggers the pipeline when an issue is labelled, pulls pre-built images from a registry, and runs each stage as a CI job. This part explains that path, and the three deployment models behind it.

Most teams already write down what they are going to build. They open a ticket: "As a user I want a search box, so that I can find pets quickly." That sentence has served software teams for twenty years. At Conduction we write specs instead. The reason is simple: the developer reading the ticket is now an LLM, not a colleague, and an LLM needs a different kind of brief. This opener explains why, before the rest of the series gets into the how.

A spec tells you what one feature must do. But "build a search box" leaves a hundred questions unanswered that have nothing to do with search. Which data layer? Vue 2 or Vue 3? Where do modals live? Which licence header? Answering those per spec would be madness, and an AI would answer them differently every time. That is what ADRs are for. They are the standing context that every spec is built on top of. This part explains what they are, how they are written, and how Conduction splits them across the fleet.

In Part 1 you learned that a scenario describes behaviour in GIVEN / WHEN / THEN form. In Part 2 you wrote one. This part closes the loop. A scenario is a test you have not run yet, and OpenSpec gives you a mechanical way to prove that every scenario in a spec is exercised by a real browser test. The @e2e annotation and the gate that enforces it are what turn "write a spec" into a safe sandbox for AI. They are also the single biggest thing that separates spec coding from vibe coding.

Heads up — this is an optional, situational tutorial. Most developers will never need to run a retrofit. Day-to-day work in a Conduction app — writing changes, implementing tasks, opening PRs — doesn't touch any of the commands below. You can finish Parts 1 + 2 and go straight to the Hydra series or the Claude skills series without losing anything.

This part is only relevant in one specific case: an older Conduction app needs to be brought up to date with the current OpenSpec convention after the fact. A small number of our apps were built before openspec/specs/ and the @spec-tag convention existed — they have working code, but no specs and no annotations pointing from code to requirements. If one of those apps ever has to be brought into line with the convention, this is the playbook for it. We work through the retrofit playbook end to end.

By Part 6 your PetStore app is shipped and integrated. Along the way the manifest renderer mounted a handful of nc-vue components for you (CnAppRoot, CnPageRenderer, CnIndexPage, CnDetailPage, CnDashboardPage, CnObjectSidebar, CnMarkdownEditor) and Part 5b walked through the dashboard widget vocabulary. The lib ships ~70 Cn* components and a dozen composables. Part 7 is the capability tour: which component to reach for when, what the composable layer does for you, and how the whole library fits together so you stop guessing.

This is a tour, not a reference. The full prop tables live on nextcloud-vue.conduction.nl. Use Part 7 to build the mental map; use the lib docs to look up signatures.

A 45-minute tutorial that gives your PetStore app a documentation site. Hosted from your own Codeberg or GitHub repo via the central documentation workflow, illustrated with abstract screen mocks that compose from design tokens, and brought to life with real screenshots that Playwright captures from your running app. By the end, every push to development rebuilds and republishes.

A working Conduction workstation needs a specific combination of tools: Claude Code, Docker, Nextcloud running locally, Playwright, a handful of global Claude settings and hooks, and a working gh CLI. New developers often lose their first day (or two) to setup puzzles we've already solved internally. This six-part series gets you from a clean laptop to a working workstation in one evening. Part 1 — this one — answers the question what do you install, and why before you start clicking through installers.

This is the part with the most install commands. WSL2, Docker Desktop, VS Code with the right extensions, the language runtimes (Node, PHP, Composer), the CLIs (gh, OpenSpec), and the Playwright Chromium binary. By the end of Part 2 you'll have a working dev workstation — just without Claude Code wired up yet. That's Part 3.

With the runtimes in place from Part 2, it's time to add the AI pair programmer we actually work with: Claude Code. This part covers the install, the sign-in, and — the bit you should not skip — the mandatory global settings and safety hooks that keep Claude from running destructive shell commands without your approval. Short part, important part.

MCP — Model Context Protocol — is the standard interface Claude Code uses to call out to external tools. Inside a Conduction project, that means two things in practice: a Playwright browser pool (browser-1 … browser-7) for the testing skills, and the OpenRegister MCP server for direct access to your local Conduction data layer. A workstation isn't really complete until at least the browser pool is wired into your project root via .mcp.json. This part covers that; the OpenRegister MCP server has its own tutorial — we link to it at the bottom.

A workstation without a Nextcloud is half a workstation. Nearly every other tutorial in the academy assumes you have one running on localhost:8080. The good news: a dedicated tutorial already covers this end to end. This module is a short bridge that explains why you do it now, which Conduction apps to install once it's up, and how this part connects to the rest of the series.

Your workstation is complete. WSL2, Docker, VS Code with the right extensions, Claude Code with the safety hooks live, the MCP browser pool connected, Nextcloud running locally with the apps you need. Take a moment to feel good about that — most new Conduction developers used to lose one or two days to this; you've done it in one evening. This last part is a short map of the next tutorials, grouped by what kind of work you'll do.

This is Part 5 of the nine-part app-building tutorial series. Parts 1–4 got you a working app: scaffold, schemas + manifest, schema-driven Calendar integration, and a custom Care tab. Part 5 is the "now what": the v2.7.0 manifest features Parts 1–4 deliberately skipped so the learning curve stayed gentle. You don't need any of them to ship PetStore, but the moment your app needs a public form, a wiki, an admin-only listing, or a markdown editor inside a form, they save you from another round of hand-rolled Vue.

Three principles run through every feature in this part: schema-driven (no per-page Vue), type-safe (the manifest schema validates every shape before runtime), and fleet-portable (the same JSON works in every Conduction app and gets lib upgrades for free).

This is Part 6 of the nine-part app-building tutorial series. Part 4 packaged the app and put it on the Conduction store; this part makes it talk to the rest of the workspace: three integration patterns layered from least to most invasive. By the end your orders know who their supplier is, every order shows the right care guide from xWiki, and a needs_followup order automatically opens a maintenance page in xWiki that flips the order back to delivered when the page is marked resolved.

The point isn't the specific integrations, it's the pattern. Cross-register reads are how Conduction apps share data without coupling. The OpenConnector source-and-synchronisation pattern is how you absorb data from anywhere into your own register. The webhook endpoint pattern is how external systems push state back. Once you've wired all three, you've covered the integration vocabulary the rest of the catalogue uses.

Part 4 of the nine-part app-building tutorial series. Part 3 made orders appear in NC Calendar with one schema annotation. Part 4 brings external knowledge, category-specific care advice, husbandry notes, feeding tips, from xWiki into the pet detail sidebar via a care_guide OpenRegister schema. Then we package the app and ship it.

External knowledge integration is the canonical case for OpenConnector. Pull data from a system you don't own (xWiki here, but the same applies to Confluence, Notion, SharePoint, Decos, Mendix), surface it inside Nextcloud-native UI without making the user context-switch.

This is Part 3 of the nine-part app-building tutorial series. Part 2 wired the pet and order schemas. Part 3 makes those orders appear in every user's Nextcloud Calendar (without writing a controller, an event listener, or any per-app calendar glue).

The trick: OpenRegister already ships an ICalendarProvider (RegisterCalendarProvider) that exposes any schema with a calendarProvider block as a virtual calendar. You declare the block on the order schema. NC Calendar shows the events. That's the whole story.

Claude Skills are the mechanism for extending Claude Code with reusable, specialised behaviours. Think of Conduction's own /review-pr, /opsx-new, or the whole hydra-gate-* family: each one is a skill. This first part explains in ten minutes what a skill is, how it gets activated, and when you should not write one. It's part 1 of a four-part track; by the end you'll be ready to write your own in part 2 — and in part 3 we introduce the 7-level maturity framework that takes a skill from "feels good" to "measured good" (part 4 continues with L6 and L7).

In part 1 you saw what a skill is. In this part you'll write one yourself: a working git-status-summary skill that produces a readable summary of the current working tree. At the end it sits in your ~/.claude/skills/ folder, you can invoke it via /git-status-summary, and you'll know how to share it with your team.

You now have a working skill — but does it actually work well? And does it keep working when Claude itself gets upgraded or when you tweak the skill? This third, optional part shows how to evaluate a skill systematically: test scenarios, trigger tests, a baseline measurement, and the eval runner that /skill-creator sets up for you. This is the step from Maturity Level 4 ("feels right") to Level 5 ("measurably right").

In part 3 you took a skill from "feels right" to "measurably right" — Maturity Level 5. For most skills that's enough. But for a handful of skills you use daily, or that steer other skills, you want to go further: a skill that learns from its own executions (L6), and a skill that steers other agents inside a larger workflow (L7). This fourth part shows how you get there — and how the Hydra dashboard lets you monitor your whole skill library for maturity at once.

This is Part 2 of the nine-part app-building tutorial series. Part 1 left you with an empty app shell, a chassis, no data. Part 2 fills the chassis: three schemas (modelled on the OpenAPI Pet Store), a manifest, and the same five Cn* pages drive every list, every detail view, every dashboard with the schema as the single source of truth.

The shape we keep saying "this saves you code" finally has numbers behind it: ~200 lines of hand-rolled Vue collapse to three.

Hydra is Conduction's internal agentic CI/CD platform: a factory that turns OpenSpec proposals into reviewed, tested code on a feature branch. This module explains in ten minutes what Hydra is, why it exists, and how it fits inside our app factory. It is the first part of a six-part series; by the end you're ready for part 2 on the three pipelines.

In part 1 you saw that Hydra has four personas. In this part we look at the pipeline: how those personas work on one issue one after another, which labels mark the transitions, and when the pipeline diverts to needs-input. By the end you'll know Hydra's label state machine inside out and you'll be able to steer an issue back to the right phase if it gets stuck somewhere.

In part 2 you saw that the three personas are backed up by mechanical quality gates — checks that pass or fail deterministically, without AI in the loop. This part explains which gates we have, why they are mechanical, and how to handle the exception: the false positive.

The previous parts were about what Hydra does. This part is about how: the skills that let the personas do their job. By the end you'll know which skills the automated pipeline (the "Hydra factory") runs and which ones you call yourself as a human, you'll know the five families, and you'll be able to judge when a new skill is worth writing.

The first four parts were about concept, pipelines, gates and skills. Time to actually run. In this part you start a full Hydra run on a target app, paying attention to the practical pitfalls: tokens, images, and — if you work with multiple devs against the same repos — the HYDRA_LABEL_PREFIX trick.

In part 5 the pipeline was running. Now the final part: what do you do when it doesn't go green? This part gives you the decision tree — ordered from cheapest intervention to most expensive — and the patterns that get needs-input issues moving again.

OpenSpec is a lightweight framework for spec-driven development: first write down what a feature should do, only then write the code. In this twelve-minute module you'll learn what OpenSpec is, which concepts it builds on, and why we use it underneath almost every Conduction project. By the end you're ready for Part 2, where you'll actually write your first change.

Want the bigger picture first? For where this idea comes from and why it matters more in an AI world, start with Part 0: Why spec-first. This part dives straight into the concepts.

Your starting point. You don't need to build anything special to follow along. Just clone any Conduction app and read along in its openspec/ folder:

git clone https://codeberg.org/Conduction/openregister.git
cd openregister && git checkout development
ls openspec/          # specs/, changes/, changes/archive/

development is the branch active work happens on. We won't change anything in this part — we're just looking.

Time to see OpenSpec in action. In this part you'll create your first real change inside a Conduction project — from empty folder, through a spec-delta with a requirement and scenario, to a validated proposal ready for implementation. We do that with the Claude Code skills /opsx-new and /opsx-ff.

This is Part 1 of the app-building tutorial series, the hands-on chassis lap. If you haven't read Part 0: Three paths, one curriculum yet, that's the orientation that explains why we build on this stack rather than raw Nextcloud, and how the manifest and @conduction/nextcloud-vue work as two intertwined surfaces. Part 1 picks up after that decision is made.

You'll build PetStore, a Nextcloud app on top of the OpenAPI Pet Store domain (pets, orders, categories, tags) on the full Conduction Nextcloud stack. The end product: add pets to the store, place orders, see order ship-dates in your Nextcloud Calendar, and surface category-specific care guides from xWiki right next to each pet. Every piece reuses what @conduction/nextcloud-vue and OpenRegister already give you for free.

In Part 1 you scaffold the app, rename it, build it, and see the canonical app chassis on screen. No data, no integrations yet. We get the bones right first.

A Woo publication without files is metadata without evidence. In this tutorial you attach documents to a publication through the OpenRegister interface, choose which ones are public, and remove them again. An appendix covers the API, for scripts and for files too large for a browser upload.

The Dutch Open Government Act (Woo) asks government bodies to publish documents in set information categories. Open data is published as datasets in the DCAT-AP-NL standard. OpenRegister stores both. In this tutorial you import two registers, the Woo register and a DCAT register, using only the OpenRegister interface.

This is Part 0 of the nine-part app-building tutorial series, the orientation lap. Before scaffolds, schemas, or manifests, the most useful thing we can hand a new developer is an honest map of the three ways Conduction apps actually get built, what each one costs, and what each one gives back. The rest of the series picks one path and shows the receipts. Part 0 explains why.

A second thing matters from minute one: the manifest system and the @conduction/nextcloud-vue component library are two different surfaces. The manifest is the declarative what, a single manifest.json that describes navigation, pages, configuration. nextcloud-vue is the rendering how, the Cn* components the manifest dispatches to (CnAppRoot, CnPageRenderer, CnIndexPage, CnDetailPage, CnDashboardPage, and the rest). They are technically separable. They are also so intertwined in practice that the rest of this series teaches them together, and every lesson names which surface it is touching.

The series uses the OpenAPI Pet Store as the running example: pets, orders, categories, the same entities every API developer has met before. It's the canonical sample domain across the Conduction academy. By the end of the series you have a working PetStore app on the Conduction stack and the mental model to build your own real app on the same patterns.