yisroelbaum/Attainly
1
0
Fork 0
Code Issues 1 Pull requests Projects 1 Releases Packages Wiki Activity Actions

align ai workflow rules

Browse source
This commit is contained in:
Yisroel Baum 2026-08-03 19:59:36 +03:00
parent 4241f5ba29
commit efb932903b
Signed by: yisroelbaum
GPG key ID: 0FA60884F75520A9
3 changed files with 205 additions and 220 deletions
Download patch file Download diff file Expand all files Collapse all files

157
ai/shared.md
View file

@ -39,6 +39,24 @@ Use judgment for changes that cannot meaningfully be test-driven, such as
documentation-only edits or declarative environment configuration. Validate
those changes with the most relevant parser, formatter, dry run, or check.
## Maintaining these instructions
- Treat user steering as durable when it corrects or establishes a reusable
project rule for workflow, architecture, conventions, validation, safety,
or scope.
- When durable steering is received during work, update the appropriate
`ai/*.md` file in the active worktree before completing the task. Do not
wait for a separate request to maintain the instructions.
- Put repository-wide rules in `shared.md` and stack-specific rules in the
matching backend or frontend guide.
- Merge new guidance into the existing rule set. Keep it concise, remove
duplication, and resolve conflicts between shared and stack-specific text.
- Do not persist task-specific scope, temporary directions, secrets,
environment incidents, or instructions that conflict with higher-priority
guidance.
- Commit a durable instruction update separately from implementation unless
the task itself is solely an instruction change.
## Approval discipline
- Treat dependency installation, tests, static analysis, formatting, linting,
@ -64,58 +82,42 @@ those changes with the most relevant parser, formatter, dry run, or check.
- A worktree owns its own isolated stack. The flake shell hook assigns a
deterministic port offset and creates worktree-local PostgreSQL state.
- Start a worktree stack only when runtime or integration validation requires
it. Start it once from the worktree root, reuse it throughout validation,
and stop it once when finished.
- Do not start any service for PHPUnit, frontend formatting, linting, type
checking, or production builds.
- When authorized worktree stack control is necessary, operate it directly.
Do not ask the user to start or stop worktree services.
- For non-interactive use, start the stack detached and stop it when finished,
as shown below.
- Do not use `process-compose -t=false` for a detached stack. It can leave an
it. Start it once, reuse it throughout validation, and stop it once when
finished.
- PHPUnit, frontend formatting, linting, type checking, and production builds
do not require services. The Cypress completion suite does require the
worktree stack.
- When worktree stack control is necessary, operate it directly. Do not ask
the user to start or stop worktree services.
- Never use `process-compose -t=false` for a detached stack. It can leave an
orphaned PostgreSQL process holding the data directory.
- Non-interactive agent shells do not automatically load direnv. Bare project
commands can use missing tools, default ports, or paths from the main
checkout.
- Run project tooling that depends on the repository development environment
through direnv. This includes PHP, Composer, Artisan, npm, tests, builds,
database clients, and services.
- Resolve the direnv target from the worktree containing the agent's current
working directory. Never target the main checkout or a different worktree:
- Run PHP, Composer, Artisan, npm, tests, builds, database clients, and
services through the development environment.
- Resolve the direnv target from the worktree containing the current working
directory. Never target the main checkout or a different worktree:
```sh
direnv exec "$(git rev-parse --show-toplevel)" <command>
```
- Git and environment-neutral read-only file inspection do not need the
direnv wrapper.
- Worktree stack examples:
- Git and environment-neutral read-only inspection do not need direnv.
- Start and stop a worktree stack from its root:
```sh
direnv exec "$(git rev-parse --show-toplevel)" process-compose up -D
direnv exec "$(git rev-parse --show-toplevel)" process-compose down
```
- Run backend commands from `backend/`, or explicitly change into it in the
command. The direnv target remains the worktree root.
- Run frontend commands from `frontend/website/`.
- `process-compose` starts the frontend on the worktree's assigned port. To
start only the frontend:
```sh
direnv exec "$(git rev-parse --show-toplevel)" \
npm run dev -- \
--host 127.0.0.1 \
--port "$VITE_PORT" \
--strictPort
```
- Run backend commands from `backend/` and frontend commands from
`frontend/website/`. The direnv target remains the worktree root.
- When a normally valid check fails because a required service is down,
surface the environmental failure. Do not skip the check or silently switch
to a different database or service.
surface the environmental failure. Do not skip the check, change databases,
or claim the work is complete.
- PHPUnit is self-contained and uses in-memory SQLite. It does not require the
PostgreSQL stack unless a future test is explicitly designed as a real
PostgreSQL integration test.
PostgreSQL stack unless a future test explicitly targets real PostgreSQL.
## Code style
@ -155,14 +157,13 @@ those changes with the most relevant parser, formatter, dry run, or check.
- Do not include drive-by formatter or linter changes. Restore them or land
them as a separate formatting commit.
- If a check fails on untouched code, do not bundle an unrelated fix. Report
the pre-existing failure or handle it as its own explicitly scoped change.
the baseline failure or handle it as its own explicitly scoped change.
## Branching
- Never implement features directly in the main checkout or on
`master`/`main`.
- Use a dedicated worktree under
`<repo-root>/.worktrees/<branch>`.
- Use a dedicated worktree under `<repo-root>/.worktrees/<branch>`.
- Create it with:
```sh
@ -183,10 +184,10 @@ those changes with the most relevant parser, formatter, dry run, or check.
```
- Never symlink `backend/vendor` or `frontend/website/node_modules` from
another checkout. Dependency paths and generated files must remain
another checkout. Dependencies and generated files must remain
worktree-local.
- The shell hook installs backend dependencies but does not install frontend
dependencies. From `frontend/website/`, provision them with:
- The shell hook installs backend dependencies but not frontend dependencies.
Install frontend dependencies from `frontend/website/`:
```sh
direnv exec "$(git rev-parse --show-toplevel)" npm install
@ -196,59 +197,35 @@ Do not push anything. Make commits as the TDD workflow requires.
## Before completing a change
Run the smallest relevant checks while iterating, then run every repository
gate affected by the change.
A change is not complete until the worktree stack is ready and the unified
gate passes against that worktree:
### Backend
1. Start the stack detached from the worktree root:
- Run tests from `backend/`:
```sh
direnv exec "$(git rev-parse --show-toplevel)" \
process-compose up -D
```
```sh
direnv exec "$(git rev-parse --show-toplevel)" php artisan test
```
2. Poll `process-compose process list` until every process is running and
ready.
3. Run the complete gate from the worktree root:
- Run the Composer checks defined by `backend/composer.json`:
```sh
direnv exec "$(git rev-parse --show-toplevel)" just test-all
```
```sh
direnv exec "$(git rev-parse --show-toplevel)" composer types:check
direnv exec "$(git rev-parse --show-toplevel)" composer test
```
4. Do not hand-assemble a substitute from focused commands. `test-all` runs
frontend format and lint checks, frontend type checking, Larastan, the
production build, PHPUnit, and Cypress in fail-fast order.
5. Everything must pass before completion. Report exact baseline or
environmental failures rather than hiding them.
6. If the stack was started only for validation, stop it when finished:
- Do not claim a green gate when a command fails. If the failure predates the
change, report the precise baseline failure.
```sh
direnv exec "$(git rev-parse --show-toplevel)" process-compose down
```
### Frontend
- Run these commands from `frontend/website/`:
```sh
direnv exec "$(git rev-parse --show-toplevel)" npm run format
direnv exec "$(git rev-parse --show-toplevel)" npm run lint
direnv exec "$(git rev-parse --show-toplevel)" npm run type-check
direnv exec "$(git rev-parse --show-toplevel)" npm run build
```
- The formatter and linters rewrite files. Review their changes before
committing.
- No frontend test runner is configured yet. Do not claim unit, component, or
end-to-end test coverage until the relevant scripts exist and pass.
### Environment and integration
- For Nix or shell-hook changes, run:
```sh
direnv exec "$(git rev-parse --show-toplevel)" nix fmt
direnv exec "$(git rev-parse --show-toplevel)" nix flake check
```
- For service configuration changes, run:
```sh
direnv exec "$(git rev-parse --show-toplevel)" \
process-compose --dry-run
```
- When a change affects runtime wiring, start the worktree's stack and verify
the relevant endpoint or service against that worktree.
- If you started the stack only for validation, stop it before finishing.
Focused `just` recipes are for iteration only. For Nix or shell-hook changes,
also run `nix fmt` and `nix flake check`. For service configuration changes,
also run `process-compose --dry-run`.