feat: Milestone 0 — project foundation and package skeleton (v0.1.0)

[shaypal5]

Summary

Bootstraps the leadforge codebase from empty to a fully installable, lint-clean, tested package skeleton. This is the complete Milestone 0 delivery.

All acceptance criteria pass:

• pip install -e . ✓
• leadforge --help shows all four commands ✓
• leadforge list-recipes returns b2b_saas_procurement_v1 ✓
• 20 tests passing ✓
• ruff + mypy clean ✓
• CI configured ✓

What's included

Package scaffold

• pyproject.toml — setuptools build, Typer + PyYAML runtime, ruff/mypy/pytest dev deps, leadforge CLI entry point
• Full subpackage skeleton (api, cli, core, narrative, schema, structure, mechanisms, simulation, render, exposure, validation, recipes) with __init__.py stubs
• README.md — install, CLI quickstart, Python API snippet, doc links
• .pre-commit-config.yaml — ruff (lint + format) + pre-commit-hooks

Core primitives (leadforge/core/)

• enums.py — ExposureMode + DifficultyProfile as StrEnum
• exceptions.py — LeadforgeError base + 6 typed subclasses
• models.py — GenerationConfig, WorldSpec, WorldBundle dataclass stubs
• rng.py, ids.py — documented stubs (implemented in M1)

Recipe system (leadforge/recipes/)

• registry.py — list_recipes() + load_recipe() reading YAML files
• b2b_saas_procurement_v1/recipe.yaml — id, title, primary task, modes, difficulty levels

CLI (leadforge/cli/)

• main.py — Typer app with --version and four registered commands
• list-recipes — fully implemented with Rich table output
• generate — stub with full option spec per architecture doc; exits 1 with "coming in v0.2.0"
• inspect, validate — stubs with correct argument spec

CI (.github/workflows/ci.yml)

• Three jobs: lint (ruff check + format), typecheck (mypy), test matrix (Python 3.11 + 3.12)
• Coverage artifacts uploaded under pr-agent-context-coverage-py* prefix for pr-agent-context integration

Tests (20 passing)

• tests/test_cli.py — help, version, list-recipes content, stub exit codes
• tests/core/test_enums.py — values + string construction
• tests/core/test_exceptions.py — hierarchy + message preservation
• tests/recipes/test_registry.py — list/load, required fields, error case

Test plan

• CI passes (lint, typecheck, test matrix)
• leadforge --help shows all four commands
• leadforge list-recipes shows b2b_saas_procurement_v1
• leadforge --version prints leadforge 0.1.0

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Bootstraps the leadforge repository into an installable Python package with a Typer-based CLI, an initial YAML-backed recipe registry, CI/tooling configuration, and a baseline test suite to support future milestones.

Changes:

• Added project packaging/tooling (pyproject.toml, pre-commit, CI) and a full package/module skeleton.
• Implemented a first working CLI command (list-recipes) plus stubs for generate, inspect, validate.
• Added a YAML recipe registry + an initial b2b_saas_procurement_v1 recipe and accompanying tests.

Reviewed changes

Copilot reviewed 23 out of 44 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/test_cli.py	CLI smoke tests for help/version and command stubs
tests/recipes/test_registry.py	Tests for recipe listing/loading and error case
tests/recipes/init.py	Test package marker
tests/core/test_exceptions.py	Exception hierarchy tests
tests/core/test_enums.py	Enum value/from-string tests
tests/core/init.py	Test package marker
tests/init.py	Test package marker
pyproject.toml	Packaging metadata, deps, ruff/mypy/pytest configuration
leadforge/version.py	Defines __version__
leadforge/validation/init.py	Subpackage stub
leadforge/structure/init.py	Subpackage stub
leadforge/simulation/init.py	Subpackage stub
leadforge/schema/init.py	Subpackage stub
leadforge/sample_data/public/.gitkeep	Placeholder for sample data
leadforge/sample_data/instructor/.gitkeep	Placeholder for sample data
leadforge/render/init.py	Subpackage stub
leadforge/recipes/registry.py	Implements recipe discovery/loading from YAML
leadforge/recipes/b2b_saas_procurement_v1/recipe.yaml	Adds initial recipe metadata YAML
leadforge/recipes/b2b_saas_procurement_v1/init.py	Subpackage stub
leadforge/recipes/init.py	Subpackage stub
leadforge/narrative/init.py	Subpackage stub
leadforge/mechanisms/init.py	Subpackage stub
leadforge/exposure/init.py	Subpackage stub
leadforge/examples/notebooks/.gitkeep	Placeholder for examples
leadforge/examples/configs/.gitkeep	Placeholder for examples
leadforge/core/rng.py	RNG utilities stub docstring
leadforge/core/models.py	Dataclass stubs for config/spec/bundle
leadforge/core/ids.py	ID scheme stub docstring
leadforge/core/exceptions.py	Defines project exception hierarchy
leadforge/core/enums.py	Defines ExposureMode / DifficultyProfile
leadforge/core/init.py	Core subpackage stub
leadforge/cli/main.py	Typer app entrypoint + command registration
leadforge/cli/commands/validate.py	validate command stub
leadforge/cli/commands/list_recipes.py	list-recipes command implementation (Rich table)
leadforge/cli/commands/inspect.py	inspect command stub
leadforge/cli/commands/generate.py	generate command stub + option surface
leadforge/cli/commands/init.py	Commands subpackage stub
leadforge/cli/init.py	CLI subpackage stub
leadforge/api/init.py	API subpackage stub
leadforge/init.py	Package init exporting __version__
README.md	Project README with install/quickstart/docs links
.pre-commit-config.yaml	Pre-commit hooks (ruff, formatting, basic checks)
.github/workflows/ci.yml	CI for lint/typecheck/tests with coverage artifacts
.agent-plan.md	Updates project plan to mark M0 complete / M1 next

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 45 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

pr-agent-context report:

This run includes unresolved review comments on PR #3.

For each unresolved review comment, recommend one of: resolve as irrelevant, accept and implement
the recommended solution, open a separate issue and resolve as out-of-scope for this PR, accept and
implement a different solution, or resolve as already treated by the code.

After I reply with my decision per item, implement the accepted actions, resolve the corresponding
PR comments, and push all of these changes in a single commit.

# Copilot Comments

## COPILOT-1
Location: leadforge/recipes/registry.py
URL: https://github.com/leadforge-dev/leadforge/pull/3#discussion_r3105050071
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The path traversal guard is bypassable because it uses a string prefix check. For example, a resolved path like `/.../recipes_evil` will still start with `/.../recipes`, so `recipe_id='../recipes_evil'` can incorrectly pass this check. Use `Path.is_relative_to()` (Py3.11+) or `recipe_dir.relative_to(base_dir)` in a try/except to ensure the resolved path is actually within `_RECIPES_DIR`.
    ~~~suggestion
        base_dir = _RECIPES_DIR.resolve()
        recipe_dir = (base_dir / recipe_id).resolve()
        try:
            recipe_dir.relative_to(base_dir)
        except ValueError:
    ~~~

## COPILOT-2
Location: pyproject.toml
URL: https://github.com/leadforge-dev/leadforge/pull/3#discussion_r3105050075
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The Ruff per-file-ignores glob `tests/*` only matches files directly under `tests/` and won’t apply to tests in subdirectories like `tests/core/...` or `tests/recipes/...`. If the intent is to ignore rules across the whole test tree, use `tests/**` (or similar). Also, `S101` is currently a no-op unless the `S` ruleset is enabled in `select`.

Run metadata:

Tool ref: v4
Tool version: 4.0.18
Trigger: commit pushed
Workflow run: 24606387604 attempt 1
Comment timestamp: 2026-04-18T14:07:41.401806+00:00
PR head commit: ac22ad52c0c25ff581cb8af14d2a97de9b664c63

[Copilot]

Pull request overview

Copilot reviewed 26 out of 46 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.