Add optional Claude Code features

[gilesknap]

Add a claude code question that adds:-

Primary fetures:

• installs claude code into the devcontainer
• enables auto-mode and dangerously-skip-permissions option
• adds gh and glab tools and PAT management to give claude restricted access to the specific repository
• entirely sandboxes claude from any other user credentials on the host
• refuses to run claude with these settings outside of the sandbox

Secondary features

• document in the main repo a workflow for using code as distilled from Matt Pocock's lecture https://youtu.be/-QFHIoCo-Ko?si=UwGHGjDHIQSB7q7 (or just reference https://github.com/mattpocock/skills?? - its not claude specific though)
• document how to use the sandbox and git PATs
• include useful skills to go with the above from https://github.com/mattpocock/skills

[gilesknap]

under development at:
gilesknap#6

with some minor underlying template changes here:
gilesknap#5

[gilesknap]

Also consider some recommendations for .Claude/settings.json. Some already go in the repo but some should probably just be recommend for the global settings e.g. https://engineeratheart.medium.com/the-9-claude-code-settings-power-users-change-on-day-one-acbb0c161823

[gilesknap]

I'd also like to consider helping Claude with code search. This sounds almost too good to be true but worth a look https://medium.com/vibe-coding/claude-code-is-wasting-98-of-your-tokens-on-search-heres-the-fix-1034b2039291

[gilesknap]

I'm trying the Pocock workflow and early impressions are very good.

@coretl @hyperrealist @vredchenko @garethnisbet you may be interested? Here is a summary of what I'm using (a prototype for what will go in the main docs of this repo):

Matt Pocock's Agentic Engineering Workflow

A reference for the design → spec → slice → implement pipeline used with Claude
Code in this repo. The four stages each have a slash-command or skill installed
under ~/.claude/. Each stage starts from a clean context window so the agent
isn't dragging stale assumptions into the next phase.

One-line summary

GitHub issue
   │
   ▼
[/grill-me]   interview the human until the design is pinned down
   │
   ▼
[/to-prd]     synthesise the design as a PRD issue
   │
   ▼
[/to-issues]  break the PRD into independently-grabbable issues
   │
   ▼
[tdd skill]   implement each issue, one red→green→refactor cycle at a time

Between every stage: /clear. The next stage reads from the artefact written
by the previous stage (the issue body), not from the conversation history.

---

Stage 1 — /grill-me

Purpose. Walk the design tree branch-by-branch with the human, asking one
question at a time. The agent recommends an answer for each question and
explains its reasoning so the human can redirect rather than rubber-stamp.

When to use. You have a problem statement (typically a GitHub issue) but
no concrete design. Decisions are interlinked and you want to surface them
deliberately rather than discover them mid-implementation.

Inputs.

• A reference to the problem space: an issue number, an idea, a reproduction.

Outputs.

• A shared understanding between human and agent of every meaningful design
  decision. Lives only in the conversation.

Discipline.

• The agent asks one question at a time and waits for an answer.
• The agent grounds its recommendations in code references (file paths, line
  numbers, existing class names) rather than hand-waving.
• The agent explores the codebase to answer questions that the codebase can
  answer, instead of asking the human.
• When agreement is reached on a sub-decision the agent moves on; it doesn't
  re-litigate.

Typical exit signal. The agent has nothing more to ask, or the human says
"looks good — write it up."

---

Stage 2 — /to-prd

Purpose. Convert the conversation context from /grill-me into a Product
Requirements Document and post it as a new issue on the project's tracker.

When to use. Immediately after /grill-me while the design context is
still in the agent's memory.

Inputs.

• The current conversation context (no arguments needed for the simple case).
• Optionally an issue number for the original problem to cross-link.

Outputs.

• A new GitHub issue containing the PRD, formatted with these sections:
  • Problem Statement (in the user's voice)
  • Solution (in the user's voice)
  • User Stories (a long, numbered list)
  • Implementation Decisions (architectural and interface choices, no code)
  • Testing Decisions (what to test, prior art, what makes a good test)
  • Out of Scope
  • Further Notes
• Triage label applied so it enters the team's normal triage flow.

Discipline.

• The agent does not re-interview. It synthesises from what it already knows.
• The agent first sketches the major modules it expects to build/modify and
  confirms with the human. It calls out candidates for "deep modules"
  (narrow public interfaces hiding meaningful complexity) and asks which to
  cover with unit tests.
• The PRD avoids file paths and code snippets — both go stale fast.
• The agent posts the issue at the end so the artefact is durable; if the
  agent's GitHub token can't post, it provides the body for the human.

Typical exit signal. The PRD URL is shared. The conversation can be
cleared.

---

Stage 3 — /to-issues

Purpose. Break a PRD into a set of independently-grabbable GitHub issues
using vertical-slice tracer bullets. Each issue cuts thinly through every
layer (schema, API, UI, tests) and is demoable on its own.

When to use. After a PRD exists. Run this in a fresh context window — the
skill reads the PRD from the issue tracker, not from conversation history.

Inputs.

• An issue reference (number, URL, or path) for the PRD.

Outputs.

• A set of GitHub issues, each tagged HITL (needs human in the loop, e.g. for
  a design decision or a review) or AFK (away from keyboard — implementable
  end-to-end without further input).
• Dependency relationships between issues recorded in the descriptions.

Discipline.

• Vertical slices, not horizontal. Don't ship "all the schema" or "all the
  tests" as one issue — ship "user can do thing X end-to-end" as one issue.
• Prefer many thin slices over few thick ones.
• Prefer AFK over HITL where possible.
• The agent presents the proposed breakdown as a numbered list and quizzes
  the human on granularity, ordering, and HITL/AFK tagging before posting.

Caveat for refactor work. Some PRDs (large refactors with type-contract
entanglement) don't slice into many independent issues. In that case the
output may be just 2–3 issues: small AFK prep issues plus one large HITL
issue for the atomic switch. That's still the correct answer — the
constraint is on the work, not the workflow.

Typical exit signal. Issues are posted, dependencies are clear, the human
picks the first one to implement.

---

Stage 4 — tdd skill

Purpose. Implement one issue using a strict red → green → refactor loop,
producing tests that describe behaviour through public interfaces rather
than implementation details.

When to use. After /to-issues has produced an issue you want to land.
Run in a fresh context window per issue.

Inputs.

• The issue to implement (reference, or paste in the body).

Outputs.

• A PR (or commit series) that ships the issue green, with tests that
  describe externally-observable behaviour.

Discipline.

• Vertical slices, not horizontal. Write one test → make it pass → write
  the next test. Do not write all tests first; that produces tests of
  imagined behaviour rather than real behaviour.
• Test through public interfaces. A good test would survive a complete
  refactor of the internals. If renaming a private function breaks a test,
  that test was wrong.
• Minimal code per cycle. Add only enough to pass the current test. No
  speculative features.
• Never refactor while red. Get to green first; refactor with the safety
  net of green tests.
• Use the project's vocabulary. Test names and interface names match the
  domain glossary documented in CONTEXT.md / docs/explanations/ / ADRs.
  Respect the architectural decisions already made.

Per-cycle checklist:

• The test describes behaviour, not implementation.
• The test uses the public interface only.
• The test would survive an internal refactor.
• The code is minimal for this test.
• No speculative features added.

Typical exit signal. All planned tests are green. PR opened.

---

Why /clear between stages

Each stage produces a durable artefact (a GitHub issue, a PR). The next
stage reads from that artefact, not from conversation memory. Clearing
between stages:

• Keeps the agent's context window focused on the current task.
• Stops stale assumptions from one stage leaking into the next.
• Forces the artefacts to be self-contained — if a future maintainer (or a
  fresh agent) can't pick up the work from the artefact alone, the artefact
  is incomplete and should be improved.
• Makes the agent's context cost roughly proportional to the size of the
  current task, not the full history of the project.

Skip /clear only when staying within one stage (e.g. iterating on the
to-issues breakdown before posting).

---

Other useful commands in the same family

These don't sit on the main pipeline but compose well with it:

• /zoom-out — ask the agent to step back and explain a section of code
  at a higher level. Useful when grilling is going too narrow too fast.
• improve-codebase-architecture — find deepening opportunities in
  existing code. Reads CONTEXT.md and ADRs and proposes specific refactors.
  A maintenance counterpart to the design pipeline.
• grill-with-docs — variant of /grill-me that updates CONTEXT.md
  and ADRs as a side effect, keeping the project's design documentation in
  sync with decisions made during interviews.
• diagnose — a disciplined bug/perf-regression loop (reproduce →
  minimise → hypothesise → instrument → fix → regression-test). Use instead
  of /grill-me when the entry point is a defect, not a feature.
• triage — process incoming issues through a state machine of triage
  roles. Use on the receiving end of /to-prd and /to-issues to keep the
  tracker tidy.
• setup-matt-pocock-skills — scaffold per-repo config (issue tracker,
  triage label vocabulary, domain doc layout) that the other skills read.
  Run once per new repo.

---

Worked example (from fastcs work so far)

Issue #120 ("Allow a single FastCS server to have multiple top level
Controllers with different prefixes") had several months of inconclusive
discussion in comments. The pipeline turned that into actionable work:

1. /grill-me #120 — 17 design questions answered one at a time. Mid-way
   the human realised dict-keyed-by-id was cleaner than list-with-id field
   and posted a heads-up comment to the original issue thread. Final summary
   covered runtime model, lifecycle, transport contract, EPICS internals, GUI
   layout, scope cut, demo design, and tests strategy.
2. /clear.
3. /to-prd — produced PRD #351 with 34 user stories, full
   implementation and testing decisions, and explicit out-of-scope items.
   Posted to the tracker tagged enhancement, python, needs design.
4. /clear.
5. /to-issues 351 — broke the PRD into a small number of issues (two[/-]
   [+]6. /to-issues 351 — broke the PRD into a small number of issues (two AFK prep issues plus one HITL atomic-switch issue, given the[/+][-] AFK prep issues plus one HITL atomic-switch issue, given the[/-]
   type-contract entanglement of the refactor).
6. /clear before each.
7. tdd skill per issue — implement each one red → green → refactor.

The above process created this PR