@wbern/claude-instructions 1.7.0 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +1 -0
  2. package/bin/cli.js +73 -26
  3. package/downloads/with-beads/add-command.md +27 -0
  4. package/downloads/with-beads/ask.md +5 -1
  5. package/downloads/with-beads/beepboop.md +2 -8
  6. package/downloads/with-beads/busycommit.md +9 -2
  7. package/downloads/with-beads/commit.md +9 -2
  8. package/downloads/with-beads/cycle.md +4 -0
  9. package/downloads/with-beads/gap.md +17 -5
  10. package/downloads/with-beads/green.md +4 -0
  11. package/downloads/with-beads/issue.md +12 -3
  12. package/downloads/with-beads/plan.md +22 -1
  13. package/downloads/with-beads/red.md +9 -2
  14. package/downloads/with-beads/refactor.md +6 -0
  15. package/downloads/with-beads/ship.md +5 -1
  16. package/downloads/with-beads/show.md +5 -1
  17. package/downloads/with-beads/spike.md +4 -0
  18. package/downloads/with-beads/summarize.md +15 -0
  19. package/downloads/with-beads/tdd.md +3 -0
  20. package/downloads/with-beads/worktree-add.md +17 -13
  21. package/downloads/with-beads/worktree-cleanup.md +18 -14
  22. package/downloads/without-beads/add-command.md +25 -0
  23. package/downloads/without-beads/ask.md +1 -1
  24. package/downloads/without-beads/beepboop.md +1 -1
  25. package/downloads/without-beads/busycommit.md +7 -2
  26. package/downloads/without-beads/commit.md +7 -2
  27. package/downloads/without-beads/cycle.md +2 -3
  28. package/downloads/without-beads/gap.md +11 -1
  29. package/downloads/without-beads/green.md +2 -3
  30. package/downloads/without-beads/issue.md +8 -3
  31. package/downloads/without-beads/plan.md +12 -2
  32. package/downloads/without-beads/red.md +4 -2
  33. package/downloads/without-beads/refactor.md +4 -3
  34. package/downloads/without-beads/ship.md +1 -1
  35. package/downloads/without-beads/show.md +1 -1
  36. package/downloads/without-beads/spike.md +2 -3
  37. package/downloads/without-beads/summarize.md +12 -1
  38. package/downloads/without-beads/tdd.md +1 -0
  39. package/downloads/without-beads/worktree-add.md +15 -13
  40. package/downloads/without-beads/worktree-cleanup.md +16 -14
  41. package/package.json +2 -1
package/README.md CHANGED
@@ -106,6 +106,7 @@ This injects the content only into `commit.md` and `ask.md`.
106
106
  ### File Priority
107
107
 
108
108
  The generator looks for template blocks in this order:
109
+
109
110
  1. `CLAUDE.md` (checked first)
110
111
  2. `AGENTS.md` (fallback)
111
112
 
package/bin/cli.js CHANGED
@@ -38,19 +38,48 @@ function truncatePathFromLeft(pathStr, maxLength) {
38
38
  return ELLIPSIS + truncated;
39
39
  }
40
40
  var VARIANT_OPTIONS = [
41
- { value: VARIANTS.WITH_BEADS, label: "With Beads", hint: "Includes Beads task tracking" },
42
- { value: VARIANTS.WITHOUT_BEADS, label: "Without Beads", hint: "Standard commands only" }
41
+ {
42
+ value: VARIANTS.WITH_BEADS,
43
+ label: "With Beads",
44
+ hint: "Includes Beads task tracking"
45
+ },
46
+ {
47
+ value: VARIANTS.WITHOUT_BEADS,
48
+ label: "Without Beads",
49
+ hint: "Standard commands only"
50
+ }
43
51
  ];
44
52
  function getScopeOptions(terminalWidth = 80) {
45
- const projectPath = path.join(process.cwd(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
46
- const userPath = path.join(os.homedir(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
53
+ const projectPath = path.join(
54
+ process.cwd(),
55
+ DIRECTORIES.CLAUDE,
56
+ DIRECTORIES.COMMANDS
57
+ );
58
+ const userPath = path.join(
59
+ os.homedir(),
60
+ DIRECTORIES.CLAUDE,
61
+ DIRECTORIES.COMMANDS
62
+ );
47
63
  return [
48
- { value: SCOPES.PROJECT, label: "Project/Repository", hint: truncatePathFromLeft(projectPath, terminalWidth) },
49
- { value: SCOPES.USER, label: "User (Global)", hint: truncatePathFromLeft(userPath, terminalWidth) }
64
+ {
65
+ value: SCOPES.PROJECT,
66
+ label: "Project/Repository",
67
+ hint: truncatePathFromLeft(projectPath, terminalWidth)
68
+ },
69
+ {
70
+ value: SCOPES.USER,
71
+ label: "User (Global)",
72
+ hint: truncatePathFromLeft(userPath, terminalWidth)
73
+ }
50
74
  ];
51
75
  }
52
76
  async function getCommandsGroupedByCategory(variant) {
53
- const sourcePath = path.join(__dirname, "..", DIRECTORIES.DOWNLOADS, variant || VARIANTS.WITH_BEADS);
77
+ const sourcePath = path.join(
78
+ __dirname,
79
+ "..",
80
+ DIRECTORIES.DOWNLOADS,
81
+ variant || VARIANTS.WITH_BEADS
82
+ );
54
83
  const metadataPath = path.join(sourcePath, "commands-metadata.json");
55
84
  const metadataContent = await fs.readFile(metadataPath, "utf-8");
56
85
  const metadata = JSON.parse(metadataContent);
@@ -87,21 +116,29 @@ function getDestinationPath(outputPath, scope) {
87
116
  return void 0;
88
117
  }
89
118
  function extractTemplateBlocks(content) {
90
- const matchWithCommands = content.match(/<claude-commands-template\s+commands="([^"]+)">([\s\S]*?)<\/claude-commands-template>/);
91
- if (matchWithCommands) {
92
- return {
93
- content: matchWithCommands[2].trim(),
94
- commands: matchWithCommands[1].split(",").map((c) => c.trim())
95
- };
119
+ const blocks = [];
120
+ const withCommandsRegex = /<claude-commands-template\s+commands="([^"]+)">([\s\S]*?)<\/claude-commands-template>/g;
121
+ for (const match of content.matchAll(withCommandsRegex)) {
122
+ blocks.push({
123
+ content: match[2].trim(),
124
+ commands: match[1].split(",").map((c) => c.trim())
125
+ });
96
126
  }
97
- const match = content.match(/<claude-commands-template>([\s\S]*?)<\/claude-commands-template>/);
98
- if (!match) {
99
- return null;
127
+ const withoutCommandsRegex = /<claude-commands-template>([\s\S]*?)<\/claude-commands-template>/g;
128
+ for (const match of content.matchAll(withoutCommandsRegex)) {
129
+ blocks.push({
130
+ content: match[1].trim()
131
+ });
100
132
  }
101
- return { content: match[1].trim() };
133
+ return blocks;
102
134
  }
103
135
  async function generateToDirectory(outputPath, variant, scope, options) {
104
- const sourcePath = path.join(__dirname, "..", DIRECTORIES.DOWNLOADS, variant || VARIANTS.WITH_BEADS);
136
+ const sourcePath = path.join(
137
+ __dirname,
138
+ "..",
139
+ DIRECTORIES.DOWNLOADS,
140
+ variant || VARIANTS.WITH_BEADS
141
+ );
105
142
  const destinationPath = getDestinationPath(outputPath, scope);
106
143
  if (!destinationPath) {
107
144
  throw new Error("Either outputPath or scope must be provided");
@@ -111,7 +148,10 @@ async function generateToDirectory(outputPath, variant, scope, options) {
111
148
  if (options?.commands) {
112
149
  await fs.ensureDir(destinationPath);
113
150
  for (const file of files) {
114
- await fs.copy(path.join(sourcePath, file), path.join(destinationPath, file));
151
+ await fs.copy(
152
+ path.join(sourcePath, file),
153
+ path.join(destinationPath, file)
154
+ );
115
155
  }
116
156
  } else {
117
157
  await fs.copy(sourcePath, destinationPath, {});
@@ -135,17 +175,24 @@ async function generateToDirectory(outputPath, variant, scope, options) {
135
175
  }
136
176
  if (templateSourcePath) {
137
177
  const sourceContent = await fs.readFile(templateSourcePath, "utf-8");
138
- const template = extractTemplateBlocks(sourceContent);
139
- if (template) {
178
+ const templates = extractTemplateBlocks(sourceContent);
179
+ if (templates.length > 0) {
140
180
  for (const file of files) {
141
181
  const commandName = path.basename(file, ".md");
142
- if (template.commands && !template.commands.includes(commandName)) {
143
- continue;
144
- }
145
182
  const actualFileName = options?.commandPrefix ? options.commandPrefix + file : file;
146
183
  const filePath = path.join(destinationPath, actualFileName);
147
- const content = await fs.readFile(filePath, "utf-8");
148
- await fs.writeFile(filePath, content + "\n\n" + template.content);
184
+ let content = await fs.readFile(filePath, "utf-8");
185
+ let modified = false;
186
+ for (const template of templates) {
187
+ if (template.commands && !template.commands.includes(commandName)) {
188
+ continue;
189
+ }
190
+ content = content + "\n\n" + template.content;
191
+ modified = true;
192
+ }
193
+ if (modified) {
194
+ await fs.writeFile(filePath, content);
195
+ }
149
196
  }
150
197
  templateInjected = true;
151
198
  }
@@ -3,10 +3,22 @@ description: Guide for creating new slash commands
3
3
  argument-hint: <command-name> <description>
4
4
  ---
5
5
 
6
+ ## General Guidelines
7
+
8
+ ### Output Style
9
+
10
+ - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
11
+ - Write natural, descriptive code without meta-commentary about the development process
12
+ - The code should speak for itself - TDD is the process, not the product
13
+
14
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
15
+
6
16
  # Slash Command Creator Guide
7
17
 
8
18
  ## How This Command Works
19
+
9
20
  The `/add-command` command shows this guide for creating new slash commands. It includes:
21
+
10
22
  - Command structure and syntax
11
23
  - Common patterns and examples
12
24
  - Security restrictions and limitations
@@ -15,6 +27,7 @@ The `/add-command` command shows this guide for creating new slash commands. It
15
27
  **Note for AI**: When creating commands, you CAN use bash tools like `Bash(mkdir:*)`, `Bash(ls:*)`, `Bash(git status:*)` in the `allowed-tools` frontmatter of NEW commands - but ONLY for operations within the current project directory. This command itself doesn't need bash tools since it's just documentation.
16
28
 
17
29
  ## Command Locations
30
+
18
31
  - **Personal**: `~/.claude/commands/` (available across all projects)
19
32
  - **Project**: `.claude/commands/` (shared with team, shows "(project)")
20
33
 
@@ -41,33 +54,40 @@ Bash command output: (exclamation)git status(backticks)
41
54
  ## ⚠️ Security Restrictions
42
55
 
43
56
  **Bash Commands (exclamation prefix)**: Limited to current working directory only.
57
+
44
58
  - ✅ Works: `! + backtick + git status + backtick` (in project dir)
45
59
  - ❌ Blocked: `! + backtick + ls /outside/project + backtick` (outside project)
46
60
  - ❌ Blocked: `! + backtick + pwd + backtick` (if referencing dirs outside project)
47
61
 
48
62
  **File References (`@` prefix)**: No directory restrictions.
63
+
49
64
  - ✅ Works: `@/path/to/system/file.md`
50
65
  - ✅ Works: `@../other-project/file.js`
51
66
 
52
67
  ## Common Patterns
53
68
 
54
69
  ### Simple Command
70
+
55
71
  ```bash
56
72
  echo "Review this code for bugs and suggest fixes" > ~/.claude/commands/review.md
57
73
  ```
58
74
 
59
75
  ### Command with Arguments
76
+
60
77
  **Note for AI**: The example below uses a fullwidth dollar sign ($, U+FF04) to prevent interpolation in this documentation. When creating actual commands, use the regular `$` character.
78
+
61
79
  ```markdown
62
80
  Fix issue $ARGUMENTS following our coding standards
63
81
  ```
64
82
 
65
83
  ### Command with File References
84
+
66
85
  ```markdown
67
86
  Compare @src/old.js with @src/new.js and explain differences
68
87
  ```
69
88
 
70
89
  ### Command with Bash Output (Project Directory Only)
90
+
71
91
  ```markdown
72
92
  ---
73
93
  allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git log:*)
@@ -82,7 +102,9 @@ Create commit for these changes.
82
102
  **Note**: Only works with commands in the current project directory.
83
103
 
84
104
  ### Namespaced Command
105
+
85
106
  **Note for AI**: The example below uses a fullwidth dollar sign ($, U+FF04) to prevent interpolation in this documentation. When creating actual commands, use the regular `$` character.
107
+
86
108
  ```bash
87
109
  mkdir -p ~/.claude/commands/ai
88
110
  echo "Ask GPT-5 about: $ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
@@ -90,6 +112,7 @@ echo "Ask GPT-5 about: $ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
90
112
  ```
91
113
 
92
114
  ## Frontmatter Options
115
+
93
116
  - `allowed-tools`: Tools this command can use
94
117
  - **Important**: Intrusive tools like `Write`, `Edit`, `NotebookEdit` should NEVER be allowed in commands unless the user explicitly requests them. These tools modify files and should only be used when the command's purpose is to make changes.
95
118
  - ✅ Safe for most commands: `Read`, `Glob`, `Grep`, `Bash(git status:*)`, `Task`, `AskUserQuestion`
@@ -100,6 +123,7 @@ echo "Ask GPT-5 about: $ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
100
123
  ## Best Practices
101
124
 
102
125
  ### Safe Commands (No Security Issues)
126
+
103
127
  ```markdown
104
128
  # System prompt editor (file reference only)
105
129
  (@)path/to/system/prompt.md
@@ -108,6 +132,7 @@ Edit your system prompt above.
108
132
  ```
109
133
 
110
134
  ### Project-Specific Commands (Bash OK)
135
+
111
136
  ```markdown
112
137
  ---
113
138
  allowed-tools: Bash(git status:*), Bash(npm list:*)
@@ -119,6 +144,7 @@ Review project state and suggest next steps.
119
144
  ```
120
145
 
121
146
  ### Cross-Directory File Access (Use @ not !)
147
+
122
148
  ```markdown
123
149
  # Compare config files
124
150
  Compare (@)path/to/system.md with (@)project/config.md
@@ -127,6 +153,7 @@ Show differences and suggest improvements.
127
153
  ```
128
154
 
129
155
  ## Usage
156
+
130
157
  After creating: `/<command-name> [arguments]`
131
158
 
132
159
  Example: `/review` or `/ai:gpt5 "explain this code"`
@@ -9,10 +9,13 @@ argument-hint: [optional-pr-title-and-description]
9
9
  ## General Guidelines
10
10
 
11
11
  ### Output Style
12
+
12
13
  - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
13
14
  - Write natural, descriptive code without meta-commentary about the development process
14
15
  - The code should speak for itself - TDD is the process, not the product
15
16
 
17
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
18
+
16
19
  **Ship/Show/Ask Pattern - ASK**
17
20
 
18
21
  > 💭 **Cursor says**: Fine, SOME things still need traditional PRs. But be intentional about it.
@@ -136,8 +139,9 @@ Use **/ship** instead if: change is tiny, obvious, and safe
136
139
  ### Beads Integration
137
140
 
138
141
  Use Beads MCP to:
142
+
139
143
  - Track work with `bd ready` to find next task
140
144
  - Create issues with `bd create "description"`
141
145
  - Track dependencies with `bd dep add`
142
146
 
143
- See https://github.com/steveyegge/beads for more information.
147
+ See <https://github.com/steveyegge/beads> for more information.
@@ -11,18 +11,12 @@ Execute the user's requested task (e.g., posting PR comments, GitHub issue comme
11
11
  ## General Guidelines
12
12
 
13
13
  ### Output Style
14
+
14
15
  - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
15
16
  - Write natural, descriptive code without meta-commentary about the development process
16
17
  - The code should speak for itself - TDD is the process, not the product
17
18
 
18
- ### Beads Integration
19
-
20
- Use Beads MCP to:
21
- - Track work with `bd ready` to find next task
22
- - Create issues with `bd create "description"`
23
- - Track dependencies with `bd dep add`
24
-
25
- See https://github.com/steveyegge/beads for more information.
19
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
26
20
 
27
21
  ## Instructions
28
22
 
@@ -4,12 +4,19 @@ description: Create multiple atomic git commits, one logical change at a time
4
4
  argument-hint: [optional-commit-description]
5
5
  ---
6
6
 
7
- Create multiple atomic git commits, committing the smallest possible logical unit at a time
7
+ ## General Guidelines
8
8
 
9
- Include any of the following info if specified: $ARGUMENTS
9
+ ### Output Style
10
10
 
11
+ - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
12
+ - Write natural, descriptive code without meta-commentary about the development process
13
+ - The code should speak for itself - TDD is the process, not the product
11
14
 
15
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
12
16
 
17
+ Create multiple atomic git commits, committing the smallest possible logical unit at a time
18
+
19
+ Include any of the following info if specified: $ARGUMENTS
13
20
 
14
21
  ## Process
15
22
 
@@ -4,12 +4,19 @@ description: Create a git commit following project standards
4
4
  argument-hint: [optional-commit-description]
5
5
  ---
6
6
 
7
- Create a git commit following project standards
7
+ ## General Guidelines
8
8
 
9
- Include any of the following info if specified: $ARGUMENTS
9
+ ### Output Style
10
10
 
11
+ - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
12
+ - Write natural, descriptive code without meta-commentary about the development process
13
+ - The code should speak for itself - TDD is the process, not the product
11
14
 
15
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
12
16
 
17
+ Create a git commit following project standards
18
+
19
+ Include any of the following info if specified: $ARGUMENTS
13
20
 
14
21
  ## Process
15
22
 
@@ -11,11 +11,15 @@ $ARGUMENTS
11
11
  ## General Guidelines
12
12
 
13
13
  ### Output Style
14
+
14
15
  - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
15
16
  - Write natural, descriptive code without meta-commentary about the development process
16
17
  - The code should speak for itself - TDD is the process, not the product
17
18
 
19
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
20
+
18
21
  (If there was no info above, fallback to:
22
+
19
23
  1. Context of the conversation, if there's an immediate thing
20
24
  2. `bd ready` to see what to work on next and start from there)
21
25
 
@@ -1,17 +1,29 @@
1
1
  ---
2
2
  description: Analyze conversation context for unaddressed items and gaps
3
+ argument-hint: [optional additional info]
3
4
  ---
4
5
 
6
+ ## General Guidelines
7
+
8
+ ### Output Style
9
+
10
+ - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
11
+ - Write natural, descriptive code without meta-commentary about the development process
12
+ - The code should speak for itself - TDD is the process, not the product
13
+
14
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
15
+
5
16
  Analyze the current conversation context and identify things that have not yet been addressed. Look for:
6
17
 
7
18
  1. **Incomplete implementations** - Code that was started but not finished
8
19
  2. **Unused variables/results** - Values that were captured but never used
9
20
  3. **Missing tests** - Functionality without test coverage
10
- 4. **Open issues** - Beads issues that are still open or in progress
11
- 4. **User requests** - Things the user asked for that weren't fully completed
12
- 5. **TODO comments** - Any TODOs mentioned in conversation
13
- 6. **Error handling gaps** - Missing error cases or edge cases
14
- 7. **Documentation gaps** - Undocumented APIs or features
21
+ 4. **Open issues** - Beads issues that are still open or in progress
22
+ 5. **User requests** - Things the user asked for that weren't fully completed
23
+ 6. **TODO comments** - Any TODOs mentioned in conversation
24
+ 7. **Error handling gaps** - Missing error cases or edge cases
25
+ 8. **Documentation gaps** - Undocumented APIs or features
26
+ 9. **Consistency check** - Look for inconsistent patterns, naming conventions, or structure across the codebase
15
27
 
16
28
  Present findings as a prioritized list with:
17
29
 
@@ -11,11 +11,15 @@ $ARGUMENTS
11
11
  ## General Guidelines
12
12
 
13
13
  ### Output Style
14
+
14
15
  - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
15
16
  - Write natural, descriptive code without meta-commentary about the development process
16
17
  - The code should speak for itself - TDD is the process, not the product
17
18
 
19
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
20
+
18
21
  (If there was no info above, fallback to:
22
+
19
23
  1. Context of the conversation, if there's an immediate thing
20
24
  2. `bd ready` to see what to work on next and start from there)
21
25
 
@@ -9,10 +9,13 @@ Analyze GitHub issue and create TDD implementation plan.
9
9
  ## General Guidelines
10
10
 
11
11
  ### Output Style
12
+
12
13
  - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
13
14
  - Write natural, descriptive code without meta-commentary about the development process
14
15
  - The code should speak for itself - TDD is the process, not the product
15
16
 
17
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
18
+
16
19
  Process:
17
20
 
18
21
  1. Get Issue Number
@@ -22,11 +25,12 @@ Process:
22
25
  - Or from this bullet point with custom info: $ARGUMENTS
23
26
  - If not found: ask user
24
27
 
25
- 2. Fetch Issue
28
+ 1. Fetch Issue
26
29
 
27
30
  Try to fetch the issue using GitHub MCP (mcp__github__issue_read tool).
28
31
 
29
32
  If GitHub MCP is not configured, show:
33
+
30
34
  ```
31
35
  GitHub MCP not configured!
32
36
  See: https://github.com/modelcontextprotocol/servers/tree/main/src/github
@@ -35,7 +39,7 @@ Trying GitHub CLI fallback...
35
39
 
36
40
  Then try using `gh issue view [ISSUE_NUMBER] --json` as fallback.
37
41
 
38
- 3. Analyze and Plan
42
+ 1. Analyze and Plan
39
43
 
40
44
  Summarize the issue and requirements, then:
41
45
 
@@ -44,32 +48,37 @@ Summarize the issue and requirements, then:
44
48
  Understand the requirement by asking (use AskUserQuestion if needed):
45
49
 
46
50
  **Problem Statement**
51
+
47
52
  - What problem does this solve?
48
53
  - Who experiences this problem?
49
54
  - What's the current pain point?
50
55
 
51
56
  **Desired Outcome**
57
+
52
58
  - What should happen after this is built?
53
59
  - How will users interact with it?
54
60
  - What does success look like?
55
61
 
56
62
  **Scope & Constraints**
63
+
57
64
  - What's in scope vs. out of scope?
58
65
  - Any technical constraints?
59
66
  - Dependencies on other systems/features?
60
67
 
61
68
  **Context Check**
69
+
62
70
  - Search codebase for related features/modules
63
71
  - Check for existing test files that might be relevant
64
72
 
65
73
  ### Beads Integration
66
74
 
67
75
  Use Beads MCP to:
76
+
68
77
  - Track work with `bd ready` to find next task
69
78
  - Create issues with `bd create "description"`
70
79
  - Track dependencies with `bd dep add`
71
80
 
72
- See https://github.com/steveyegge/beads for more information.
81
+ See <https://github.com/steveyegge/beads> for more information.
73
82
 
74
83
  ## TDD Fundamentals
75
84
 
@@ -11,10 +11,13 @@ Create structured implementation plan that bridges product thinking (PRD) with t
11
11
  ## General Guidelines
12
12
 
13
13
  ### Output Style
14
+
14
15
  - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
15
16
  - Write natural, descriptive code without meta-commentary about the development process
16
17
  - The code should speak for itself - TDD is the process, not the product
17
18
 
19
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
20
+
18
21
  ## Input
19
22
 
20
23
  $ARGUMENTS
@@ -25,6 +28,7 @@ $ARGUMENTS
25
28
  ## Input Processing
26
29
 
27
30
  The input can be one of:
31
+
28
32
  1. **GitHub Issue URL** (e.g., `https://github.com/owner/repo/issues/123`)
29
33
  2. **GitHub Issue Number** (e.g., `#123` or `123`)
30
34
  3. **Feature Description** (e.g., "Add user authentication")
@@ -35,12 +39,14 @@ The input can be one of:
35
39
  If input looks like a GitHub issue:
36
40
 
37
41
  **Step 1: Extract Issue Number**
42
+
38
43
  - From URL: extract owner/repo/number
39
44
  - From number: try to infer repo from git remote
40
45
  - From branch name: check patterns like `issue-123`, `123-feature`, `feature/123`
41
46
 
42
47
  **Step 2: Fetch Issue**
43
48
  Try GitHub MCP first:
49
+
44
50
  - If available: use `mcp__github__issue_read` to fetch issue details
45
51
  - If not available: show message and try `gh issue view <number>`
46
52
 
@@ -51,6 +57,7 @@ Trying GitHub CLI fallback...
51
57
  ```
52
58
 
53
59
  **Step 3: Use Issue as Discovery Input**
60
+
54
61
  - Title → Feature name
55
62
  - Description → Problem statement and context
56
63
  - Labels → Type/priority hints
@@ -58,6 +65,7 @@ Trying GitHub CLI fallback...
58
65
  - Linked issues → Dependencies
59
66
 
60
67
  Extract from GitHub issue:
68
+
61
69
  - Problem statement and context
62
70
  - Acceptance criteria (if present)
63
71
  - Technical notes (if present)
@@ -70,21 +78,25 @@ Extract from GitHub issue:
70
78
  Understand the requirement by asking (use AskUserQuestion if needed):
71
79
 
72
80
  **Problem Statement**
81
+
73
82
  - What problem does this solve?
74
83
  - Who experiences this problem?
75
84
  - What's the current pain point?
76
85
 
77
86
  **Desired Outcome**
87
+
78
88
  - What should happen after this is built?
79
89
  - How will users interact with it?
80
90
  - What does success look like?
81
91
 
82
92
  **Scope & Constraints**
93
+
83
94
  - What's in scope vs. out of scope?
84
95
  - Any technical constraints?
85
96
  - Dependencies on other systems/features?
86
97
 
87
98
  **Context Check**
99
+
88
100
  - Search codebase for related features/modules
89
101
  - Check for existing test files that might be relevant
90
102
 
@@ -104,27 +116,32 @@ bd create "Task title" \
104
116
  **Issue Structure Best Practices:**
105
117
 
106
118
  **Title**: Action-oriented, specific
119
+
107
120
  - ✅ "Add JWT token validation middleware"
108
121
  - ❌ "Authentication stuff"
109
122
 
110
123
  **Description**: Provide context
124
+
111
125
  - Why this task exists
112
126
  - How it fits into the larger feature
113
127
  - Links to related issues/docs
114
128
 
115
129
  **Design**: Technical approach
130
+
116
131
  - Key interfaces/types needed
117
132
  - Algorithm or approach
118
133
  - Libraries or patterns to use
119
134
  - Known gotchas or considerations
120
135
 
121
136
  **Acceptance Criteria**: Test-ready scenarios
137
+
122
138
  - Given-When-Then format
123
139
  - Concrete, verifiable conditions
124
140
  - Cover main case + edge cases
125
141
  - Map 1:1 to future tests
126
142
 
127
143
  **Dependencies**: Link related issues
144
+
128
145
  ```bash
129
146
  bd dep add ISSUE-123 ISSUE-456 --type blocks
130
147
  ```
@@ -132,6 +149,7 @@ bd dep add ISSUE-123 ISSUE-456 --type blocks
132
149
  ### Validation
133
150
 
134
151
  After creating issues, verify:
152
+
135
153
  - ✅ Each issue has clear acceptance criteria
136
154
  - ✅ Dependencies are mapped (use `bd dep add`)
137
155
  - ✅ Issues are ordered by implementation sequence
@@ -141,11 +159,13 @@ After creating issues, verify:
141
159
  ## Key Principles
142
160
 
143
161
  **From PRD World:**
162
+
144
163
  - Start with user problems, not solutions
145
164
  - Define success criteria upfront
146
165
  - Understand constraints and scope
147
166
 
148
167
  **From TDD World:**
168
+
149
169
  - Make acceptance criteria test-ready
150
170
  - Break work into small, testable pieces
151
171
  - Each task should map to test(s)
@@ -153,11 +173,12 @@ After creating issues, verify:
153
173
  ### Beads Integration
154
174
 
155
175
  Use Beads MCP to:
176
+
156
177
  - Track work with `bd ready` to find next task
157
178
  - Create issues with `bd create "description"`
158
179
  - Track dependencies with `bd dep add`
159
180
 
160
- See https://github.com/steveyegge/beads for more information.
181
+ See <https://github.com/steveyegge/beads> for more information.
161
182
 
162
183
  ## Integration with Other Commands
163
184
 
@@ -1,21 +1,28 @@
1
1
  ---
2
2
  allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
3
3
  description: Execute TDD Red Phase - write ONE failing test
4
+ argument-hint: [optional additional info]
4
5
  ---
5
6
 
6
7
  RED PHASE! Apply the below to the info given by user input here:
7
8
 
8
9
  $ARGUMENTS
9
10
 
10
- (If there was no info above, use info from the current context of conversation. If there was not enough info, ask for it.)
11
-
12
11
  ## General Guidelines
13
12
 
14
13
  ### Output Style
14
+
15
15
  - **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
16
16
  - Write natural, descriptive code without meta-commentary about the development process
17
17
  - The code should speak for itself - TDD is the process, not the product
18
18
 
19
+ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
20
+
21
+ (If there was no info above, fallback to:
22
+
23
+ 1. Context of the conversation, if there's an immediate thing
24
+ 2. `bd ready` to see what to work on next and start from there)
25
+
19
26
  ## TDD Fundamentals
20
27
 
21
28
  ### The TDD Cycle