Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@
},
"metadata": {
"description": "AI-powered strategic advisor for entrepreneurs. 158 skills, 24 diagnostics, 21 playbooks, 9 industry packs.",
"version": "1.1.0-rc.1"
"version": "1.1.0"
},
"plugins": [
{
"name": "foreman",
"description": "AI-powered strategic advisor for entrepreneurs. 158 business framework skills, 24 diagnostic triage systems, 21 multi-step playbooks, 48 output templates, 9 industry packs, board simulation, implementation tracking, research guides, and organizational politics navigation. Supports solo mode, Stoic philosophical mode, and multilingual output.",
"version": "1.1.0-rc.1",
"version": "1.1.0",
"author": {
"name": "Fatih Guner"
},
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "foreman",
"version": "1.1.0-rc.1",
"version": "1.1.0",
"description": "AI-powered strategic advisor for entrepreneurs",
"author": {
"name": "Fatih Guner"
Expand Down
2 changes: 2 additions & 0 deletions .claude/RUNTIME.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ Run `node "<content-root>/runtime/run.mjs" <command> --workspace "<project-root>

Read profile: `profile`. Set `/solo`: `profile --mode solo`; `/solo off`: `profile --mode standard`. Set `/stoic`: `profile --stoic on`; off uses `off`. Set `/language tr`: `profile --language tr`; default uses `en`; status only reads. `/sector saas` uses `profile --sector saas`. Always read persisted settings at the start of a new session.

Honor the scope requested by the user. A mode or language requested only for this conversation is a session override: apply it without changing the saved profile. Explicitly requested persistent settings use the profile runtime. A current user instruction takes precedence over a saved preference for the current response.

Read tasks: `track --filter all` (also `active`, `overdue`, `stalled`, or any of the six statuses). Add a confirmed task: `task --id impl-001 --description "Interview five customers" --deadline 2026-10-01`. Update `/progress impl-001 40 note`: `task --id impl-001 --progress 40 --note "note"`. Status changes use `--status not-started|in-progress|blocked|completed|abandoned|deferred`. A completed task has progress 100. Use `--revision N` when editing a previously read revision; a conflict requires rereading, not overwriting.

After a confirmed playbook step, save the next step: `resume --playbook pivot-playbook --step 2`. Read `resume` to continue from that checkpoint; verify the playbook and step against the catalog before writing. The exposed Claude command is `/foreman-resume`, because `/resume` is a host command. Never mark a step complete based merely on a generated recommendation.
Expand Down
2 changes: 1 addition & 1 deletion .claude/catalog.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"release": {
"version": "1.1.0-rc.1",
"version": "1.1.0",
"license": "MIT",
"repository": "git+https://github.com/fatihguner/foreman.git",
"homepage": "https://foreman.sh"
Expand Down
3 changes: 3 additions & 0 deletions .claude/policies/advisory.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,10 @@ For an initial advisory answer, distinguish the facts supplied by the founder fr
- Assess reversibility from actual commitments and dependencies. Do not dismiss a founder's concern as irrational or prescribe a fixed multi-month experiment without checking capacity and runway.
- When a formula is needed, preserve all its components and define the period. The revenue bridge includes expansion as well as new revenue, contraction and churn.
- Before recommending that a founder stop advertising, freeze product work, change prices or cut staff, establish the relevant constraints, cash runway, dependencies and evidence. Prefer a bounded reversible experiment when uncertainty is high.
- Research is not a prerequisite for every operational decision. Do not postpone all feature decisions or deliveries until an interview quota is met. First identify urgent fixes, existing customer commitments and available capacity; while these are unknown, gather one existing piece of evidence alongside ongoing work.
- Treat proposed effort, sample sizes and deadlines as provisional until the founder's capacity is known. A valid research outcome can be no recurring pattern or insufficient evidence; never require research to produce a particular finding.
- Solo mode uses the founder's actual capacity and resources. Do not invent a team, board, investor mandate or delegation capacity. Stoic mode adds perspective without overriding evidence or the user's priorities.
- Present philosophical accounts of emotion as optional perspectives, not proven explanations of this person's feelings. Acknowledge distress without saying that their judgment alone causes it or that the feeling is misplaced.
- Use the saved output language for both questions and recommendations. Keep catalog identifiers unchanged.
- Recommend commands and content that exist in the supplied catalog. Treat examples in source documents as illustrations, not evidence that tools ran or state was saved.
- Read actual saved state before claiming recall or progress. Confirm a write only after the runtime succeeds. If persistence is unavailable, say the preference applies to this conversation and do not claim it will survive a new session.
Expand Down
24 changes: 14 additions & 10 deletions .claude/research/customer-interview-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ feeds_into_skills:
feeds_into_templates:
- market-opportunity-summary
- new-initiative-brief
estimated_time: "10-20 hours"
estimated_time: "Depends on scope, recruitment and available capacity"
data_sources:
- Direct interviews
- User testing sessions
Expand All @@ -28,6 +28,8 @@ related_content:

# Customer Interview Guide

Scope this research to the founder's actual available time and the decision at hand. If capacity is unknown, review an existing customer interaction first and ask what time is available before assigning any new interview quota. Keep current commitments and urgent work running. The goal is to record what the evidence shows; no recurring pattern or insufficient evidence is a valid outcome.

Every failed startup is a monument to assumptions that were never tested. The Business Model Canvas has nine boxes, and at least six of them contain guesses until a founder has sat across from a real customer and listened — truly listened, without pitching, without leading, without defending. Customer interviews are the highest-leverage research activity available to an early-stage company. They cost nothing but time and ego. Yet most founders skip them, or worse, conduct them so poorly that the resulting data confirms whatever they already believed.

The difference between useful and useless interviews is not the questions asked but the discipline with which they are asked. This guide provides that discipline.
Expand Down Expand Up @@ -58,7 +60,7 @@ The difference between useful and useless interviews is not the questions asked

## Recruiting Participants

**How many:** 5-8 interviews per customer segment for pattern detection. After 5 interviews within a segment, you will hear the same themes repeating. After 8, you have statistical confidence in qualitative patterns.
**How many:** Agree on a small initial round after checking available capacity, participant access and the decision being investigated. Reassess after that round: diversity of responses or missing perspectives may require more work, while limited capacity may require narrowing the question. No fixed number guarantees recurring themes, saturation or statistical confidence. Qualitative interviews inform hypotheses; do not present their count alone as population-level proof.

**Where to find them:**
- LinkedIn outreach (direct, honest, brief — "I'm researching [problem area], not selling")
Expand All @@ -80,6 +82,8 @@ The difference between useful and useless interviews is not the questions asked

## Interview Protocol

The time boxes below are illustrative planning aids, not measured requirements. Shorten or split the session around the research question and the participant's availability.

**Phase 1 — Context Setting (5 minutes)**
Thank them. Explain you are researching, not selling. Ask permission to take notes. Establish that honesty is more valuable than politeness. State there are no wrong answers.

Expand Down Expand Up @@ -173,16 +177,16 @@ Complete one form per interview. Fill in during or immediately after — memory

## Synthesis Template

After completing 5+ interviews within a segment, fill in this cross-interview pattern matrix.
Record evidence as interviews become available. The five columns below are placeholders: resize them and use the actual sample size as the denominator. Do not wait for a quota or require the matrix to reveal a pattern.

### Pain Point Frequency

| Pain Point | Interview 1 | Interview 2 | Interview 3 | Interview 4 | Interview 5 | Mentions |
|-----------|-------------|-------------|-------------|-------------|-------------|----------|
| [Pain point A] | | | | | | /5 |
| [Pain point B] | | | | | | /5 |
| [Pain point C] | | | | | | /5 |
| [Pain point D] | | | | | | /5 |
| [Pain point A] | | | | | | /N |
| [Pain point B] | | | | | | /N |
| [Pain point C] | | | | | | /N |
| [Pain point D] | | | | | | /N |

Mark: S = strong signal, M = mentioned, X = not mentioned

Expand All @@ -208,13 +212,13 @@ Mark: S = strong signal, M = mentioned, X = not mentioned

## Interpretation Guide

**Pattern threshold:** A pain point mentioned by 4 out of 5 interviewees is a pattern. Mentioned by 2 out of 5 is an observation. Mentioned by 1 is an anecdote. Build on patterns, investigate observations, and set aside anecdotes.
**Interpreting recurrence:** Report observed mentions alongside the actual sample size, participant selection and contradictory cases. Repetition in a small selected sample can suggest a hypothesis to investigate; it is not a universal threshold or proof of market prevalence. Keep important outliers visible. Report no clear pattern or insufficient evidence when that is what the interviews show.

**Behavior over opinion:** "I would definitely use that" is an opinion. "I spent three hours last Tuesday building a spreadsheet to do this" is a behavior. Weight behaviors over opinions by a factor of ten.
**Behavior over opinion:** "I would definitely use that" is an opinion. "I spent three hours last Tuesday building a spreadsheet to do this" describes a specific behavior. Prefer concrete recent examples to hypothetical enthusiasm, while checking context and corroboration. Do not assign an invented numerical weight.

**Enthusiasm calibration:** Polite interest ("That's interesting") is not a buying signal. Genuine engagement looks like: asking when it will be ready, requesting to be a beta tester, introducing you to colleagues who have the same problem, or asking about pricing unprompted.

**Negative data is the most valuable data.** If five interviews reveal that nobody has the problem you assumed, you have just saved six months of building the wrong thing. Treat disconfirmation as the prize, not the disappointment.
**Keep disconfirming evidence.** If participants do not report the assumed problem, revisit the hypothesis and participant selection. That observation can inform the next decision, but it does not establish that the problem is absent everywhere or guarantee a particular amount of saved development time.

**Segment divergence:** If interviewees in different segments give contradictory answers, your segments are real and distinct. This is useful information — it means you need to choose which segment to serve first.

Expand Down
2 changes: 2 additions & 0 deletions .claude/solo-mode/SOLO.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Capacity rule: measure the founder's workload before promising time savings. Do not assume contractor budget or automation suitability. Start with one measured routine and one bounded improvement; do not promise 10–15 saved hours from an unmeasured intervention.

Confirm available capacity before assigning a weekly quota or promising how little time an action takes. When capacity is unknown, begin with one existing customer interaction or work item. Research runs alongside essential work; do not make all feature decisions wait for a fixed number of interviews. No clear pattern is a valid finding.

Solo mode adapts the entire Foreman system for solopreneurs: individuals who are the company. No co-founder, no team, no board of directors, possibly no external investors. The business is an extension of one person's capabilities, decisions, and constraints. Every skill, diagnostic, playbook, template, and hook in the system was designed with the assumption that a founder operates within a multi-person structure — reporting to a board, delegating to a team, pitching to investors. Solo mode removes those assumptions without removing the frameworks. The intellectual architecture remains intact. The application context shifts.

---
Expand Down
4 changes: 4 additions & 0 deletions .claude/stoic-mode/STOIC-MODE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

Evidence rule: philosophical reflection does not justify an automatic product freeze, feature removal or competitor-monitoring ban. Connect any operational change to customer evidence and capacity. Use concepts present in the source; do not invent named Stoic principles.

Operational scope: keep ordinary delivery, urgent fixes and existing customer commitments running while gathering evidence. Do not say "make no product or price changes" or make all changes wait for research. If caution is needed, name the specific proposed reactive change and assess its constraints; the founder's ongoing work is not implicitly paused. Before sending a response, replace any blanket stop/wait instruction with this narrower scope.

Emotional framing: the philosophical maxims below are perspectives to explore, not diagnoses of the founder. Do not assert that judgment alone causes their anxiety or that an emotion is misplaced. Acknowledge the feeling, distinguish known business facts from feared outcomes, and offer a controllable action without prescribing how the person must feel.

When `/stoic on` is active, every system response passes through a Stoic philosophical lens. This mode does not change WHAT the system delivers -- it changes HOW it frames, contextualises, and deepens the delivery. The same Porter's Five Forces analysis runs identically; the difference is that the output carries Stoic wisdom alongside strategic insight.

Solo mode asks: "Who is this for?" and filters content accordingly.
Expand Down
2 changes: 1 addition & 1 deletion .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "foreman",
"version": "1.1.0-rc.1",
"version": "1.1.0",
"description": "AI-powered strategic advisor for entrepreneurs. 158 skills across 12 categories, from Porter's Five Forces to Stoic philosophy, with diagnostics, playbooks, output templates, and industry-specific packs.",
"author": {
"name": "Fatih Guner",
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).

No unreleased changes.

## [1.1.0] - 2026-09-05

Stable release of the cross-platform installer, persistent state runtime and complete plugin bundles introduced in 1.1.0-rc.1.

### Changed
- Use npm's stable `latest` channel for the cross-platform installer, persistent state runtime and complete plugin bundles.
- Keep session-only mode and language overrides separate from saved profile preferences.
- Stop live advisory evaluation on incomplete model responses, and add isolated host-session checks for profile, task and playbook persistence.
- Keep existing commitments and urgent fixes running during research; scope caution to a specific proposed change.
- Remove fixed interview quotas, unsupported statistical confidence claims and invented evidence weights or time-saving guarantees from the customer interview guide.
- Present Stoic emotional framing as an optional perspective, not a diagnosis of the founder.
- Ground Codex resource paths in the installed skill directory, restrict record discovery to the selected founder, and verify that live tool calls do not read another founder's test record.

## [1.1.0-rc.1] - 2026-09-05

Public release candidate for the cross-platform runtime and packaging update.
Expand Down
26 changes: 11 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,16 +35,16 @@

Foreman is an open-source strategic advisor that gives every entrepreneur access to structured strategic thinking, the kind that used to require a six-figure consulting engagement.

You describe your problem in plain language. Foreman diagnoses the root cause, selects the right framework, applies it to your context, produces a professional deliverable, and tracks whether you actually follow through.
You describe your problem in plain language. Foreman compares plausible causes, selects a framework, applies it to your context, and helps produce a deliverable. Confirmed tasks and playbook checkpoints can be saved for your next session.

| Without Foreman | With Foreman |
|---|---|
| ❌ "My sales are dropping" stays a vague worry | ✅ Diagnosed as onboarding churn in 6 questions |
| ❌ "My sales are dropping" stays a vague worry | ✅ Revenue components compared before attributing a cause |
| ❌ Frameworks learned but never applied | ✅ 158 frameworks applied to YOUR context |
| ❌ Board deck built from scratch every time | ✅ 48 professional templates, ready to fill |
| ❌ Advice given, execution forgotten | ✅ Implementation tracking with weekly check-ins |
| ❌ Advice given, execution forgotten | ✅ Saved tasks, status history and review prompts |
| ❌ Same strategy for SaaS and marketplace | ✅ 9 industry packs with sector-specific benchmarks |
| ❌ Generic AI chat with no memory | ✅ 5-layer memory system that knows your company |
| ❌ Generic AI chat with no memory | ✅ Persisted profile, tasks and playbook checkpoints |

---

Expand All @@ -69,7 +69,7 @@ Entrepreneur: "My competitors are crushing us on price"
│ Output │ ── Competitive landscape brief (investor) + action plan (team)
└────┬────────────┘
┌────▼────────────┐
│ Memory │ ── Saves analysis, tracks implementation, follows up next week
│ Memory │ ── Saves confirmed tasks and checkpoints for the next session
└─────────────────┘
```

Expand Down Expand Up @@ -136,27 +136,23 @@ Single source of truth: `.claude/`. Every other platform derives from it.

## Quickstart

### Try the current release candidate
### Install the stable release

**1.1.0-rc.1** includes the new installer, shared state runtime and repaired plugin bundles. It is publicly available as a release candidate while final live advisory quality acceptance is pending. See the [release notes](docs/releases/v1.1.0-rc.1.md) for verification and known limitations.

Install the GitHub release package directly (Node 22.19 or later):
**1.1.0** includes the new installer, shared state runtime and complete plugin bundles. See the [release notes](docs/releases/v1.1.0.md) for verification and limitations. Requires Node 22.19 or later.

```bash
npx --yes --package=https://github.com/fatihguner/foreman/releases/download/v1.1.0-rc.1/foreman-sh-1.1.0-rc.1.tgz foreman-sh init
npx foreman-sh init
```

Add `--platform codex` for Codex, or `--platform all` for both Claude and Codex. Foreman is MIT-licensed and free to install; your AI host account and model usage are separate.

### npm registry
Use `npx foreman-sh@1.1.0 init` to pin this version. You can also install the same tarball directly from GitHub:

```bash
npx foreman-sh@next init
npx --yes --package=https://github.com/fatihguner/foreman/releases/download/v1.1.0/foreman-sh-1.1.0.tgz foreman-sh init
```

The `next` channel installs the current release candidate. Use `npx foreman-sh@1.1.0-rc.1 init` to pin this exact version. The unversioned command still selects the older stable release.

The new installer adds `.claude/` and `CLAUDE.md` to your current directory and preserves existing files. Use `--workspace /path/to/project` to choose a directory or `--platform codex` to install project skills under `.agents/skills/`. Open Claude Code and start talking:
The new installer adds `.claude/` and `CLAUDE.md` to your current directory and preserves existing files. Repeated initialization only fills missing files; when upgrading, back up and review existing generated files before replacing them. Use `--workspace /path/to/project` to choose a directory or `--platform codex` to install project skills under `.agents/skills/`. Open Claude Code and start talking:

> "My SaaS churn rate is 5.2% and I'm preparing for Series A. What should I focus on?"

Expand Down
Loading
Loading