docs(specs): spec 016 standardised Claude Code cloud environment

[ashleyshaw]

Documentation Pull Request

This repository enforces changelog, release, and label automation for all PRs and issues.
See the organisation-wide Automation Governance & Release Strategy for required rules.

Linked issues

• Relates to chore: shared Claude Code cloud environment and branch-name guard #3524, which implements the SessionStart and PreToolUse hooks and the cloud setup.
• Relates to docs(specs/009): record branch naming clarification and align working branch #3358 (spec 009 branch cleanup), which carries this spec's claude/* cleanup rule.
• Relates to Label Prefix Governance Enforcement — Audit Results & Remediation Plan #1592, label prefix governance enforcement.

This PR doesn't close any of them: it adds the specification, and the implementation lands in those PRs.

What changed

This PR adds the full SpecKit record for spec 016, Standardised Claude Code Cloud Environment, in .github/specs/016-claude-cloud-environment/. It also adds contract tests for it.

• spec.md (status: Draft): three prioritised user stories.

  • P1: Claude never publishes a non-compliant branch.
  • P2: everyone starts from the same shared cloud environment.
  • P3: the configuration is versioned and documented.

  The spec also has functional requirements, success criteria SC-001 to SC-008, edge cases, assumptions, and the clarifications from two /speckit-clarify sessions.

• Design: plan.md, research.md, data-model.md and contracts/. contracts/hooks.md covers the hooks, and contracts/branch-cleanup.md covers the extension to spec 009's categoriser and workflow.

• quickstart.md: validation steps that can be run, from automated checks through to a real cloud session.

• tasks.md: 51 tasks, 36 of them ticked because they were delivered in chore: shared Claude Code cloud environment and branch-name guard #3524 or docs(specs/009): record branch naming clarification and align working branch #3358. The open ones are:

  • the remaining US1 guard work in chore: shared Claude Code cloud environment and branch-name guard #3524;
  • the Owner actions (T028, T042, T048);
  • the live checks (T030, T035, T043);
  • the analysis and PR-description tasks for chore: shared Claude Code cloud environment and branch-name guard #3524 (T039, T040).

• checklists/: the requirements and security checklists. The reviewer ticks the security items.

• .github/specs/CATALOG.md: spec 016 is listed under Draft Specifications, with its own detailed entry.

• tests/js/claude-cloud-environment-docs.test.js: Jest contract checks that keep the spec, plan, tasks and contracts consistent with each other.

• CHANGELOG.md: an Unreleased → Added entry.

Audience & placement

• Audience: maintainers and organisation Owners.
• Location: .github/specs/016-claude-cloud-environment/, under the SpecKit numbering scheme. Specs 014 and 015 aren't in the catalogue yet, and this PR doesn't touch them.

Preview / Screenshots

N/A: this PR is Markdown plus one test file.

Notes

• There's no runtime code here. The implementation is in chore: shared Claude Code cloud environment and branch-name guard #3524, and the cleanup rule is in docs(specs/009): record branch naming clarification and align working branch #3358.
• The contract tests pin some current values, such as the spec's Draft status and the catalogue date. Update the tests whenever those change.
• Status on head cb53f83c:
  • develop has been merged in, so there's no merge conflict.
  • All CI checks pass, including Specification Validation.
  • All 11 review threads from CodeRabbit and Copilot are addressed and resolved.
  • npx jest tests/js/claude-cloud-environment-docs.test.js passes 37 of 37.
• aiops: qodo-pr-agent - Qodo PR-Agent pilot, shared skill and agent/skill integrations (spec 019) #3532 (spec 017) depends on this PR merging for its numbering check.

Changelog

Added

• Cloud Environment Specification — Documented the shared Claude Code cloud setup and the branch-name rules Claude sessions must follow, with automated checks that keep the spec consistent. (docs(specs): spec 016 standardised Claude Code cloud environment #3525)

---

Checklist (Global DoD / PR)

• All AC met and demonstrated: the SpecKit artefacts are complete and the requirements checklist passes.
• Tests added/updated: the spec contract tests, 37 passing.
• Accessibility checklist: N/A, documentation only.
• Docs/readme/changelog updated.
• Security checklist: no secrets or sensitive data are introduced. The guard's security requirements are in FR-013a and checklists/security.md.
• Code/design reviews approved: waiting on @eleshar.
• CI green. The linked issues stay open, because the implementation lands in chore: shared Claude Code cloud environment and branch-name guard #3524 and docs(specs/009): record branch naming clarification and align working branch #3358.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_014Co9SZUTwfLmMUr92dvMqF

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: lightspeedwp/.github/.coderabbit.yml

Review profile: CHILL

Plan: Advanced

Run ID: 67c19bfd-55a1-4a38-a083-760dd4f4c4f9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 1 files. (12 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change for spec 016 and the Standardised Claude Code Cloud Environment. It is concise and matches the main changeset.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 1 files. (12 skipped: 12 unsupported.)

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• 🤖 Coding Agent task started for unit test generation.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Template Routing

Branch Type: docs
Scope: claude-cloud-environment-spec
Template: pr_docs.md
Labels Applied: type:docs

This PR was automatically routed based on the branch naming strategy.

[github-actions]

AI Feedback Validation Report

❌ No issue link found: the PR must include Resolves #123 or Closes #123.

Required actions

1. Link this PR to its issue with Resolves #123 or Closes #123 in the description.
2. Track AI review feedback in FEEDBACK_RESPONSE.md with a status per item.
3. For deferred feedback, open a follow-up issue and link it.

[eleshar]

Heads-up: spec number 016 is now taken on develop

#3500 merged at 62c9344f31 and landed .github/specs/016-changelog-agent-quality/, with this row in CATALOG.md:

| 016 | changelog-agent-quality | Changelog Agent Quality & Validation Framework | Draft | 2026-09-18 | ...

This PR creates .github/specs/016-claude-cloud-environment/ and adds a competing row:

| 016 | claude-cloud-environment | Standardised Claude Code Cloud Environment | Draft | 2026-09-... | ...

This PR is CONFLICTING, so the row collision will be caught, but the folder collision would survive a naive rebase if the directory were renamed without the CATALOG row being updated to match.

This is the numbering problem #3539 tracks ("add spec/ prefix and reserve spec numbers on develop"), and it is now a concrete instance of it rather than a prediction. Suggest picking the next free number and updating the directory name, the internal spec_id references, and the CATALOG row together.

Not changing anything on this branch — the number is a decision for the spec owner, and #3539 may settle the convention first.

[eleshar]

Status check (read-only): this branch conflicts with develop and needs a rebase. It pairs with #3524 (shared Claude Code cloud environment and branch-name guard), which is also open and blocked, so the two probably want rebasing and reviewing together. No code has been changed on this PR.

[eleshar]

Blocked on one decision: spec 016 is taken on develop

I started the develop merge and stopped at the conflict, because the remaining hunk is not mechanical. The branch is untouched — I aborted the merge, so nothing here is half-resolved.

The mechanical hunk is fine. CHANGELOG.md conflicts because both sides added an ### Added entry. The union keeps both, dropping neither: your Cloud Environment Specification entry plus the nine that landed on develop since this branch was cut.

The CATALOG.md hunk is a decision. develop already has a spec 016:

| 016 | changelog-agent-quality | Changelog Agent Quality & Validation Framework | Draft | 2026-09-18 |

That is a different spec — the changelog agent, tracked by #3519 and implemented by #3434. This PR adds .github/specs/016-claude-cloud-environment, a second spec claiming 016. develop also added 014, 015 and 017 after this branch was cut, which is why the hunk spans three rows.

Why this cannot be merged as-is

Your own test pins the number, and pins it as exclusive:

// tests/js/claude-cloud-environment-docs.test.js:38-40
const entries = catalogue.split('\n').filter((line) => /^\| 016 \|/.test(line));
expect(entries).toHaveLength(1);
expect(columns.slice(2, 6)).toEqual(['claude-cloud-environment', ...]);

Keeping both rows gives two | 016 | entries and turns this test red. So 016 cannot simply be duplicated, and it cannot be silently taken from develop either — that would break #3519's file references and #3434's traceability.

The choice

Recommended: renumber this spec to 018. CATALOG.md on develop documents its own allocation rule:

1. Determine next number: take the highest number in this catalog and in .github/specs/ (017 at the time of writing)

017 is the current highest, so 018 is the next free number, and this spec was written on 2026-09-23 — after 016 and 017 existed. Cost: 13 references to 016-claude-cloud-environment across 5 files in this PR (the spec's spec.md, plan.md, tasks.md, CATALOG.md, and tests/js/claude-cloud-environment-docs.test.js, which also hardcodes specDirectory and the /^\| 016 \|/ filter). #3524 implements the spec but does not reference the number, so it needs no code change — only the traceability note.

Alternative: keep 016 and renumber develop's 016-changelog-agent-quality. I do not recommend this — it moves a number that #3519, #3434 and #3464 all reference, for a spec authored five days later.

What I need from you

Confirm 018 (or tell me the number you want). On your answer I will renumber, merge develop, resolve both hunks, and run the review before committing.

Not doing this without your call: the spec number is the spec's identity, and it is referenced from a second PR.

[github-actions]

No description provided.

[linear-code]

GIT-2400