Repository navigation
Help EN
🇷🇺 Русский: Help
Full user guide.
The agent is not a program and not a bot — it is a repository folder that you open in an LLM environment
(Claude Code, Cursor, Codex, OpenCode, Windsurf, Copilot). The environment reads AGENTS.md (rules and process),
knowledge/ (knowledge sets by category: strategy · economics · product · UX · data · platforms · Gen AI;
techniques only — no brands), while the tool pfs keeps
the research "bookkeeping": sources, claims, checks, decisions, cost.
Four layers to distinguish:
| Layer | Where | What is inside |
|---|---|---|
| Rules and process | AGENTS.md |
12-step process, evidence rules, command cheat sheet |
| Methods | knowledge/methods/ |
111 method cards (RU) + 111 EN mirrors (full bilingual base): unit economics, A/B testing, platforms, GenAI, etc. |
| Task materials | projects/<slug>/ |
sources, claim registry, documents, Excel models, state |
| Tools | python3 -m tools.pfs … |
CLI and MCP server with guarantees: no fact without a source |
The agent drives the process and calls pfs itself. Your job: answer questions and decide at three checkpoints —
brief (step 0), option choice (step 6), decision approval (step 10).
You need: Python 3.9+ (no packages), git, any environment above. Optional: pdftotext (poppler) or
pip install pypdf for PDF sources.
git clone https://github.com/Fighter90/product-factory-strategist-agent.git
cd product-factory-strategist
python3 -m tools.pfs doctor # environment check
python3 -m unittest discover -s tests # self-check (260 tests)Agent materials (
knowledge/— RU/EN knowledge maps, templates, rubrics) live in a separate public repository product-factory-strategist-base are pulled automatically by./scripts/install.sh— together with the site; the install verifies the result. Without thempfs doctorhints; to update the materials runcd knowledge && git pull.
doctor reports install mode (editable/venv/source), package version, pfs path (which), PATH health, projects dir location, Python version, pdftotext/pypdf availability, an HTTPS check against three domains (TLS chain certifi → truststore → SSL_CERT_FILE; on failure it prints the «Install Certificates.command» / pip install certifi hint), number of knowledge cards, active project.
CLI needs no API keys. Keys (e.g., Linear API) go into .env — it is git-ignored.
-
Open the repo folder in your environment (in Claude Code: run
claudeinside the folder). -
Write the task in plain language, like a product director would:
Our paid anti-spam service is losing subscribers. What do we do with the product, and what do we tell customers?
-
The agent will: create a project, ask 1–3 clarifying questions, build a research plan, collect sources, propose options and attack them with a red team, synthesize strategies, and show progress as:
Step 2/12 · research · sources S001–S009 collected · next: discovery -
At any moment you can say: "stop" — pause; "clarify: …" — adjust the task; "redo section X" — rework only the affected part; "build the six-pager" — get the committee report.
-
Break / new chat: open a new chat in the same folder — the SessionStart hook feeds the agent its state (
pfs statusdoes the same manually). Finished steps are never repeated.
| # | Step | What happens | Your role |
|---|---|---|---|
| 0 | intake | Clarify question, goal, constraints, data → 00_brief.md
|
approve the brief |
| 1 | sources | Register your files and public sources → sources/S###.md
|
provide materials |
| 2 | research | Plan from decision-changing questions; search; calculations; interviews | answer questions |
| 3 | discovery | Personas, JTBD, user alternatives → "Segments" section in 02 | answer discovery block |
| 4 | situation | Known/unknown, contradictions → 02_situation.md
|
— |
| 5 | options | ≥3 distinct options + objections (red team) → 03_options.md
|
— |
| 6 | choice | Comparison and recommendation | you pick |
| 7 | strategy | Product + communication strategies → 04/05_*.md
|
— |
| 8 | validation | Test plan: metric, baseline, duration, counter-metrics → 06_validation_plan.md
|
— |
| 9 | review |
pfs check + rubric review → 07_quality_review.md; lock the verdict: pfs review lock
|
— |
| 10 | decision | Grounds, owners, metrics, commitments → decisions.jsonl
|
you approve |
| 11 | monitoring | Deadlines, new data, revision of affected conclusions | receive reminders |
After step 9 (review) you can build the six-pager with Excel attachments (section 7) — a committee-ready report in the FAQ-1…FAQ-6 growth-strategy reference structure (detailed format spec — knowledge/templates/SIX_PAGER_PROMPT.md).
Full list: python3 -m tools.pfs --help. The agent runs most of this itself — the commands are here to check
state or act manually.
pfs new "Title" "Request verbatim" # create a project
pfs list # list projects
pfs use <slug> # make a project active
pfs status [--brief] # where we stopped, what's next, costThe active project is stored in projects/.active: switch with pfs use <slug> before working on another
project — no need to export environment variables (the env override exists for tests only, via PFS_PROJECTS_DIR).
File paths in source add, docx and media add resolve first against the project directory
(projects/<slug>/…), falling back to the current directory; the resolved path is printed in the output.
pfs next # "what to decide now": current step, human checkpoint,
# overdue commitments, grounds sources unchecked for 180+ days
# (with a ready `pfs source refresh S###` command), reviews due
# (past and within 14 days), open questions;
# after review without SIX_PAGER.md — committee package
# build first (calc scaffold → calc all → export --six-pager)
pfs step strategy in_progress --note "…" --next "…" # statuses: in_progress, done
pfs ask "Question?" --options "A,B,C" # pause: agent waits for your answer
pfs answer "Option B"
pfs question "Open question" [--close]
pfs questions strategy # question blocks per step (step | block) for strategy tuning; use `pfs ask` to pose to the directorpfs source add https://example.com/report # web page: fetched, cleaned, deduped by URL/SHA-256
pfs source add ~/Downloads/report.pdf # PDF/DOCX/XLSX/CSV/image
pfs source add sources/raw/report.md # relative path: project directory first
# (projects/<slug>/…), then cwd; resolved path is printed
pfs source add --text-file doc.md --url https://example.com/report --origin excerpt --published 2025-06-01 # excerpt mode:
# origin=excerpt, claim strength capped at C
# until the original is re-verified by refresh
# (incl. inferences via derived_from — check warns)
pfs source fetch <url> --title "…" # unreachable URL (403/SSL/JS/timeout) in one call:
# direct request → r.jina.ai → web.archive.org;
# origin: public on direct success, excerpt on fallback;
# channels validate content: a 404-page body with HTTP 200
# skips the channel; if all channels return 404, the source
# registers with a "broken" mark and a warning (pfs check warns)
pfs source fetch <url> --via-browser # JS-rendered page via Playwright (if installed);
# without it — install command; on full failure use an excerpt: add --origin excerpt
pfs source add interview.md --origin interview # your interview (no personal data)
pfs source add transcript.md --origin synthetic # AI respondent: hypotheses only
pfs source list # the source registry
pfs source show S003 # a source card
pfs source refresh S003 # refresh a web source: sha256 delta → old version backed up
Edit a source without touching jsonl: `pfs source update S### --title "…" --origin … --note "…" --text-file <new file>` — text is replaced with a backup in sources/raw/.
# to raw/<S###>_old_<sha8>.txt → impact on claims built on it;
# a direct answer from the original clears the excerpt markRules: project domains (project.json → allowed_sources) are checked before the request; secret files
(.ssh, keys, .env) are rejected; instruction-like phrases in texts are flagged and never executed.
pfs claim add "Market is 40 B RUB" --kind fact --source S002 --grade B
pfs claim add "People will pay for family protection" --kind hypothesis --source S005
pfs claim add "Therefore focus on families" --kind inference --from C003,C010
pfs claim add-batch claims.jsonl # register a batch from JSONL (text/kind/source/grade/quote/from):
# one line = one claim; an invalid line cancels the whole
# batch; duplicates by text are skipped
pfs claim list [--kind fact] [--all]
pfs claim retract --id C005 --reason "methodology error"
pfs claim supersede "Market is 45 B RUB" --id C005 --reason "new report" [--source S009]
pfs claim rebase [--id C012] # redirect conclusions to the replacements of their grounds
pfs claim retag --from C003 --to C059 # renumber [C###] tags across all outputs in one command,
# validated before writing and journalledKinds: fact (needs a source; synthetic material never counts as one), hypothesis, forecast,
assumption, inference (only from other C###). Evidence strength: --grade A…D.
The registries
projects/*/{claims,sources,decisions}.jsonlandstate.jsonare edited only via pfs: direct writes (sed -i, redirect, Edit) are blocked by opencode.json permissions and the pre_guard.py PreToolUse hook, with a hint pointing to the right command. Reading stays inside the repository; user materials count only when explicitly handed over. Reads outside the repo (Read/Grep/Glob, and in Bash any~/…path outside the repo) ask the human first; in OpenCode the same role is played by theexternal_directorypermission. Excerpts live inprojects/<slug>/sources/raw/;pfs source add --text-filecopies the file there itself, marking files that came from outside the project.
pfs check --strict # quality gate: untagged numbers, dead links, structure (--json for machine output)
Numbers with a unit need a [C###]/[S###] tag on the same line. The unit list lives in one
place — `config/quality_gate.json → number_regex` (EN: %, pp, ₽/RUB, mln, bn, k, $, times,
users/subscribers/customers, weeks/months/days, years, companies; mirrors RU) — the rule:
"any number with any listed unit requires a tag". Line exemptions: `exempt_line_markers`
(table separators, "Goal:", "Observation window:", `<!-- no-tag -->`).
# numeric cross-check (PRO-26): numbers of active claims vs numbers in the
# titles of their sources, and quote numbers vs sources/S###.md text —
# a mismatch ("claim says 19, title says 17") adds a warning with the C###/S### pair
pfs review lock # lock the review verdict: registry snapshot (sha256 of claims/sources and docs 00–07)
# into outputs/.review_state.json; registry edits after the lock add a
# "review verdict stale — the registry changed after the review; re-run evidence-auditor"
# warning to check/status/export; re-lock after the re-review
pfs gap list # research gaps from 02 "What we don't know": numbers and status (open/partial/closed)
pfs gap close 3 --claim C069 --note "how it was closed"
# mark a gap closed SYNCHRONOUSLY: the 02 row + the 01 item / question status;
# pfs check warns if 02 says "closed" but the 01 line still says "open"
pfs impact C005 # what a change affects: conclusions → document lines → decisionspfs decision add --title "…" --decision "…" --owner "CPO" --grounds C001,C007 --metric "M1 retention: 38% -> 45% @2027-01-01" --review 2027-01-01 --trigger "M1 < 40% for two months" --commit "Launch pilot|PM|2026-12-01"
pfs decision due # what to decide now: overdue commitments, stale grounds, sources
# unchecked for 180+ days — with a ready `pfs source refresh S###` command
pfs decision done --id D001 --commitment K1
pfs decision list # the decision registry
pfs decision status --id D001 # decision status (alternatives: list, rebase)pfs data profile events.csv [--sheet Sheet1] --save profile # table profile: types, gaps, dupes, periods
pfs data cohort events.csv --user user_id --date dt --save cohorts # cohort retention
pfs data funnel events.csv --steps visit,signup,pay --user user_id # funnel over an event log
# or per-step flag columns; --date validates step order
pfs data stats events.csv --col revenue [--group segment] # descriptive stats for a column
# (n, mean, median, percentiles, 95% CI), optionally per grouppfs interview guide --persona "Parent of 7–12" [--topic "…"] # interview question outline in interviews/
pfs interview save transcript.md --persona "…" --title "…" # AI-respondent transcript/summary
# → source with origin synthetic (hypotheses only)
pfs media add screenshot.png --desc "what is visible" # media within declared limits: the file is copied
# to sources/raw and its description — "only what is visible/audible" —
# becomes a source; interpretations are separate claims
# (path: project directory → cwd)
pfs ux scaffold S003 --focus "onboarding" # UX scaffold of 10 heuristics in analysis/ux_<S###>.md
# with the rule "conclusions only from the source material"pfs calc scaffold # calcs.json skeleton from 02/04/06/07: numbers carry
# C/S tags in _notes; misses become null + _hints
pfs calc all # 4 workbooks → projects/<slug>/outputs/attachments/
pfs calc unit-econ | growth | cohort | marketEach workbook: an Input sheet (editable parameters) + calculation sheets built on formulas — Excel
recalculates on open. Parameters come from projects/<slug>/calcs.json; the skeleton is generated
by pfs calc scaffold (manual filling — only the null fields):
{
"unit_econ": {"arpu": 199, "vc_share": 0.2, "cac": 600, "churn_month": 0.08,
"note": "values from C010, C014; replace modeled ones — see open questions"},
"growth": {"mau_start": 100000, "mau_growth_month": 0.05, "conv_order": 0.02,
"orders_per_active": 1.5, "aov": 3500, "take_rate": 0.08, "margin": 0.6},
"cohort": {"sizes": [5000, 6000], "retention": [1.0, 0.55, 0.42]},
"market": {"pam": 120000000000, "tam_share": 0.6, "sam_share": 0.3, "som_share": 0.05}
}Anything missing falls back to the example in tools/pfs/calc.py: DEFAULTS marked "EXAMPLE"
(null fields from the skeleton too). Number ranges ("60–70%") are taken as the midpoint by the
skeleton; a null inside lists (sizes/retention) is filled from the example at its own position,
while a null in the tail beyond the example truncates the list right there — positions never
shift, cohort 8's size never becomes cohort 7's. Trace every value to C###/S###: the source lives
in the registry, the link goes into note; numbers found by the scaffold carry their tag in the
section's _notes, and a re-run preserves _notes/_hints of values already set.
pfs finish # full package in one chain: pfs check → calc all → REPORT →
# SIX_PAGER → registry snapshot → DOCX → deck → "built + stale" summary;
# any check error stops the build (same as pfs check --strict); re-running is idempotent
pfs finish --no-deck # same without the HTML deck
pfs finish --en # + EN draft of the six-pager: SIX_PAGER_EN.md + DOCX (tool skeleton in
# English; document sections are marked "[RU source — translate]"; check
# compares RU↔EN tags and warns when the EN draft lags behind RU)
pfs export # REPORT.md: all documents + appendices A–E
# registry snapshot in outputs/.export_state.json; if claims/sources/Excel changed after the build — ⚠ on `pfs status` and on the next export
pfs export --six-pager # SIX_PAGER.md (FAQ-1…6) + Excel rebuild
pfs export --six-pager --en # + EN skeleton: SIX_PAGER_EN.md — same structure/numbers/tags, English skeleton,
# document sections marked "[RU source — translate]" (translation is the agent's job)
pfs export --six-pager --no-calcs # rebuild text without regenerating workbooks
pfs export --deck # 16:9 HTML deck from SIX_PAGER.md
pfs docx <file.md> [--out] # Markdown → Word, dependency-free (path: project directory → cwd; docx versions of HELP/README live in docs/docx/)
pfs ab --hypothesis "…" --metric "…" # A/B test design: proxy, guardrail, MDE, traffic (PRO-71)Six-pager structure: FAQ-1 market & competitors · FAQ-2 segments & personas · FAQ-3 initiatives & objections · FAQ-4 tactics · FAQ-5 plan & validation · FAQ-6 success metrics · Excel attachments table. Full evidence — REPORT.md.
pfs kb search "cohort retention analysis" # BM25 search over method cards
pfs kb show M-unit-economics # show a card
pfs kb index # rebuild INDEX.md, validate linkspfs models # which model solves which task (config/models.json)
pfs models pick red_team # plan for a task
pfs models use cursor-mixed # profile for another environment
pfs models sync # write models into Claude Code subagents
pfs cost [--transcript session.jsonl] [--session ses_e43_session.json] [--window] [--plan-month 18] # cost from Claude Code transcripts or an OpenCode session (session.json; plan providers like zai-coding-plan report $0 actual cost, a «subscription plan» mark and a non-zero API-price equivalent from config/pricing.json, plus a per-step breakdown, per-model cache tokens, session time and retries); --plan-month <USD/mo> — your subscription tier, shows the project's share of the subscription separately; --session <file> without --transcript is an alias with auto-detection in the project root (*_session.json / *.jsonl; no value — the newest one; registry claims/sources/decisions/log.jsonl are not treated as transcripts); elsewhere:
pfs log "Manual edit" --usd 0.8 --human-minutes 15pfs doctor # environment + source registry integrity: duplicate IDs/URLs, record without file, orphan file (PRO-34)The agent offloads the main dialogue to subagents: researcher (reading long sources), red-team
(attacking options), evidence-auditor (rubric review), data-analyst (calculations, including pfs calc),
synthetic-respondent (AI respondents — hypotheses only), comms-strategist, ux-analyst, router.
Six-pager Excel models are built in the background: while pfs calc runs, you can keep chatting.
The model per task is selected via config/models.json (cheap models for classification and extraction,
strong ones for synthesis and strategy); escalation — pfs models escalate.
Deep research — Feynman (feynman.is, skill deep-research): feynman deepresearch/lit/compare with a provenance
file. Transfer rules: provenance → primary sources registered as S###; numbers are facts only from primary sources;
the report itself is origin agent — hypotheses only. Telemetry: FEYNMAN_TELEMETRY=off;
OPENALEX/SEMANTIC_SCHOLAR_API_KEY in .env.
Alongside the process the environment loads skills — packaged instruction sets (101 in total, in three groups plus integrations):
-
Base (13) — one per process step:
intake,research,situation,options,strategy,validation-plan,decision-support,six-pager, etc. - Product-skills (27) — domain packs around the process: segments, JTBD, unit economics, growth, risks.
-
Personal library (57) — imported packs by category:
-
Design —
design-ui,refero-design,frontend-design,claudable-landing,make-interfaces-feel-better,emil-design-eng,web-design-guidelines; -
Marketing —
ads,ad-creative,seo-audit,ai-seo,cro,pricing,offers,emails,launch,content-strategy,competitors,analytics,programmatic-seo,customer-research,marketing-psychology,prospecting…; -
Science and data —
research-lookup,literature-review,scientific-writing,scientific-critical-thinking,peer-review,statistical-analysis,hypothesis-generation,exploratory-data-analysis,transcribe,watch; -
Docs/media —
pdf,docx,pptx,xlsx,markitdown,officecli,generate-image,video,infographics,matplotlib,scientific-visualization; -
Meta —
balanced,find-skills.
-
Design —
-
Integrations — cross-process behaviors:
premortem(failure pre-mortem),sdd(development discipline),deck(six-pager presentation),ph-trends(Product Hunt trends → product application).
How skills are invoked:
- Automatically — by description trigger: the task matches, the skill loads.
-
Explicitly — say
use skill <name>: <task>(example:use skill deck: build the deck from the six-pager). -
In-process, by step —
pfs stepprints the step's knowledge cards; atoptionsexpensive decisions additionally getred-team; atdecision—decision-supportpluspremortemAFTER the D### draft and BEFORE your approval; atresearch—deep-researchfor hard pages.
Examples of requests: "run a premortem on D001", "use skill deck: build the deck".
Precedence rule: on conflict, the knowledge/ methodology wins over a skill's own procedure.
Full registry of skills — SKILLS.md.
- Wait until documents 02/03/04/06 exist (steps situation…validation).
- Tell the agent "build the six-pager" — it fills
calcs.jsonfrom the claim registry (every value tied to a C###), runs calculations in a background subagent, and assembles the report. - You get:
outputs/SIX_PAGER.md+outputs/attachments/*.xlsx(4 workbooks). - Open Excel: the Input sheet — replace assumptions with actual figures; formulas recalculate.
- Numbers in text and Excel must match: after editing
calcs.json, rerunpfs calc allandpfs export --six-pager.
| Event | What happens automatically |
|---|---|
| Chat start | feeds the agent project state and "what to decide now" |
| WebFetch | blocks domains outside project allowed_sources before the request |
| After tools | writes the log, scans web answers for instruction-like phrases, auto-checks edited documents |
| Answer end | counts session cost (idempotent) |
Hooks never crash the session: errors go to .claude/hooks/hook_errors.log.
To check that "the agent handles new tasks", run the whole 12-step chain on a fresh clone:
scripts/e2e_opencode.sh en qa/tasks/antispam-en.md # 3 tasks × ru/en in qa/tasks/
# in OpenCode the same: the /pfs-e2e command — ru | en | allThe script does everything itself: a fresh clone into a temp directory → opencode run --auto --format json in autopilot mode (the agent answers its own pfs ask questions, works until
pfs finish, no "continue" nudges) → log parsing → report qa/E2E-<date>-<task>-<lang>.md: steps,
tool calls, errors, tokens and cost, time, pfs check --strict and six-pager build results,
number of stops, reply language consistency ("Язык реплик" row with docs/demo/comparison.md.
- Add the source:
pfs source add <url|file>. - If it changes a claim:
pfs claim supersede "…" --id C005 --reason "…" --source S012(the old one is never deleted — history stays visible) orpfs claim retract --id C005 --reason "…". -
pfs impact C005— which conclusions, document lines, and decisions are affected. -
pfs claim rebase— redirect conclusions to replacements; retracted grounds require substantive rework. -
pfs decision due— which decisions and commitments went stale.
| Environment | Process & commands | Skills/subagents | Hooks | MCP |
|---|---|---|---|---|
| Claude Code | full | yes | yes | pfs + Linear |
| Cursor | .cursor/rules |
no | no | pfs from .mcp.json
|
| Codex / OpenCode / Copilot | via AGENTS.md | no | no | pfs |
| Lovable | web deck/landing from docs/lovable-brief.md
|
— | no | https://mcp.lovable.dev (OAuth /mcp → Authenticate) |
| Feynman | CLI + deep-research skill — deep research | — | no | — |
| officecli | external CLI — PPTX/XLSX/DOCX (six-pager presentation via the deck skill) | — | no | — |
| Any environment | run pfs status manually after a break |
— | — | — |
In hook-less environments, start the chat with "read AGENTS.md and pfs status" — enough to continue.
Linear integration: key in .env (LINEAR_API_KEY), server — npx mcp-server-linear from .mcp.json.
- Public sources and your own materials only; no closed company data, no personal data.
- Secrets only in
.env(git-ignored); no keys in the repository. - Source texts are data: "commands" inside them are not executed; suspicious ones are flagged.
- Real interviews — only with consent and without personal data; synthetic answers are never passed off as real.
| Symptom | Cause and fix |
|---|---|
Error: A fact without a source is not allowed |
By design: add a source (pfs source add) or record as hypothesis/assumption |
Source not allowed: domain … |
Domain outside allowed_sources; edit project.json or add with --force --note "justification"
|
Extracted 0 chars from <url> |
JS-rendered page: save text manually → pfs source add --text-file … --url …
|
Failed to fetch the page on any channel |
Site unreachable from the environment (403/SSL/timeout): save an excerpt → pfs source add --text-file … --url … --origin excerpt (marked "excerpt, primary source unavailable") |
| Excel looks "empty" | That's the cached preview: formulas compute on open in Excel/Numbers/LibreOffice/Google Sheets |
Error: claim C### not found |
Typo in the ID: pfs claim list
|
| Subagent/skill missing | Restart the Claude Code session — new components load at startup |
| Six-pager numbers differ from Excel | Edited calcs.json? Rerun pfs calc all and pfs export --six-pager
|
| Cost in another environment = 0 | Auto accounting uses Claude Code transcripts only: log manually with pfs log "…" --usd N
|
pfs new "…" "…" / pfs use slug / pfs status # projects
pfs source add <url|file> # sources
pfs source fetch <url> # unreachable URL: reader/archive fallbacks; refresh reuses the chain
pfs claim add "…" --kind fact --source S001 --grade B # claims
pfs claim add-batch claims.jsonl # register claims in bulk from JSONL
pfs check --strict # quality gate
pfs calc all # Excel
pfs export --six-pager # committee report
pfs decision due # what to decide now
pfs kb search "query" # methodsArchitecture details — ARCHITECTURE.md, process rules — ../AGENTS.md.
Стратег Фабрики продуктов
Устройство
Компоненты
Справочник
Процесс
Справка и прозрачность