Skip to content

AI agent skills for startup validation, competitive intelligence, and planning

docs: add startup-positioning to project documentation

Ferdinando Bonsegna6218c61640b9
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 41c6ac8..451b2ec 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -16,7 +16,8 @@
"strict": false,
"skills": [
"./startup-design",
- "./startup-competitors"
+ "./startup-competitors",
+ "./startup-positioning"
]
}
]
diff --git a/CLAUDE.md b/CLAUDE.md
index 82b90b6..b9bf12c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,7 +16,7 @@ This repository contains the **startup** plugin for AI agents. The plugin namesp
| Category | Purpose | Skills |
|----------|---------|--------|
| **Design** | Full process, idea to validated plan | `startup-design` |
-| **Analyze** | Deep standalone analysis of one area | `startup-competitors`, `startup-positioning` (planned) |
+| **Analyze** | Deep standalone analysis of one area | `startup-competitors`, `startup-positioning` |
| **Build** | Post-validation execution tools | `startup-pitch` (planned) |
## Repository Structure
@@ -43,6 +43,15 @@ startup-skill/ # Plugin namespace (startup:*)
│ ├── research-wave-2-sentiment-mining.md
│ ├── research-wave-3-gtm-signals.md
│ └── research-synthesis.md
+├── startup-positioning/ # Skill: startup:startup-positioning
+│ ├── SKILL.md # Main skill file (~218 lines, 2 waves)
+│ └── references/
+│ ├── research-principles.md
+│ ├── research-wave-1-alternatives.md
+│ ├── research-wave-2-market-frame.md
+│ ├── research-synthesis.md
+│ ├── frameworks.md
+│ └── honesty-protocol.md
├── CLAUDE.md
├── CONTRIBUTING.md
├── LICENSE
@@ -55,8 +64,8 @@ startup-skill/ # Plugin namespace (startup:*)
- **Plugin name** (`startup`): defined in `.claude-plugin/marketplace.json` → becomes the namespace prefix
- **Skill name** (`startup-design`, `startup-competitors`): defined in `SKILL.md` frontmatter → must match directory name
-- **Command**: `/startup:startup-design`, `/startup:startup-competitors` — `plugin-name:skill-name`
-- Future skills go in the same repo as separate directories (e.g. `startup-pitch/`, `startup-positioning/`)
+- **Command**: `/startup:startup-design`, `/startup:startup-competitors`, `/startup:startup-positioning` — `plugin-name:skill-name`
+- Future skills go in the same repo as separate directories (e.g. `startup-pitch/`)
### Skill Format
@@ -80,7 +89,11 @@ startup-skill/ # Plugin namespace (startup:*)
- Wave 2: Customer Sentiment Mining (2 agents)
- Wave 3: GTM & Strategic Signals (2 agents)
-Each wave must complete before the next starts. Agents use WebSearch for real data. Both skills support Claude.ai (sequential fallback) and Knowledge-Based Mode when WebSearch is unavailable.
+**startup-positioning** uses 2 sequential waves of parallel agents:
+- Wave 1: Competitive Alternatives + Customer Intelligence (2 agents)
+- Wave 2: Market Frame + Trends (2 agents)
+
+Each wave must complete before the next starts. Agents use WebSearch for real data. All skills support Claude.ai (sequential fallback) and Knowledge-Based Mode when WebSearch is unavailable.
### Output Structure
@@ -101,10 +114,20 @@ Each wave must complete before the next starts. Agents use WebSearch for real da
- `battle-cards/{competitor}.md` — Per-competitor one-pagers
- `raw/` — Raw research data from each wave
+**startup-positioning** generates files in `{project-name}/`:
+- `intake.md` — Product and market context
+- `positioning-doc.md` — Main deliverable (Dunford 5 components)
+- `positioning-statement.md` — Moore + Neumeier statements + elevator pitch
+- `competitive-alternatives.md` — JTBD-informed alternatives map
+- `market-category-analysis.md` — Category candidates + recommendation
+- `raw/` — Raw research data from each wave
+
### Integration Between Skills
`startup-competitors` can detect and leverage prior `startup-design` output. If files like `01-discovery/competitor-landscape.md` exist, it uses them as a starting point instead of re-interviewing.
+`startup-positioning` can detect and leverage output from BOTH `startup-design` (intake, discovery, strategy) and `startup-competitors` (battle cards, pricing landscape). It uses prior data as a head start and skips redundant intake questions.
+
### Testing
Eval cases are in `{skill}-workspace/evals/evals.json`. To test:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4e89c60..c0b4ecb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
# Contributing
-Thanks for your interest in contributing to Startup Design Skill! This guide will help you improve the skill or add new capabilities.
+Thanks for your interest in contributing to Startup Skills! This guide will help you improve existing skills or add new capabilities.
## Ways to Contribute
@@ -18,16 +18,20 @@ Thanks for your interest in contributing to Startup Design Skill! This guide wil
## Skill Structure
+Each skill follows the same directory pattern:
+
```
-startup-design/
+{skill-name}/
├── SKILL.md # Main skill file (keep under 500 lines)
└── references/ # Supporting documents loaded on demand
├── research-principles.md
├── research-wave-*.md
├── research-synthesis.md
- └── frameworks.md
+ └── frameworks.md (if applicable)
```
+Current skills: `startup-design/`, `startup-competitors/`, `startup-positioning/`.
+
### Guidelines
- **SKILL.md** should stay under 500 lines. Move detailed content to `references/`
@@ -66,12 +70,15 @@ Existing test scenarios are in `startup-design-workspace/evals/evals.json`:
When creating a new release:
-- [ ] Rebuild `startup-design.zip` from the `startup-design/` directory: `zip -r startup-design.zip startup-design/`
+- [ ] Rebuild zip files for each changed skill:
+ - `zip -r startup-design.zip startup-design/`
+ - `zip -r startup-competitors.zip startup-competitors/`
+ - `zip -r startup-positioning.zip startup-positioning/`
- [ ] Create a git tag: `git tag -a vX.Y.Z -m "description"`
- [ ] Push code and tag: `git push origin main && git push origin vX.Y.Z`
-- [ ] Create a GitHub release and attach `startup-design.zip` as an asset (Claude.ai users download this)
+- [ ] Create a GitHub release and attach zip files as assets (Claude.ai users download these)
-The zip file is used by Claude.ai web app users who install skills via Settings → Skills → Add Skill. It must be updated with every release.
+The zip files are used by Claude.ai web app users who install skills via Settings → Skills → Add Skill. They must be updated with every release that changes skill files.
## Quality Checklist
@@ -81,7 +88,7 @@ The zip file is used by Claude.ai web app users who install skills via Settings
- [ ] No sensitive data or credentials
- [ ] Tested locally with AI agent
- [ ] Changes are focused and minimal
-- [ ] `startup-design.zip` rebuilt if skill files changed
+- [ ] Zip files rebuilt for any changed skills
## Questions?
diff --git a/README.md b/README.md
index f748b01..4db772a 100644
--- a/README.md
+++ b/README.md
@@ -16,8 +16,9 @@ Works with [Claude Code](https://claude.ai/claude-code) and any agent that suppo
|-------|-------------|
| [startup-design](startup-design/) | A complete startup plan: market research, strategy, brand, product definition, financial projections, and validation experiments. 8 phases, 11 research agents, one command. |
| [startup-competitors](startup-competitors/) | Battle cards for every competitor, a pricing landscape with reverse-engineered tiers, a feature matrix, and a strategic report — built from real reviews, forums, and web data. |
+| [startup-positioning](startup-positioning/) | Market positioning strategy using April Dunford's framework, enriched with JTBD, Moore, and Neumeier. Produces a positioning doc, positioning statements, competitive alternatives map, and market category analysis. 3 phases, 4 research agents. |
-Coming soon: `startup-positioning` (April Dunford framework) and `startup-pitch` (investor deck generation).
+Coming soon: `startup-pitch` (investor deck generation).
## Usage
@@ -34,9 +35,13 @@ I need battle cards and a pricing comparison."
"Quick validation — fast track mode."
→ startup-design runs a compressed go/no-go analysis
+
+"How should we position our product? We're in the project management space
+but we're different from Asana and Monday."
+→ startup-positioning builds positioning through Dunford's 5+1 components
```
-Or invoke directly: `/startup:startup-design`, `/startup:startup-competitors`
+Or invoke directly: `/startup:startup-design`, `/startup:startup-competitors`, `/startup:startup-positioning`
> **Token usage:** These skills run multiple research agents and can consume a large number of tokens. For the best experience, use [Claude Max 5x](https://claude.ai/upgrade). If a session hits the limit, just ask Claude to "resume from where you left off" — it will pick up the process.
@@ -63,6 +68,7 @@ npx skills add ferdinandobons/startup-skill
git clone https://github.com/ferdinandobons/startup-skill.git
cp -r startup-skill/startup-design .agents/skills/
cp -r startup-skill/startup-competitors .agents/skills/
+cp -r startup-skill/startup-positioning .agents/skills/
# Git submodule
git submodule add https://github.com/ferdinandobons/startup-skill.git .agents/startup-skill