AGENTS.md

You're a fresh agent in kibsu-lab -- a public, cloneable virtual workspace for one fictional distribution company, Tuppi Trading Co. This file is thin on purpose: it points, it doesn't restate. Read in this order.

0. On arrival

Run python -m kibsu discover . -- it checks what this repo actually has wired (CI, git hooks, agent hooks, tests, and whether the gates these docs mandate are invoked by any real automation) against what these docs merely claim. Do this before anything else below; a declared-but-dead gate reads as coverage from the outside, and this is the fastest way to find out whether that's true right now.

1. How to think here

skills/thinking-partner/SKILL.md -- judgment, not procedure. Read it before you act on anything ambiguous. skills/strategist/SKILL.md -- how to choose between approaches: name the real hurdle first, then recommend rather than list. Neither names a command to run; both score near zero on checkability by design.

2. What is true right now

docs/STATE.md -- one row per track (DATA / REPORTING / RECONCILIATION / TASKS), each with a Next action. This is the current state; it is not history.

3. What has already happened

docs/CHANGELOG.md -- newest entry first. docs/memory/learnings/ -- reusable lessons from past fixes; read before you re-derive something that's already known.

4. What you can be asked to do

tasks/ -- three machine-checkable tasks (T1_add_kpi.md, T2_fix_reconciliation.md, T3_resume_the_work.md). Each names its own verifier under tools/check_task.py. Run the verifier before and after your change -- it will exit non-zero on a pristine repo by design; that is the starting state, not a broken checker.

5. How work gets logged and gated

skills/change-log/SKILL.md (what to write, where, when you finish something) and skills/gate/SKILL.md (what needs a green check before you commit). For anything spanning 3+ steps, skills/planner/SKILL.md. Adding, moving, or renaming a file: skills/architect/SKILL.md -- what every file must declare, where it belongs, and the commands that prove it.

6. The data

data/ does not exist until you generate it -- it is gitignored on purpose; the shipped artifact is the generator, never its output:

python tools/generate_data.py

Every tool in this repo (tools/reconcile.py, tools/sales_report.py, tools/check_task.py) generates data/ itself with the default seed if it's missing, so you never have to run this by hand first -- but running it explicitly is fine too.

7. Tooling config

.kibsu.json -- docs root, skills dir, and the commit gate wired to tools/reconcile.py. This repo depends on the kibsu package (PyPI) to read its own governance; see README.md for the version pin.

README.md publishes what kibsu prints here, and python tools/check_baseline.py proves it still does (exit 0 = the page is right, 1 = it is not, 2 = could not run). Adding a document or editing a skill moves those numbers. git add your files first -- the tool counts only what git knows -- then run it, and re-capture the block if it fails.

Provenance

PROVENANCE.md -- every name, company, and row of data here is fictional and generated, never committed, never sourced from anything real.