panopticon-cli 0.4.6 → 0.4.7

package/skills/beads-completion-check/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: beads-completion-check
+description: >
+  Verify all beads (tasks) in a workspace are closed before review completion.
+  Use as final check in code review workflow. Returns PASS if no open beads,
+  BLOCKED if open beads found. Triggers on "check beads", "verify tasks complete",
+  "beads status", or as subagent in review workflow.
+tools: Bash(bd:*), Read
+model: haiku
+---
+
+# Beads Completion Check
+
+Verify all beads (tracked tasks) in a workspace are closed before declaring work complete.
+
+## Purpose
+
+Agents often create beads to track sub-tasks during implementation. These must all be closed before the work can be considered complete. This check prevents:
+- Incomplete work being merged
+- Forgotten sub-tasks
+- Lost context about remaining work
+
+## When to Use
+
+- **Review workflow**: Final check before approving PR
+- **Work completion**: Before invoking `/work-complete`
+- **Handoff**: Before passing to test-agent or merge-agent
+
+## Execution
+
+Run this check in the workspace being reviewed:
+
+```bash
+# Check for open beads
+bd list --status open --json
+```
+
+## Result Interpretation
+
+### PASS - No Open Beads
+```
+BEADS CHECK: PASS
+No open beads found in workspace.
+Work tracking is complete.
+```
+
+### BLOCKED - Open Beads Found
+```
+BEADS CHECK: BLOCKED
+
+Found N open bead(s) that must be resolved:
+
+| ID | Title | Priority | Status |
+|----|-------|----------|--------|
+| pan-123 | Implement feature X | P2 | open |
+| pan-124 | Add tests for Y | P3 | in_progress |
+
+ACTION REQUIRED:
+1. Close completed beads: bd close <id> --reason "Completed"
+2. Or document why they should remain open
+3. Re-run review after resolution
+```
+
+## Integration with Review Agent
+
+The review-agent should invoke this as a final check:
+
+```
+Task(subagent_type='beads-completion-check', prompt='Check if all beads are closed in workspace: /path/to/workspace')
+```
+
+If this check fails, the review should be BLOCKED until beads are resolved.
+
+## Output Format
+
+Return a structured result:
+
+```json
+{
+  "status": "PASS" | "BLOCKED",
+  "openBeads": [],
+  "message": "Human-readable summary"
+}
+```
+
+## Error Handling
+
+- If `bd` command not found: WARN but don't fail (beads may not be used)
+- If `.beads/` directory doesn't exist: PASS (no beads tracking in this workspace)
+- If bd returns error: Report error, don't fail review

package/skills/beads-panopticon-guide/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: beads-panopticon-guide
+description: >
+  Panopticon-specific beads usage patterns. Covers common mistakes agents make
+  when filtering beads by issue number (PAN-XXX) and working with Linear-synced beads.
+version: "1.0.0"
+allowed-tools: "Read,Bash(bd:*)"
+triggers:
+  - "bd list"
+  - "find beads"
+  - "filter by issue"
+  - "PAN-"
+  - "panopticon-"
+---
+
+# Beads Quick Reference for Panopticon Agents
+
+**Context:** Panopticon uses beads to track tasks for Linear issues (PAN-XXX). Each Linear issue spawns multiple bead tasks with IDs like `panopticon-abc`.
+
+## ⚠️ Common Mistakes
+
+### ❌ WRONG: Using `--issue` flag
+```bash
+bd list --issue PAN-116
+# Error: unknown flag: --issue
+```
+
+### ✅ CORRECT: Filter by title or label
+```bash
+# Option 1: Search in title (most common)
+bd list --title-contains "PAN-116" --all
+
+# Option 2: Filter by label (if issues are labeled)
+bd list --label PAN-116
+
+# Option 3: Search full text
+bd search "PAN-116"
+```
+
+## Finding Beads for a Panopticon Issue
+
+**Pattern:** Linear issue `PAN-XXX` → Multiple beads `panopticon-{random}`
+
+```bash
+# Find ALL beads for PAN-116 (including closed)
+bd list --title-contains "PAN-116" --all
+
+# Find OPEN beads for PAN-116
+bd list --title-contains "PAN-116" --status open
+
+# Get details about a specific bead
+bd show panopticon-abc
+
+# Find unblocked work for PAN-116
+bd ready | grep -i "PAN-116"
+```
+
+## Common Filters
+
+```bash
+# By status
+bd list --status open
+bd list --status in_progress
+bd list --status closed
+
+# By priority
+bd list --priority 1              # P1 only
+bd list --priority-min 0 --priority-max 1  # P0-P1
+
+# By assignee
+bd list --assignee "Claude"
+bd list --no-assignee             # Unassigned
+
+# Multiple filters
+bd list --title-contains "PAN-116" --status open --priority 1
+```
+
+## Working With Beads
+
+```bash
+# Start work on a bead
+bd update panopticon-abc --status in_progress
+
+# Add progress notes (CRITICAL for crash recovery)
+bd comments add panopticon-abc "Implemented parseClaudeSession refactor"
+
+# Complete a bead
+bd close panopticon-abc --reason "Per-message costing implemented"
+
+# Check dependencies
+bd dep tree panopticon-abc
+```
+
+## Bead ID vs Issue ID
+
+| Type | Example | Where Used |
+|------|---------|------------|
+| **Linear Issue ID** | `PAN-116` | GitHub issues, titles, labels |
+| **Bead ID** | `panopticon-abc` | bd commands (`bd show`, `bd update`) |
+
+**Key insight:** `bd list --id` expects bead IDs, not Linear IDs.
+
+```bash
+# ❌ WRONG
+bd list --id PAN-116
+
+# ✅ CORRECT
+bd list --id panopticon-abc,panopticon-xyz
+```
+
+## Quick Cheat Sheet
+
+| Task | Command |
+|------|---------|
+| Find beads for issue | `bd list --title-contains "PAN-XXX" --all` |
+| Find open work | `bd ready` or `bd list --status open` |
+| Start a bead | `bd update <bead-id> --status in_progress` |
+| Add notes | `bd comments add <bead-id> "notes"` |
+| Complete bead | `bd close <bead-id> --reason "done"` |
+| Show bead details | `bd show <bead-id>` |
+
+## When to Use Each Filter
+
+| Use Case | Filter Flag | Example |
+|----------|-------------|---------|
+| Search by Linear issue number | `--title-contains` | `--title-contains "PAN-116"` |
+| Filter by specific bead IDs | `--id` | `--id panopticon-abc,panopticon-xyz` |
+| Filter by label | `--label` | `--label PAN-116` (if labeled) |
+| Full text search | Use `bd search` | `bd search "PAN-116"` |
+
+## Resource Files
+
+For complete beads documentation, see the main `beads` skill:
+- `/beads/SKILL.md` - Core beads reference
+- `/beads/resources/CLI_REFERENCE.md` - Complete command syntax
+- `/beads/resources/PATTERNS.md` - Common usage patterns
+
+## Remember
+
+1. **No `--issue` flag exists** - Use `--title-contains` instead
+2. **`--id` expects bead IDs** (panopticon-abc), not Linear IDs (PAN-116)
+3. **Always add comments** - They survive compaction and help the next agent
+4. **Sync at session end** - `bd sync` commits to git
+
+## Example: Complete Workflow for PAN-116
+
+```bash
+# 1. Find beads for this issue
+bd list --title-contains "PAN-116" --all
+
+# Output shows:
+#   panopticon-abc [open] - PAN-116: Refactor parseClaudeSession
+#   panopticon-xyz [open] - PAN-116: Add multi-model tests
+
+# 2. Pick first unblocked task
+bd show panopticon-abc
+
+# 3. Start work
+bd update panopticon-abc --status in_progress
+
+# 4. Do the work...
+
+# 5. Add progress notes
+bd comments add panopticon-abc "Implemented per-message costing logic"
+
+# 6. Complete
+bd close panopticon-abc --reason "Refactored parseClaudeSession to calculate cost per-message"
+
+# 7. Sync to git
+bd sync
+```

package/skills/bug-fix/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: bug-fix
+description: Systematic approach to investigating and fixing bugs
+---
+
+# Bug Fix
+
+When fixing a bug:
+
+## 1. Reproduce
+- Confirm the bug exists
+- Document exact reproduction steps
+- Identify affected code paths
+
+## 2. Investigate Root Cause
+- Use debugger or logging to trace execution
+- Don't just fix symptoms - find the ROOT CAUSE
+- Check for similar bugs elsewhere
+
+## 3. Implement Fix
+- Make minimal, focused changes
+- Don't refactor unrelated code
+- Commit: `fix: description (ISSUE-XXX)`
+
+## 4. Add Regression Test
+- Write a test that WOULD HAVE caught this bug
+- Test should fail without fix, pass with it
+
+## 5. Verify
+- Run full test suite
+- Manually verify the fix
+- Check for unintended side effects

package/skills/clear-writing/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: clear-writing
+description: >
+  Use when writing prose humans will read—documentation, commit messages,
+  error messages, explanations, reports, or UI text. Applies proven rules
+  for clearer, stronger, more professional writing and eliminates common
+  AI writing patterns.
+triggers:
+  - write documentation
+  - improve writing
+  - edit for clarity
+  - clear writing
+  - concise writing
+  - commit message
+  - PR description
+---
+
+# Clear Writing
+
+## Overview
+
+Write with clarity and force. This skill covers what to do (proven composition rules) and what not to do (AI writing patterns to avoid).
+
+## When to Use This Skill
+
+Use this skill whenever you write prose for humans:
+
+- Documentation, README files, technical explanations
+- Commit messages, pull request descriptions
+- Error messages, UI copy, help text, comments
+- Reports, summaries, or any explanation
+- Editing to improve clarity
+
+**If you are writing sentences for a human to read, use this skill.**
+
+## Limited Context Strategy
+
+When context is tight:
+
+1. Write your draft using judgment
+2. Dispatch a subagent with your draft and the relevant section file
+3. Have the subagent copyedit and return the revision
+
+Loading a single section (~1,000-4,500 tokens) instead of everything saves significant context.
+
+## Composition Rules
+
+These rules teach you to write clearly and cut ruthlessly.
+
+### Rules
+
+**Elementary Rules of Usage (Grammar/Punctuation)**:
+
+1. Form possessive singular by adding 's
+2. Use comma after each term in series except last
+3. Enclose parenthetic expressions between commas
+4. Comma before conjunction introducing co-ordinate clause
+5. Don't join independent clauses by comma
+6. Don't break sentences in two
+7. Participial phrase at beginning refers to grammatical subject
+
+**Elementary Principles of Composition**:
+
+8. One paragraph per topic
+9. Begin paragraph with topic sentence
+10. **Use active voice**
+11. **Put statements in positive form**
+12. **Use definite, specific, concrete language**
+13. **Omit needless words**
+14. Avoid succession of loose sentences
+15. Express co-ordinate ideas in similar form
+16. **Keep related words together**
+17. Keep to one tense in summaries
+18. **Place emphatic words at end of sentence**
+
+### Reference Files
+
+The rules above are summarized from the original text. For complete explanations with examples:
+
+| Section | File | ~Tokens |
+|---------|------|---------|
+| Grammar, punctuation, comma rules | `references/elements-of-style/02-elementary-rules-of-usage.md` | 2,500 |
+| Paragraph structure, active voice, concision | `references/elements-of-style/03-elementary-principles-of-composition.md` | 4,500 |
+| Headings, quotations, formatting | `references/elements-of-style/04-a-few-matters-of-form.md` | 1,000 |
+| Word choice, common errors | `references/elements-of-style/05-words-and-expressions-commonly-misused.md` | 4,000 |
+
+**Most tasks need only `03-elementary-principles-of-composition.md`** — it covers active voice, positive form, concrete language, and omitting needless words.
+
+## AI Writing Patterns to Avoid
+
+LLMs regress to statistical means, producing generic, puffy prose. Avoid:
+
+- **Puffery:** pivotal, crucial, vital, testament, enduring legacy
+- **Empty "-ing" phrases:** ensuring reliability, showcasing features, highlighting capabilities
+- **Promotional adjectives:** groundbreaking, seamless, robust, cutting-edge
+- **Overused AI vocabulary:** delve, leverage, multifaceted, foster, realm, tapestry
+- **Formatting overuse:** excessive bullets, emoji decorations, bold on every other word
+
+Be specific, not grandiose. Say what it actually does.
+
+For comprehensive research on why these patterns occur, see `references/signs-of-ai-writing.md`. This guide catalogs patterns observed across thousands of instances of AI-generated text — well-documented and field-tested.
+
+## Bottom Line
+
+Writing for humans? Load the relevant section from `references/elements-of-style/` and apply the rules. For most tasks, `03-elementary-principles-of-composition.md` covers what matters most.

package/skills/clear-writing/references/elements-of-style/01-introductory.md

@@ -0,0 +1,3 @@
+## I. Introductory
+
+This handbook summarizes the essentials of plain English style. It focuses on the rules of usage and principles of composition most often broken, offering a compact alternative to exhaustive manuals. Master the guidance here, then look to the best authors for finer points of style.

package/skills/clear-writing/references/elements-of-style/02-elementary-rules-of-usage.md

@@ -0,0 +1,214 @@
+## II. Elementary Rules Of Usage
+
+### Rule 1. Form the possessive singular of nouns by adding 's.
+
+Follow this rule whatever the final consonant. Thus write,
+
+Charles's friend
+
+Burns's poems
+
+the witch's malice
+
+This is the usage of the United States Government Printing Office and of the Oxford University Press.
+
+Exceptions are the possessive of ancient proper names ending in *-es* and *-is*, the possessive *Jesus'*, and such forms as *for conscience' sake*, *for righteousness' sake*. But such forms as *Achilles' heel*, *Moses' laws*, *Isis' temple* are commonly replaced by
+
+the heel of Achilles
+
+the laws of Moses
+
+the temple of Isis
+
+The pronominal possessives *hers*, *its*, *theirs*, *yours*, and *oneself* have no apostrophe.
+
+### Rule 2. In a series of three or more terms with a single conjunction, use a comma after each term except the last.
+
+Thus write,
+
+red, white, and blue
+
+gold, silver, or copper
+
+He opened the letter, read it, and made a note of its contents.
+
+This is also the usage of the Government Printing Office and of the Oxford University Press.
+
+In the names of business firms the last comma is omitted, as,
+
+Brown, Shipley & Co.
+
+### Rule 3. Enclose parenthetic expressions between commas.
+
+The best way to see a country, unless you are pressed for time, is to travel on foot.
+
+This rule is difficult to apply; it is frequently hard to decide whether a single word, such as *however*, or a brief phrase, is or is not parenthetic. If the interruption to the flow of the sentence is but slight, the writer may safely omit the commas. But whether the interruption be slight or considerable, he must never insert one comma and omit the other. Such punctuation as
+
+Marjorie's husband, Colonel Nelson paid us a visit yesterday,
+
+or
+
+My brother you will be pleased to hear, is now in perfect health,
+
+is indefensible.
+
+If a parenthetic expression is preceded by a conjunction, place the first comma before the conjunction, not after it.
+
+He saw us coming, and unaware that we had learned of his treachery, greeted us with a smile.
+
+Always to be regarded as parenthetic and to be enclosed between commas (or, at the end of the sentence, between comma and period) are the following:
+
+\(1\) the year, when forming part of a date, and the day of the month, when following the day of the week:
+
+February to July, 1916.
+
+April 6, 1917.
+
+Monday, November 11, 1918.
+
+\(2\) the abbreviations *etc.* and *jr.*
+
+\(3\) non-restrictive relative clauses, that is, those which do not serve to identify or define the antecedent noun, and similar clauses introduced by conjunctions indicating time or place.
+
+The audience, which had at first been indifferent, became more and more interested.
+
+In this sentence the clause introduced by *which* does not serve to tell which of several possible audiences is meant; what audience is in question is supposed to be already known. The clause adds, parenthetically, a statement supplementing that in the main clause. The sentence is virtually a combination of two statements which might have been made independently:
+
+The audience had at first been indifferent. It became more and more interested.
+
+Compare the restrictive relative clause, not set off by commas, in the sentence,
+
+The candidate who best meets these requirements will obtain the place.
+
+Here the clause introduced by *who* does serve to tell which of several possible candidates is meant; the sentence cannot be split up into two independent statements.
+
+The difference in punctuation in the two sentences following is based on the same principle:
+
+Nether Stowey, where Coleridge wrote The Rime of the Ancient Mariner, is a few miles from Bridgewater.
+
+The day will come when you will admit your mistake.
+
+Nether Stowey is completely identified by its name; the statement about Coleridge is therefore supplementary and parenthetic. The *day* spoken of is identified only by the dependent clause, which is therefore restrictive.
+
+Similar in principle to the enclosing of parenthetic expressions between commas is the setting off by commas of phrases or dependent clauses preceding or following the main clause of a sentence.
+
+Partly by hard fighting, partly by diplomatic skill, they enlarged their dominions to the east, and rose to royal rank with the possession of Sicily, exchanged afterwards for Sardinia.
+
+Other illustrations may be found in sentences quoted under Rules 4, 5, 6, 7, 16, and 18.
+
+The writer should be careful not to set off independent clauses by commas: see under Rule 5.
+
+### Rule 4. Place a comma before a conjunction introducing a co-ordinate clause.
+
+The early records of the city have disappeared, and the story of its first years can no longer be reconstructed.
+
+The situation is perilous, but there is still one chance of escape.
+
+Sentences of this type, isolated from their context, may seem to be in need of rewriting. As they make complete sense when the comma is reached, the second clause has the appearance of an afterthought. Further, *and* is the least specific of connectives. Used between independent clauses, it indicates only that a relation exists between them without defining that relation. In the example above, the relation is that of cause and result. The two sentences might be rewritten:
+
+As the early records of the city have disappeared, the story of its first years can no longer be reconstructed.
+
+Although the situation is perilous, there is still one chance of escape.
+
+Or the subordinate clauses might be replaced by phrases:
+
+Owing to the disappearance of the early records of the city, the story of its first years can no longer be reconstructed.
+
+In this perilous situation, there is still one chance of escape.
+
+But a writer may err by making his sentences too uniformly compact and periodic, and an occasional loose sentence prevents the style from becoming too formal and gives the reader a certain relief. Consequently, loose sentences of the type first quoted are common in easy, unstudied writing. But a writer should be careful not to construct too many of his sentences after this pattern (see Rule 14).
+
+Two-part sentences of which the second member is introduced by *as* (in the sense of *because*), *for*, *or*, *nor*, and *while* (in the sense of *and at the same time*) likewise require a comma before the conjunction.
+
+If the second member is introduced by an adverb, a semicolon, not a comma, is required (see Rule 5). The connectives *so* and *yet* may be used either as adverbs or as conjunctions, accordingly as the second clause is felt to be co-ordinate or subordinate; consequently either mark of punctuation may be justified. But these uses of *so* (equivalent to *accordingly* or to *so that*) are somewhat colloquial and should, as a rule, be avoided in writing. A simple correction, usually serviceable, is to omit the word *so* and begin the first clause with *as* or *since*:
+
+| Original | Revision |
+| --- | --- |
+| I had never been in the place before; so I had difficulty in finding my way about. | As I had never been in the place before, I had difficulty in finding my way about. |
+
+If a dependent clause, or an introductory phrase requiring to be set off by a comma, precedes the second independent clause, no comma is needed after the conjunction.
+
+The situation is perilous, but if we are prepared to act promptly, there is still one chance of escape.
+
+When the subject is the same for both clauses and is expressed only once, a comma is required if the connective is *but*. If the connective is *and*, the comma should be omitted if the relation between the two statements is close or immediate.
+
+I have heard his arguments, but am still unconvinced.
+
+He has had several years' experience and is thoroughly competent.
+
+### Rule 5. Do not join independent clauses by a comma.
+
+If two or more clauses, grammatically complete and not joined by a conjunction, are to form a single compound sentence, the proper mark of punctuation is a semicolon.
+
+Stevenson's romances are entertaining; they are full of exciting adventures.
+
+It is nearly half past five; we cannot reach town before dark.
+
+It is of course equally correct to write the above as two sentences each, replacing the semicolons by periods.
+
+Stevenson's romances are entertaining. They are full of exciting adventures.
+
+It is nearly half past five. We cannot reach town before dark.
+
+If a conjunction is inserted the proper mark is a comma (Rule 4).
+
+Stevenson's romances are entertaining, for they are full of exciting adventures.
+
+It is nearly half past five, and we cannot reach town before dark.
+
+A comparison of the three forms given above will show clearly the advantage of the first. It is, at least in the examples given, better than the second form, because it suggests the close relationship between the two statements in a way that the second does not attempt, and better than the third, because briefer and therefore more forcible. Indeed it may be said that this simple method of indicating relationship between statements is one of the most useful devices of composition. The relationship, as above, is commonly one of cause or of consequence.
+
+Note that if the second clause is preceded by an adverb, such as *accordingly*, *besides*, *then*, *therefore*, or *thus*, and not by a conjunction, the semicolon is still required.
+
+Two exceptions to the rule may be admitted. If the clauses are very short, and are alike in form, a comma is usually permissible:
+
+Man proposes, God disposes.
+
+The gate swung apart, the bridge fell, the portcullis was drawn up.
+
+Note that in these examples the relation is not one of cause or consequence. Also in the colloquial form of expression,
+
+I hardly knew him, he was so changed,
+
+a comma, not a semicolon, is required. But this form of expression is inappropriate in writing, except in the dialogue of a story or play, or perhaps in a familiar letter.
+
+### Rule 6. Do not break sentences in two.
+
+In other words, do not use periods for commas.
+
+I met them on a Cunard liner several years ago. Coming home from Liverpool to New York.
+
+He was an interesting talker. A man who had traveled all over the world and lived in half a dozen countries.
+
+In both these examples, the first period should be replaced by a comma, and the following word begun with a small letter.
+
+It is permissible to make an emphatic word or expression serve the purpose of a sentence and to punctuate it accordingly:
+
+Again and again he called out. No reply.
+
+The writer must, however, be certain that the emphasis is warranted, and that he will not be suspected of a mere blunder in syntax or in punctuation.
+
+Rules 3, 4, 5, and 6 cover the most important principles in the punctuation of ordinary sentences; they should be so thoroughly mastered that their application becomes second nature.
+
+### Rule 7. A participial phrase at the beginning of a sentence must refer to the grammatical subject.
+
+Walking slowly down the road, he saw a woman accompanied by two children.
+
+The word *walking* refers to the subject of the sentence, not to the woman. If the writer wishes to make it refer to the woman, he must recast the sentence:
+
+He saw a woman accompanied by two children, walking slowly down the road.
+
+Participial phrases preceded by a conjunction or by a preposition, nouns in apposition, adjectives, and adjective phrases come under the same rule if they begin the sentence.
+
+| Original | Revision |
+| --- | --- |
+| On arriving in Chicago, his friends met him at the station. | When he arrived (or, On his arrival) in Chicago, his friends met him at the station. |
+| A soldier of proved valor, they entrusted him with the defence of the city. | A soldier of proved valor, he was entrusted with the defence of the city. |
+| Young and inexperienced, the task seemed easy to me. | Young and inexperienced, I thought the task easy. |
+| Without a friend to counsel him, the temptation proved irresistible. | Without a friend to counsel him, he found the temptation irresistible. |
+
+Sentences violating this rule are often ludicrous.
+
+Being in a dilapidated condition, I was able to buy the house very cheap.
+
+Wondering irresolutely what to do next, the clock struck twelve.