# AGENTS.md

Rules for any agent working in this repository. These override default agent
behaviour and are not negotiable.

## Core Philosophy: CRAFTESB

**Decision-quality bar.** Every non-trivial decision and implementation must
satisfy all eight dimensions of CRAFTESB. This is the PRD Plugin quality bar,
not an optional routing hint, and no dimension may be traded away for
convenience:

**CRAFTESB means Correct · Robust · Aligned · Faithful-to-method · Tested · Efficient · Secure · Bounded.**

**Correct** — the result is accurate, sound, and actually works.

**Robust** — it handles relevant edge cases and survives foreseeable change.

**Aligned** — it serves the user's real goal rather than a nearby problem.

**Faithful-to-method** — it follows PRD Plugin rules, durable decisions, and
repository conventions.

**Tested** — evidence proves the result; code changes start with a failing test
that demonstrates the missing behaviour.

**Efficient** — it is the smallest sufficient implementation that preserves the
full intended behaviour and quality bar.

**Secure** — secrets stay protected, trust boundaries fail closed, and the
change uses no more authority or exposure than necessary.

**Bounded** — solve the problem you were asked to solve, at the size you were
asked to solve it, without speculative options, abstractions, or adjacent work.
Bounded never permits under-delivery; gaps inside the ask are fixed now, while
adjacent problems are filed separately.

Apply CRAFTESB while scoping, implementing, reviewing, verifying, and reporting
work. `project-decision-policy` Stage 2 contains the extended decision procedure,
but the complete bar above is always in force.

## Evidence Follow-Through

When you identify a plausible, decision-relevant hypothesis with a bounded
discriminating check, state the check visibly and carry it through. A tool call alone
is not evidence, and tool output alone is not resolution. Do not pivot to
a causal claim, permanent mutation, replacement/disablement, or completion claim
until the expected and observed result is resolved, or explicitly defer it as:
`Deferred: <check>; reason: <why>; decision impact: <bound>; reopen when:
<condition>.` Label temporary safety actions as mitigation with root cause
unresolved. Never put private prompts, raw reasoning, or secrets in these markers.

When a check must become explicit machine-readable authority, emit one visible
`Evidence-Check: {JSON}` explicit directive. The JSON must contain exactly
`version`, `kind`, `claim`, `required_evidence`, `expected_result`, and
`blocking`; use version `1` and kind `evidence-check`. Set `blocking: true` only
when the check is explicitly intended to prevent guarded actions or completion.
Inferred prose remains low-confidence and report-only. Each required-evidence
entry names a tool and uses only the documented allowlisted acceptance
predicates. Never put secrets, private reasoning, or raw sensitive output in the
directive. See `node_modules/prd-plugin/docs/REASONING-GUARD.md` for the bounded
schema and examples.

## Message Checks

**Check messages means PRD Plugin inbox first.** When the user asks to "check
messages", asks whether there are "any messages", or asks about requests,
inboxes, mailboxes, replies, or outbox items, call `prd_check_messages` for the
current repository before using any chat, email, collaboration, or host message
tool. If the MCP tool is unavailable, run `python
.prd_plugin/scripts/message_check.py --repo-root . --config
.prd_plugin/config.json`. Do not report that there are no messages until this
current-repo check has completed and every reported category has been accounted
for.

## Repository Role

**This is a downstream repo that uses PRD Plugin.** The plugin is installed
as a devDependency (`prd-plugin` in `package.json`) and via
`opencode.json` plugin spec. Do not change the plugin itself from here.

Updates to PRD Plugin come from npm. To refresh or update:

```bash
npm update prd-plugin
npx prd-install . --codex --opencode --force
```

`--force` is the safe update route: it refreshes plugin-owned files while
preserving `.prd_plugin/state/`, `.prd_plugin/ids/`, and
`.prd_plugin/config.json`. **Never add `--yes` to a normal update.** That flag
requests a destructive reset to skeleton defaults; the installer refuses it in
non-interactive agent sessions and requires the exact interactive confirmation
phrase `RESET PRD STATE` when protected project data exists.

Do not edit files in the PRD Plugin hub repo (`github.com/markusuk1/prd-plugin`).
The hub repo is only changed by the plugin maintainer.

## Secrets Handling

NEVER read, display, echo, or log the contents of these files or any variable
named `*TOKEN*`, `*SECRET*`, `*KEY*`, `*PASSWORD*`, `*PASS*`, or `*CREDENTIAL*`:

- `.env`
- `.env.*`
- `*.pem`, `*.key`, `*.p12`
- Any file under `.prd_plugin/local/` that is not committed
- Any file the user explicitly marks as sensitive

If you must use a secret locally, do not load it manually. Use `dotenv-cli`:

```bash
npx dotenv-cli -- <command>
```

This loads `.env` into the child process environment without ever writing the
value to stdout. Never `cat`, `Get-Content`, `read`, `type`, or `Print-Output`
an `.env` file or any variable derived from it.

If a secret is ever displayed in chat, console, logs, screenshots, or a
model response, treat it as compromised. Tell the user to revoke it
immediately at the relevant provider (GitHub, npm, etc.).

## PRD Plugin Method

**Use the skills — don't work from memory.** This file and the session nudge are
instructions, not FYI. When a task matches one of the skills below, open that
skill and follow it rather than reconstructing the method from memory — after a
compaction or two your recollection drifts, but the `SKILL.md` is the source of
truth. Consult `project-decision-policy` at the start of every task to pick the
skill. (This is for tasks that match a skill; a trivial one-line answer needs no
ritual skill invocation.)

This repo uses the downstream runtime of PRD Plugin. The available skills
are in `.agents/skills/` (Codex) and `.opencode/skill/` (opencode). Use them
for:

- `project-brainstorm` for new ideas and feature concepts.
- `project-planning-lifecycle` to turn brainstorms into PRD, architecture,
  and implementation plans.
- `project-blocker-resolution` before declaring a blocker.
- `project-git-workflow` for branch, worktree, and merge discipline.
- `project-code-review` before completion claims.
- `project-test-driven-implementation` for code changes.
- `project-systematic-debugging` for bug investigation.
- `project-verification-before-completion` before claiming done.
- `project-llm-wiki` to query durable domain/codebase knowledge before
  re-deriving it, and to ingest new knowledge as work closes.
- `project-local-integration` for current-repo fold-in work.
- `project-prd-plugin-setup` for first-use onboarding only.
- `project-request-intake` for bugs, issues, and compatibility reports.
- `project-health` for operational health checks.
- `project-session-close` at end of session.
- `project-traceability-sync` and `project-traceability-review` for cross-artifact
  consistency.

Do not invoke `project-fold-it-in` in this repo - that workflow is for
the PRD Plugin hub only.

Use `project-decision-policy` to pick the right workflow and apply the
configured autonomy tier (`automation.autonomy_level`).

Use `project-deterministic-workflows` and the `prd_workflow_*` tools before
assigning bounded sequencing, bookkeeping, validation, state mutation, test
planning, or lifecycle mechanics to the LLM. LLM judgment must pass only
through a hash-bound source-backed request and deterministic resume.

**Test first.** For any code change, write the failing test **before** the
implementation and run it — the failing test first, confirmed to fail because
the behaviour is missing rather than because the test is malformed
(`project-test-driven-implementation`). Find and extend existing coverage rather
than adding a second test beside it. This is what the "Tested" in CRAFTESB
requires.

## Grounding And Estimation

These rules are always in force; see the shared method docs for detail.

- **Grounding (no hallucination):** never state something as true that you have
  not checked. Verify before claiming done, cite command output / file paths /
  real values rather than narrating, and never reference an ID, record, or file
  you have not confirmed exists. See `.prd_plugin/method/grounding.md` and
  `.prd_plugin/method/completion-gate.md`.
- **No timescales:** do not give time/duration estimates ("1-2 weeks",
  "3-5 months", "a few days"). Use **complexity** (trivial/small/medium/large/
  x-large) and **confidence** (low/medium/high) ratings instead, plus **risk**
  when relevant. Only use a schedule when the user explicitly asks for one. See
  `.prd_plugin/method/estimation.md`.

## Commit Discipline

Local commits on a work branch never need consent, in any tier — only pushing,
merging, and publishing are tier-governed (see below). You do not need permission
to commit your own work locally.

- Commit every verified increment. Uncommitted work has no history and no rollback.
- If the only branch is `main`/`master`, create a work branch first, then commit
  freely on it.
- Autonomous runs commit. "Do not ask the owner" plus "never commit to main" must
  never resolve to "never commit". Branch, commit, report.

## Resolve Before You Ask

Follow `.prd_plugin/method/self-service.md`. Before stopping to ask the user a
**factual** question, answer it yourself first with the tools you already have:

- **Capability discovery** — first inspect which host, plugin, MCP, UTCP,
  workflow, and Substrate tools are actually available and enabled. Prefer a
  purpose-built query/recall tool over reconstructing its answer from files.
- **Substrate memory** — when a connected Substrate exposes long-term memory,
  repository recall, records, graph, or event indexes, query those before raw
  repository search. Check the adapter handshake/config rather than assuming it
  is active; if unavailable or stale, continue down this list.
- **LLM wiki** — query `wiki/index.md` and the relevant articles through
  `project-llm-wiki` before re-deriving durable domain or codebase knowledge.
- **Canonical project truth** — use PRD MCP/UTCP tools to read decisions,
  memory, evidence, tracking, changelog, plans, and recorded preferences before
  reading their backing JSON directly.
- **Raw repository search** — use code search/read and git history only for
  exact implementation facts, verification, or gaps not answered by the
  structured knowledge sources above (`rg`, host read tools, `git log`/`blame`).
- **Local files** — config files for settings and READMEs for intent. Use the
  approved credential loader when needed; never read or echo `.env` values.
- **Web tools** — WebSearch/WebFetch for versions, APIs, and other external facts.

Only ask if all genuinely come up empty, and then **state what you checked** in
one line. This never lowers the consent floor, and a genuine preference/decision
only the user holds is still a legitimate ask.

## Reporting To The User

Follow `.prd_plugin/method/reporting.md`. The test of a good report: a non-expert
teammate understands what happened and what's next without decoding any ID.

- **Plain language first.** Lead with a short, plain-English summary of what you
  did and what happens next. **Never open with ID codes** (`REQ-*`, `TRK-*`,
  `ARCH-DEC-*`, `IMP-*`, `BR-Q-*`, …) — they are bookkeeping; put traceability/ID
  detail after the summary, not as the headline.
- **Human-readable UI.** In any interface you design, implement, review, or
  describe, use the available human-readable name, title, summary, or label as
  the primary UI text. System IDs are behind-the-scenes identifiers, not button
  labels, headings, navigation text, notifications, or the sole visible value
  in a table. Show an ID only when the user asks for it or it is needed for
  disambiguation, support, or audit; then keep it secondary and copyable beside
  the human-readable name. If no readable name exists, provide a useful fallback
  label rather than exposing a bare ID without explanation.
- **Don't ask permission to continue.** In `autonomous`, finish the planned work
  and report it — do not end a completed step with "shall I proceed?" / "which
  would you prefer?". Stop only for the consent floor or a check the configured
  tier actually requires; ask that inline, in plain words.
- **Never nag the user to stop.** Session length and context pressure are not
  reasons to stop. Never suggest wrapping up, handing off, closing the session, or
  starting fresh because it's been long — the harness compacts context for you.
  Keep working until the task is done or the user stops you. `project-session-close`
  is user-invoked, never agent-pushed.

## Parallel Work And Subagents

Do not use subagents unless the user **explicitly asks** for them **and** current
host/runtime permissions allow them. If either condition is absent, do not use
subagents. If both are present, read and follow
`.prd_plugin/method/subagents.md` before creating any worker.

## File Operations

- Do not delete files without explicit user permission, especially `.env` and
  any file containing secrets.
- Do not commit `.env` or files matching the secrets patterns above.
- If a secrets-pattern file is added to the working tree by accident, ask
  before removing it.

## PR and Repo Work

- Pushing to a remote and merging to `main`/`master` are governed by the autonomy
  tier. In `key_decision` / `guided`, get explicit user consent first. In
  `autonomous`, the tier is that consent — ship and report once the gate is green.
- Never force-push without explicit user consent, in any tier.
- Never edit another repo's files without explicit user consent, in any tier.
- **Never stop, restart, or rebind a live public service without explicit user
  consent, in any tier.** Check `services.json` first: a provided service with
  `runtime.public: true` or `restart_requires_consent: true` is consent-floor
  territory even in `autonomous`. Launch/relaunch declared services with the
  manifest's `runtime.bind_host` (e.g. `0.0.0.0`) — never a loopback default.

## Hub Release Publication

For the PRD Plugin hub, the remote v* tag push is the publication action:
.github/workflows/npm-publish.yml checks out the tag, runs the tests and package
check, and publishes to npm. Push main first, then push the annotated version
tag. Do not run npm publish locally and do not diagnose missing local npm
credentials as a release blocker.

If npm has not updated, inspect the GitHub Actions **Publish to npm** run for that
tag and rerun the workflow when needed. Registry lag alone is not evidence of a
credential problem. Completion requires both a successful workflow run and the
expected version visible from the npm registry.

## Host Agent Boundaries

- Codex reads `.agents/skills/`.
- opencode reads `.opencode/skill/`.
- Claude Code reads `CLAUDE.md`, enabled plugin skills, and repo-local
  `.claude/skills/` when present.
- Both Codex and opencode can also load skills via `opencode.json` plugin spec.
- If the user reports skills are being ignored, check `opencode.json` exists
  and points to the correct plugin version, and check that the
  `permission.skill.prd-plugin` entry is set to `allow`.