From 76cc8b3e3e4d83ceba036990679539febea969a7 Mon Sep 17 00:00:00 2001
From: ulises-jeremias <ulisescf.24@gmail.com>
Date: Thu, 16 Jul 2026 02:57:06 -0300
Subject: [PATCH] docs: add AGENTS.md and VS Code workspace settings

Guide agents/contributors on uv stack and recommend Ruff/Pyright extensions.

Closes #16

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .vscode/extensions.json |  7 +++++++
 .vscode/settings.json   | 12 ++++++++++++
 AGENTS.md               | 41 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+)
 create mode 100644 .vscode/extensions.json
 create mode 100644 .vscode/settings.json
 create mode 100644 AGENTS.md

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..c1ea73e
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "charliermarsh.ruff",
+    "ms-python.python",
+    "ms-python.vscode-pylance"
+  ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..13948d2
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,12 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "editor.formatOnSave": true,
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.codeActionsOnSave": {
+      "source.fixAll.ruff": "explicit",
+      "source.organizeImports.ruff": "explicit"
+    }
+  },
+  "python.analysis.typeCheckingMode": "basic"
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f9b20d6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# Agent Instructions for create-python-app
+
+## Overview
+
+`create-python-app` is a CLI tool for scaffolding Python projects from templates
+(parity with [Create-Node-App/create-node-app](https://github.com/Create-Node-App/create-node-app)).
+
+Roadmap: [#1](https://github.com/Create-Python-App/create-python-app/issues/1).
+
+## Tech Stack
+
+- Python 3.12+ (see `.python-version`)
+- [uv](https://docs.astral.sh/uv/) workspaces (virtual root + `packages/*`)
+- Typer (CLI — Epic 4)
+- Ruff (lint/format — Epic 2)
+- Pyright (types — Epic 2)
+- pytest (tests — Epic 2)
+
+## Packages
+
+| Package | Role |
+|---------|------|
+| `create-python-app-core` | Scaffolding engine |
+| `create-awesome-python-app` | User-facing CLI (`uvx` / console script) |
+
+## Key Commands
+
+```bash
+uv sync
+make test        # uv run pytest
+make lint        # uv run ruff check .
+make typecheck   # uv run pyright
+make build       # uv build --all
+uv run create-awesome-python-app --help
+```
+
+## Code Style
+
+- Ruff for lint + format
+- Pyright for type checking
+- Prefer minimal, issue-linked changes; English for commits/PRs