twilom

Imported from iktrnch/twilom (AGENTS.md). Install upstream with npx skills add iktrnch/twilom. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

Twilom is a Tauri 2 desktop application. The SvelteKit/TypeScript frontend is in src/: routes live in src/routes/, with the current screen at src/routes/+page.svelte. Static frontend assets belong in static/.

The Rust host is in src-tauri/. Put Tauri commands and application setup in src-tauri/src/lib.rs; keep src-tauri/src/main.rs as the thin executable entry point. Tauri configuration and permissions live in src-tauri/tauri.conf.json and src-tauri/capabilities/.

Design contracts live in docs/: ADRs are under docs/decisions/, feature notes under docs/features/, and architecture notes under docs/architecture/. Use the matching file in docs/_templates/ when adding documentation.

Build, Test, and Development Commands

• bun run dev starts the Vite frontend for browser-focused work.
• __NV_DISABLE_EXPLICIT_SYNC=1 bun tauri dev runs the complete desktop application under wayland with the Rust host.
• bun run check synchronizes SvelteKit and type-checks Svelte and TypeScript.
• bun run build creates the static frontend build.
• cd src-tauri && cargo check type-checks the Rust host quickly.
• cd src-tauri && cargo test runs Rust tests when present.
• python3 scripts/generate_docs_index.py docs regenerates docs/index.md after documentation changes.

Coding Style & Naming Conventions

Follow existing Svelte formatting: two-space indentation, TypeScript in <script lang="ts">, and component-local styles where appropriate. Name route files according to SvelteKit conventions (+page.svelte, +layout.ts).

Use standard Rust style (four spaces) and run cargo fmt before submitting Rust changes. Prefer snake_case for Rust functions/modules, PascalCase for types, and expose frontend-to-Rust calls as explicit #[tauri::command] functions.

Use tdd skill for new features. Refer to the docs for the current design and architecture.

Testing & Documentation

Add focused Rust unit tests next to the code they exercise; name them for the observable behavior, e.g. restores_compatible_workflow_run. There is currently no configured JavaScript test runner, so bun run check is the required frontend safety check. Regenerate the documentation index and preserve ADR numbering; accepted ADRs define design decisions.

Commits & Pull Requests

Recent commits use short, imperative, Title Case subjects (for example, Rebuild tauri project). Keep commits narrowly scoped. Pull requests should explain the user-visible or architectural change, link the relevant issue or ADR, list validation commands run, and include screenshots for UI changes. Do not commit .env files or generated local build output.

Milestone implementation workflow

These instructions apply whenever implementing a milestone from the Linear project twilom.

Sources of truth

Use sources in this order:

1. Applicable AGENTS.md files define the working process and repository rules.
2. docs/ defines externally observable behaviour, requirements, invariants, workflows, and failure handling.
3. Linear defines milestone scope, issue breakdown, dependencies, and progress.
4. Existing code defines current implementation details, but does not override documented behaviour.

Read docs/index.md, the milestone description, its Linear issues, and every documentation file relevant to the milestone before editing code.

If documentation conflicts about externally observable behaviour, stop and report the exact conflict. Do not silently select an interpretation. For unspecified internal implementation details, choose the simplest maintainable design consistent with the existing architecture.

Git safety

Before editing:

• Inspect the current branch, working tree, and recent history.
• Preserve all unrelated user changes.
• Never discard, overwrite, amend, or include unrelated changes in a commit.
• If overlapping uncommitted changes make safe implementation impossible, stop and report the conflict.
• Create the milestone branch from the latest local main when necessary.
• Derive a clear branch name such as milestone/01.
• Do not create branches for future milestones.
• Do not merge into main, push, publish, tag, or create a release.
• Do not rewrite published history.

Planning and Linear

Before implementation:

1. Fetch the milestone and its existing issues from Linear.
2. Compare its scope and acceptance criteria with the relevant documentation.
3. If suitable issues do not already exist, divide the milestone into small, ordered, independently testable Linear issues.
4. Attach new issues to the twilom project and the current milestone.
5. Give each issue:
   • A concrete observable outcome.
   • Relevant documentation references.
   • Acceptance criteria.
   • Explicit exclusions.
   • Dependencies where necessary.
6. Order issues so the project remains compiling and testable after each one.
7. Present a concise implementation plan and proceed without waiting for confirmation unless a genuine specification blocker exists.

Do not create speculative issues or issues belonging to later milestones.

Implementation loop

Implement milestone issues sequentially.

For each issue:

1. Mark the issue In Progress in Linear.
2. Add or update tests that demonstrate the required behaviour.
3. Implement only the behaviour required by the issue.
4. Run focused tests while developing.
5. Run the broader regression suite when the issue is complete.
6. Compare the implementation and tests with the issue acceptance criteria and relevant documentation.
7. Review the diff for unrelated changes and accidental scope expansion.
8. Commit the coherent passing change, referencing the Linear issue.
9. Mark the issue Done only after all acceptance criteria pass.

Prefer test-driven development whenever behaviour can reasonably be expressed in a test before its implementation.

Every commit must:

• Compile.
• Pass all tests relevant to the committed change.
• Represent one coherent change.
• Reference the relevant Linear issue where one exists.
• Avoid unrelated formatting, refactoring, or cleanup.

Never commit deliberately failing tests or a knowingly broken intermediate state.

Design and testing rules

• Keep domain logic separate from terminal, filesystem, network, process, IPC, and clock side effects.
• Use deterministic fixtures, temporary directories, fake processes, and mocked upstream services.
• Do not require Minecraft or internet access in the ordinary automated test suite.
• Preserve documented stdout, stderr, exit codes, file permissions, atomicity, cleanup, ordering, cancellation, and failure behaviour.
• Test negative and failure paths, not only successful execution.
• Avoid timing-dependent tests where deterministic synchronisation is possible.
• Do not add abstractions solely for hypothetical future milestones.
• Do not implement commands, protocol behaviour, or infrastructure belonging to later milestones.
• Do not add placeholder success paths, hidden TODO implementations, or tests that pass without exercising the claimed behaviour.
• An explicitly unavailable command may return a clear error when necessary to preserve a compiling scaffold.
• Do not change documented behaviour merely to simplify implementation.

Scope control

Work only on the requested milestone.

Small prerequisite changes are allowed only when they are necessary to make the current milestone compile or satisfy its documented behaviour. Keep them minimal and explain them in the completion report.

Do not:

• Begin another milestone.
• Perform speculative refactoring.
• Redesign adjacent systems without a demonstrated requirement.
• Mark incomplete behaviour as complete.
• Expand scope simply because related code is nearby.

Verification

Before declaring the milestone complete, run:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

Also run all milestone-specific integration and scenario tests.

After the commands pass, independently compare the finished implementation against every relevant:

• Requirement and acceptance criterion.
• Workflow and failure case.
• Interface and invariant.
• Cleanup and cancellation rule.
• Linear issue.

Add missing tests where practical instead of relying only on manual reasoning.

Completion and blockers

The milestone is complete only when:

• All documented behaviour within its scope is implemented.
• All milestone acceptance criteria pass.
• Required verification commands pass.
• All associated Linear issues accurately reflect their status.
• All completed work has been committed.
• No known required behaviour is hidden behind TODOs or placeholders.

When complete, stop without merging or beginning another milestone. Report:

• Branch name.
• Commits created.
• Linear issues completed or changed.
• Tests and verification commands run.
• Important implementation decisions.
• Necessary prerequisite changes.
• Any documented behaviour that remains incomplete.
• Risks the independent reviewer should inspect.
• Exact commands needed to reproduce verification.

If genuinely blocked:

• Preserve and commit only coherent passing work.
• Do not invent missing product behaviour.
• Record the blocker in Linear when appropriate.
• Stop and report the exact blocker, its impact, and the decision or information needed to continue.