Command: specleft discover

[Dimwiddle]

Summary

New top-level Click command that runs the full Phase 1 + Phase 2 discovery pipeline and writes draft specs to .specleft/specs/_discovered/. Supports --dry-run, --format json, --language filtering, and a promote subcommand.

Depends on: #126, #134, #135

New file

src/specleft/commands/discover.py

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

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

Command signature

specleft discover [OPTIONS] [PROJECT_ROOT]

Options:
  --format [table|json]   Output format (default: auto-detect TTY)
  --dry-run               Preview without writing any files
  --output-dir PATH       Override default staging dir (.specleft/specs/_discovered/)
  --language TEXT         Limit to language: python, typescript (repeatable)
  --specs-dir PATH        Existing specs dir for traceability matching
                          [default: resolved via resolve_specs_dir()]
  --pretty                Indented JSON output

Table output (TTY)

Scanning project...
  ✓ Python (pytest)   — 142 test functions
  ✓ TypeScript (Jest) — 38 test functions
  ✓ API routes        — 24 routes
  ✓ Docstrings        — 67 items
  ✓ Git history       — 200 commits

Generating draft specs...

  ┌──────────────────────────┬───────────┬───────────────────────────────────────────────┐
  │ Feature                  │ Scenarios │ Written to                                    │
  ├──────────────────────────┼───────────┼───────────────────────────────────────────────┤
  │ user-authentication      │ 8         │ .specleft/specs/_discovered/user-auth….md     │
  │ payment-processing       │ 5         │ .specleft/specs/_discovered/payment-p….md     │
  └──────────────────────────┴───────────┴───────────────────────────────────────────────┘

  14 features, 47 scenarios written to .specleft/specs/_discovered/
  Review drafts, then promote with: specleft discover promote

JSON output

{
  "features": [
    {
      "feature_id": "user-authentication",
      "name": "User Authentication",
      "scenario_count": 8,
      "output_file": ".specleft/specs/_discovered/user-authentication.md",
      "confidence": 0.8
    }
  ],
  "total_features": 14,
  "total_scenarios": 47,
  "output_dir": ".specleft/specs/_discovered",
  "dry_run": false,
  "errors": []
}

discover promote subcommand

specleft discover promote [OPTIONS] [FEATURE_ID...]

Copies draft specs from .specleft/specs/_discovered/ to .specleft/specs/
(or --specs-dir). Files remain in _discovered/ after promotion (drafts are not deleted).

Options:
  --all              Promote every file in the staging dir
  --specs-dir PATH   Destination dir [default: resolve_specs_dir()]
  --overwrite        Replace existing spec if it already exists
  --dry-run          Preview without writing

Acceptance criteria

• specleft discover --dry-run prints table/JSON with no files written
• specleft discover --format json exits 0 and output is valid JSON matching the schema above
• specleft discover writes files to .specleft/specs/_discovered/ by default
• specleft discover --output-dir /tmp/out writes to /tmp/out instead
• specleft discover promote --all copies all draft files to .specleft/specs/
• specleft discover promote user-authentication copies only that feature
• Promote skips files already in destination unless --overwrite
• Git miner error appears in errors[] but command still exits 0
• --format json output is valid JSON even when all miners error
• Tests in tests/cli/test_discover.py using CliRunner + tmp_path

Documentation updates

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

docs/cli-reference.md

Add a new top-level ## Discover section before ## Status, containing:

• ### specleft discover — full flag reference, table output example, JSON schema
• ### specleft discover promote — flag reference, behaviour description (draft files remain in staging after promotion)

README.md

• Quick Start — replace Path 2: Bulk-generate feature specs from a PRD with a new Path 2: Discover specs from existing code block:

  specleft discover
  specleft discover promote --all
  specleft status
  

• AI Agents section — add specleft discover --format json alongside the existing agent commands

docs/getting-started.md

Add a Discover specs from existing code section after the existing Create Specs section:

specleft discover
specleft discover promote --all

Include a one-sentence explanation of the staging area (.specleft/specs/_discovered/).

docs/SKILL.md

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

specleft discover --format json [PROJECT_ROOT] [--dry-run] [--language python|typescript] [--output-dir PATH] [--specs-dir PATH]
specleft discover promote --format json [--all] [FEATURE_ID...] [--specs-dir PATH] [--overwrite] [--dry-run]

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

[Dimwiddle]

Implementation Notes

Branch: codex/feature/discovery-layer/136-specleft-discover
Approach: Add a new specleft discover command that runs the discovery pipeline, groups items into draft features, writes staged drafts to .specleft/specs/_discovered/, and provides a promote subcommand for safe copy-based promotion into active specs.

Decisions

• Reuse build_default_pipeline() + group_items() + generate_draft_specs() to avoid duplicating discovery logic in command code.
• Treat promotion as non-destructive by default: staged files remain in _discovered/, and destination overwrite requires explicit --overwrite.
• Keep machine output deterministic with stable feature ordering and root-relative path strings in JSON payloads.

Tasks

• Implement src/specleft/commands/discover.py with discover + discover promote command flow and output schema.
• Register discover command in src/specleft/cli/main.py.
• Add CLI tests in tests/cli/test_discover.py for dry-run, JSON, output-dir override, promote behavior, overwrite/skip behavior, and miner-error resilience.
• Update docs/cli-reference.md with Discover command docs.
• Update README.md, docs/getting-started.md, and docs/SKILL.md with discover workflow guidance.
• Update features/feature-spec-discovery.md scenarios and validations for issue Command: specleft discover #136.
• Run make lint-fix && make lint && make test && make pre-commit.