From b67457f7c5caec2ab8ee6ebb6d9f33fc08901d6f Mon Sep 17 00:00:00 2001
From: Chris Krough <461869+ckrough@users.noreply.github.com>
Date: Fri, 9 Jan 2026 10:10:13 -0500
Subject: [PATCH] feat: add project create command with E2E integration tests

Add `agentspaces project create` command for initializing new projects:
- Creates project skeleton (CLAUDE.md, README.md, docs/, .claude/)
- Optional Python language pack with --python flag (pyproject.toml, ruff, mypy, pytest, pre-commit, GitHub Actions)
- Runs git init if not already a git repo
- Shows preview and asks for confirmation

Also adds comprehensive E2E integration tests:
- 23 tests across 6 categories (basic, python naming, errors, content, git, edge cases)
- pytest integration marker for selective test runs
- Isolated test fixtures with temp directories and git config isolation

Other changes:
- Remove docs scaffold command (replaced by project create)
- Remove TODO.md and deployment templates (Beads replaces planning)
- Add task description standards to CLAUDE.md for Beads issues
- Update documentation with new command usage
---
 CLAUDE.md                                     |  47 +-
 README.md                                     |  15 +-
 pyproject.toml                                |   3 +
 src/agentspaces/cli/app.py                    |   3 +-
 src/agentspaces/cli/docs.py                   |  97 ----
 src/agentspaces/cli/project.py                | 306 +++++++++++++
 src/agentspaces/infrastructure/design.py      |  89 ++++
 src/agentspaces/infrastructure/git.py         |  14 +
 src/agentspaces/infrastructure/resources.py   |  24 +
 src/agentspaces/infrastructure/skeleton.py    |  45 ++
 .../languages/python/dot_github-ci.md         |  51 +++
 .../languages/python/dot_gitignore-python.md  |  69 +++
 .../languages/python/dot_pre-commit-config.md |  33 ++
 .../languages/python/dot_python-version.md    |  10 +
 .../languages/python/pyproject-toml.md        | 105 +++++
 .../templates/languages/python/src-init.md    |  12 +
 .../languages/python/tests-conftest.md        |  19 +
 src/agentspaces/templates/skeleton/TODO.md    |  35 --
 .../skeleton/docs/planning/deployment.md      | 270 -----------
 tests/integration/cli/__init__.py             |   1 +
 tests/integration/cli/conftest.py             | 116 +++++
 tests/integration/cli/test_project_create.py  | 430 ++++++++++++++++++
 tests/unit/infrastructure/test_design.py      |   2 -
 tests/unit/infrastructure/test_resources.py   |   4 +-
 24 files changed, 1385 insertions(+), 415 deletions(-)
 create mode 100644 src/agentspaces/cli/project.py
 create mode 100644 src/agentspaces/infrastructure/skeleton.py
 create mode 100644 src/agentspaces/templates/languages/python/dot_github-ci.md
 create mode 100644 src/agentspaces/templates/languages/python/dot_gitignore-python.md
 create mode 100644 src/agentspaces/templates/languages/python/dot_pre-commit-config.md
 create mode 100644 src/agentspaces/templates/languages/python/dot_python-version.md
 create mode 100644 src/agentspaces/templates/languages/python/pyproject-toml.md
 create mode 100644 src/agentspaces/templates/languages/python/src-init.md
 create mode 100644 src/agentspaces/templates/languages/python/tests-conftest.md
 delete mode 100644 src/agentspaces/templates/skeleton/TODO.md
 delete mode 100644 src/agentspaces/templates/skeleton/docs/planning/deployment.md
 create mode 100644 tests/integration/cli/__init__.py
 create mode 100644 tests/integration/cli/conftest.py
 create mode 100644 tests/integration/cli/test_project_create.py

diff --git a/CLAUDE.md b/CLAUDE.md
index 0a9e11c..2310afe 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,6 +22,7 @@ src/agentspaces/
 ├── main.py                    # CLI entry point
 ├── cli/                       # Typer commands
 │   ├── app.py                 # Main app
+│   ├── project.py             # Project initialization
 │   ├── workspace.py           # Workspace subcommands
 │   └── docs.py                # Design template commands
 ├── modules/
@@ -33,15 +34,17 @@ src/agentspaces/
 │   ├── naming.py              # Name generation
 │   ├── paths.py               # Path resolution
 │   ├── design.py              # Template rendering
+│   ├── skeleton.py            # Project structure definitions
 │   ├── resources.py           # Package resource access
 │   ├── frontmatter.py         # YAML frontmatter parser
 │   └── logging.py             # structlog config
 └── templates/                 # Bundled project templates
-    └── skeleton/              # Project skeleton templates
-        ├── CLAUDE.md          # Agent constitution template
-        ├── TODO.md            # Task list template
-        ├── .claude/           # Agent/command templates
-        └── docs/              # ADR and design templates
+    ├── skeleton/              # Project skeleton templates
+    │   ├── CLAUDE.md          # Agent constitution template
+    │   ├── .claude/           # Agent/command templates
+    │   └── docs/              # ADR and design templates
+    └── languages/             # Language-specific packs
+        └── python/            # Python tooling templates
 ```
 
 ## Architecture
@@ -70,6 +73,10 @@ A workspace is:
 ## Commands
 
 ```bash
+# Project initialization
+agentspaces project create              # Initialize new project in current dir
+agentspaces project create --python     # With Python language pack
+
 # Workspaces
 agentspaces workspace create [branch]   # Create workspace
 agentspaces workspace list              # List workspaces
@@ -152,7 +159,6 @@ See [RELEASING.md](RELEASING.md) for full details on versioning and releases.
 
 ## Documentation
 
-- [TODO.md](TODO.md) - Active task list
 - [CONTRIBUTING.md](CONTRIBUTING.md) - Development guide
 - [RELEASING.md](RELEASING.md) - Version management and release process
 - [CHANGELOG.md](CHANGELOG.md) - Project changelog (auto-generated)
@@ -168,7 +174,7 @@ Use [Beads](https://github.com/steveyegge/beads) for lightweight issue tracking
 bd ready --json
 
 # Create issues
-bd create "title" -t <type> -p <priority>
+bd create "title" -t <type> -p <priority> -d <task details>
 # Types: feature, bug, task, chore
 # Priority: 1 (critical) to 4 (low)
 
@@ -185,6 +191,33 @@ bd dep add <new-id> <current-id> --type discovered-from
 bd sync
 ```
 
+### Task Description Standards
+
+When creating Beads issues, include comprehensive standalone context so tasks can be independently executed by an agent without conversation history:
+
+- **Context**: What system/command is involved, relevant source files
+- **Goal**: Specific objective of the task
+- **Implementation**: Code examples, file paths, specific steps
+- **Dependencies**: What other tasks/files are prerequisites
+- **Verification**: Commands to confirm task completion
+
+Example:
+```bash
+bd create "Add validation to user input" -t task -p 2 -d "## Context
+The user registration form in src/api/routes/auth.py accepts email without validation.
+
+## Goal
+Add email format validation before creating user accounts.
+
+## Implementation
+1. Add email-validator to dependencies in pyproject.toml
+2. Create validate_email() in src/api/validators.py
+3. Call validator in register_user() route handler
+
+## Verification
+uv run pytest tests/api/test_auth.py -k email_validation"
+```
+
 ## Learned Patterns
 
 <!-- Add entries when Claude makes mistakes. Format: When X happens, do Y instead of Z -->
diff --git a/README.md b/README.md
index fba2b28..1ca88ad 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,10 @@ Workspace orchestration for AI coding agents. Manage isolated workspaces for par
 
 ## Features
 
+- **Project Initialization** - Create new projects with templates, documentation, and Python tooling
 - **Parallel Development** - Work on multiple features simultaneously without branch switching
 - **Isolated Environments** - Each workspace has its own Python venv and dependencies
-- **Project Templates** - Generate documentation optimized for AI agents (CLAUDE.md, TODO.md, ADRs)
+- **Project Templates** - Generate documentation optimized for AI agents (CLAUDE.md, ADRs, architecture docs)
 - **Workspace Tracking** - Purpose, metadata, and timestamps per workspace
 
 ## Quick Start
@@ -36,6 +37,16 @@ agentspaces workspace create main --purpose "Add user authentication"
 
 ## Usage
 
+### Initialize a New Project
+
+```bash
+mkdir my-project && cd my-project
+agentspaces project create -n "My Project" -d "Description"
+
+# With Python tooling (pyproject.toml, ruff, mypy, pytest, GitHub Actions)
+agentspaces project create --python -n "My CLI" -d "A CLI tool"
+```
+
 ### Workspace Commands
 
 ```bash
@@ -53,7 +64,7 @@ agentspaces docs info <template>         # Show template details
 agentspaces docs create <template>       # Generate from template
 ```
 
-Available templates: `readme`, `claude-md`, `todo-md`, `architecture`, `development-standards`, `deployment`, `adr-template`
+Available templates: `readme`, `claude-md`, `architecture`, `development-standards`, `adr-template`
 
 ## Configuration
 
diff --git a/pyproject.toml b/pyproject.toml
index 66faac8..6d2e1b4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -107,6 +107,9 @@ testpaths = ["tests"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 addopts = "-v --tb=short"
+markers = [
+    "integration: marks tests as integration tests (deselect with '-m \"not integration\"')",
+]
 
 [tool.coverage.run]
 source = ["src"]
diff --git a/src/agentspaces/cli/app.py b/src/agentspaces/cli/app.py
index d170d16..87d1bf3 100644
--- a/src/agentspaces/cli/app.py
+++ b/src/agentspaces/cli/app.py
@@ -5,7 +5,7 @@
 import typer
 
 from agentspaces import __version__
-from agentspaces.cli import docs, workspace
+from agentspaces.cli import docs, project, workspace
 from agentspaces.infrastructure.logging import configure_logging
 
 # Main application
@@ -18,6 +18,7 @@
 
 # Register subcommand groups
 app.add_typer(docs.app, name="docs")
+app.add_typer(project.app, name="project")
 app.add_typer(workspace.app, name="workspace")
 
 
diff --git a/src/agentspaces/cli/docs.py b/src/agentspaces/cli/docs.py
index 7ccfaa6..de94bc7 100644
--- a/src/agentspaces/cli/docs.py
+++ b/src/agentspaces/cli/docs.py
@@ -250,100 +250,3 @@ def create(
         raise typer.Exit(1) from e
 
     console.print(f"[green]✓[/green] Created: {result_path}")
-
-
-# Mapping of template names to their output paths relative to project root
-SCAFFOLD_STRUCTURE: dict[str, str] = {
-    # Root files
-    "readme": "README.md",
-    "claude-md": "CLAUDE.md",
-    "todo-md": "TODO.md",
-    # .claude directory
-    "agents-readme": ".claude/agents/README.md",
-    "commands-readme": ".claude/commands/README.md",
-    # Design docs
-    "architecture": "docs/design/architecture.md",
-    "development-standards": "docs/design/development-standards.md",
-    # Planning/operational
-    "deployment": "docs/planning/deployment.md",
-    # ADR
-    "adr-template": "docs/adr/000-template.md",
-    "adr-example": "docs/adr/001-example.md",
-}
-
-
-@app.command("scaffold")
-def scaffold(
-    target: Annotated[
-        Path,
-        typer.Argument(help="Target directory to scaffold (created if needed)"),
-    ],
-    project_name: Annotated[
-        str,
-        typer.Option("--project-name", "-n", help="Project name"),
-    ],
-    project_description: Annotated[
-        str,
-        typer.Option("--project-description", "-d", help="Project description"),
-    ],
-    force: Annotated[
-        bool,
-        typer.Option("--force", "-f", help="Overwrite existing files"),
-    ] = False,
-) -> None:
-    """Create all documentation templates in a new project directory.
-
-    Scaffolds a complete project documentation structure with all templates
-    pre-populated with your project name and description.
-
-    \b
-    Examples:
-        agentspaces docs scaffold ./my-project -n "MyApp" -d "A web application"
-        agentspaces docs scaffold /tmp/new-proj -n "CLI Tool" -d "Command-line utility" -f
-    """
-    # Create target directory
-    target = target.resolve()
-    target.mkdir(parents=True, exist_ok=True)
-
-    context: dict[str, Any] = {
-        "project_name": project_name,
-        "project_description": project_description,
-        # Defaults for ADR template
-        "adr_number": "000",
-        "adr_title": "ADR Template",
-    }
-
-    created: list[Path] = []
-    skipped: list[Path] = []
-
-    for template_name, relative_path in SCAFFOLD_STRUCTURE.items():
-        output_path = target / relative_path
-
-        # Check for existing file
-        if output_path.exists() and not force:
-            skipped.append(output_path)
-            continue
-
-        # Create parent directories
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-
-        try:
-            render_design_template(template_name, context, output_path)
-            created.append(output_path)
-        except DesignError as e:
-            error_console.print(f"[red]✗[/red] {template_name}: {e}")
-
-    # Summary
-    console.print()
-    if created:
-        console.print(f"[green]✓[/green] Created {len(created)} files in {target}")
-        for path in created:
-            rel = path.relative_to(target)
-            console.print(f"  [dim]•[/dim] {rel}")
-
-    if skipped:
-        console.print(f"\n[yellow]![/yellow] Skipped {len(skipped)} existing files")
-        for path in skipped:
-            rel = path.relative_to(target)
-            console.print(f"  [dim]•[/dim] {rel}")
-        console.print("[dim]Use --force to overwrite[/dim]")
diff --git a/src/agentspaces/cli/project.py b/src/agentspaces/cli/project.py
new file mode 100644
index 0000000..ffd3d27
--- /dev/null
+++ b/src/agentspaces/cli/project.py
@@ -0,0 +1,306 @@
+"""Project initialization CLI commands."""
+
+from __future__ import annotations
+
+import keyword
+import re
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from agentspaces.infrastructure import git
+from agentspaces.infrastructure.design import (
+    DesignError,
+    render_design_template,
+    render_language_template,
+)
+from agentspaces.infrastructure.skeleton import PYTHON_STRUCTURE, SKELETON_STRUCTURE
+
+app = typer.Typer(
+    name="project",
+    help="Initialize new projects with templates and best practices.",
+    no_args_is_help=True,
+)
+
+console = Console()
+error_console = Console(stderr=True)
+
+
+def _is_valid_python_package_name(name: str) -> bool:
+    """Check if name is a valid Python package name."""
+    # Must start with letter, contain only letters, numbers, underscores
+    return bool(re.match(r"^[a-zA-Z][a-zA-Z0-9_]*$", name))
+
+
+def _to_package_name(project_name: str) -> str:
+    """Convert project name to valid Python package name."""
+    # Replace spaces and hyphens with underscores, lowercase
+    package_name = project_name.lower().replace(" ", "_").replace("-", "_")
+    # Remove any invalid characters
+    package_name = re.sub(r"[^a-z0-9_]", "", package_name)
+    # Ensure it starts with a letter
+    if package_name and not package_name[0].isalpha():
+        package_name = "pkg_" + package_name
+    package_name = package_name or "project"
+    # Avoid Python keywords
+    if keyword.iskeyword(package_name):
+        package_name = f"{package_name}_pkg"
+    return package_name
+
+
+def _validate_output_path(output_path: Path, cwd: Path) -> None:
+    """Validate that output path stays within the project directory.
+
+    Args:
+        output_path: Path to validate.
+        cwd: Project root directory.
+
+    Raises:
+        ValueError: If path escapes project directory.
+    """
+    try:
+        output_path.resolve().relative_to(cwd.resolve())
+    except ValueError as e:
+        raise ValueError(
+            f"Invalid path escapes project directory: {output_path}"
+        ) from e
+
+
+def _is_directory_empty(path: Path) -> bool:
+    """Check if directory is empty (ignoring hidden files like .git)."""
+    if not path.exists():
+        return True
+    # Allow .git directory but nothing else
+    contents = list(path.iterdir())
+    non_git = [f for f in contents if f.name != ".git"]
+    return len(non_git) == 0
+
+
+def _print_preview(
+    project_name: str,
+    project_description: str,
+    python: bool,
+    python_version: str,
+    will_init_git: bool,
+) -> None:
+    """Print preview of what will be created."""
+    console.print("\n[bold]Project Configuration[/bold]")
+    console.print(f"  Name:        [cyan]{project_name}[/cyan]")
+    console.print(f"  Description: {project_description}")
+    if python:
+        package_name = _to_package_name(project_name)
+        console.print(f"  Language:    [green]Python {python_version}[/green]")
+        console.print(f"  Package:     [dim]{package_name}[/dim]")
+
+    console.print("\n[bold]Files to create:[/bold]")
+
+    # Base skeleton
+    console.print("\n  [dim]Base skeleton:[/dim]")
+    for relative_path in sorted(SKELETON_STRUCTURE.values()):
+        console.print(f"    [dim]•[/dim] {relative_path}")
+
+    # Python language pack
+    if python:
+        package_name = _to_package_name(project_name)
+        console.print("\n  [dim]Python language pack:[/dim]")
+        for relative_path in sorted(PYTHON_STRUCTURE.values()):
+            # Replace {package_name} placeholder
+            display_path = relative_path.replace("{package_name}", package_name)
+            console.print(f"    [dim]•[/dim] {display_path}")
+
+    if will_init_git:
+        console.print("\n[blue]Git repository will be initialized.[/blue]")
+
+    console.print()
+
+
+def _print_success(
+    path: Path,
+    created_count: int,
+    python: bool,
+    python_version: str,
+) -> None:
+    """Print success message with next steps."""
+    lines = [
+        f"[bold]Location:[/bold] {path}",
+        f"[bold]Files:[/bold]    {created_count} created",
+    ]
+    if python:
+        lines.append(f"[bold]Python:[/bold]   {python_version}")
+
+    panel = Panel(
+        "\n".join(lines),
+        title="[green]Project Created[/green]",
+        border_style="green",
+    )
+    console.print(panel)
+
+    # Next steps
+    next_steps = ["cd " + str(path)]
+    if python:
+        next_steps.extend(
+            [
+                "uv sync --all-extras",
+                "uv run pre-commit install",
+            ]
+        )
+    next_steps.append("Start coding!")
+
+    step_lines = [
+        f"  {i + 1}. [cyan]{step}[/cyan]" for i, step in enumerate(next_steps)
+    ]
+    next_panel = Panel(
+        "\n".join(step_lines),
+        title="[blue]Next Steps[/blue]",
+        border_style="blue",
+    )
+    console.print(next_panel)
+
+
+@app.command("create")
+def create(
+    project_name: Annotated[
+        str | None,
+        typer.Option("--name", "-n", help="Project name"),
+    ] = None,
+    project_description: Annotated[
+        str | None,
+        typer.Option("--description", "-d", help="Project description"),
+    ] = None,
+    python: Annotated[
+        bool,
+        typer.Option("--python", "-p", help="Include Python language pack"),
+    ] = False,
+    python_version: Annotated[
+        str,
+        typer.Option("--python-version", help="Python version (default: 3.13)"),
+    ] = "3.13",
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip confirmation prompt"),
+    ] = False,
+) -> None:
+    """Initialize a new project in the current directory.
+
+    Creates a complete project skeleton with documentation templates,
+    development standards, and optionally a Python language pack.
+
+    The current directory must be empty (or contain only .git).
+
+    \b
+    Examples:
+        agentspaces project create -n "My Project" -d "A cool project"
+        agentspaces project create --python -n "CLI Tool" -d "Command-line app"
+        agentspaces project create -p -n "api" -d "REST API" --python-version 3.12
+        agentspaces project create -y -n "quick" -d "Quick start"  # Skip confirmation
+    """
+    cwd = Path.cwd()
+
+    # Validate directory is empty
+    if not _is_directory_empty(cwd):
+        error_console.print(
+            "[red]✗[/red] Directory is not empty. "
+            "Project initialization requires an empty directory."
+        )
+        console.print("[dim]Create a new directory and cd into it first.[/dim]")
+        raise typer.Exit(1)
+
+    # Prompt for required values if not provided
+    if not project_name:
+        project_name = typer.prompt("Project name")
+    if not project_description:
+        project_description = typer.prompt("Project description")
+
+    # Validate Python package name if using Python pack
+    if python:
+        package_name = _to_package_name(project_name)
+        if not _is_valid_python_package_name(package_name):
+            error_console.print(
+                f"[red]✗[/red] Cannot create valid Python package name from '{project_name}'"
+            )
+            raise typer.Exit(1)
+
+    # Check if we need to init git
+    will_init_git = not git.is_git_repo(cwd)
+
+    # Show preview and confirm
+    if not yes:
+        _print_preview(
+            project_name=project_name,
+            project_description=project_description,
+            python=python,
+            python_version=python_version,
+            will_init_git=will_init_git,
+        )
+
+        if not typer.confirm("Continue?", default=True):
+            console.print("[dim]Cancelled[/dim]")
+            raise typer.Exit(0)
+
+    # Initialize git if needed
+    if will_init_git:
+        try:
+            git.init(cwd)
+            console.print("[green]✓[/green] Initialized git repository")
+        except git.GitError as e:
+            error_console.print(f"[red]✗[/red] Failed to initialize git: {e}")
+            raise typer.Exit(1) from e
+
+    # Build template context
+    context: dict[str, Any] = {
+        "project_name": project_name,
+        "project_description": project_description,
+    }
+
+    if python:
+        context["python_version"] = python_version
+        context["package_name"] = _to_package_name(project_name)
+
+    # Track results
+    created: list[Path] = []
+    failed: list[tuple[str, str]] = []
+
+    # Render skeleton templates
+    for template_name, relative_path in SKELETON_STRUCTURE.items():
+        output_path = cwd / relative_path
+        try:
+            _validate_output_path(output_path, cwd)
+            render_design_template(template_name, context, output_path)
+            created.append(output_path)
+        except (DesignError, ValueError) as e:
+            failed.append((template_name, str(e)))
+
+    # Render Python language pack if requested
+    if python:
+        package_name = _to_package_name(project_name)
+        for template_name, relative_path in PYTHON_STRUCTURE.items():
+            # Replace {package_name} placeholder in path
+            actual_path = relative_path.replace("{package_name}", package_name)
+            output_path = cwd / actual_path
+            try:
+                _validate_output_path(output_path, cwd)
+                render_language_template("python", template_name, context, output_path)
+                created.append(output_path)
+            except (DesignError, ValueError) as e:
+                failed.append((template_name, str(e)))
+
+    # Report results
+    if failed:
+        console.print()
+        for template_name, error in failed:
+            error_console.print(f"[red]✗[/red] {template_name}: {error}")
+
+    if created:
+        _print_success(
+            path=cwd,
+            created_count=len(created),
+            python=python,
+            python_version=python_version,
+        )
+
+    if failed and not created:
+        error_console.print("[red]✗[/red] Project creation failed")
+        raise typer.Exit(1)
diff --git a/src/agentspaces/infrastructure/design.py b/src/agentspaces/infrastructure/design.py
index 40b14d7..0f51491 100644
--- a/src/agentspaces/infrastructure/design.py
+++ b/src/agentspaces/infrastructure/design.py
@@ -21,6 +21,7 @@
 from agentspaces.infrastructure.frontmatter import FrontmatterError, parse_frontmatter
 from agentspaces.infrastructure.resources import (
     ResourceError,
+    get_language_templates_dir,
     get_skeleton_templates_dir,
 )
 
@@ -33,6 +34,7 @@
     "get_design_template",
     "list_design_templates",
     "render_design_template",
+    "render_language_template",
 ]
 
 logger = structlog.get_logger()
@@ -285,3 +287,90 @@ def render_design_template(
     )
 
     return output_path
+
+
+def render_language_template(
+    language: str,
+    template_name: str,
+    context: dict[str, Any],
+    output_path: Path,
+) -> Path:
+    """Render a language pack template with the given context.
+
+    Unlike design templates, language templates output raw content without
+    YAML frontmatter (suitable for config files like pyproject.toml).
+
+    Args:
+        language: Language pack name (e.g., "python").
+        template_name: Template name (e.g., "pyproject-toml").
+        context: Variables to pass to the template.
+        output_path: Where to write the rendered file.
+
+    Returns:
+        Path to the generated file.
+
+    Raises:
+        DesignError: If rendering fails.
+    """
+    # Validate template_name to prevent path traversal
+    if "/" in template_name or "\\" in template_name or ".." in template_name:
+        raise DesignError(f"Invalid template name: {template_name}")
+
+    # Get language templates directory
+    try:
+        lang_dir = get_language_templates_dir(language)
+    except ResourceError as e:
+        raise DesignError(str(e)) from e
+
+    # Find template file
+    template_path = lang_dir / f"{template_name}.md"
+    if not template_path.exists():
+        raise DesignError(
+            f"Template '{template_name}' not found in {language} language pack"
+        )
+
+    # Read and parse template
+    try:
+        content = template_path.read_text(encoding="utf-8")
+    except OSError as e:
+        raise DesignError(f"Cannot read template: {e}") from e
+
+    try:
+        _, body = parse_frontmatter(content)
+    except FrontmatterError as e:
+        raise DesignError(f"Invalid template frontmatter: {e}") from e
+
+    # Set up Jinja2 environment
+    env = Environment(
+        loader=FileSystemLoader(str(template_path.parent)),
+        autoescape=False,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+    # Render the body (without frontmatter in output)
+    try:
+        jinja_template = env.from_string(body)
+        rendered = jinja_template.render(**context)
+    except TemplateNotFound as e:
+        raise DesignError(f"Template include not found: {e}") from e
+    except UndefinedError as e:
+        raise DesignError(f"Undefined variable in template: {e}") from e
+    except Exception as e:
+        raise DesignError(f"Template rendering failed: {e}") from e
+
+    # Ensure output directory exists and write file
+    try:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered, encoding="utf-8")
+    except OSError as e:
+        raise DesignError(f"Cannot write output file: {e}") from e
+
+    logger.debug(
+        "language_template_rendered",
+        language=language,
+        template=template_name,
+        output=str(output_path),
+    )
+
+    return output_path
diff --git a/src/agentspaces/infrastructure/git.py b/src/agentspaces/infrastructure/git.py
index 548368b..5ad34c9 100644
--- a/src/agentspaces/infrastructure/git.py
+++ b/src/agentspaces/infrastructure/git.py
@@ -23,6 +23,7 @@
     "get_main_git_dir",
     "get_repo_name",
     "get_repo_root",
+    "init",
     "is_dirty",
     "is_git_repo",
     "is_in_worktree",
@@ -372,6 +373,19 @@ def is_git_repo(path: Path) -> bool:
     return result.returncode == 0
 
 
+def init(path: Path | None = None) -> None:
+    """Initialize a new git repository.
+
+    Args:
+        path: Directory to initialize (defaults to current directory).
+
+    Raises:
+        GitError: If initialization fails.
+    """
+    logger.info("git_init", path=str(path) if path else None)
+    _run_git(["init"], cwd=path)
+
+
 def is_dirty(cwd: Path | None = None) -> bool:
     """Check if the repository has uncommitted changes.
 
diff --git a/src/agentspaces/infrastructure/resources.py b/src/agentspaces/infrastructure/resources.py
index bef2a6f..c2113a1 100644
--- a/src/agentspaces/infrastructure/resources.py
+++ b/src/agentspaces/infrastructure/resources.py
@@ -14,6 +14,7 @@
 
 __all__ = [
     "ResourceError",
+    "get_language_templates_dir",
     "get_skeleton_templates_dir",
     "get_skills_templates_dir",
 ]
@@ -93,3 +94,26 @@ def get_skills_templates_dir() -> Path:
         raise ResourceError(f"Skills templates directory not found: {skills_dir}")
 
     return skills_dir
+
+
+def get_language_templates_dir(language: str) -> Path:
+    """Get the templates directory for a specific language pack.
+
+    Args:
+        language: Language name (e.g., "python").
+
+    Returns:
+        Path to the templates/languages/{language} directory.
+
+    Raises:
+        ResourceError: If the directory cannot be accessed or doesn't exist.
+    """
+    templates_dir = _get_templates_dir()
+    language_dir = templates_dir / "languages" / language
+
+    if not language_dir.exists():
+        raise ResourceError(
+            f"Language pack '{language}' not found. Expected directory: {language_dir}"
+        )
+
+    return language_dir
diff --git a/src/agentspaces/infrastructure/skeleton.py b/src/agentspaces/infrastructure/skeleton.py
new file mode 100644
index 0000000..c4dff75
--- /dev/null
+++ b/src/agentspaces/infrastructure/skeleton.py
@@ -0,0 +1,45 @@
+"""Project skeleton structure definitions.
+
+Defines the mapping between template names and their output paths for
+project initialization. Separates base skeleton (language-agnostic) from
+language-specific packs.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "PYTHON_STRUCTURE",
+    "SKELETON_STRUCTURE",
+]
+
+
+# Base project skeleton structure (language-agnostic)
+# Maps template name -> output path relative to project root
+SKELETON_STRUCTURE: dict[str, str] = {
+    # Root files
+    "readme": "README.md",
+    "claude-md": "CLAUDE.md",
+    # .claude directory
+    "agents-readme": ".claude/agents/README.md",
+    "commands-readme": ".claude/commands/README.md",
+    # Design docs
+    "architecture": "docs/design/architecture.md",
+    "development-standards": "docs/design/development-standards.md",
+    # ADR
+    "adr-template": "docs/adr/000-template.md",
+    "adr-example": "docs/adr/001-example.md",
+}
+
+
+# Python language pack structure
+# Uses chezmoi-style naming: dot_ prefix for dotfiles
+# Maps template name -> output path relative to project root
+PYTHON_STRUCTURE: dict[str, str] = {
+    "pyproject-toml": "pyproject.toml",
+    "dot_gitignore-python": ".gitignore",
+    "dot_python-version": ".python-version",
+    "dot_pre-commit-config": ".pre-commit-config.yaml",
+    "dot_github-ci": ".github/workflows/ci.yml",
+    "src-init": "src/{package_name}/__init__.py",
+    "tests-conftest": "tests/conftest.py",
+}
diff --git a/src/agentspaces/templates/languages/python/dot_github-ci.md b/src/agentspaces/templates/languages/python/dot_github-ci.md
new file mode 100644
index 0000000..355b0b9
--- /dev/null
+++ b/src/agentspaces/templates/languages/python/dot_github-ci.md
@@ -0,0 +1,51 @@
+---
+name: dot_github-ci
+description: GitHub Actions CI workflow for Python projects.
+category: python
+variables:
+  required:
+    - project_name
+  optional:
+    - python_version
+---
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install {{ python_version | default('3.13') }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linter
+        run: uv run ruff check src/ tests/
+
+      - name: Run formatter check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Run type checker
+        run: uv run mypy src/
+
+      - name: Run tests
+        run: uv run pytest --cov=src --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
diff --git a/src/agentspaces/templates/languages/python/dot_gitignore-python.md b/src/agentspaces/templates/languages/python/dot_gitignore-python.md
new file mode 100644
index 0000000..de5e85b
--- /dev/null
+++ b/src/agentspaces/templates/languages/python/dot_gitignore-python.md
@@ -0,0 +1,69 @@
+---
+name: dot_gitignore-python
+description: Python-specific .gitignore entries.
+category: python
+variables:
+  required: []
+  optional: []
+---
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# Local development
+.env
+.env.local
+*.local
+
+# OS
+.DS_Store
+Thumbs.db
diff --git a/src/agentspaces/templates/languages/python/dot_pre-commit-config.md b/src/agentspaces/templates/languages/python/dot_pre-commit-config.md
new file mode 100644
index 0000000..608b33f
--- /dev/null
+++ b/src/agentspaces/templates/languages/python/dot_pre-commit-config.md
@@ -0,0 +1,33 @@
+---
+name: dot_pre-commit-config
+description: Pre-commit hooks configuration for Python projects.
+category: python
+variables:
+  required: []
+  optional:
+    - python_version
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--strict]
diff --git a/src/agentspaces/templates/languages/python/dot_python-version.md b/src/agentspaces/templates/languages/python/dot_python-version.md
new file mode 100644
index 0000000..86880d3
--- /dev/null
+++ b/src/agentspaces/templates/languages/python/dot_python-version.md
@@ -0,0 +1,10 @@
+---
+name: dot_python-version
+description: Python version specification for pyenv/asdf.
+category: python
+variables:
+  required: []
+  optional:
+    - python_version
+---
+{{ python_version | default('3.13') }}
diff --git a/src/agentspaces/templates/languages/python/pyproject-toml.md b/src/agentspaces/templates/languages/python/pyproject-toml.md
new file mode 100644
index 0000000..712303e
--- /dev/null
+++ b/src/agentspaces/templates/languages/python/pyproject-toml.md
@@ -0,0 +1,105 @@
+---
+name: pyproject-toml
+description: Python project configuration with uv, ruff, mypy, and pytest.
+category: python
+variables:
+  required:
+    - project_name
+  optional:
+    - project_description
+    - python_version
+---
+[project]
+name = "{{ project_name | lower | replace(' ', '-') | replace('_', '-') }}"
+version = "0.1.0"
+description = "{{ project_description | default('A Python project') }}"
+readme = "README.md"
+requires-python = ">={{ python_version | default('3.13') }}"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.8",
+    "mypy>=1.13",
+    "pre-commit>=4.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ project_name | lower | replace(' ', '_') | replace('-', '_') }}"]
+
+[tool.ruff]
+target-version = "py{{ python_version | default('3.13') | replace('.', '') }}"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+    "TCH",    # flake8-type-checking
+    "PTH",    # flake8-use-pathlib
+    "ERA",    # eradicate
+    "PL",     # Pylint
+    "RUF",    # Ruff-specific
+]
+ignore = [
+    "PLR0913",  # Too many arguments
+    "PLR2004",  # Magic value comparison
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["{{ project_name | lower | replace(' ', '_') | replace('-', '_') }}"]
+
+[tool.mypy]
+python_version = "{{ python_version | default('3.13') }}"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+follow_imports = "normal"
+show_error_codes = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = [
+    "-ra",
+    "-q",
+    "--strict-markers",
+    "--strict-config",
+]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
diff --git a/src/agentspaces/templates/languages/python/src-init.md b/src/agentspaces/templates/languages/python/src-init.md
new file mode 100644
index 0000000..ac42e22
--- /dev/null
+++ b/src/agentspaces/templates/languages/python/src-init.md
@@ -0,0 +1,12 @@
+---
+name: src-init
+description: Package __init__.py with version.
+category: python
+variables:
+  required:
+    - project_name
+  optional: []
+---
+"""{{ project_name }} package."""
+
+__version__ = "0.1.0"
diff --git a/src/agentspaces/templates/languages/python/tests-conftest.md b/src/agentspaces/templates/languages/python/tests-conftest.md
new file mode 100644
index 0000000..25db7a4
--- /dev/null
+++ b/src/agentspaces/templates/languages/python/tests-conftest.md
@@ -0,0 +1,19 @@
+---
+name: tests-conftest
+description: Pytest configuration and shared fixtures.
+category: python
+variables:
+  required: []
+  optional: []
+---
+"""Pytest configuration and shared fixtures."""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture
+def sample_data() -> dict[str, str]:
+    """Provide sample test data."""
+    return {"key": "value"}
diff --git a/src/agentspaces/templates/skeleton/TODO.md b/src/agentspaces/templates/skeleton/TODO.md
deleted file mode 100644
index 134cacf..0000000
--- a/src/agentspaces/templates/skeleton/TODO.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-name: todo-md
-description: Read when starting work or checking priorities. Active/Backlog/Blocked/DONE task list.
-category: root
-when_to_use:
-  - Starting a new project
-  - Tracking development tasks
-variables:
-  required: []
-  optional:
-    - active_tasks
-    - backlog_tasks
----
-
-# TODO
-
-## Active
-{% if active_tasks %}
-{% for task in active_tasks %}
-- [ ] {{ task }}
-{% endfor %}
-{% else %}
-- [ ] Initial project setup
-{% endif %}
-
-## Backlog
-{% if backlog_tasks %}
-{% for task in backlog_tasks %}
-- [ ] {{ task }}
-{% endfor %}
-{% endif %}
-
-## Blocked
-
-# DONE
diff --git a/src/agentspaces/templates/skeleton/docs/planning/deployment.md b/src/agentspaces/templates/skeleton/docs/planning/deployment.md
deleted file mode 100644
index bce34cc..0000000
--- a/src/agentspaces/templates/skeleton/docs/planning/deployment.md
+++ /dev/null
@@ -1,270 +0,0 @@
----
-name: deployment
-description: Read when deploying or troubleshooting environments. Setup, configuration, verification.
-category: operational
-when_to_use:
-  - Deploying the application for the first time
-  - Setting up a new environment
-  - Onboarding ops team members
-  - Troubleshooting deployment issues
-dependencies:
-  - architecture.md
-variables:
-  required:
-    - project_name
-  optional:
-    - platforms
-    - prerequisites
-    - env_vars
-    - deployment_steps
-    - post_deployment_checklist
-    - health_endpoints
-    - monitoring_options
-    - rollback_instructions
----
-
-# Deployment Guide
-
-How to deploy {{ project_name }} to production.
-
-## Recommended Platforms
-
-{% if platforms %}
-| Platform | Free Tier | Notes |
-|----------|-----------|-------|
-{% for p in platforms %}
-| {{ p.name }} | {{ p.free_tier }} | {{ p.notes }} |
-{% endfor %}
-{% else %}
-| Platform | Free Tier | Notes |
-|----------|-----------|-------|
-| Railway | 500 hours/month | Simple, good DX |
-| Render | 750 hours/month | Easy setup |
-| Fly.io | 3 shared VMs | Global edge deployment |
-
-Choose based on your requirements and preference.
-{% endif %}
-
-## Prerequisites
-
-{% if prerequisites %}
-{% for prereq in prerequisites %}
-{{ loop.index }}. {{ prereq }}
-{% endfor %}
-{% else %}
-1. GitHub repository with code
-2. Platform account (Railway, Render, or Fly.io)
-3. Environment variables ready (see below)
-4. Domain name (optional)
-{% endif %}
-
-## Environment Variables
-
-{% if env_vars %}
-| Variable | Required | Description |
-|----------|----------|-------------|
-{% for var in env_vars %}
-| `{{ var.name }}` | {{ "Yes" if var.required else "No" }} | {{ var.description }} |
-{% endfor %}
-{% else %}
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `SECRET_KEY` | Yes | Random string for cryptographic operations |
-| `DATABASE_URL` | Yes | Database connection string |
-| `ENVIRONMENT` | No | `development` or `production` |
-| `LOG_LEVEL` | No | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
-{% endif %}
-
-## Deployment Steps
-
-{% if deployment_steps %}
-{% for platform, steps in deployment_steps.items() %}
-### {{ platform }}
-
-{% for step in steps %}
-#### {{ loop.index }}. {{ step.title }}
-
-{{ step.content }}
-
-{% if step.code %}
-```{{ step.code_lang | default("bash") }}
-{{ step.code }}
-```
-{% endif %}
-{% endfor %}
-
-{% endfor %}
-{% else %}
-### Railway
-
-#### 1. Connect Repository
-
-1. Go to [railway.app](https://railway.app)
-2. Click "New Project" → "Deploy from GitHub repo"
-3. Select your repository
-4. Railway auto-detects Python
-
-#### 2. Configure Environment
-
-In Railway dashboard → Variables, add your environment variables.
-
-#### 3. Configure Build
-
-Create `railway.toml` if needed:
-
-```toml
-[build]
-builder = "nixpacks"
-
-[deploy]
-startCommand = "uvicorn src.main:app --host 0.0.0.0 --port $PORT"
-```
-
-#### 4. Add Persistent Storage
-
-For SQLite or file storage:
-
-1. Railway dashboard → Add Volume
-2. Mount path: `/app/data`
-3. Update app to use `/app/data` for storage
-
-#### 5. Custom Domain (Optional)
-
-1. Settings → Domains
-2. Add custom domain
-3. Configure DNS CNAME
-
-### Render
-
-#### 1. Create Web Service
-
-1. Go to [render.com](https://render.com)
-2. New → Web Service
-3. Connect GitHub repository
-
-#### 2. Configure Service
-
-```yaml
-# render.yaml
-services:
-  - type: web
-    name: {{ project_name | lower | replace(" ", "-") }}
-    env: python
-    buildCommand: pip install -e .
-    startCommand: uvicorn src.main:app --host 0.0.0.0 --port $PORT
-    envVars:
-      - key: SECRET_KEY
-        generateValue: true
-```
-
-#### 3. Add Persistent Disk
-
-1. Service settings → Add Disk
-2. Mount path: `/app/data`
-3. Size: 1GB (adjust as needed)
-{% endif %}
-
-## Post-Deployment Checklist
-
-{% if post_deployment_checklist %}
-{% for item in post_deployment_checklist %}
-- [ ] {{ item }}
-{% endfor %}
-{% else %}
-- [ ] Health check endpoint responds: `GET /health`
-- [ ] Application loads without errors
-- [ ] Can perform core functionality
-- [ ] Error tracking working (if configured)
-- [ ] SSL certificate active
-- [ ] Environment variables set correctly
-{% endif %}
-
-## Health Checks
-
-{% if health_endpoints %}
-```
-{% for endpoint in health_endpoints %}
-{{ endpoint.method }} {{ endpoint.path }}  → {{ endpoint.description }}
-{% endfor %}
-```
-{% else %}
-```
-GET /health        → Basic liveness
-GET /health/ready  → Dependencies OK
-```
-{% endif %}
-
-## Monitoring
-
-{% if monitoring_options %}
-{% for option in monitoring_options %}
-- {{ option }}
-{% endfor %}
-{% else %}
-### Uptime Monitoring
-
-Set up external monitoring (free options):
-- UptimeRobot
-- Checkly
-- Better Uptime
-
-Configure to check `/health` every 5 minutes.
-
-### Error Tracking
-
-- Sentry (recommended)
-- LogRocket
-- Rollbar
-{% endif %}
-
-## Scaling
-
-For MVP scale (50-100 users), single instance is sufficient.
-
-If needed:
-1. Increase instance size before adding instances
-2. Consider managed database if SQLite becomes bottleneck
-3. Add caching layer for frequently accessed data
-
-## Rollback
-
-{% if rollback_instructions %}
-{% for platform, instructions in rollback_instructions.items() %}
-**{{ platform }}:**
-{% for step in instructions %}
-{{ loop.index }}. {{ step }}
-{% endfor %}
-
-{% endfor %}
-{% else %}
-If deployment fails:
-
-**Railway:**
-1. Deployments → Select previous successful deploy
-2. Click "Redeploy"
-
-**Render:**
-1. Events → Find previous deploy
-2. Click "Rollback"
-{% endif %}
-
-## Troubleshooting
-
-### Application Won't Start
-
-1. Check logs for error messages
-2. Verify all environment variables are set
-3. Ensure port binding uses `$PORT` environment variable
-4. Check that dependencies are installed correctly
-
-### Database Connection Issues
-
-1. Verify `DATABASE_URL` is set correctly
-2. Check if persistent storage is mounted
-3. Ensure database file permissions are correct
-
-### SSL Certificate Issues
-
-1. Wait up to 24 hours for certificate provisioning
-2. Verify DNS records are correct
-3. Check platform-specific SSL settings
diff --git a/tests/integration/cli/__init__.py b/tests/integration/cli/__init__.py
new file mode 100644
index 0000000..94742f5
--- /dev/null
+++ b/tests/integration/cli/__init__.py
@@ -0,0 +1 @@
+"""Integration tests for CLI commands."""
diff --git a/tests/integration/cli/conftest.py b/tests/integration/cli/conftest.py
new file mode 100644
index 0000000..0d07b73
--- /dev/null
+++ b/tests/integration/cli/conftest.py
@@ -0,0 +1,116 @@
+"""Fixtures for CLI integration tests."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from typer.testing import CliRunner
+
+from agentspaces.cli.app import app
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+    from pathlib import Path
+
+runner = CliRunner(mix_stderr=False)
+
+
+@pytest.fixture
+def empty_dir(temp_dir: Path) -> Path:
+    """Create a fresh empty directory for project initialization.
+
+    Returns the temp_dir directly (already empty).
+    """
+    return temp_dir
+
+
+@pytest.fixture
+def empty_git_dir(temp_dir: Path) -> Path:
+    """Create an empty directory that is already a git repo.
+
+    Initializes git but doesn't create any files (except .git/).
+    """
+    subprocess.run(
+        ["git", "init"],
+        cwd=temp_dir,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "config", "user.email", "test@example.com"],
+        cwd=temp_dir,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Test User"],
+        cwd=temp_dir,
+        capture_output=True,
+        check=True,
+    )
+    return temp_dir
+
+
+@pytest.fixture
+def non_empty_dir(temp_dir: Path) -> Path:
+    """Create a directory with existing files (not git-ignored)."""
+    (temp_dir / "existing.txt").write_text("existing content")
+    return temp_dir
+
+
+@pytest.fixture
+def chdir_to(
+    monkeypatch: pytest.MonkeyPatch,
+) -> Generator[Callable[[Path], None]]:
+    """Factory fixture to change to a directory and restore after test.
+
+    Usage:
+        def test_example(chdir_to, empty_dir):
+            chdir_to(empty_dir)
+            # test runs in empty_dir
+    """
+
+    def _chdir_to(path: Path) -> None:
+        monkeypatch.chdir(path)
+
+    yield _chdir_to
+
+
+@pytest.fixture
+def invoke_project_create() -> Callable[..., Any]:
+    """Factory fixture for invoking project create with defaults.
+
+    Returns a callable that invokes the CLI with common defaults.
+    """
+
+    def _invoke(
+        *args: str,
+        name: str = "TestProject",
+        description: str = "A test project",
+        yes: bool = True,
+        input: str | None = None,
+    ) -> Any:
+        cmd = ["project", "create"]
+        if name:
+            cmd.extend(["--name", name])
+        if description:
+            cmd.extend(["--description", description])
+        if yes:
+            cmd.append("--yes")
+        cmd.extend(args)
+        return runner.invoke(app, cmd, input=input)
+
+    return _invoke
+
+
+@pytest.fixture(autouse=True)
+def isolate_git(monkeypatch: pytest.MonkeyPatch, temp_dir: Path) -> None:
+    """Prevent tests from using system git config.
+
+    Sets GIT_CONFIG_GLOBAL and GIT_CONFIG_SYSTEM to isolate git configuration.
+    """
+    git_config = temp_dir / ".gitconfig"
+    monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(git_config))
+    monkeypatch.setenv("GIT_CONFIG_SYSTEM", "/dev/null")
diff --git a/tests/integration/cli/test_project_create.py b/tests/integration/cli/test_project_create.py
new file mode 100644
index 0000000..910c8a2
--- /dev/null
+++ b/tests/integration/cli/test_project_create.py
@@ -0,0 +1,430 @@
+"""Integration tests for project create command."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from agentspaces.cli.app import app
+from tests.integration.cli.conftest import runner
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+
+@pytest.mark.integration
+class TestProjectCreateBasic:
+    """Tests for basic project creation scenarios."""
+
+    def test_create_in_empty_directory(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should create skeleton in empty directory and init git."""
+        chdir_to(empty_dir)
+
+        result = invoke_project_create()
+
+        assert result.exit_code == 0, f"Command failed: {result.output}"
+        assert "Project Created" in result.output
+        # Git was initialized
+        assert (empty_dir / ".git").is_dir()
+        # Skeleton files exist
+        assert (empty_dir / "README.md").exists()
+        assert (empty_dir / "CLAUDE.md").exists()
+        assert (empty_dir / ".claude" / "agents" / "README.md").exists()
+        assert (empty_dir / ".claude" / "commands" / "README.md").exists()
+        assert (empty_dir / "docs" / "design" / "architecture.md").exists()
+        assert (empty_dir / "docs" / "design" / "development-standards.md").exists()
+        # ADR example is created (no required variables)
+        assert (empty_dir / "docs" / "adr" / "001-example.md").exists()
+        # Note: 000-template.md may fail if template has required variables not provided
+
+    def test_create_in_existing_git_repo(
+        self,
+        empty_git_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should create skeleton without re-initializing git."""
+        chdir_to(empty_git_dir)
+
+        result = invoke_project_create()
+
+        assert result.exit_code == 0, f"Command failed: {result.output}"
+        # Git was NOT re-initialized (no message about it)
+        assert "Initialized git" not in result.output
+        # But files were created
+        assert (empty_git_dir / "README.md").exists()
+        assert (empty_git_dir / "CLAUDE.md").exists()
+
+    def test_create_with_python_flag(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should create Python language pack files with --python flag."""
+        chdir_to(empty_dir)
+
+        result = invoke_project_create("--python", name="MyPythonApp")
+
+        assert result.exit_code == 0, f"Command failed: {result.output}"
+        # Python pack files exist
+        assert (empty_dir / "pyproject.toml").exists()
+        assert (empty_dir / ".gitignore").exists()
+        assert (empty_dir / ".python-version").exists()
+        assert (empty_dir / ".pre-commit-config.yaml").exists()
+        assert (empty_dir / ".github" / "workflows" / "ci.yml").exists()
+        # Package structure with derived name
+        assert (empty_dir / "src" / "mypythonapp" / "__init__.py").exists()
+        assert (empty_dir / "tests" / "conftest.py").exists()
+
+
+@pytest.mark.integration
+class TestProjectCreatePythonPackageNaming:
+    """Tests for Python package name derivation."""
+
+    @pytest.mark.parametrize(
+        ("project_name", "expected_package"),
+        [
+            ("My Project", "my_project"),
+            ("CLI-Tool", "cli_tool"),
+            ("api", "api"),
+            ("123App", "pkg_123app"),  # Can't start with number
+            ("for", "for_pkg"),  # Python keyword
+        ],
+    )
+    def test_package_name_derivation(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        project_name: str,
+        expected_package: str,
+    ) -> None:
+        """Should derive valid Python package name from project name."""
+        chdir_to(empty_dir)
+
+        result = runner.invoke(
+            app,
+            [
+                "project",
+                "create",
+                "--python",
+                "-y",
+                "-n",
+                project_name,
+                "-d",
+                "Test",
+            ],
+        )
+
+        assert result.exit_code == 0, f"Command failed: {result.output}"
+        assert (empty_dir / "src" / expected_package / "__init__.py").exists()
+
+    def test_custom_python_version(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should use specified Python version in generated files."""
+        chdir_to(empty_dir)
+
+        result = invoke_project_create(
+            "--python",
+            "--python-version",
+            "3.12",
+        )
+
+        assert result.exit_code == 0, f"Command failed: {result.output}"
+        pyproject = (empty_dir / "pyproject.toml").read_text()
+        assert ">=3.12" in pyproject
+        python_version = (empty_dir / ".python-version").read_text()
+        assert "3.12" in python_version
+
+
+@pytest.mark.integration
+class TestProjectCreateErrors:
+    """Tests for error conditions."""
+
+    def test_fails_in_non_empty_directory(
+        self,
+        non_empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should fail if directory contains non-git files."""
+        chdir_to(non_empty_dir)
+
+        result = invoke_project_create()
+
+        assert result.exit_code == 1
+        # Error message suggests creating a new directory
+        assert "directory" in result.output.lower()
+
+    def test_allows_directory_with_only_git(
+        self,
+        empty_git_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should allow creation in dir with only .git directory."""
+        chdir_to(empty_git_dir)
+
+        result = invoke_project_create()
+
+        assert result.exit_code == 0
+
+    def test_respects_confirmation_prompt_no(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+    ) -> None:
+        """Should abort when user declines confirmation."""
+        chdir_to(empty_dir)
+
+        result = runner.invoke(
+            app,
+            ["project", "create", "-n", "Test", "-d", "Desc"],
+            input="n\n",
+        )
+
+        assert result.exit_code == 0  # Clean exit
+        assert "Cancelled" in result.output
+        assert not (empty_dir / "README.md").exists()
+
+
+@pytest.mark.integration
+class TestProjectCreateContent:
+    """Tests for generated file content."""
+
+    def test_readme_contains_project_info(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Generated README should contain project name and description."""
+        chdir_to(empty_dir)
+
+        invoke_project_create(name="AwesomeApp", description="Does amazing things")
+
+        readme = (empty_dir / "README.md").read_text()
+        assert "AwesomeApp" in readme
+        assert "Does amazing things" in readme
+
+    def test_claude_md_contains_project_name(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Generated CLAUDE.md should reference project name."""
+        chdir_to(empty_dir)
+
+        invoke_project_create(name="TestProject")
+
+        claude_md = (empty_dir / "CLAUDE.md").read_text()
+        assert "TestProject" in claude_md
+
+    def test_pyproject_contains_project_metadata(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Generated pyproject.toml should have correct metadata."""
+        chdir_to(empty_dir)
+
+        invoke_project_create(
+            "--python",
+            name="My CLI Tool",
+            description="A command line tool",
+        )
+
+        pyproject = (empty_dir / "pyproject.toml").read_text()
+        # Name uses project_name variable
+        assert "my_cli_tool" in pyproject.lower() or "my-cli-tool" in pyproject.lower()
+        assert "A command line tool" in pyproject
+
+    def test_files_have_valid_frontmatter(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Markdown files should have valid YAML frontmatter."""
+        chdir_to(empty_dir)
+
+        invoke_project_create()
+
+        # Check a sample of generated files
+        for md_file in [
+            empty_dir / "README.md",
+            empty_dir / "CLAUDE.md",
+            empty_dir / "docs" / "design" / "architecture.md",
+        ]:
+            content = md_file.read_text()
+            assert content.startswith("---\n"), f"{md_file} missing frontmatter"
+            # Find end of frontmatter
+            end = content.find("\n---\n", 4)
+            assert end > 0, f"{md_file} has unclosed frontmatter"
+
+
+@pytest.mark.integration
+class TestProjectCreateGitIntegration:
+    """Tests for git-related behavior."""
+
+    def test_git_init_creates_valid_repo(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Git init should create a valid repository."""
+        chdir_to(empty_dir)
+
+        invoke_project_create()
+
+        # Verify it's a valid git repo
+        result = subprocess.run(
+            ["git", "status"],
+            cwd=empty_dir,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        assert result.returncode == 0
+
+    def test_generated_files_are_untracked(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Generated files should be untracked (ready for initial commit)."""
+        chdir_to(empty_dir)
+
+        invoke_project_create()
+
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=empty_dir,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        # All files should be untracked (??)
+        lines = result.stdout.strip().split("\n")
+        for line in lines:
+            if line:  # Skip empty lines
+                assert line.startswith("??"), f"Unexpected status: {line}"
+
+    def test_does_not_modify_existing_git_config(
+        self,
+        empty_git_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should not modify existing git configuration."""
+        chdir_to(empty_git_dir)
+
+        # Get config before
+        before = subprocess.run(
+            ["git", "config", "--local", "--list"],
+            cwd=empty_git_dir,
+            capture_output=True,
+            text=True,
+            check=False,
+        ).stdout
+
+        invoke_project_create()
+
+        # Get config after
+        after = subprocess.run(
+            ["git", "config", "--local", "--list"],
+            cwd=empty_git_dir,
+            capture_output=True,
+            text=True,
+            check=False,
+        ).stdout
+
+        assert before == after
+
+
+@pytest.mark.integration
+class TestProjectCreateEdgeCases:
+    """Tests for edge cases and boundary conditions."""
+
+    def test_handles_special_characters_in_project_name(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should handle special characters in project name."""
+        chdir_to(empty_dir)
+
+        result = invoke_project_create(
+            name="Project (Alpha) - v1.0",
+            description="Test",
+        )
+
+        assert result.exit_code == 0
+        assert (empty_dir / "README.md").exists()
+
+    def test_handles_long_project_name(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should handle very long project names."""
+        chdir_to(empty_dir)
+
+        long_name = "A" * 200
+        result = invoke_project_create(name=long_name)
+
+        assert result.exit_code == 0
+        readme = (empty_dir / "README.md").read_text()
+        assert long_name in readme
+
+    def test_handles_unicode_in_description(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should handle unicode characters in description."""
+        chdir_to(empty_dir)
+
+        result = invoke_project_create(
+            description="A project for handling emoji and unicode: café, naïve",
+        )
+
+        assert result.exit_code == 0
+        readme = (empty_dir / "README.md").read_text()
+        assert "café" in readme
+        assert "naïve" in readme
+
+    def test_creates_nested_directories(
+        self,
+        empty_dir: Path,
+        chdir_to: Callable[[Path], None],
+        invoke_project_create: Callable[..., Any],
+    ) -> None:
+        """Should create deeply nested directory structures."""
+        chdir_to(empty_dir)
+
+        invoke_project_create("--python")
+
+        # Verify nested structure
+        assert (empty_dir / ".github" / "workflows" / "ci.yml").exists()
+        assert (empty_dir / "docs" / "design" / "architecture.md").exists()
+        assert (empty_dir / "docs" / "adr" / "001-example.md").exists()
diff --git a/tests/unit/infrastructure/test_design.py b/tests/unit/infrastructure/test_design.py
index 9e3f4ff..ce87ec8 100644
--- a/tests/unit/infrastructure/test_design.py
+++ b/tests/unit/infrastructure/test_design.py
@@ -29,13 +29,11 @@ def test_returns_all_templates(self) -> None:
         # Docs templates
         assert "architecture" in names
         assert "development-standards" in names
-        assert "deployment" in names
         assert "adr-template" in names
         assert "adr-example" in names
         # Root templates
         assert "readme" in names
         assert "claude-md" in names
-        assert "todo-md" in names
         # .claude directory templates
         assert "agents-readme" in names
         assert "commands-readme" in names
diff --git a/tests/unit/infrastructure/test_resources.py b/tests/unit/infrastructure/test_resources.py
index 673e70f..d13ce56 100644
--- a/tests/unit/infrastructure/test_resources.py
+++ b/tests/unit/infrastructure/test_resources.py
@@ -34,8 +34,10 @@ def test_skeleton_contains_expected_templates(self) -> None:
 
         # Check for key template files
         assert (result / "CLAUDE.md").exists()
-        assert (result / "TODO.md").exists()
         assert (result / "README.md").exists()
+        # docs directory with subdirectories
+        assert (result / "docs" / "design" / "architecture.md").exists()
+        assert (result / "docs" / "adr" / "000-template.md").exists()
 
     def test_raises_error_when_skeleton_missing(self, tmp_path: Path) -> None:
         """Should raise ResourceError when skeleton directory doesn't exist."""