StartupKit

A deterministic, phase-sequenced founder-board orchestrator for Claude Code business ideation.

Why StartupKit · Phases · Architecture · Install · Contracts · CLI · Non-goals

What it is

StartupKit is an installable, contract-enforced, reality-grounded ideation pipeline for Claude Code. It decomposes the business-ideation problem into a bounded sequence of 11 phases — diverge → niche → competitors → positioning → offer → validate → money → leads → skills → pitch → export — each implemented as a Claude Code skill with its own prompt, required output sections, and session artifacts. A thin Node CLI (bin/cli.js) deterministically installs the skills and shared templates under ~/.claude/skills/, writes a content-hashed install manifest, and classifies every subsequent file transition as added / updated / skipped / conflict / unchanged. Session state lives as YAML frontmatter inside 00-session.md, so progress is a machine-readable artifact rather than a prose log. Every installable asset is declared in .install-contract.json and constrained by CONTRACTS.md, enforced in CI via .github/workflows/ci.yml. No API keys, no telemetry, no background agents.

Why use StartupKit

Structured ideation over open-ended prompting. An 11-phase pipeline enforces a discipline of diverge → converge → validate → monetize → pitch, backed by one skill per phase in skills/. You never start from a blank prompt.
Collective founder counsel, not name-dropping. Seven Domain Expert Boards convene per phase (primary + secondary) via the mapping in skills/startupkit/SKILL.md. Every decision point surfaces agreement, disagreement, and application instead of quoting one founder.
Deterministic installer. bin/cli.js uses SHA-256 content hashes and an install manifest at ~/.claude/skills/startupkit/.install-manifest.json to classify every file transition; locally edited files surface as conflict and require --force to overwrite.
Machine-readable session state. 00-session.md begins with YAML frontmatter (session, phases, export, goldNiche) defined in templates/session-template.md. Dashboards and phase advancement read from structured data, not prose regex.
Single source of truth. CONTRACTS.md declares the canonical asset layout (skills/<name>/SKILL.md, skills/<name>/references/*.md, templates/*.md). Duplicate mirrors (for example .claude/skills/) are explicitly forbidden.
Reference-by-design. Heavy phases (competitors, positioning, pitch) carry declared mode contracts (quick / standard / deep) and output contracts under each skill's references/ directory. Downstream phases consume only the sections a contract declares.
Local-only, subscription-driven. Every LLM call is a Claude Code session. No API keys, no per-token billing, no outbound telemetry.
CI guardrails. .github/workflows/ci.yml runs node bin/cli.js doctor plus an install dry-run on every push and pull request.

Design principles

Principle	Mechanism
One source of truth per asset	CONTRACTS.md declares canonical locations; `.install-contract.json` enumerates every shipped asset
Deterministic install, not `cp -r`	bin/cli.js hashes every source and destination file and classifies the transition explicitly
Manifest-tracked local edits	`~/.claude/skills/startupkit/.install-manifest.json` records prior hashes; drift becomes a first-class `conflict` action
Structured session state	YAML frontmatter in `00-session.md` drives phase status and next-step logic
Phase skills carry their own contracts	Each heavy skill declares `references/mode-contracts.md` and `references/output-contracts.md`
Fresh-context domain boards	Seven named boards (see below) are convened per phase with agreement/disagreement/application structure
CI-backed contract enforcement	The CI workflow runs `doctor` and a dry-run install on every push and pull request
No background agents, no telemetry	Everything happens inside the user's Claude Code session and the local filesystem

Phases

/startupkit is the orchestrator, not a numbered phase. It creates sessions, renders the dashboard from frontmatter, and routes the user to the next skill.

#	Phase	Command	Role
1	Diverge	`/sk-diverge`	Brainstorm skills, passions, and problems
2	Niche	`/sk-niche`	Score and rank niche ideas
3	Competitors	`/sk-competitors`	Analyze competitors and pricing
4	Positioning	`/sk-positioning`	Build market positioning
5	Offer	`/sk-offer`	Build a Grand Slam Offer
6	Validate	`/sk-validate`	Plan interviews, outreach, MVP validation
7	Money	`/sk-money`	Build pricing and revenue model
8	Leads	`/sk-leads`	Design lead channels and nurture strategy
9	Skills	`/sk-skills`	Map AI skill opportunities to the offer
10	Pitch	`/sk-pitch`	Build investor pitch materials
11	Export	`/sk-export`	Generate final one-pager

How a session flows

1. /startupkit      → create session, render dashboard from frontmatter
2. /sk-diverge      → raw idea surface (no judging)
3. /sk-niche        → converge via Taki Moore 3Q + Hormozi 4-criteria
4. /sk-competitors  → research, mode=quick|standard|deep
5. /sk-positioning  → Dunford 5+1, mode-contracted output
6. /sk-offer        → Grand Slam Offer (Six P's + Value Equation)
7. /sk-validate     → discovery calls, outreach, MVP plan
8. /sk-money        → pricing, offer ladder, projections
9. /sk-leads        → channels + nurture sequence
10. /sk-skills      → AI skill integration plan
11. /sk-pitch       → investor pitch materials (mode-contracted)
12. /sk-export      → one-pager summary

At every step, the active skill writes back into 00-session.md frontmatter (phases[id=N].status, session.activePhase, session.nextPhase, session.updated) as defined in skills/startupkit/references/session-state-protocol.md.

Session state machine

stateDiagram-v2
    [*] --> notStarted
    notStarted --> inProgress: user opens phase
    inProgress --> complete: skill writes phase artifact + updates frontmatter
    inProgress --> notStarted: user resets phase
    complete --> inProgress: user redoes phase
    complete --> [*]: final phase completes

Each of the 11 phases is a row in phases[]. session.activePhase tracks the currently focused phase; session.nextPhase is the recommended next command.

Architecture

flowchart TB
    subgraph Repo ["Repository"]
        skillsDir["skills/"]
        templatesDir["templates/"]
        contractJson[".install-contract.json"]
        contractsMd["CONTRACTS.md"]
    end

    subgraph CLI ["bin/cli.js"]
        init["init / upgrade / force / dry-run / verbose"]
        doctor["doctor"]
        uninstall["uninstall"]
    end

    subgraph Home ["~/.claude/skills"]
        installedSkills["&lt;skill&gt;/SKILL.md + references/"]
        installedTemplates["startupkit/templates/*.md"]
        manifest[".install-manifest.json"]
    end

    subgraph Session ["workspace/sessions/#123;name#125;"]
        sessionMd["00-session.md (YAML frontmatter)"]
        phaseArtifacts["01-..11-*.md artifacts"]
    end

    Repo --> CLI
    CLI --> Home
    Home --> Session
    contractsMd --> CLI
    contractJson --> CLI

Serial by construction. One phase at a time. No background daemons, no multi-agent parallelism.
Install target is stable. Skills always land in ~/.claude/skills/<skill>/. Shared templates always land in ~/.claude/skills/startupkit/templates/.

Domain Expert Boards

Seven boards, mapped per phase. Each skill convenes its primary board and consults its secondary board.

flowchart LR
    subgraph Boards
        OV[Opportunity and Vision]
        MF[Market Focus]
        CS[Competitive Strategy]
        VP[Value and Pricing]
        CV[Customer and Validation]
        SP[Storytelling and Persuasion]
        CE[Craft and Execution]
    end

    P1[1 Diverge] --> OV
    P2[2 Niche] --> MF
    P3[3 Competitors] --> CS
    P4[4 Positioning] --> CS
    P5[5 Offer] --> VP
    P6[6 Validate] --> CV
    P7[7 Money] --> VP
    P8[8 Leads] --> CV
    P9[9 Skills] --> CE
    P10[10 Pitch] --> SP
    P11[11 Export] --> SP

The full primary/secondary mapping lives in skills/startupkit/SKILL.md.

Observability

Everything is on disk, in a form you can grep, diff, and replay.

workspace/sessions/{name}/
├── 00-session.md          # YAML frontmatter + progress tracker (source of truth)
├── 01-diverge.md          # Raw idea surface
├── 02-niches.md           # Scored niches + Gold selection
├── 03-competitors.md      # Competitive summary
├── 03-competitors/        # Full deliverables (battle cards, pricing, matrix)
├── 04-positioning.md      # Positioning summary
├── 04-positioning/        # Full deliverables (statements, alternatives, messaging)
├── 05-offer.md            # Grand Slam Offer
├── 06-validation.md       # Validation plan
├── 07-money-model.md      # Pricing, offer ladder, projections
├── 08-lead-strategy.md    # Channels + nurture
├── 09-skills-match.md     # AI skill recommendations
├── 10-pitch.md            # Investor pitch summary + scorecard
├── 10-pitch/              # Full pitch deliverables
└── 11-one-pager.md        # Final one-pager export

00-session.md is authoritative for phase status. The orchestrator renders the dashboard from its frontmatter.

Install

Two equal paths. Both leave the same result on disk: skills under ~/.claude/skills/, shared templates under ~/.claude/skills/startupkit/templates/, and an install manifest alongside.

Option A — npm CLI

npx startup-ideation-kit init

The package is startup-ideation-kit; the binary is startupkit. Once available on your PATH:

startupkit init
startupkit init --upgrade
startupkit init --dry-run --upgrade
startupkit uninstall

Option B — skill registry

npx skills add mohamedameen-io/StartupKit

Installer behavior

On init, every source file is classified against the install manifest and the current destination:

Action	Meaning
`added`	destination did not exist
`updated`	source differed, applied under `--upgrade` or `--force`
`skipped`	source and destination identical, or `--upgrade` / `--force` not set
`conflict`	destination differs from manifest (local edits); requires `--force`
`unchanged`	identical under `--upgrade`

Flags:

Flag	Effect
`--upgrade`	Apply changes where source differs, preserving local edits as `conflict`
`--force`	Overwrite even on `conflict`
`--dry-run`	Classify without writing
`--verbose`	Print per-file decisions including `unchanged`

A report is printed at the end of every run summarizing totals per action.

Session output

Session files are written under the current working directory: workspace/sessions/{name}/. Each phase skill updates the frontmatter in 00-session.md after its save step. The export skill sets export.generated: true and updates session.status.

Contracts

StartupKit treats the repository layout as a contract, not a convention.

Canonical sources — declared in CONTRACTS.md:
- skills/<name>/SKILL.md
- skills/<name>/references/*.md
- templates/*.md
Enumerated assets — .install-contract.json lists every shipped skill and template; CI fails if filesystem and contract drift.
Forbidden mirrors — tracking duplicate skill content under .claude/ or other mirror directories is disallowed.
No absolute local paths — absolute host paths (for example /Users/...) are forbidden inside any SKILL.md.

CLI reference

Command	Purpose
`startupkit init`	Install skills and shared templates under `~/.claude/skills/`
`startupkit init --upgrade`	Apply changed source files, preserving local edits as `conflict`
`startupkit init --force`	Overwrite local edits during upgrade
`startupkit init --dry-run`	Classify transitions without writing
`startupkit init --verbose`	Include `unchanged` entries in the per-file log
`startupkit doctor`	Run repository contract checks (script under scripts/doctor/)
`startupkit uninstall`	Remove installed skills, templates, and manifest
`startupkit help`	Print usage

Commands not in this table are not implemented in bin/cli.js.

Doctor and CI

doctor is wired in bin/cli.js and dispatches to scripts/doctor/index.js; it runs repository contract checks against CONTRACTS.md and .install-contract.json.
CI is defined in .github/workflows/ci.yml. On every push and pull request, it runs:
- npm ci
- node bin/cli.js doctor
- node bin/cli.js init --dry-run --upgrade under a temporary $HOME

This is the same doctor the local CLI runs — CI has no parallel implementation to drift from.

How it compares

Capability	StartupKit	Single-chat ideation	Generic template pack
11-phase pipeline with named skills	Yes (phases 1–11)	No	Partial
Machine-readable session state	Yes (YAML frontmatter)	No	No
Deterministic installer with manifest	Yes (SHA-256 + action classes)	N/A	No
Conflict-aware upgrade	Yes (`--upgrade` / `--force`)	N/A	No
Contract-enforced asset layout	Yes (CONTRACTS.md, `.install-contract.json`)	No	No
Mode contracts for heavy phases	Yes (`quick` / `standard` / `deep`)	No	No
CI-enforced contract checks	Yes (`.github/workflows/ci.yml`)	No	No
Local-only, no API keys	Yes	Depends	Yes
No telemetry	Yes	Depends	Yes

Non-goals

StartupKit intentionally does not do these things:

No background agents. Phases are serial and user-driven. Nothing runs on a daemon.
No in-context delegation. Skills do not @mention each other mid-conversation.
No hidden CLI surface. If it is not in the CLI reference above, it is not implemented. Commands like founders search do not exist.
No API keys. StartupKit depends on your Claude Code session, not direct LLM APIs.
No telemetry. Nothing phones home. All state lives under workspace/ and ~/.claude/skills/.
No duplicate mirrors. .claude/skills/ and other install mirrors are not tracked; CONTRACTS.md forbids them.
No silent overwrites. Locally modified installed files surface as conflict until you pass --force.

Project structure

StartupKit/
  bin/                        # Node CLI entrypoint (startupkit)
  skills/                     # Skill definitions and per-skill references
  templates/                  # Canonical shared templates
  scripts/doctor/             # Repository contract checks
  docs/                       # Register / evidence / project docs
  workspace/sessions/         # Session outputs (local)
  .install-contract.json      # Enumerated installable assets
  CONTRACTS.md                # Source-of-truth path contract
  .github/workflows/ci.yml    # doctor + install dry-run on push/PR

Requirements

Claude Code
Node.js 18+ (for both npx skills add ... and npx startup-ideation-kit ...)

Attribution

Frameworks used across phases draw from Alex Hormozi, April Dunford, Taki Moore, Geoffrey Moore, Marty Neumeier, Ali Abdaal, Rob Fitzpatrick, and the founder-biography corpus that informs the Domain Expert Boards. All credit for the underlying business frameworks goes to their respective creators.

License

MIT License. See LICENSE.

FilesExpand file tree

README.md

Latest commit

History