@grainulation/wheat 1.0.0

package/templates/commands/init.md

@@ -0,0 +1,68 @@
+# /init — Bootstrap a Wheat research sprint
+
+You are initializing a new Wheat research sprint. Have a focused conversation with the user to establish:
+
+1. **What are we figuring out?** Get a clear, specific question. Not "should we use X" but "should we use X given constraints Y and Z for audience A."
+2. **Who is the audience?** Who needs to be convinced or informed? (engineering leads, CTO, product, finance, etc.)
+3. **What constraints exist?** Budget, timeline, tech stack, compliance, team size, existing infrastructure.
+4. **What does done look like?** What artifact ends this sprint? A recommendation? A prototype? A go/no-go decision?
+
+Once you have answers:
+
+## Step 1: Update CLAUDE.md
+
+Update the Sprint section of CLAUDE.md with the question, audience, constraints, and success criteria.
+
+## Step 2: Seed claims.json
+
+Update claims.json with:
+- `meta.question` — the sprint question
+- `meta.initiated` — today's date (ISO format)
+- `meta.audience` — array of audience labels
+- `meta.phase` — set to "define"
+- `meta.connectors` — empty array
+
+Add constraint claims (type: "constraint") for each hard requirement identified. Use IDs starting with `d001`. Each claim needs:
+```json
+{
+  "id": "d001",
+  "type": "constraint",
+  "topic": "<relevant topic>",
+  "content": "<the constraint>",
+  "source": { "origin": "stakeholder", "artifact": null, "connector": null },
+  "evidence": "stated",
+  "status": "active",
+  "phase_added": "define",
+  "timestamp": "<ISO timestamp>",
+  "conflicts_with": [],
+  "resolved_by": null,
+  "tags": []
+}
+```
+
+## Step 3: Run the compiler
+
+```bash
+npx @grainulation/wheat compile --summary
+```
+
+Verify compilation succeeds.
+
+## Step 4: Generate problem statement
+
+Generate `output/problem-statement.html` — a clean, self-contained HTML page summarizing the sprint question, audience, constraints, and success criteria. Use the dark theme from the explainer template in `templates/`. Keep it to a single page — this is the "here's what we're investigating" artifact that can be shared immediately.
+
+## Step 5: Git commit
+
+Stage claims.json, CLAUDE.md, output/problem-statement.html, and any other changed files.
+
+Commit with message: `wheat: /init "<sprint question short>" — seeded <claim IDs>`
+
+## Step 6: Tell the user what's next
+
+Tell them:
+- Their problem statement is in `output/problem-statement.html` — they can open it in a browser and share it
+- Next step: `/research <topic>` to start exploring, or `/connect` to link org tools
+- Remind them that `/status` shows the dashboard at any time
+
+$ARGUMENTS

package/templates/commands/merge.md

@@ -0,0 +1,51 @@
+# /merge — Combine Claim Sets Across Sprints
+
+You are merging claims from another sprint into the current one. This is for when two teams researched the same problem independently and need to combine their findings.
+
+## Process
+
+1. **Parse the argument**: The user provides a path to another sprint's claims.json.
+   - Example: `/merge ../auth-sprint/claims.json`
+   - If no path given, ask for it.
+
+2. **Validate both claim sets**:
+   - Read the current `claims.json`
+   - Read the incoming claims file
+   - Validate both against the compiler schema:
+     ```bash
+     npx @grainulation/wheat compile --input <incoming-path> --output /tmp/wheat-merge-incoming.json
+     ```
+
+3. **Determine the sprint slug**: Derive from the incoming sprint's `meta.question`.
+
+4. **Resolve ID collisions**: Prefix all incoming claim IDs with the sprint slug:
+   - `r001` -> `auth-r001`
+   - Also update all `conflicts_with` and `resolved_by` references.
+
+5. **Align topics**: Present probable topic mappings for user confirmation.
+
+6. **Detect cross-sprint conflicts** and **identify evidence upgrades**.
+
+7. **Write merged claims.json** and compile:
+   ```bash
+   npx @grainulation/wheat compile --summary
+   ```
+
+## Git commit
+
+Commit: `wheat: /merge <slug> — merged <N> claims from <source path>`
+
+## Tell the user
+
+- How many claims were merged
+- Topic alignment results
+- Cross-sprint conflicts detected
+- Suggest: `/resolve` for conflicts, `/blind-spot` for cross-sprint gaps
+
+## Cleanup
+
+```bash
+rm -f /tmp/wheat-merge-*.json
+```
+
+$ARGUMENTS

package/templates/commands/present.md

@@ -0,0 +1,52 @@
+# /present — Generate a presentation from compiled claims
+
+You are generating a presentation for this Wheat sprint. Same Bran compilation gate as /brief.
+
+## Process
+
+1. **Run the compiler with check**:
+   ```bash
+   npx @grainulation/wheat compile --check
+   ```
+
+   **If blocked, STOP.** Show errors, suggest fixes. Do not generate a presentation with unresolved conflicts.
+
+2. **Read compilation.json** — use ONLY `resolved_claims`.
+
+3. **Generate presentation HTML**: Create `output/presentation.html` — a self-contained, scroll-snap presentation using a dark theme.
+
+   Structure the slides as:
+   1. **Title slide**: Sprint question, date, audience
+   2. **The Problem**: Why this research was needed (from constraint claims)
+   3. **What We Found**: Key research findings (2-3 slides, from factual claims)
+   4. **What We Tested**: Prototype and evaluation results (from tested claims)
+   5. **Tradeoffs**: Risks and estimates
+   6. **Recommendation**: The compiled recommendation with evidence
+   7. **Next Steps**: Concrete actions
+   8. **Appendix**: Compilation certificate, claim count, evidence summary
+
+   Each slide should:
+   - Be visually clean (use the dark theme, accent colors, cards)
+   - Reference claim IDs subtly (small text at bottom of relevant sections)
+   - Include data visualizations where relevant (CSS-only charts, comparison tables)
+   - Work at any screen size (responsive)
+
+## Key rules
+
+- Same compilation gate as /brief — no presentation without passing compilation
+- Cite claims, but more subtly than the brief (this is for presenting, not auditing)
+- The presentation should tell a story: problem -> investigation -> evidence -> recommendation
+
+## Git commit
+
+Stage output/presentation.html.
+
+Commit: `wheat: /present — generated presentation, certificate [hash]`
+
+## Tell the user
+
+- Presentation is at `output/presentation.html` — open in browser, works for screen share
+- Mention the compilation certificate for reproducibility
+- Suggest `/feedback` after they present to capture stakeholder responses
+
+$ARGUMENTS

package/templates/commands/prototype.md

@@ -0,0 +1,68 @@
+# /prototype — Build something testable
+
+You are building a proof-of-concept for the current Wheat sprint. Read CLAUDE.md for sprint context and claims.json for existing research claims.
+
+## Process
+
+1. **Determine what to prototype**: Based on the user's argument and existing research claims. If no argument given, look at the research and suggest the most promising option to test.
+
+2. **Build it**: Create a working prototype in `prototypes/<name>/`. This should be:
+   - Minimal — just enough to test the hypothesis
+   - Runnable — include a README or run script
+   - Measurable — produce output that can be evaluated
+
+3. **Also generate a demo artifact**: Create `prototypes/<name>/demo.html` — a self-contained HTML page that shows what the prototype does, with screenshots, code snippets, or interactive elements. Non-technical stakeholders should be able to understand the prototype from this page alone.
+
+## Claim updates
+
+Every prototype finding becomes a claim with evidence tier `tested`:
+
+```json
+{
+  "id": "p001",
+  "type": "factual",
+  "topic": "<what was tested>",
+  "content": "<what we found — be specific with numbers>",
+  "source": {
+    "origin": "prototype",
+    "artifact": "prototypes/<name>/",
+    "connector": null
+  },
+  "evidence": "tested",
+  "status": "active",
+  "phase_added": "prototype",
+  "timestamp": "<ISO timestamp>",
+  "conflicts_with": [],
+  "resolved_by": null,
+  "tags": []
+}
+```
+
+**Critical**: Check if any existing research claims (evidence: "web") are contradicted by prototype results. If so:
+- Set `conflicts_with` on both claims
+- The compiler will auto-resolve in favor of `tested` over `web`
+
+Update `meta.phase` to "prototype" in claims.json if this is the first prototype.
+
+## Run the compiler
+
+```bash
+npx @grainulation/wheat compile --summary
+```
+
+Report evidence upgrades (research claims superseded by prototype findings).
+
+## Git commit
+
+Stage claims.json and all new/changed files.
+
+Commit: `wheat: /prototype "<name>" — added <claim IDs>`
+
+## Tell the user
+
+- Point them to the demo.html and the actual prototype code
+- Summarize what was tested and what was found
+- Highlight any research claims that were confirmed or contradicted
+- Suggest: more `/prototype` for other options, `/evaluate` to compare, or `/status` to see progress
+
+$ARGUMENTS

package/templates/commands/replay.md

@@ -0,0 +1,61 @@
+# /replay — Time-Travel Through Sprint Evolution
+
+You are reconstructing the historical evolution of this sprint by recompiling every version of claims.json from git history.
+
+## Process
+
+1. **Get the git history of claims.json**:
+   ```bash
+   git log --oneline claims.json
+   ```
+   This gives every commit that touched claims.json — the sprint event log.
+
+2. **Extract each historical version**: For each commit hash:
+   ```bash
+   git show <hash>:claims.json > /tmp/wheat-replay-<N>.json
+   ```
+
+3. **Recompile each version** with the current compiler:
+   ```bash
+   npx @grainulation/wheat compile --input /tmp/wheat-replay-<N>.json --output /tmp/wheat-comp-<N>.json
+   ```
+
+4. **Compute deltas** between consecutive compilations:
+   ```bash
+   npx @grainulation/wheat compile --diff /tmp/wheat-comp-<N-1>.json /tmp/wheat-comp-<N>.json
+   ```
+
+5. **Identify interesting moments** in each delta:
+   - Phase transitions (define -> research -> prototype -> evaluate)
+   - First time compilation went "ready"
+   - Peak conflict count
+   - Evidence tier jumps (topic going web -> tested)
+   - Claims added then superseded (the sprint changed its mind)
+
+6. **Generate replay HTML**: Create `output/replay.html` — a self-contained timeline visualization using a dark scroll-snap template. Include:
+   - Frame-by-frame scrubbing (each commit = one frame)
+   - Highlighted pivotal moments
+   - Coverage evolution chart
+   - Summary statistics per frame
+
+7. **Print a text summary** to the terminal with the key narrative moments.
+
+## Git commit
+
+Commit: `wheat: /replay — generated sprint timeline (N frames)`
+
+## Tell the user
+
+- How many frames (commits) were found
+- The most interesting moments
+- Point them to `output/replay.html` for the full interactive timeline
+- Suggest: `/handoff` to package this narrative for a successor
+
+## Cleanup
+
+Remove temporary files from /tmp after generating the output:
+```bash
+rm -f /tmp/wheat-replay-*.json /tmp/wheat-comp-*.json
+```
+
+$ARGUMENTS

package/templates/commands/research.md

@@ -0,0 +1,73 @@
+# /research — Deep dive on a topic
+
+You are researching a topic for the current Wheat sprint. Read CLAUDE.md for sprint context and claims.json for existing claims.
+
+## Process
+
+1. **Understand the request**: The user's argument tells you what to research. Could be a technology, a comparison, a question, a process.
+
+2. **Research deeply**: Use web search, read documentation, check connected repos (see Connectors in CLAUDE.md). Be thorough — this is the foundation for later decisions.
+
+3. **Extract claims**: Every finding becomes a typed claim. Be specific and verifiable. Bad: "Auth0 is popular." Good: "Auth0 serves 15,000+ customers as of 2025."
+
+4. **Detect conflicts with existing claims**: Check claims.json. If your new findings contradict existing claims, set `conflicts_with` on both the new and existing claim.
+
+## Adding claims
+
+Append claims to claims.json with IDs continuing the `r###` sequence (check existing claims for the next number). Each claim:
+
+```json
+{
+  "id": "r001",
+  "type": "factual|estimate|risk|recommendation",
+  "topic": "<topic category>",
+  "content": "<specific, verifiable finding>",
+  "source": {
+    "origin": "research",
+    "artifact": "research/<topic-slug>.md",
+    "connector": null
+  },
+  "evidence": "web",
+  "status": "active",
+  "phase_added": "research",
+  "timestamp": "<ISO timestamp>",
+  "conflicts_with": [],
+  "resolved_by": null,
+  "tags": ["<relevant tags>"]
+}
+```
+
+If the finding came from a connector (GitHub repo, Jira, etc.), set evidence to "documented" and fill in the connector field.
+
+## Run the compiler
+
+```bash
+npx @grainulation/wheat compile --summary
+```
+
+Check for new conflicts introduced. Report them to the user.
+
+## Generate HTML explainer
+
+Create `research/<topic-slug>.html` — a self-contained HTML explainer using the dark scroll-snap template style. This should be:
+- Beautiful and presentable (stakeholders will see this)
+- Organized into logical sections (scroll-snap slides)
+- Include key findings, comparisons, tradeoffs
+- Reference claim IDs so findings are traceable
+
+Also create `research/<topic-slug>.md` as the structured markdown source.
+
+## Git commit
+
+Stage claims.json and all new files.
+
+Commit: `wheat: /research "<topic>" — added <claim IDs>`
+
+## Tell the user
+
+- Point them to the HTML file to open in browser
+- Summarize key findings (3-5 bullets)
+- Flag any conflicts with existing claims
+- Suggest next steps: more `/research`, `/prototype`, or `/evaluate`
+
+$ARGUMENTS

package/templates/commands/resolve.md

@@ -0,0 +1,42 @@
+# /resolve — Manually adjudicate a conflict
+
+You are manually resolving a conflict between claims that the compiler couldn't auto-resolve (same evidence tier).
+
+## Process
+
+1. **Run the compiler** to see current conflicts:
+   ```bash
+   npx @grainulation/wheat compile --summary
+   ```
+
+2. **If the user specified claim IDs** (e.g., `/resolve r012 e003`), focus on that conflict. Otherwise, show all unresolved conflicts and ask which to resolve.
+
+3. **Present both sides**: Show the conflicting claims with full context — content, evidence tier, source, when they were added.
+
+4. **Ask the user to decide** (or decide based on additional research if the user asks you to investigate).
+
+5. **Update claims.json**:
+   - Set the winning claim's status to `active`
+   - Set the losing claim's status to `superseded` and `resolved_by` to the winner's ID
+   - Remove the conflict references from `conflicts_with`
+
+6. **Run the compiler again**:
+   ```bash
+   npx @grainulation/wheat compile --summary
+   ```
+
+   Verify the conflict is resolved.
+
+## Git commit
+
+Stage claims.json.
+
+Commit: `wheat: /resolve <winner> over <loser> — "<reason>"`
+
+## Tell the user
+
+- Confirm which claim won and why
+- Show updated compilation status
+- If all conflicts resolved, suggest `/brief` or `/present`
+
+$ARGUMENTS

package/templates/commands/status.md

@@ -0,0 +1,56 @@
+# /status — Render the sprint dashboard
+
+You are generating the current status dashboard for this Wheat sprint.
+
+## Process
+
+1. **Run the compiler**:
+   ```bash
+   npx @grainulation/wheat compile --summary
+   ```
+
+2. **Read compilation.json** for all dashboard data.
+
+3. **Read git log** for recent activity:
+   ```bash
+   git log --oneline -20 claims.json
+   ```
+
+4. **Generate dashboard HTML**: Create/update `output/dashboard.html` — a self-contained dashboard page. The dashboard must show:
+
+   **Header**: Sprint question, current phase, compilation status (ready/blocked), days since initiation
+
+   **Phase Progress**: Visual progress through define -> research -> prototype -> evaluate -> compile. Show which phases have claims.
+
+   **Evidence Strength by Topic**: For each topic in coverage, show:
+   - Topic name
+   - Number of claims
+   - Highest evidence tier (with color coding: green=tested/production, amber=documented, red=web/stated)
+   - Visual bar representing depth
+
+   **Conflict Status**:
+   - Resolved conflicts with winner/loser and reason
+   - Unresolved conflicts highlighted as blockers
+   - "Compilation readiness" indicator
+
+   **Connected Sources**: List any connectors from meta
+
+   **Recent Activity**: From git log — the sprint timeline
+
+   **Claim Inventory**: Grouped by topic, showing type, evidence tier, and status for each claim
+
+5. **Also print a text summary to the terminal** so the user gets immediate feedback without opening a file.
+
+## Git commit
+
+Only commit if the dashboard changed meaningfully. Don't commit for a status-only check.
+
+Commit: `wheat: /status — updated dashboard`
+
+## Tell the user
+
+- Print the text summary (phase, claim counts, conflicts, readiness)
+- Point them to `output/dashboard.html` for the full visual dashboard
+- Suggest next actions based on what's needed (resolve conflicts, fill coverage gaps, etc.)
+
+$ARGUMENTS

package/templates/commands/witness.md

@@ -0,0 +1,79 @@
+# /witness — Targeted External Corroboration
+
+You are corroborating (or contradicting) a specific claim using an external source. Read CLAUDE.md for sprint context and claims.json for existing claims.
+
+## Process
+
+1. **Parse arguments**: The user provides a claim ID and an external URL.
+   - Example: `/witness p001 https://nodejs.org/api/http.html`
+   - If only a claim ID is given, ask for the URL
+   - If only a URL is given, ask which claim to witness
+
+2. **Read the target claim** from claims.json. Understand what it asserts.
+
+3. **Fetch the external source**: Use web fetch to read the URL. If it's documentation, source code, or an article, extract the relevant content.
+
+4. **Classify the relationship** between the external evidence and the claim:
+   - **Full support** -> external source confirms the claim completely
+   - **Partial support** -> confirms some assertions but adds caveats
+   - **Partial contradiction** -> external source challenges some assertions
+   - **Full contradiction** -> external source directly contradicts the claim
+
+5. **Determine evidence tier** based on source type:
+   - Official docs (*.nodejs.org, docs.*, RFC) -> `documented`
+   - Blog posts, Stack Overflow, tutorials -> `web`
+   - GitHub source code, changelogs -> `documented`
+   - Production metrics, dashboards -> `production`
+
+6. **Create a witness claim**:
+
+```json
+{
+  "id": "w001",
+  "type": "factual",
+  "topic": "<same topic as witnessed claim>",
+  "content": "<what the external source says, in relation to the witnessed claim>",
+  "source": {
+    "origin": "witness",
+    "witnessed_claim": "<target claim ID>",
+    "external_url": "<the URL>",
+    "relationship": "full_support|partial_support|partial_contradiction|full_contradiction",
+    "artifact": null,
+    "connector": null
+  },
+  "evidence": "<tier based on source type>",
+  "status": "active",
+  "phase_added": "<current phase>",
+  "timestamp": "<ISO timestamp>",
+  "conflicts_with": [],
+  "resolved_by": null,
+  "tags": ["witness", "<relevant tags>"]
+}
+```
+
+**Important relationship -> action mapping:**
+- Full/partial support: No `conflicts_with`. The witness corroborates.
+- Partial contradiction: Set `conflicts_with: ["<target claim ID>"]`. Explain the contradiction clearly in content.
+- Full contradiction: Set `conflicts_with: ["<target claim ID>"]`. This becomes a challenge claim effectively.
+
+7. **Run the compiler**:
+   ```bash
+   npx @grainulation/wheat compile --summary
+   ```
+   Report corroboration count changes and any new conflicts.
+
+## Git commit
+
+Stage claims.json.
+
+Commit: `wheat: /witness <target claim ID> — added <witness claim IDs> (<relationship>)`
+
+## Tell the user
+
+- What the external source says about the claim
+- How you classified the relationship (and why, if ambiguous)
+- Whether the witness introduced any conflicts
+- The corroboration count for the witnessed claim
+- Suggest: `/witness` for other uncorroborated claims, `/challenge` if partial contradiction warrants deeper investigation
+
+$ARGUMENTS