stack-kb

Imported from fritzhand/stack-kb (AGENTS.md). Install upstream with npx skills add fritzhand/stack-kb. Copyright stays with the author.

AGENTS.md — instructions for an AI working inside a function stack

You are working inside a function's knowledge base. Read this file before touching anything else.

(If your tool looks for CLAUDE.md, .cursorrules, GEMINI.md or similar, that file points here. This is the single source. The full front-matter schema, tag table and naming rules live in docs/conventions.md — this file is the working rules, that one is the reference.)

What this repo is

A function stack: the working knowledge base for one function of one organization — a Finance office, an HR team, a Registrar, a lab, or a whole small org treated as one function. Ten numbered sections in stack/ (01-mandate through 10-pulse), one markdown file each, every file carrying front matter that says what it is and whether it has been verified. stack/PROFILE.md is the configuration — it says what each section means for this function. stack/INDEX.md is the router. stack/CONTEXT.md is the one-page summary.

The stack may stand alone, or sit under an umbrella — an organization rolling many function stacks into one picture. The umbrella has extra rules; they are at the end of this file.

The function owner is the named human in stack/PROFILE.md (and in each file's owner: field). They are not a developer. Write for someone who has never seen this function before and has to get up to speed in twenty minutes.

Read in this order — always

1. stack/PROFILE.md — the configuration. What this function is, what each section means here, the cadence, the vocabulary, the always-on metric. Without it you are working on a generic office that does not exist.
2. stack/INDEX.md — the router. One line per file. Decide from here which sections you actually need.
3. stack/CONTEXT.md — the one-pager. Almost every task needs it.
4. Only the sections the task requires. Each file's front matter lists reads: and feeds: — follow those edges rather than opening everything.

Do not read the whole stack/ on every request. The index exists so you don't have to, and reading everything is exactly the cost this system is designed to avoid. If the index does not tell you enough to route, say so and improve the index.

The rules — non-negotiable

1. Never invent a number

Every figure, date, name, budget line, headcount, deadline and utilization rate must trace to a source: a file in _inbox/, an existing entry in stack/, or something the function owner told you in this conversation.

If you do not have a source, write [TBD — <what specifically is needed and from where>]. Do not estimate. Do not say "approximately." Do not fill a table cell with a plausible-looking number because the table looks bad empty.

An empty cell is information. A fabricated cell is damage that will surface in an audit, a committee meeting, or a leadership review.

2. Tag every claim

Every fact carries one of these, either in front matter (whole file) or inline (individual claim):

You may never promote something to [SOURCE OF TRUTH]. You may only propose it: "You confirmed X in this session — shall I mark it source-of-truth?"

One more tag exists in the umbrella layer, because all four above assume a checkable claim. "The office's budget is 4.2 million" can be verified. "That team resists change" cannot — it has no source to check, no action that resolves it, and two people disagreeing about it is a difference of judgement rather than a discrepancy.

Two assessments that disagree both stand, side by side, with their names on them. That is not a [CONFLICT] to resolve — it is two people who have looked at the same function and read it differently, which is information.

3. Cite where things came from

When you write a fact into the stack, note its origin: (src: _inbox/budget-fy26.xlsx), (src: minutes 2026-05-12), (src: owner, 2026-08-12). Web material carries its URL and fetch date: (src: https://example.edu/registrar, fetched 2026-08-12). This is what makes the base auditable later, when the number is being questioned in a room you are not in.

An organization's own website is its public claim about itself — it is [NEEDS VERIFICATION] and never [SOURCE OF TRUTH]. When it contradicts something already in the stack, that is a [CONFLICT] to surface, not a discrepancy to quietly resolve — an org's own site is out of date more often than not.

4. Update front matter when you edit a file

Change updated: to today. Re-check whether status: and confidence: still hold. Rewrite summary: if the file's substance changed — the index is built from those summary lines and a stale summary breaks routing for every future request. Update the file's row in stack/INDEX.md in the same pass.

5. Respect sensitivity

Every file declares sensitivity: public | internal | restricted.

• public — safe in a published report, a website, a presentation
• internal — the function and its leadership only: budgets, vendor terms, capacity problems, stakeholder complaints
• restricted — never leaves the function's own machine: personal data about named people, salaries, audit findings under privilege, anything under a confidentiality obligation

When asked to produce something shareable — a briefing, a one-pager, a report, a rollup — carve it. Pull from public freely, from internal only with an explicit instruction, and never from restricted. State in your output what you excluded and why.

In the umbrella layer only, two further fields appear, because sensitivity measures one thing — how far from the owner a file may travel — and an umbrella needs to answer a second question it cannot: whether the people a file is about are among the people who may read it.

An umbrella team's read of a function is audience: umbrella-team. It never travels to that function's copy, and never into anything the function receives. If you are producing something for a function and a file says umbrella-team, it is not yours to include — say you excluded it, without quoting it.

One rule governs everything written about a person: write it as though they will read it. That is the posture the law takes in most places, and it is also the only way the note stays honest enough to be worth keeping. A function working on its own stack will never need either field.

6. Never delete without asking

You may add, restructure, and rewrite files. You may not delete a file, empty a section, or drop a historical recap without asking first and getting a clear yes. Recaps in stack/10-pulse/recaps/ are an append-only record — they are not tidied, corrected or consolidated, ever. The spine is never renumbered or renamed; a section with nothing in it stays at status: tbd with one line saying why.

7. Write in the owner's voice, not a consultant's

Factual, concrete, short sentences. No marketing language. No "leverage," "synergy," "unlock," "transformative," "world-class." No emoji anywhere. The ballot and check glyphs used as structural markers in these templates (☐ ✓ ✗) are not emoji and stay.

If the function has its own vocabulary — a name it calls a service, a term it deliberately avoids — stack/PROFILE.md and stack/CONTEXT.md record it. Use the function's words, not better ones.

8. Numbers stay consistent across the stack

Before writing a headline figure anywhere, check whether it already appears elsewhere in stack/. If your new number disagrees with the old one, that is a [CONFLICT] to surface, not a discrepancy to quietly resolve. Inconsistent headline numbers across a budget, a report and a briefing is the single most common way an otherwise sound function loses credibility with its oversight.

The umbrella rules — sovereignty is absolute

These apply whenever an umbrella layer exists, in both modes — shared-repo (functions inside one repository the umbrella team can physically read) and federated (each function a sovereign repo, rollups travelling through an exchange folder). The mode changes physical access. It never changes these rules:

• The umbrella never edits a function's stack. Not a typo, not a stale date, nothing. It asks the function.
• The umbrella never promotes a function's facts. Only that function's owner promotes to [SOURCE OF TRUTH].
• The umbrella never re-scores outside the quarterly pass, and it scores from the record, not the conversation.
• restricted never enters any umbrella artifact — not a rollup, not a brief, not a theme, not a signal. No exceptions, no summaries of it, no "anonymized" versions of it.
• A rollup inherits the strictest sensitivity of its inputs. One internal source makes the whole rollup internal.
• [ASSESSMENT]s are never aggregated. Each stays attributed to its author and date.
• Anything written about a person is written as though they will read it.

Full detail: docs/umbrella.md.

Working with prompts

prompts/ holds the task library. When the owner invokes one, follow it exactly — the prompts encode the sequence the method depends on, and skipping steps produces confident output built on nothing. Prompt 00 prepares a stack with zero documents; prompt 01 requires a prepared stack and a non-empty inbox; each prompt's Requires: line says what it needs.

If a prompt asks for input the stack does not have, stop and ask. Do not proceed with an assumption and mention it in a footnote. The owner can answer in ten seconds; a wrong assumption propagates through every downstream document.

Writing new files

Use the front-matter schema in docs/conventions.md. Every new file needs:

• the full front-matter block, including a one-sentence summary: written for routing
• a row added to stack/INDEX.md
• correct reads: / feeds: edges to its neighbours — intra-stack only; cross-function dependencies are register rows in stack/08-interfaces/interfaces.md, never front-matter edges

The failure mode to avoid

The most damaging thing you can do here is produce a complete, polished, well-formatted stack in which a third of the content is invented. It will read as finished. The owner will trust it. They will put its numbers into a report, quote them to their leadership or an auditor, and be caught out by someone who did the arithmetic.

An obviously incomplete stack full of honest [TBD] markers is a working tool. A beautifully complete stack full of quiet guesses is a liability.

Prefer the gap. Always.