plumb-dev 0.2.0__tar.gz

plumb_dev-0.2.0/.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true
+  }
+}

plumb_dev-0.2.0/.claude/skills/plumb/SKILL.md

@@ -0,0 +1,130 @@
+# Plumb Skill
+
+Plumb keeps the spec, tests, and code in sync. It intercepts every `git commit`
+via a pre-commit hook, analyzes staged changes and conversation history, and
+surfaces decisions for review before the commit lands.
+
+## Your responsibilities when Plumb is active
+
+### Before starting work
+Run `plumb status` to understand the current state of spec/test/code alignment.
+Note any pending decisions and any broken git references. Report a brief summary
+to the user before proceeding.
+
+### Before committing
+Run `plumb diff` to preview what Plumb will capture from staged changes. Report
+the estimated decisions to the user so they are not surprised during review.
+
+### When git commit is intercepted
+When you run `git commit` and it exits non-zero with Plumb output, do the
+following:
+
+1. Parse the JSON from stdout. It will have this shape:
+   ```json
+   {
+     "pending_decisions": 2,
+     "decisions": [
+       {
+         "id": "dec-abc123",
+         "question": "...",
+         "decision": "...",
+         "made_by": "llm",
+         "confidence": 0.87
+       }
+     ]
+   }
+   ```
+
+2. **You MUST use `AskUserQuestion` to present decisions.** Do NOT print decision
+   details as plain text and ask the user to respond. You MUST use the
+   `AskUserQuestion` tool so the user sees the native multiple-choice UI.
+   Present each decision with these options:
+   - **Approve** (Recommended) — accept it and update the spec
+   - **Approve with edits** — modify what the decision says before approving
+   - **Ignore** — not spec-relevant; discard permanently
+   - **Reject** — undo this change in the staged code
+
+   Include the decision details in the question text:
+   ```
+   Plumb found [N] decision(s). Decision [X of N]:
+   Question: [question]
+   Decision: [decision]
+   Made by: [made_by] (confidence: [confidence])
+   ```
+
+   This is non-negotiable. Presenting decisions as plain text defeats the
+   purpose of structured review. Always use `AskUserQuestion`.
+
+3. Based on the user's selection, call the appropriate command:
+   - Approve: `plumb approve <id>`
+   - Approve with edits: `plumb edit <id> "<new decision text from user>"`
+   - Ignore: `plumb ignore <id>`
+   - Reject: `plumb reject <id> --reason "..."`
+     (modify runs automatically — no separate call needed)
+
+   If the user approved ALL decisions with no edits, use `plumb approve --all`
+   instead of approving each one individually.
+
+4. **After all decisions are resolved, run `plumb sync`.** This updates the spec
+   files and generates tests for approved decisions. You MUST run sync
+   before re-committing — approved decisions that are not synced will leave the
+   spec out of date.
+
+5. Stage any files changed by sync (spec files, generated tests), then re-run
+   `git commit`. Draft the commit message **after** decision review is complete
+   and include a summary of approved decisions (e.g. "Approved: dec-abc123
+   (added caching), dec-def456 (fixed retry logic)"). The hook will fire again.
+   If there are no pending decisions it will exit 0 and the commit will land.
+   If new decisions are found (rare), repeat the review process.
+
+### After committing
+Run `plumb coverage` and briefly report the three coverage dimensions to the
+user: code coverage, spec-to-test coverage, and spec-to-code coverage. Flag any
+gaps that should be addressed before the next commit.
+
+### Using coverage to guide work
+When the user asks what to work on next, run `plumb coverage` to identify:
+- Requirements with no corresponding tests (run `plumb parse-spec` first if the
+  spec has changed)
+- Requirements with no corresponding implementation
+- Code with no test coverage
+
+Present these gaps clearly so the user can prioritize.
+
+## Rules
+
+- **NEVER approve, reject, or edit decisions without explicit user instruction.**
+  Every decision must be presented to the user via `AskUserQuestion`, and the user
+  must tell you how to handle each one. Do not batch-approve, auto-approve, or
+  assume the user's intent. This is the core purpose of Plumb — human review of
+  decisions.
+- **ALWAYS use `AskUserQuestion` to present decisions. NEVER print them as plain
+  text.** The native multiple-choice UI is the only acceptable way to present
+  decisions. If you present decisions as plain text you are doing it wrong.
+- Never edit `.plumb/decisions.jsonl` directly.
+- Never edit `.plumb/config.json` directly. Use `plumb init` or `plumb status`.
+- Never install the Plumb skill globally (`~/.claude/`). It is project-local only.
+- The spec markdown files are the source of truth for intended behavior. Plumb
+  keeps them updated as decisions are approved. Do not edit spec files to resolve
+  decisions — let Plumb do it via `plumb sync`.
+- Do not attempt to commit if there are decisions with `status: rejected_manual`.
+  The user must resolve these manually first.
+
+## Command reference
+
+| Command | When to use |
+|---|---|
+| `plumb status` | Start of session, before beginning work |
+| `plumb diff` | Before committing, to preview decisions |
+| `plumb hook` | Called automatically by pre-commit hook |
+| `plumb check` | Manually scan staged changes for decisions (alias for hook) |
+| `plumb approve <id>` | User approves a decision during review |
+| `plumb approve --all` | User approves all pending decisions at once |
+| `plumb reject <id> --reason "<text>"` | User rejects a decision (auto-modifies code) |
+| `plumb ignore <id>` | User marks a decision as not spec-relevant |
+| `plumb modify <id>` | Called automatically by reject — do not call directly |
+| `plumb edit <id> "<text>"` | User amends decision text before approving |
+| `plumb review` | Interactive terminal review (not needed in Claude Code) |
+| `plumb sync` | **Run after approving decisions** — updates spec and generates tests |
+| `plumb coverage` | Report coverage across all three dimensions |
+| `plumb parse-spec` | Re-parse spec after manual edits |

plumb_dev-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.coverage
+.pytest_cache/
+.env