kenn-forge is a local-first maintainer console. A Go/Huma server syncs provider-backed pull requests, issues, and activity into SQLite and serves an embedded Svelte 5 SPA. Kata and Docs are separate first-class modes whose data remains owned by their external or filesystem domains. The project builds without CGO; use the README and Makefile for discoverable setup, build, and development commands.
These rules win over any skill, hook, context document, or review finding.
- Check the code that runs. Before relying on how existing code or a provider behaves, read the call that actually executes and the primary docs for that endpoint and version. Mark anything unchecked as unverified, in chat and in commit messages; reviewers read commit messages as context.
- Make the smallest change. Reuse existing helpers, components, and types before writing new ones. Ask before adding anything the request did not ask for: new state, caches, caps, retries, guards, options, compatibility shims, or UI. When a bug recurs in another place, fix its cause once.
- Answer findings; do not obey them. Before changing code for a review
finding, confirm it against the running code. Decline a wrong, unreachable,
or out-of-scope finding with evidence where the reviewer will see it
(
roborev comment <job>, or a PR reply), never only in chat. A finding that returns after you addressed it means the design is wrong: stop and rethink. - Done means shown. Do not say tests pass, CI is green, a bug is fixed, or
a PR is ready without output from this turn that proves it. A failure is
flaky only if it also fails on
mainor passes on an unchanged rerun.
kenn-forge supports GitHub, GitLab, Forgejo, Gitea, and Bitbucket Cloud/Data Center. This is the single
canonical provider list; gitealike is the shared Forgejo/Gitea adapter.
Provider-backed features must work across every supported provider within its
declared capabilities and preserve provider-verified stable repository identity;
owner/name remains a mutable route. The routing table below owns the detailed rules.
Before using provider state to gate an action, establish which credential queried it, which resource revision it describes, and whether it is fresh. Test differing read/write identities, including an allowed user who needs no bypass and a denied user. Verify provider assumptions before encoding them in mocks.
Kata and Docs are first-class modes, not platform providers. Do not force them
through platform: their data remains owned respectively by Kata
daemons and configured filesystem folders.
Read the smallest relevant set of topic documents before changing or reviewing the corresponding area. These documents own the detailed invariants; this file only routes to them.
| When working on | Read |
|---|---|
| Provider interfaces or package boundaries | context/provider-architecture.md |
| Provider identity, sync, import, routes, or settings | context/platform-sync-invariants.md |
| GitHub-specific sync or notifications | context/github-sync-invariants.md, context/notifications-in-activity.md |
| Config fields that persist to TOML | context/config-persistence.md |
| External PR context commands, cards, or actions | context/external-pr-context.md |
| Database schema migrations or the SQLite connection layer | context/db-migrations.md |
| Deferred merge behavior | context/deferred-merge.md |
| Daemon startup, discovery, host/origin validation, or SSE replay | context/server-runtime.md |
| Activity relay protocol, consumer, or status | context/server-runtime.md, context/github-sync-invariants.md |
| Fleet settings, snapshots, host routing, or peer transports | context/fleet-architecture.md |
| API failures or frontend error branching | context/error-handling.md |
| Retries, rate limits, scheduling, or single-flight work | context/retries-and-backoffs.md |
OpenTelemetry spans, trace export, or tools/observability |
context/server-runtime.md |
| Go test commands, assertions, fixtures, or shell tests | context/testing-basics.md |
| Test lanes, provider tests, API contracts, or HTTP tests | context/testing.md |
| Repository-controlled session bootstrap or dependency installation | context/agent-bootstrap.md |
| User documentation, screenshots, or the Zensical site | context/docs-authoring.md |
| CI runner policy, pushing, opening a pull request, or changing PR metadata, comments, or review threads | context/pull-request-workflow.md |
| Frontend visual design or component conventions | context/ui-design-system.md |
| Frontend Effect workflows, services, layers, errors, or async ownership | context/frontend-effect.md |
| Frontend interaction, route state, persistence, or input semantics | context/ui-interaction-contracts.md |
| Phone routes, narrow layouts, or touch UX | context/mobile-ux.md |
| Workflow or terminal panel interaction models | context/vscode-workflow-panel-interaction-spec.md |
| MCP companion tools, transports, safety boundary, or agent handoff | context/mcp-server.md |
| Worklists, their MCP tools, freshness, or worklist UI | context/worklists.md, context/mcp-server.md |
| Embeddings config, the semantic index, semantic list ranking, or palette Meaning mode | context/semantic-search.md |
| Workspace APIs, creation, item identity, lifecycle hooks, or generated launch context | context/workspace-apis.md |
| Workspace deletion, runtime sessions, tmux, or terminal UI | context/workspace-runtime-lifecycle.md |
| Repository source-browser routes, clones, refs, or previews | context/repository-source-browser.md |
| Inline diff review drafts, comments, or threads | context/inline-review-comments.md |
| Kata task authority, daemon integration, task UI, or Kata workspaces | context/kata-mode.md, context/workspace-apis.md |
| Markdown folders, Docs APIs, or git publishing | context/docs-mode.md |
- Prefer stdlib over external dependencies
- Before hand-rolling file-safety or filesystem helpers, reuse
go.kenn.io/kit(for examplefslink.ReadFilefor regular-file-only reads,safefileiofor private files); do not reimplement what Kit already owns - Never make backward-incompatible changes to the activity relay wire format. Relays and Forge clients upgrade independently; preserve existing field types, meanings, and events, and verify changes against fixed wire fixtures from deployed versions.
- The
kenn-forgebinary has one Cobra root command. Register every public command on that tree; do not add a second parser, manual dispatcher, or command-facingflag.FlagSet. (cmd/kenn-forge/cli.go::newRootCommand) - CLI flags must affect execution or fail validation; reject shared persistent flags outside the commands that consume them instead of silently ignoring user input. (
internal/cli/ctl/ctl.go::installControlFlagValidation) - Extend an existing route or MCP tool that already lists, filters, resolves, and forwards the same items instead of adding a parallel one; a new mode on the existing path inherits its filters, repository resolution, and hub forwarding
- Use
humafor the web framework and OpenAPI generation - Regenerate API artifacts with
make api-generate; the Go client also supportsgo generate ./internal/apiclient/generated - The maintainer's local backend and frontend run under process-compose; never launch unsupervised replacements. Never run
kenn-forge daemon start|restart|stopagainst its config.daemon restartswaps it for an unsupervised detached copy of the invoking binary. (process-compose.yml) - Tests, docs, fixtures, commit messages, and PR text should use generic synthetic examples unless the user explicitly asks to preserve exact private project names, paths, prose, or domain details.
- Use Bun only for dependency installation — run
bun install, and launch Vite+, Vitest, Svelte tooling, and Playwright with Node via./node_modules/.bin/vp ...(or../node_modules/.bin/vp ...fromfrontend/). Never use npm; it createspackage-lock.json, which conflicts with the Bun lockfile - No emojis in code or output
- Sub-second race windows that self-heal on the next event or pass are accepted eventual consistency. Do not fix them, add guards for them, or raise them as review findings; the maintainer has decided this. A window self-heals only if the next sync or pass restores the right state before anything irreversible (a merge, a deletion) acts on the wrong one. Decide which side of that line a finding is on once, and refute later repeats with a
roborev commentthat cites the earlier decision. - A context owns every network connection, socket, and stream the application opens, and the
connection ends with it, including upgraded connections
http.Server.Shutdownno longer tracks. Blocking dials and stream opens take the caller's context. (internal/server/federation_tunnel.go::Server.serveFederationTunnel) - A function that blocks, does I/O, runs a subprocess, or waits on another goroutine takes
ctx context.Contextfirst and passes it on. Start subprocesses withprocutil.CommandContext;noctxcannot see throughprocutil.Command. Create a new root context only inmain, server and daemon lifecycle roots, and shared or cached work that no single caller owns, with a comment saying why. Cleanup that must finish after cancellation usescontext.WithoutCancel(ctx). Tests uset.Context();context/testing-basics.mdcovers cleanup. Lint enforces the rest (.golangci.overlay.yml). - Another repository taking over an owner/name route that a stale reference (a Gone worklist item, an old link or URL) still names is vanishingly rare. Beyond carrying the stable identity the code already has, do not add guards or tests for its follow-on effects, or raise them as review findings; the maintainer has decided this.
- Datetimes are UTC across storage and API boundaries. Store timestamps in UTC, emit API timestamps as UTC RFC3339, and only convert to local time in the Svelte UI presentation layer.
- Never invoke the
roborev reviewCLI command in any form unless the user explicitly asks for it. Use all otherroborevCLI commands normally when they are appropriate for interacting with roborev. Never invoke a roborev skill (includingroborev-fixorroborev-design-review-branch) unless the user explicitly asks for that skill.
The CI gate job runs on a Namespace profile that uses Namespace's
Restricted access level,
which disables workload access to Namespace features and APIs. GitHub fork
approvals, token permissions, and secrets are separate controls. See
context/pull-request-workflow.md for runner selection.
- Commit and push every turn — always commit and push your work at the end of each turn, after required checks
- Superpowers design specs and implementation plans are temporary working artifacts; never commit
or retain them. Before committing, distill current contracts into the matching
context/topic docs and delete the artifacts. Do not convert a transient spec into an ADR to preserve it. - Record what the code cannot tell you — run the
context-syncskill with--commitonly when the maintainer stated a durable decision or corrected you during this work. Context documents hold decisions, invariants, and structure no single file shows; never restate what reading the code shows. - Never amend commits — always create new commits for fixes, never use
--amend - Never change branches — don't create, switch, or delete branches without explicit permission
- Never bypass pre-commit hooks — all commits must go through a hook-enforced Git commit path. Do not use
jjor any other workflow to create, rewrite, or finalize commits in a way that skips the repository's Git hooks - Kata task identifiers are internal execution metadata; never include them in branch names, commit messages, PR titles or descriptions, or GitHub comments.
- Pull requests must have a user-facing benefit or improve the developer experience, and the body must say which one.
- Write issues and pull requests in English.
- End every commit message with a
Co-authored-by:trailer naming the agent that wrote the change. - End the pull request description with a
Model used:line naming the model, such asModel used: Opus 5.5orModel used: GPT-6.1 Sol. Squash-merge keeps only the description, so put theCo-authored-by:trailer there too. - Write commit messages and PR titles as Commit Messages requires.
- Commit bodies must add any important context about the bug, regression, constraint, or tradeoff that motivated the change; do not rely on the diff to explain intent
- Never push unless the repository's non-mutating lint check passes after the final relevant edit; keep local and CI linter versions aligned. (
Makefile,prek.toml,.github/workflows/ci.yml) - Before pushing any frontend change, you must have run the tests covering the changed files locally after the final frontend/test edit (
../node_modules/.bin/vp test related <changed source files> --runfromfrontend/, which also finds tests of components that render them), plus every Playwright spec intests/e2eandtests/e2e-fullthat exercises the changed behavior, found by grepping both lanes for the changed labels, roles, and routes, not only specs the change edits; type checks and CI-only verification are not enough. Vitest does not type-check, so runmake frontend-check-core-no-depstoo. CI runs the full suites.
Commit subjects must use the Conventional Commits format. Pull requests are squash-merged: the PR title becomes the commit subject and the PR description becomes the commit body, so PR titles use the same format.
type(scope): summary
The scope is optional and names the part of the project the change touches. Use one of these types:
feat: a new capability users can see or use.fix: a bug fix users can notice.perf: faster or lighter behavior users can notice.refactor,test,docs,build,ci, orchore: a change that leaves product behavior as it was.
Mark a breaking change with ! before the colon, as in feat(api)!: remove the v1 endpoints, and describe the break in a BREAKING CHANGE: footer at the end of the commit body or PR description.
The summary explains the reason or user-visible outcome, not just the mechanical change. Good subjects answer "why does this commit exist?" (for example, fix: restore workspace activity for launched agents), while vague mechanics such as fix: run agents under tmux are not acceptable on their own.
This format is required. Releases and release notes are generated from these messages: the type decides whether a change appears in the notes and under which heading, and the version bump follows the largest change since the last release, from a breaking change to feat to fix.