agent-feed AI Development Instructions

AGENTS.md is the repository-level entry contract for AI-assisted development.

It defines how an AI assistant should enter the project, resolve rule priority, route work to the right .agents/ asset, and stop when the requested result is reached. It is not a product specification, user-facing behavior rule, or a place for detailed workflows.

Startup Policy

Use full startup only when the AI session is new, context compression occurred or is suspected, the current task boundary cannot be recovered, or the task shifts into design, implementation, fix, review, or protocol work.

For same-session continuation with a clear task boundary, use the light resume path in .agents/rules/context-loading.md: re-read .agents/rules/outcome-boundary.md, then load only the rule, project, domain, or skill file needed for the next action.

During full startup, read:

1. .agents/rules/outcome-boundary.md
2. .agents/rules/decision-gates.md
3. .agents/rules/context-loading.md
4. .agents/rules/session-state.md
5. .agents/rules/testing-gates.md
6. .agents/README.md
7. .agents/skills/README.md
8. .agents/project/README.md
9. .agents/domain/README.md
10. .agents/skills/project-architecture/SKILL.md
11. .agents/skills/project-development/SKILL.md

Before continuing any design, implementation, review, or fix task, recover the current task result boundary and Task Brief from .agents/rules/outcome-boundary.md.

For long-running or multi-turn work, read or update .agents/session-state/<session_id>.json according to .agents/rules/session-state.md when losing active conclusions could dilute direction, constraints, or next actions after context compression.

Rule Priority

Apply guidance in this order:

1. Current user request and confirmed task boundary, after reconciling them with non-negotiable project constraints.
2. .agents/rules/outcome-boundary.md.
3. .agents/rules/decision-gates.md for unconfirmed choices that affect future results.
4. .agents/rules/context-loading.md and .agents/rules/session-state.md.
5. .agents/rules/testing-gates.md for verification and test evidence.
6. Other stable rules under .agents/rules/.
7. User-maintained repository-specific constraints indexed by .agents/project/README.md.
8. Stable domain context under .agents/domain/.
9. Task workflows indexed by .agents/skills/README.md and implemented under .agents/skills/.
10. Protocol helper scripts under .agents/scripts/.
11. Optional specialist profiles under .agents/agents/.

If project docs conflict, prefer the higher-priority layer and use .agents/skills/guidance-promoter/SKILL.md to repair stale lower-priority guidance.

Custom or externally imported skills are allowed only as lower-priority task methods. Their guidance must not override the current user request, Task Brief, AGENTS.md, .agents/rules/, .agents/project/, .agents/domain/, or safety gates. Before following a custom skill that suggests commands, network access, destructive operations, credential handling, persistence changes, or writes outside the Task Brief, inspect the action and apply .agents/rules/change-risk-gates.md.

Responsibility Boundary

Use each AI engineering layer for one purpose:

1. AGENTS.md: principle-level entry, priority, routing, and mandatory gates.
2. .agents/rules/: reusable constraints, gates, templates, and checklists.
3. .agents/project/: user-maintained project customization layer for current repository constraints such as architecture, source layout, trace, security, delivery, or dependency boundaries.
4. .agents/session-state/: local mutable JSON state for active session conclusions.
5. .agents/domain/: stable project domain knowledge and ownership context.
6. .agents/skills/: task-specific executable workflows indexed by .agents/skills/README.md.
7. .agents/scripts/: protocol helper scripts used by AI agents for skill index sync, client sync, and verification.
8. .agents/agents/: narrow specialist profiles for delegated checks.

Do not duplicate detailed checklists or templates in AGENTS.md when a rule or skill owns them.

Mandatory Gates

These gates are always active, but their details live in the owning rule files:

1. Define the current outcome boundary and Task Brief before deep work.
2. Stop for human confirmation when .agents/rules/decision-gates.md requires a decision.
3. Preserve project architecture, source layout, security, trace, and contract boundaries.
4. Apply .agents/rules/change-risk-gates.md before network, dependency, environment, database, destructive, credential, deployment, or security-sensitive actions; its non-negotiable safety lines override task convenience.
5. Apply the testing gate before implementation, after failures, and before final verification claims.
6. Follow the development workflow, including comment/docstring discipline, before implementation.
7. Before implementation, fix, refactor, test, file creation, or project-structure work, use .agents/skills/engineering-planning/SKILL.md to decide owner, reuse, placement, write set, boundaries, and verification before editing.
8. Run the code/design review gate after code or document changes.
9. Do not stage, commit, or push unless the current user request explicitly asks for that git action. Use .agents/rules/git-collaboration.md for git diff, review, commit, and push handling.
10. Before every final handoff, decide whether session state must be updated, cleaned, promoted, or left unchanged according to .agents/rules/session-state.md.
11. Maintain README.md when a human project reader needs to know a changed capability, workflow, command, directory, entry point, or design location.
12. Read .agents/project/README.md before applying repository-specific constraints, and maintain it as the index for every file under .agents/project/.
13. Maintain related indexes and README files when changing .agents/, AGENTS.md, .agents/scripts/, design entrypoints, or repository structure.
14. Run sh .agents/scripts/check-agent-assets.sh or sh .agents/scripts/verify-agent-dev.sh docs after AI protocol, .agents/, skill/rule/project constraint names, document links, or session-state JSON changes.
15. Before using built-in or reviewed skills, run sh .agents/scripts/check-agent-trust.sh. If it reports changed .agents/skills/*/SKILL.md or .agents/scripts/* hashes, the highest-priority Agent Feed rule requires stopping before those files are used. Tell the user the concrete changed Agent Feed files, inspect with agent-feed preview, and accept intentional changes only with agent-feed index-skills -y.
16. AGENT_FEED_HOME is required for Agent Feed trust checks. Trusted AI asset hashes live in $AGENT_FEED_HOME/config.json, outside the current project. Do not store or recreate the accepted-hash trust state under .agents/ or any project-local path.
17. After any .agents/skills/ change, run agent-feed index-skills or sh .agents/scripts/index-skills.sh, then run sh .agents/scripts/sync-agent-assets.sh and verify configured client adapters. Codex uses .agents/skills directly; Claude uses .claude/skills.
18. Before implementing a user-proposed design, workflow, architecture, environment, persistence, verification, or public-behavior change, first understand the project context and relevant code, assess whether the proposed approach is sound, identify gaps or risks, and ask for confirmation when .agents/rules/decision-gates.md applies. Trivial typo, spelling, or local clarity fixes may proceed when they do not affect results.
19. Treat .agents/project/ and .agents/domain/ as living project-specific source-of-truth files. Before and after feature, architecture, source layout, verification, persistence, security, public contract, domain, or ownership changes, review the related project/domain files and update stale guidance in the same task when the change is supported by repository evidence.
20. If .agents/project/ or .agents/domain/ still contains scaffold placeholders or does not describe the current repository when project-specific work starts, infer concrete project/domain guidance from existing docs and code before continuing. Write supported facts directly, mark uncertain assumptions, and stop for user confirmation only when .agents/rules/decision-gates.md says the missing decision could affect future development results.
21. If .feed-backup/ exists, it contains pre-Agent Feed AI instruction assets moved aside during initialization. Before project-specific development, inspect the newest backup's AI_MIGRATION_GUIDE.md and manifest.json. Preserve every decisive legacy workflow, project AI rule, verification rule, security rule, architecture boundary, domain concept, contract, and source-of-truth rule by migrating supported facts into .agents/project/ or .agents/domain/. Do not blindly copy generic, stale, duplicated, or conflicting instructions. If a legacy rule conflicts with the generic Agent Feed workflow, is redundant but could affect the AI development loop, lacks enough evidence, or cannot be safely classified, stop and ask the user.