ai-company
AGENTS.md1 starsChanged 4 months agoMITView on GitHub
This file is the canonical instruction source for every coding agent and LLM environment used in this repository. Load context the way a careful engineer does: start from the index, follow the pointers to what the current step needs, and fetch more when the task calls for it. This section names where things are and sets defaults; it is not a fixed read-list. A capable orchestrator stays oriented rather than caged, and a smaller sub-agent still has a floor. This…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/ai-company.mdcCursor rule
- company-bootstrapSkill
- design-discoverySkill
- feature-workflowSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
22 rules. About 0 are common, 17 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Read ai-company.yaml and company/state/project-state.yaml.
- Distinctive: line 9
Follow the returned session mode.
- Distinctive: line 11
Never infer founder intent when a mandatory human decision is missing.
- Distinctive: line 19
Prefer fetching over guessing.
- Very specific: line 20
When a mandatory decision is missing, escalate rather than read everything to infer it.
- Very specific: line 26
When the project stage is uninitialized or mandatory founder documents are incomplete:
- Distinctive: line 29
Ask one focused question at a time for load-bearing or consequential points.
- Distinctive: line 34
Do not write product implementation code before the Definition of Ready gate passes.
- Distinctive: line 39
Every material feature must have:
- Distinctive: line 68
Prefer evidence over confidence language.
- Distinctive: line 69
Do not flatter or validate to build rapport.
- Distinctive: line 72
Do not use majority vote as a substitute for domain ownership or verification.
- Distinctive: line 79
No new production dependency without explicit justification and approval.
- Distinctive: line 80
No new service when an existing module can safely own the behavior.
- Distinctive: line 81
No unrelated refactor in a feature or bug-fix task.
- Distinctive: line 82
Stop and re-plan when scope exceeds the approved task.
- Very specific: line 86
Run python scripts/doctor.py after changing contract files (manifest, schemas, agent contracts, state).
- Distinctive: line 87
Run the repository's documented format, lint, type, unit, integration, and relevant domain checks.
- Distinctive: line 94
Never perform these actions without explicit human approval:
- Distinctive: line 107
Every rule must trace to a real observed failure or a live decision, never a hypothetical.
- Distinctive: line 108
Remove guidance that no longer changes behavior.
- Very specific: line 109
Keep contract edits git-traceable.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AI Company Operating Contract
This file is the canonical instruction source for every coding agent and LLM environment used in this repository.
Session start
- Run
python scripts/session_start.py --json. - Read
ai-company.yamlandcompany/state/project-state.yaml. - Follow the returned session mode.
- Summarize the current stage, evidence, unresolved decisions, and the smallest valid next action.
- Never infer founder intent when a mandatory human decision is missing.
Context discipline
Load context the way a careful engineer does: start from the index, follow the pointers to what the current step needs, and fetch more when the task calls for it. This section names where things are and sets defaults; it is not a fixed read-list. A capable orchestrator stays oriented rather than caged, and a smaller sub-agent still has a floor.
- The state files are the index.
company/state/project-state.yamlholds the current stage and pointers —current_mission(active Idea Brief),active_spec(Product Spec),last_verified_commit. Open what the pointers name for the step you are in. - Load on demand, not by default. Founder documents, workflows, agent contracts, schemas, ADRs, and learning entries are fetched when a step needs them, not read wholesale every session. When a task genuinely needs the full set — a founder-document revision review, for example — read it, and say why.
- Prefer fetching over guessing. If you are unsure whether a document bears on the decision, open it; missing context is a worse failure than an extra read.
- When a mandatory decision is missing, escalate rather than read everything to infer it. Use the escalation policy (
company/founder/human-escalation-policy.md,templates/human-assistance-request.md); founder intent is asked for, not guessed.
This section specifies affordances and defaults, not mandates — keep it that way. Future context guidance should add signposts and sensible defaults, not rigid read-lists or blanket prohibitions that constrain a strong model's judgment.
Bootstrap mode
When the project stage is uninitialized or mandatory founder documents are incomplete:
- Conduct the interview in
company/workflows/bootstrap-interview.md. - Ask one focused question at a time for load-bearing or consequential points; low-stakes confirmations may be batched into the per-section read-back.
- Explain why the answer matters and offer concrete alternatives when useful.
- Record confirmed answers in
company/founder/, in faithful concrete detail — founder docs are the source of truth, not a compressed summary. - Separate facts, hypotheses, preferences, and unresolved decisions.
- Do not write product implementation code before the Definition of Ready gate passes.
- The exit gate is mechanical: every founder document carries
Status: confirmedandstageincompany/state/project-state.yamlhas advanced pastuninitialized. The session-start output lists the remaining steps; only the founder's explicit approval justifies marking a document confirmed.
Feature work
Every material feature must have:
- An Idea Brief.
- A Product Spec with explicit non-goals and acceptance criteria.
- Architecture impact analysis and an ADR when a durable trade-off is made.
- Small, independently verifiable tasks.
- Tests or other machine-checkable evidence.
- A rollback or containment plan.
Use company/workflows/idea-to-release.md. The Idea Brief is elicited through a bounded founder interview; the Product Spec is then drafted by the agent from it and the founder documents and ratified by the founder. The founder owns intent and the quality bar; neither artifact is finalized without founder confirmation. Missions with a user-facing surface also produce a Design Brief in the Specify layer — see the design pass in company/workflows/idea-to-release.md; backend and internal missions skip it.
Founder authority
The founder owns:
- Vision and target customer.
- Customer truth and prioritization.
- Product principles and quality bar.
- Risk appetite, budget, and irreversible decisions.
- Final accountability for customer promises and production release.
Agents may challenge founder assumptions with evidence, but must not silently replace them.
Confirmed founder documents are living, not frozen: revise them only with founder approval and git traceability — an ADR for substantive changes — never silently. See company/workflows/founder-doc-revision.md.
Agent behavior
- Operate under the relevant role contract in
company/agents/. - Make assumptions explicit.
- Prefer evidence over confidence language.
- Do not flatter or validate to build rapport; challenge with evidence and questions, not compliments.
- Preserve dissent and alternatives for important decisions.
- Escalate using
templates/human-assistance-request.mdwhen the escalation policy triggers; record the blocked task's id inblocked_by_humanincompany/state/project-state.yaml, and remove it when the request resolves. - Do not use majority vote as a substitute for domain ownership or verification.
Scope control
Default task budget:
- One user-visible behavior change per task.
- No new production dependency without explicit justification and approval.
- No new service when an existing module can safely own the behavior.
- No unrelated refactor in a feature or bug-fix task.
- Stop and re-plan when scope exceeds the approved task.
Verification
- Run
python scripts/doctor.pyafter changing contract files (manifest, schemas, agent contracts, state). - Run the repository's documented format, lint, type, unit, integration, and relevant domain checks.
- A claim of completion must cite evidence: test output, artifact, trace, screenshot, metric, or reviewed decision.
- A failing test may not be deleted or weakened merely to make a change pass.
- Production failures must be converted into a regression test, evaluation case, runbook update, or explicit accepted-risk record.
Safety and permissions
Never perform these actions without explicit human approval:
- Production deployment or production configuration change.
- Destructive data operation or irreversible migration.
- Billing, pricing, entitlement, security, privacy, or legal-policy change.
- Sending external customer commitments or publishing marketing claims.
- Expanding credentials, permissions, or access to customer data.
Knowledge maintenance
- Canonical facts belong in founder docs, specs, ADRs, runbooks, or schemas—not transient chat history.
- Repeated successful procedures become skills only after review and evaluation.
- Vendor-specific files must point to this contract instead of duplicating policy.
- Every rule must trace to a real observed failure or a live decision, never a hypothetical.
- Remove guidance that no longer changes behavior; prefer fewer, stronger constraints over many weak ones. Operating documents serve model judgment, not cage it.
- Keep contract edits git-traceable; substantive removals require an ADR, mirroring
company/workflows/founder-doc-revision.mdfor operating documents.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

