DOCSEARCHbyAlgolia
Submit Docs

Conduction Documentation

website·Indexed 33 days ago

https://docs.conduction.nl

Internal engineering and operational documentation for Conduction, featuring the spec-driven development workflow. Includes details on the Specter intelligence-to-spec and Hydra spec-to-code pipelines, OpenSpec commands, Nextcloud app development standards, and organizational Way of Work.

Tokens
110.2K
Snippets
386
Records
774
Agent score
65%

What's inside Conduction

  1. Overview of the three-phase app renaming process

    Renaming an app is divided into three separable phases to manage risk. Each phase can be shipped independently, with risk increasing in later stages.

    1. Display names: Update web properties, documentation, info.xml names, and READMEs. No risk as these are not used for resolution.
    2. Repository name: Rename the GitHub repository using gh repo rename. Low risk due to GitHub's automatic redirects for URLs, clones, and PRs.
    3. App ID: Update the <id>, PHP namespaces, routes, l10n domains, and frontend URLs. This is a high-risk data migration.

  2. Overview of Hydra Agent Personas

    Hydra utilizes named agent personas, each running in a dedicated container with a unique GitHub identity, skill set, and CLAUDE.md instructions. The primary personas include:

    • Al Gorithm (Builder): Handles implementation, quality fixes, and PR creation. Uses opus for builds and sonnet for fixes.
    • Juan Claude van Damme (Code Reviewer): Performs code reviews for correctness, style, and architecture using sonnet.
    • Clyde Barcode (Security Reviewer): Focuses on code-level security vulnerabilities using sonnet.

    To force a specific model for all agents, set the HYDRA_MODEL environment variable.

  3. Overview of Hydra Pipeline Agents

    The Hydra pipeline uses four containerized personas (agents) to move changes from ready-to-build to a draft PR. Each agent operates in an ephemeral container with scoped permissions and a specific responsibility.

    PersonaSlugRoleContainerModelMax Turns
    Al Gorithmal-gorithmBuilder: Implements changes against OpenSpec proposal, pushes feature branches, opens draft PRs.hydra-builderopus200
    Juan Claude van Dammejuan-claude-van-dammeCode Reviewer: Reviews PRs and posts findings. Has fix authority (per ADR-013 no-loop policy).hydra-reviewersonnet200
    Clyde Barcodeclyde-barcodeSecurity Reviewer: Performs SAST analysis and posts findings. Has fix authority.hydra-securitysonnet150
    Axel Pliéraxel-plierApplier: Acts as a binary go/no-go gate after reviews. No fix authority.hydra-appliersonnet20

    Configuration is managed via agents/base.yaml (shared) and individual config.yaml files for each agent.

  4. Overview of the Conduction Work Pipeline

    Claude operates as an architect and orchestrator using a four-stage pipeline. Instead of writing raw code, it defines, configures, and validates the system using platform building blocks.

    • Stage 1: Obtain: Discovery and requirements gathering. Exploring issues, existing apps, and documentation without making changes.
    • Stage 2: Specify: Creating structured OpenSpec artifacts (blueprints) that guide implementation.
    • Stage 3: Build: Configuration and assembly. Defining schemas and wiring components.
    • Stage 4: Validate: Quality assurance and verification.

  5. Overview of Conduction's spec-driven workflow

    Conduction utilizes a spec-driven workflow powered by the Hydra pipeline and Claude Code with a specialized skills catalogue. This workflow allows developers to set up workstations, write specifications (specs) and skills, submit changes to the pipeline, and perform reviews. The system integrates specs, tracking issues (primarily on Codeberg, with GitHub as a fallback), and plan.json files to manage the development lifecycle.

  6. Overview of the Conduction Engineering Pipeline

    The Conduction engineering pipeline is a four-layer architecture designed for traceability and quality assurance, mapping every code change back to a requirement (ISO 9001:2015 compliance). The flow is:

    1. Specter (What & Why): Processes intelligence, tenders, and features into OpenSpec change proposals.
    2. Hydra (How): Acts as the builder and reviewer, turning specs into code and tests (Draft PRs).
    3. Quality CI Workflow (Gatekeeper): Automated validation via quality.yml (PHPCS, Psalm, PHPStan, PHPMD, ESLint, Newman, Playwright, audits, SBOM).
    4. Human Reviewer (Release Authority): Final approval or request for changes.

    Traceability is maintained via @spec PHPDoc tags in source files and GitHub issue $\leftrightarrow$ PR $\leftrightarrow$ change-folder links.

  7. Overview of the Hydra CI/CD pipeline workflow

    Hydra is an agentic spec-driven CI/CD pipeline that transforms an OpenSpec change proposal into a draft pull request through a multi-stage AI pipeline. The process follows these stages:

    1. Builder: Implements the change, pushes the branch, and opens a draft PR.
    2. Quality Tests: Runs linting and static analysis (phpcs, phpmd, psalm, phpstan, phpmetrics, composer audit, eslint, stylelint, npm audit, PHPUnit, Newman). Failures trigger a bounded fix-quality loop back to the Builder.
    3. Browser Tests: Playwright MCP executes GIVEN/WHEN/THEN acceptance criteria against a live Nextcloud instance. Failures trigger a bounded fix-browser loop back to the Builder.
    4. Code Review: Analyzes diffs and ADRs, applying bounded in-scope fixes. A 'fail' verdict escalates the PR to needs-input (no retry loop).
    5. Security Review: A sequential gate following the code review with the same bounded fix authority.
    6. Draft PR: Final human review and merge.
    7. Archive: Post-merge synchronization of specs to Specter, test scenario generation, and changelog updates.

  8. Overview of the Conduction spec-driven development workflow

    Conduction uses a spec-driven development workflow that integrates OpenSpec (structured specifications), tracking issues on Codeberg (primary) or GitHub (fallback), and automated spec verification. The core philosophy is to write specifications once and break them into small JSON tasks that reference specific spec sections, allowing AI coding agents to operate with minimal, targeted context rather than loading entire documents.

  9. Overview of CI/CD quality job groups

    The quality.yml reusable workflow executes jobs across eight distinct groups to validate the application:
    GroupJobs
    PHP Qualitylint, phpcs, phpmd, psalm, phpstan, phpmetrics (matrix)
    Vue Qualityeslint, stylelint (matrix)
    FrontendFrontend Build, Frontend Tests (unit), Frontend Check (per npm script)
    TestsPHPUnit (PHP × Nextcloud matrix), Integration Tests (Newman), E2E Tests (Playwright)
    Accessibilityaxe-core (opt-in)
    Supply chainSecurity (composer), Security (npm), License (composer), License (npm), SBOM
    GovernanceHydra Gates, Coverage Baseline Protection, Features Extract, Journeydoc Capture
    RollupQuality Report

  10. Overview of Conduction ISO Certifications and Policies

    Conduction maintains active certifications for ISO 9001:2015 (Quality Management) and ISO 27001:2022 (Information Security Management). The following core policy documents are active and available in the documentation:

    • Quality Policy (ISO 9001:2015 §5.2)
    • Information Security Policy (ISO 27001:2022 §5.2)
    • Incident Reporting (ISO 27001:2022 A.6.8 / ISO 9001:2015 §10.2)
    • Security Practices (ISO 27001:2022 Annex A)
    • Privacy & AVG (AVG/GDPR, ISO 27001:2022 A.5.34)

  11. Overview of the App Lifecycle Workflow

    The application lifecycle is managed via the app- command namespace. The workflow typically follows this sequence: /app-design (optional) → /app-create → /app-explore → /app-apply → /app-verify. The openspec/app-config.json file serves as the single source of truth for the application's configuration. If drift is found during verification, the user should return to the exploration phase.

  12. Configure business-critical Claude Code skills (L4)

    Business-critical skills should reach L4 maturity to ensure alignment with organizational standards:

    • Include a references/ directory containing business-specific standards, architecture documents, and Architecture Decision Records (ADRs).
    • Utilize project-specific templates and terminology.
    • Ensure output matches team expectations without requiring manual correction.