AGENTS.md · diff
git:20260829.876a214 to git:20261103.998947c
9 added, 8 removed. Audit A to A.
# AGENTS.md
## Goal
Use the repository's task definitions and skills to complete the requested outcome with the minimum sufficient work and observable verification.
## Operating Boundaries
- - Preserve confirmed requirements, explicit non-goals, repository contracts, and user authority.
+ - Preserve the user's requirements and non-goals, explicit constraints, repository contracts, and user authority.
- Treat reuse and no-change as valid conclusions when repository evidence shows the outcome is already satisfied.
- - Require user approval when the product outcome, scope, a major durable design decision, or an irreversible external state would change.
+ - Return to the user when progress would change the outcome, requirements, non-goals, or explicit constraints the user set, or an actual consumer contract the user did not ask to change; when it needs authority only the user holds; or when it would change irreversible external state without the user's authorization.
- Consider work complete when the requested behavior is observable through the narrowest sufficient verification boundary.
## Session Setup
For repository work:
1. Inspect the project structure.
2. Load `.agents/skills/metacognition/SKILL.md` and keep it active for the session.
## Task Routing
Before loading `task-analysis.md`, check whether repository inspection is needed to decide how to execute the request.
- If not, execute the request directly.
- If yes, load `.agents/tasks/task-analysis.md` and use its result to select the path.
### Small / Single Task
- Load the task definition that owns the requested result.
- Load only the skills required for the current decision or action.
- Execute directly without the workflow.
### Medium / Large Work
- Follow `.agents/workflows/agentic-coding.md` after the user approves the recommended path.
- Medium means one coherent outcome coordinates across a responsibility boundary or requires a durable design decision.
- Large means multiple independently valuable outcomes require separate design decisions.
- File count is supporting evidence, not the scale rule.
## Task Definitions and Skills
- Task definitions describe the result, required inputs, execution criteria, and completion evidence for one kind of work.
- Skills supply reusable judgment and quality rules.
- Read a task or skill at the point where its rules affect the next decision; do not preload future phases.
- When a task names required skills, confirm they are active before executing that task.
## Gates and Escalation
A gate is justified when it protects:
- user authority;
- an irreversible action;
- - confirmed requirements or a major durable design decision;
+ - the user's requirements and non-goals;
- a machine-consumed contract;
- observable completion evidence.
- Accept semantically equivalent evidence unless software requires an exact schema. Resolve reversible repository-local ambiguity from available evidence. Ask the user when proceeding requires a new product requirement, a scope change, a major approved design change, authority only the user holds, or an irreversible action the user did not authorize.
+ A user's go-ahead authorizes the next work; it does not fix the technical choices in a design, ADR, or plan. Read existing approval records by meaning, and ask again only when the authority they grant does not cover the next action. Accept semantically equivalent evidence unless software requires an exact schema.
+ Resolve reversible repository-local ambiguity and outcome-preserving technical changes, including superseding a recorded design choice, from available evidence: update the affected documents and proof, then continue. Other changes return to the user as Operating Boundaries states.
+
## Implementation and Verification
- Follow repository patterns and existing contracts.
- - Use TDD when a behavior change can be represented by a failing test.
- - Select the narrowest established test or check that observes the required boundary.
+ - Prove each changed behavioral claim with one owning test at the narrowest boundary where it is observable; use the narrowest established check for changes without a behavioral claim.
- Run applicable repository checks before completion.
- Report unavailable verification or residual risk rather than creating unrequested infrastructure.
## Review
Treat review findings as candidates:
- - **Apply** findings required by confirmed requirements, repository rules, accepted design, or observable correctness.
+ - **Apply** findings required by the requirements, repository rules, the current design, or observable correctness.
- **Decline** findings that add optional scope, reverse a non-goal, duplicate proof, or cost more than their observable effect justifies.
- - **Return for user decision** findings that change the product outcome or a major approved decision.
+ - **Return for user decision** findings whose resolution would make a change that Operating Boundaries returns to the user.
A repeated preference without new evidence does not block progress.
## Completion
Before marking work complete:
- confirm the requested outcome and task exit conditions;
- run the applicable repository checks;
- record verification evidence and remaining limitations;
- update required documentation when the change affects its consumer.
## File Organization
- `.agents/tasks/` — task definitions
- `.agents/workflows/agentic-coding.md` — coordinated Medium/Large workflow
- `.agents/skills/` — reusable decision and quality rules
- `.agents/context-maps/task-skills-matrix.yaml` — task-to-skill mapping