Command: specleft start

[Dimwiddle]

Summary

New top-level Click command serving as the single entry point for new users. Runs health check → project detection → quick discovery → side-by-side report. Does not write specs to .specleft/specs/ unless --save is passed. Designed to show value in under 10 seconds.

Depends on: #126, #136

New file

src/specleft/commands/start.py

Register in src/specleft/cli/main.py:

from specleft.commands.start import start
cli.add_command(start)

Command signature

specleft start [OPTIONS] [PROJECT_ROOT]

Options:
  --format [table|json]   Output format (default: auto-detect TTY)
  --save                  Persist draft specs to .specleft/specs/_discovered/
  --specs-dir PATH        Existing specs dir to compare against
                          [default: resolve_specs_dir()]
  --pretty                Indented JSON

Internal steps

1. Init - reuse 'init' to initialise the project.
2. Health check — reuse existing doctor logic; exit 1 with clear message if unhealthy
3. Project detection — use FileIndex for file stats + FrameworkDetector.detect() for frameworks (from Discovery: pipeline orchestrator #126). Do NOT implement independent framework detection — import and use the centralised FrameworkDetector
4. Quick discovery — call build_default_pipeline(root).run() → DiscoveryReport. The pipeline internally builds FileIndex, runs FrameworkDetector, and constructs MinerContext — no duplication here
5. Phase 2 grouping — call group_items(report.all_items) → list[DraftFeature]
6. Side-by-side comparison — compare grouped features against resolve_specs_dir(): - "Code" column: count of discovered scenarios per feature
   • "Specs" column: count of existing spec scenarios from SpecsConfig.from_directory(specs_dir) (0 or "none" if no match)
7. Output — table as below; JSON for --format json
8. Save — if --save: call generate_draft_specs(features, .specleft/specs/_discovered/, dry_run=False)

Framework detection

Uses the centralised FrameworkDetector from #126. No local detection logic. The start command gets framework results from the DiscoveryReport which was populated by the pipeline.

For display purposes (the "Detected: Python (pytest)" line), read report.languages_detected and the framework results. The FrameworkDetector implements the hybrid detection strategy (manifest files first, file patterns to confirm/resolve conflicts) as a single source of truth.

Table output

  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   │ none        │
  │ email-notifications      │ 6 tests   │ none        │
  └──────────────────────────┴───────────┴─────────────┘

  You have 47 test scenarios with no specifications.

  → Run `specleft discover` to generate specs
  → Run `specleft start --save` to save these results

When existing specs are found, the "Specs" column shows the count (not "none").

JSON output

{
  "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,
  "errors": []
}

Acceptance criteria

• specleft start exits 0 on a valid Python project
• specleft start --format json exits 0 and output validates against the JSON schema above
• specleft start --save writes draft specs to .specleft/specs/_discovered/ and confirms file paths in output
• specleft start without --save writes nothing to disk
• On a project with existing .specleft/specs/ files, "Specs" column shows correct non-zero counts
• Uses FrameworkDetector from Discovery: pipeline orchestrator #126 — no local framework detection logic
• Git miner failure appears in errors[] but command exits 0
• Tests in tests/cli/test_start.py using CliRunner + tmp_path with a minimal fake Python project fixture

Documentation updates

All docs must be updated as part of this issue — not deferred.

docs/cli-reference.md

Add a new top-level ## Start section (place before ## Status), containing:

• ### specleft start — full flag reference, table output example, JSON schema
• Note that --save writes to .specleft/specs/_discovered/ and does not promote automatically
• Cross-reference: "To generate and write specs directly, use specleft discover"

README.md

• Quick Start — prepend a new Path 0: New to SpecLeft? Start here block as the very first path:

  cd my-project
  specleft start
  

  One-line description: "Scans your codebase, discovers features from existing code, and shows a side-by-side report of code vs specs."
• AI Agents section — add specleft start --format json to the pre-flight agent commands list

docs/getting-started.md

Replace the opening ## Install → ## Create Specs flow with a new recommended entry point:

## Quickstart (existing codebase)

specleft start

Retain the existing ## Create Specs flow as an alternative for greenfield projects. Add a note: "If you already have code, specleft start is faster — it discovers specs from your existing tests, routes, and docstrings."

docs/SKILL.md

Add specleft start as the first command in the ## Workflow section (before specleft next):

## Workflow
0. specleft start --format json          # first run: discover features from code
1. specleft next --limit 1
...

Add a ## Discovery section with the full agent-facing signatures:

specleft start --format json [PROJECT_ROOT] [--save] [--specs-dir PATH]

• Update scenarios and tests in features/feature-spec-discovery.md to cover the functionality introduced by this issue

[Dimwiddle]

Implementation Notes

Branch: codex/137-specleft-start-command
Approach: Implement a new top-level specleft start command that orchestrates init/health/discovery/grouping/comparison, supports table+JSON output, and only persists drafts when --save is provided.

Decisions

• Reuse existing discovery pipeline + FrameworkDetector output from DiscoveryReport as the single source of truth (no local framework detection logic).
• Build comparison rows by normalized feature ID with discovered scenario counts versus SpecsConfig scenario counts.
• Treat non-fatal miner failures (for example git miner) as report errors in output while preserving exit code 0.

Tasks

• Add start command module with options and CLI registration.
• Implement orchestration flow: init, health check, quick discovery, phase 2 grouping, and comparison model.
• Implement output rendering for table and JSON, including saved paths and errors.
• Implement --save behavior to write draft specs to .specleft/specs/_discovered/ only when requested.
• Add CLI tests in tests/cli/test_start.py covering success, JSON output, save/no-save behavior, specs comparison counts, and non-fatal miner error handling.
• Update docs: docs/cli-reference.md, README.md, docs/getting-started.md, and docs/SKILL.md.
• Update features/feature-spec-discovery.md scenarios/tests for specleft start.