thePR0M3TH3AN/TORCH
1
0 Fork 0
mirror of https://github.com/PR0M3TH3AN/TORCH.git synced 2026-10-27 07:51:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor AGENTS and CLAUDE for repo-agnostic guidance

Browse Source
This commit is contained in:
thePR0M3TH3AN committed 2026-02-13 22:25:12 -05:00
1 parent 9aae831977
commit bb55f37fe1
2 files changed
+88 -76
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CLAUDE.md
+43 -29
View File
@@ -1,52 +1,66 @@
# CLAUDE.md
Operational playbook for agent execution in this repository.
Execution playbook for agents working in this repository.
## Scope
Applies to all agent tasks unless superseded by direct runtime instructions.
Applies to all tasks unless overridden by direct session instructions.
## Operating model
## Core operating principles
- Keep output and changes generic by default.
- Prefer deterministic, auditable steps.
- Record useful decisions so future agents can continue with minimal rediscovery.
- Be repository-agnostic by default.
- Keep behavior deterministic and auditable.
- Prefer minimal, reversible changes.
- Leave the workspace clearer for the next agent than you found it.
## Execution flow (recommended)
## Recommended execution workflow
1. Read policy files listed in `AGENTS.md` startup checklist.
2. Review current known issues and recent handoff notes.
3. Implement the smallest safe change.
4. Validate with relevant checks/tests.
5. Update shared docs (`KNOWN_ISSUES.md` and/or handoff notes) when new reusable knowledge appears.
1. Load baseline context from `AGENTS.md`, `CONTRIBUTING.md`, `KNOWN_ISSUES.md`, and handoff notes.
2. Restate the task internally as concrete outcomes.
3. Make the smallest safe implementation change.
4. Validate with the most relevant automated checks available.
5. Summarize results with clear evidence (commands, outputs, and file references).
6. Record durable learnings/incidents if new reusable knowledge was discovered.
## Handoff documentation workflow
## Change quality checklist
When you learn something that can help future agents:
Before finishing, verify:
1. Check for related notes in:
- The change is scoped to the request.
- Naming and docs remain generic unless project-specific behavior is explicitly required.
- Existing workflows are not silently broken.
- Validation matches the risk level of the change.
## Handoff and documentation expectations
When new reusable context appears:
1. Search for an existing related note in:
- `docs/agent-handoffs/learnings/`
- `docs/agent-handoffs/incidents/`
2. If the insight is new, add a short markdown note using the naming standard from `AGENTS.md`.
3. If the issue is still active/reproducible, add or update the corresponding entry in `KNOWN_ISSUES.md`.
4. Keep note content sanitized and reusable (no secrets, no user-identifying details).
2. Update existing notes if they already cover the issue.
3. Otherwise add a new note using `YYYY-MM-DD-short-topic.md`.
4. If the issue is still active/reproducible, add or update `KNOWN_ISSUES.md`.
Keep notes concise, actionable, and safe to share.
## What belongs where
- `KNOWN_ISSUES.md`: active/reproducible issues, impact, workaround, and current status.
- `docs/agent-handoffs/learnings/`: durable implementation insights and successful patterns.
- `docs/agent-handoffs/incidents/`: failure writeups, root causes, and prevention guidance.
- `CONTRIBUTING.md`: standards for proposing, validating, and reviewing changes.
- `KNOWN_ISSUES.md`: active issues, impact, status, workaround, verification date.
- `docs/agent-handoffs/learnings/`: successful implementation patterns.
- `docs/agent-handoffs/incidents/`: failures and prevention guidance.
- `CONTRIBUTING.md`: contribution, review, and quality standards.
## Style for handoff notes
## Writing style for handoff notes
- Prefer bullets over long prose.
- Include exact commands where useful.
- State confidence and remaining uncertainty.
- Include exact commands when they improve reproducibility.
- Explicitly separate facts from assumptions.
- End with: `Recommendation for next agents:`
## Anti-patterns
## Anti-patterns to avoid
- Avoid repo-local jargon in reusable templates.
- Avoid stale TODO dumps without context.
- Avoid project/brand-specific terms unless explicitly required by the active downstream repo.
- Product/brand-specific assumptions in reusable docs.
- Broad refactors not required for the current request.
- Status updates without validation evidence.
- Duplicated notes that fragment context.