Provide a non-repository mechanism for loading Kata agent guidance from `kata init --with-agents`

[gadenbuie]

Summary

Would you consider exposing the managed agent briefing installed by kata init --with-agents as a stable, marker-free CLI output mode?

kata quickstart --format contract

The output should be the same canonical briefing body currently written between:

<!-- BEGIN KATA (managed by `kata init --with-agents`) -->
...
<!-- END KATA -->

but without those file-management markers.

Motivation

kata init --with-agents is a good opt-in for repositories that want to adopt Kata as a shared, committed agent-workflow convention.

I am interested in using Kata locally in a shared repository, without:

• Modifying or committing AGENTS.md, CLAUDE.md, or other repository instruction files.
• Implying that all collaborators should install or use Kata.
• Creating a second, locally maintained copy of Kata’s operating policy that can drift from the installed Kata version.

Several agent harnesses have user-local ways to load instructions at session start:

• Claude Code: a user-level SessionStart hook can inject a command’s stdout or structured additionalContext into the current session.
• Codex CLI: its SessionStart hooks can likewise add context.
• OpenCode: supports user-local global instructions and configurable instruction sources.

A stable command that emits the managed Kata briefing would let users integrate the same policy locally in each of these environments.

For example, a Claude Code user-level hook could run:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "kata quickstart --format contract"
          }
        ]
      }
    ]
  }
}

This would supply Kata’s policy to the agent at session start without changing anything in the repository.

In fact, a user-local integration can be installed globally but remain inert outside Kata workspaces. For example, a session-start hook can first detect the workspace binding:

test -f "$CLAUDE_PROJECT_DIR/.kata.toml" &&
    kata quickstart --format contract --workspace "$CLAUDE_PROJECT_DIR"

This injects Kata guidance only when the repository has explicitly opted into Kata via .kata.toml; unrelated repositories receive no additional context. It also means the harness integration itself does not need to be committed or configured per repository.

Why this should be distinct from existing formats

kata quickstart / kata agent-instructions already provides the fuller agent operating contract. The --with-agents block is a different, shorter briefing:

• It directs agents to the full kata quickstart contract.
• It provides the most important CLI workflow rules.
• It includes work.* attention/orchestration conventions.
• It is specifically designed as persistent agent guidance.

That makes contract a semantic output mode, and I think it could fit in with the existing --format options

Format	Intended output
human	Interactive terminal-oriented output
agent	Concise line-oriented command output for agent transcripts
json	Structured machine-readable command result
contract	Canonical managed agent briefing, suitable for injection into an agent session

This is just a suggestion, though; you may prefer another subcommand or flag.

Proposed behavior

kata quickstart --format contract
# alias
kata agent-instructions --format contract

This should:

• Write only the marker-free managed briefing body to stdout.

• Avoid terminal framing, progress messages, or workspace mutation.

• Work even when the current directory has not been initialized as a Kata workspace, since this is policy text rather than project state.

• Be documented as an automation-friendly API for agent harness integrations.

• Preserve the existing --project and --workspace selectors for contract output, so a harness can inject a contract tailored to an explicitly selected Kata project or workspace:

  kata quickstart --format contract --project my-project
  kata quickstart --format contract --workspace /path/to/project

  This leaves room for the contract renderer to include project-specific guidance where appropriate, while retaining a stable local-integration API.

Most importantly, kata init --with-agents and kata quickstart --format contract should use the same underlying template/renderer, so the static file-managed briefing and dynamically injected briefing cannot drift.