Skip to content

agents.md

Latest commit

 

History

History
267 lines (200 loc) · 8.44 KB

agents.md

File metadata and controls

267 lines (200 loc) · 8.44 KB
Raw
last_edited 2026-08-20

Agent workflows

kata is designed to survive the parts of agent work that chat does not: context compaction, multiple workers, incomplete attempts, and close discipline.

Session start

Run from the workspace, or pass --workspace:

kata quickstart
kata list --agent

Set actor identity once:

export KATA_AUTHOR=agent-a
kata whoami --agent

Default to --agent for ordinary reads and mutations in agent logs. Use --json only when the script needs full structured data.

Agent harnesses can load kata's shorter managed briefing dynamically without changing a repository:

kata quickstart --format contract
# Equivalent alias; selectors are available for user-local integrations.
kata agent-instructions --format contract --workspace /path/to/workspace

Contract output is marker-free, has no terminal framing, works without an initialized workspace, and performs no workspace mutation. It comes from the same canonical body that kata init --with-agents writes, so static and session-injected guidance stay aligned.

To make a workspace self-documenting for agents, run kata init --with-agents once. It writes a marker-delimited kata briefing into existing real AGENTS.md and CLAUDE.md files, or creates AGENTS.md when neither exists. The block points back at kata quickstart and carries short planning-date and work.* conventions (see agent orchestration); re-running refreshes only kata's block, so a repo initialized before that section shipped gains it on the next run. If a target file still carries a Beads integration block, kata leaves it untouched and writes a <file>.kata-proposed sidecar to adopt or discard — see --with-agents. If AGENTS.md is a symlink, kata refuses to manage it before reading the target; replace it with a regular file before using --with-agents.

The generated block gives agents exact commands for native planning state:

# A future schedule parks work until its gate opens.
kata schedule <ref> <date-or-time>
kata schedule <ref> -

# A deadline does not park work.
kata deadline <ref> <date-or-time>
kata deadline <ref> -

# Someday parks work with no date. Remove the key to return it to the queue.
kata meta set <ref> someday true --json-value
kata meta unset <ref> someday

Guidance files produce tendency, not contract: an agent can still end a session without updating its issue. For Claude Code workspaces, kata init --with-hooks additionally installs the attention harness hooks as two command-hook lifecycle entries: SessionStart runs kata attention-hook start for new, resumed, and cleared sessions (but not context compaction), and SessionEnd runs kata attention-hook end only for terminal exits rather than clear/resume transitions. Both use the launcher-provided KATA_REF and intentionally do nothing when it is absent.

For Codex CLI workspaces, kata init --with-codex-hooks installs two SessionStart hooks in .codex/hooks.json. One injects the canonical agent contract on startup, resume, clear, and context compaction. The other runs kata attention-hook start on startup, resume, and clear (but not compaction), using the same launcher-provided KATA_REF. Codex has no stable session-end hook event yet, so pair the attention hook with a launcher wrapper that runs kata attention-hook end after the Codex invocation exits — see agent orchestration for the recipe.

Use Kata through MCP

Agents with an MCP client can start Kata as a stdio server bound to the current workspace's project:

kata mcp serve

Clients that cannot launch a stdio subprocess can connect through Streamable HTTP. The listener requires an environment-sourced bearer token:

export KATA_MCP_HTTP_TOKEN='<random bearer token>'
kata mcp serve \
  --http 127.0.0.1:8080 \
  --http-token-env KATA_MCP_HTTP_TOKEN

The server starts with 13 section loaders. An agent loads only the detailed issue, project, administration, automation, or event tools needed for its task. Pass --workspace or --project for an explicit project, --projects for a fixed allowlist, or --all-projects to use every project visible to the selected daemon. The actor stays fixed at startup. See the MCP reference for transport configuration and exact schemas.

Search before creating

kata search "login race" --agent

If no existing issue fits, create with an idempotency key:

kata create "fix login race" \
  --body "Observed double-submit in Safari callback." \
  --idempotency-key "login-race-2026-05-31" \
  --agent

Prefer updating existing issues over opening duplicates:

kata show abc4 --agent
kata comment abc4 --body "Found another reproduction path." --agent
kata label add abc4 safari --agent
kata edit abc4 --blocks d4ex --agent

Claim work

In multi-agent environments, choose one unowned ready issue and claim it:

kata next --unowned --agent
kata claim abc4 --agent

next applies the shared priority rules and returns at most one candidate. The claim fails if another actor already claimed the issue; treat that as a coordination signal and run next again.

Use ready when you want to inspect a filtered queue instead of choosing one issue:

kata ready --unowned --label bug --no-label blocked --agent

Use the global list when waiting or blocked work must stay visible across projects. Unlike ready, list does not remove issues with active blockers:

kata list --all --status open --label handoff --no-label parked --agent

Release ownership only when you are intentionally giving the work back:

kata unassign abc4 --comment "Releasing; blocked on missing test fixture." --agent

Keep durable notes

Record decisions, partial attempts, and remaining work in comments:

kata comment abc4 --body "Verified the daemon rejects public IP listeners; docs still need hosted-mode wording." --agent

This is especially important before a long pause, context compaction, or handoff to another agent.

Use relationships deliberately

Create child work under a parent issue:

kata create "docs: rewrite CLI reference" --parent y04r --agent

Connect ordering with --blocks or --blocked-by, not comments:

kata edit cli-ref --blocked-by scaffold --agent

Use --related only for context.

Close only when verified

Do not close because work was attempted. Close only when the requested work is complete and freshly verified:

SHA=$(git rev-parse HEAD)
kata close abc4 --done \
  --message "Updated the CLI reference and verified docs-check passes." \
  --commit "$SHA" \
  --test "make docs-check" \
  --agent

Close each issue as soon as its work is verified, not in a batch at the end of a run. By default the daemon allows sibling close bursts when each close carries valid evidence and a substantive message. Operators can enable stricter burst/prose throttling when they want pacing in addition to evidence checks. Successful CLI closes also print a reminder that each close is a completion claim and that the message and evidence should be specific to the issue. Closing as you finish each issue leaves a better audit trail. See Close throttle.

If work is incomplete:

kata label add abc4 needs-review --agent
kata comment abc4 --body "Drafted remote-daemon docs; still need token identity verification." --agent

Poll events during long runs

For periodic polling:

kata events --after 0 --limit 100 --agent

Remember the returned cursor and resume from it. If the response says reset_required, discard cached kata state and resume from the reset cursor.

For live streams:

kata events --tail --agent

Use --json for consumers that require newline-delimited JSON.

Destructive commands

Agents should not run kata delete or kata purge unless the user explicitly asks for that exact operation and issue ref. delete is reversible; purge is not.

Recommended operating loop

  1. Read kata quickstart.
  2. Search for existing work.
  3. Claim or create one issue.
  4. Record the intended approach in a comment for large work.
  5. Implement and verify.
  6. Commit repository changes.
  7. Close the issue with evidence as soon as it is verified.
  8. Move to the next ready issue.