Manifesto

Introduction

Generative AI is faster at producing answers than humans are at thinking them through. When generating becomes cheaper than thinking, the path of least resistance takes over: the AI proposes, the human accepts, and speed starts replacing thought.

That shift creates risks that are easy to miss:

• Judgment drifts away from the person. The faster the machine can produce, the easier it becomes to stop questioning, exploring and deciding deliberately.
• Accountability dissolves. Work goes out that nobody fully understands — code, a report, a post. When it fails, “the AI wrote it” explains nothing — a machine cannot own an outcome.
• Understanding erodes. Tests pass, drafts go unread, and people sign off on what they cannot explain.
• Design erodes. AI is good at producing locally plausible pieces, but local plausibility is not global coherence. Without someone holding the intent, structure starts being accumulated rather than designed.
• Plausibility replaces value. Generated work often looks complete and correct, but looking right is not the same as being useful, true or worth making.
• Existing controls weaken. Reviews, roles and definitions of done still matter, but they need to evolve when machines perform a significant part of the work.

None of this is an argument against AI. It is an argument against surrendering judgment to speed.

AI should make production cheaper, not thinking optional.

The question is not whether AI produces the work. It is who remains in charge of it.

What we hold

talaia stands on a simple conviction: the human person comes first, and no tool can take the place of human judgment or responsibility.

Keeping that order, we have come to value:³

Human judgment over machine autonomy
A person who answers over a system with no owner
Understanding what goes out over accepting what works
Deliberate design over generated accumulation
Knowing when not to use it over using it because it is there
Work that serves people over work that merely looks complete

A tool serves best when it strengthens the person who works and fails the moment it invites that person to stop being present.

talaia adheres in full to The Pro-Human AI Declaration, which also inspired it.

What AI is

At talaia we know that AI is software, and only software. It is not alive: it has no intelligence or perception comparable to a person’s, no spirit, no desires of its own. It does not understand what it produces. It imitates language, analysis, even empathy and care, and the imitation can be useful; but its learning is statistical adjustment over data, not the growth of someone shaped by choices, mistakes and time. And it is not neutral: its answers carry the choices and assumptions of the few people who designed and trained it, so what sounds like a fact may be their opinion.

That makes talaia more than a proposal for how to work with AI. It is a defense of human work with AI: against the ways of working that dilute responsibility, and against replacing human grace, talent and personality. AI should augment our intelligence, through the tool, not replace it. We have much more to bring to this world.

We call the principle that follows from this human-in-charge.

Human-in-charge

The principle

Human-in-charge means that every use of AI has a person in charge of it: someone who decided it should exist, designed how it works, understands it, and answers for it by name. It is not a human placed in the path of a system to approve each thing the system produces. It is a person who stands behind the system itself.

Take a process that uses AI to classify a thousand emails a day. Nobody needs to read, check and understand a thousand classifications; that would undo the reason for building it. What must be true is that a person can say what the process is for and what value it brings, how it is built and where the AI sits in it, what can go wrong and what happens when it does, and that the outcome is theirs. The machine may act a thousand times with no one watching. It never acts on its own authority: it acts on the authority of the person who put it there, inside the limits that person drew.

Being in charge is held at three levels, and none of them is the output of an automation:

• Responsibility. A named person answers for what the system does, including what it does when no one is looking.
• Design. A person decided what is handed to the machine and what is not, knowing the risks and the value. The structure was designed, not accumulated.
• Understanding. A person understands the code and the structure that carry the AI, and can explain how they work and why without the help of an AI.

We hold this as a belief, not a proposal. The harm AI can do is avoided only when every use of AI has a human in charge of it, without exception, as an obligation and not a recommendation.

How to apply it

Responsibility is not taken from a person: it is given up a little at a time, one unexamined delegation after another, until none is left. Each step is comfortable. The system quietly shapes how people work and judge, it is accepted until it is no longer seen, and what was built comes to look inevitable.⁴ What is lost on the way is cognitive sovereignty: a person’s own judgment. The defence is friction:

• Stop and ask who decided that this should be handed to the machine, and by what measure its answers count as correct.
• Keep deciding, deliberating and doubting, even though thinking is tiring and the machine is not.
• Follow no oracle. No guru, model or algorithm can carry the responsibility of choosing.
• Do not delegate what cannot be optimised or reduced to a calculation.

talaia makes this practicable by bringing the manifesto and the Certificate of Understanding into every piece of work where AI is used. The manifesto is the frame: why the person stands above the tool. The certificate is the practice, and it is signed over what a person makes — the code, the structure, the design of the automation — not over each thing the automation later produces. Where there is no name, nobody is in charge.

The Certificate of Understanding

The Certificate

The Certificate of Understanding is a tool for applying the manifesto day to day, for people who work with AI. Its statements aim to sum up the actionable part of the manifesto.

The text, in the shape of the DCO:⁵

Certificate of Understanding
Version 1 — talaia.dev/certificate

By signing off on this work, I certify that:

(a) The work was created, in whole or in part, with the
    assistance of an AI, at my direction and to a brief
    that was mine; and

(b) I have read the work in full; I understand what it
    says and why, and can explain it without the help of
    an AI; I have checked what it claims, and its
    opinions and assumptions are mine; and I take
    responsibility for the work and make it my own.

I sign this in keeping with the talaia manifesto: talaia.dev

Two clauses, and the signature means both at once: the machine was here, and a person answers for what it made.⁶

Against Co-Authorship

The certificate records assistance, never co-authorship. An author is not the one who produced the words but the one who stands behind them. To author is to mean something and to be held to it. That takes a self with something at stake, and a machine has none.

Some tools say otherwise. Claude Code, by default, ends the commits it writes with a git trailer that names the machine as an author:

Co-Authored-By: Claude <[email protected]>

We are against that use and against that definition. The trailer is not just a label: GitHub and other forges read it and list the machine next to the person, as an author of the change. Calling it a co-author turns help into authorship, and splits the responsibility between a person and something that cannot answer for anything. talaia keeps the two apart: Assisted-by: names the machine that helped, Signed-off-by: names the person who answers.

How to use it

The text lives at talaia.dev/certificate and is never signed there. You sign by adding one line to the work:

talaia.dev/certificate — John Doe

Two parts, in that order:

• The address is the certificate. It points at a fixed text, so the line means the same thing wherever it appears, and clause (a) is already in it: an AI was here.
• The name is the certification. A person is here, and both clauses are true of them.

Adding the line is the act; the gesture is deliberate, and it is yours.

Under a post, the line as it is. At the foot of a report, the address once and one name per hand, because the work passed from hand to hand — the analyst to the head of finance, the head of finance to the board — and each hand adds its own name under the last:

talaia.dev/certificate
John Doe, Head of Finance, 2026-09-14
Jane Roe, CEO, 2026-09-16

In a commit, the address goes in the message and -s writes the name as the Signed-off-by: trailer; the reviewer’s sign-off on the pull request is the next hand:

git commit -s -m "feat: export orders as CSV (#42)" -m "talaia.dev/certificate"

feat: export orders as CSV (#42)

talaia.dev/certificate

Signed-off-by: John Doe <[email protected]>

The lines accumulate, and every one of them is a person who read the work in full and answers for it. That is the chain of towers: the fire passes, and at every tower someone is watching.

Talaia

The manifesto and the certificate are the same for everyone. What changes is who adopts them, and there are two ways in: a person or a team, on their own; or a company, as a whole.

For individuals and teams

talaia is open and free to use, and nobody’s permission is needed. You already have the certificate. What remains is the way of working that makes signing it honest: the framework, which says how to brief the AI, how to read what comes back, and when to sign — a post, a report, a commit. For software there is also a small tool that installs the rules your AI agent works under and checks that every commit carries a signature. All of it is under Individuals and Teams.

For companies

A company can make the manifesto its own: its values held across the whole organization, so that people stay in charge of the work AI helps them make. The certificate is how that shows in each piece of work: it carries the name of a person who read it and answers for it. From there it travels outwards in both directions: delivered to customers as a seal on what the company hands over, and required of distributors for what the company receives.

See the Companies tab for the services we offer to help companies apply talaia, and for other related services.

Framework

Introduction

The manifesto says what we stand for; the certificate says what a person promises; the framework is how the promise becomes possible.

talaia does not replace the way you already work; it sits underneath it. Stories can live in Jira, GitHub Issues or a text file; a report can still be a Word document; a post is still a post. What talaia adds is a boundary between what may be delegated and what must remain human:

• The instrument may draft, build, test, iterate and report.
• The instrument may not design the system, decide what counts as done, accept its own work, sign it, or put it into the world. Those acts are yours.

Working output is not accepted work.

The framework

Like Scrum or Kanban, talaia is a method before it is a tool. Unlike them, it works per piece of work, not per sprint, so it runs under whatever process you already have.

It has five steps. The first is done once per system; the other four are a loop, run once per piece of work:

DESIGN ───▶ ( BRIEF ───▶ BUILD ────▶ WATCH ───▶ SIGN )
person        person     instrument  person     person, in the work itself

Work with an AI is a conversation: something is asked, something comes back, and the next turn corrects the last. The loop keeps that shape: Brief, Build and Watch turn until you are satisfied, and the Sign closes it. You direct at the start and answer at the end.

None of it is new ceremony. The Design is what you already know about your system, written down; the Brief is the asking itself; Build is the instrument working inside the rules; the Watch is you reading what came back; the Sign is the line you add. Together the steps draw a single line: execution may be delegated; judgment may not.

Design — the human says what the system is

Nothing is asked yet. The Design is what is true of the system, written down by you before the first Brief:

1. The architecture. What the system is, what it is made of, and the principles it keeps.
2. The conventions. What “done right” looks like here: how the work is made, checked and written.
3. The constraints. The hard limits: what may not be done even if it works, and the choices that bind what comes after.

Every kind of work has all three: a codebase; a publication — its line, its house style, what it never prints; a series of reports.

Three rules keep it yours:

• The instrument does not design the system. It may help you word the Design and format it; it never changes it on its own.
• Every Brief is read against the Design. If an ask contradicts it, or the work shows it wrong or incomplete, the instrument says so and stops.
• Only you reopen it. The instrument goes on when you have decided: by rewriting the Design yourself, or by dictating the change.

Done when: the Design is written and you approve it. Until then, no Brief starts. Signing it as you sign any other work — the line, your name — is good practice; nothing checks it.

Brief — the human says what “done” means

Nothing is produced yet. The Brief is not a meeting and not a form: it is your ask, in your own words, and the conversation that follows it.

1. You say what you want: what must be true when the work is finished.
2. The instrument reads the ask against the Design and the project — the code, the sources it is working in — and returns what is loose: a contradiction, an open question, a decision the ask leaves to be taken.
3. You answer. The instrument takes none of those decisions itself: nothing of design, architecture or higher order, and no substantial change — a library swapped, a structure reshaped, a capability added or removed.

Done when: no question is left open. While one remains, the Brief turns. When none is left, the instrument starts Build on its own, without asking permission: the ask, what “done” means and every decision are already yours.

Keep your brief. It is your evidence for clause (a) of the certificate — the AI helped, and the ask was yours — and the one part of the work that was yours from the first word. Where it helps, publish it beside the result.

Build — the instrument works

Nothing is decided here. The instrument works to the Brief, under seven rules:

1. The smallest thing. The least that makes the Brief true.
2. Nothing more, nothing less than briefed. No features, abstractions or “improvements” nobody asked for; nothing that was asked for silently dropped.
3. What a person wrote stays as they wrote it. Hand-made content is not touched — above all your edit to something the instrument produced. That edit is a decision, and the next turn works around it, not over it. Only an explicit ask reopens it.
4. Proof first, and it never bends. Where the work can be tested, the failing test is written before the work and shown failing; where it cannot, the check is named before the work starts. Tests and checks are never deleted, skipped or weakened.
5. Every claim comes with its evidence. “Tests pass” counts only as the real output of tests that ran, shown. “According to the data” counts only with the source beside it.
6. The work stays watchable. Small enough to be read in full in one sitting, coherent enough to be explained without help. When it grows past that, it is split.
7. Iterate, never insist. If the same failure survives two attempts, the instrument stops and returns the decision to you.

Done when: what was briefed is true and its evidence is shown — or two attempts have failed and the decision is back with you.

Watch — the human keeps guard

The Watch happens where the work already is: the diff in your editor, the document on your screen, the draft in the chat.

1. Read every part you are about to accept. If you cannot explain a hunk, a paragraph, a figure, do not accept it: ask, or take it over by hand.
2. Check the evidence, not the claim. The tests ran in front of you, real output included; the sources open; the numbers trace. Anything still marked unverified is verified by you or removed.
3. Keep only what you approve. In code, hunk by hunk, staging the ones that pass; in a document, paragraph by paragraph, leaving the rest out.
4. Send back the rest. All of it or a part: it goes round the loop again until it is what you asked for.

Tools may scale the reading, never the judgment. Semantic diffs, review assistants, summarizers: use whatever helps you read; the decision to accept stays yours.

Done when: you have read everything you kept, you can explain it, and nothing in it is still unverified.

Sign — the human answers for it

You add the line — the address and your name — in the work itself; in software, the commit.

The instrument does not sign, does not publish, does not write history. In software: no add, no commit, no push, no merge — no state-changing git command, ever. Reading history is allowed.

Done when: the work carries your name. The instrument iterates; you decide when the loop ends, and the signature is that decision.

Assurance

Anyone can add the line without having read a word of the Build. No machine will catch it, and the framework does not pretend one will. What the line does is change what the work is: you declare that an AI helped and that you read the result, understood it and answer for it, and whoever receives the work reads it as yours — not the machine’s, not a draft, not a proposal — and judges it as your work is judged.

So assurance comes from the signer. The line does not check the work; it makes the work yours, and what carries your name you do properly, because your name is what people will ask for when it fails. The certificate does not add a control. It removes an excuse.

The receiver’s part is to trust the signature, and to ask; responsibility has always meant asking the one who signed. Why this and not that; where the figure comes from; what this part does; what would break it. Whoever read the work and made it their own can answer without the tool. Whoever signed without reading finds out what the signature meant. Four things make the asking possible:

• A name. The certificate line: the address, and a person who answers.
• The evidence. The checks the work cites ran, and their output is beside it.
• The size. The work stays within what one reading can hold.
• The reading. Rework and reverts — never throughput — tell whether the Watch was real.

In practice

The instrument’s rules

The framework is applied in two places, and nowhere else. The first is the person’s own discipline: write the design and the brief in your words, read the work in full, sign only what you can answer for. No tool enforces that part; it is the habit the certificate names. The second is the instrument: the rules — the Design it reads and never changes on its own, Brief, Build, the refusal to sign — written into the instructions the agent reads on every turn. Every agent takes such instructions, under one name or another: AGENTS.md, CLAUDE.md, a system prompt, a custom instructions field. The rules go there once, and the agent works inside them from then on.

talaia.dev/agentsmd

This is the one file that matters: the framework, as the agent reads it, kept in one place so that every copy says the same thing. Save it at the root of your repository. Where each tool reads it — Claude Code, Codex, Gemini, Cursor, Copilot, or a chat window — is at talaia.dev/how-to-agentsmd.

Content and documents

An article, a thread, an image; a report a manager will decide on. The Design is what holds across every piece: the line, the house style, what is never published — written by you, once, and given to the assistant before the first ask. Brief and Build are the conversation with the assistant. The Watch is the document on your screen: you read the draft and keep the paragraphs you accept. The Sign is the line, added by hand. Under a post, as it is:

talaia.dev/certificate — John Doe

At the foot of a report, the address once and one name per hand:

talaia.dev/certificate
John Doe, Head of Finance, 2026-09-14
Jane Roe, CEO, 2026-09-16

Software

Software is the medium where the framework maps onto gestures you already make, and where the rules are strictest: the instrument does not write git. No add, no commit, no push, no merge — nothing enters history without a human decision.

The Design is three files in .talaia/, at the root of the repository — architecture.md, conventions.md, constraints.md — written by you, read by the agent on every turn, and committed and signed like any other change. The agent writes in them only at your dictation.

Brief and Build are the conversation with the agent, under the rules in its instructions file. Watch and Sign are git:

• Watch is the diff and the stage. You read the change in your editor, hunk by hunk, and stage what you accept: staging is the first act of acceptance.

• Sign is the commit. You write the message in your own words — the agent never drafts it; if you cannot write the message, you cannot commit — with the address in it, and -s writes your name as the trailer:

  git commit -s -m "feat: export orders as CSV (#42)" -m "talaia.dev/certificate"

  feat: export orders as CSV (#42)
  
  talaia.dev/certificate
  
  Signed-off-by: John Doe <[email protected]>

• The pull request is the next hand. The reviewer reads the change and puts their own sign-off behind yours; the pull request template asks the certificate again, in front of the team, where review already happens.

The agent ends every finished piece of work with the certificate and the command to sign. Same trailer, same gesture, same enforcement as the DCO: if your project already uses it, one sign-off certifies both — talaia adds understanding on top of origin, never replacing it.

The forge can hold the gate. A check runs on every pull request and fails when a commit in it carries no Signed-off-by:; make it a required check and no signature means no merge — the DCO’s lever, one level up.

talaia.dev/pr-check

One file. Where to put it on GitHub, GitLab, Bitbucket or Gitea, and how to make it required, is at talaia.dev/how-to-pr-check.

Using talaia

This part is for software only: it applies when the work lives in a git repository. Everything before it holds for any work done with AI.

Quick start

Install once, then two commands inside your own repository:

go install talaia.dev/cmd/talaia@latest   # once; Go 1.23+ is the only requirement

cd ~/your-project
talaia init                 # the instructions file, the design files, the pull request template, the check
talaia hooks claude         # optional: deny git writes in the agent's own settings (claude, gemini, git)
talaia audit --strict       # any time: are the commits signed? — read from git

Write the design in .talaia/, commit the scaffold, open your AI tool, and work as usual. The CLI executes no AI and makes no network calls; it creates files, edits only the settings list that hooks owns, and reads git history. talaia help lists the commands.

talaia init

Run it at the root of your repository. It creates the harness — eight files — and touches nothing else:

AGENTS.md                     The framework rules for AI agents
CLAUDE.md, GEMINI.md          Redirects to AGENTS.md (Claude Code, Gemini CLI)
.github/
├── PULL_REQUEST_TEMPLATE.md  What, why, how it was tested + the certificate
└── workflows/talaia.yml      The audit check on every pull request
.talaia/                      The design: yours to write
├── architecture.md           Overview, structure, principles
├── conventions.md            Coding and development conventions
└── constraints.md            Hard limits and binding decisions

init is idempotent and never destructive. Existing files are left exactly as they are; only missing files are created.

talaia hooks

AGENTS.md tells the agent never to run a state-changing git command. talaia hooks <agent> makes that rule mechanical, in the place each agent obeys, so the commit stays the person’s even when the agent forgets:

talaia hooks claude   # .claude/settings.json  → permissions.deny: one Bash rule per git write
talaia hooks gemini   # .gemini/settings.json  → tools.exclude: one run_shell_command per git write
talaia hooks git      # .git/hooks/            → reference-transaction + pre-push, this clone only

The git writes denied are the ones AGENTS.md names and their equivalents: add, am, apply, branch, checkout, cherry-pick, clean, commit, merge, mv, pull, push, rebase, reset, restore, revert, rm, stash, switch, tag. Read-only git stays open.

• claude and gemini edit a versioned settings file, so the rule reaches everyone who clones. Existing settings are kept: only the deny list grows, with what is missing; a file that is not JSON is reported and left alone. Running it twice changes nothing.
• git works with any agent, because every agent ends up calling git. The two hooks refuse when the process carries an agent’s environment variable — CLAUDECODE (Claude Code), GEMINI_CLI, CODEX_SANDBOX, or TALAIA_AGENT=1 for any agent you launch yourself — and do nothing otherwise, so the person and their tools never notice them. reference-transaction stops every ref update (commit, branch, tag, stash, merge, rebase) even under --no-verify; pre-push stops pushes, unless --no-verify. They do not cover the index or the working tree (add, reset --hard, checkout -- file, clean): that is what the agent’s own settings are for. Hooks live in .git/hooks/, so they are per clone: run it again after every fresh clone. An existing hook is never overwritten; chain them by hand.

None of this is a security boundary. An agent can call git another way or unset its own variable; a deny rule stops the command the agent usually writes, not the program. What holds against a deliberate bypass is that the commit carries the person’s name. Agents with no per-command deny list in the repository — Codex, Cursor, Copilot, Windsurf, Aider — keep the rule from AGENTS.md alone, plus the git hooks where they set a variable.

talaia audit

Assurance is a by-product of git, not a report. talaia audit reads the history — one git log, read-only, merge commits skipped — and says whether the signatures are there: how many commits carry Signed-off-by: and a story id, and which do not. With --strict it exits with status 1 on any unsigned commit — a missing story id or an oversize commit is only reported; that is what the pull request check runs. Narrow it with whatever you would pass to git log: talaia audit main..feature, talaia audit --since=2026-08-01.

Development

Project layout

cmd/talaia/                  Entry point: builds the CLI app and registers the modules
internal/cli/                Command dispatcher
internal/modules/scaffold/   talaia init — scaffolding, report, tests
  └── templates/             Every generated file, editable; embedded at build time
internal/modules/hooks/      talaia hooks — the git rule in the agent's settings or the clone's hooks
internal/modules/audit/      talaia audit — git log parsing, summary, text/JSON output
action.yml                   The audit check as a composite GitHub Action (uses: talaia-dev/talaia@…)
.github/workflows/ci.yml     This repo's CI: build, test, vet, fmt — and the audit check on PRs
docs/README.md               This document: the README and the website's content
web/                         talaia.dev — Astro, static, self-hosted fonts
AGENTS.md, .talaia/, .github/   The framework, applied to this repository itself

The CLI

Go 1.23+, standard library only. The usual loop:

make build   # → bin/talaia
make test    # go test ./...
make vet     # go vet ./...
make fmt     # gofmt

To get a system-wide binary from a clone, build as your own user first, so bin/ is not left owned by root:

git clone https://github.com/talaia-dev/talaia.git
cd talaia
make build && sudo make install   # → /usr/local/bin/talaia
# or, per user, without sudo:
make install-user                 # → $(go env GOPATH)/bin/talaia

Each capability is a self-contained module under internal/modules/<name>/ exposing Register(app *cli.App), wired in cmd/talaia/main.go; a new command is a new module.

The website

web/ is an Astro site that renders this README — web/src/content/docs is a symlink to docs/, so both paths are literally the same file: edit either, never replace the link with a copy — and serves it as plain text at /llms.txt. Node 22 (.nvmrc):

cd web && nvm use
npm run dev             # http://localhost:4321
npm run build           # → dist/
npm run check           # verifies the in-text wordmark transform against dist/
sh scripts/og.sh        # re-renders public/og.png (needs headless Chrome)
python3 scripts/icons.py   # regenerates favicon.ico and apple-touch-icon.png

The README stays plain markdown; what looks designed on the site — the wordmark in running text, the two towers, the manifesto pairs, the cards — is applied at build time from the markdown’s own shape (two small Sätteri plugins and a few CSS selectors). If you rename a section, the index follows; the one thing that will not is the Get started button, which points at #the-instruments-rules.

How to contribute

talaia.dev grows in two directions, and both are open at github.com/talaia-dev/talaia:

• The manifesto and the method — the ideas. If the interpretation misses something, a value pair is wrong, or the loop doesn’t survive contact with your team, open a GitHub issue and make the case. Changes to the manifesto are held to a high bar, measured against the foundation, and discussed in the open before any wording changes — it is meant to be stable, not static.
• The techniques and the code — the practice. Rules for AGENTS.md, prompts, CI recipes, checks: anything that makes an AI agent obey the manifesto in a real project. And the CLI itself. This is where most contributions belong, and where the framework grows from practice. Every design choice reflects a vision of the person who will work inside it; contribute accordingly.

Nothing lands on main directly — not from a contributor, not from a maintainer. Every change is proposed on its own branch and enters the repository through a pull request, or not at all:

1. Propose first. For anything beyond a small fix, open an issue and make the case, so the direction is agreed before the work. The issue is the story the commits will reference.
2. Branch, never main. Contributors fork and branch; maintainers branch. One change per branch, small enough to read in a sitting.
3. Verify before proposing: make test and make vet for code; for docs and techniques, check them against a real project.
4. Own what you propose. talaia is built with its own framework — this repository has the AGENTS.md, the design files and the pull request template that talaia init gives yours. An AI may write your contribution, but you read the diff before opening the pull request, you sign every commit (git commit -s, with Assisted-by: when it applies), and the pull request carries your name. The manifesto applies to contributing too.
5. The pull request is the gate. main is protected: it takes no pushes, only merged pull requests, and a pull request merges only when its checks pass — the build and tests, and talaia audit over its own commits: unsigned, no merge — and a maintainer has read it and approved. Approval is the reviewer’s signature: the second hand of the chain.