@companion-ai/feynman 0.2.0

package/prompts/autoresearch.md

@@ -0,0 +1,63 @@
+---
+description: Autonomous experiment loop — try ideas, measure results, keep what works, discard what doesn't, repeat.
+args: <idea>
+section: Research Workflows
+topLevelCli: true
+---
+Start an autoresearch optimization loop for: $@
+
+This command uses pi-autoresearch.
+
+## Step 1: Gather
+
+If `autoresearch.md` and `autoresearch.jsonl` already exist, ask the user if they want to resume or start fresh.
+
+Otherwise, collect the following from the user before doing anything else:
+- What to optimize (test speed, bundle size, training loss, build time, etc.)
+- The benchmark command to run
+- The metric name, unit, and direction (lower/higher is better)
+- Files in scope for changes
+- Maximum number of iterations (default: 20)
+
+## Step 2: Environment
+
+Ask the user where to run:
+- **Local** — run in the current working directory
+- **New git branch** — create a branch so main stays clean
+- **Virtual environment** — create an isolated venv/conda env first
+- **Docker** — run experiment code inside an isolated Docker container
+- **Cloud** — delegate to a remote Agent Computer machine via `/delegate`
+
+Do not proceed without a clear answer.
+
+## Step 3: Confirm
+
+Present the full plan to the user before starting:
+
+```
+Optimization target: [metric] ([direction])
+Benchmark command:   [command]
+Files in scope:      [files]
+Environment:         [chosen environment]
+Max iterations:      [N]
+```
+
+Ask the user to confirm. Do not start the loop without explicit approval.
+
+## Step 4: Run
+
+Initialize the session: create `autoresearch.md`, `autoresearch.sh`, run the baseline, and start looping.
+
+Each iteration: edit → commit → `run_experiment` → `log_experiment` → keep or revert → repeat. Do not stop unless interrupted or `maxIterations` is reached.
+
+## Key tools
+
+- `init_experiment` — one-time session config (name, metric, unit, direction)
+- `run_experiment` — run the benchmark command, capture output and wall-clock time
+- `log_experiment` — record result, auto-commit, update dashboard
+
+## Subcommands
+
+- `/autoresearch <text>` — start or resume the loop
+- `/autoresearch off` — stop the loop, keep data
+- `/autoresearch clear` — delete all state and start fresh

package/prompts/compare.md

@@ -0,0 +1,16 @@
+---
+description: Compare multiple sources on a topic and produce a source-grounded matrix of agreements, disagreements, and confidence.
+args: <topic>
+section: Research Workflows
+topLevelCli: true
+---
+Compare sources for: $@
+
+Requirements:
+- Before starting, outline the comparison plan: which sources to compare, which dimensions to evaluate, expected output structure. Present the plan to the user and confirm before proceeding.
+- Use the `researcher` subagent to gather source material when the comparison set is broad, and the `verifier` subagent to verify sources and add inline citations to the final matrix.
+- Build a comparison matrix covering: source, key claim, evidence type, caveats, confidence.
+- Generate charts with `pi-charts` when the comparison involves quantitative metrics. Use Mermaid for method or architecture comparisons.
+- Distinguish agreement, disagreement, and uncertainty clearly.
+- Save exactly one comparison to `outputs/` as markdown.
+- End with a `Sources` section containing direct URLs for every source used.

package/prompts/deepresearch.md

@@ -0,0 +1,167 @@
+---
+description: Run a thorough, source-heavy investigation on a topic and produce a durable research brief with inline citations.
+args: <topic>
+section: Research Workflows
+topLevelCli: true
+---
+Run a deep research workflow for: $@
+
+You are the Lead Researcher. You plan, delegate, evaluate, verify, write, and cite. Internal orchestration is invisible to the user unless they ask.
+
+## 1. Plan
+
+Analyze the research question using extended thinking. Develop a research strategy:
+- Key questions that must be answered
+- Evidence types needed (papers, web, code, data, docs)
+- Sub-questions disjoint enough to parallelize
+- Source types and time periods that matter
+- Acceptance criteria: what evidence would make the answer "sufficient"
+
+Write the plan to `outputs/.plans/deepresearch-plan.md` as a self-contained artifact:
+
+```markdown
+# Research Plan: [topic]
+
+## Questions
+1. ...
+
+## Strategy
+- Researcher allocations and dimensions
+- Expected rounds
+
+## Acceptance Criteria
+- [ ] All key questions answered with ≥2 independent sources
+- [ ] Contradictions identified and addressed
+- [ ] No single-source claims on critical findings
+
+## Decision Log
+(Updated as the workflow progresses)
+```
+
+Also save the plan with `memory_remember` (type: `fact`, key: `deepresearch.plan`) so it survives context truncation.
+
+Present the plan to the user and ask them to confirm before proceeding. If the user wants changes, revise the plan first.
+
+## 2. Scale decision
+
+| Query type | Execution |
+|---|---|
+| Single fact or narrow question | Search directly yourself, no subagents, 3-10 tool calls |
+| Direct comparison (2-3 items) | 2 parallel `researcher` subagents |
+| Broad survey or multi-faceted topic | 3-4 parallel `researcher` subagents |
+| Complex multi-domain research | 4-6 parallel `researcher` subagents |
+
+Never spawn subagents for work you can do in 5 tool calls.
+
+## 3. Spawn researchers
+
+Launch parallel `researcher` subagents via `subagent`. Each gets a structured brief with:
+- **Objective:** what to find
+- **Output format:** numbered sources, evidence table, inline source references
+- **Tool guidance:** which search tools to prioritize
+- **Task boundaries:** what NOT to cover (another researcher handles that)
+
+Assign each researcher a clearly disjoint dimension — different source types, geographic scopes, time periods, or technical angles. Never duplicate coverage.
+
+```
+{
+  tasks: [
+    { agent: "researcher", task: "...", output: "research-web.md" },
+    { agent: "researcher", task: "...", output: "research-papers.md" }
+  ],
+  concurrency: 4,
+  failFast: false
+}
+```
+
+Researchers write full outputs to files and pass references back — do not have them return full content into your context.
+
+## 4. Evaluate and loop
+
+After researchers return, read their output files and critically assess:
+- Which plan questions remain unanswered?
+- Which answers rest on only one source?
+- Are there contradictions needing resolution?
+- Is any key angle missing entirely?
+
+If gaps are significant, spawn another targeted batch of researchers. No fixed cap on rounds — iterate until evidence is sufficient or sources are exhausted.
+
+Update the plan artifact (`outputs/.plans/deepresearch-plan.md`) decision log after each round.
+
+Most topics need 1-2 rounds. Stop when additional rounds would not materially change conclusions.
+
+## 5. Write the report
+
+Once evidence is sufficient, YOU write the full research brief directly. Do not delegate writing to another agent. Read the research files, synthesize the findings, and produce a complete document:
+
+```markdown
+# Title
+
+## Executive Summary
+2-3 paragraph overview of key findings.
+
+## Section 1: ...
+Detailed findings organized by theme or question.
+
+## Section N: ...
+
+## Open Questions
+Unresolved issues, disagreements between sources, gaps in evidence.
+```
+
+When the research includes quantitative data (benchmarks, performance comparisons, trends), generate charts using `pi-charts`. Use Mermaid diagrams for architectures and processes. Every visual must have a caption and reference the underlying data.
+
+Save this draft to a temp file (e.g., `draft.md` in the chain artifacts dir or a temp path).
+
+## 6. Cite
+
+Spawn the `verifier` agent to post-process YOUR draft. The verifier agent adds inline citations, verifies every source URL, and produces the final output:
+
+```
+{ agent: "verifier", task: "Add inline citations to draft.md using the research files as source material. Verify every URL.", output: "brief.md" }
+```
+
+The verifier agent does not rewrite the report — it only anchors claims to sources and builds the numbered Sources section.
+
+## 7. Verify
+
+Spawn the `reviewer` agent against the cited draft. The reviewer checks for:
+- Unsupported claims that slipped past citation
+- Logical gaps or contradictions between sections
+- Single-source claims on critical findings
+- Overstated confidence relative to evidence quality
+
+```
+{ agent: "reviewer", task: "Verify brief.md — flag any claims that lack sufficient source backing, identify logical gaps, and check that confidence levels match evidence strength. This is a verification pass, not a peer review.", output: "verification.md" }
+```
+
+If the reviewer flags FATAL issues, fix them in the brief before delivering. MAJOR issues get noted in the Open Questions section. MINOR issues are accepted.
+
+## 8. Deliver
+
+Copy the final cited and verified output to the appropriate folder:
+- Paper-style drafts → `papers/`
+- Everything else → `outputs/`
+
+Use a descriptive filename based on the topic.
+
+Write a provenance record alongside the main artifact as `<filename>.provenance.md`:
+
+```markdown
+# Provenance: [topic]
+
+- **Date:** [date]
+- **Rounds:** [number of researcher rounds]
+- **Sources consulted:** [total unique sources across all research files]
+- **Sources accepted:** [sources that survived citation verification]
+- **Sources rejected:** [dead links, unverifiable, or removed]
+- **Verification:** [PASS / PASS WITH NOTES — summary of reviewer findings]
+- **Plan:** outputs/.plans/deepresearch-plan.md
+- **Research files:** [list of intermediate research-*.md files]
+```
+
+## Background execution
+
+If the user wants unattended execution or the sweep will clearly take a while:
+- Launch the full workflow via `subagent` using `clarify: false, async: true`
+- Report the async ID and how to check status with `subagent_status`

package/prompts/delegate.md

@@ -0,0 +1,21 @@
+---
+description: Delegate a research task to a remote Agent Computer machine for cloud execution.
+args: <task>
+section: Internal
+---
+Delegate the following task to a remote Agent Computer machine: $@
+
+## Workflow
+
+1. **Check CLI** — Verify `computer` or `aicomputer` is installed and authenticated. If not, install with `npm install -g aicomputer` and run `computer login`.
+2. **Pick a machine** — Run `computer ls --json` and choose an appropriate machine. If none are running, tell the user to create one with `computer create`.
+3. **Pick an agent** — Run `computer agent agents <machine> --json` and choose an installed agent with credentials (prefer Claude).
+4. **Create a session** — Use `computer agent sessions new <machine> --agent claude --name research --json`.
+5. **Send the task** — Translate the user's research task into a self-contained prompt and send it via `computer agent prompt`. The prompt must include:
+   - The full research objective
+   - Where to write outputs (default: `/workspace/outputs/`)
+   - What artifact to produce when done (summary file)
+   - Any tools or data sources to use
+6. **Monitor** — Use `computer agent watch <machine> --session <session_id>` to stream progress. Report status to the user at meaningful milestones.
+7. **Retrieve results** — When the remote agent finishes, pull the summary back with `computer agent prompt <machine> "cat /workspace/outputs/summary.md" --session <session_id>`. Present results to the user.
+8. **Clean up** — Close the session with `computer agent close <machine> --session <session_id>` unless the user wants to continue.

package/prompts/draft.md

@@ -0,0 +1,16 @@
+---
+description: Turn research findings into a polished paper-style draft with equations, sections, and explicit claims.
+args: <topic>
+section: Research Workflows
+topLevelCli: true
+---
+Write a paper-style draft for: $@
+
+Requirements:
+- Before writing, outline the draft structure: proposed title, sections, key claims to make, and source material to draw from. Present the outline to the user and confirm before proceeding.
+- Use the `writer` subagent when the draft should be produced from already-collected notes, then use the `verifier` subagent to add inline citations and verify sources.
+- Include at minimum: title, abstract, problem statement, related work, method or synthesis, evidence or experiments, limitations, conclusion.
+- Use clean Markdown with LaTeX where equations materially help.
+- Generate charts with `pi-charts` for quantitative data, benchmarks, and comparisons. Use Mermaid for architectures and pipelines. Every figure needs a caption.
+- Save exactly one draft to `papers/` as markdown.
+- End with a `Sources` appendix with direct URLs for all primary references.

package/prompts/jobs.md

@@ -0,0 +1,16 @@
+---
+description: Inspect active background research work, including running processes and scheduled follow-ups.
+section: Project & Session
+topLevelCli: true
+---
+Inspect active background work for this project.
+
+Requirements:
+- Use the `process` tool with the `list` action to inspect running and finished managed background processes.
+- Use the scheduling tooling to list active recurring or deferred jobs if any are configured.
+- Summarize:
+  - active background processes
+  - queued or recurring research watches
+  - failures that need attention
+  - the next concrete command the user should run if they want logs or detailed status
+- Be concise and operational.

package/prompts/lit.md

@@ -0,0 +1,16 @@
+---
+description: Run a literature review on a topic using paper search and primary-source synthesis.
+args: <topic>
+section: Research Workflows
+topLevelCli: true
+---
+Investigate the following topic as a literature review: $@
+
+## Workflow
+
+1. **Plan** — Outline the scope: key questions, source types to search (papers, web, repos), time period, and expected sections. Present the plan to the user and confirm before proceeding.
+2. **Gather** — Use the `researcher` subagent when the sweep is wide enough to benefit from delegated paper triage before synthesis. For narrow topics, search directly.
+2. **Synthesize** — Separate consensus, disagreements, and open questions. When useful, propose concrete next experiments or follow-up reading. Generate charts with `pi-charts` for quantitative comparisons across papers and Mermaid diagrams for taxonomies or method pipelines.
+4. **Cite** — Spawn the `verifier` agent to add inline citations and verify every source URL in the draft.
+5. **Verify** — Spawn the `reviewer` agent to check the cited draft for unsupported claims, logical gaps, and single-source critical findings. Fix FATAL issues before delivering. Note MAJOR issues in Open Questions.
+6. **Deliver** — Save exactly one literature review to `outputs/` as markdown. Write a provenance record alongside it as `<filename>.provenance.md` listing: date, sources consulted vs. accepted vs. rejected, verification status, and intermediate research files used.

package/prompts/log.md

@@ -0,0 +1,14 @@
+---
+description: Write a durable session log with completed work, findings, open questions, and next steps.
+section: Project & Session
+topLevelCli: true
+---
+Write a session log for the current research work.
+
+Requirements:
+- Summarize what was done in this session.
+- Capture the strongest findings or decisions.
+- List open questions, unresolved risks, and concrete next steps.
+- Reference any important artifacts written to `notes/`, `outputs/`, `experiments/`, or `papers/`.
+- If any external claims matter, include direct source URLs.
+- Save the log to `notes/` as markdown with a date-oriented filename.

package/prompts/replicate.md

@@ -0,0 +1,22 @@
+---
+description: Plan or execute a replication workflow for a paper, claim, or benchmark.
+args: <paper>
+section: Research Workflows
+topLevelCli: true
+---
+Design a replication plan for: $@
+
+## Workflow
+
+1. **Extract** — Use the `researcher` subagent to pull implementation details from the target paper and any linked code.
+2. **Plan** — Determine what code, datasets, metrics, and environment are needed. Be explicit about what is verified, what is inferred, and what is still missing.
+3. **Environment** — Before running anything, ask the user where to execute:
+   - **Local** — run in the current working directory
+   - **Virtual environment** — create an isolated venv/conda env first
+   - **Docker** — run experiment code inside an isolated Docker container
+   - **Cloud** — delegate to a remote Agent Computer machine via `/delegate`
+   - **Plan only** — produce the replication plan without executing
+4. **Execute** — If the user chose an execution environment, implement and run the replication steps there. Save notes, scripts, and results to disk in a reproducible layout.
+5. **Report** — End with a `Sources` section containing paper and repository URLs.
+
+Do not install packages, run training, or execute experiments without confirming the execution environment first.

package/prompts/review.md

@@ -0,0 +1,15 @@
+---
+description: Simulate an AI research peer review with likely objections, severity, and a concrete revision plan.
+args: <artifact>
+section: Research Workflows
+topLevelCli: true
+---
+Review this AI research artifact: $@
+
+Requirements:
+- Before starting, outline what will be reviewed and the review criteria (novelty, empirical rigor, baselines, reproducibility, etc.). Present the plan to the user and confirm before proceeding.
+- Spawn a `researcher` subagent to gather evidence on the artifact — inspect the paper, code, cited work, and any linked experimental artifacts. Save to `research.md`.
+- Spawn a `reviewer` subagent with `research.md` to produce the final peer review with inline annotations.
+- For small or simple artifacts where evidence gathering is overkill, run the `reviewer` subagent directly instead.
+- Save exactly one review artifact to `outputs/` as markdown.
+- End with a `Sources` section containing direct URLs for every inspected external source.

package/prompts/watch.md

@@ -0,0 +1,14 @@
+---
+description: Set up a recurring or deferred research watch on a topic, company, paper area, or product surface.
+args: <topic>
+section: Research Workflows
+topLevelCli: true
+---
+Create a research watch for: $@
+
+Requirements:
+- Before starting, outline the watch plan: what to monitor, what signals matter, what counts as a meaningful change, and the check frequency. Present the plan to the user and confirm before proceeding.
+- Start with a baseline sweep of the topic.
+- Use `schedule_prompt` to create the recurring or delayed follow-up instead of merely promising to check later.
+- Save exactly one baseline artifact to `outputs/`.
+- End with a `Sources` section containing direct URLs for every source used.