8000 docs: point agents at the testing, eval and UI component guidance (#232) by simon-inkie · Pull Request #233 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8000
55 changes: 55 additions & 0 deletions .specs/232-agents-md-patterns/SPEC.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# #232: Point AGENTS.md to testing, eval and UI patterns

- Issue: [#232](https://github.com/simon-inkie/inkie-deck/issues/232)
- Branch: `agents-md-patterns`
- Started: 2026-11-19

## TL;DR

Add a short Patterns and tests section to `AGENTS.md` so agents can find the
testing, proposed eval and UI guidance. Link to the existing guides rather
than restating procedures.

## Scope

In scope:
- Summarise test priorities, safe shell and Nudges tests, the proposed eval
workflow and reuse of existing UI components and theme tokens.
- Add both guides to the opening pointers in `AGENTS.md`.

Out of scope:
- Changes to the guides, application code or test tooling.
- Running live agents, starting servers or using the network.

## Test plan

- Verify each summary against the guides and the repository's tests and UI.
- Run `COREPACK_ENABLE_NETWORK=0 COREPACK_DEFAULT_TO_LATEST=0 pnpm check:leaks`
and `node scripts/leak-gate.mjs`.
- Run the direct dash scan and expect no matches:
`rg --hidden --pcre2 -n '[\x{2014}\x{2013}]' --glob '!node_modules' --glob '!build' --glob '!.git' --glob '!.react-router'`.
- Run `git diff --check` and
`git diff --no-index --check /dev/null .specs/232-agents-md-patterns/SPEC.md`.
- Check both edited files for non-ASCII characters and verify the guide links.
No automated tests added for this documentation-only change.

## Follow-ups

None.

## Log

### 2026-11-19: Link the existing patterns from the orientation
- What changed: Added a compact section and links to both guides in `AGENTS.md`.
- Why: Agents need a quick pointer to safe tests and UI conventions without
mistaking the proposed eval workflow for existing tooling.
- Supersedes: nothing, additive
- Commits: pending

### 2026-11-19: Check the documentation offline
- What changed: Verified the links and guidance, and ran the direct dash scan,
ASCII scan and diff whitespace checks. They reported no issues.
- Why: Both leak gate commands were blocked by `spawnSync git EPERM` in the
sandbox. The leak gate still needs a run in an environment that permits it.
- Supersedes: nothing, additive
- Commits: pending
21 changes: 20 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ and action cards, projects and drafts, backed by a file-based message protocol.
This file is the short orientation for AI coding agents. The rules live in one
place each, so read these before your first change:
[CONTRIBUTING.md](CONTRIBUTING.md) (rules), [DEVELOPMENT.md](DEVELOPMENT.md)
(workflow), [README.md](README.md) and [INSTALL.md](INSTALL.md) (setup).
(workflow), [README.md](README.md) and [INSTALL.md](INSTALL.md) (setup),
[Testing and evals](docs/testing-and-evals.md) and [UI components](docs/ui-components.md).

## Map

Expand All @@ -32,6 +33,24 @@ place each, so read these before your first change:
5. Branch off `main`, keep each pull request to one change, and title commits
`type(scope): summary (#issue)`. Never push to `main`.

## Patterns and tests

- Test core behaviour, meaningful regressions and safeguards against
unexpected spend, data loss or leaks. Skip exhaustive low-risk edge cases
and implementation details unless they are part of the contract.
- Test shell scripts in subprocesses with temporary fixtures, fake homes and
stubs. For Nudges, use synthetic requests and fake cron dependencies, never
a real crontab. If tmux is needed, use a private fixture socket, never the
real `agents` session or the user's tmux. Do not run live agents for tests.
- The [eval workflow](docs/testing-and-evals.md#agent-evals-proposed-not-implemented)
is proposed, not implemented: use synthetic fixtures, check outputs and side
effects deterministically first, and use a fixed rubric for model grading
only where judgement is needed. Keep live evals opt-in and agree limits first.
- Feature components live in `packages/deck/app/components/`, with shared
primitives in its `ui/` subdirectory. Reuse existing components before adding
new ones and follow the semantic tokens in `packages/deck/app/app.css`.
See the [UI components guide](docs/ui-components.md).

## House rules

- No internal material (names, hosts, paths, ticket ids, addresses) in the
Expand Down
Loading
0