Ga naar hoofdinhoud

Using Hydra

Developer-facing guide to Conduction's spec-driven workflow. This is the driver's seat view of the Hydra pipeline — how to set your workstation up, write specs and skills, hand a change off to the pipeline, and run reviews. The pipeline internals (Builder / Reviewer / Applier agents, container architecture, deployment models, operations) are documented in the sibling Hydra section.

Underneath, the tool is Claude Code with the Conduction skills catalogue; this section was previously titled Claude Code Developer Guide before being folded into the Hydra umbrella.

Academy tutorials​

The reference docs in this section are deliberately terse — for narrative walkthroughs with worked examples, the Conduction Academy publishes interactive tutorial series that pair with the topics below:

Use the reference docs as lookup material; use the Academy tutorials when you want to learn a workflow narratively for the first time.

Guides​

Getting Started​

Step-by-step guide from installation to your first completed change. Start here if you're new to the workflow.

Workflow Overview​

Architecture overview of the full system: how specs, tracking issues (GitHub — see the platform policy below), and plan.json fit together. Includes the plan.json format and flow diagrams.

Platform policy (2026-08-22, supersedes the 2026-05-29 Codeberg-first order): ConductionNL work lives on GitHub. The 2026-05-29 migration to codeberg.org/Conduction/* was reversed — directive 2026-07-17, executed 2026-07-23; zero Codeberg remotes remained fleet-wide as of 2026-08-22. All Hydra skills and pipeline scripts auto-detect the per-repo platform from git remote get-url origin and prefer GitHub first, GitLab second (non-Conduction client work), Gitea/Forgejo third (only for a repo that genuinely lives on a Forgejo host — never the default). A codeberg.org URL found inside a repo is stale data to be fixed, not evidence of where that repo lives. See hydra/.claude/skills/PLATFORM-POLICY.md for the canonical reference.

Command Reference​

Detailed reference for every skill — OpenSpec built-ins (/opsx-new, /opsx-ff, etc.) and custom Conduction skills (/opsx-plan-to-issues, /opsx-apply-loop, /opsx-pipeline). Includes expected output and usage tips.

OpenSpec Command Reference​

Focused reference for the per-project OpenSpec commands installed by openspec init. Split out from the main command reference for quick lookup.

Tender & Ecosystem Commands​

Reference for the competitive analysis and ecosystem gap-finding commands (/tender-scan, /tender-status, /tender-gap-report, /ecosystem-investigate) that operate on the concurrentie-analyse/intelligence.db SQLite database.

Writing Specs​

In-depth guide on writing effective specifications: RFC 2119 keywords, Gherkin scenarios, delta specs, shared spec references, task breakdown, and common mistakes to avoid.

Writing Skills​

How to create and structure skills: folder layout (templates/, references/, examples/, assets/), SKILL.md format, naming conventions, common patterns, and the extraction threshold rule.

Skill Checklist​

Quick validation checklist to run before adding or reviewing a skill, organized by maturity level (L1–L7).

Skill Patterns​

Proven L3 building blocks for skills — description writing, subfolder layout (templates/, references/, examples/, assets/), and reusable patterns to apply consistently.

Skill Evaluation​

Detailed L5 reference for evaluating, measuring, and improving skills with data — evals.json format, baseline scoring, trigger tests, and the iteration workflow.

Skill Level Sources​

Annotated external sources behind the L1–L7 maturity framework — direct ancestry, human-competence frameworks (SFIA 9, Dreyfus, e-CF/KWIV), maturity models (CMMI), L5 eval methodology, user AI-fluency frameworks (Anthropic 4Ds, EU AI Act Article 4), and sources assessed-and-excluded.

Writing ADRs​

How to write Architectural Decision Records: structure, format, when to create one, and how ADRs feed into the OpenSpec workflow.

Writing Docs​

Guidelines for writing and maintaining documentation within a project: structure, tone, what to document, and how docs connect to the spec-driven workflow.

Writing Controllers​

How to author Nextcloud controllers in Conduction apps: auth attributes, response envelope, exception translation, security-config fail-modes and public-surface hardening, with the gates that enforce each rule.

App Lifecycle​

Creating and managing Nextcloud apps: design research (/app-design), bootstrapping from template or onboarding an existing repo (/app-create), thinking through goals and features (/app-explore), applying config to code (/app-apply), and auditing for drift (/app-verify). Includes project.md and openspec/config.yaml templates, and an onboarding checklist.

Docker Environment​

Available docker-compose profiles, reset instructions, and environment setup.

Workstation Setup​

How to set up a new machine — Windows + WSL2 + Docker Desktop + VS Code installation, required/recommended extensions, Claude Code authentication, and WSL prerequisites (Node.js, PHP, Composer, git-host CLIs — gh for GitHub (primary), glab for GitLab, tea for Codeberg/Gitea/Forgejo (non-Conduction repos only) — Playwright, OpenSpec CLI).

Quick Setup — for people who already know the system​

Condensed cheat-sheet for re-imaging a known-good workstation: prerequisites, repos to clone, commands in order, validation step. Not for first-timers — for them, the Workstation Tutorial series (with screenshots) plus Workstation Setup (full reference) is the path.

Codeberg Authentication Setup​

End-to-end auth for Codeberg from WSL: SSH key generation + Codeberg upload, ~/.ssh/config, keychain for passphrase persistence, tea CLI install + token scopes, VS Code Gitea extension, switching existing repo remotes, and how Claude Code inherits the auth without re-prompting. Per the platform policy above, ConductionNL work does not live on Codeberg — read this only when you need a non-Conduction repo that genuinely lives on a Forgejo host.

Global Claude settings (~/.claude)​

Mandatory user-level settings enforcing a read-only Bash policy and write-approval hooks. Versioned — Claude warns you at session start when an update is available. Install once per machine; see the doc for the full guide and update instructions.

Testing Reference​

All testing commands and skills in one place — when to use each, typical workflows (pre-PR, regression sweep, smoke test), per-command "use when" guidance, test scenario integration, and browser pool rules.

Parallel Agents & Subscription Cap​

How parallel agent commands (like /test-counsel, /test-app, and /feature-counsel) consume your Claude subscription cap, guidelines for responsible use, and which files to keep lean to reduce token usage.

Frontend Standards​

Frontend development standards enforced across all Conduction apps: OpenRegister dependency checking, CSS scoping, admin detection patterns, and reference implementations.

Local LLM Setup (Ollama + Qwen)​

How to run Claude Code with a local Qwen model via Ollama for privacy, cost reduction, and offline use. Includes the Double Dutch RAD workflow for pairing Claude (day shift) with Qwen (overnight batch jobs).

Playwright MCP Browser Setup​

Setup guide for the Playwright MCP browsers: browser-1 by default, the opt-in seven-browser pool on one shared server for parallel testing, VS Code user-scope registration, verification and usage rules.

Usage Tracker​

Real-time Claude token usage monitoring in VS Code — color-coded status, threshold notifications, and multi-model support (Haiku, Sonnet, Opus). Reads Claude Code session files directly; no log configuration needed. Run bash usage-tracker/install.sh to get started.

End-to-End Walkthrough​

A complete worked example showing every phase of the flow on a realistic feature (adding a search endpoint to OpenCatalogi). Shows exactly what you type and what happens.

Retrofit Playbook​

Bringing legacy apps under ADR-003 §Spec traceability — the three retrofit skills (/opsx-coverage-scan, /opsx-annotate, /opsx-reverse-spec) in order, plus the six coverage buckets and when to extend vs create new specs.


Table of Contents​


Work Pipeline​

Claude follows a four-stage pipeline for all development work. Each stage has dedicated commands and tools. Claude operates as an architect and orchestrator — it defines, configures, and validates but delegates actual code generation to the platform's building blocks.

Key commands per stage:

Stage 1: Obtain — Discovery & Requirements Gathering​

Collect requirements, study existing solutions, and identify what to build. Claude explores without making changes.

SourceHowCommands / Tools
Tracking issuesSync and analyze open issues from project repos (GitHub; tea only for non-Conduction Forgejo repos)/swc-update, gh issue list, tea issues list
Other applicationsCrawl code or browse running apps to understand patterns/opsx-explore, Playwright browsers (browser-1; browser-2–browser-7 opt-in)
DocumentationRead docs from other platforms, APIs, standardsWebFetch, WebSearch, /opsx-explore
TendersScrape TenderNed, classify by category, analyze requirements and ecosystem gaps/tender-scan, /tender-status, /tender-gap-report, /ecosystem-investigate, Read (PDF support)
App store scoutingSpot interesting apps on WordPress plugin directory, GitHub/Codeberg trending, ArtifactHub, Nextcloud app storeWebSearch, WebFetch, Playwright browsers

Typical discovery session:

/opsx-explore # Investigate a topic or problem
> "What calendar apps exist on ArtifactHub and WordPress that we could learn from?"
> "Crawl the Nextcloud app store for document management apps"
> "Analyze the tracking issues for openregister and summarize themes" (on the per-repo platform — GitHub for `ConductionNL/*`, which is where all Conduction work lives)

Stage 2: Specify — Writing OpenSpec Artifacts​

Turn discoveries into structured specifications. This stage produces the blueprint that guides implementation.

PhaseArtifactCommand
StartChange directory + proposal.md/opsx-new <change-name>
Proposal → TasksAll artifacts in one go (proposal, specs, design, tasks)/opsx-ff
IncrementalOne artifact at a time/opsx-continue
ReviewMulti-perspective feature analysis/feature-counsel
ArchitectureArchitecture review of specs/team-architect
Business valueAcceptance criteria and prioritization/team-po
New appFull app design from scratch (architecture, features, wireframes)/app-design
TrackConvert tasks to tracking issues with epic (Codeberg/GitHub)/opsx-plan-to-issues

Artifact progression:

proposal.md ──► specs/*.md ──► design.md ──► tasks.md ──► plan.json
│
▼
Tracking Issues (Codeberg/GitHub)

Typical spec session:

/opsx-new add-document-preview # Start the change
/opsx-ff # Generate all artifacts
/feature-counsel # Get 9-persona feedback
# Human reviews and refines specs
/opsx-plan-to-issues # Create trackable issues

Stage 3: Build — Configuration, Not Code​

Claude acts as an assembler, not a coder. It defines schemas, configures workflows, and wires up components using the platform's three pillars:

LayerToolClaude's Role
Frontend UI@conduction/nextcloud-vueSelect and configure components, define views and layouts, set up routing
Backend dataOpenRegisterDefine schemas, registers, and object structures; configure validation rules and relations
Backend logicn8n workflowsDesign workflow logic, configure triggers, map data transformations

Claude does not write raw PHP business logic, custom Vue components from scratch, or manual SQL. Instead:

  • UI comes from the shared @conduction/nextcloud-vue component library
  • Data models are OpenRegister schemas (JSON-based configuration)
  • Business processes are n8n workflows (visual/JSON configuration)
CommandPurpose
/opsx-applyImplement tasks from the change — assembles components per the specs
/opsx-syncSync delta specs to main specs during implementation

Typical build session:

/opsx-apply # Implement tasks from specs
# Claude configures schemas, wires components, sets up n8n flows
/opsx-sync # Keep specs in sync

Stage 4: Validate — Quality Assurance & Verification​

Verify that the implementation matches the specs, passes quality standards, and works for all user types.

Code Quality​

ToolCommandChecks
PHPCScomposer phpcsCoding standards (auto-fix: composer cs:fix)
PHPMDcomposer phpmdComplexity, naming, unused code
PHPStancomposer phpstanStatic type analysis
Psalmcomposer psalmType analysis (stricter)
phpmetricscomposer phpmetricsCode metrics + violations
ESLintnpm run lintJavaScript/Vue linting (auto-fix: npm run lint -- --fix)
Stylelintnpm run stylelintCSS/SCSS linting

If composer phpcs fails due to a permissions error on vendor/, see PHP Quality Tools setup in Prerequisites.

Testing​

For the full list of testing commands, browser pool rules, and recommended workflows, see testing.md and commands.md.

Key commands: /opsx-verify (spec verification), /test-counsel (9-persona test sweep), /test-app (automated browser testing), /test-functional, /test-api, /test-accessibility, /test-performance, /test-security, /test-regression, and /test-persona-* (per-persona testing — incl. /test-persona-jasper, screen-reader-primary).

CI/CD​

All apps have code-quality.yml workflows that block PRs on (GitHub Actions; the same files also run natively under Forgejo Actions, which is why the .forgejo/ variants are kept):

  • PHPCS + PHPMD + Psalm (PHP quality)
  • ESLint (frontend quality)
  • PHPUnit (unit tests)

Completion​

CommandPurpose
/opsx-verifyFinal verification against specs — generates review.md
/opsx-archiveArchive the change, merge delta specs into main specs
/opsx-bulk-archiveArchive multiple completed changes at once

Typical validation session:

composer phpcs && composer phpmd # Code quality gates
/opsx-verify # Verify against specs
/test-counsel # 9-persona test sweep
/test-api # API compliance check
/opsx-archive # Archive when everything passes

Workstation Setup​

For new-machine setup instructions — Windows + WSL2 + Docker Desktop + VS Code installation, extensions, Claude Code authentication, and WSL prerequisites (Node.js, PHP, Composer, git-host CLIs — gh for GitHub (primary), glab for GitLab, tea for Codeberg/Gitea/Forgejo (non-Conduction repos only) — Playwright, OpenSpec CLI, etc.) — see workstation-setup.md.


Local Configuration​

Claude Code uses three settings files that work together. Understanding the difference prevents confusion:

FileScopeCommitted?Purpose
~/.claude/settings.jsonMachine-wide, all projectsNo — installed per developerGlobal read-only policy and safety hooks. Installed from global-settings/ in step 7 above.
.claude/settings.jsonProject-wide, all developersYesShared team permissions — MCP server approvals, enableAllProjectMcpServers. Do not edit locally.
.claude/settings.local.jsonProject, per developerNo — gitignoredYour personal tool approvals on top of the shared settings. Auto-generated by Claude Code.

settings.local.json​

This file is auto-generated by Claude Code the first time you approve a tool permission in a session — no manual setup needed. It stores your personal allow/deny rules on top of the shared project settings.

Optionally, bootstrap it upfront with common permissions to avoid approval prompts during normal development:

{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(docker:*)",
"Bash(docker-compose:*)",
"Bash(composer:*)",
"Bash(git:*)",
"Bash(npm:*)",
"Bash(php:*)",
"Bash(curl:*)",
"Bash(bash:*)",
"Bash(ls:*)",
"Bash(mkdir:*)",
"Bash(cp:*)",
"Bash(mv:*)",
"Bash(rm:*)",
"WebFetch(domain:localhost)",
"WebFetch(domain:codeberg.org)",
"WebFetch(domain:github.com)",
"WebFetch(domain:raw.githubusercontent.com)"
],
"additionalDirectories": ["/tmp"]
}
}

Save this as .claude/settings.local.json in your project root. It is gitignored and will never be committed.

Review before keeping: entries like Bash(bash:*) and Bash(rm:*) are intentionally broad for initial setup — tighten or remove them once you know which commands Claude actually needs on your project.

~/.claude/CLAUDE.md (personal, optional)​

Your working agreements with Claude — scope, handover format, commit language, when to ask first — loaded in every session in every repository. It is personal and not part of the versioned global settings, so an update never touches it. Start from the example template only if you have none yet:

[ -e ~/.claude/CLAUDE.md ] || cp docs/claude/examples/global-CLAUDE.md.example ~/.claude/CLAUDE.md
# Fill in the placeholders, drop the sections you don't want

CLAUDE.local.md​

Contains environment-specific credentials and API tokens (passwords, keys, endpoints). Never commit this file.

Copy the example template into your project and fill in your values:

cp docs/claude/examples/CLAUDE.local.md.example .claude/CLAUDE.local.md
# Edit with your credentials

Playwright MCP Browser Setup​

Every project ships one headless browser (browser-1) in its root .mcp.json — copy the example .mcp.json. The seven-browser pool for parallel agents is opt-in: one shared @playwright/mcp server on localhost:8931, referenced by URL, so a pool costs zero processes per session (example). Claude Code starts every stdio server in .mcp.json at session start; seven per session is how WSL ran out of memory on 2026-09-08. See playwright-setup.md for the shared server, the user-scope registration for VS Code, verification steps and usage rules.

Quick summary:

ServerModePurpose
browser-1HeadlessMain agent (default)
browser-2–browser-5, browser-7HeadlessSub-agent / parallel
browser-6HeadedUser observation (visible window)

Usage rules: Use browser-1 for normal work. Assign browser-2–browser-5 and browser-7 to parallel sub-agents. Keep browser-6 reserved for user observation only.


Directory Structure​

This repository (.github)​

This repo contains documentation, global settings, and project templates — not skills, personas, or scripts. Those live in each project's own .claude/ directory (see below).

.github/
├── docs/
│ └── claude/ # Developer guides (this documentation)
│ ├── README.md # This file — overview and setup
│ ├── getting-started.md # First-change walkthrough
│ ├── workflow.md # Spec-driven architecture reference
│ ├── commands.md # Full command reference
│ ├── commands-openspec.md # OpenSpec per-project commands
│ ├── commands-tender.md # Tender & ecosystem intelligence commands
│ ├── testing.md # Testing commands and skills
│ ├── writing-specs.md # How to write specs
│ ├── writing-skills.md # How to create skills
│ ├── skill-checklist.md # Pre-add / review checklist by maturity level
│ ├── skill-patterns.md # Reusable L3 skill patterns and subfolder guide
│ ├── skill-evals.md # Skill evaluation & measurement (L5 reference)
│ ├── skill-level-sources.md # Annotated external sources for the L1–L7 framework
│ ├── writing-adrs.md # How to write ADRs
│ ├── writing-docs.md # Documentation standards
│ ├── writing-controllers.md # Nextcloud controller authoring rules
│ ├── app-lifecycle.md # Nextcloud app lifecycle
│ ├── frontend-standards.md # Frontend coding standards
│ ├── parallel-agents.md # Parallel agents and cap usage
│ ├── local-llm.md # Ollama + Qwen + Double Dutch
│ ├── playwright-setup.md # Playwright browser configuration
│ ├── walkthrough.md # End-to-end worked example
│ ├── docker.md # Docker environment
│ ├── workstation-setup.md # New machine setup (WSL2, VS Code, tools)
│ ├── global-claude-settings.md # Global settings reference
│ ├── retrofit.md # Legacy app retrofit playbook
│ └── examples/ # Template files (project-level, plus the personal global CLAUDE.md)
│ ├── global-CLAUDE.md.example # Template for your personal ~/.claude/CLAUDE.md
│ ├── CLAUDE.local.md.example # Template for project .claude/CLAUDE.local.md
│ ├── .mcp.json.example # Template for project root .mcp.json (browser-1 only)
│ └── browser-pool-shared.json.example # Opt-in 7-browser pool pointing at the shared server
│
├── global-settings/ # Mandatory user-level settings for ~/.claude/
│ ├── README.md # Install, update, version-bump policy and security model
│ ├── settings.json # → ~/.claude/settings.json (global read-only policy)
│ ├── block-write-commands.sh # → ~/.claude/hooks/block-write-commands.sh
│ ├── block-polling.sh # → ~/.claude/hooks/block-polling.sh (blocks hand-rolled waiting and poll loops)
│ ├── block-config-tool-writes.sh # → ~/.claude/hooks/block-config-tool-writes.sh
│ ├── check-settings-version.sh # → ~/.claude/hooks/check-settings-version.sh
│ ├── sound-notify.sh # → ~/.claude/hooks/sound-notify.sh (optional sound wrapper; silent by default)
│ ├── user-hooks-dispatch.sh # → ~/.claude/hooks/user-hooks-dispatch.sh (runs your ~/.claude/user-hooks.json)
│ ├── VERSION # → ~/.claude/settings-version (version tracking for update checks)
│ ├── settings-repo-url.example # → ~/.claude/settings-repo-url (GitHub slug for the online version check)
│ ├── settings-repo-ref.example # → ~/.claude/settings-repo-ref (optional; branch to track, default main)
│ ├── sound-config.sh.example # → ~/.claude/sound-config.sh (opt-in, user-editable)
│ ├── user-hooks.example.json # → ~/.claude/user-hooks.json (opt-in per-user hooks)
│ └── tests/ # Test suites for the hooks (not installed)
│
└── usage-tracker/ # Claude token usage monitoring tool

Typical project workspace​

Each Conduction project (Nextcloud apps, WordPress sites, etc.) has its own .claude/ directory with skills, personas, and configuration. The Hydra repo also maintains its own set of skills and personas for CI/CD agents.

<project-root>/
├── .mcp.json # Playwright browser-1 (see docs/claude/examples/.mcp.json.example); pools live in .claude/mcp/
│
└── .claude/
├── CLAUDE.md # Workflow rules, project context
├── CLAUDE.local.md # [GITIGNORED] Your credentials
├── CLAUDE.local.md.example # Template — copy from global-settings/ or customize per project
├── settings.json # [COMMITTED] Shared team permissions
├── settings.local.json # [GITIGNORED] Personal tool permissions (auto-generated)
│
├── skills/ # Project-specific skills (see commands.md)
├── personas/ # User personas for testing
├── scripts/ # Shared shell utilities
└── docs/ # Project-specific documentation

Personas​

Each project defines its own user personas in personas/. Personas drive multi-perspective analysis via /feature-counsel and testing via /test-counsel.

The Nextcloud workspace uses 9 Dutch government personas (retired citizens, low-literate migrants, digital natives, CISOs, standards architects, MKB vendors, ZZP developers, small business owners, blind senior developers — Jasper, the first AT-primary persona). Other workspaces define personas relevant to their domain — e.g., a webshop workspace would carry shopper, returning-customer, and shop-owner personas instead.

For the full persona table with testing command mapping, see testing.md.


Architectural Design Rules (ADRs)​

ADRs define constraints that all OpenSpec artifacts must comply with. Company-wide ADRs live in hydra/openspec/architecture/; app-specific ADRs live in {app}/openspec/architecture/. They are enforced during artifact creation (via config.yaml rules injected into openspec instructions output) and during verification (via /opsx-verify).

For the full guide on ADR structure, format, the current list of company-wide ADRs, and when to create a new one, see writing-adrs.md.


Usage Tracker​

Monitor your Claude token usage in real-time to avoid hitting subscription limits mid-session. The tracker reads Claude Code's JSONL session files directly — no extra configuration needed.

# Install
bash usage-tracker/install.sh

# Quick status (all models)
python3 usage-tracker/claude-usage-tracker.py --status-bar --all-models

# Live monitoring (refreshes every 5 min)
python3 usage-tracker/claude-usage-tracker.py --monitor --all-models

See usage-tracker/README.md for full documentation, VS Code task integration, and limit configuration.


Hydra is Conduction's agentic CI/CD platform that runs the same spec-driven workflow autonomously in Docker containers. It transforms OpenSpec change proposals into validated, security-scanned code on feature branches — with final human approval before merging.

For an overview of the pipeline stages, the label-based triggers (ready-to-build, code-review:queued, security-review:queued), and how to put Hydra to work on your PR, see the Hydra docs. For container architecture, image builds, orchestrator internals, and operator-level material, see the Hydra repository.


Scripts​

Each project may include shell scripts in its .claude/scripts/ or scripts/ directory, used by skills and developers. Common examples:

ScriptDescriptionUsage
clean-env.shFull Docker environment reset — stops containers, removes volumes, restarts, installs core appsbash scripts/clean-env.sh or /clean-env

Contributing​

Adding a Skill​

Skills are added to each project's .claude/skills/ directory. See writing-skills.md for the full guide on folder layout, SKILL.md format, naming conventions, maturity levels, and the extraction threshold rule.

Quick start:

  1. Create skills/<skill-name>/SKILL.md in your project's .claude/ directory
  2. Use frontmatter:
    ---
    name: skill-name
    description: What this skill does
    ---
  3. Document instructions and expected behavior

Adding a Persona​

Personas are added to each project's personas/ directory.

  1. Create personas/<firstname-lastname>.md
  2. Follow the existing format (see any existing persona file in the project)
  3. Update skills that reference the persona list

PR Process​

  1. Create a branch: git checkout -b my-change
  2. Make changes, commit, push
  3. Create PR against main

Troubleshooting​

openspec: command not found​

npm install -g @fission-ai/openspec

Playwright browser not launching​

npx playwright install chromium
# If permission errors:
npx playwright install --with-deps chromium

MCP servers not showing in VS Code / not connected​

  1. Confirm .mcp.json exists in your project root
  2. Confirm settings.json contains "enableAllProjectMcpServers": true
  3. Reload the window: Ctrl+Shift+P → reload window
  4. Check the output panel for errors: Ctrl+Shift+P → "Output: Focus on Output" → select "Claude VSCode"

You can verify the MCP binary itself starts correctly:

npx -y @playwright/mcp@latest --headless --isolated --port 9999
# Should print: Listening on http://localhost:9999

If the pool entries (browser-2…) fail while browser-1 works, the shared server is not running: scripts/playwright-mcp-server.sh status in the hydra checkout.

Claude Code doesn't see commands​

Ensure .claude/ is at the workspace root and Claude Code is started from that directory.

tea login list empty / gh: not logged in​

# GitHub — PRIMARY (the ConductionNL org: code, PRs and issues)
gh auth login

# GitLab — ALTERNATIVE (non-Conduction client work)
glab auth login

# Codeberg / Gitea / Forgejo — only for a non-Conduction repo that genuinely
# lives on a Forgejo host. Not needed for ConductionNL work.
tea login add --name codeberg --url https://codeberg.org --token <PAT>
# Token from https://codeberg.org/user/settings/applications
# Scopes: read:repository, write:repository, read:issue, write:issue

Note: tea pulls create / tea issues create need a controlling TTY and fail from Claude Code's Bash tool. Claude-driven workflows use REST POST /api/v1/... with the token from ~/.config/tea/config.yml. Read-only tea login list/default, tea repos list, tea pulls list -o json are TTY-safe.

Docker environment not starting​

docker compose -f openregister/docker-compose.yml up -d
# Full reset:
/clean-env

"You've hit your limit · resets 3pm (Europe/Amsterdam)"​

This means you've reached your Claude subscription's usage cap. It can happen after running commands that launch many agents in parallel (/test-counsel, /feature-counsel, /test-app in Full mode).

See parallel-agents.md for an explanation of why parallel agents drain the cap, guidelines for careful use, and tips to reduce token usage (including always opening a fresh window before running these commands).

To monitor your usage proactively before hitting the limit, use the usage tracker:

python3 usage-tracker/claude-usage-tracker.py --status-bar --all-models