diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 10b8c80..0000000 --- a/AGENTS.md +++ /dev/null @@ -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. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 78be0ca..0000000 --- a/CLAUDE.md +++ /dev/null @@ -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. diff --git a/src/docs/TORCH.md b/TORCH.md similarity index 68% rename from src/docs/TORCH.md rename to TORCH.md index e26da11..6058b51 100644 --- a/src/docs/TORCH.md +++ b/TORCH.md @@ -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 diff --git a/src/ops.mjs b/src/ops.mjs index 657a09d..5cae20c 100644 --- a/src/ops.mjs +++ b/src/ops.mjs @@ -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') { diff --git a/src/prompts/META_PROMPTS.md b/src/prompts/META_PROMPTS.md index 3dd3070..5e4f39b 100644 --- a/src/prompts/META_PROMPTS.md +++ b/src/prompts/META_PROMPTS.md @@ -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: diff --git a/src/prompts/scheduler-flow.md b/src/prompts/scheduler-flow.md index 56f48e2..47abf08 100644 --- a/src/prompts/scheduler-flow.md +++ b/src/prompts/scheduler-flow.md @@ -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:` 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: