@erclx/aitk 0.8.0

package/tooling/claude/seeds/.claude/hooks/index-reminder.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+
+input=$(cat)
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Grep | Glob) ;;
+*) exit 0 ;;
+esac
+
+path=$(printf '%s' "$input" | jq -r '.tool_input.path // empty')
+[ -n "$path" ] || exit 0
+
+if [ -f "$path" ]; then
+  dir=$(dirname "$path")
+else
+  dir="$path"
+fi
+
+index=""
+cur="$dir"
+while :; do
+  if [ -f "$cur/index.md" ]; then
+    index="$cur/index.md"
+    break
+  fi
+  parent=$(dirname "$cur")
+  [ "$parent" = "$cur" ] && break
+  cur="$parent"
+done
+
+[ -n "$index" ] || exit 0
+
+session=$(printf '%s' "$input" | jq -r '.session_id // "none"')
+key=$(printf '%s__%s' "$session" "$index" | tr -c 'A-Za-z0-9' '_')
+marker_dir="${CLAUDE_PROJECT_DIR:-.}/.claude/.tmp/index-reminder"
+marker="$marker_dir/$key"
+[ -f "$marker" ] && exit 0
+mkdir -p "$marker_dir"
+: >"$marker"
+
+msg=$(printf 'An index.md exists at %s. Read it before searching this folder, it catalogs the sibling files faster than a blind search.' "$index")
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+input=$(cat)
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Write | Edit) ;;
+*) exit 0 ;;
+esac
+
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+[ -n "$file_path" ] || exit 0
+
+case "$file_path" in
+*/.claude/.tmp/*) exit 0 ;;
+esac
+
+# A project whose own root sits under a path carrying a tmp segment is not
+# writing to system temp, and the bare pattern below trips the guard on every
+# source file it holds. Anchor on the project root before the pattern match.
+#
+# This gives up one case on purpose: a write to <project>/tmp/ is a genuine
+# scratch violation that no longer warns. The false positive fires on every
+# source write in an affected project, so the trade favors the anchor.
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  case "$file_path" in
+  "$CLAUDE_PROJECT_DIR"/*) exit 0 ;;
+  esac
+fi
+
+case "$file_path" in
+*/tmp/* | *\\tmp\\* | */Temp/* | *\\Temp\\* | */var/folders/*) ;;
+*) exit 0 ;;
+esac
+
+session=$(printf '%s' "$input" | jq -r '.session_id // "none"')
+key=$(printf '%s' "$session" | tr -c 'A-Za-z0-9' '_')
+marker_dir="${CLAUDE_PROJECT_DIR:-.}/.claude/.tmp/scratch-guard"
+marker="$marker_dir/$key"
+[ -f "$marker" ] && exit 0
+mkdir -p "$marker_dir"
+: >"$marker"
+
+msg='Temporary file write outside .claude/.tmp/. Write temp files to .claude/.tmp/<slug>/ in the project root, not system temp. See the Scratch rule in CLAUDE.md.'
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+
+input=$(cat)
+file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_response.filePath // empty')
+
+file="${file//\\//}"
+
+case "$file" in
+*.md) ;;
+*) exit 0 ;;
+esac
+
+case "$file" in
+*.claude/.tmp/* | *.claude/memory/* | *.claude/review/* | *.claude/plans/*) exit 0 ;;
+esac
+
+[ -f "$file" ] || exit 0
+
+# Read the closed-set word bans from the standard so the hook never carries a
+# second copy. Every "Do not use ... (`a`, `b`)" bullet contributes its
+# single-word backticked terms, which skips the multi-word and punctuation bans.
+standard="${CLAUDE_PROJECT_DIR:-.}/.claude/standards/prose.md"
+words=""
+if [ -f "$standard" ]; then
+  words=$(grep '^- Do not use ' "$standard" |
+    grep -o '`[^`]*`' |
+    tr -d '`' |
+    grep -x '[a-z][a-z]*' |
+    sort -u |
+    paste -sd '|' -)
+fi
+
+hits=$(awk -v words="$words" '
+  BEGIN { if (words != "") banned = "(^|[^a-z])(" words ")([^a-z]|$)" }
+  /^```/ { in_code = !in_code; next }
+  in_code { next }
+  /—/ { print NR ": em-dash: " $0 }
+  /;/  { print NR ": semicolon: " $0 }
+  banned != "" {
+    prose = tolower($0)
+    gsub(/`[^`]*`/, "", prose)
+    found = ""
+    delete seen
+    while (match(prose, banned)) {
+      word = substr(prose, RSTART, RLENGTH)
+      gsub(/[^a-z]/, "", word)
+      if (word != "" && !(word in seen)) {
+        seen[word] = 1
+        found = found (found == "" ? "" : ", ") word
+      }
+      prose = substr(prose, RSTART + RLENGTH)
+    }
+    if (found != "") print NR ": banned word (" found "): " $0
+  }
+' "$file")
+
+[ -z "$hits" ] && exit 0
+
+msg=$(printf 'Standards-audit: prose.md violations in %s. Rewrite or restructure (do not lazy-swap).\n%s' "$file" "$hits")
+
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/hooks/tasks-index.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+
+# Regenerates .claude/tasks/index.md after a task file changes.
+#
+# The task folder is gitignored, so the whole-repo walk in `bun run check`
+# drops it and never regenerates this index. A positional path bypasses that
+# filter, which makes this hook the only trigger that reaches the folder.
+
+input=$(cat)
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Write | Edit | MultiEdit) ;;
+*) exit 0 ;;
+esac
+
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+[ -n "$file_path" ] || exit 0
+
+case "$file_path" in
+*/.claude/tasks/*.md) ;;
+*) exit 0 ;;
+esac
+
+case "$file_path" in
+*/.claude/tasks/index.md) exit 0 ;;
+esac
+
+# Report a missing CLI rather than exiting quietly. The path guard above already
+# scopes this to a task-file edit, so the message only fires where the stale
+# index it warns about is the actual outcome.
+if ! command -v aitk >/dev/null 2>&1; then
+  jq -nc --arg msg 'aitk is not on PATH, so .claude/tasks/index.md was not regenerated and is now stale. Install the toolkit CLI or run aitk indexes regen by hand.' \
+    '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+  exit 0
+fi
+
+# The walk-up boundary has to come from the path, not from the session. Shared
+# scratch resolves at the main worktree root, so a session inside a linked
+# worktree passes a path that sits outside its own project directory and the
+# default boundary would reject it.
+root="${file_path%/.claude/tasks/*}"
+[ -n "$root" ] || exit 0
+
+# `--no-stage` because a hook has no business touching the index. On a project
+# whose board is not gitignored, the default auto-stage would silently add task
+# files to whatever commit is being assembled.
+output=$(aitk indexes regen --no-stage --root "$root" "$file_path" 2>&1) && exit 0
+
+# Regen failed, which on this folder means a task file is missing `title` or
+# `description`. Report it. Nothing else can: the folder is gitignored, so the
+# whole-repo walk never reaches it and no gate stage will ever fail on a stale
+# index. Staying quiet here is what makes the drift permanent.
+errors=$(printf '%s\n' "$output" | grep '^ERROR: ' | head -5)
+[ -n "$errors" ] || errors="$output"
+
+msg="Task index regen failed, so .claude/tasks/index.md is now stale. Fix the frontmatter and save again. $errors"
+jq -nc --arg msg "$msg" \
+  '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+exit 0

package/tooling/claude/seeds/.claude/settings.json

@@ -0,0 +1,39 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/index-reminder.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scratch-guard.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/standards-audit.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tasks-index.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/tooling/claude/seeds/.claude/tasks/index.md

@@ -0,0 +1,8 @@
+---
+title: Tasks
+subtitle: One file per task, ordered by phase label
+---
+
+# Tasks
+
+One file per task, ordered by phase label

package/tooling/claude/seeds/.claude/wireframes/index.md

@@ -0,0 +1,8 @@
+---
+title: Wireframes
+subtitle: Per-surface ASCII layouts loaded on demand
+---
+
+# Wireframes
+
+Per-surface ASCII layouts loaded on demand

package/tooling/claude/seeds/CLAUDE.md

@@ -0,0 +1,87 @@
+# Project
+
+[One-line description]
+
+## Context
+
+- Before non-trivial work in a domain read `.claude/context/<domain>.md`, and before touching a UI surface read `.claude/wireframes/<surface>.md`. Pick which from the index anchors below.
+- Scan `.claude/wiki/index.md` before answering a how-to question about project tooling or the shell environment, where that folder exists
+- `claude-docs` populates context entries at ship time
+
+@.claude/REQUIREMENTS.md
+@.claude/ARCHITECTURE.md
+@.claude/context/index.md
+@.claude/wireframes/index.md
+
+## Behavior
+
+- Flag concerns or alternatives when a proposed change has tradeoffs worth discussing
+- When facing a judgment call with 2-3 reasonable options mid-flow, pick one and state the tradeoff in one sentence. Enumerate options only when the user's preference is the deciding factor.
+- Match edit scope to the request. Ship minimal v1 and queue extensions as follow-ups.
+- On simplification requests, edit only what the user named
+- Do not add features the user did not ask for
+- When rewriting a section, preserve existing code blocks, tables, and grouped examples unless the user asked to remove them
+- When planning an edit to `CLAUDE.md`, show the proposed change as a fenced `diff` block in chat first, then wait for approval before calling `Edit`
+- Edit an existing file with the file-editing tool, never a shell stream editor. An unescaped `&` in a `sed` replacement expands to the whole match, and `sed -i` exits zero when its pattern matches nothing, so both fail silently while reporting success. This governs edits you make, not stream editors written into a project's own scripts.
+
+## Indexes
+
+- Check a folder's `index.md` before grepping its source or reading its files, starting with `.claude/context/` for a domain and `.claude/wireframes/` for a UI surface. It orients faster than a blind search.
+- For folders where an agent browses to pick a document, `index.md` is regenerated from each file's frontmatter. Do not hand-edit `index.md`. Code folders and scratch folders do not need one.
+- Every `index.md` carries its own frontmatter (`title`, `subtitle`) that the walker preserves. To keep a folder's `index.md` hand-edited, add `auto: false` to its frontmatter.
+
+## Commands
+
+- Run `bun run check` before committing. Full script reference in `.claude/context/development.md`.
+
+## Output
+
+- After creating or modifying a file, include its path on its own line so terminal emulators can make it clickable. Do not paraphrase paths into prose ("the seeds folder", "your CLAUDE.md").
+- Use the path the user's editor can resolve. The editor is rooted at the main project root.
+- In the main worktree: relative from `pwd` works because `pwd` equals the editor root
+- In a linked worktree (under `.claude/worktrees/<name>/`): use absolute paths. Relative paths from worktree `pwd` would not resolve against the editor's project root.
+- When the response covers multiple files, group paths under headers: `**Created:**`, `**Modified:**`, `**Deleted:**`. For single-file changes, the path on its own line is enough.
+
+## Key paths
+
+- `src/`: [description]
+- `.claude/`: planning docs (requirements, architecture, design, tasks)
+- `.claude/context/`: per-domain narrative (how a domain is structured, decisions, gotchas), indexed via `.claude/context/index.md`
+- `.claude/wireframes/`: per-surface ASCII layouts loaded on demand, indexed via `.claude/wireframes/index.md`
+- `.claude/wiki/`: reference pages for tools, workflows, and concepts, indexed via `.claude/wiki/index.md`
+- `.claude/rules/`: path-scoped coding standards loaded by Claude Code on file match
+- `.claude/review/`: gitignored scratch for review and UI-test output, overwritten on each run
+
+## Spelling
+
+- When cspell flags a word, rewrite typos. Add real terms to the appropriate dictionary in `cspell.json`.
+- Keep dictionary files sorted alphabetically
+
+## Snippets
+
+- When a snippet is referenced with `@`, execute its instructions immediately using available session context
+
+## Tasks
+
+- `.claude/tasks/` is gitignored local session scratch, one file per task. Edit freely. No staging or revert before commits.
+- Only create a task for work that spans multiple sessions or has real dependencies. Handle small edits immediately without a task entry.
+- Do not add tasks retroactively for work already completed. Completed work is visible in git.
+- When a task needs execution detail beyond its own file, create a plan in `.claude/plans/` and link to it from the task's intro paragraph. When that task ships, move its plan file to `.claude/.tmp/plans-archive/`. Never delete it.
+- Write the plan in the same session as the task file. The session that executes the plan later inherits reasoning context it would otherwise have to re-derive.
+
+## Memory
+
+- Write all memory files to `.claude/memory/`, not `~/.claude/projects/`
+- Save a feedback memory only when the same mistake happens twice in the session, or when the user explicitly corrects you. First-occurrence slips are noise.
+- Keep feedback memories to 3 lines: the rule, a one-line Why, and a one-line How to apply. Capture the pattern, not the recovery narrative.
+- Before creating a new memory file, check for an existing one on the same topic. Update rather than duplicate.
+
+## Scratch
+
+- Write temporary files to `.claude/.tmp/<slug>/<file>.md` in the project root, a nested `<slug>/` folder with a kebab-slug tied to the topic, not a flat `<slug>-<file>.md`. The scratch-guard hook enforces the location.
+
+## Worktrees
+
+- Implementation work runs in a linked worktree. From the main worktree, enter one with `/claude-worktree` before editing tracked files for a feature.
+- Shared session scratch (`.claude/plans/`, `.claude/review/`, `.claude/memory/`, `.claude/tasks/`) lives at the main worktree root, not inside a linked worktree. From a linked worktree, resolve these paths against the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. Fall back to `pwd` if not a git repo.
+- From a linked worktree, every `Edit` or `Write` to a tracked file (source, docs) must use a path starting with `pwd`. Only shared session scratch (`.claude/plans/`, `.claude/review/`, `.claude/memory/`, `.claude/tasks/`) resolves to the main worktree root.

package/tooling/claude/user/settings.template.json

@@ -0,0 +1,10 @@
+{
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
+  "permissions": {
+    "allow": ["Bash(bun run *)"],
+    "deny": ["Read(**/.env)", "Read(**/.env.*)"]
+  }
+}

package/tooling/claude/user/statusline-command.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+input=$(cat)
+
+{
+  IFS= read -r model
+  IFS= read -r effort
+  IFS= read -r remaining
+  IFS= read -r used_pct
+  IFS= read -r ctx_size
+} <<<"$(
+  echo "$input" | jq -r '
+    .model.display_name // "",
+    .effort.level // "",
+    .context_window.remaining_percentage // "",
+    .context_window.used_percentage // "",
+    .context_window.context_window_size // ""'
+)"
+
+real_ctx="$ctx_size"
+if [[ "${ANTHROPIC_BASE_URL:-}" == *"localhost"* ]] && command -v ollama &>/dev/null; then
+  ollama_ctx=$(ollama ps 2>/dev/null | awk 'NR>1 {print $7; exit}')
+  [ -n "$ollama_ctx" ] && real_ctx="$ollama_ctx"
+fi
+
+parts=""
+
+[ -n "$model" ] && parts="$model"
+
+if [ -n "$effort" ]; then
+  [ -n "$parts" ] && parts="$parts | $effort" || parts="$effort"
+fi
+
+if [ -n "$used_pct" ] && [ -n "$ctx_size" ]; then
+  used_k=$(awk "BEGIN {printf \"%.0f\", ($used_pct/100)*$ctx_size/1000}")
+  total_k=$(awk "BEGIN {printf \"%.0f\", $real_ctx/1000}")
+  tokens_part="${used_k}k / ${total_k}k"
+  [ -n "$parts" ] && parts="$parts | $tokens_part" || parts="$tokens_part"
+fi
+
+if [ -n "$remaining" ]; then
+  rounded=$(printf '%.0f' "$remaining")
+  reset=$'\033[0m'
+  if [ "$rounded" -lt 15 ]; then
+    ctx_part=$'\033[31m'"⚠ ${rounded}%${reset}"
+  elif [ "$rounded" -lt 30 ]; then
+    ctx_part=$'\033[33m'"${rounded}%${reset}"
+  else
+    ctx_part=$'\033[32m'"${rounded}%${reset}"
+  fi
+  [ -n "$parts" ] && parts="$parts | $ctx_part" || parts="$ctx_part"
+fi
+
+printf "%s" "$parts"

package/tooling/python/configs/.coveragerc

@@ -0,0 +1,14 @@
+[run]
+source = src
+branch = True
+omit =
+    tests/*
+    */__init__.py
+data_file = .coverage_cache/.coverage
+
+[report]
+show_missing = True
+skip_empty = True
+
+[html]
+directory = .coverage_cache/html

package/tooling/python/configs/.python-version

@@ -0,0 +1 @@
+3.14

package/tooling/python/configs/mypy.ini

@@ -0,0 +1,6 @@
+[mypy]
+python_version = 3.14
+strict = True
+ignore_missing_imports = True
+exclude = (?x)(^tests/ | ^docs/)
+mypy_path = src

package/tooling/python/configs/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+addopts = -ra -q
+testpaths = tests
+pythonpath = src

package/tooling/python/configs/ruff.toml

@@ -0,0 +1,15 @@
+indent-width = 4
+line-length = 88
+target-version = "py314"
+
+[lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP", "N"]
+ignore = ["E501", "B008"]
+
+[format]
+quote-style = "single"
+indent-style = "space"
+line-ending = "auto"
+
+[lint.flake8-tidy-imports]
+ban-relative-imports = "all"

package/tooling/python/configs/scripts/verify.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+set -e
+set -o pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+NESTED="${VERIFY_NESTED:-false}"
+
+log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
+log_error() {
+  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
+  exit 1
+}
+log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
+
+pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
+  command -v uv >/dev/null 2>&1 || log_error "uv is not installed"
+}
+
+run_check() {
+  local cmd=$1
+  local err_msg=$2
+  local output
+  if ! output=$(eval "$cmd" 2>&1); then
+    echo "$output" | pipe_output
+    log_error "$err_msg"
+  fi
+  echo "$output" | pipe_output
+}
+
+main() {
+  check_dependencies
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  echo -e "${GREY}├${NC} ${WHITE}Typecheck${NC}"
+  run_check "bun run typecheck" "Typecheck failed"
+  log_info "Typecheck passed"
+
+  log_step "Lint"
+  run_check "bun run lint" "Lint failed"
+  log_info "Lint passed"
+
+  log_step "Formatting"
+  run_check "bun run format" "Format failed"
+  log_info "Format applied"
+
+  log_step "Format check"
+  run_check "bun run check:format" "Format check failed"
+  log_info "Format check passed"
+
+  log_step "Spelling"
+  run_check "bun run check:spell" "Spell check failed"
+  log_info "Spell check passed"
+
+  log_step "Shell"
+  run_check "bun run check:shell" "Shell check failed"
+  log_info "Shell check passed"
+
+  log_step "Unit tests"
+  run_check "bun run test:run" "Unit tests failed"
+  log_info "Unit tests passed"
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Verification passed${NC}"
+  fi
+}
+
+main "$@"

package/tooling/python/manifest.toml

@@ -0,0 +1,16 @@
+[stack]
+name = "python"
+extends = "base"
+runtime = "uv"
+scaffold = "uv init --app {{name}}"
+
+[scripts]
+"lint" = "uv run ruff check . && uv run ruff format --check ."
+"lint:fix" = "uv run ruff check --fix . && uv run ruff format ."
+"typecheck" = "uv run mypy ."
+"test" = "uv run pytest"
+"test:run" = "uv run pytest -v"
+"test:cov" = "uv run pytest --cov --cov-report=term-missing --cov-report=html"
+
+[gitignore]
+"# Python" = [".pytest_cache/", ".mypy_cache/", ".ruff_cache/", ".coverage_cache/"]

package/tooling/python/reference.md

@@ -0,0 +1,66 @@
+# Tooling Python reference
+
+> Extends: `base`. Apply base stack first.
+
+## Overview
+
+The python stack covers Python 3.13+ projects managed with `uv`. It ships golden sidecar configs for `ruff`, `mypy`, `pytest`, and `coverage`, plus a `.python-version` pin and a python-aware `verify.sh`. Framework adapters layer on top with their own deps and configs.
+
+Configs ship as sidecar files (`ruff.toml`, `mypy.ini`, `pytest.ini`, `.coveragerc`) rather than `[tool.*]` sections in `pyproject.toml`. Sync overwrites configs on every run, so keeping them sidecar avoids stomping the user-owned `[project]` block in `pyproject.toml`.
+
+## Scaffold checklist
+
+1. Scaffold with `uv init --app <name>`. This creates `pyproject.toml`, `.python-version` pinned to 3.14, `src/<name>/`, and a starter `main.py`. `uv init` defaults `requires-python` to `>=3.14`, which matches the `.python-version` pin this stack ships.
+2. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`. Without this `aitk tooling sync` drops base configs but skips the dep install, since `resolve_missing_deps` short-circuits when `package.json` is absent.
+3. Install base tooling: `aitk tooling sync base .`
+4. Install python tooling: `aitk tooling sync python .`
+5. Install Python tooling deps: `uv add --dev ruff mypy pytest pytest-cov`. v1 of this stack does not declare these in `[dependencies.dev]` because manifest injection hardcodes `bun add -D`, which can not install Python packages. Until the injector branches on `runtime`, this step is manual.
+6. Sync the lockfile and create the venv: `uv sync`.
+7. Annotate `main()` in the scaffold-generated `main.py` with `-> None`. `uv init --app` ships an unannotated `main()` that fails strict mypy on the first run.
+8. Run `bun run lint:fix` then `bun run check`.
+
+The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest` collects at least one test on first run, so `bun run test:run` exits 0 instead of the empty-collection exit code 5. Delete or replace the smoke test with real tests.
+
+## What ships as golden configs
+
+- `ruff.toml`: line length 88, target `py314`, strict lint rules (`E`, `W`, `F`, `I`, `B`, `C4`, `UP`, `N`), single-quote format, banned relative imports.
+- `mypy.ini`: strict mode, `python_version = 3.14`, `mypy_path = src`, excludes `tests/` and `docs/`.
+- `pytest.ini`: tests live under `tests/`, source under `src/`.
+- `.coveragerc`: branch coverage on `src/`, html report under `.coverage_cache/html`.
+- `.python-version`: pinned to `3.14` to match `uv init --app` defaults.
+- `scripts/verify.sh`: overrides base verify to add Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) phases.
+
+## Hybrid project shape
+
+A python project synced with this stack ends up with both `package.json` from base and `pyproject.toml` from `uv init`. The base layer brings prettier, cspell, commitlint, and husky for non-Python files. Both `node_modules/` and `.venv/` coexist at the project root. The hybrid shape gives Python projects access to the toolkit's cross-cutting tools without forking the base stack.
+
+## Dependencies
+
+The manifest declares no `[dependencies.dev]`. Manifest injection currently calls `bun add -D` for any declared deps, which would fail for Python packages. v1 sidesteps this by leaving the section empty. Framework adapters that need Python deps require the injector to branch on `runtime` or detect `pyproject.toml` and call `uv add --dev` instead.
+
+## Verify command
+
+`aitk tooling verify <stack>` currently runs `bun run lint:fix` and `bun run check` against any stack with a `package.json`. Since base ships a `package.json`, those run for python too. Python's verify.sh wraps the package.json `lint`/`typecheck`/`test:run` scripts that delegate to `uv run`, so the verify path works end-to-end as long as `uv` is installed in the verify environment. The end-to-end test and screenshot phases are gated on `package.json` script keys that python does not declare, so they cleanly skip.
+
+## Anti-patterns
+
+- Do not use `pip` directly. Always go through `uv add` / `uv sync` / `uv run`.
+- Do not move `[tool.ruff]`, `[tool.mypy]`, `[tool.pytest.ini_options]`, or `[tool.coverage.*]` into `pyproject.toml`. Sync owns the sidecar files. Editing `pyproject.toml` tool sections will conflict with the sidecars and produce silent precedence bugs.
+- Do not pin Python via `[project] requires-python` and `.python-version` independently. Treat `.python-version` as the source of truth and let `requires-python` in `pyproject.toml` track it.
+- Do not add `commitizen` for conventional commits. The base stack already ships commitlint + husky. Two enforcers is one too many.
+- Do not ship a `Dockerfile` or `mkdocs` config under tooling. Those are framework or deployment choices and belong in the project itself or in a future adapter stack.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run lint` | Run `ruff check` and `ruff format --check`. |
+| `bun run lint:fix` | Auto-fix with `ruff check --fix` then `ruff format`. |
+| `bun run typecheck` | Run `mypy` in strict mode. |
+| `bun run test` | Run `pytest`. |
+| `bun run test:run` | Run `pytest -v` (used by `verify`). |
+| `bun run test:cov` | Run `pytest` with branch coverage and HTML report. |
+
+## CI docs (extend)
+
+In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `mypy .` passes ``. Add a Lint row whose assertion reads: `` `ruff check` and `ruff format --check` pass ``. Add a Tests row whose assertion reads: `` `pytest` exits 0 ``.

package/tooling/python/seeds/.cspell/tech-stack.txt

@@ -0,0 +1,19 @@
+addopts
+appuser
+asyncio
+coveragerc
+dotenv
+fastapi
+flake8
+htmlcov
+mkdocs
+mypy
+pycache
+pyproject
+pytest
+pythonpath
+PYTHONUNBUFFERED
+ruff
+testpaths
+venv
+virtualenv

package/tooling/python/seeds/tests/test_smoke.py

@@ -0,0 +1,2 @@
+def test_smoke() -> None:
+    assert True