Workflow

How we build K-Web, especially when using agents (Cursor).

Tickets

Use GitHub Issues for work that changes code.

Each issue must include:

• goal (one paragraph)
• scope (what is in, what is out)
• acceptance checklist (observable)
• relevant spec links (events/modules)

Vertical slices

Prefer thin end-to-end slices:

• a small behavior across graph, timeline, map, and bio
• rather than fully building one module in isolation

Spec updates

If a change affects:

• data model
• event contracts
• module boundaries

then update the corresponding spec doc in the same PR.

ADRs

When making an architectural choice that will be hard to change later, write an ADR in ./adr/.

Examples:

• storage format choice
• routing model choice
• map/globe engine choice

PR checklist

• [ ] Links to issue
• [ ] Notes on behavior changes
• [ ] Updated specs (if needed)
• [ ] Tests pass
• [ ] Smoke tour completed (see ./testing.md)
• [ ] Screenshots or short clip if UI changed

How to prompt an agent

Template prompt:

• Read specs/README.md, specs/event-contracts.md, and module specs touched by this issue.
• Propose a plan with steps and acceptance checks.
• Implement in small commits.
• Run tests and do the smoke tour in a browser.
• Open a PR and include smoke tour notes.