epic: claude - Configure agents, hooks, skills and cloud settings #218

AI Ops Summary

Configure Claude for the book repository, adapting the shared .claude example to its own guidance and workflows.

Current implementation status — 17 October 2026

aiops: claude - Configure agents, hooks, skills and cloud settings is merged. Implementation has been delivered for Claude settings, agents, hooks, skills and cloud guidance, alongside branch validation, worktree guidance and Jest/Bats/Playwright test tooling and routing coverage. Delivery does not establish acceptance.

In the latest available records, dependency-validation and dependency-validation (dependabot, hosted) are skipped; CodeRabbit is pending. The PR's claim of 154 passing tests is author-reported and is not independently established by these checks. Build results, local/cloud smoke tests and requirement-to-test acceptance evidence remain unverified. Previously recorded hook-schema and test-server module compatibility concerns require confirmation against the merged code, rather than being treated as verified current findings.

Keep this epic open and all unchecked acceptance criteria unresolved pending validation. The implementation checklist and phased plan below remain the planning baseline, not completion evidence.

Build Summary

Add .claude/agents/, .claude/cloud/, .claude/hooks/, .claude/skills/, .claude/settings.example.json and .claude/settings.json. Keep executable setup, hook and validation helpers under scripts/claude/, following repository script-placement rules. Document configuration ownership, setup, validation and rollback.

Linked Stories/Tasks/PRs/Epic

Related work: #17, branch agent-repository-021f. No epic or additional issue relationships specified.

Milestones & Timeline

No milestone or deadline specified.

Problem / Opportunity

At initial intake, the requested Claude configuration was absent from the working branch. Configuration has since been delivered through the merged implementation PR. The remaining work is to validate repository-specific adaptations, reconcile documentation with implemented behaviour and establish acceptance evidence.

Approach / Solution

Read AGENTS.md, CONTRIBUTING.md, guidelines/README.md and applicable project guidelines before implementation.

Verify canonical source paths under the shared agents directory, then assess and adapt all 17 requested agents:

changelog-agent, design-partner-agent, content-strategy-agent, website-content-strategist-agent, testing-agent, reviewer-agent, reporting-agent, release-agent, prd-agent, pr-agent, pagespeed-agent, metrics-agent, metadata-agent, labeling-agent, issue-agent, document-reviewer-agent, client-website-discovery-assistant-agent.

Record source mappings, adaptations and any unsuitable or missing agents. Define repository-appropriate hooks, skills and cloud configuration without copying personal settings or secrets.

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
• Requested directory/configuration structure implemented and documented
• All 17 requested agents have verified source mappings and documented adaptation decisions
• Settings contain no secrets or machine-specific configuration
• JSON, agent references and runnable hooks/scripts pass applicable repository checks

Additional Context

Before acceptance or closure, consolidate a requirement-to-file-and-test evidence map: requirement, implementation file, checked revision, test command/scenario, result, evidence link and remaining gap. Distinguish verified results from author-reported claims.

docs: reconcile repository guidance and fix Netlify routing configuration merged into develop on 16 October 2026. Earlier references to it being open, targeting main and containing 196 changed files describe an earlier review state, not its final disposition.

Claude configuration was subsequently delivered through aiops: claude - Configure agents, hooks, skills and cloud settings, using aiops/claude-repository-configuration → develop. The earlier recommendation to choose a separate implementation PR has therefore been fulfilled; PR placement is no longer an unresolved decision.

The original agent-repository-021f name belongs to the guidance work, not the Claude implementation branch. Preserve protected files and require separate authorisation for changes to CHANGELOG.md. Merging implementation does not establish validation or acceptance.

Chat handover — historical recommendations, recorded 19 October 2026

The following recommendations originated before implementation. They are handover context, not evidence of what was implemented or validated.

• Proposed implementation branch: aiops/claude-repository-configuration, following the shared {type}/{scope}-{short-title} convention. This does not establish the actual implementation branch.
• The integration base was unresolved during planning: the repository default was develop, while contributor guidance and PR docs: reconcile repository guidance and fix Netlify routing configuration #17 referenced main. The cloud child now records that the implementation PR merged into develop; do not treat the earlier uncertainty as proof that the merge destination remains unknown.
• Two repositories were selected for the Claude session: lightspeedwp/ThisOneTimeOnAcidCom as the implementation target and lightspeedwp/.github as read-only reference material.
• Read each repository’s own instructions. Do not import .github runtime, package-manager or governance assumptions into the book repository.
• Accessible agent specifications are not necessarily registered Claude subagents. Verify discovery and invocation independently.

Consolidated session-opening handover

Read TOA-222 and its children TOA-263 through TOA-267 before
continuing. If Linear is inaccessible, request their descriptions.

Implementation target: lightspeedwp/ThisOneTimeOnAcidCom.
Reference only: lightspeedwp/.github.
Confirm checkout paths, working-tree state and active project root.
Read each repository’s own instructions before using its files.

Begin read-only. Do not edit files, install dependencies, execute
setup/build scripts, change branches, start agents, alter cloud
settings or update records until the proposed batch is approved.
Preserve uncommitted work and never print credentials.

Historical proposed branch:
aiops/claude-repository-configuration

Verify current branch policy, actual implementation branch and
integration base. Do not recreate, reset or repurpose an existing
branch. Do not restart work already delivered.

Inspect the merged implementation and current issue evidence.
Separate delivered files, author-reported results and independently
verified acceptance. Recheck runtime/package-manager decisions,
Claude compatibility and outstanding local/cloud validation.

Keep executable helpers under scripts/claude/, following current
repository instructions. Preserve protected files and avoid
unrelated repairs.

Return:
1. Verified implementation baseline with file/revision evidence.
2. Remaining gaps, contradictions and decisions.
3. Proposed next validation or remediation batch, including exact
   files, commands, dependencies and rollback.

Stop for approval before making changes or running validation.

This handover does not authorise further implementation, branch operations, record updates or closure. Existing acceptance criteria remain unresolved until supported by evidence.

Implementation checklist

1. Repository baseline and compatibility

• Read the repository’s current AGENTS.md, CONTRIBUTING.md, guidelines/README.md and applicable guidelines before adapting shared configuration.
• Inspect the existing .claude structure and record what will be added, retained or adapted.
• Resolve conflicting repository instructions before encoding package-manager, build or styling assumptions.
• Record the Claude Code version, authentication/provider, subscription prerequisites and supported execution surfaces for each requested feature. Document unavailable features and fallbacks rather than assuming local/cloud parity.
• Resolve PR placement and branch naming before implementation; preserve protected files unless separately authorised.

2. Overall, project and local settings

• Create a settings ownership matrix covering user-wide ~/.claude/settings.json, shared .claude/settings.json, private .claude/settings.local.json, managed organisation policy and session overrides.
• Define shared repository defaults separately from personal preferences, credentials and machine-specific paths.
• Add a sanitised settings.example.json and explain how it is used; do not assume an example file is automatically loaded.
• Configure only required permissions, model defaults, environment values and hooks. Document precedence and effective-setting verification.
• Validate strict JSON and supported keys; confirm loaded setting sources with /status.
• Document ignore rules, setup, reset and rollback without committing private settings or modifying organisation policy. (code.claude.com)

3. Cloud environment and environment variables

• Define the cloud environment’s repository access, runtime, package manager, dependency installation, working directory and build prerequisites.
• Add reproducible setup helpers under scripts/claude/ and supporting documentation under .claude/cloud/; distinguish repository-owned artefacts from configuration applied through the cloud environment interface.
• Configure minimum necessary network access and document external hosts, credential ownership, provisioning and rotation.
• Inventory required environment variables with purpose, scope, safe default, sensitivity and local/cloud availability; commit placeholders only.
• Test fresh-environment setup, repeat execution, missing credentials, denied network access and setup failures.
• Verify which local settings, hooks, skills and MCP connections actually reach cloud sessions; document any separate cloud setup. (code.claude.com)

4. Agents and subagents

• Verify canonical source paths and record adaptation decisions for all 17 agents already listed in this issue.
• Implement suitable definitions under .claude/agents/, with valid names, descriptions, instructions and supported frontmatter.
• Define each agent’s purpose, invocation conditions, inputs, outputs, tools, model choice, permissions and applicable isolation.
• Remove unrelated application/governance assumptions; explain unsuitable or unavailable agents rather than copying them unchanged.
• Test discovery, explicit invocation, delegation, permission boundaries and output quality using representative repository tasks. (code.claude.com)

5. Hooks

• Keep executable hook handlers and accompanying tests under scripts/claude/; use .claude/hooks/ for documentation and references, with hook registration in the appropriate settings file.
• Create a hook inventory identifying each required event, matcher, handler, purpose, setting scope and expected outcome.
• Implement repository-appropriate setup/context, protected-file safeguards, post-edit checks and completion verification where justified.
• Define JSON input/output handling, exit codes, timeouts, executable permissions, dependency checks and safe path handling.
• Prevent recursive completion hooks, duplicate execution, secret leakage and unintended destructive operations.
• Test matching and non-matching events, malformed input, missing dependencies, blocked actions and handler failures locally and in cloud.
• Document installation, debugging, disabling and rollback; do not treat hooks as a replacement for permissions or sandbox controls. (code.claude.com)

6. Skills

• Identify reusable repository workflows and implement appropriate .claude/skills/<name>/SKILL.md definitions.
• Define invocation behaviour, arguments, tool restrictions and supporting references/scripts using supported frontmatter.
• Separate reusable instructions from executable helpers; document dependencies and side effects.
• Test discovery, manual invocation, automatic invocation where intended, argument handling and overlap with agents.
• Document source mappings and maintenance responsibility for adapted shared skills. (code.claude.com)

7. MCP connections

• Inventory required MCP servers, their purpose, transport, installation, authentication and configuration scope.
• Add sanitised shared configuration only where appropriate; keep credentials and personal connections outside version control.
• Document connection approval, least-privilege tool access, external-data trust and local/cloud differences.
• Test connection health, representative read operations, approval-gated writes, unavailable servers and expired credentials.
• Provide onboarding, troubleshooting and removal instructions without enabling unrelated integrations. (code.claude.com)

8. Agent view, teams and cross-session messaging

• Document agent-view prerequisites and how to inspect progress, identify blocked work, intervene and stop agents.
• Define when to use a single session, subagents, agent teams or independent sessions.
• Establish team roles, task boundaries, dependency hand-offs, file ownership, review responsibility and shutdown procedures.
• Verify supported team display modes and required terminal dependencies.
• Define cross-session naming, addressing, inbound-message policy and local/cloud communication boundaries.
• Test messaging and hand-offs without treating another session’s message as user approval or authority to change configuration.
• Document concurrency and cost controls; keep optional capabilities explicitly opt-in until validated. (code.claude.com)

9. Workflows and worktrees

• Define representative end-to-end workflows with inputs, stages, agent/skill assignments, review gates and expected artefacts.
• Assess documented dynamic workflow support against the installed version; provide a simpler fallback where unavailable.
• Test progress inspection, interruption, failure recovery and completion evidence.
• Define worktree creation, branch naming, dependency setup, ignored-file handling and independent validation.
• Prevent concurrent agents from unintentionally editing the same checkout; document reconciliation and cleanup while preserving uncommitted work. (code.claude.com)

10. Validation and handover

• Validate settings, agent/skill frontmatter, referenced paths and executable hooks.
• Run the repository’s actual supported build/check commands; record unavailable checks rather than inventing scripts.
• Complete local and cloud smoke tests covering agents, skills, hooks, MCP, orchestration and worktree isolation.
• Check committed configuration and logs for secrets, personal paths and unnecessarily broad permissions.
• Document setup, ownership, compatibility, troubleshooting, rollback and known limitations.
• Include a requirement-to-file-and-test evidence map in the implementation PR; leave blocked items explicitly unresolved.

Phased delivery plan

The following table preserves the original proposed file mappings and delivery gates. Reconcile it with the merged implementation and requirement-to-file-and-test evidence map; it is not a statement that delivery or validation remains wholly unstarted, nor proof that acceptance gates have passed.

Validation baseline

After confirming npm as the package manager, establish the baseline with:

npm ci
npm ls --depth=0
npm run build
node --test tests/speckit.test.mjs

• Record pre-existing failures separately; do not expand scope into unrelated repairs.
• Run journal checks when applicable, after verifying the parser’s expected content location.
• Do not assume test, lint or typecheck scripts exist. Explicitly implement and test any additional Claude-specific checks.
• Preserve protected files, including CHANGELOG.md; do not copy shared automation that changes branches, global tooling or personal configuration without explicit authorisation.
• No validation results are claimed by this plan.

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

Unanswered clarification questions

These questions clarify acceptance of the delivered Claude configuration; they do not authorise installations, configuration changes or further implementation.

1. Which checked revision and evidence map each acceptance requirement to its implementation and validation?
2. Which applicable checks have completed, and what remains pending, skipped, failed or independently unverified?
3. What evidence establishes build results and local/cloud smoke-test outcomes?
4. Have the previously recorded hook-schema and test-server compatibility concerns been reassessed against the delivered revision?
5. Who accepts the agent adaptations, settings and runnable hooks/scripts, including evidence that settings contain no secrets or machine-specific configuration?