Working with agents

Applies to DevSikt 1.0.0. Prerequisites: the extracted source, its root AGENTS.md, a source-control checkpoint or backup, and a working npm run dev preview.

DevSikt supports conventional editing and agent-assisted work. An agent is optional; the same source files, build outputs and npm commands apply either way. Agent-generated changes still need review.

First agent-assisted edit

Outcome: change the overview heading without changing theme behavior. Files: index.html only. Ask the agent to read AGENTS.md, inspect the existing worktree, change the visible overview heading to your chosen text, and leave the queue, IDs, classes and imports untouched. The manual equivalent is to edit that same heading in your editor.

Open the development overview and confirm the new heading, then run npm run build and inspect npm run preview. Expected result: the same heading appears in both versions, with working navigation and no styling flash. Review the diff before accepting it. Restore the sample text after this exercise if you want fixture-specific tests to remain unchanged, then run npm run check.

If the agent edits generated output or absent files, stop and point it at the extracted source root. If a test expects the old heading, distinguish an intentional content change from a broken behavior; update a content assertion only after reviewing its purpose. Never disable an entire test or accessibility rule to make a customization pass.

Give a bounded brief

Name the page, expected interaction, source boundary and acceptance checks. State whether the task is a static UI preview or a real integration. This example asks for a local theme change only:

Read AGENTS.md and inspect chat.html and its controller before editing.
Add a local example attachment-removal control to the chat composer.
Keep customer changes in src/project/ and the page source.
Do not connect a model, upload files, add dependencies or edit src/theme/.
Preserve keyboard submission, stop, retry and focus behavior.
Test empty, pending, cancelled and error states.
Run npm run check and review 390x844, 768x1024 and 1440x1000
in light and dark. Report modified files, test results and limitations.

For a new page, include its proposed HTML file, controller, Vite entry and navigation destination. Ask the agent to inspect an existing shell rather than inventing a parallel styling system. For diagnosis-only requests, explicitly say not to implement changes yet.

Protect shared code

Ask the agent to read AGENTS.md before making changes. Keep an unchanged baseline or version-control commit, and have it inspect existing modifications before editing. Do not allow generated dist/, dist-docs/ or dependency files to become the source of a fix.

Review changes to src/theme/ separately because they affect every consumer. Do not add frameworks or dependencies for small visual conveniences. Never paste real keys into a task, fixture, screenshot or client-side source file. Real integrations require a separate architecture and security review; a working-looking theme screen does not provide a backend.

Work in small batches

Give each task an explicit set of files and a testable outcome. Independent tasks may run in parallel when their ownership does not overlap. Assign one integrator for shared navigation, build configuration and final validation; avoid multiple browser suites competing for port 5198.

Finish writes before the integrated check. Vite can reload pages when source or documentation changes during browser tests. If a task is blocked, ask for the exact failing command or missing decision instead of accepting a weakened test or a silently removed behavior.

Review evidence

Ask for the following handoff:

• Modified source files and a short explanation of ownership.
• Commands actually run, their results and anything not tested.
• Screenshots at the reference sizes, including dark mode.
• Keyboard checks for menus, dialogs, forms and recovery flows.
• Clear distinctions between local simulation and external effects.

Reproduce the key interaction yourself, then build and open the compiled version. Check back/forward navigation, reload behavior, long content, no-data states and narrow screens. Passing automated accessibility rules does not prove a pleasant screen-reader experience. Screenshots do not prove a control works.

Verify that source changes reproduce the result and unrelated customer work was preserved. If a generated change is unsuitable, revert only that task's changes using your baseline; do not reset unrelated work.

Maintain documentation

Update Markdown in docs/content/ whenever commands, ownership or customer-visible behavior change. Describe how a customer can perform the same operation without an agent. Heading text becomes the link anchor, so keep existing public headings stable when possible. See Build & deployment for the article registration workflow.