Skip to content

plan: design Claude Code hook integration#14

Draft
mariusvniekerk wants to merge 5 commits into
mainfrom
claude-hooks-design
Draft

plan: design Claude Code hook integration#14
mariusvniekerk wants to merge 5 commits into
mainfrom
claude-hooks-design

Conversation

@mariusvniekerk

@mariusvniekerk mariusvniekerk commented May 5, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • add a design spec for a new kata hooks claude command namespace
  • define Claude Code TaskCreated/TaskCompleted hook install and runtime behavior
  • document safety choices around kata init, absolute executable paths, handler ownership, issue lookup, settings merge behavior, and implementation staging

Validation

  • design-only change
  • self-reviewed for stale command names, JSON shape, placeholders, and section numbering
  • ran roborev design review job 807 and revised the spec to address its findings

@roborev-ci

roborev-ci Bot commented May 5, 2026

Copy link
Copy Markdown

roborev: Combined Review (fa24dd5)

No Medium, High, or Critical issues found.

All reviewers agreed the PR only adds a design/spec document and introduces no actionable code or security findings.

Synthesized from 3 reviews (agents: codex, gemini | types: default, security)

@mariusvniekerk mariusvniekerk marked this pull request as draft May 5, 2026 17:35
@mariusvniekerk mariusvniekerk changed the title docs: design Claude Code hook integration plan: design Claude Code hook integration May 5, 2026
@roborev-ci

roborev-ci Bot commented May 5, 2026

Copy link
Copy Markdown

roborev: Combined Review (4089ec8)

Medium issue found in the design spec; no security findings.

Medium

  • docs/superpowers/specs/2026-05-05-kata-claude-hooks-design.md:209
    The spec is ambiguous about unresolved issue references. It says a missing referenced issue is “treated like no usable reference,” which would allow the TaskCreated flow to create or reuse an issue, but later guidance says an issue-looking reference that does not resolve should block and ask Claude to fix the reference. This could create duplicate issues for stale or incorrect kata #N references.

    Suggested fix: Split the cases explicitly: “no reference present” may create or reuse an issue, while “reference present but unresolved” must block without creating a new issue.

Synthesized from 3 reviews (agents: codex, gemini | types: default, security)

@roborev-ci

roborev-ci Bot commented May 5, 2026

Copy link
Copy Markdown

roborev: Combined Review (c030ea0)

Medium-risk issue found; no high or critical findings.

Medium

  • docs/superpowers/specs/2026-05-05-kata-claude-hooks-design.md:89
    The canonical Claude command shape double-quotes the kata executable path, which is not shell-safe for paths containing command substitution or other shell-expanded characters. Since Claude executes a command string, an installed path containing characters like $() could execute unintended shell code.
    Fix: Specify robust shell escaping for the executable path, and add tests covering paths with $, backticks, backslashes, and quotes.

Synthesized from 3 reviews (agents: codex, gemini | types: default, security)

@mariusvniekerk

mariusvniekerk commented May 5, 2026

Copy link
Copy Markdown
Collaborator Author

the actual claude code hooks example EXPRESSLY has quoted executables.

mariusvniekerk and others added 5 commits May 17, 2026 13:53
@mariusvniekerk @codex
docs: design Claude Code hook integration
bb3c9f1 
Capture the approved shape for installing Claude Code TaskCreated and TaskCompleted hooks under the kata hooks namespace. The design keeps Claude settings as thin wiring and puts runtime behavior behind a testable kata command so issue hygiene can evolve without generated scripts.

Validation: design-only change; self-reviewed for stale command names, placeholders, and scope contradictions.

Generated with OpenAI Codex
Co-authored-by: OpenAI Codex <noreply@openai.com>
@mariusvniekerk @codex
docs: tighten Claude hook design
67534b0 
Address the design review gaps before implementation planning: pin the Claude task payload source, make installed hooks independent of PATH, define managed-handler ownership, specify issue lookup and invalid settings behavior, and split the work into reviewable implementation slices.

Validation: design-only change; reviewed the spec for stale command names, placeholder text, JSON shape, and section numbering.

Generated with OpenAI Codex
Co-authored-by: OpenAI Codex <noreply@openai.com>
@mariusvniekerk @codex
docs: steer Claude tasks through kata issues
57166d9 
Refine the Claude hook design so kata, not Claude Code task IDs, owns the durable work identity. TaskCreated now creates or reuses a kata issue and returns the resulting kata number through Claude's exit-2 feedback path, avoiding a hidden mapping from Claude internals to project state.

Validation: design-only change; checked for leftover task_id correlation language and reviewed the spec diff.

Generated with OpenAI Codex
Co-authored-by: OpenAI Codex <noreply@openai.com>
@mariusvniekerk @codex
docs: note Claude hook creation question
95ab12f 
Record the unresolved product choice around TaskCreated behavior before implementation planning: the hook can either create/reuse the kata issue and return a concrete issue number, or only steer Claude to run the kata command itself.

Validation: design-only change; reviewed the doc diff.

Generated with OpenAI Codex
Co-authored-by: OpenAI Codex <noreply@openai.com>
@mariusvniekerk @codex
docs: update Claude hook refs for short IDs
421f178 
kata no longer resolves legacy numeric task refs, so the Claude hook design needs to steer models toward stored short_id refs and ULIDs instead of #N placeholders. Keep the lookup guidance conservative so bare short IDs are resolved only when task text clearly marks them as kata issue references.

Validation: checked for stale #N/{number}/positive-integer placeholders; GOFLAGS=-buildvcs=false go test -p=1 ./...

Generated with OpenAI Codex
Co-authored-by: OpenAI Codex <noreply@openai.com>
@roborev-ci

roborev-ci Bot commented May 17, 2026

Copy link
Copy Markdown

roborev: Combined Review (421f178)

Summary verdict: Medium issues remain in the spec; security review found no issues.

Medium

  • docs/superpowers/specs/2026-05-05-kata-claude-hooks-design.md:274
    The spec ends with an unresolved open question about whether TaskCreated should create/reuse issues, while earlier sections and implementation stages require create/reuse behavior. This makes the runtime contract internally inconsistent for implementers and tests.
    Fix: Resolve the open question before implementation, either by removing it or by moving create/reuse into an explicit pending decision.

  • docs/superpowers/specs/2026-05-05-kata-claude-hooks-design.md:142
    The spec uses kata#abc4 as the canonical reference example while defining qualified refs as <project>#<short_id> and saying the qualifier selects the project. In projects not named kata, this guidance could produce a reference that resolves against the wrong project or fails.
    Fix: Clarify whether kata# is a literal namespace marker or a project qualifier. If it is a project qualifier, examples and stderr guidance should use the resolved project alias/name or prefer the bare short ID.

Synthesized from 3 reviews (agents: codex, gemini | types: default, security)

@roborev-ci

roborev-ci Bot commented May 21, 2026

Copy link
Copy Markdown

roborev: Combined Review (421f178)

Summary verdict: Medium issues remain in the new hook integration spec; no High or Critical findings were reported.

Medium

  • docs/superpowers/specs/2026-05-05-kata-claude-hooks-design.md:142
    The spec defines qualified refs as <project>#<short_id> but uses kata#abc4 in user-facing guidance as if it were universally valid. In non-kata projects, that guidance can resolve against the wrong project or fail.
    Fix: Use the resolved project qualifier dynamically, or prefer the bare short ID where the current project is already known.

  • docs/superpowers/specs/2026-05-05-kata-claude-hooks-design.md:397
    The spec still has an “Open question” about whether TaskCreated should create/reuse issues, while earlier sections and implementation stages require create/reuse behavior. This leaves the implementation contract internally inconsistent.
    Fix: Remove the open question or rewrite it as a resolved decision, moving any remaining alternatives to future work.

Synthesized from 3 reviews (agents: codex, gemini | types: default, security)

@roborev-ci

roborev-ci Bot commented Jun 1, 2026

Copy link
Copy Markdown

roborev: Pass

No issues found.

Review type: | Agent: codex | Job: 19213

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mariusvniekerk