SpecLeft Skill

[Dimwiddle]

Skill File — .specleft/SKILL.md

Generated by specleft init. Contains the full CLI reference that agents read once from disk. This will replace MCP tool declarations with a single file read.

Target size: ~800 tokens

Structure:

# SpecLeft CLI Reference

## Workflow
1. specleft next → pick scenario
2. Implement test logic
3. specleft features validate → verify specs
4. pytest → run tests
5. Repeat

## Safety
- Always --dry-run before writing
- Never --force without user request
- Exit codes: 0=success, 1=error, 2=cancelled
- All commands deterministic and safe to retry

---

## Features

### Validate specs
specleft features validate --format json [--dir PATH] [--strict]
Always validate before generating tests. --strict treats warnings as errors.

### List features
specleft features list --format json [--dir PATH]

### Show stats
specleft features stats --format json [--dir PATH] [-t TESTS_DIR]

### Add a feature
specleft features add --format json --id  --title "Title" [--priority critical|high|medium|low] [--description TEXT] [--dir PATH] [--dry-run]
Creates features/.md. Never overwrites existing files. Use --interactive for guided prompts (TTY only).

### Add a scenario
specleft features add-scenario --format json --feature  --title "Title" [--id SCENARIO_ID] [--step "Given ..." --step "When ..." --step "Then ..."] [--priority critical|high|medium|low] [--tags "tag1,tag2"] [--dir PATH] [--tests-dir PATH] [--dry-run] [--add-test stub|skeleton] [--preview-test]
Appends to feature file. --add-test generates test file. --preview-test shows test content without writing. Use --interactive for guided prompts (TTY only).

## Status & Planning

### Show status
specleft status --format json [--dir PATH] [--feature ID] [--story ID] [--unimplemented] [--implemented]

### Next to implement
specleft next --format json [--dir PATH] [--limit N] [--priority critical|high|medium|low] [--feature ID] [--story ID]

### Coverage metrics
specleft coverage --format json [--dir PATH] [--threshold N] [--output PATH]
--threshold N exits non-zero if coverage below N%.

## Test Generation

### Generate skeleton tests
specleft test skeleton --format json [-f FEATURES_DIR] [-o OUTPUT_DIR] [--dry-run] [--force] [--single-file] [--skip-preview]
ALWAYS --dry-run first. Skeletons are skipped by default. Never overwrites without --force.

### Generate stub tests
specleft test stub --format json [-f FEATURES_DIR] [-o OUTPUT_DIR] [--dry-run] [--force] [--single-file] [--skip-preview]
Minimal test stubs. Same safety rules as skeleton.

### Generate test report
specleft test report --format json [-r RESULTS_FILE] [-o OUTPUT_PATH] [--open-browser]
HTML report from latest results in .specleft/results/.

## Planning

### Generate specs from PRD
specleft plan --format json [--from PATH] [--dry-run] [--analyze] [--template PATH]
--analyze inspects PRD structure without writing. --template uses a YAML template for section matching.

## Contract

### Show contract
specleft contract --format json

### Verify contract
specleft contract test --format json [--verbose]
Run once to verify safety guarantees hold.

## Enforcement

### Enforce policy
specleft enforce [POLICY_FILE] --format json [--dir PATH] [--tests PATH] [--ignore-feature-id ID]
Default policy: .specleft/licenses/policy.yml. --ignore-feature-id excludes features (Enforce+ tier, repeatable).
Exit codes: 0=satisfied, 1=violated, 2=license issue (invalid/expired/repo mismatch).

## License

### License status
specleft license status [--file PATH]
Show license status and validated policy. Default: .specleft/licenses/policy.yml.

## Guide

### Show workflow guide
specleft guide --format json

Acceptance Criteria

1. specleft init creates the skill file in to directory .specleft/SKILL.md
2. docs/SKILL.md content is overwritten with the new SKILL.md
3. If .specleft/SKILL.md exists already - then optimised print warning with the exit code 2. Warning: "Skipped creation. Specleft SKILL.md exists already."
4. Tests written to verify skill is created on the command

[Dimwiddle]

Implementation Notes

Branch: 95-specleft-skill-file
Approach: Add a packaged SKILL template source and wire specleft init to create .specleft/SKILL.md safely, including idempotent skip behavior and tests.

Decisions

• Use docs/SKILL.md as the canonical template source so generated skill guidance stays aligned with docs.
• Treat existing .specleft/SKILL.md as a non-destructive skip with exit code 2 and warning text per acceptance criteria.

Tasks

• Create/update canonical SKILL template content in docs/SKILL.md
• Extend specleft init to create .specleft/SKILL.md from the canonical template
• Add existing-file guard with warning and exit code 2
• Add/adjust tests covering creation and skip behavior
• Run lint and tests and fix regressions

[Dimwiddle]

Implementation update: all planned tasks for 95-specleft-skill-file are complete and pushed.

• Create/update canonical SKILL template content in docs/SKILL.md
• Extend specleft init to create .specleft/SKILL.md from the canonical template
• Add existing-file guard with warning and exit code 2
• Add/adjust tests covering creation and skip behavior
• Run lint and tests and fix regressions

Commit: 91dfb1b

[Dimwiddle]

Security update complete and pushed on 95-specleft-skill-file.

• Added new specleft skill command group with verify and update
• Made specleft init idempotent for existing .specleft/SKILL.md (warning + exit 0)
• Added checksum artifact .specleft/SKILL.md.sha256 generation
• Added doctor --verify-skill delegation
• Implemented integrity states: pass, modified, outdated
• Added contract guarantees under guarantees.skill_security
• Updated docs/SKILL.md for the new command group
• Added tests for all new flows

Validation:

• make lint passed
• make test passed (448 passed)

Commit: d3ad329