@sienklogic/plan-build-run 2.56.2 → 2.56.3

package/plugins/cursor-pbr/skills/undo/SKILL.md

@@ -64,9 +64,9 @@ Present grouped output:
 ```
 Recent PBR commits (grouped by scope):
 
-[55-02] Phase 55, Plan 02
-  abc1234  feat(55-02): add undo skill
-  def5678  chore(55-02): register undo command
+[undo]
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
 
 [quick-003]
   ghi9012  fix(quick-003): fix hook path resolution
@@ -75,7 +75,7 @@ Recent PBR commits (grouped by scope):
   jkl3456  docs(planning): update roadmap phase 55
 ```
 
-For phase-plan scopes (NN-MM pattern), add a "Phase NN, Plan MM" annotation. For other scopes, show just the scope label.
+For descriptive scopes, show just the scope label. For phase-plan scopes (NN-MM pattern, from older commits), add a "Phase NN, Plan MM" annotation.
 
 ---
 
@@ -103,8 +103,8 @@ Display the commits that will be reverted:
 ```
 The following commits will be reverted (using git revert, NOT git reset):
 
-  abc1234  feat(55-02): add undo skill
-  def5678  chore(55-02): register undo command
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
 
 This creates new revert commits — your history is preserved.
 ```
@@ -126,7 +126,7 @@ git revert --no-commit {hash}
 ```
 
 After all reverts are staged, determine the commit message:
-- Extract scope from the first commit being reverted (e.g., `55-02`)
+- Extract scope from the first commit being reverted (e.g., `undo`, `auth`, `executor`)
 - If reverting a **single commit**: `revert({scope}): undo {original description}`
 - If reverting **multiple commits**: `revert({scope}): undo {N} commits from {scope}`
 

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.56.2",
+  "version": "2.56.3",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/agents/executor.md

@@ -109,7 +109,7 @@ One task = one commit. Exception: TDD tasks get 3 commits (RED, GREEN, REFACTOR)
 ### Commit Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 | Type | When |
@@ -128,7 +128,7 @@ Stage only files listed in the task's `<files>`. If git commit fails with lock e
 When the plan frontmatter contains a non-empty `closes_issues` array, append issue-closing syntax to the **final** commit body for the plan:
 
 ```
-git commit -m "feat(01-02): implement user auth
+git commit -m "feat(auth): implement user auth
 
 Closes #42
 Closes #57"
@@ -226,9 +226,9 @@ When a task has `tdd="true"`, follow Red-Green-Refactor:
 
 | Phase | Action | Test Must | Commit | If Wrong |
 |-------|--------|-----------|--------|----------|
-| RED | Write test from `<done>` | FAIL | `test(NN-MM): RED - ...` | Passes? Fix test. |
-| GREEN | Minimal code to pass | PASS | `feat(NN-MM): GREEN - ...` | Fails? Fix code. |
-| REFACTOR | Clean up, keep behavior | PASS | `refactor(NN-MM): REFACTOR - ...` | Breaks? Revert. |
+| RED | Write test from `<done>` | FAIL | `test({scope}): RED - ...` | Passes? Fix test. |
+| GREEN | Minimal code to pass | PASS | `refactor({scope}): GREEN - ...` | Fails? Fix code. |
+| REFACTOR | Clean up, keep behavior | PASS | `refactor({scope}): REFACTOR - ...` | Breaks? Revert. |
 
 ---
 

package/plugins/pbr/agents/general.md

@@ -59,7 +59,7 @@ This agent is available for ad-hoc `Task()` calls from skills or custom orchestr
 
 All commits follow: `{type}({scope}): {description}`
 - **Types**: feat, fix, refactor, test, docs, chore, wip
-- **Scopes**: `{phase}-{plan}` (e.g., `03-01`), `quick-{NNN}`, `planning`
+- **Scopes**: descriptive word (e.g., `auth`, `api`, `executor`), `quick-{NNN}`, `planning`
 
 ## Self-Escalation
 

package/plugins/pbr/references/archive/pbr-rules.md

@@ -105,7 +105,7 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 
 56. Format: `{type}({scope}): {description}`.
 57. Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`.
-58. Valid scopes: `{NN}-{MM}` (phase-plan), `quick-{NNN}`, `planning`, or any lowercase word.
+58. Valid scopes: a short descriptive word for what changed (e.g., `auth`, `executor`, `config`), `quick-{NNN}`, `planning`, or `{NN}-{MM}` (phase-plan, legacy).
 59. **Never** use `git add .` or `git add -A` — stage specific files only.
 60. Blocked files: `.env` (not `.env.example`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*credential*`, `*secret*` (unless in `tests/` or `*.example`).
 61. TDD tasks: exactly 3 commits — RED (test), GREEN (feat), REFACTOR.

package/plugins/pbr/references/config-reference.md

@@ -151,7 +151,7 @@ Controls git integration and branching strategy.
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `branching` | string | `none` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
-| `commit_format` | string | `{type}({phase}-{plan}): {description}` | Commit message template |
+| `commit_format` | string | `{type}({scope}): {description}` | Commit message template. Use a short descriptive word as the scope (e.g., `auth`, `config`, `executor`) rather than phase-plan numbers. |
 | `phase_branch_template` | string | `plan-build-run/phase-{phase}-{slug}` | Phase branch name pattern |
 | `milestone_branch_template` | string | `plan-build-run/{milestone}-{slug}` | Milestone branch name pattern |
 | `mode` | string | `enabled` | Git mode: `enabled` or `disabled` |

package/plugins/pbr/references/git-integration.md

@@ -7,23 +7,22 @@ Plan-Build-Run's commit conventions, commit points, branching strategy, and hook
 ## Commit Message Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 ### Components
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `{type}` | Conventional commit type | `feat`, `fix`, `test` |
-| `{phase}` | Phase number (zero-padded) | `02` |
-| `{plan}` | Plan number | `01` |
-| `{description}` | Imperative, lowercase description | `implement discord oauth client` |
+| `{type}` | Conventional commit type | `feat`, `fix`, `chore` |
+| `{scope}` | Descriptive word for the area of change | `auth`, `executor`, `changelog` |
+| `{description}` | Imperative, lowercase description | `add discord oauth flow` |
 
-The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({phase}-{plan}): {description}`.
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({scope}): {description}`.
 
 ### Full Example
 ```
-feat(02-01): implement discord oauth client
+feat(auth): implement discord oauth client
 ```
 
 ---
@@ -32,19 +31,35 @@ feat(02-01): implement discord oauth client
 
 | Type | When to Use | Example |
 |------|------------|---------|
-| `feat` | New feature or functionality | `feat(02-01): implement discord oauth client` |
-| `fix` | Bug fix (including during execution) | `fix(02-01): handle null user profile from discord api` |
-| `refactor` | Code restructuring, no behavior change | `refactor(02-01): extract token validation into helper` |
-| `test` | Adding or modifying tests | `test(02-01): add failing tests for discord oauth flow` |
-| `docs` | Documentation changes | `docs(03-02): add api endpoint documentation` |
-| `chore` | Build config, dependencies, tooling | `chore(01-01): configure typescript and eslint` |
-| `style` | Formatting, whitespace (no logic change) | `style(02-01): fix import ordering` |
+| `feat` | New feature or functionality | `feat(auth): implement discord oauth client` |
+| `fix` | Bug fix (including during execution) | `fix(api): handle null user profile from discord` |
+| `refactor` | Code restructuring, no behavior change | `refactor(auth): extract token validation into helper` |
+| `test` | Adding or modifying tests | `test(auth): add failing tests for oauth flow` |
+| `docs` | Documentation changes | `docs(planning): add api endpoint documentation` |
+| `chore` | Build config, dependencies, tooling | `chore(deps): configure typescript and eslint` |
+| `style` | Formatting, whitespace (no logic change) | `style(auth): fix import ordering` |
+
+---
+
+## Commit Type Discipline
+
+| Type | Use For | Appears in Changelog |
+|------|---------|---------------------|
+| `feat` | User-visible features ONLY (new commands, new config options, changed behavior users notice) | YES |
+| `fix` | Bug fixes users would notice | YES |
+| `refactor` | Internal restructuring, TDD GREEN commits, code cleanup | No |
+| `test` | Test additions including TDD RED commits | No |
+| `docs` | Documentation (hidden — mostly planning artifacts) | No |
+| `chore` | Build config, deps, tooling, internal scaffolding | No |
+| `wip` | Work in progress (use sparingly) | No |
+
+**TDD commits**: RED phase → `test({scope}): RED - ...`, GREEN phase → `refactor({scope}): GREEN - ...`, REFACTOR phase → `refactor({scope}): REFACTOR - ...`
 
 ---
 
 ## Special Commit Scopes
 
-Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these additional patterns:
+Beyond descriptive scopes, Plan-Build-Run recognizes these additional patterns:
 
 | Pattern | When Used | Example |
 |---------|-----------|---------|
@@ -84,9 +99,9 @@ Each successfully completed plan task gets exactly one atomic commit. No more, n
 TDD tasks (`tdd="true"`) produce exactly 3 commits following Red-Green-Refactor:
 
 ```
-test(02-01): RED - add failing tests for auth middleware
-feat(02-01): GREEN - implement auth middleware to pass tests
-refactor(02-01): REFACTOR - extract token verification helper
+test(auth): RED - add failing tests for auth middleware
+refactor(auth): GREEN - implement auth middleware to pass tests
+refactor(auth): REFACTOR - extract token verification helper
 ```
 
 ### Commit Preconditions
@@ -125,15 +140,15 @@ When an executor applies a deviation rule during a task, the deviation is includ
 ```bash
 # Standard task
 git add src/auth/discord.ts src/auth/types.ts
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # Task that also installed a dependency (Rule 2)
 git add src/auth/discord.ts src/auth/types.ts package.json package-lock.json
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # TDD RED
 git add tests/auth/discord.test.ts
-git commit -m "test(02-01): add failing tests for Discord OAuth flow"
+git commit -m "test(auth): add failing tests for Discord OAuth flow"
 ```
 
 ---

package/plugins/pbr/skills/begin/templates/config.json.tmpl

@@ -44,7 +44,7 @@
   },
   "git": {
     "branching": "none",
-    "commit_format": "{type}({phase}-{plan}): {description}",
+    "commit_format": "{type}({scope}): {description}",
     "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
     "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
     "mode": "enabled"

package/plugins/pbr/skills/undo/SKILL.md

@@ -65,9 +65,9 @@ Present grouped output:
 ```
 Recent PBR commits (grouped by scope):
 
-[55-02] Phase 55, Plan 02
-  abc1234  feat(55-02): add undo skill
-  def5678  chore(55-02): register undo command
+[undo]
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
 
 [quick-003]
   ghi9012  fix(quick-003): fix hook path resolution
@@ -76,7 +76,7 @@ Recent PBR commits (grouped by scope):
   jkl3456  docs(planning): update roadmap phase 55
 ```
 
-For phase-plan scopes (NN-MM pattern), add a "Phase NN, Plan MM" annotation. For other scopes, show just the scope label.
+For descriptive scopes, show just the scope label. For phase-plan scopes (NN-MM pattern, from older commits), add a "Phase NN, Plan MM" annotation.
 
 ---
 
@@ -104,8 +104,8 @@ Display the commits that will be reverted:
 ```
 The following commits will be reverted (using git revert, NOT git reset):
 
-  abc1234  feat(55-02): add undo skill
-  def5678  chore(55-02): register undo command
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
 
 This creates new revert commits — your history is preserved.
 ```
@@ -127,7 +127,7 @@ git revert --no-commit {hash}
 ```
 
 After all reverts are staged, determine the commit message:
-- Extract scope from the first commit being reverted (e.g., `55-02`)
+- Extract scope from the first commit being reverted (e.g., `undo`, `auth`, `executor`)
 - If reverting a **single commit**: `revert({scope}): undo {original description}`
 - If reverting **multiple commits**: `revert({scope}): undo {N} commits from {scope}`