# Flask Harness Profile

Use these snippets when the target project is a Flask app or API.

These files are agent reference material, not automatic transformations. Merge
only the pieces that fit the target project's existing tools.

Apply this profile by priority: always preserve existing app structure and exact
check commands; document local config, database, or fixture setup when present;
consider decision records only when changing architecture, persistence, config,
or extension policy; use a short report/check note for narrow fixes.

## Recommended Checks

- `python -m unittest discover -s tests` for standard-library tests.
- `python -m flask --app <app_package> routes` to validate the Flask app can
  import and register routes.
- `scripts/check_docs_drift.py` for stale documentation references.
- `scripts/check_structure.py` for temporary or drift-prone files.

Prefer the target repository's virtual environment path when documenting
commands. On Windows PowerShell, that is often:

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests
.\.venv\Scripts\python.exe -m flask --app sample_flask routes
.\.venv\Scripts\python.exe scripts\check_harness.py
```

## Suggested Check Script

Copy or adapt `check_harness.py` into the target repository's `scripts/`
directory when the project has no existing task runner.

## Profile Absorption Notes

When Flask is introduced after generic adoption:

- Copy or adapt `check_harness.py` into `scripts/` only when the target has no
  equivalent local verification command.
- Merge relevant ignores from `gitignore.harness.txt`, especially virtual
  environments, generated Python caches, Flask instance data, coverage output,
  local env files, and the local `harness-starter-kit/` clone.
- Update `AGENTS.md` with Flask commands, app import path, route inspection
  command, source directories, generated paths, and completion checks.
- Update `docs/conventions/coding.md` with app factory, blueprint, config,
  service, repository, testing, and error handling conventions.
- Consider a decision record when changing or selecting Flask, app structure,
  config strategy, persistence approach, or extension set. When the task only
  follows the existing architecture or makes a narrow fix, a final report or
  check note is enough.
- Keep optional local directories out of backtick path references unless they
  actually exist, so document drift checks stay useful.
- In the final report, list which snippets were adopted, adapted, skipped, or
  deferred.

## Flask Notes

- Prefer an app factory named `create_app`.
- Keep Flask package code under the application package, and keep route tests
  under `tests/`.
- Use Flask's test client for HTTP behavior checks.
- Use `python -m unittest discover -s tests` rather than bare
  `python -m unittest discover` when test discovery needs an explicit test
  directory.
- Do not edit or commit `.venv/`, generated Python caches, Flask instance
  directories, or the local `harness-starter-kit/` clone.
- Avoid documenting optional local directories as backtick paths unless they
  actually exist, because document drift checks may treat them as missing
  references.
- Add pytest, Ruff, mypy, or pre-commit only when they fit the target
  repository's existing tooling.
