Metadata-Version: 2.4
Name: sk8r
Version: 1.0.0
Summary: Set a project up so it runs: identify it, install it, fill local settings, add editor run buttons and verify it starts, after one approval.
Keywords: developer-tools,project-setup,ai-agents,dev-environment,django,t3code,cli
Author: Akash Damle
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/code-kasha/sk8r
Project-URL: Repository, https://github.com/code-kasha/sk8r
Project-URL: Issues, https://github.com/code-kasha/sk8r/issues
Project-URL: Changelog, https://github.com/code-kasha/sk8r/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/logo-light.png">
    <img alt="sk8r" src="assets/brand/logo.png" width="420">
  </picture>
</p>

# sk8r

**Keep your momentum.** sk8r sets a project up so it actually runs: it works out what the project
is, installs its dependencies, fills in local settings, adds run buttons to your editor, and checks
that the app really starts — after one approval. Then it keeps a short, always-current briefing so
the next AI session picks up where the last one stopped.

Pronounced *skat-r*. Python 3.11+, standard library only at runtime. Linux, macOS and Windows.

[![CI](https://github.com/code-kasha/sk8r/actions/workflows/ci.yml/badge.svg)](https://github.com/code-kasha/sk8r/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)

[Quick start](#quick-start) · [Features](#features) · [How it works](#how-it-works) ·
[Commands](#commands) · [Results](results/README.md) · [Reference](docs/reference.md) ·
[Contributing](CONTRIBUTING.md)

---

## Contents

- [Why](#why)
- [Quick start](#quick-start)
- [Features](#features)
  - [Ready](#ready)
  - [Upcoming](#upcoming)
- [How it works](#how-it-works)
- [Safety](#safety)
- [Commands](#commands)
- [Configuration files](#configuration-files)
- [Platforms](#platforms)
- [Status](#status)
- [Contributing](#contributing)
- [License](#license)

## Why

Cloning a project is easy. Getting it to *run* is where momentum dies: which Python, which
package manager, which virtual environment, the `.env` nobody committed, the database URL, the
command that starts the server, and whether it really started. AI coding assistants make this
worse and better at once: they can do all of it, but they guess, and "it should work now" is not
the same as a server answering.

Momentum also dies between sessions. A new AI session starts cold: it doesn't know what is done,
what is next or which rules the project follows, so it re-reads everything or, worse, guesses.

sk8r turns both into predictable steps an assistant (or you) can run, preview and undo:

```text
You:    Set this project up with sk8r; follow `sk8r guide`.
Agent:  Here is the plan:
        1. Write sk8r.toml (preset django, python=uv inferred from uv.lock)
        2. Write 3 run buttons into T3 Code (backup first)
        3. Setup: uv sync
        4. Add app settings to .env: SECRET_KEY, ALLOWED_HOSTS, DATABASE_URL, DEBUG (names only)
        5. Start check: wait for http://127.0.0.1:8000/admin/login/, then stop
        Approve?
You:    approve it
Agent:  configured ✓  dependencies installed ✓  dry-run verified ✓  launched ✓ (HTTP 200)
```

That exchange is a real run on a real Django project, from approval to a verified HTTP 200 in about
11 seconds. See [results](results/README.md) for it and for the less flattering runs that shaped
sk8r.

## Quick start

```bash
uv tool install sk8r                                      # from PyPI
uv tool update-shell                                      # puts sk8r on PATH if it isn't yet
sk8r --version
```

**With an AI assistant in [T3 Code](https://github.com/pingdotgg/t3code):** open your project and
say *"Set this project up with sk8r; follow `sk8r guide`."* Review the plan, approve once, and the
new run buttons appear in T3 (press **Ctrl+R** if they don't).

**On your own, in a terminal:**

```bash
cd your-project
sk8r run --dry-run      # see the whole plan; nothing is written or run
sk8r run                # do it, after one yes
sk8r start dev          # launch the profile's processes, one terminal tab each
sk8r undo               # changed your mind? reverse everything sk8r did here
```

**Keep AI sessions in context:**

```bash
sk8r pack init --dry-run --hook --remind claude   # preview adopting the briefing workflow
sk8r pack init --yes --hook --remind claude       # adopt it: pack, task list, AGENTS.md pointer, hook
sk8r status                                       # progress, next tasks, warnings
```

## Features

**Ready** features ship in the current version and are covered by the test suite.
**Upcoming** features are planned on the roadmap; their shape may change before they ship.

### Ready

#### 1. One-approval project setup — `sk8r run`

- **One plan, one yes.** Identification, configuration, run buttons, dependency setup, app
  settings and start checks are shown as a single numbered plan and carried out after one
  approval.
- **Preview everything first.** `sk8r run --dry-run` writes and runs nothing; `--json` returns one
  result object for an AI assistant.
- **Leave parts out.** `--no-setup`, `--no-env` and `--no-verify` drop steps from the plan;
  `--pack` adds context-pack adoption to it.
- **Four honest states,** reported separately because they are different claims:
  *configured* (`sk8r.toml` written), *dependencies installed* (setup recorded),
  *dry-run verified* (programs and paths exist) and *launched* (the app actually answered).
- **Never rewrites your configuration.** An existing `sk8r.toml` with profiles is left as it is.

#### 2. Stack detection and presets — `sk8r presets`, `sk8r init`

- **Six presets:** `django`, `django-vite`, `django-expo`, `fastapi-vite`, `node-next` and
  `python-server` ([catalogue](docs/presets.md)).
- **Choices inferred from your files,** with the source shown in the preview: `uv.lock` → uv,
  `poetry.lock` → Poetry, `requirements.txt` → a project `.venv`, `pyproject.toml` alone → uv;
  `pnpm-lock.yaml`, `yarn.lock` or `package-lock.json` pick the Node tool.
- **Safe automatic choice.** Only a single full preset match is picked automatically; half matches
  ask you to choose with `--preset`.
- **Python options:** `uv`, `poetry`, `venv` (creates `.venv` and installs requirements; commands
  use the venv's Python directly, no activation) and `plain`. **Node options:** `pnpm`, `npm`, `yarn`.
- **Parameters with validation** (`--set port=8001`, `--set backend_dir=api`): paths, ports, text
  and choices are checked before anything is written.
- **Presets are data, not code.** `sk8r init --preset <name>` copies the profiles into
  `sk8r.toml`, appending after a comment that records your options, keeping your newline style and
  encoding, and writing atomically. Name clashes stop with a list; `--rename old=new` resolves them.
- **Browse and inspect:** `sk8r presets list`, `presets show <name>` (the exact TOML) and
  `presets detect` (read-only).
- **Repair a generated profile:** `sk8r init --replace <profile> --dry-run` shows a diff and
  replaces only a profile that `init` generated and nobody edited.

#### 3. Launching — `sk8r start`

- **One terminal tab per process:** Windows Terminal (a PowerShell 7 tab each), a detached tmux
  session on Linux (and on macOS with tmux), or Terminal.app windows on macOS.
- **Fallback that still helps:** when no terminal is available, sk8r prints the exact commands.
- **Profiles and variants,** for example `sk8r start dev lan` or `sk8r start dev phone`.
- **Exact plans:** `--dry-run` prints every tab, folder and command; `--tab <t> --here` runs one tab
  in the current terminal (what each editor button runs).
- **Checked before launch.** The profile's readiness checks run first; nothing starts while one
  blocks (`--no-check` skips them). Tabs whose setup is incomplete are refused.
- **Shell shortcut:** `sk8r shortcut powershell|bash|zsh` prints an opt-in `start` function;
  nothing edits your shell profile.

#### 4. Dependency setup — `sk8r setup`

- **Declared, shown, confirmed.** Each profile's setup (`uv sync`, `poetry install`,
  `pnpm install`, venv creation…) is printed with its folder and runs only after a yes.
- **Recorded completion.** Successful setup is recorded with the hashes of its inputs (lock or
  requirements files), so an empty or outdated `.venv` never counts as ready.
- **Independent entries.** A failed `pnpm install` doesn't stop the Python environment.
- **Plain warnings.** Choosing `plain` beside a requirements file warns that dependencies are
  unmanaged.

#### 5. App settings — `.env` defaults

- **Fills only what is missing.** Required keys come from `.env.example` and the preset; a key is
  added only when it is missing or empty.
- **Local-development defaults** for Django: a SQLite `DATABASE_URL`, a generated `SECRET_KEY`,
  `DEBUG=True` and `ALLOWED_HOSTS=localhost,127.0.0.1`. Add your own with `sk8r defaults`.
- **Names only.** Values are never printed, logged or stored by sk8r, and values you set are never
  changed.
- **Gated start.** Until required keys are filled, doctor reports `env-missing` and `start` waits.

#### 6. Start check — `sk8r verify`

- **A real HTTP answer,** not a guess: sk8r starts the tab in the background, waits for any HTTP
  response at its `check_url` (Django: `/admin/login/`, Vite: port 5173), then stops it.
- **Cleans up after itself.** It stops only its own process tree and confirms the port is free
  again.
- **Refuses busy ports** and never touches processes it didn't start.
- **Useful failures.** When the app doesn't answer, the last log lines are shown and kept under
  `.git/sk8r/verify/`.
- **A "check" button per tab** in T3 Code.

#### 7. Editor run buttons — T3 Code

- **Buttons written for you.** One button per tab and one per setup, written straight into T3's
  project settings (with a timestamped backup first) and/or a shared `t3.json`
  (`--t3 file|settings|both|off`).
- **Only sk8r's entries.** Existing scripts are kept; only entries whose id starts with `sk8r-` are
  replaced.
- **Project defaults for T3:** the model and thread mode (local or worktree) you prefer, applied to
  every project you set up; different existing values are kept unless you override them.
- **Import path** for any setup without direct settings access: import `t3.json` in T3's project
  settings.

#### 8. Readiness check — `sk8r doctor`

- **Read-only.** Changes nothing and runs no project commands.
- **Checks in order:** Python, sk8r on `PATH`, Git; the repository, `sk8r.toml`, records branch,
  plan and pack; the terminal launcher; each profile's folders, required paths, programs, setup
  and app settings; `t3.json` freshness.
- **Every finding has a fix,** a stable code (`program-missing`, `setup-needed`, `env-missing`…)
  and a level (`ok`, `warn`, `block`). `--json` gives one machine-readable object.

#### 9. Undo — `sk8r undo`

- **Everything journalled.** `sk8r.toml`, `t3.json`, T3 buttons and project defaults, setup
  records, created files and folders, `.env` additions, and context-pack adoption (pack, task list,
  `AGENTS.md` block, hook and reminder).
- **Reversible in one command.** `sk8r undo --dry-run` lists changes newest first; `--yes`
  reverses them byte for byte, restoring editor buttons sk8r replaced.
- **Your edits win.** Anything changed since sk8r wrote it is reported and left alone.

#### 10. Your defaults — `sk8r defaults`

- **One file for your preferences:** preferred tools and ports, terminal launcher, start-check
  timeout, where buttons go, T3 model and thread mode, and extra `.env` defaults.
- **Edit safely:** `defaults init`, `defaults set run.launcher tmux` and `defaults unset …` edit one
  setting atomically, keeping comments and line endings.
- **Clear precedence,** shown with each value's source: what you type wins over the project's
  files, your defaults and preset defaults.

#### 11. AI assistant guide — `sk8r guide`

- **Versioned instructions** an assistant follows to set a project up in T3 Code, centred on
  `sk8r run`'s one-approval plan; `--json` gives the same as data.
- **No model inside.** sk8r itself never calls a model; the assistant runs sk8r's commands and you
  approve.

#### 12. Context pack for AI sessions — `sk8r pack`, `sk8r pack init`

- **A short briefing** (`docs/context-pack.md`) a new AI session reads first: agent rules, the next
  task, open questions, and a generated block of current facts, kept under 10 KB by trimming rules.
- **One-command adoption:** `sk8r pack init` creates the pack from a template, finds your task list
  (`TODO.md` or `todo.md`, exact spelling kept) or creates a starter one, sets the plan, pack and
  records branch in `sk8r.toml`, adds a marked start-here block to `AGENTS.md`, and fills the block —
  as one numbered plan in plain words, after one yes, and fully undoable.
- **Safe refresh.** `sk8r pack` rewrites only the generated block between its markers, on the
  records branch only, and changes no other byte; `--check` exits 3 when the pack is stale.
- **Stable by design.** The block changes only when the plan's facts change, so a committed pack
  stays current (an optional recent-commits list is off by default).

#### 13. Project status — `sk8r status`

- **The facts in one place:** current branch or detached HEAD, uncommitted changes, progress per
  phase, the current phase, next tasks per teammate, branch locks and plan warnings.
- **Read from the records branch** without switching branches; `--json` gives one versioned object.
  It never writes.

#### 14. Commit hook and agent reminders — `--hook`, `sk8r hook`, `sk8r remind`

- **Optional pre-commit hook** that refreshes and stages only the pack when you commit plan
  changes. It respects `core.hooksPath`, keeps an existing hook's lines (inserting its stanza
  before the final `exit`), and always exits 0, so it never blocks a commit.
- **Installed only when asked** (`sk8r pack init --hook`) or by hand from `sk8r hook show`.
- **Claude Code reminder** (`--remind claude`) merges a post-commit reminder into
  `.claude/settings.json`, keeping your other settings; it tells the model when the pack is stale
  and never refreshes anything itself.
- **Portable routine** for other assistants: `sk8r pack --check` after a commit
  ([details](docs/hooks.md)).

#### 15. Configuration check — `sk8r config check`

- Validates `sk8r.toml` (versioned schema, unknown keys rejected, repository-relative paths
  only) without running anything.

#### 16. Repository trust — `sk8r trust`

- **You approve a project's commands once.** Before `sk8r start` (and the editor's run buttons),
  `sk8r setup` and `sk8r verify` run anything a project's `sk8r.toml` declares, sk8r shows every
  command with the full path of the program it runs, and asks.
- **Any change asks again,** with the added and removed lines, so a `git pull` can't slip in new
  commands.
- **Approvals live on your machine,** outside every repository, so a cloned or copied project
  never arrives pre-approved. `sk8r trust --revoke` removes one.
- **One plan, still one yes.** `sk8r run` lists the commands in its plan when they are new or
  changed; configuration sk8r writes itself is approved automatically.
- **Programs are what they say.** Bare names like `git` are found only on `PATH`, never in the
  project or current folder, and the start check only connects to this machine.

### Upcoming

Planned, in roughly this order. None of these ship yet.

- **More presets.** More stacks, mostly from contributors; each is a small data file plus a test.
- **Verification profiles and portable handoffs.** Richer, declared checks beyond "the server
  answers", and handoffs that move between machines and assistants.
- **Backup and move — the backup tool.** Move a project between machines: Git history and
  uncommitted work, folders that live outside the repository, optional data, and project-filtered
  AI chat history, with an archive manifest, ownership filters, upload to a committed backend and
  restore validation.
- **Agents kit.** A reusable setup for teams of AI agents: a shared agreement, teammate
  permissions, task briefs, record and claim rules, and a helper for working one step at a time.
- **Workflow playbook.** A `WORKFLOW.md` written from the tested routines: approval, pauses, tests,
  commits, the pack, status and handoff.
- **Docs export (optional).** Export project records to Word and Excel.
- **Browser kit.** Isolated browser environments, sign-in, pinned time and screenshot helpers for
  checking web apps, while the core stays standard-library only.

## How it works

1. **Identify.** sk8r matches the project against [presets](docs/presets.md) and infers the
   choices from the files that are there. It writes one small file, `sk8r.toml`.
2. **Check.** `sk8r doctor` explains what is missing and how to fix it, without changing anything.
3. **Install.** Declared setup runs only after your yes: create the venv, install requirements,
   `pnpm install`. Completion is recorded, so an empty or outdated `.venv` never counts as ready.
4. **Configure.** Missing local-development settings are added to `.env`. Values you set are never
   changed, and values are never printed.
5. **Buttons.** Run buttons go into your editor's project settings (T3 Code today) and a shared
   `t3.json`, with a backup first.
6. **Verify.** sk8r starts each server in the background, waits for a real HTTP answer, stops it,
   and confirms the port is free. It refuses ports already in use and never touches your servers.
7. **Brief.** Optionally, `sk8r pack init` adds a context pack that the next AI session reads first,
   kept current by `sk8r pack` and an optional commit hook.

Your preferences live in one file (`sk8r defaults`). A project's own files and anything you type
always win.

## Safety

- **Nothing changes without a yes.** Every write and install is shown first; without a terminal
  and without `--yes`, sk8r refuses.
- **Everything can be undone.** sk8r journals each change in the project and `sk8r undo` reverses
  it, restoring editor buttons it replaced; anything you changed since is left alone.
- **Secrets stay secret.** `.env` values are never printed, logged or stored by sk8r.
- **Your processes are yours.** sk8r never kills, reuses or frees a port it did not open.
- **A project's commands run only after you approve them,** once per version, with the full
  path of every program shown (`sk8r trust`).
- **Your hooks are yours.** Nothing is installed implicitly; an existing hook is extended, never
  overwritten, and sk8r's hook never blocks a commit.
- **Atomic writes.** Files are written through a temporary file and one replace; links and
  non-regular files are refused.
- **No internet, no model.** sk8r itself calls no online service and no AI model (the start check
  only talks to your own app on `127.0.0.1`); package managers it runs on your behalf do go online.

## Commands

| Command | What it does |
|---|---|
| `sk8r run` | Identify, install, configure, add buttons and verify, after one approval |
| `sk8r start <profile> [variant]` | Launch a profile's processes in terminal tabs (Windows Terminal, tmux, Terminal.app) |
| `sk8r setup <profile>` | Run a profile's declared setup, after confirmation |
| `sk8r verify <profile> --tab <t>` | Start one tab, wait for an HTTP answer, stop it |
| `sk8r doctor [profile]` | Read-only readiness check with fixes (`--json` for tools) |
| `sk8r undo` | Reverse every change sk8r made in this project |
| `sk8r trust` | Show, approve (`--yes`) or revoke the commands a project may run |
| `sk8r presets list\|show\|detect` | The preset catalogue, a preset's exact profiles, matching presets |
| `sk8r init --preset <name>` | Add a preset's profiles to `sk8r.toml` (append-only, atomic) |
| `sk8r config check` | Validate `sk8r.toml` without running anything |
| `sk8r defaults` | Your preferences in one file: tools, ports, launcher, T3 model and thread mode |
| `sk8r guide` | The instructions an AI assistant follows to set a project up |
| `sk8r status` | Plan progress, next tasks, locks and warnings, read from the records branch |
| `sk8r pack init` | Adopt the context-pack workflow in one approved, undoable step |
| `sk8r pack` | Refresh the context pack's generated block (`--check`, `--dry-run`) |
| `sk8r hook show` | The optional pre-commit hook and how to integrate it by hand |
| `sk8r remind claude` | The optional Claude Code post-commit reminder |
| `sk8r shortcut <shell>` | Print an opt-in `start` shell function |

Commands that write offer `--dry-run`; those that report offer `--json`. Every command and setting is in the
[reference](docs/reference.md); `sk8r run` in depth is in [docs/run.md](docs/run.md).

## Configuration files

| File | Where | What it holds |
|---|---|---|
| `sk8r.toml` | Repository root, committed | Project name, records branch, plan and pack paths, run profiles, setup and app-settings rules |
| `t3.json` | Repository root, committed | Shared T3 Code run buttons (only `sk8r-` entries are sk8r's) |
| `docs/context-pack.md` | Repository, committed | The AI briefing; sk8r owns only its generated block |
| `defaults.toml` | `%APPDATA%\sk8r\` on Windows, `~/.config/sk8r/` elsewhere | Your personal preferences |
| Journal, setup records, verify logs | Under Git's own folder (`.git/sk8r/`) | Undo history and local state; never committed |

## Platforms

| Platform | Status |
|---|---|
| Windows | Tested in CI and by hand; Windows Terminal launcher |
| Linux | Tested in CI and by hand, including a real tmux launch |
| macOS | Tested in CI; **not yet tried on a real Mac** — your report is welcome |

**Have a Mac? Please try sk8r and tell us how it went.** The test suite passes on macOS in CI,
but nobody has run it on a real Mac yet, so the Terminal.app and tmux launchers, `sk8r run` and the
start check are unconfirmed there. A [platform report](https://github.com/code-kasha/sk8r/issues/new?template=platform_report.yml) takes a few minutes, and
problems you hit become fixes.

Windows limit: npm-style `.cmd` shims such as `pnpm.cmd` go through batch-file parsing, so quotes
and `%` inside their arguments can't be passed reliably; ordinary arguments are fine.

## Status

sk8r 1.0 is out on [PyPI](https://pypi.org/project/sk8r/). The test suite (444 tests) runs in CI on Linux, macOS and Windows with
Python 3.11 and 3.15. Field results from real projects are in [results](results/README.md).
Changes are listed in the [changelog](CHANGELOG.md).

## Contributing

The easiest first contribution is a [preset](docs/contributing-presets.md) for a stack you use:
it is a small data file plus a test. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development
setup and the checks every change passes.

## License

[MIT](LICENSE) © 2026 Akash Damle
