Skip to content

AGENTS.md

Latest commit

 

History

History
184 lines (118 loc) · 12.3 KB

AGENTS.md

File metadata and controls

184 lines (118 loc) · 12.3 KB

Agentboard — Codex CLI Entry

Bash CLI for shared work-state across Claude Code, Codex CLI, and Gemini CLI

Status: This project was scaffolded by agentboard init on 2026-04-17. If not yet activated, say "activate this project" and the agent will read .platform/ACTIVATE.md.

You are an AI agent reading this file (Codex CLI / OpenAI Agents)

This file is auto-loaded when you open this project in Codex CLI. All mandatory protocols below apply to you exactly as they apply to Claude Code and Gemini CLI.

Active Work (.platform/work/)

Session start (every session — mandatory)

  1. Run agentboard brief first — compact "state of the project" view: active streams, recent gotchas (landmines the 20-year-employee would warn you about), open questions, latest usage pattern. This is your institutional memory; read it before touching code.
  2. Then read the narrative docs in order:
    • work/BRIEF.md — what we're building, why, current state, relevant context
    • work/ACTIVE.md — stream registry

If there is an active stream you're resuming, run agentboard handoff <slug> before anything else — it prints the exact load order and the Resume state (what just happened, current focus, next action) left by the previous agent. This is how context is shared between Claude, Codex, and Gemini without re-explaining.

Report to user: 1 stream → "Resuming <stream> — next: <action>. Continue?" / 2+ streams → ask which / 0 → ask what to work on.

Product mindset rule (mandatory)

PMs, engineers, and all agent roles should think like best-in-class Silicon Valley product teams: user-obsessed, future-facing, innovative, craft-driven, fast, and rigorous. Raise the bar beyond basic task completion by asking what would make the work differentiated, durable, scalable, delightful, and credible against leading technology products.

This mindset is not permission for vague hype or scope creep. Ambition must be translated into the smallest coherent slice, explicit tradeoffs, strong execution quality, tests, rollback thinking, and human approval for any scope change.

Context handoff — before ending or switching providers (mandatory)

When context is running low, you're ending the session, or you're about to hand off to another CLI (Claude → Codex, Codex → Gemini, etc.), run:

agentboard checkpoint <stream-slug> --what "<1-2 lines of what just happened>" --next "<one sentence: what to do next>" \
  --cumulative-in <N> --cumulative-out <N> --provider codex --model <model-id> [--complexity trivial|normal|heavy]

For --cumulative-in / --cumulative-out pass your current session totals (running counters, not per-segment deltas). Agentboard subtracts what was already logged for this stream+provider+day so mid-session logging never double-counts. Omit the token fields if you don't know the counts; the checkpoint itself still works.

This overwrites the stream file's ## Resume state block with compact "where we are" state and trims the progress log to the last 10 entries. The next agent runs agentboard handoff <slug> and picks up from there — no re-explaining the feature. Without this, the next agent has only stale state.

Reasoning annotation — after significant edits (mandatory)

After every non-trivial Write or Edit, log WHY so the next agent understands:

agentboard log-reason [<file>] "<one sentence why>"

Skip for: formatting, typo fixes, obvious renames. Required for: refactors, deletions, new abstractions, architectural choices.

Stream closure — before archiving (mandatory harvest ritual)

When a stream is done, do not just archive the file. Run the two-step close to feed project memory:

# Step 1 — print the harvest checklist
agentboard close <stream-slug>

Then, following the checklist it prints, distill and append to these files (only where applicable — skip categories with nothing to add):

  • .platform/memory/gotchas.md — landmines discovered (🔴 never-forget · 🟡 usually-matters · 🟢 minor)
  • .platform/memory/playbook.md — shortcuts / rituals / commands worth recording
  • .platform/memory/open-questions.md — anything still unresolved (or move a prior question to Resolved)
  • .platform/memory/decisions.md — locked architectural/product/tooling decisions
  • .platform/memory/learnings.md — non-obvious bug root-causes
# Step 2 — after harvest, archive the stream
agentboard close <stream-slug> --confirm

This is the compounding ritual. Each close adds durable knowledge so the next agent running agentboard brief inherits what you learned, without you being there to explain it.

Long session fallback — agentboard watch (recommended for Codex/Gemini sessions)

For sessions where checkpoints may be forgotten, start a background watcher:

agentboard watch &

It polls git status every 10 min and auto-checkpoints the active stream whenever ≥1 tracked file has changed since the last poll. The auto-content is mechanical (file list + carried-over Next action) — always prefer your own explicit checkpoints with specific --what / --next. The watcher skips ticks when it sees a manual checkpoint happened in the last 5 minutes, so it never clobbers fresh state. Stop with agentboard watch --stop.

Codex / Gemini: start agentboard watch & at the beginning of every session — it's the closest equivalent to Claude Code's auto-checkpoint hooks.

New task bootstrap (before any non-trivial task — mandatory)

When the user gives a task not already tracked in ACTIVE.md, stop and complete these steps before any research, planning, or code:

  1. Check ACTIVE.md — does this stream already exist? If yes, load it and continue.
  2. Check .platform/domains/ — does a domain file exist for this feature area?
    • No → create .platform/domains/<name>.md with cross-layer touch-point inventory first.
  3. Create work/<stream-slug>.md — what we're building, why, done criteria, key files, current state.
  4. Add a row to work/ACTIVE.md — slug / type / in-progress / agent / date.
  5. Update work/BRIEF.md — point to new primary stream + list domain file under "Relevant context".
  6. Only then proceed to triage → research → propose → execute.

Research-first new stream rule. If the request is a new stream, research is always required before planning or implementation. Scale the depth to risk, but include local context and targeted external research every time. Present the research-backed phased plan, risks, mitigations, alternatives, tests, rollback path, and open questions; wait for human validation/approval before implementation. If implementation diverges from the approved plan, pause and ask.

Worktree branch rule. Before implementation starts on any feature, bugfix, or hotfix stream, create or enter a separate Git worktree for every touched repo. Use feature/<slug> or bugfix/<slug> from develop; use hotfix/<slug> from master only when the user explicitly says hotfix. Install each repo's development dependencies in its worktree, identify the local dev command and localhost port(s), and record them in the stream file before coding or QA.

Manual QA artifact rule. Before any commit, push, merge, release, or stream closure for implementation, bug fix, debugging, feature, UI, API behavior, or release work that requires human/app-driving verification, create a durable QA markdown document at .platform/work/qa/<stream-slug>-manual-qa.md. Cover scope, environment, test data, safety limits, exact click/type/navigation steps, expected results, happy path, bug repro/regression steps, edge cases, browser/device checks when relevant, accessibility checks when relevant, evidence to capture, Maestro/automation notes when relevant, and pass/fail signoff. If manual QA is not relevant, record Manual QA: not required — <specific reason> in the stream file and explain why. Do not delete QA docs; archive them with the stream under .platform/work/archive/qa/.

QA execution journal rule. When an LLM/agent uses Maestro, Browser, Playwright, MCP, a simulator/emulator, or another interactive tool to drive the app, also create .platform/work/qa/<stream-slug>-execution-journal.md. Document every meaningful step from the agent perspective: tool used, action, observation, expected result, actual result, pass/fail/skipped status, evidence, bugs found, diagnosis, fix or human escalation, retest, successful paths, blockers, and remaining risk. Do not replace this with a final summary; the journal is the chronological trace.

Non-negotiable. Skipping this means context is lost when the session ends. Trivial single-file fixes are the only exception.

Reference pack

Loading rule: only load files listed in work/BRIEF.md § "Relevant context". Do not auto-load the full pack. Never read work/archive/* unless explicitly asked. Never load BACKLOG.md or learnings.md at session start — read them only when the user asks, or when appending.

  • .platform/workflow.md — the 6-stage inline workflow ← read this before running any multi-step protocol
  • .platform/ONBOARDING.md — 7-step onboarding path for future sessions
  • .platform/memory/learnings.md — bug post-mortems + hard-won patterns (L-NNN); grep here first before diagnosing non-obvious bugs

Mandatory Protocol — Stream Audit / Analysis

Whenever the user asks to audit, analyze, or check the state of a stream or its implementation (e.g. "audit the stream", "analyze what we've done on X", "check the state of <feature>", or references a work/*.md file explicitly), you MUST:

  1. Read .platform/workflow.md first — before touching any agent results or synthesizing anything.
  2. Follow the Stream / Feature Analysis Protocol exactly as written there — no shortcuts, no partial synthesis before all agents finish, no skipping the standardized template or the stream-file anchor step.

This applies even when resuming after context compaction. A compressed context summary is NOT a substitute for reading the protocol spec.

Commit Gate — Never commit without explicit user request

Never run git commit or git push unless the user explicitly asked for it in this conversation turn.

"Tests pass" is not a request to commit. "Looks good" is not a request to commit. "Done" is not a request to commit.

If you have completed work and believe it is ready: say what you did and ask "Ready to commit?" — then wait. The user decides.

Enforcement:

  • Claude Code — bash-guard.sh PreToolUse hook blocks the commit and shows an approval dialog. If you see the dialog and the user did not ask for a commit, deny it.
  • Codex / Gemini — no hook; this instruction is your only guard. Violating it is a hard failure.

Stream Closure — Human Approval Required

Only the human/owner declares a stream complete. You never self-declare completion. You may say "I believe this is done — here is the evidence" and propose closure, but the final decision belongs to the developer. No exceptions.

Before running Steps 7–9 of the Stream Closure Protocol (archiving the stream file, removing from ACTIVE.md, appending to log.md), you MUST:

  1. Present evidence of completion to the user.
  2. Wait for explicit human sign-off.
  3. Verify the stream file has closure_approved: true before archiving.

Enforcement: Three layers, all providers:

  • Git pre-commit hook — blocks any commit that removes a stream row from ACTIVE.md without closure_approved: true. Fires regardless of which AI tool made the edit.
  • Claude Code only — platform-closure-gate.js blocks the edit itself (PreToolUse), before the file is even written.
  • Codex / Gemini — no PreToolUse hooks; rely on this instruction. The git hook is the mechanical backstop.

Full protocol: .platform/workflow.md → "Stream Closure Protocol".

Skills available to you

Installed into .agents/skills/ by agentboard init.

ab-triage, ab-workflow, ab-research, ab-pm, ab-architect, ab-test-writer, ab-security, ab-qa, ab-qa-self-heal, ab-review, ab-debug, ab-cleanup, ab-graphify

Read each skill's SKILL.md on first use to understand its protocol.

Generated by agentboard on 2026-04-17. After activation, this file will be updated with project-specific content by sync-context.sh.