Skip to content

AGENTS.md

Latest commit

 

History

History
113 lines (80 loc) · 4.46 KB

AGENTS.md

File metadata and controls

113 lines (80 loc) · 4.46 KB
Raw

AGENTS.md

Purpose

nyako is the definition repo built on top of nyakore.

It owns:

  • agent definitions
  • prompt assets
  • committed agent memory assets
  • schedules
  • project tools and skills
  • integration tools and project-wide routing behavior

It is not the place for:

  • session registry internals
  • runtime kernel behavior
  • protocol transport internals
  • credential storage logic
  • machine/account-specific channel, adapter, identity, or allowlist config

Those belong in nyakore.

Boundary

If a behavior is missing because the runtime lacks a primitive, fix nyakore.

Do not paper over runtime gaps here with:

  • prompt-only fake state
  • duplicated session bookkeeping
  • ad-hoc shadow routing systems
  • local integration config committed into repo files

Stack

  • Package manager: pnpm
  • Language for executable repo code: TypeScript
  • Runtime host: nyakore
  • Check: vp check
  • Test: vp test
  • Formatter/lint/test config lives in vite.config.ts

Required Commands

Before wrapping up meaningful changes, run:

vp check
vp test

If a command cannot run, state why.

After meaningful definition changes, do an end-to-end validation against a real nyakore runtime with an isolated NYAKORE_DATA_ROOT.

If the change touches schedules, tools, routing, or session behavior, prefer validating in tmux with separate Gateway/runtime and producer panes or equivalent real cross-process flows.

Commit Rule

All commits created from agent-driven work must use:

<gitmoji> <type>(<scope>): <subject>

scope is optional. Choose the gitmoji according to its normal meaning on gitmoji.dev, and keep the overall style aligned with the existing commit history in this repo.

All commits created from agent-driven work must also include an agent co-author trailer:

Co-authored-by: Codex <noreply@openai.com>

Repo Rules

  1. Keep runtime-independent behavior here; keep runtime primitives in nyakore.
  2. One agent per directory under agents/; do not collapse multiple personas into one folder.
  3. Project tools under tools/ should be small, explicit adapters around typed local config.
  4. Skills are optional, on-demand instructions; always-on constraints belong in AGENTS.md / TOOLS.md.
  5. Secrets, external account identifiers, user bindings, allowlists, and integration instance config never live in the repo; they belong in ~/.nyakore/config.toml.
  6. Session continuity is owned by runtime state, not by prompt fiction.
  7. If a monitor or integration needs cross-run truth, prefer explicit state files or tools over model memory.
  8. Keep definition files deterministic and file-oriented so nyakore can assemble prompts predictably.
  9. Local and remote repo work use the same lifecycle hook, with shared clones and Session worktrees under the selected device user's ~/.nyakore/projects/<project>/workspaces/. An explicit remote working directory takes precedence over automatic repository provisioning.
  10. Shared repo roots carry upstream synchronization state; session workspaces carry task execution state.
  11. Workspace acquisition, layout, and cleanup are defined by runtime workspace state and lifecycle hooks.
  12. External Skills belong in skills.lock.toml with a full immutable revision and canonical digest. A mutable ref is only an explicit update selector; startup must never advance it, and a local Skill directory must not shadow a locked Skill with the same name.

User-Visible Links

When reporting GitHub PRs, issues, discussions, or comments to the user, always provide a clickable Markdown link instead of only a bare number, raw URL, or plain repo#id text.

  • PR / issue display text must use [owner/repo#123](https://github.com/owner/repo/pull/123) or [owner/repo#123](https://github.com/owner/repo/issues/123).
  • Comment or review links should use [owner/repo#123 comment](https://github.com/owner/repo/pull/123#issuecomment-...) or an equally clear Markdown link.
  • This applies to user-visible summaries and to NNP payload fields that are intended to be forwarded or quoted to the user.
  • Machine-only fields, ledger keys, fingerprints, and structured routing fields may still keep separate repo, pr, issue, and url values.

Maintenance Rule

Keep this repo tidy:

  • remove dead schedules, tools, and prompt fragments
  • collapse duplicated policy text
  • keep README.md and this file aligned with actual behavior
  • move any generic capability that no longer belongs here back into nyakore