opencode-thrum-pro 0.1.0

package/assets/skills/project-philosophy/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: project-philosophy
+description: "Use when a project needs its implementation philosophy established or updated — the canonical doc at .thrum/philosophy.md defining anti-patterns, red flags, and project-specific rules that implementation agents read at task-start time. First invocation generates from project inspection; subsequent invocations reconcile against current project state and propose diffs."
+---
+
+# Project Philosophy
+
+## Canonical path
+
+`.thrum/philosophy.md` — the single authoritative location. `project-setup` and
+every implementation-agent prompt read from this path only. Non-standard paths
+are handled by the fallback migration (documented below), not by moving the
+canonical target.
+
+## Run modes and dispatch order
+
+On every invocation, dispatch in this order. Earlier branches short-circuit
+later ones.
+
+0. **Fallback migration** — runs first when `.thrum/philosophy.md` is absent. If
+   a legacy philosophy doc exists elsewhere in the repo, offer move/link/fresh
+   before generating anything new. If no legacy doc is found, fall through to
+   branch 1.
+1. **First-run** (doc absent, no legacy doc or "fresh" chosen above) — generate
+   a new `.thrum/philosophy.md` from project inspection + interactive prompts
+   (documented below).
+2. **Re-run-unchanged** (doc present, matches current project state) — report
+   "philosophy.md is current; no changes needed" and exit without writing.
+3. **Re-run-evolved** (doc present, project has drifted) — compute a sectional
+   diff, present via `AskUserQuestion`, write only on confirmation.
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_generator-idempotency-protocol.md`
+
+> **Note: human-in-the-loop required.** This skill uses `AskUserQuestion` for
+> first-run project-specific prompts, re-run-evolved diff approval, and
+> fallback-migration three-way choice. It cannot run unattended in CI or any
+> other non-interactive automation context. Invoke it only from a session that
+> can answer prompts.
+
+## Fallback migration
+
+Runs before the First-run branch when `.thrum/philosophy.md` is absent. If the
+user has a philosophy doc at a legacy path, offer a three-way choice rather than
+ignoring it and generating a parallel doc.
+
+### Step 1: Search for legacy philosophy docs
+
+```bash
+find . -type f \( -name "*philosophy*" -o -name "*anti-pattern*" -o -name "*implementation-standards*" -o -name "CONTRIBUTING.md" \) \
+  -not -path '*/node_modules/*' \
+  -not -path '*/.git/*' \
+  -not -path '*/dist/*' \
+  -not -path '*/build/*' \
+  2>/dev/null | head
+```
+
+Common legacy locations: `dev-docs/implementation-philosophy.md`,
+`docs/anti-patterns.md`, `CONTRIBUTING.md` with an anti-patterns section.
+
+If zero candidates: fall through to First-run. If one or more candidates:
+present the choice.
+
+### Step 2: Present three-way choice via `AskUserQuestion`
+
+Question: "Found existing philosophy doc at `<path>`. What should I do?"
+
+Options:
+
+- **Move** — `git mv <path> .thrum/philosophy.md`. Preserves history via rename;
+  the file moves to the canonical location and the legacy path stops existing.
+- **Link** — Create `.thrum/philosophy.md` with a single line: `See: <path>`.
+  The legacy doc stays in place; the canonical path becomes a pointer. Useful
+  when the legacy path is load-bearing (e.g., referenced from a
+  `CONTRIBUTING.md` that can't be retargeted cheaply).
+- **Fresh** — Ignore the legacy doc; generate a new `.thrum/philosophy.md` via
+  the First-run flow. The legacy doc stays unmodified. Useful when the legacy
+  doc is stale or incomplete.
+
+If multiple candidates were found, ask which one first (separate
+`AskUserQuestion`) before offering move/link/fresh.
+
+### Step 3: Execute the chosen option
+
+**Move path:**
+
+```bash
+mkdir -p .thrum/
+git mv <legacy-path> .thrum/philosophy.md
+```
+
+`git mv` requires the repo to be initialized with at least one commit on the
+current branch. If the repo has no commits (fresh `git init`), fall back to a
+plain `mv` + `git add`, and note in the final message that rename history is not
+preserved.
+
+**Link path:**
+
+```bash
+mkdir -p .thrum/
+printf 'See: %s\n' "<legacy-path>" > .thrum/philosophy.md
+```
+
+**Fresh path:** Drop into First-run mode without touching the legacy file.
+
+### Step 4: Announce and continue
+
+Tell the user what was done and where the canonical doc now lives. If `move` or
+`link` was chosen, exit (the doc is materialized — no further generation
+needed). If `fresh` was chosen, continue into First-run Step 1.
+
+## First-run mode
+
+Triggered when `.thrum/philosophy.md` does not exist AND no non-standard
+philosophy doc is found (or the fallback migration is skipped via the "fresh"
+option).
+
+### Step 1: Detect language
+
+Inspect the repo root for manifest files and pick the primary language:
+
+| File present                                         | Language                |
+| ---------------------------------------------------- | ----------------------- |
+| `go.mod`                                             | Go                      |
+| `package.json`                                       | JavaScript / TypeScript |
+| `Cargo.toml`                                         | Rust                    |
+| `pyproject.toml` or `setup.py` or `requirements.txt` | Python                  |
+| `pom.xml` or `build.gradle*`                         | Java / Kotlin           |
+| `Gemfile`                                            | Ruby                    |
+| `mix.exs`                                            | Elixir                  |
+
+If multiple are present, record the repo as polyglot and pick the most prominent
+by file count.
+
+### Step 2: Detect framework
+
+Grep the detected language's manifest for well-known framework markers:
+
+- Go: `cmd/` layout + `net/http` or `gin-gonic` or `chi` → web service; `cobra`
+  → CLI; pure library if neither
+- JS/TS: `next` in `package.json` → Next.js; `react` without Next → React SPA;
+  `express`/`fastify` → Node backend
+- Python: `fastapi`/`flask`/`django` in dependencies → web backend;
+  `pytorch`/`tensorflow` → ML
+- Rust: `tokio`/`actix-web`/`axum` → async service; bin-only → CLI
+
+### Step 3: Detect test harness
+
+Check for test files and harness config:
+
+- Go: `*_test.go` files; `testing` package import → stdlib; `testify` →
+  assertions; `ginkgo` → BDD
+- JS/TS: `__tests__/` or `*.test.ts`; `jest.config.*`, `vitest.config.*`,
+  `playwright.config.*`
+- Python: `tests/` dir; `pytest.ini`, `conftest.py`
+- Rust: `#[cfg(test)]` blocks; `cargo test` always available
+
+Record the harness in the rendered template so implementation-agent prompts know
+how to run tests.
+
+### Step 4: Detect pattern conventions visible in existing code
+
+Sample the codebase for:
+
+- Error handling shape (Go: `if err != nil { return ..., fmt.Errorf(...) }`;
+  Rust: `?` propagation; TS: try/catch vs. Result types)
+- Logging convention (structured vs. `fmt.Println`; named logger vs.
+  package-level)
+- Public API shape (exported types, interface-heavy vs. struct-heavy)
+
+Grep narrow — 20–50 lines is enough to surface the dominant convention. Don't
+read the whole repo; surface what's consistent, let the user correct via
+prompts.
+
+### Step 4a: Probe for generalizable reliability classes
+
+Read `resources/reliability-class-library.md`. For each of its 7 classes, run
+the per-language probe matching the language detected in Step 1 (fall back to
+the class's generic probe if the detected language has no dedicated entry).
+Record every hit as an adapted finding: the class name, the specific file/line
+found, and a BAD/GOOD pair phrased in the target repo's own language and
+idioms — never reuse the library's own example snippets verbatim, they are
+illustrations of the SHAPE to look for, not text to paste.
+
+A class with zero hits is not an error — record it as walked-and-not-found and
+move on. This step runs before the interactive prompts (Step 5) so seeded
+findings can be shown to the user as defaults they can accept, edit, or
+decline, rather than starting from a blank prompt.
+
+### Step 5: Interactive prompts for project-specific rules
+
+Use `AskUserQuestion` for items the codebase can't reveal:
+
+- Known anti-patterns this team has hit (with links to post-mortems if any)
+- Non-negotiable red flags (e.g. "never rm -rf a session dir")
+- Deploy/release constraints (e.g. "no pushes to main from agents")
+- External dependencies that require care (e.g. "never call prod Salesforce APIs
+  from tests")
+
+Each prompt should offer a clear default (usually "none"). Philosophy doc
+quality comes from real answers, not filler.
+
+> **`AskUserQuestion` permits at most 4 options per question.** Exceeding the
+> limit triggers a runtime "Invalid tool parameters" / "expected array to have
+> <=4 items" error. Each of the categories above has a natural option count that
+> can grow past 4 once a real team's rules are listed — so use multiple
+> sequential questions (e.g. "category?" → "specific item within category?")
+> rather than packing options into a single prompt. Prefer one prompt per
+> category over one prompt with all categories listed.
+
+### Step 6: Render the template
+
+Read `resources/philosophy-template.md`. It is not token-substituted — it
+uses bracketed prose placeholders (e.g. `[Criterion 1 — e.g., ...]`) that you
+replace with real content, and `<!-- TODO: ... -->` comments for anything left
+undetected or unprovided. Fill in:
+
+- The intro/language/framework/test-harness lines from Step 1–3.
+- The `## Anti-Patterns` section's `### 1.`–`### 3.` entries are universal
+  defaults — leave them as-is unless a detected convention (Step 4)
+  contradicts one.
+- `### 4.` onward: one numbered section per Step 4a finding (an adapted class
+  hit), in the order the classes are listed in the library, using that
+  finding's BAD/GOOD pair and Why. If Step 4a found more than 2 classes, add
+  as many numbered sections as the probe finds — the template's `### 4.`/
+  `### 5.` are illustrative slots, not a fixed count. If Step 4a found fewer
+  than 2, leave the remaining slot(s) as the template's own
+  `[Project-specific anti-pattern]` placeholder rather than fabricating a
+  finding.
+- Any remaining `[...]` placeholder with no detected or provided value stays
+  as a `<!-- TODO: … -->` line rather than silent emptiness.
+
+### Step 6a: MANDATORY — wire the project's security/threat model into the Decision Framework
+
+If the project has a written threat model (search `docs/security_model/`,
+`docs/security*.md`, `SECURITY.md`), the rendered philosophy MUST carry a
+Decision Framework row pointing at it — and that row MUST NOT be keyed on the
+word "attacker".
+
+```text
+| Does this add a GUARD, RETENTION RULE, PERMANENCE/IMMUTABILITY claim,
+  AUDIT/FORENSIC requirement, TAMPER-EVIDENCE, or AUTHORIZATION/RECIPIENT
+  check — WHETHER OR NOT it names an attacker? | Read <threat-model-path> §1
+  BEFORE designing it. State the project's actual deployment shape here. |
+```
+
+**A control whose key excludes its own target population is decoration** —
+key the Decision Framework row on effect (adds a guard, retention rule,
+permanence claim, audit/forensic requirement, tamper-evidence, or
+authorization check), never on whether it names an attacker. Security-shaped
+requirements often arrive wearing non-security vocabulary: durability,
+forensics, compliance, "defence in depth", "must never be lost".
+
+🔴 **AND STATE THE DEPLOYMENT SHAPE POSITIVELY, not just the exclusions.** The
+dominant failure here is importing a SaaS/multi-tenant frame into a system
+that is not one — which **manufactures defects out of correct design**.
+Write what the project IS, e.g. for thrum: *NOT SaaS, NOT
+internet-facing, NOT product-oriented; single-user, localhost, multi-machine
+on the same network.* A reader who knows only what is out of scope will still
+import the wrong frame.
+
+### Step 7: Write `.thrum/philosophy.md`
+
+`mkdir -p .thrum/` then write the rendered content. Announce the path in the
+final message so the user knows where to edit it manually later.
+
+## Re-run-unchanged mode
+
+Triggered when `.thrum/philosophy.md` exists. The goal is a fast,
+side-effect-free sanity check that confirms the doc is still accurate for the
+current project state.
+
+### Step 1: Read the existing doc
+
+Read `.thrum/philosophy.md` in full. Parse its sections — at minimum the
+language/framework line, the test harness line, and the anti-patterns list.
+
+### Step 2: Sanity-check against current project state
+
+Walk the same detection steps as first-run, but compare rather than write:
+
+- Language / framework / test harness — do the current manifest files agree with
+  what the doc claims?
+- Anti-patterns in `CLAUDE.md` (or equivalent) — is every anti-pattern in
+  CLAUDE.md reflected in the doc?
+- Linters or test configs recently added — are they acknowledged?
+
+Each check is a boolean "matches" vs. "differs". Keep the comparison narrow;
+this mode should not do deep inspection.
+
+### Step 3: If nothing differs — no-op exit
+
+Print:
+
+> `.thrum/philosophy.md` is current; no changes needed.
+
+Do NOT write to the file. Do NOT update mtime. Do NOT create backups. Exit
+cleanly.
+
+### Step 4: If anything differs — hand off to evolved mode
+
+If at least one check reports "differs", transition to the re-run-evolved flow
+(below). The drift detection from Step 2 becomes the input to the diff proposal.
+
+Idempotency invariant: re-running `/project-philosophy` on an unchanged project
+must never modify any file. Tests for this mode should confirm mtime is
+untouched — `stat -c %Y .thrum/philosophy.md` on Linux,
+`stat -f %m .thrum/philosophy.md` on macOS.
+
+## Re-run-evolved mode
+
+Triggered when `.thrum/philosophy.md` exists AND the unchanged-mode sanity check
+flagged drift. This is the load-bearing idempotency path — philosophy docs
+accumulate learned anti-patterns over time, so silent overwrites destroy
+context. The merge-proposal shape is the only correct shape.
+
+> **Never silently overwrite.** Philosophy docs are not regenerated — they are
+> evolved. If the user has added hand-written anti-patterns, post-mortem
+> references, or team-specific notes, those must survive every re-run. A write
+> without explicit user confirmation is a bug.
+
+### Step 1: Read the existing doc
+
+Same as re-run-unchanged Step 1. Keep the parsed sections in memory so the diff
+proposal can cite them.
+
+### Step 2: Detect drift
+
+Four drift categories, conservative on purpose:
+
+- **Language/framework version change.** `go.mod`'s `go 1.X` differs from the
+  doc's stated version; `package.json` lists `next@15.x` but doc says
+  `next@14.x`.
+- **New test patterns in codebase.** `ginkgo` imports appear but the doc lists
+  only `stdlib testing`. New `playwright.config.ts` exists but doc doesn't
+  mention E2E.
+- **New anti-patterns recorded in CLAUDE.md since last run.** Compare
+  anti-pattern bullets in CLAUDE.md against the doc's `{{ANTI_PATTERNS}}`
+  section; anything new in CLAUDE.md is a drift candidate.
+- **New linters or code-quality tooling added.** `.golangci.yml`,
+  `eslint.config.js`, `ruff.toml` that weren't mentioned in the doc.
+
+Start conservative. Expand the detector list only based on real-use feedback —
+over-eager drift detection pesters users and erodes trust in the skill.
+
+### Step 3: Compute a proposed diff (sectional)
+
+Present drift as a readable sectional diff, one item per drift category. Each
+item should have:
+
+- The detected change in plain language
+- A proposed edit (insertion / replacement / addition at the bottom of a
+  section)
+- A one-line rationale
+
+Example shape:
+
+```markdown
+### Proposed updates to `.thrum/philosophy.md`
+
+**1. Framework version bump**
+
+- Current: "Next.js 14"
+- Proposed: "Next.js 15"
+- Rationale: `package.json` lists `"next": "^15.0.0"`
+
+**2. New anti-pattern from CLAUDE.md**
+
+- Proposed addition under "## Anti-patterns":
+  > - Never run migrations from an agent session — always via the release
+  >   pipeline.
+- Rationale: Added to CLAUDE.md in commit abc1234 after the 2026-03 incident.
+```
+
+### Step 4: Present via `AskUserQuestion`
+
+Use `AskUserQuestion` with:
+
+- A concise summary question: "3 drifts detected against `.thrum/philosophy.md`.
+  Apply all, select, or decline?"
+- Options: `Apply all`, `Select items to apply`, `Decline (keep doc as-is)`
+- Include the full sectional diff from Step 3 in the question context so the
+  user can see what they're approving
+
+If the user picks `Select items`, fire a follow-up `AskUserQuestion` with
+per-item yes/no choices.
+
+### Step 5: Write only on confirmation
+
+Apply approved edits in-place. For each applied edit:
+
+- Preserve surrounding content (don't re-render the whole template)
+- Append a provenance comment near the change:
+  `<!-- updated YYYY-MM-DD via project-philosophy re-run-evolved -->`
+
+Write the file once, at the end. Announce the applied items in the final
+message.
+
+### Step 6: On decline — no write + log
+
+If the user declines (or selects zero items), do NOT write to the file. Record
+the skipped proposal in `.thrum/philosophy-skipped.jsonl` (append-only, one JSON
+line per decline) with the timestamp and the drift items proposed. Future runs
+can re-surface the same items without re-computing drift from scratch.
+
+Skipped-proposal log is advisory — its absence is not an error.
+
+## Reference
+
+- `.thrum/philosophy.md` — the canonical doc this skill generates
+- `resources/reliability-class-library.md` — the generalizable reliability
+  class library Step 4a probes; shared with `project-hotpath-gate`
+- `coordinator-philosophy-merge-gate` — the gate skill that reads the philosophy
+  doc
+- `project-hotpath-gate` — the companion builder that generates
+  `.thrum/hotpath-gate.json` (hot-path/perf gate config). Run both at the same
+  onboarding moment so the project has both general philosophy and hot-path gate
+  configuration from day one.

package/assets/skills/project-philosophy/resources/philosophy-template.md

@@ -0,0 +1,155 @@
+# Implementation Philosophy
+
+> **For all agents:** This document governs how features are built. Read this
+> BEFORE any plan file or task descriptions. When in doubt, ask: "[your > >
+> project's > guiding question — e.g., 'Am I wiring a real service, or faking >
+>
+> > it?']"
+>
+> **Fill this template** for your project. The pre-filled examples below are
+> universal defaults — adapt, replace, or extend them for your domain.
+
+## Core Principle
+
+**Every implementation MUST satisfy ALL of these criteria:**
+
+1. [Criterion 1 — e.g., Handler calls real service method, not hardcoded data]
+2. [Criterion 2 — e.g., Template renders from service response, not inline HTML]
+3. [Criterion 3 — e.g., Changing underlying data changes rendered output]
+4. [Criterion 4 — e.g., Access control uses real permission checks, not
+   client-side hiding]
+5. The verification step in the task description passes
+
+## Decision Framework
+
+When implementing any requirement, follow this decision tree:
+
+| Question                                   | Action                                |
+| ------------------------------------------ | ------------------------------------- |
+| Does a backend service already exist?      | Wire it. Do not rewrite.              |
+| Does the service exist but need extension? | Extend the service, then wire.        |
+| Is this purely new capability?             | Build minimal service first, then UI. |
+| Is this seed data / configuration?         | Load into real stores, not hardcoded. |
+
+## Anti-Patterns
+
+<!-- Define BAD/GOOD code examples. Sections 1-3 are universal defaults.  -->
+<!-- Sections 4+ are seeded from the reliability-class-library probe     -->
+<!-- (project-philosophy SKILL.md Step 4a) — as many numbered sections as the probe finds, not a fixed count. -->
+<!-- The BAD/GOOD format is critical — it makes the standard concrete and unambiguous. -->
+
+### 1. Hardcoded data in handlers
+
+```text
+// BAD — handler returns static data, ignoring the service layer
+func handleList(w http.ResponseWriter, r *http.Request) {
+    items := []Item{{Name: "hardcoded-1"}, {Name: "hardcoded-2"}}
+    tmpl.Execute(w, items)
+}
+
+// GOOD — handler calls real service, renders response
+func handleList(w http.ResponseWriter, r *http.Request) {
+    items, err := h.store.ListItems(r.Context())
+    if err != nil { http.Error(w, err.Error(), 500); return }
+    tmpl.Execute(w, items)
+}
+```
+
+**Why:** Hardcoded data passes tests but breaks when real data changes. It
+creates a false sense of completion.
+
+### 2. Client-side permission hiding
+
+```html
+<!-- BAD — server renders everything, JS/CSS hides unauthorized items -->
+<button id="admin-action" style="display:none">Delete</button>
+<script>
+  if (userRole === "admin") show("admin-action");
+</script>
+
+<!-- GOOD — server only renders items the user can access -->
+{{if .Permissions.CanDelete}}
+<button>Delete</button>
+{{end}}
+```
+
+**Why:** Client-side hiding is a UI illusion, not access control. The server
+still processes unauthorized requests.
+
+### 3. Scripted/mocked responses in production paths
+
+```python
+# BAD — handler returns a pre-written response instead of calling the service
+def analyze(request):
+    return {"result": "This ticket appears to be high priority..."}
+
+# GOOD — handler calls the real analysis service
+def analyze(request):
+    result = analysis_service.analyze(request.ticket_id)
+    return {"result": result}
+```
+
+**Why:** Scripted responses mask integration failures. The service may not
+actually work, and you won't know until production.
+
+### 4. [Project-specific anti-pattern]
+
+```text
+// BAD
+// GOOD
+```
+
+**Why:** [Impact explanation]
+
+### 5. [Project-specific anti-pattern]
+
+```text
+// BAD
+// GOOD
+```
+
+**Why:** [Impact explanation]
+
+## Acceptable Simplifications
+
+Not everything needs to be production-grade. These simplifications are OK:
+
+| Simplification             | Why It's OK                          | Boundary (when to stop)                  |
+| -------------------------- | ------------------------------------ | ---------------------------------------- |
+| SQLite instead of Postgres | Same SQL interface, simpler setup    | When concurrent write throughput matters |
+| Cached/mock external APIs  | Deterministic tests, no network deps | When testing real API behavior changes   |
+| Static seed data           | Reproducible demos and tests         | When data must reflect real user input   |
+| [Project-specific]         | [Rationale]                          | [Boundary]                               |
+
+## Red Flags
+
+If you see any of these in your code, **STOP and fix before continuing:**
+
+- [ ] Literal data structures returned from handlers (not from a store/service)
+- [ ] Inline HTML generation (`fmt.Fprintf`, string concatenation) instead of
+      templates
+- [ ] Missing error handling on service/store calls
+- [ ] TODO/FIXME comments left in committed code
+- [ ] [Project-specific red flag]
+- [ ] [Project-specific red flag]
+- [ ] [Project-specific red flag]
+
+## For Implementation Agents
+
+### Before You Start a Task
+
+- [ ] Read the design doc referenced in your prompt
+- [ ] Read the task description (`bd show {TASK_ID}`) — it's your source of
+      truth
+- [ ] Search the plan file for your task's implementation code
+      (`grep "## Task: {BEAD_ID}" plan-file.md`)
+- [ ] Identify which existing services to wire (do not reimplement)
+- [ ] Review the anti-patterns above — know what NOT to do
+
+### Before You Close a Task
+
+- [ ] All acceptance criteria in the beads task are satisfied
+- [ ] Tests pass (run quality commands from your prompt)
+- [ ] No red flags present in your implementation
+- [ ] Commit message is descriptive
+- [ ] Code follows existing project patterns and conventions