Add specleft start command (#137)

README.md

@@ -28,6 +28,15 @@ pip install specleft
 specleft init
 ```
 
+### Path 0: New to SpecLeft? Start here
+
+Scans your codebase, discovers features from existing code, and shows a side-by-side report of code vs specs.
+
+```bash
+cd my-project
+specleft start
+```
+
 ### Path 1: Add one feature (and generate a test skeleton)
 
 Create a feature, then add a scenario and generate a skeleton test for it:
@@ -86,6 +95,7 @@ If you are integrating SpecLeft into an agent loop, it's recommended to install
 Otherwise begin with:
 
 ```bash
+specleft start --format json
 specleft doctor --format json
 specleft contract --format json
 specleft features stats --format json

docs/SKILL.md

@@ -5,6 +5,7 @@
 All commands below run in compact mode.
 
 ## Workflow
+0. specleft start --format json
 1. specleft next --limit 1
 2. Implement test logic
 3. specleft features validate
@@ -27,6 +28,11 @@ All commands below run in compact mode.
 
 ## Features
 
+## Discovery
+
+### Start discovery report
+`specleft start --format json [PROJECT_ROOT] [--save] [--specs-dir PATH]`
+
 ### Validate specs
 `specleft features validate --format json [--dir PATH] [--strict]`
 Validate before generating tests. `--strict` treats warnings as errors.

docs/cli-reference.md

@@ -173,6 +173,28 @@ Options:
   --format [table|json] Output format (default: table)
 ```
 
+## Start
+
+### `specleft start`
+
+Discovery-first entrypoint for existing codebases. Runs health checks, scans code,
+discovers features, and compares discovered scenarios against existing specs.
+
+```bash
+specleft start [OPTIONS] [PROJECT_ROOT]
+
+Options:
+  --format [table|json]  Output format (default: auto-detect TTY)
+  --save                 Write draft specs to .specleft/specs/_discovered/
+  --specs-dir PATH       Existing specs dir to compare against
+  --pretty               Pretty-print JSON output
+```
+
+`--save` stages drafts in `.specleft/specs/_discovered/` only. It does not
+promote them automatically to active specs.
+
+To generate and write specs directly, use `specleft discover`.
+
 ## Discover
 
 ### `specleft discover`
@@ -196,6 +218,18 @@ Table output example:
 
 ```text
 Scanning project...
+✓ Detected: Python (pytest), 847 files, 142 test functions
+
+Discovering features...
+✓ Found 14 features, 47 scenarios
+
+Your project vs your specs:
+┌──────────────────────────┬───────────┬─────────────┐
+│ Feature                  │ Code      │ Specs       │
+├──────────────────────────┼───────────┼─────────────┤
+│ user-authentication      │ 12 tests  │ none        │
+│ payment-processing       │ 8 tests   │ 6 specs     │
+└──────────────────────────┴───────────┴─────────────┘
   ✓ Python (pytest) — 142 test functions
   ✓ API routes      — 24 routes
   ✓ Docstrings      — 67 items
@@ -216,6 +250,31 @@ JSON output schema:
 
 ```json
 {
+  "project": {
+    "root": "/path/to/project",
+    "languages": ["python"],
+    "test_frameworks": ["pytest"],
+    "files_scanned": 847
+  },
+  "discovery": {
+    "features": 14,
+    "scenarios": 47,
+    "items_by_kind": {
+      "test_function": 142,
+      "api_route": 24,
+      "docstring": 67,
+      "git_commit": 200
+    }
+  },
+  "comparison": [
+    {
+      "feature_id": "user-authentication",
+      "name": "User Authentication",
+      "code_scenarios": 12,
+      "spec_scenarios": 0
+    }
+  ],
+  "saved": false,
   "features": [
     {
       "feature_id": "user-authentication",

docs/getting-started.md

@@ -1,12 +1,21 @@
 # SpecLeft Getting Started
 
+## Quickstart (existing codebase)
+
+```bash
+specleft start
+```
+
+If you already have code, `specleft start` is faster. It discovers specs from
+your existing tests, routes, and docstrings.
+
 ## Install
 
 ```bash
 pip install -e ".[dev]"
 ```
 
-## Create Specs
+## Create Specs (greenfield alternative)
 
 ```bash
 mkdir -p .specleft/specs/calculator/addition

features/feature-spec-discovery.md

@@ -62,6 +62,19 @@ Add shared discovery infrastructure for Issues #125 and #126: centralized parser
 **When** I call `build_default_pipeline(root).run()`
 **Then** a `DiscoveryReport` is returned with run duration, detected languages, miner results, and total item counts.
 
+### Story 6.1: Start command onboarding flow
+**Scenario:** As a new user with existing code, I need a single command to discover specs without writing by default.
+**Given** a valid Python project
+**When** I run `specleft start`
+**Then** it performs health check, project detection, discovery, and side-by-side code-vs-spec comparison.
+**And** no files are written to `.specleft/specs/_discovered/` unless `--save` is passed.
+
+**Scenario:** As a pipeline consumer, I need resilient startup output.
+**Given** a discovery run where the git miner fails (for example, non-git directory)
+**When** I run `specleft start --format json`
+**Then** the command exits successfully
+**And** miner failures are included in `errors[]`.
+
 ### Story 7: Shared docstring and JSDoc mining
 **Scenario:** As a discovery pipeline, I need intent-rich text signals from source code comments.
 **Given** configured source directories and a shared miner context
@@ -322,6 +335,10 @@ Add shared discovery infrastructure for Issues #125 and #126: centralized parser
 - `specleft status` marks convention-linked scenarios as implemented with `match_kind="convention"` in verbose JSON output.
 - `specleft status --format table` displays `✓ (convention)` for convention-linked scenarios.
 - `generate_draft_specs(..., traceability_links=...)` emits `linked_tests` frontmatter for matched scenarios.
+- `specleft start` exits 0 on a healthy Python project and returns table/json output.
+- `specleft start --format json` returns `project`, `discovery`, `comparison`, `saved`, and `errors`.
+- `specleft start --save` writes draft markdown files to `.specleft/specs/_discovered/`.
+- `specleft start` without `--save` performs a read-only discovery run.
 - `specleft discover --dry-run` does not write files and reports planned outputs.
 - `specleft discover --format json` exits `0` with valid JSON output even when miners report errors.
 - `specleft discover` writes drafts to `.specleft/specs/_discovered/` by default and supports `--output-dir` override.

src/specleft/cli/main.py

@@ -19,6 +19,7 @@
     next_command,
     plan,
     skill_group,
+    start,
     status,
     test,
 )
@@ -53,6 +54,7 @@ def cli() -> None:
 cli.add_command(skill_group)
 cli.add_command(guide)
 cli.add_command(mcp)
+cli.add_command(start)
 
 
 __all__ = ["cli"]

src/specleft/commands/__init__.py

@@ -16,6 +16,7 @@
 from specleft.commands.next import next_command
 from specleft.commands.plan import plan
 from specleft.commands.skill import skill_group
+from specleft.commands.start import start
 from specleft.commands.status import status
 from specleft.commands.test import test
 
@@ -31,6 +32,7 @@
     "next_command",
     "plan",
     "skill_group",
+    "start",
     "status",
     "test",
 ]