v0.14.0

Imported from projectious-work/aibox (context/templates/processkit/v0.14.0/AGENTS.md). Install upstream with npx skills add projectious-work/aibox --skill v0.14.0. Copyright stays with the author.

AGENTS.md

processkit Compliance Contract

Call route_task(task_description) before any create_*, transition_*, link_*, record_*, or open_* tool call.

If there is even a 1% chance a processkit skill applies to the current task, consult skill-finder (or call find_skill) before acting.

When you decide to create a WorkItem, DecisionRecord, Note, or Artifact, call the tool in the same turn — deferred entity creation is lost.

Write entities through MCP tools, not by hand-editing files under context/ — hand edits bypass schema validation, state-machine enforcement, and the event-log auto-entry.

Read entities through index-management (query_entities, get_entity, search_entities) — do not use ls, grep, or raw filesystem walks under context/.

Log an event after any state change that an MCP write did not already produce automatically.

After a cross-cutting recommendation is accepted, call record_decision in the same turn.

Do not edit any file under context/templates/ — it is a read-only upstream mirror used as a diff baseline.

Do not hand-edit the generated harness MCP config — edit the per-skill mcp-config.json and let the installer re-merge.

This file is the canonical, provider-neutral entry point for any AI coding agent (or human collaborator) working on {{PROJECT_NAME}}. It follows the agents.md open standard.

If your harness auto-loads a provider-specific file (CLAUDE.md, CODEX.md, .cursor/rules, …), that file should be a thin pointer to this one. Edit this file, not the pointers.

⚠ First-time setup (delete this section once done)

This file ships from processkit as a generic template. Some placeholders are filled in by the project's installer at render time; the rest require human input or codebase analysis.

This is your first task on any new project. Treat it as the implicit first backlog entry — until the file is fully customized, no other work can confidently proceed.

Markup conventions

This template uses two markup conventions you need to recognize:

• {{TOKEN}} — a placeholder. Replace it with the real value during the fill protocol below.
• <!-- PLACEHOLDER:TOKEN class=X ... --> — an HTML comment immediately above a placeholder, declaring its class and how to fill it. Delete the comment along with the token once the value has been written in.

Placeholder classes

Scan this file for any remaining {{TOKEN}} strings. For each, look at the comment immediately above it (when present) for the class label, then follow the matching protocol:

Placeholders without a <!-- PLACEHOLDER:... --> annotation default to Class B — owner-supplied.

Steps

1. Walk every {{TOKEN}} in this file in document order.
2. For each, follow the protocol above. Replace the token (and its <!-- PLACEHOLDER:... --> annotation, if any) with the value.
3. Once the file is fully populated, delete this entire ## ⚠ First-time setup section so future agents do not re-read instructions that no longer apply.
4. Then — and only then — proceed with whatever the user actually asked you to do.

Do not skip this step in the name of being helpful. An AGENTS.md full of placeholders is worse than no AGENTS.md at all: it tells every future agent that the project's contract has not been established, and they will have no shared ground to work from.

About this project

{{PROJECT_DESCRIPTION}}

Why it exists. {{PROJECT_PURPOSE}}

Setup

# install dependencies and build
{{BUILD_COMMAND}}

# run tests
{{TEST_COMMAND}}

# run linter / formatter check
{{LINT_COMMAND}}

Code style and conventions

{{CODE_STYLE_NOTES}}

Pull requests

{{PR_CONVENTIONS}}

processkit preferences

Runtime configuration lives in per-skill config files under context/skills/<name>/config/settings.toml. The agent edits these directly; MCP servers read them on every call — no restart needed.

{{PROCESSKIT_PREFS}}

How this project is organized: processkit content

This project uses processkit, pinned at {{PROCESSKIT_VERSION}}, package tier(s) {{CONTEXT_PACKAGES}}, to manage process content (skills, primitives, processes, schemas). All processkit-installed material lives under context/:

context/
├── skills/         ← skill packages (SKILL.md, mcp/, references/, templates/)
├── schemas/        ← JSON schemas for the core primitives
├── state-machines/ ← state-machine definitions
├── processes/      ← process definitions (bug-fix, code-review, release, …)
└── templates/      ← immutable upstream mirror used as a diff baseline

context/templates/processkit/<version>/ is the verbatim upstream snapshot. Do not edit it. Edit the live files at context/skills/<name>/SKILL.md, context/processes/<name>.md, etc., directly. Local edits are detected at the next sync via three-way diff against the templates mirror.

Every context/ subdirectory has an INDEX.md. Read those first — do not slurp context/skills/ or any large directory at session start. Load specific files only when the task demands it. This is the three-level principle: start at Level 1 (intro), drop to Level 2 (workflows) when the task narrows, drop to Level 3 (full reference) for edge cases.

Working with entities

processkit models project state as entities — work items, decision records, discussions, log entries, scopes, gates, bindings, and so on. Each entity is a YAML file under context/<kind>s/, created lazily on first use.

For each entity kind, processkit ships:

• A schema at context/schemas/<kind>.yaml
• A state machine at context/state-machines/<kind>.yaml
• An MCP server at context/skills/<kind>-management/mcp/server.py

Read entities through the index

context/skills/index-management/ exposes a SQLite-backed index over every entity in context/. Call its tools — query_entities(kind=…, state=…), get_entity(id), search_entities(text) — instead of ls / grep / filesystem walks. The index is faster, context-cheaper, and reflects the canonical state.

Write entities through the per-kind MCP servers

Use the relevant MCP tool to create or transition entities — create_workitem and transition_workitem from workitem-management, record_decision from decision-record, and so on. Hand-editing entity files works but bypasses index updates and state-machine validation, so the index can drift and invalid transitions can slip through. Reserve hand edits for cases the MCP tools genuinely don't cover.

Wiring the MCP servers into your harness

Each MCP-bearing skill ships its own mcp/mcp-config.json declaring how to launch the server (typically uv run …/server.py). Agent harnesses (Claude Code, Codex CLI, Cursor, …) discover MCP servers by reading a single config file at startup, so the per-skill configs need to be merged into the one file your harness reads, and that file needs to live at the path your harness expects.

If this project was set up by an installer (e.g. an aibox-managed devcontainer), the installer is responsible for that wiring — the merged config is generated for you and you should not need to touch it. If processkit was installed manually, the project owner is responsible for merging the per-skill blocks and placing the result at the harness-specific path themselves.

Either way, MCP-bearing skills require uv and Python ≥ 3.10 on PATH inside the environment where the harness runs the servers — each server.py is a self-contained PEP 723 script and uv run resolves its dependencies on first launch.

AI agents on this project

Configured providers: {{AI_PROVIDERS}}. Other agents may be working on this project — coordinate through the entity layer (workitem-management, event-log, discussion-management) rather than assuming you are alone.

Commit to actions immediately. If you decide to create an entity (WorkItem, DecisionRecord, etc.), call the tool in the same turn. Do not say "I'll track that" and move on — deferred commitments are routinely dropped and leave the entity layer out of sync with what was discussed.

Check the skill catalog before acting on domain tasks. When a domain-specific task arrives — writing a PRD, creating a release, reviewing a skill, designing a schema — search the processkit skill catalog first. Use search_entities via index-management or check skill-finder before falling back to general knowledge. A matching skill may exist with processkit-specific conventions (entity storage paths, workitem linking, output formats) that general knowledge does not know. Missing a skill wastes work and produces non-standard output.

Contributing improvements upstream

When you make a behavioral or content improvement to a file in context/ that was installed from processkit (it has a counterpart in context/templates/processkit/<version>/), ask whether the improvement is general enough to benefit all processkit consumers.

If yes:

1. Open a Discussion entity locally with open_discussion — title it "Upstream proposal: ", note the changed file and the improvement in the body. This creates an audit trail so future sessions can see what was proposed and what was decided.
2. File an issue at the processkit repository so maintainers can consider it for the upstream catalog.

Nothing is mandatory — the project owner decides what to file upstream. The Discussion entity records the decision either way.

Project-specific notes

{{NONOBVIOUS_GOTCHAS}}

Scaffolded by processkit {{PROCESSKIT_VERSION}} on {{INSTALL_DATE}}. Re-rendered on each installer sync.