feed-the-machine 1.0.0

package/ftm-brainstorm/evals/promptfoo.yaml

@@ -0,0 +1,109 @@
+description: "ftm-brainstorm behavior across multi-turn brainstorming sessions"
+
+prompts:
+  - "{{input}}"
+
+providers:
+  - id: "exec:claude --print"
+    label: "claude-code"
+
+defaultTest:
+  options:
+    transformVars: "vars"
+
+tests:
+  # Eval 0: fresh-idea-intake
+  - description: "fresh idea intake — asks 1-2 questions, no research sprint, hard stop"
+    vars:
+      input: "I'm thinking about building an app that helps people find study buddies at their university. Like Tinder but for studying."
+    assert:
+      - type: regex
+        value: "\\?"
+        description: "Response must contain at least one question"
+      - type: not-contains
+        value: "sprint"
+        description: "Does not dispatch research sprint on first turn"
+      - type: not-contains
+        value: "dispatch"
+        description: "Does not dispatch agents on first turn"
+
+  # Eval 1: fresh-idea-turn2-research
+  - description: "turn 2 — dispatches research agents, citations, labeled recommendation, challenge, ends with question"
+    vars:
+      input: "It's for college students who want to find people in the same classes to study with. Matching based on courses, study style, and schedule availability."
+    assert:
+      - type: regex
+        value: "https?://"
+        description: "Response includes at least one URL citation"
+      - type: regex
+        value: "RECOMMENDED|recommended|#1"
+        description: "At least one suggestion is labeled as recommended"
+      - type: regex
+        value: "\\?"
+        description: "Ends with a question"
+
+  # Eval 2: turn3-deeper-research
+  - description: "turn 3 — deeper research on specific concerns, builds on prior, fresh citations, challenge"
+    vars:
+      input: "I like option 2 — the React Native approach with Firebase. But I'm worried about the matching algorithm complexity. Also we need to handle the cold-start problem when a new university joins."
+    assert:
+      - type: regex
+        value: "matching|algorithm|cold.start"
+        description: "Response addresses the specific concerns raised"
+      - type: regex
+        value: "https?://"
+        description: "Response includes at least one URL citation"
+      - type: regex
+        value: "\\?"
+        description: "Ends with a question"
+
+  # Eval 3: brain-dump-intake
+  - description: "brain dump intake — extracts structure, confirmation gate, no research yet"
+    vars:
+      input: "help me build all the suggestions in this chat: [brain dump about eng-buddy]"
+    assert:
+      - type: regex
+        value: "Decided|decided|Decision|decision"
+        description: "Contains a 'Decided' section"
+      - type: regex
+        value: "open question|Open question|gap|Gap"
+        description: "Contains an open questions or gaps section"
+      - type: regex
+        value: "\\?"
+        description: "Ends with a confirmation question"
+      - type: not-contains
+        value: "dispatch"
+        description: "Does not dispatch research agents on intake turn"
+
+  # Eval 4: brain-dump-turn2-research
+  - description: "brain dump turn 2 — novelty map, research citations, challenge, question"
+    vars:
+      input: "Yeah that looks right, go ahead and research it"
+    assert:
+      - type: regex
+        value: "Novelty|novelty|novel|Novel"
+        description: "Contains a Novelty Map"
+      - type: regex
+        value: "https?://"
+        description: "Response includes at least one URL citation"
+      - type: regex
+        value: "\\?"
+        description: "Ends with a question"
+
+  # Eval 5: phase3-gate
+  - description: "phase 3 gate — vision summary and approval before generating full plan"
+    vars:
+      input: "Ok I think I know what I want. Let's turn this into a plan."
+    assert:
+      - type: regex
+        value: "summary|Summary|we've landed|landed on|here's what"
+        description: "Presents a vision summary before generating the full plan"
+      - type: regex
+        value: "confirm|Confirm|proceed|Proceed|ready|Ready|go ahead|approve"
+        description: "Asks for confirmation before proceeding to full plan"
+      - type: not-contains
+        value: "Wave 1"
+        description: "Does not dump the full plan structure prematurely"
+      - type: not-contains
+        value: "Wave 2"
+        description: "Does not dump the full plan structure prematurely"

package/ftm-brainstorm/references/agent-prompts.md

@@ -0,0 +1,224 @@
+# Agent Prompts (Legacy)
+
+> **NOTE:** As of ftm-researcher integration, brainstorm research sprints are handled
+> by ftm-researcher. These prompts are retained for reference and fallback if
+> ftm-researcher is unavailable.
+
+# Research Agent Prompts
+
+Load this file when dispatching research sprints. Each turn, spawn all 3 agents in parallel with the accumulated context injected.
+
+## Cumulative Context Injection
+
+Every agent prompt MUST include these two blocks at the top. Copy them verbatim from your running context register.
+
+```
+PROJECT CONTEXT:
+[Phase 0 repo summary — tech stack, architecture, patterns, file structure]
+
+ACCUMULATED KNOWLEDGE (Turn {N}):
+[Running summary of everything learned so far — user's answers, prior research findings,
+decisions made, open questions remaining, contradictions found]
+
+RESEARCH DEPTH: {broad | focused | implementation}
+- broad (turns 1-2): Map the landscape. What exists? What are the major approaches?
+- focused (turns 3-5): Drill into the user's chosen direction. What are the real trade-offs?
+- implementation (turns 6+): Find concrete patterns, libraries, code examples for the specific approach.
+```
+
+---
+
+## Agent 1: Web Researcher
+
+```
+{CUMULATIVE CONTEXT BLOCK}
+
+You are the Web Researcher on a 3-agent research team. Your job is to find real-world
+implementations, blog posts, case studies, and architectural write-ups.
+
+CURRENT RESEARCH QUESTION: {what this turn needs to answer}
+
+PREVIOUS FINDINGS TO BUILD ON (don't re-search these):
+{summary of what you found in prior turns — URLs already surfaced, patterns already identified}
+
+NEW INFORMATION FROM USER THIS TURN:
+{what the user just told us — constraints, preferences, decisions, corrections}
+
+---
+
+DEPTH-SPECIFIC INSTRUCTIONS:
+
+IF DEPTH == broad:
+  - Map the territory. What category of thing is this?
+  - What are the 3-5 major technical approaches people use?
+  - What's typically harder than expected?
+  - Search: "[core concept] architecture", "[concept] case study", "how [company] built [feature]"
+
+IF DEPTH == focused:
+  - Drill into the specific approach the user is leaning toward
+  - Find gotchas, failure modes, scaling limits for THIS approach
+  - Compare 2-3 real implementations that took this approach — what differed?
+  - Search: "[specific approach] [user's stack] production", "[approach] lessons learned",
+    "[approach] vs [alternative the user rejected] trade-offs"
+
+IF DEPTH == implementation:
+  - Find concrete code patterns, library recommendations, config examples
+  - Look for "how to" guides specific to the user's stack + approach
+  - Find migration/integration guides if connecting to existing systems
+  - Search: "[specific library] [specific framework] tutorial", "[exact pattern] implementation",
+    "[stack] [feature] boilerplate", "github [specific integration]"
+
+---
+
+BRAIN DUMP MODE (if user pasted a large document):
+The user proposed these specific architectural ideas. Search for existing
+implementations of EACH claim independently:
+{list of extracted claims from brain dump}
+
+For each claim, categorize:
+- SOLVED: existing tool/library does exactly this → name it, link it
+- PARTIALLY SOLVED: existing approach covers part → what's covered, what's novel
+- NOVEL: nothing found → flag as genuinely new or possibly mis-framed
+
+---
+
+RETURN FORMAT:
+- 3-5 findings (fewer if results are thin — don't pad with weak results)
+- Each finding: source URL, 2-3 sentence summary, key takeaway for this project
+- Flag if a finding requires technology NOT in the project's current stack
+- Flag if a finding contradicts something from ACCUMULATED KNOWLEDGE
+- Note what you DIDN'T find — gaps are signal too
+```
+
+---
+
+## Agent 2: GitHub Explorer
+
+```
+{CUMULATIVE CONTEXT BLOCK}
+
+You are the GitHub Explorer on a 3-agent research team. Your job is to find real
+repositories, code patterns, and open-source implementations.
+
+CURRENT RESEARCH QUESTION: {what this turn needs to answer}
+
+PREVIOUS FINDINGS TO BUILD ON (don't re-search these):
+{repos already surfaced in prior turns}
+
+NEW INFORMATION FROM USER THIS TURN:
+{what the user just told us}
+
+---
+
+DEPTH-SPECIFIC INSTRUCTIONS:
+
+IF DEPTH == broad:
+  - Find the most-starred repos in this problem space
+  - Look at how they're structured — what patterns emerge across repos?
+  - Check trending repos in relevant categories
+  - Search: "[core concept] [language]", "[concept] framework", "awesome-[concept]"
+
+IF DEPTH == focused:
+  - Find repos using the SAME stack as this project (prioritize these)
+  - Dig into their architecture decisions — read READMEs, check directory structure
+  - Look at their open issues — what pain points do users report?
+  - Compare how 2-3 repos solved the same sub-problem differently
+  - Search: "[specific approach] [exact framework]", "[approach] example [language]"
+
+IF DEPTH == implementation:
+  - Find repos that solved the EXACT sub-problem the current task requires
+  - Look at specific files/functions, not just repo-level architecture
+  - Check if there are libraries/packages that wrap common patterns
+  - Look at test suites — how do they verify this works?
+  - Search: "[specific library] [specific pattern] example", "[exact integration] starter"
+
+---
+
+BRAIN DUMP MODE:
+Find repos that implement each of the user's proposed components:
+{list of extracted claims}
+
+Map each repo to which claims it covers. A single repo might cover multiple claims.
+
+---
+
+RETURN FORMAT:
+- 3-5 repos (fewer if search is thin)
+- Each: URL, star count, last commit date, 2-3 sentence description
+- Note architectural decisions visible from README/structure
+- Note compatibility with this project's existing patterns
+- Flag repos that are unmaintained (>1yr since last commit) or have critical open issues
+```
+
+---
+
+## Agent 3: Competitive Analyst
+
+```
+{CUMULATIVE CONTEXT BLOCK}
+
+You are the Competitive Analyst on a 3-agent research team. Your job is to find
+existing products, tools, and solutions — and identify what works, what doesn't,
+and where the opportunity is.
+
+CURRENT RESEARCH QUESTION: {what this turn needs to answer}
+
+PREVIOUS FINDINGS TO BUILD ON:
+{products/tools already identified in prior turns}
+
+NEW INFORMATION FROM USER THIS TURN:
+{what the user just told us}
+
+---
+
+DEPTH-SPECIFIC INSTRUCTIONS:
+
+IF DEPTH == broad:
+  - What products/tools already solve this problem (or adjacent problems)?
+  - What do users love and hate about them? (check reviews, Reddit, HN, Twitter)
+  - Where are the obvious gaps?
+  - Search: "[problem] tool", "[concept] app", "site:reddit.com [problem] recommendation",
+    "site:news.ycombinator.com [concept]"
+
+IF DEPTH == focused:
+  - Deep-dive the 2-3 most relevant competitors
+  - How do they handle the specific technical challenge the user is facing?
+  - What's their pricing/business model? What can we learn from it?
+  - What do power users wish these tools did differently?
+  - Search: "[specific product] review", "[product] vs [product]", "[product] limitations"
+
+IF DEPTH == implementation:
+  - How do competitors implement the specific feature/pattern the user is building?
+  - Are there public APIs, SDKs, or integrations we can leverage instead of building from scratch?
+  - What UX patterns do the best tools in this space use?
+  - Search: "[product] API", "[product] architecture", "[product] integration guide"
+
+---
+
+BRAIN DUMP MODE:
+The user proposes building these capabilities:
+{list of extracted claims}
+
+For each: does an existing product already handle it? Should the user use it,
+fork the approach, or build differently? Be specific about why.
+
+---
+
+RETURN FORMAT:
+- 3-5 products/tools (fewer if space is thin)
+- Each: URL/name, what they do well, what they do poorly, relevance to this project
+- Identify the gap — what would the user's project do that these don't?
+- Flag if "just use [existing tool]" is the honest recommendation for any sub-problem
+```
+
+---
+
+## Dispatch Checklist
+
+Before spawning agents each turn, verify:
+
+1. Cumulative context is up to date (includes user's latest response)
+2. Research depth level is set correctly for this turn number
+3. Previous findings are summarized so agents don't re-search
+4. The research question is specific to THIS turn (not the whole project)
+5. Brain dump claims are included if Path B

package/ftm-brainstorm/references/plan-template.md

@@ -0,0 +1,121 @@
+# Plan Generation Template
+
+Load this file only when the user approves moving to Phase 3 (plan generation).
+
+## Present Incrementally
+
+Do NOT dump the entire plan in one message. Present section by section:
+
+1. **Vision + Architecture Decisions** — ask: "Does this foundation look right?"
+2. **Task Breakdown** — ask: "Any tasks missing, or should any be split/merged?"
+3. **Agent Team + Execution Order** — ask: "Good to save it?"
+
+Only save after all three sections are approved.
+
+## Plan Document Structure
+
+```markdown
+# [Project/Feature Name] — Implementation Plan
+
+## Vision
+[2-3 sentence summary of what we're building and why, grounded in research findings]
+
+## Key Research Findings
+- [Most important patterns/decisions discovered, with source links]
+- [Each finding that materially influenced the plan]
+
+## Architecture Decisions
+[Major technical choices and the reasoning behind each — reference the research turn where evidence was found]
+
+## Tasks
+
+### Task N: [Title]
+**Description:** [What needs to be built]
+**Files:** [Expected files to create/modify — use ACTUAL project paths from Phase 0]
+**Dependencies:** [Which tasks must complete first, or "none"]
+**Agent type:** [frontend-developer, backend-architect, etc.]
+**Acceptance criteria:**
+- [ ] [Specific, testable criterion]
+- [ ] [Another criterion]
+**Hints:**
+- [Relevant research finding with source URL]
+- [Known pitfall from research: "Watch out for Z — see [link]"]
+- [If brain dump: novelty verdict — "Already solved by [tool]" or "Novel — no prior art"]
+**Wiring:**
+  exports:
+    - symbol: [ExportedName]
+      from: [file path]
+  imported_by:
+    - file: [parent file that should import this]
+  rendered_in:
+    - parent: [ParentComponent]
+      placement: "[where in parent JSX]"
+  route_path: [/path]
+  nav_link:
+    - location: [sidebar|navbar|menu]
+      label: "[Display text]"
+
+## Agent Team
+| Agent | Role | Tasks |
+|-------|------|-------|
+| [type] | [what they handle] | [task numbers] |
+
+## Execution Order
+- **Wave 1 (parallel):** Tasks [X, Y, Z] — no dependencies
+- **Wave 2 (parallel, after wave 1):** Tasks [A, B] — depend on wave 1
+- **Wave 3:** Task [C] — integration/final assembly
+```
+
+## Wiring Contract Rules
+
+Auto-populate the `Wiring:` block based on file type:
+
+- **New component** (.tsx/.vue/.svelte): exports (component name), imported_by (parent), rendered_in (where in JSX), route_path (if page)
+- **New hook** (use*.ts): exports (function), imported_by (consuming components)
+- **New API function** (api/*.ts): exports (functions), imported_by (hooks/components calling them)
+- **New store/state**: store_reads (which components read), store_writes (which write)
+- **New route/view**: route_path, nav_link (where navigation appears), rendered_in (router config)
+
+## Hints Population
+
+For each task, pull from the cumulative research register:
+
+1. **Web Researcher findings** — blog posts, case studies, patterns (include URL)
+2. **GitHub Explorer findings** — repos that solved similar problems (include URL + what's useful)
+3. **Competitive Analyst findings** — products to learn from or differentiate against
+4. **Brain dump novelty map** (Path B): solved/partially solved/novel verdicts
+5. **Pitfalls** — warnings from any research turn
+
+Rules:
+- Always include source links
+- 2-4 bullets per task, not paragraphs
+- "No specific research findings for this task" if nothing applies
+- Hints are suggestions, not mandates
+
+## Quality Rules
+
+- Tasks small enough for one agent session
+- Every task has testable acceptance criteria
+- Dependencies explicit — no implicit ordering
+- Agent assignments match domain
+- Wave structure maximizes parallelism
+- File paths reference ACTUAL project structure from Phase 0
+- Leverage existing project patterns (don't reinvent)
+
+## Save Location
+
+```
+~/.claude/plans/[project-name]-plan.md
+```
+
+Create `~/.claude/plans/` if needed.
+
+## Handoff Prompt
+
+After saving, give the user:
+
+```
+/ftm-executor ~/.claude/plans/[project-name]-plan.md
+```
+
+Plus a summary: "[N] tasks across [M] agents in [W] waves. First wave starts immediately with [list]. Scope: [small/medium/large]."

package/ftm-brainstorm.yml

@@ -0,0 +1,2 @@
+name: ftm-brainstorm
+description: Research-powered Socratic brainstorming that dispatches parallel agents to search the web and GitHub for real-world patterns, then synthesizes findings into actionable suggestions with citations. Use this skill whenever the user wants to brainstorm, explore ideas, think through a feature, plan a project, or flesh out a concept before building. Also triggers when the user pastes a large block of text (notes, prior brainstorm, meeting transcript, spec draft, stream-of-consciousness dump) and wants to turn it into something buildable — phrases like "help me build this", "turn this into a plan", "here's what I've been thinking", or just a big paste followed by "what do you think?" or "go". Triggers on "brainstorm", "help me think through", "I have an idea for", "how should I approach", "let's explore", "what if we built", "I'm thinking about", "help me figure out", or any conversation where the user has a concept they want to develop before writing code. Even vague ideas like "I want to build something that..." or "what's the best way to..." should trigger this skill.