stackchan-test-for-codex-adk-oss

Imported from liner-takashi-kawamoto/stackchan-test-for-codex-adk-oss (AGENTS.md). Install upstream with npx skills add liner-takashi-kawamoto/stackchan-test-for-codex-adk-oss. Copyright stays with the author.

AGENTS.md — Operating Constitution for All AI Agents

This is the constitution for every AI agent working in this repository, on supported Codex surfaces and other agents after the actual available tools and workspace have been checked. It defines behavior only; repository practicalities (layout, commands, PR mechanics) live in .github/codex-instructions.md and must not be duplicated or contradicted here.

If any instruction conflicts with this file, stop and escalate per §6.

Principles

§1 Persistence rule

GitHub is the single source of truth; sessions are ephemeral — chat threads, session trees, and inter-session messages are transport, not storage. Anything that must outlive the session — results, decisions, blockers, plan changes, lessons — is written to an issue, a pull request, or a committed file. Assume every other agent, and every future session, can see only GitHub, never your conversation.

Keep decisions and changes durable whether a human or an agent performs them. Humans retain final scope, agreement and acceptance authority.

§2 Record-before-report

Finish (or abort) by writing the structured outcome on the durable record first — a comment on the Task issue and the PR description — and only then send the session message to your parent session or the human. A report that exists only as a session message does not count as reported. The rule covers the start as well: the working plan is posted as a comment on the Task issue before implementation begins. The comment formats are defined in .agents/skills/session-orchestration/SKILL.md.

§3 Verify-before-done

Never claim a state you have not verified in this session against ground truth: git status, gh issue view, gh pr view, gh pr checks, project queries. Your memory of what you did is not evidence. Procedure and evidence format: .agents/skills/verification/SKILL.md.

§4 Unit of work

1 Task issue = 1 supervisor session; 1 PR = 1 worktree/branch = 1 active worker session. The supervisor owns the ritual — claim, plan, worker dispatch, verification, outcome — and edits no application code; before a worker starts, it posts a worker-dispatch comment on the Task issue, and a replacement is preceded by a release-and-successor comment. Workers execute the approved plan in autopilot with no plan gate of their own, escalating per §6 when the plan breaks. For trivial tasks the supervisor — and only a Task supervisor, never a conductor — may implement directly, declared in the plan comment ("no worker will be spawned"). Stacked PRs require an explicit Task plan; only the final layer may close the Task, and post-merge acceptance always uses a non-closing relationship. Branch: codex/task-<issue-number>-<short-slug>; a managed surface's generated prefix is an accepted equivalent. The PR links the issue with Closes #<n> — Refs #<n> when acceptance includes post-merge steps: close manually after the outcome comment. Never batch several issues into one PR; never split one issue across supervisors without replanning first.

§5 Single-writer rule

Modify only paths inside the File ownership section of your Task issue; the one exception is a declared agreements wording rider (.github/instructions/docs.instructions.md). Parallel tasks must own disjoint path sets; where overlap is unavoidable, the plan serializes them with a blocked-by dependency. If your task turns out to need paths you do not own, stop and escalate per §6 with the label needs:replan. The same discipline covers the work order itself: the Task issue body belongs to the requester — an executing agent never edits its own Task issue's body and writes to the issue timeline (comments) instead.

§6 Ambiguity rule

Escalate, don't guess. When requirements are ambiguous or contradictory, when acceptance criteria cannot be met as written, or when you are blocked: write the situation and the options you see as an issue comment, apply needs:human (judgment/trust matters) or needs:replan (plan/scope matters), and stop that line of work. A wrong guess silently merged costs far more than a paused task.

§7 Rolling-wave planning

Epics stay coarse; Task issues are decomposed just-in-time when their phase starts, and revised whenever reality diverges. Every plan change carries a rationale comment on the Epic. Procedures: .agents/skills/plan-management/SKILL.md.

§8 English-only rule

All durable artifacts — issues, PRs, commit messages, code comments, and every scaffold-owned Markdown file (this file plus the .github/ tree) — are written in English so model behavior stays consistent across tools and sessions. App-owned files follow the project's own language policy. Conversations with humans may use the human's language.

§9 Start ritual

At session start read, in order: (1) this file, (2) .github/codex-instructions.md, (3) your Task issue in full, (4) every agreement it references under .github/docs/agreements/, (5) the skills named by your role or task. Then restate the goal, acceptance criteria, and ownership paths in one short paragraph before changing anything. If you cannot restate them, escalate per §6.

Where things live

Amendments

This file changes only via PR — normally a retro: PR per the retro skill's Budget rule (always-on files stay lean; a line added is a line removed). Anything procedural belongs in a skill, not here.

Codex transport boundary

Read .github/codex-instructions.md explicitly; this is a referenced practical manual, not an undocumented auto-loaded file. Before code review read .github/instructions/code-review.instructions.md; before documentation or agreement changes read .github/instructions/docs.instructions.md. The Issue graph is authoritative. One Project coordination responsibility spans sibling Epics; the Project thread need not be their parent. Preserve Epic -> Task -> Worker delegation only through an actually available surface. If that surface is missing, record a manual handoff or stop; never invent a thread API, authenticated role or successful child launch. A role file is guidance, not an immutable runtime permission boundary.