@phuc1403/musketeer 0.7.0 → 0.9.0

package/template/.claude/skills/skill-creator/scripts/utils.py

@@ -1,47 +1,47 @@
-"""Shared utilities for skill-creator scripts."""
-
-from pathlib import Path
-
-
-
-def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
-    """Parse a SKILL.md file, returning (name, description, full_content)."""
-    content = (skill_path / "SKILL.md").read_text()
-    lines = content.split("\n")
-
-    if lines[0].strip() != "---":
-        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
-
-    end_idx = None
-    for i, line in enumerate(lines[1:], start=1):
-        if line.strip() == "---":
-            end_idx = i
-            break
-
-    if end_idx is None:
-        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
-
-    name = ""
-    description = ""
-    frontmatter_lines = lines[1:end_idx]
-    i = 0
-    while i < len(frontmatter_lines):
-        line = frontmatter_lines[i]
-        if line.startswith("name:"):
-            name = line[len("name:"):].strip().strip('"').strip("'")
-        elif line.startswith("description:"):
-            value = line[len("description:"):].strip()
-            # Handle YAML multiline indicators (>, |, >-, |-)
-            if value in (">", "|", ">-", "|-"):
-                continuation_lines: list[str] = []
-                i += 1
-                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
-                    continuation_lines.append(frontmatter_lines[i].strip())
-                    i += 1
-                description = " ".join(continuation_lines)
-                continue
-            else:
-                description = value.strip('"').strip("'")
-        i += 1
-
-    return name, description, content
+"""Shared utilities for skill-creator scripts."""
+
+from pathlib import Path
+
+
+
+def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
+    """Parse a SKILL.md file, returning (name, description, full_content)."""
+    content = (skill_path / "SKILL.md").read_text()
+    lines = content.split("\n")
+
+    if lines[0].strip() != "---":
+        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
+
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
+
+    name = ""
+    description = ""
+    frontmatter_lines = lines[1:end_idx]
+    i = 0
+    while i < len(frontmatter_lines):
+        line = frontmatter_lines[i]
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip('"').strip("'")
+        elif line.startswith("description:"):
+            value = line[len("description:"):].strip()
+            # Handle YAML multiline indicators (>, |, >-, |-)
+            if value in (">", "|", ">-", "|-"):
+                continuation_lines: list[str] = []
+                i += 1
+                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
+                    continuation_lines.append(frontmatter_lines[i].strip())
+                    i += 1
+                description = " ".join(continuation_lines)
+                continue
+            else:
+                description = value.strip('"').strip("'")
+        i += 1
+
+    return name, description, content

package/template/.claude/hooks/inject-context.cjs

@@ -1,52 +0,0 @@
-#!/usr/bin/env node
-// SessionStart hook (dotnet company): auto-load the repo-root `CONTEXT.md` — the
-// bounded-context model produced by the knowledge-crunching skill — into every
-// session, so the domain's ubiquitous language and invariants "lead the code".
-//
-// If the root CONTEXT.md is missing, ALERT the user (systemMessage) so they
-// create one. Any other error fails open (emits nothing, exit 0) so it can never
-// block a session.
-const fs = require("fs");
-const path = require("path");
-
-const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const file = path.join(root, "CONTEXT.md");
-
-try {
-  let content;
-  try {
-    content = fs.readFileSync(file, "utf-8");
-  } catch {
-    // Not found — surface a visible warning to the user, inject nothing.
-    process.stdout.write(
-      JSON.stringify({
-        systemMessage:
-          "musketeer: no CONTEXT.md at the repo root — the bounded-context model is missing. " +
-          "Run the knowledge-crunching skill (/knowledge-crunching) to create one.",
-      })
-    );
-    process.exit(0);
-  }
-
-  const additionalContext =
-    "Bounded-context model (root CONTEXT.md) — injected every session. It is the " +
-    "ubiquitous language and model rules of this bounded context, kept vendor- and " +
-    "decision-neutral. Treat it as canonical for domain naming, concepts, and invariants: " +
-    "name new code after it, and when a concept is renamed update CONTEXT.md and the code in " +
-    "the same turn. It bounds what the DOMAIN model sees, not what infrastructure may do " +
-    "(an ACL can legitimately key on more).\n\n" +
-    "===== CONTEXT.md =====\n" +
-    content.trimEnd();
-
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext,
-      },
-    })
-  );
-  process.exit(0);
-} catch {
-  process.exit(0); // fail open
-}

package/template/.claude/skills/code-review/references/adversarial-review.md

@@ -1,223 +0,0 @@
----
-name: adversarial-review
-description: Stage 3 red-team review that actively tries to break code — finds security holes, false assumptions, failure modes, race conditions. Spawns adversarial reviewer subagent with destructive mindset. Includes scope gate for trivial changes.
----
-
-# Adversarial Review (Stage 3)
-
-Runs after every Stage 2 (Code Quality) pass. Subject to scope gate below.
-
-## Scope Gate
-
-Skip adversarial review when ALL of these are true:
-- Changed files <= 2
-- Lines changed <= 30
-- No security-sensitive files touched (auth, crypto, input parsing, SQL, env)
-- No new dependencies added
-
-When skipped, note: `Adversarial: skipped (below threshold)` in review output.
-
-**NEVER skip when:**
-- Any file in: `auth/`, `middleware/`, `security/`, `crypto/`
-- `package.json`, `package-lock.json`, or lockfile changed
-- Environment variables added/changed
-- Database schema modified
-- API route added/changed
-
-## Mindset
-
-> "You are hired to tear apart the implementer's work. Your job is to find every way this code can fail, be exploited, or produce incorrect results. Assume the implementer made mistakes. Prove it."
-
-This is NOT a standard code review. Standard reviews check if code meets requirements. Adversarial review assumes requirements are met and asks: **"How can this still break?"**
-
-## What to Attack
-
-### Security Holes
-- Injection vectors (SQL, command, XSS, template)
-- Auth bypass paths (missing checks, privilege escalation)
-- Secrets exposure (logs, error messages, stack traces)
-- Input trust boundaries (user input treated as safe)
-- SSRF, path traversal, deserialization attacks
-
-### False Assumptions
-- "This will never be null" -- prove it can be
-- "This list always has elements" -- find the empty case
-- "Users always call A before B" -- find the out-of-order path
-- "This config value exists" -- find the missing env var
-- "This third-party API always returns 200" -- find the failure mode
-- "This API shape won't change" -- find the breaking caller
-
-### Failure Modes & Resource Exhaustion
-- What happens when disk is full?
-- What happens when network times out mid-operation?
-- What happens when the database connection drops during a transaction?
-- Unbounded allocations from user-controlled input
-- Missing timeouts on external calls
-- Event loop blocking (sync operations in async context)
-- Connection/handle leaks on error paths
-- Regex catastrophic backtracking (ReDoS)
-
-### Race Conditions
-- Shared mutable state without locks
-- Time-of-check-to-time-of-use (TOCTOU)
-- Async operations with implicit ordering assumptions
-- Cache invalidation during concurrent writes
-
-### Data Corruption
-- Partial writes on failure (no transaction/rollback)
-- Type coercion surprises (string "0" as falsy)
-- Floating point comparison for equality
-- Timezone-naive datetime operations
-
-### Supply Chain & Dependencies
-- New dependencies: postinstall scripts, maintainer reputation, bundle size
-- Lockfile changes: version drift, removed integrity hashes
-- Transitive deps pulling in known-vulnerable packages
-
-### Observability Blind Spots
-- Swallowed errors (`catch {}` with no log)
-- Missing structured context in error logs
-- PII in log output
-
-## Process
-
-### 1. Spawn Adversarial Reviewer
-
-Dispatch `code-reviewer` subagent with adversarial prompt:
-
-```
-You are an adversarial code reviewer. Your ONLY job is to find ways this code
-can fail, be exploited, or produce incorrect results.
-
-DO NOT praise the code. DO NOT note what works well.
-ONLY report problems. If you find nothing, say "No findings" -- but try harder first.
-
-Focus on ADDED/MODIFIED lines (+ prefix in diff). Pre-existing code is out of scope
-unless the change makes it newly exploitable.
-
-Context (read for understanding, DO NOT review):
-{CONTEXT_FILES}
-
-Runtime: {RUNTIME} (e.g., Node.js single-threaded, browser, serverless)
-Framework: {FRAMEWORK} (e.g., Express with global error handler at app.ts:45)
-
-Review this diff:
-{DIFF}
-
-Changed files: {FILES}
-
-Attack vectors to check:
-1. Security holes (injection, auth bypass, secrets exposure)
-2. False assumptions (null, empty, ordering, config, API contracts)
-3. Failure modes + resource exhaustion (timeouts, leaks, unbounded input)
-4. Race conditions (shared state, TOCTOU, async ordering)
-5. Data corruption (partial writes, type coercion, encoding)
-6. Supply chain (new deps, lockfile changes, transitive vulns)
-7. Observability (swallowed errors, missing logs, PII in output)
-
-For each finding, report:
-- SEVERITY: Critical / Medium / Low
-- CATEGORY: Security / Assumption / Failure / Race / Data / Supply / Observability
-- LOCATION: file:line
-- ATTACK: How to trigger the problem
-- IMPACT: What happens when triggered
-- FIX: Describe the fix approach (e.g., "add null check before line 42").
-  Do NOT write implementation code -- the implementer has full context.
-```
-
-**If adversarial produces >10 findings on <100 lines changed:** likely too aggressive. Batch-reject noise, deep-review only Critical/Medium.
-
-### 2. Adjudicate Findings
-
-Main agent reviews each adversarial finding and assigns verdict:
-
-| Verdict | Meaning | Action |
-|---------|---------|--------|
-| **Accept** | Valid flaw, reproducible or clearly reasoned | Must fix before merge |
-| **Reject** | False positive, already handled, or impossible path | Document why, no action |
-| **Defer** | Valid but low-risk, tracked for later | Create GitHub issue for tracking |
-
-**Rules:**
-- Every finding gets a verdict -- no silent dismissals
-- Critical findings: Accept unless you can PROVE false positive
-- Benefit of doubt goes to the adversary (safer to fix than to dismiss)
-- If >50% of findings are Rejected, the adversary was too aggressive -- but still report all
-
-**Calibration examples:**
-
-| Verdict | Example | Reasoning |
-|---------|---------|-----------|
-| Accept | "SQL injection via string interpolation in query builder" | Clearly exploitable, concrete path shown |
-| Reject | "Missing null check on config.apiUrl" | Config loaded at startup with schema validation (see config.ts:12), cannot be null at runtime |
-| Defer | "No rate limiting on POST /api/upload" | Valid concern but internal-only tool currently; track for public exposure |
-
-### 3. Report Format
-
-```
-## Adversarial Review -- Stage 3
-
-### Summary
-- Findings: N total (X Critical, Y Medium, Z Low)
-- Accepted: A (must fix)
-- Rejected: B (false positive)
-- Deferred: C (tracked via GitHub issues)
-
-### Accepted Findings (Must Fix)
-
-#### [1] SEVERITY -- CATEGORY -- file:line
-**Attack:** How to trigger
-**Impact:** What happens
-**Fix:** Approach description
-**Verdict:** Accept -- [reason]
-
-### Rejected Findings
-
-#### [N] SEVERITY -- CATEGORY -- file:line
-**Attack:** Claimed vector
-**Verdict:** Reject -- [reason this is a false positive]
-
-### Deferred Findings
-
-#### [N] SEVERITY -- CATEGORY -- file:line
-**Attack:** How to trigger
-**Verdict:** Defer -- [reason] → GitHub issue #X
-```
-
-### 4. Fix Accepted Findings
-
-- Critical: Block merge. Fix immediately via `/fix` or manual edit.
-- Medium: Fix before merge if feasible. Defer only with explicit user approval.
-- Low: Track. Fix in follow-up if pattern repeats.
-
-### Re-review Optimization
-
-On fix cycles (re-running after accepted findings were fixed):
-- Only pass the FIX diff to adversarial, not the full original diff
-- Verify accepted findings are resolved
-- Check for regression: did the fix introduce new issues?
-
-## Integration with Pipeline
-
-```
-Stage 1 (Spec) → PASS
-  ↓
-Stage 2 (Quality) → PASS
-  ↓
-Scope gate → below threshold? → skip (note in report)
-  ↓ (above threshold)
-Stage 3 (Adversarial) → findings
-  ├─ 0 Accepted → PASS → proceed
-  ├─ Accepted Critical → BLOCK → fix → re-run Stage 3 (fix diff only)
-  └─ Accepted Medium/Low only → fix or defer → proceed
-```
-
-**Task pipeline update:** When using task-managed reviews, adversarial review gets its own task between "Review implementation" and "Fix critical issues".
-
-## What This Is NOT
-
-- NOT a style review (Stage 2 handles that)
-- NOT a spec compliance check (Stage 1 handles that)
-- NOT dependency graph analysis or import tracing (scout handles that)
-- NOT a general "suggestions for improvement" pass
-
-This is a focused, hostile attempt to break the code. If the code survives, it's ready to ship.

package/template/.claude/skills/knowledge-crunching/assets/context.template.md

@@ -1,59 +0,0 @@
-# {{CONTEXT_TITLE}}
-
-<One line: the slice of the domain this context covers — the flow you crunched, in the expert's words.>
-
-> Starter for a context that has **no `CONTEXT.md` yet**. It lives at the
-> root folder as `CONTEXT.md`. If the context already has one, edit that — never a second.
-
-## Language
-
-The vocabulary of *this* context, crunched with the domain expert. Each entry must clear this bar:
-
-- **One meaning.** A term denotes exactly one thing here. If it means two things, split it into two.
-- **Defined in the expert's words**, present tense — never with implementation or vendor terms, and
-  never using the term to define itself.
-- **Says what it is _not_** whenever it's easily confused with a neighbour — the sharpest
-  disambiguator there is.
-- **Carries its governing rule** when one exists ("… finishes when …") — the language should imply the
-  behavior, not just label a noun.
-- **Bound to code:** name the `TypeName` that embodies it. The type and the term are the same word.
-- **`_Avoid_:` rejected synonyms** so the wrong word can't creep back (add a half-line *why* if it
-  isn't obvious).
-
-Group related terms under `###` subsections. Reference other defined terms by their exact name.
-
-Worked example of the bar (delete once you have your own):
-
-### Connectivity
-
-**Net**:
-A conductor that carries one signal to every `Pin` connected to it; a signal crossing a `Net` counts as
-one **hop**. _Not_ a physical wire segment — one `Net` may span many segments.
-_Avoid_: wire, trace, connection
-
-**Pin**:
-A single connection point on a `ComponentInstance`. Belongs to exactly one `ComponentInstance` and
-connects to exactly one `Net` — that one-to-one-to-one rule is an invariant.
-_Avoid_: leg, terminal (terminal means the physical metal, not the model concept)
-
----
-
-### <your first group>
-
-**<Term>**:
-<One sentence in the expert's words; fold in the governing rule if any, and what it is _not_ if it's
-confusable; name the `TypeName` that embodies it.>
-_Avoid_: <rejected synonyms>
-
-## Deferred
-
-Concepts that exist in the domain but this scenario doesn't need yet — distilled out, the way Evans
-dropped `Topology` for the probe simulation. Bring one back only when a feature actually pulls it in.
-
-- **<Term>** — <what it is; why it isn't needed yet>
-
-## Flagged ambiguities
-
-Open questions or contradictions between experts, to resolve in a later loop.
-
-- <the question — and who or what would settle it>

package/template/.claude/skills/knowledge-crunching/references/crunching-dialogue.md

@@ -1,113 +0,0 @@
-# The Crunching Dialogue
-
-How to run Step 4's per-concept loop well: the kinds of questions that actually move the model, and
-the full PCB session translated from Evans' diagrams into the code/test/glossary this skill produces.
-
-> The model fragments below are written in **language-neutral pseudocode** so the modeling moves stay
-> the point. In a real session, write them as actual runnable types and tests in the bounded context's
-> own language and test framework.
-
-## Verifying-question catalog
-
-Each loop turn asks **one** question whose answer would change the code if your guess is wrong. Pick
-the type that fits the fragment you just proposed. A good question is falsifiable, concrete, and
-answerable in a sentence — not "does this look right?"
-
-| Type | What it pins down | Template | PCB example |
-|---|---|---|---|
-| **Cardinality** | how many relate to how many | "Does one X belong to exactly one Y, or many?" | "A `Pin` belongs to one `ComponentInstance` and one `Net`?" |
-| **Synonym** | two words, one concept | "Are X and Y the same thing?" | "Is `ref-des` the same as `component instance`?" |
-| **Ownership of behavior** | which object does the work | "What pushes the signal — X or Y?" | "Does the `Net` carry the signal further, or does the component push it?" |
-| **Exclusion / relevance** | is this concept needed *now* | "Does X matter for this scenario?" | "Does `Topology` come into the probe simulation?" |
-| **Simplification** | how little can we model | "Is a simplified Z enough instead of full X?" | "Can a list of push-throughs stand in for chip internals?" |
-| **Computation goal** | what the output must be | "What exactly do you need from this?" | "What are we looking for — paths longer than 2–3 hops?" |
-| **Definition of a unit** | what one increment is | "What counts as one X?" | "What counts as one hop?" |
-| **Lifetime / sameness** | shared vs per-instance data | "Is this the same for every instance, or per instance?" | "Are the pushes the same for all instances of a component?" |
-
-Rules of thumb:
-- If you can't think of a question, you don't understand the fragment well enough to code it — go
-  smaller.
-- Prefer a question that could get a "no." A question that can only be answered "yes" teaches nothing.
-- After a "no," restate the corrected understanding before moving on, so the correction is shared.
-
-## The PCB session, translated to code
-
-Evans drew object-interaction and class diagrams. This skill produces the same model as code + tests +
-glossary. Below, each beat of the original dialogue maps to what you would actually write.
-
-### Beat 1 — the glimmer ("nets")
-The experts kept asking for reports about *nets*. That recurring noun, not their "read a file and
-sort it" framing, was the first model element. You name it back and ask a cardinality question rather
-than scaffolding a type immediately.
-
-> "A `Net` is a conductor that connects components and carries a signal to everything on it — yes?"
-
-### Beat 2 — reconcile terminology, fix cardinality
-"Component" vs "component instance" vs "ref-des" collide. You reconcile them (synonym question), then
-pin the pin↔instance↔net cardinality (cardinality question). Only once confirmed do you write:
-
-```
-ComponentInstance                 // expert's "ref-des" — reconciled to one name
-    pins -> read-only list of Pin
-
-Pin
-    owner -> ComponentInstance     // exactly one (confirmed)
-    net   -> Net (optional)        // exactly one (confirmed)
-
-Net
-    pins  -> read-only list of Pin // connects many pins
-```
-
-### Beat 3 — narrow to one scenario (probe simulation)
-You drop everything not needed to simulate a signal. You ask the *ownership* question and learn the
-**component pushes the signal through** — the `Net` does not do it alone.
-
-### Beat 4 — simplify what you can't model
-You can't model chip internals; you ask the *simplification* question and the expert offers
-"push-throughs": a list of (fromPin → toPin) for a component **type** (not per instance — that's the
-lifetime question). The behavior, driven by a test:
-
-```
-test "signal propagates through pushes and across nets":
-    // arrange a tiny board: in-pin → component pushes to out-pin → net to next component
-    hops = simulation.probe(startPin)
-    assert hops == 2          // each Net crossing counts as one hop
-```
-
-### Beat 5 — pin the computation goal and the unit
-The *computation-goal* question yields the rule: flag any signal path longer than 2–3 hops. The
-*unit* question yields: **one hop = one Net crossing.** So the `Net` increments the hop count as the
-signal passes:
-
-```
-Net
-    carry(hopsSoFar) -> hopsSoFar + 1   // crossing this Net is one hop
-```
-
-### Beat 6 — distill: drop `Topology`
-`Topology` exists in the domain but isn't used by the probe simulation, so you explicitly leave it
-out ("I'll drop it for now; we'll bring it back for routing"). The model is a distillation, not a
-transcription — it excludes the hundreds of facts the engineers know but this problem doesn't need.
-
-## What "on the same page" looks like at the end of a loop
-
-A loop turn is complete only when **all three** agree:
-1. the **expert** has answered the verifying question,
-2. the **code** (type/method/test) reflects that answer, and
-3. the **`CONTEXT.md` `## Language`** records the term, its definition in their words, the rejected
-   synonyms (`_Avoid_:`), and the `TypeName` that embodies it.
-
-If any of the three lags, close the gap before proposing the next concept.
-
-## Drift triggers in existing code
-
-When the module's domain layer already has a model, read it against the language and let each mismatch
-become a verifying-question loop turn — surface it, verify with the user, then change code +
-`CONTEXT.md` together:
-
-- **Synonym drift** — code says `Learner`, experts now say `Student`. Reconcile, pick one, record the
-  rejected synonym under `_Avoid_:`.
-- **Conflated concept** — one type doing two jobs the experts name separately → candidate split.
-- **Leaked invariant** — a rule enforced in a service/controller that an aggregate should own.
-- **Dead concept** — a type no scenario exercises anymore → deprecate (move to `CONTEXT.md`'s
-  `## Deferred` with the reason).