mirror of
https://github.com/PR0M3TH3AN/TORCH.git
synced 2026-10-27 07:51:52 +00:00
Consolidate agent docs into TORCH.md and update installer
- Merged AGENTS.md, CLAUDE.md, and src/docs/TORCH.md into a single TORCH.md in the root. - Updated src/ops.mjs to copy TORCH.md during init/update and correctly transform path references. - Updated src/prompts/META_PROMPTS.md and src/prompts/scheduler-flow.md to reference TORCH.md. - Deleted obsolete AGENTS.md, CLAUDE.md, and src/docs/TORCH.md. Co-authored-by: PR0M3TH3AN <[email protected]>
This commit is contained in:
google-labs-jules[bot]andPR0M3TH3AN committed
1 parent
a384548663
commit
8b5cec4890
6 files changed
+138
-229
No files matched your search
@@ -1,112 +0,0 @@
|
||||
# AGENTS.md — Repository-Agnostic Agent Operating Guide
|
||||
|
||||
This file defines how agents should work in this repository **before any project-specific customization exists**.
|
||||
|
||||
## Purpose
|
||||
|
||||
- Keep agent work predictable, auditable, and safe.
|
||||
- Minimize repeated discovery work across sessions.
|
||||
- Capture durable learnings so future agents can move faster.
|
||||
|
||||
## Session startup checklist (run every session)
|
||||
|
||||
1. Read `AGENTS.md`.
|
||||
2. Read `CLAUDE.md` for execution workflow details.
|
||||
3. Read `CONTRIBUTING.md` for commit and PR expectations.
|
||||
4. Read `KNOWN_ISSUES.md` for active blockers and workarounds.
|
||||
5. Read `docs/agent-handoffs/README.md`.
|
||||
6. Scan recent notes in:
|
||||
- `docs/agent-handoffs/learnings/`
|
||||
- `docs/agent-handoffs/incidents/`
|
||||
7. If present, review the current run artifacts in:
|
||||
- `src/context/`
|
||||
- `src/todo/`
|
||||
- `src/decisions/`
|
||||
- `src/test_logs/`
|
||||
- `src/issues/`
|
||||
|
||||
## Core operating principles
|
||||
|
||||
- Default to generic guidance and neutral language.
|
||||
- Make the smallest safe change that satisfies the request.
|
||||
- Avoid unrelated refactors.
|
||||
- Preserve backward compatibility unless explicitly asked otherwise.
|
||||
- Prefer explicit commands and documented behavior over assumptions.
|
||||
- Record assumptions clearly in your final summary.
|
||||
|
||||
## Validation policy
|
||||
|
||||
- Run the most relevant checks for changed files (tests, lint, typecheck, build, or targeted scripts).
|
||||
- Never claim a check passed unless it was actually executed.
|
||||
- If a check cannot run, record:
|
||||
- command attempted,
|
||||
- why it could not complete,
|
||||
- what fallback validation was performed.
|
||||
|
||||
## Knowledge-sharing protocol
|
||||
|
||||
### What belongs where
|
||||
|
||||
- `KNOWN_ISSUES.md`
|
||||
- Active, reproducible issues only.
|
||||
- Include status, impact, workaround, and last verification date.
|
||||
- `docs/agent-handoffs/learnings/`
|
||||
- Proven patterns, repeatable fixes, and successful implementation guidance.
|
||||
- `docs/agent-handoffs/incidents/`
|
||||
- Failures, root causes, mitigations, and prevention guidance.
|
||||
- `src/context/`
|
||||
- Snapshot of current task context (goal, scope, constraints).
|
||||
- `src/todo/`
|
||||
- Actionable checklist for in-progress work.
|
||||
- `src/decisions/`
|
||||
- Key implementation decisions and rationale.
|
||||
- `src/test_logs/`
|
||||
- Commands run and their outcomes.
|
||||
- `src/issues/`
|
||||
- One-off investigative or audit outputs not yet promoted to `KNOWN_ISSUES.md`.
|
||||
|
||||
### Naming standard (generic)
|
||||
|
||||
Use: `YYYY-MM-DD-short-topic.md`
|
||||
|
||||
Examples:
|
||||
|
||||
- `2026-02-14-validation-before-summary.md`
|
||||
- `2026-02-14-missing-baseline-context.md`
|
||||
|
||||
Naming rules:
|
||||
|
||||
- Keep names concise and descriptive.
|
||||
- Avoid company, product, team, customer, and environment names.
|
||||
- Prefer neutral technical terms.
|
||||
|
||||
### Required sections for reusable notes
|
||||
|
||||
Use these headings in learning/incident notes:
|
||||
|
||||
1. Context
|
||||
2. Observation
|
||||
3. Action taken
|
||||
4. Validation performed
|
||||
5. Recommendation for next agents
|
||||
|
||||
### Update decision tree
|
||||
|
||||
When you discover reusable context:
|
||||
|
||||
1. Check if an existing note already covers it.
|
||||
2. If yes, update that note.
|
||||
3. If no, add a new note in `learnings/` or `incidents/`.
|
||||
4. If the issue is still active/reproducible, add or update `KNOWN_ISSUES.md`.
|
||||
|
||||
## Priority order when guidance conflicts
|
||||
|
||||
1. System/developer/user instructions in the active session
|
||||
2. `AGENTS.md`
|
||||
3. `CLAUDE.md`
|
||||
4. `CONTRIBUTING.md`
|
||||
5. Inline code comments and prompt templates
|
||||
|
||||
## Keep this file generic
|
||||
|
||||
Only add project-specific details after they are truly needed and explicitly labeled as repository-specific.
|
||||
@@ -1,108 +0,0 @@
|
||||
# CLAUDE.md — Generic Agent Execution Workflow
|
||||
|
||||
This guide defines an execution flow that works across repositories and tech stacks.
|
||||
|
||||
## Default workflow
|
||||
|
||||
1. **Load baseline context**
|
||||
- `AGENTS.md`
|
||||
- `CONTRIBUTING.md`
|
||||
- `KNOWN_ISSUES.md`
|
||||
- `docs/agent-handoffs/README.md`
|
||||
- Recent notes in `docs/agent-handoffs/learnings/` and `docs/agent-handoffs/incidents/`
|
||||
2. **Clarify the task**
|
||||
- Restate the requested outcome.
|
||||
- Identify constraints, risks, and assumptions.
|
||||
3. **Plan minimal changes**
|
||||
- Keep scope tight.
|
||||
- Avoid touching unrelated files.
|
||||
4. **Implement**
|
||||
- Apply small, reversible edits.
|
||||
- Favor readability and maintainability.
|
||||
5. **Validate**
|
||||
- Run relevant checks for impacted files.
|
||||
- Capture exact commands and outcomes.
|
||||
6. **Document and hand off**
|
||||
- Summarize what changed and why.
|
||||
- Record reusable learnings/incidents when appropriate.
|
||||
|
||||
## Working files for session state
|
||||
|
||||
Use the following folders as lightweight coordination artifacts:
|
||||
|
||||
- `src/context/` — Current objective, scope, constraints.
|
||||
- `src/todo/` — Task checklist and blockers.
|
||||
- `src/decisions/` — Important design/implementation choices.
|
||||
- `src/test_logs/` — Validation commands and results.
|
||||
- `src/issues/` — Investigations or audits that may become tracked issues.
|
||||
|
||||
### Recommended content templates
|
||||
|
||||
#### Context note template
|
||||
|
||||
- Goal
|
||||
- Scope
|
||||
- Constraints
|
||||
- Open questions
|
||||
|
||||
#### Todo note template
|
||||
|
||||
- Pending tasks
|
||||
- Completed tasks
|
||||
- Blocked tasks
|
||||
|
||||
#### Decision note template
|
||||
|
||||
- Decision
|
||||
- Alternatives considered
|
||||
- Rationale
|
||||
- Consequences/follow-ups
|
||||
|
||||
#### Test log template
|
||||
|
||||
- Command
|
||||
- Result (pass/fail/warn)
|
||||
- Notes (environmental limits, retries, artifacts)
|
||||
|
||||
## Knowledge-sharing protocol
|
||||
|
||||
### Where to write durable knowledge
|
||||
|
||||
- `docs/agent-handoffs/learnings/` for reusable successes.
|
||||
- `docs/agent-handoffs/incidents/` for failures and mitigations.
|
||||
- `KNOWN_ISSUES.md` for active, reproducible unresolved issues.
|
||||
|
||||
### File naming
|
||||
|
||||
Use `YYYY-MM-DD-short-topic.md`.
|
||||
|
||||
### Required structure for learning/incident notes
|
||||
|
||||
1. Context
|
||||
2. Observation
|
||||
3. Action taken
|
||||
4. Validation performed
|
||||
5. Recommendation for next agents
|
||||
|
||||
## Quality checklist before completion
|
||||
|
||||
- Scope matches request.
|
||||
- Documentation remains repository-agnostic unless explicitly needed.
|
||||
- No unsupported claims about testing.
|
||||
- Assumptions and limitations are called out.
|
||||
- Changes are easy to revert.
|
||||
|
||||
## Anti-patterns to avoid
|
||||
|
||||
- Embedding product/company-specific guidance in baseline docs.
|
||||
- Large refactors when a focused change is sufficient.
|
||||
- Skipping validation without recording why.
|
||||
- Creating duplicate notes when an update would suffice.
|
||||
|
||||
## Customization policy
|
||||
|
||||
This file should stay generic until real repository-specific patterns emerge. When customizing:
|
||||
|
||||
- Add a clearly labeled section: `Repository-specific overrides`.
|
||||
- Keep generic workflow unchanged.
|
||||
- Include evidence (commands, failures, repeated incidents) for each override.
|
||||
@@ -1,6 +1,135 @@
|
||||
# TORCH: Task Orchestration via Relay-Coordinated Handoff
|
||||
|
||||
TORCH is a decentralized task-locking protocol for multi-agent software development.
|
||||
TORCH is a decentralized task-locking protocol for multi-agent software development. This document serves as the primary manual for both human operators and AI agents working within a TORCH-enabled repository.
|
||||
|
||||
---
|
||||
|
||||
## Agent Operating Guide
|
||||
|
||||
This section defines how agents should work in this repository.
|
||||
|
||||
### Purpose
|
||||
|
||||
- Keep agent work predictable, auditable, and safe.
|
||||
- Minimize repeated discovery work across sessions.
|
||||
- Capture durable learnings so future agents can move faster.
|
||||
|
||||
### Session startup checklist (run every session)
|
||||
|
||||
1. **Read `TORCH.md`** (this file).
|
||||
2. Read `CONTRIBUTING.md` for commit and PR expectations.
|
||||
3. Read `KNOWN_ISSUES.md` for active blockers and workarounds.
|
||||
4. Read `docs/agent-handoffs/README.md`.
|
||||
5. Scan recent notes in:
|
||||
- `docs/agent-handoffs/learnings/`
|
||||
- `docs/agent-handoffs/incidents/`
|
||||
6. If present, review the current run artifacts in:
|
||||
- `src/context/`
|
||||
- `src/todo/`
|
||||
- `src/decisions/`
|
||||
- `src/test_logs/`
|
||||
- `src/issues/`
|
||||
|
||||
### Core operating principles
|
||||
|
||||
- Default to generic guidance and neutral language.
|
||||
- Make the smallest safe change that satisfies the request.
|
||||
- Avoid unrelated refactors.
|
||||
- Preserve backward compatibility unless explicitly asked otherwise.
|
||||
- Prefer explicit commands and documented behavior over assumptions.
|
||||
- Record assumptions clearly in your final summary.
|
||||
|
||||
### Validation policy
|
||||
|
||||
- Run the most relevant checks for changed files (tests, lint, typecheck, build, or targeted scripts).
|
||||
- Never claim a check passed unless it was actually executed.
|
||||
- If a check cannot run, record:
|
||||
- command attempted,
|
||||
- why it could not complete,
|
||||
- what fallback validation was performed.
|
||||
|
||||
### Execution Workflow
|
||||
|
||||
1. **Load baseline context** (see Session startup checklist above).
|
||||
2. **Clarify the task**
|
||||
- Restate the requested outcome.
|
||||
- Identify constraints, risks, and assumptions.
|
||||
3. **Plan minimal changes**
|
||||
- Keep scope tight.
|
||||
- Avoid touching unrelated files.
|
||||
4. **Implement**
|
||||
- Apply small, reversible edits.
|
||||
- Favor readability and maintainability.
|
||||
5. **Validate**
|
||||
- Run relevant checks for impacted files.
|
||||
- Capture exact commands and outcomes.
|
||||
6. **Document and hand off**
|
||||
- Summarize what changed and why.
|
||||
- Record reusable learnings/incidents when appropriate.
|
||||
|
||||
### Working files for session state
|
||||
|
||||
Use the following folders as lightweight coordination artifacts:
|
||||
|
||||
- `src/context/` — Current objective, scope, constraints.
|
||||
- `src/todo/` — Task checklist and blockers.
|
||||
- `src/decisions/` — Important design/implementation choices.
|
||||
- `src/test_logs/` — Validation commands and results.
|
||||
- `src/issues/` — Investigations or audits that may become tracked issues.
|
||||
|
||||
#### Content templates
|
||||
|
||||
**Context note:** Goal, Scope, Constraints, Open questions.
|
||||
**Todo note:** Pending tasks, Completed tasks, Blocked tasks.
|
||||
**Decision note:** Decision, Alternatives considered, Rationale, Consequences/follow-ups.
|
||||
**Test log:** Command, Result (pass/fail/warn), Notes (environmental limits, retries, artifacts).
|
||||
|
||||
### Knowledge-sharing protocol
|
||||
|
||||
#### What belongs where
|
||||
|
||||
- `KNOWN_ISSUES.md`: Active, reproducible issues only. Include status, impact, workaround, and last verification date.
|
||||
- `docs/agent-handoffs/learnings/`: Proven patterns, repeatable fixes, and successful implementation guidance.
|
||||
- `docs/agent-handoffs/incidents/`: Failures, root causes, mitigations, and prevention guidance.
|
||||
- `src/context/`, `src/todo/`, etc.: Ephemeral session state.
|
||||
|
||||
#### Naming standard
|
||||
|
||||
Use: `YYYY-MM-DD-short-topic.md` (e.g., `2026-02-14-validation-before-summary.md`).
|
||||
Keep names concise, descriptive, and neutral.
|
||||
|
||||
#### Required sections for reusable notes
|
||||
|
||||
1. Context
|
||||
2. Observation
|
||||
3. Action taken
|
||||
4. Validation performed
|
||||
5. Recommendation for next agents
|
||||
|
||||
#### Update decision tree
|
||||
|
||||
When you discover reusable context:
|
||||
1. Check if an existing note already covers it.
|
||||
2. If yes, update that note.
|
||||
3. If no, add a new note in `learnings/` or `incidents/`.
|
||||
4. If the issue is still active/reproducible, add or update `KNOWN_ISSUES.md`.
|
||||
|
||||
### Quality checklist before completion
|
||||
|
||||
- Scope matches request.
|
||||
- Documentation remains repository-agnostic unless explicitly needed.
|
||||
- No unsupported claims about testing.
|
||||
- Assumptions and limitations are called out.
|
||||
- Changes are easy to revert.
|
||||
|
||||
### Anti-patterns to avoid
|
||||
|
||||
- Embedding product/company-specific guidance in baseline docs.
|
||||
- Large refactors when a focused change is sufficient.
|
||||
- Skipping validation without recording why.
|
||||
- Creating duplicate notes when an update would suffice.
|
||||
|
||||
---
|
||||
|
||||
## Dashboard & Protocol Overview
|
||||
|
||||
+3
-2
@@ -24,7 +24,7 @@ const EVOLVING_DIRS = ['daily', 'weekly'];
|
||||
|
||||
// New constants for full application install
|
||||
const APP_DIRS = ['src', 'bin', 'dashboard', 'landing', 'assets', 'scripts'];
|
||||
const APP_FILES = ['package.json', 'build.mjs', 'README.md', 'torch-config.example.json'];
|
||||
const APP_FILES = ['package.json', 'build.mjs', 'README.md', 'torch-config.example.json', 'TORCH.md'];
|
||||
|
||||
function getPaths(root, installDirName) {
|
||||
const torchDir = path.resolve(root, installDirName);
|
||||
@@ -65,7 +65,8 @@ function transformContent(content, installDirName) {
|
||||
.replace(/src\/prompts\/daily\//g, `${prefix}prompts/daily/`)
|
||||
.replace(/src\/prompts\/weekly\//g, `${prefix}prompts/weekly/`)
|
||||
.replace(/src\/prompts\/roster\.json/g, `${prefix}roster.json`)
|
||||
.replace(/src\/prompts\/scheduler-flow\.md/g, `${prefix}scheduler-flow.md`);
|
||||
.replace(/src\/prompts\/scheduler-flow\.md/g, `${prefix}scheduler-flow.md`)
|
||||
.replace(/TORCH\.md/g, `${prefix}TORCH.md`);
|
||||
}
|
||||
|
||||
function copyFile(src, dest, transform = false, overwrite = true, installDirName = 'torch') {
|
||||
|
||||
@@ -27,7 +27,7 @@ Use `excluded` from the JSON output as the canonical exclusion set.
|
||||
If `excluded` is unavailable, fallback to the union of `locked`, `paused`, and `completed`.
|
||||
|
||||
MUST 3: Run these commands in this order:
|
||||
1) test -f AGENTS.md && cat AGENTS.md || echo "No AGENTS.md found; continuing" (missing AGENTS.md is non-fatal)
|
||||
1) test -f TORCH.md && cat TORCH.md || echo "No TORCH.md found; continuing" (missing TORCH.md is non-fatal)
|
||||
2) mkdir -p task-logs/daily task-logs/weekly
|
||||
3) ls -1 task-logs/daily/ | sort | tail -n 1
|
||||
4) Select next roster agent using this exact algorithm:
|
||||
@@ -111,7 +111,7 @@ Use `excluded` from the JSON output as the canonical exclusion set.
|
||||
If `excluded` is unavailable, fallback to the union of `locked`, `paused`, and `completed`.
|
||||
|
||||
MUST 3: Run these commands in this order:
|
||||
1) test -f AGENTS.md && cat AGENTS.md || echo "No AGENTS.md found; continuing" (missing AGENTS.md is non-fatal)
|
||||
1) test -f TORCH.md && cat TORCH.md || echo "No TORCH.md found; continuing" (missing TORCH.md is non-fatal)
|
||||
2) mkdir -p task-logs/daily task-logs/weekly
|
||||
3) ls -1 task-logs/weekly/ | sort | tail -n 1
|
||||
4) Select next roster agent using this exact algorithm:
|
||||
|
||||
@@ -20,8 +20,7 @@ Prompt authors: do not use legacy unprefixed paths (`context/`, `todo/`, `decisi
|
||||
Every agent prompt invoked by the schedulers (daily/weekly) MUST enforce this contract:
|
||||
|
||||
1. **Read baseline policy files before implementation**:
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `TORCH.md`
|
||||
- `KNOWN_ISSUES.md`
|
||||
- Canonical path note: active issues are tracked in root `KNOWN_ISSUES.md` (not `docs/KNOWN_ISSUES.md`)
|
||||
- `docs/agent-handoffs/README.md`
|
||||
@@ -68,10 +67,10 @@ Every agent prompt invoked by the schedulers (daily/weekly) MUST enforce this co
|
||||
|
||||
Goose Desktop note: `npm run lock:check:<cadence>` can emit large hermit wrapper logs. Use `--json --quiet` (as documented above). If the command still fails due to Goose hermit issues, apply the PATH workaround in `KNOWN_ISSUES.md` before rerunning.
|
||||
|
||||
3. Read policy file(s) once before the run loop. This step is conditional: if `AGENTS.md` is missing, continue without failing.
|
||||
3. Read policy file(s) once before the run loop. This step is conditional: if `TORCH.md` is missing, continue without failing.
|
||||
|
||||
```bash
|
||||
test -f AGENTS.md && cat AGENTS.md || echo "No AGENTS.md found; continuing"
|
||||
test -f TORCH.md && cat TORCH.md || echo "No TORCH.md found; continuing"
|
||||
```
|
||||
|
||||
4. Bootstrap log directories before listing files:
|
||||
|
||||
Reference in new issue
Block a user