academy: add spec-driven development tutorial#114
Merged
Conversation
Companion tutorial to the new nextcloud-vue.conduction.nl/docs/architecture/configuration-over-code page. Teaches the schema-first, manifest-second authoring workflow without writing any Vue, and frames the same JSON contract as the safe sandbox for AI agents, citizen developers, and the OpenBuilt visual editor. Slug 'spec-driven-development' so the docs site can link to conduction.nl/academy/spec-driven-development.
The first draft framed "spec-driven development" as the JSON-manifest authoring workflow. That was wrong. Rewrite around OpenSpec as practised by Hydra: humans write Markdown specs (RFC 2119 + GIVEN/WHEN/THEN) and ADRs, an AI agent implements to them, and a sequential quality + gatekeeping harness validates the result. Covers: the OpenSpec directory layout (living specs vs deltas), the org-wide vs per-app ADR tiers governing samenhang, one-feature-one-spec, the /opsx-explore thinking stance, the /opsx-apply implementer with ADR-031 declarative business logic, the n8n/Windmill codeless path via WorkflowEngineInterface, and the 13 mechanical gates + team-reviewer + team-security review harness.
- Prerequisites rewritten: app-design-principles + manifest/schemas as knowledge prereqs, an LLM tool (Claude/Mistral/Codex/other), and the OpenSpec skills installed from the Hydra repo. - ADR section generalised: describes the org/app two-tier pattern abstractly (no link to the org set), links OpenConnector's 16 real per-app ADRs as the concrete application-level example. - New "workflow, phase by phase" section using the SetupSteps component for the opsx phase sequence (explore → scaffold → plan → apply → verify → archive), plus a stacked cn-domain-tree diagram showing the ADR tiers feeding every phase and apply outputting manifest + schema with optional code/workflows. - New "feature request to delivered functionality" section using a cn-pipeline for the end-to-end flow. - MDX fix: wrap `*`-bearing literals inside <code> in JS expressions so the asterisks aren't parsed as emphasis.
2 tasks
…cooldown The spec-driven tutorial uses the SetupSteps component, which only exists in @conduction/docusaurus-preset >= 3.19.0. The site was pinned at 3.17.0, so SetupSteps imported as undefined and crashed the MDX render at runtime (passed webpack compile, failed in the browser). - Bump @conduction/docusaurus-preset 3.17.0 -> 3.20.0. - Temporarily disable the .npmrc min-release-age=1 supply-chain cooldown so 3.20.0 (published <24h ago) installs in CI. Tracked for re-enable tomorrow in #115.
The top-level `import '@conduction/docusaurus-preset/diagrams'` ran `class CnHex extends HTMLElement` at module-eval during static site generation, where HTMLElement is undefined — crashing SSG for every /academy/ path (ReferenceError: HTMLElement is not defined, cascading to "Cannot access 'assets' before initialization" on tag/author pages). BrowserOnly defers rendering, not the import. Fix: drop the top-level import and require() the diagrams module inside each BrowserOnly render function, so the side-effect only runs in the browser.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Companion tutorial to the new nextcloud-vue.conduction.nl/docs/architecture/configuration-over-code page (PR: ConductionNL/nextcloud-vue#328).
spec-driven-developmentso the docs site linkconduction.nl/academy/spec-driven-developmentresolves.<Outcomes>(3 outcomes),<Prerequisites>(3 items),<NextSteps>(4 follow-ups).Test plan
npm start— page renders at/academy/spec-driven-development.<Outcomes>,<Prerequisites>,<NextSteps>components mount.nextcloud-vue.conduction.nl/docs/...andconduction.nl/apps/openbuiltare reachable./academy?type=tutorial) includes the new tutorial.