Skip to content

chore(claude-config): namespace agents and commands under cypher #693

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bhabalan wants to merge 2 commits into
base: next
Choose a base branch
from
Open

chore(claude-config): namespace agents and commands under cypher #693

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9267518
chore(claude-config): namespace agents and commands under cypher/
bhabalan Jun 3, 2026
92f63f7
fix(claude-config): use unscoped ticket-worker subagent name
bhabalan Jun 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
0 .claude/agents/fixer.md → .claude/agents/cypher/fixer.md
View file
Open in desktop
File renamed without changes.
0 .claude/agents/git-pr.md → .claude/agents/cypher/git-pr.md
View file
Open in desktop
File renamed without changes.
0 .claude/agents/qa-test-coverage.md → .claude/agents/cypher/qa-test-coverage.md
View file
Open in desktop
File renamed without changes.
0 .claude/agents/scrubber.md → .claude/agents/cypher/scrubber.md
View file
Open in desktop
File renamed without changes.
0 .claude/agents/ticket-worker.md → .claude/agents/cypher/ticket-worker.md
View file
Open in desktop
File renamed without changes.
0 .claude/agents/triager.md → .claude/agents/cypher/triager.md
View file
Open in desktop
File renamed without changes.
4 changes: 4 additions & 0 deletions .claude/commands/cleanup-worktrees.md → .claude/commands/cypher/cleanup-worktrees.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: List, inspect, and remove worktrees created by /fix-tickets in /tmp/claude-widgets/
---

# Cleanup Worktrees Command

## Description
Expand Down
11 changes: 8 additions & 3 deletions .claude/commands/fix-tickets.md → .claude/commands/cypher/fix-tickets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
description: Full lifecycle - fetch JIRA tickets, create worktrees, implement fixes, create PRs, poll review
argument-hint: "[TICKET-ID...]"
---

# Fix Tickets Command

## Description
Expand Down Expand Up @@ -115,9 +120,9 @@ Launch ALL workers in a **single message** with multiple `Task()` calls for true

```
Task({
subagent_type: "ticket-worker",
subagent_type: "cypher:ticket-worker",

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Use the actual subagent name when spawning ticket workers

When /cypher:fix-tickets reaches the parallel worker launch, this subagent_type does not match any project subagent: Claude Code scans .claude/agents/ recursively but identifies project subagents by their frontmatter name, and .claude/agents/cypher/ticket-worker.md still declares name: ticket-worker rather than cypher:ticket-worker. This means the full lifecycle command will fail to start ticket workers after the namespace move; keep the file path updates, but spawn ticket-worker unless the agent is actually provided as a scoped plugin agent.

Useful? React with 👍 / 👎.

@bhabalan bhabalan Jun 11, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in next push. Reverted to subagent_type: "ticket-worker" since project subagents are identified by frontmatter name, not file path. The cypher: prefix only applies to plugin-scoped agents.

description: "Fix ticket {TICKET_ID}",
prompt: `You are a ticket-worker agent. Follow the instructions in .claude/agents/ticket-worker.md.
prompt: `You are a ticket-worker agent. Follow the instructions in .claude/agents/cypher/ticket-worker.md.

TICKET_ID: {TICKET_ID}
WORKTREE_PATH: /tmp/claude-widgets/{TICKET_ID}
Expand All @@ -137,7 +142,7 @@ Priority: {priority}

Dependencies are already installed and packages are already built in the worktree.

Read .claude/agents/ticket-worker.md for your full workflow. Use systematic debugging to understand the root cause, apply TDD (write failing test first, then implement fix), verify all tests pass, stage changes (NO commit), and return result JSON.`,
Read .claude/agents/cypher/ticket-worker.md for your full workflow. Use systematic debugging to understand the root cause, apply TDD (write failing test first, then implement fix), verify all tests pass, stage changes (NO commit), and return result JSON.`,
run_in_background: true
})
```
Expand Down
9 changes: 7 additions & 2 deletions .claude/commands/fix.md → .claude/commands/cypher/fix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
description: Stage 3 of bug-fix pipeline - implement fixes for triaged bugs, create PRs, poll review feedback
argument-hint: "[TICKET-ID...]"
---

# Fix Command

## Description
Expand Down Expand Up @@ -107,7 +112,7 @@ Agent({
subagent_type: "general-purpose",
model: "sonnet",
description: "Fix ticket {TICKET_ID}",
prompt: `You are a fixer agent. Follow the instructions in .claude/agents/fixer.md.
prompt: `You are a fixer agent. Follow the instructions in .claude/agents/cypher/fixer.md.

TICKET_ID: {TICKET_ID}
WORKTREE_PATH: /tmp/claude-widgets/{TICKET_ID}
Expand All @@ -127,7 +132,7 @@ Description:

Dependencies are already installed and packages are already built in the worktree.

Read .claude/agents/fixer.md for your full workflow. Implement the fix, run tests, stage changes (NO commit), and return result JSON.`,
Read .claude/agents/cypher/fixer.md for your full workflow. Implement the fix, run tests, stage changes (NO commit), and return result JSON.`,
run_in_background: true
})
```
Expand Down
9 changes: 7 additions & 2 deletions .claude/commands/scrub.md → .claude/commands/cypher/scrub.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
description: Stage 1 of bug-fix pipeline - classify bug tickets as prioritize/followup/dolater for AI-readiness
argument-hint: "[TICKET-ID...]"
---

# Scrub Command

## Description
Expand Down Expand Up @@ -61,7 +66,7 @@ Agent({
subagent_type: "general-purpose",
model: "haiku",
description: "Scrub ticket {TICKET_ID}",
prompt: `You are a scrubber agent. Follow the instructions in .claude/agents/scrubber.md.
prompt: `You are a scrubber agent. Follow the instructions in .claude/agents/cypher/scrubber.md.

TICKET_ID: {TICKET_ID}

Expand All @@ -80,7 +85,7 @@ Description:
Comments:
{all comments}

Read .claude/agents/scrubber.md for your full workflow. Evaluate this ticket and return result JSON.`,
Read .claude/agents/cypher/scrubber.md for your full workflow. Evaluate this ticket and return result JSON.`,
run_in_background: true
})
```
Expand Down
4 changes: 4 additions & 0 deletions .claude/commands/spec-drift-changed.md → ...ude/commands/cypher/spec-drift-changed.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: Validate ai-docs affected by staged/unstaged changes (lightweight pre-commit drift check)
---

# Spec Drift Detection — Changed Files Only

Validate ai-docs affected by any staged/unstaged changes — whether the changes are to ai-docs themselves OR to source code that has corresponding ai-docs. Lightweight mode for pre-commit validation.
Expand Down
4 changes: 4 additions & 0 deletions .claude/commands/spec-drift.md → .claude/commands/cypher/spec-drift.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: Full SDD ai-docs validation against source code via parallel agents across 7 drift categories
---

# Spec Drift Detection — Full Scan

Run a comprehensive validation of all SDD ai-docs against actual source code. Deploys a parallel agent team to catch documentation drift across 7 categories.
Expand Down
5 changes: 5 additions & 0 deletions .claude/commands/submit-pr.md → .claude/commands/cypher/submit-pr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
description: Commit, push, and create a draft PR for a ticket fixed in a worktree (no subagents)
argument-hint: "<TICKET-ID>"
---

# Submit PR Command

## Description
Expand Down
9 changes: 7 additions & 2 deletions .claude/commands/triage.md → .claude/commands/cypher/triage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
description: Stage 2 of bug-fix pipeline - root-cause prioritized bugs and propose fixes (read-only)
argument-hint: "[TICKET-ID...]"
---

# Triage Command

## Description
Expand Down Expand Up @@ -60,7 +65,7 @@ Agent({
subagent_type: "general-purpose",
model: "sonnet",
description: "Triage ticket {TICKET_ID}",
prompt: `You are a triager agent. Follow the instructions in .claude/agents/triager.md.
prompt: `You are a triager agent. Follow the instructions in .claude/agents/cypher/triager.md.

TICKET_ID: {TICKET_ID}
REPO_ROOT: {absolute path to main repo}
Expand All @@ -79,7 +84,7 @@ Description:
Comments:
{all comments, including Scrubber's classification}

Read .claude/agents/triager.md for your full workflow. Analyze this bug, identify the root cause, and return a fix suggestion as JSON.`,
Read .claude/agents/cypher/triager.md for your full workflow. Analyze this bug, identify the root cause, and return a fix suggestion as JSON.`,
run_in_background: true
})
```
Expand Down
6 changes: 3 additions & 3 deletions .claude/hooks/check-ai-docs-drift.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@
# 3. If command is NOT git commit -> exit 0 (allow immediately)
# 4. Check if ANY staged files are under packages/contact-center/
# 5. If none -> exit 0 (allow)
# 6. Check for verification marker (created by /spec-drift-changed)
# 6. Check for verification marker (created by /cypher:spec-drift-changed)
# 7. If marker exists -> exit 0 (allow — marker stays until content changes)
# 8. If no marker -> exit 2 (BLOCK, instruct to run /spec-drift-changed)
# 8. If no marker -> exit 2 (BLOCK, instruct to run /cypher:spec-drift-changed)

CC_PKG="packages/contact-center"

Expand Down Expand Up @@ -57,6 +57,6 @@ echo ""
echo "Staged contact-center files:"
echo "$STAGED_CC" | sed 's/^/ - /'
echo ""
echo "Run /spec-drift-changed to validate ai-docs against source code before committing."
echo "Run /cypher:spec-drift-changed to validate ai-docs against source code before committing."

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Point the hook at the actual slash command

When this hook blocks a git commit with staged packages/contact-center files, it now tells the user to run /cypher:spec-drift-changed. Current Claude Code slash-command docs state that files under .claude/commands/ keep the filename as the command name and subdirectories only appear in the description, so cypher/spec-drift-changed.md is still invoked as /spec-drift-changed, not /cypher:spec-drift-changed. Following the hook's instruction leaves users at an unknown command and they cannot create the verification marker from the blocked flow.

Useful? React with 👍 / 👎.

echo "The command will check documentation accuracy and create a verification marker."
exit 2 # Exit code 2 = blocking error in Claude Code hooks
14 changes: 8 additions & 6 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@ corepack enable # If yarn is unavailable

| Command | Stage | Agent | Model | Purpose |
|---------|-------|-------|-------|---------|
| `/scrub` | 1 | scrubber | haiku | Classify bugs: `prioritize` / `followup` / `dolater` |
| `/triage` | 2 | triager | sonnet | Root-cause analysis, produce fix suggestion |
| `/fix` | 3 | fixer | sonnet | Implement fix in worktree, TDD, create PR |
| `/cypher:scrub` | 1 | cypher:scrubber | haiku | Classify bugs: `prioritize` / `followup` / `dolater` |
| `/cypher:triage` | 2 | cypher:triager | sonnet | Root-cause analysis, produce fix suggestion |
| `/cypher:fix` | 3 | cypher:fixer | sonnet | Implement fix in worktree, TDD, create PR |

Inter-stage state passes via **Jira comments** (durable, human-visible). Each stage reads previous stage's comments.
Jira labels track progress: `scrubbed` → `prioritize`/`followup`/`dolater` → `triaged` → `fixing` → `fixed`.
Expand All @@ -65,9 +65,11 @@ Jira labels track progress: `scrubbed` → `prioritize`/`followup`/`dolater` →

| Command | Purpose |
|---------|---------|
| `/fix-tickets` | Full lifecycle: fetch Jira tickets → worktree → implement → PR (uses superpowers skills) |
| `/submit-pr` | Commit + push + create PR for a worktree. Runs in main conversation (no subagents) |
| `/cleanup-worktrees` | List, inspect, and remove worktrees in `/tmp/claude-widgets/` |
| `/cypher:fix-tickets` | Full lifecycle: fetch Jira tickets → worktree → implement → PR (uses superpowers skills) |
| `/cypher:submit-pr` | Commit + push + create PR for a worktree. Runs in main conversation (no subagents) |
| `/cypher:cleanup-worktrees` | List, inspect, and remove worktrees in `/tmp/claude-widgets/` |
| `/cypher:spec-drift` | Full SDD ai-docs validation across 7 drift categories |
| `/cypher:spec-drift-changed` | Validate ai-docs for staged/unstaged changes (pre-commit) |

## Subagent Constraints

Expand Down