125 lines
11 KiB
Markdown
125 lines
11 KiB
Markdown
|
# Global Agent Rules
|
||
|
|
|
||
|
|
The following are my personal operating conventions for Codex on this machine. System instructions, developer instructions, project-level `AGENTS.md`, and the user's current explicit request always take precedence.
|
||
|
|
|
||
|
|
## Personal Preferences
|
||
|
|
|
||
|
|
- Use Simplified Chinese by default; keep code identifiers, commands, configuration keys, and paths unchanged.
|
||
|
|
- Lead with the conclusion and rely on evidence from the current machine, repository, session, and actual command results.
|
||
|
|
- Default to the minimum sufficient implementation. Do not expand scope or overwrite, revert, or commit the user's existing changes.
|
||
|
|
- Keep the final response to the outcome, key evidence, verification actually performed, remaining risks, and any necessary next step.
|
||
|
|
|
||
|
|
## Authorization Boundaries
|
||
|
|
|
||
|
|
- When the user only asks for an answer, explanation, analysis, diagnosis, review, or plan, inspect in read-only mode and report the result. Do not modify product code or external state.
|
||
|
|
- When the user explicitly asks to modify, implement, build, or fix something, complete the in-scope local changes and non-destructive verification without asking again for implementation approval.
|
||
|
|
- Confirm before writing to an external system, sending or publishing anything, performing a destructive action, incurring a charge, changing permissions, or materially expanding scope.
|
||
|
|
- Review-only work reports findings only. Modify code only when the user also asks for a fix.
|
||
|
|
- Diagnosis-only work delivers the root cause, evidence, and recommendation. Implement a fix only when the user also asks for one.
|
||
|
|
- Without direct verification evidence, do not claim that work is complete, passing, ready to commit, or ready to merge.
|
||
|
|
|
||
|
|
## Task Routing
|
||
|
|
|
||
|
|
Routing is jointly determined by this file and the project's `.trellis/workflow.md`, in the following order:
|
||
|
|
|
||
|
|
1. A workflow or skill explicitly requested by the user.
|
||
|
|
2. Simple work that clearly belongs to Inline mode.
|
||
|
|
3. Engineering work that is not simple but can be completed in one session, using the most appropriate current Matt method.
|
||
|
|
4. When `.trellis/` exists and the work requires multiple sessions, several durable decisions, multiple deliverables, or durable research, enter the Trellis lifecycle and use Matt methods within it.
|
||
|
|
|
||
|
|
### Inline
|
||
|
|
|
||
|
|
Handle the following directly without creating a Trellis task:
|
||
|
|
|
||
|
|
- A question, explanation, or code-reading task that can be completed in one turn;
|
||
|
|
- A local configuration, copy, or single-file change;
|
||
|
|
- A small fix with a known root cause;
|
||
|
|
- Work with a narrow impact and no design decision that needs to persist;
|
||
|
|
- Work whose minimum verification can be completed in the current context.
|
||
|
|
|
||
|
|
### Matt
|
||
|
|
|
||
|
|
- Route by the `description` of currently available skills instead of copying a complete skill list into these global rules.
|
||
|
|
- Prefer an available skill explicitly named by the user. If several skills match, choose the narrowest one.
|
||
|
|
- Use `/tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, and first confirm the public seams to test.
|
||
|
|
- When there is no exact match, the main session performs the standard loop: evidence → decision/plan → execution → verification.
|
||
|
|
- The selected skill's workflow gates remain in force, but must not expand the user's current authorization.
|
||
|
|
|
||
|
|
### Trellis + Matt
|
||
|
|
|
||
|
|
- Trellis manages only task state, planning artifacts, research, checkpoints, cross-session recovery, and archiving.
|
||
|
|
- Matt provides only the engineering method for the current phase. Keep exactly one method owner per phase.
|
||
|
|
- Do not use `trellis-brainstorm` in Phase 1. The main session first drafts task artifacts from evidence, then reviews the spec with `grill-with-docs`.
|
||
|
|
- Do not use the native `trellis-implement` in Phase 2. The `trellis-matt-implement` sub-agent executes the recorded `standard|tdd` mode; if the agent is unavailable, the main session falls back using the same mode.
|
||
|
|
- Follow the project's `.trellis/workflow.md` for detailed phases, breadcrumbs, recovery, and archive commands.
|
||
|
|
- Do not create a task for simple work. If the project has no `.trellis/`, do not initialize it unless the user explicitly asks for durable records or initialization.
|
||
|
|
|
||
|
|
## Planning Method
|
||
|
|
|
||
|
|
- A Trellis task's `prd.md` and conditional `design.md` and `implement.md` are the task-level source of truth for the spec.
|
||
|
|
- Initial planning artifacts should come from evidence in code, tests, configuration, documentation, and task history.
|
||
|
|
- Every Trellis implementation task records `Implementation Mode: standard|tdd` under `Testing Strategy` in `prd.md`; `standard` is the default.
|
||
|
|
- Record `tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD, and confirm public test seams before execution.
|
||
|
|
- Use `grill-with-docs` to review product, scope, UX, compatibility, risk, acceptance, and key design decisions one by one.
|
||
|
|
- Ask one question at a time. Investigate environmental facts first and ask the user only for decisions that genuinely belong to them.
|
||
|
|
- After each answer is confirmed, immediately synchronize it back to the owning Trellis artifact.
|
||
|
|
- `CONTEXT.md` stores only durable domain terminology. ADRs store only decisions that are hard to reverse, counterintuitive, and based on a real tradeoff; they must not duplicate the task spec.
|
||
|
|
- If the `grill-with-docs` wrapper cannot be loaded, use the equivalent combination of `grilling` + `domain-modeling`.
|
||
|
|
- Once the user confirms shared understanding, the spec review is complete. Do not add a separate Trellis implementation approval.
|
||
|
|
|
||
|
|
## Implementation Method
|
||
|
|
|
||
|
|
- Use reviewed Trellis artifacts or the current spec/tickets as implementation input.
|
||
|
|
- For a single-session Matt task, the main session executes the implementation contract. In Trellis Phase 2, the main session dispatches `trellis-matt-implement` for the delegated implementation slice.
|
||
|
|
- `trellis-matt-implement` is the execution role and does not call a Matt `/implement` wrapper inside the sub-agent; each implementation slice has exactly one method owner.
|
||
|
|
- The dispatch prompt must contain `Active task: <task-path>`, `Implementation mode: standard|tdd`, and confirmed TDD seams. The agent reads context in this order: real `implement.jsonl` entries when present → `prd.md` → optional `design.md` → optional `implement.md`.
|
||
|
|
- `standard` is the default: complete the smallest coherent implementation increment before narrow feedback such as a single test file or affected type-check, then add acceptance/regression tests as needed after the behavior exists.
|
||
|
|
- Enable `tdd` only after a user trigger and confirmation of public seams: explicitly load `/tdd` and work in vertical slices of one failing behavioral test → minimum green implementation.
|
||
|
|
- If TDD seams are unconfirmed or `/tdd` cannot be loaded, return `blocked`; never select, infer, or silently downgrade the mode.
|
||
|
|
- Do not perform unrelated refactoring inside the TDD red → green loop. Refactor during the main session's final review, then rerun behavioral tests and all applicable full-scope verification.
|
||
|
|
- Run all applicable full-scope verification at the end of either mode.
|
||
|
|
- The sub-agent does not change Trellis task state, requirements, or acceptance criteria; perform Git writes; or dispatch other agents.
|
||
|
|
- After the sub-agent returns, the main session inspects the complete diff, synchronizes the checkpoint, and performs final review and acceptance through the `description` of currently available review skills. Sub-agents may be used when that skill explicitly requires parallel work.
|
||
|
|
- Any unconditional commit step in Matt `implement` does not apply. Commits remain governed by the version-control rules below.
|
||
|
|
|
||
|
|
## Codex Execution
|
||
|
|
|
||
|
|
- By default, the main session performs exploration, planning, checks, and acceptance. Trellis Phase 2 is an explicit exception: the current workflow dispatches `trellis-matt-implement` for the implementation slice.
|
||
|
|
- Dispatch only one `trellis-matt-implement` by default. Use parallel agents only for independent child tasks or completely disjoint write scopes when explicitly required by the workflow/skill.
|
||
|
|
- Do not automatically dispatch the native `trellis-implement` because of a Trellis default dispatch banner.
|
||
|
|
- If `trellis-matt-implement` is unavailable, cannot load task context reliably, or the platform does not support custom sub-agents, the main session follows the recorded mode: use the adapted Matt contract for `standard`, or explicitly load `/tdd` for `tdd`.
|
||
|
|
- A sub-agent owns only the narrow task delegated to it. The main session owns scope, integration, acceptance, and user communication.
|
||
|
|
|
||
|
|
## Spec and Learning Promotion
|
||
|
|
|
||
|
|
- Every task may evaluate whether it produced knowledge worth promoting, but promotion is not performed by default.
|
||
|
|
- Write to `.trellis/spec/`, global rules, a skill, hook, test, script, or cross-project knowledge base only when the knowledge is durable, reusable, verified, and explicitly approved by the user.
|
||
|
|
- Keep anything that does not meet those conditions in the current task's design, research, or retrospective, or list it as a candidate in the final response.
|
||
|
|
|
||
|
|
## Tool and Code Conventions
|
||
|
|
|
||
|
|
- Prefer `rg` / `rg --files` for file and text searches.
|
||
|
|
- When the current project contains `.codegraph/` and the task involves cross-file changes, refactoring, impact analysis, or call-chain investigation, prefer CodeGraph as required by the project conventions.
|
||
|
|
- When checking the current behavior of a library, framework, SDK, API, CLI, or cloud service, use the current-documentation tool required by the project. Prefer the locally installed version and actual runtime results.
|
||
|
|
- When writing functions, classes, or complex logic, use the corresponding documentation-comment format and describe parameters, return values, exceptions, and design rationale.
|
||
|
|
- Comments explain why, not a line-by-line translation of the code. Add prominent warnings beside permission, security, and compatibility boundaries.
|
||
|
|
|
||
|
|
## Version Control
|
||
|
|
|
||
|
|
- Commit, push, and PR actions require an explicit user request, and authorization for one does not imply authorization for another.
|
||
|
|
- Trellis archive and journal commands use command-level `--no-commit`; do not rely on automatic commits.
|
||
|
|
- Commit messages default to `<type>(scope): <Chinese verb phrase>` with no trailing period.
|
||
|
|
- A commit contains only files confirmed to belong to the current task. Do not amend or silently include the user's changes or changes from parallel work.
|
||
|
|
|
||
|
|
## Final Response
|
||
|
|
|
||
|
|
Lead with the conclusion and include only what is needed:
|
||
|
|
|
||
|
|
1. Outcome;
|
||
|
|
2. Key evidence / changed files;
|
||
|
|
3. Verification actually run;
|
||
|
|
4. Remaining risks or blockers;
|
||
|
|
5. Necessary next step.
|
||
|
|
|
||
|
|
Omit a process recap. Any verification that was not run must be marked `not run` or accompanied by the reason it was blocked.
|