Skip to content

Quick Setup EN

Jump to bottom
Sergey Emelyanov edited this page Nov 6, 2026 · 2 revisions

Quick Setup — set up in 5 minutes

Source: README.md, docs/HELP_EN.md (sections 2–3). Languages: Quick-Setup (RU) · Quick-Setup-EN (EN).

Requirements

What Requirement Notes
OS macOS or Linux Windows — via WSL2
Python 3.9+ stdlib only, no pip install needed
External packages 0 CLI and MCP server run on pure stdlib
git any recent version for cloning and PRs
LLM environment Claude Code, Cursor, Codex, OpenCode, Windsurf, Copilot at least one
PDF tools (optional) pdftotext (poppler) or pip install pypdf only if you feed PDF sources

No API keys are needed for the CLI. Integration keys (e.g., LINEAR_API_KEY) go into .env — it is not committed.

Step 1. Clone

git clone https://github.com/Fighter90/product-factory-strategist.git
cd product-factory-strategist

Step 2. Check Python

python3 --version          # must be 3.9 or newer

If older than 3.9, update the interpreter (macOS: brew install python@3.12; Ubuntu/Debian: sudo apt install python3.12). All commands below use python3.

Step 3. Environment self-check

python3 -m tools.pfs doctor

Example output:

Python 3.12.x — OK
pdftotext: found · pypdf: not installed (PDF sources: via pdftotext)
Knowledge base: 88 cards (knowledge/methods) · EN mirrors: 16
Active project: none (pfs new / pfs use)

doctor needs no keys and writes nothing — it is read-only.

Step 4. Tests

python3 -m unittest discover -s tests      # 103 tests

All tests should pass in seconds — they cover the CLI: source/claim registries, Excel workbook quality, claim-type validators, SHA-256 source dedup. If tests fail in bulk, you are on the wrong Python or the clone is broken: re-clone. Details — Verification.

Step 5. First task (in your LLM environment)

  1. Open the repository folder in your environment (in Claude Code — run claude inside the folder).

  2. Write the task in plain language, as you would brief a product leader:

    Paid spam protection is losing subscribers. What do we do with the product, and what do we tell subscribers?

  3. The agent will: create the project, ask 1–3 clarifying questions, build a research plan, collect sources, present options with a red-team attack, and produce the strategies. Progress shows as:

    Step 2/12 · research · sources S001–S009 collected · next: discovery

  4. You decide at three points: brief approval (step 0), option choice (step 6), decision approval (step 10). Step terms — Glossary-EN.

Step 6. Verify the project exists

python3 -m tools.pfs new "Test" "Check request"     # create a project manually (optional)
python3 -m tools.pfs status                         # where you stopped, what's next, cost
python3 -m tools.pfs list                           # project list
python3 -m tools.pfs use <slug>                     # switch the active project

Example pfs status output:

Project: test · created 2026-11-06
Step: 2/12 research (in_progress) · next: discovery
Waiting for human: no · open questions: 1
Sources: 3 · claims: 5 · decisions: 0
Session cost: $0.42 (Claude Code transcripts)

Resuming after a break

State lives in project files (state.json, log.jsonl, claims.jsonl, decisions.jsonl) — not in chat memory.

  • In Claude Code: open a new chat in the same folder — the SessionStart hook feeds the agent pfs status + pfs decision due automatically. You do not need to type anything.
  • In any other environment: start the chat with “read AGENTS.md and run python3 -m tools.pfs status”.
  • Manually: pfs next — a “what to decide now” digest: current step, human waits, overdue commitments, revisions, open questions.

Completed steps are never repeated: the agent checks the log.jsonl journal.

Typical getting-started commands

pfs status                          # where you stopped
pfs next                            # what needs a decision now
pfs list                            # which projects exist
pfs source list                     # which sources are registered
pfs claim list                      # which claims are recorded
pfs check --strict                  # document quality gate
pfs kb search "cohort retention"    # find a method card
pfs questions intake                # the step's question block
pfs cost                            # cost from transcripts
pfs doctor                          # environment diagnostics

Full reference — CLI-Reference-EN.

What lives where

Path Contents Who changes it
AGENTS.md rules and the 12-step process maintainer, via PR
knowledge/methods/ 88 knowledge cards (RU) maintainer, via PR
knowledge/methods_en/ + INDEX_EN.md 16 EN mirrors + EN index maintainer, via PR
knowledge/templates/, knowledge/rubrics/ document templates, grading rubrics maintainer
config/models.json models per task, profiles agent owner
config/question_blocks.json per-step question blocks agent owner
.claude/agents/ 8 subagents maintainer
.claude/skills/ 120 skills maintainer / library
.claude/hooks/ 4 hook events + _common.py + error log maintainer
projects/<slug>/ task materials: sources/, outputs/, analysis/, interviews/ agent, during work
projects/<slug>/state.json, claims.jsonl, decisions.jsonl, log.jsonl task state only via pfs
.env integration keys you; the file is not committed

Steering during work

What you say What happens
“stop” pause; state saved to state.json
“clarify: …” task correction; only the affected parts are redone
“redo section X” section rework without repeating the whole step
“build a six-pager” committee report + 4 Excel workbooks (pfs export --six-pager)
“make a deck” 16:9 HTML deck from the six-pager (pfs export --deck)
“use skill premortem: on D001” attaching a skill to the task

Environment setup: briefly

Environment What to do after cloning
Claude Code run claude in the repo folder — hooks, subagents, and skills load automatically
Cursor rules already in .cursor/rules; MCP — .mcp.json (pfs)
Codex / OpenCode / Windsurf / Copilot nothing: the environment reads AGENTS.md; state — pfs status
Linear integration (optional) LINEAR_API_KEY in .env; server — npx mcp-server-linear from .mcp.json

The 5-minute checklist

  • python3 --version → 3.9+
  • git clone done, you are in the repo root
  • python3 -m tools.pfs doctor — Python OK, 88 cards, PDF tools (optional)
  • python3 -m unittest discover -s tests — 103 tests green
  • The folder is open in your LLM environment
  • The task sent, the agent asked ≤3 brief questions
  • pfs status shows Step 0/12 intake and your project

Your first week

Day What to do Page
1 setup + first task up to step 6 (the option choice) Quick-Setup-EN
2 understand S###/C###/D###, look at pfs claim list Glossary-EN
3 finish the run: choice → strategies → validation plan → decision D### Workflow-Walkthrough-EN
4 build the six-pager + Excel, check formulas on the “Input” sheet CLI-Reference-EN (pfs calc, pfs export)
5 read the CVStart demo and compare with your run Demo-CVStart-EN
ongoing pfs decision due weekly; new data → pfs impact Decisions-and-Monitoring-EN

Common startup problems

Symptom Fix
ModuleNotFoundError: tools you are not in the repo root — cd into the clone
Tests fail in bulk check Python version (python3 --version)
doctor can't see PDF tools not critical: install poppler or pip install pypdf
Hook is “silent” in a new chat check .claude/hooks/hook_errors.log
Subagent/skill not showing restart the environment session

Full breakdown — Troubleshooting-EN and FAQ-EN.

Next

Стратег Фабрики продуктов

Устройство

Компоненты

Справочник

Процесс

Справка и прозрачность

Clone this wiki locally