aiops: claude - Configure and validate Claude cloud environment #263

AI Ops Summary

Configure and validate the proposed ThisOneTimeOnAcid Claude cloud environment for lightspeedwp/ThisOneTimeOnAcidCom.

Build Summary

Delivery and remaining validation — 17 October 2026

Cloud documentation and setup helpers were delivered in aiops: claude - Configure agents, hooks, skills and cloud settings, merged into develop. Real provisioning, fresh/repeated setup, builds, network access, missing credentials and failure handling remain unverified. Reconcile runtime/package-manager guidance and verify local/cloud settings, hooks, skills and MCP parity. Acceptance checkboxes remain unchanged; author-reported tests are not independently verified.

Document the environment under .claude/cloud/, with executable setup helpers under scripts/claude/. Assess MCP requirements separately from basic dependency installation.

Linked Stories/Tasks/PRs/Epic

Parent: #218. Settings dependency: #259. Final parity checks depend on agents, hooks and skills: #260, #261, #262.

Milestones & Timeline

No milestone or deadline specified. Estimates remain unset.

Problem / Opportunity

Cloud setup needs reproducible dependencies, explicit networking and credential boundaries, and verified local/cloud behaviour rather than assumed parity.

Approach / Solution

Resolve runtime and package-manager policy before finalising executable setup. Start with Trusted networking and no secrets or custom variables unless verified requirements emerge. No cloud validation success is claimed.

Acceptance Criteria

• AI workflow/agent described
• Problem/opportunity scoped
• Success metric defined
• Documentation updated
• PR uses correct branch prefix (aiops/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards
• Runtime and package manager are explicitly agreed.
• Trusted networking is tested against required dependency hosts.
• Start with no secrets or custom environment variables unless a verified requirement emerges.
• Setup installs development dependencies reproducibly; npm ci --include=dev remains proposed pending the package-manager decision.
• Fresh-session setup and npm run build are tested, with actual runtime versions and results recorded.
• Missing credentials, denied network access and setup failures are handled safely.
• Any MCP configuration is approved, sanitised and least-privilege.
• Local/cloud differences, setup ownership and rollback are documented.

Additional Context

Separate documented cloud intentions from applied configuration and observed results. Record runtime, package-manager, networking and local/cloud compatibility evidence.

Cloud setup handover — historical recommendation

The environment name ThisOneTimeOnAcid was supplied during setup. Trusted networking, no network secrets and no custom environment variables were recommended initially. These are intended settings, not independently verified applied configuration.

Remove sample values such as NODE_ENV=production, GIT_AUTHOR_NAME=Your Name and the multiline CONFIG example if they were entered. Keep credentials out of ordinary environment variables.

The following setup script was proposed during planning, not executed or validated in this chat:

#!/bin/bash
set -euo pipefail

cd "${CLAUDE_PROJECT_DIR:?Repository directory is unavailable}"

echo "Node: $(node --version)"
echo "npm: $(npm --version)"

npm ci --include=dev

Before using this historical script:

• Confirm CLAUDE_PROJECT_DIR identifies the book repository, not the .github reference checkout.
• Inspect the merged setup helpers and current repository instructions; prefer the reviewed implementation where appropriate rather than replacing it with this earlier proposal.
• Confirm npm and the runtime against the current lockfile and dependency requirements. Do not infer a runtime pin from this script.
• After approval to execute validation, test fresh and repeated setup, then the applicable build command. Record the checked revision, Node/npm versions, commands, results and failure evidence.
• Record whether Trusted networking reaches all required hosts. Add credentials or MCP connections only for verified, separately approved requirements.

Cloud provisioning, dependency installation, build success and local/cloud parity remain unverified by this handover.

Dependencies: parent runtime/package-manager decisions and settings foundations. Final cloud parity checks depend on agents, hooks and skills being ready. Branch-prefix policy requires repository verification. Preserve protected files; no CHANGELOG.md edits without separate authorisation.

Definition of Ready (DoR)

• AI ops goal described
• Area/action mapped
• Acceptance criteria listed
• Estimate added

Definition of Done (DoD)

• All acceptance criteria met
• Solution/automation verified
• Documentation updated
• PR uses correct branch prefix (aiops/)
• PR uses the correct PR template based on type:aiops PR label or linked issue type or linked issue type:aiops label
• Branch deleted after merge
• Linked issue(s) updated with latest status and closed after merge,
• The related epic should not be closed, instead updated with a comment to reflect the closed issue

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom.
• Implementing target: this cloud-validation issue; public counterpart GitHub issue 263. Remaining outcome: reproducibility, operational validation and evidence-backed local/cloud handover, not rebuilding merged configuration.
• Parent context: independently verified in Linear and GitHub; coordination only. Do not put parent identifiers or links in the proposed branch, PR or commits while association effects remain unverified. Never use the parent as a native development or closing target.
• Allowed closing targets: none for this bounded documentation contribution; documentation alone does not complete operational acceptance.
• Branch state: proposed new branch, not created. No matching branch or cloud-specific open continuation found during refresh; no existing branch approved for reuse.
• Branch: aiops/claude-cloud-validation.
• Base: develop, checked at 4ecdb26d9655a48bf000a7c89da2f70383edce87; refresh before implementation.
• Naming policy: local guide, validator and organisation strategy. aiops/ is authorised and fits cloud operational handover independently of Linear classification. Naming inspected, not executed.
• Existing work: aiops: claude - Configure agents, hooks, skills and cloud settings #265 merged repository configuration into develop. Its historical aiops/claude-repository-configuration branch is absent from the refreshed remote listing. Do not recreate it or infer runtime parity from its merge.
• PR template: canonical shared AI Operations template, mapped by the shared routing contract. The local router lacks an aiops case and falls back to pr_default.md/type:maintenance; shared template metadata says type:ai-ops, while the issue has type:aiops. Obtain maintainer disposition before PR creation. Do not repair workflows/templates/taxonomy or assume automatic loading. Remove unused closing placeholders, omit parent references and use truthful attribution.
• Instruction conflicts: root AGENTS/CONTRIBUTING retain stale claims about missing pins/conventions, contradicted by current configuration. Record the conflict without expanding into root-guidance cleanup.
• Runtime evidence: .nvmrc selects Node 24 and package.json requires Node >=24; cloud documentation still says Node 22/npm 10. Root README states npm 10+; nested Netlify configuration declares npm 10 but proves neither effective cloud versions nor an exact cloud npm pin. Do not invent a pin or assert applied configuration/parity without evidence.
• Dependencies: settings/privacy, agents, hooks and skills remain In Progress and share docs/claude-configuration.md. Serialise approved document changes and refresh after their handover before final parity checks.
• Human prerequisites: confirm environment, repository-root working directory, supported Claude runtime, effective networking, credential boundaries and execution permission. npm ci can run postinstall Lefthook installation; setup/validation helpers install/build and are not read-only inspections.
• Constraints: this description plan authorises no implementation, cloud provisioning, environment/secret/MCP changes, installs, hooks, tests, builds, network probes, branch operations, PR changes, force-push, merge, deployment or spending. Exclude credentials, private identifiers and unsanitised logs from publicly synced content.

Expected file changes

Bounded documentation proposal. Paths inspected at 4ecdb26d9655a48bf000a7c89da2f70383edce87; existence is not edit approval. Operational acceptance is separate.

No creates, moves or deletions. Setup/validation scripts remain read-only. Helper defects require a separate bounded helper/test plan, not speculative edits.

Later operational evidence must identify revision, actual Node/npm/Claude versions, approved working directory, commands, fresh/repeated-session and failure outcomes, and sanitised network observations. Expected results are not observed results; a successful build does not prove hooks, permissions, credentials, skills, MCP or local/cloud parity.

Exclude runtime/package/lockfile changes, root-guidance cleanup, settings/hooks/agent/skill rewrites, Netlify changes, asset recovery and generated output. Protected changelog, attribution, image assets/references, Supabase and task-list files remain untouched; locked governance is human-controlled and workflows centrally managed. Additional files or operations require revised scope and approval.