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

feat(agents): add plan-agent pipeline to close idea-to-implementation gap

Browse Source 
Introduces three new weekly agents that form a triage→plan→build pipeline:

- proposal-triage-agent: evaluates proposals, dead ends, and coverage gaps;
  produces prioritized backlog in src/backlog/BACKLOG.md
- plan-agent: creates concrete implementation plans from top backlog items
  in src/plans/PLAN-*.md
- builder-agent: executes approved plans, makes code changes, verifies
  acceptance criteria

Also includes:
- Architecture proposal document in docs/proposals/
- Seeded initial backlog with 11 items from diagnosed dead ends
- Updated roster.json and weekly-scheduler.md (24 weekly agents)
- All three validators pass (prompt-contract, scheduler-roster, flow-parity)

https://claude.ai/code/session_01FLP7ibXd5QPG517g1kYCHL
This commit is contained in:
Claude committed 2026-02-21 20:13:35 +00:00
1 parent 3d788c58a7
commit 33ea996b04
7 files changed
+1050 -20
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/proposals/plan-agent-architecture.md
+542
View File
@@ -0,0 +1,542 @@
# Proposal: Plan Agent Architecture — Closing the Idea-to-Implementation Gap
## Problem Statement
TORCH has **44 agents** generating proposals, audits, and feature ideas — but **zero agents** that evaluate those proposals, plan implementation strategies, or build approved features. The result is a growing pile of dead ends:
### Diagnosed Dead Ends (Current State)
| Dead End | Type | Why It's Stuck |
|----------|------|----------------|
| Node-based prompt editor | Proposal | 306-line design doc, zero implementation, no champion |
| Prompt packages system | Proposal | Concept doc only, never prioritized into work |
| Hybrid distribution (binary + dashboard) | Proposal | Architecture written, zero progress |
| `event-schema-agent` | Broken agent | References `src/lib/eventSchemas.js` which doesn't exist — failed 2x, never fixed |
| `content-audit-agent` | Scope mismatch | Audits upload/contribution features that don't exist in TORCH |
| `style-agent` | Missing tooling | Blocked on missing `npm run format` script — never added |
| 7 proposed agents in `AGENT_COVERAGE_GAPS.md` | Coverage gaps | Documented but no agent builds new agents |
| 77 scattered TODO files | Organizational debt | Created daily, never consolidated or triaged |
| 130+ dead artifacts | Audit fatigue | Reports generated continuously, never acted upon |
### Root Cause: Missing Pipeline Stages
The current pipeline has a structural gap. Ideas flow in but never flow through to completion:
```
CURRENT PIPELINE (broken feedback loop)
feature-proposer-agent ──→ creates single file in features/
prompt-gap-analysis-agent ──→ identifies gaps, writes report
weekly-synthesis-agent ──→ summarizes activity
governance-agent ──→ applies/rejects prompt changes
┌─────────────────────────────────────────────────┐
│ MISSING: Who evaluates proposals? │
│ MISSING: Who plans implementation strategy? │
│ MISSING: Who builds multi-file features? │
│ MISSING: Who retires dead-end work? │
│ MISSING: Who closes the loop on artifacts? │
└─────────────────────────────────────────────────┘
```
The `feature-proposer-agent` creates single-file features in `features/`. It explicitly cannot modify existing files or execute multi-step implementations. The `governance-agent` handles prompt changes but not feature development. Nobody triages the 3 stalled proposals, 7 unimplemented agent gaps, or 15 failed task logs.
---
## Proposed Solution: Three New Pipeline Agents
Add three new weekly agents that close the gap between "idea" and "implementation":
```
PROPOSED PIPELINE (closed loop)
IDEAS IN BUILT OUT
───────── ─────────
feature-proposer-agent ─┐
prompt-gap-analysis-agent ─┤
docs/proposals/*.md ──────┤
AGENT_COVERAGE_GAPS.md ───┤
KNOWN_ISSUES.md ──────────┤
artifacts/ reports ───────┘
│
┌───────▼────────┐
│ proposal- │ TRIAGE: Evaluates all pending
│ triage-agent │ proposals, dead ends, and gaps.
│ │ Produces prioritized backlog.
└───────┬────────┘
│
┌───────▼────────┐
│ plan-agent │ PLAN: Takes top-priority item
│ │ from backlog. Produces step-by-step
│ │ implementation plan with file list,
│ │ test strategy, and acceptance criteria.
└───────┬────────┘
│
┌───────▼────────┐
│ builder-agent │ BUILD: Executes approved plan.
│ │ Creates/modifies files, writes tests,
│ │ validates against acceptance criteria.
└────────────────┘
```
### Why Three Agents, Not One?
A single "do everything" agent would violate TORCH's core design principles:
1. **Single responsibility** — Each agent has one job, one prompt, one failure mode
2. **Round-robin fairness** — Three separate agents get three separate time slots; a monolithic agent would monopolize an entire weekly slot
3. **Incremental progress** — Triage can run without planning; planning can run without building; each produces value independently
4. **Auditable handoffs** — Each stage produces artifacts that the next stage consumes, creating a reviewable paper trail
5. **Failure isolation** — If the builder fails, the plan still exists for the next cycle; if triage fails, existing plans aren't affected
---
## Agent 1: `proposal-triage-agent` (Weekly)
### Identity
> You are: **proposal-triage-agent**, a weekly agent that evaluates pending proposals, identifies dead ends, and produces a prioritized implementation backlog.
### Mission
Synthesize all pending work items (proposals, coverage gaps, dead-end agents, stale artifacts) into a single prioritized backlog file that downstream agents can consume.
### Inputs (Read)
| Source | What to Extract |
|--------|----------------|
| `docs/proposals/*.md` | Active proposals and their implementation status |
| `docs/AGENT_COVERAGE_GAPS.md` | Proposed but unimplemented agents |
| `KNOWN_ISSUES.md` | Blocking issues that need tooling fixes |
| `task-logs/daily/` + `task-logs/weekly/` | Failed agent runs (pattern detection) |
| `artifacts/` | Reports that haven't driven action |
| `src/todo/` | Scattered TODO files needing consolidation |
| `features/` | Single-file features from `feature-proposer-agent` |
| `docs/agent-handoffs/incidents/` | Unresolved incidents |
| Previous backlog (`src/backlog/BACKLOG.md`) | Carry forward items not yet addressed |
### Output (Write)
**Primary artifact:** `src/backlog/BACKLOG.md`
```markdown
# Implementation Backlog — <YYYY-MM-DD>
## Triage Summary
- Items evaluated: <N>
- New items added: <N>
- Items retired (dead end): <N>
- Items promoted to ready: <N>
## Priority 1: Ready to Plan
<!-- Items with clear scope, no blockers, high value -->
### BACKLOG-001: Add `npm run format` script to package.json
- **Source:** KNOWN_ISSUES.md, style-agent failures
- **Impact:** Unblocks style-agent (daily cadence)
- **Scope:** Single line in package.json
- **Status:** ready-to-plan
- **Acceptance:** `npm run format` exits 0; style-agent completes successfully
### BACKLOG-002: Create `src/lib/eventSchemas.js`
- **Source:** event-schema-agent failures (2x)
- **Impact:** Unblocks event-schema-agent (weekly cadence)
- **Scope:** Extract event builders from `src/nostr-lock.mjs` into shared module
- **Status:** ready-to-plan
- **Acceptance:** event-schema-agent completes; `src/nostr-lock.mjs` imports from new module
## Priority 2: Needs Scoping
<!-- Items with clear value but unclear implementation -->
### BACKLOG-003: Implement Phase 0 of prompt graph extraction
- **Source:** docs/proposals/node-based-prompt-editor.md
- **Impact:** Machine-readable agent metadata for all 44 prompts
- **Scope:** 4 new scripts in `scripts/prompt-graph/`
- **Status:** needs-scoping
- **Blockers:** None
- **Open Questions:** Regex patterns may not cover all prompt variations
## Priority 3: Deferred
<!-- Items with value but dependencies or low urgency -->
## Retired (Dead Ends)
<!-- Items explicitly marked as not worth pursuing, with rationale -->
### RETIRED: content-audit-agent upload/contribution scope
- **Rationale:** TORCH has no upload UI, API, or storage. Agent audits features
that don't exist. Recommend revising agent scope instead of building features.
```
### Triage Criteria
Items are scored on four dimensions:
| Dimension | Weight | Scoring |
|-----------|--------|---------|
| **Unblock** | 3x | Does this unblock a currently-broken agent or workflow? |
| **Value** | 2x | Does this deliver user-visible value or reduce failure rate? |
| **Scope** | 1x | Is the implementation scope clear and bounded? |
| **Risk** | -1x | Does this require architectural changes or new dependencies? |
### Retirement Rules
An item should be retired (not deferred) when:
- The feature it depends on doesn't exist and isn't planned (e.g., content-audit-agent auditing upload features)
- The proposal has been superseded by a different approach
- The cost clearly exceeds the benefit with no path to improvement
- The item has been deferred for 4+ consecutive triage cycles with no progress
### Weekly Workflow
1. Read all inputs listed above
2. Read previous `src/backlog/BACKLOG.md` if it exists
3. Evaluate each pending item against triage criteria
4. Score and rank items
5. Write updated `src/backlog/BACKLOG.md`
6. Write triage summary to `src/decisions/DECISIONS_<timestamp>.md`
---
## Agent 2: `plan-agent` (Weekly)
### Identity
> You are: **plan-agent**, a weekly agent that creates detailed implementation plans for the highest-priority backlog item.
### Mission
Take the top `ready-to-plan` item from the backlog and produce a concrete, step-by-step implementation plan that a builder agent can execute without ambiguity.
### Inputs (Read)
| Source | What to Extract |
|--------|----------------|
| `src/backlog/BACKLOG.md` | Top `ready-to-plan` item |
| Original proposal/source doc | Full context for the item |
| Relevant codebase files | Current implementation to understand integration points |
| `KNOWN_ISSUES.md` | Active blockers that might affect the plan |
| `docs/agent-handoffs/learnings/` | Past learnings relevant to this work |
| Previous plans (`src/plans/`) | Avoid re-planning already-planned items |
### Output (Write)
**Primary artifact:** `src/plans/PLAN-<backlog-id>.md`
```markdown
# Implementation Plan: BACKLOG-001 — Add `npm run format` script
## Backlog Reference
- **ID:** BACKLOG-001
- **Source:** KNOWN_ISSUES.md, style-agent failures
- **Priority:** P1 (unblocks daily agent)
## Objective
Add a working `npm run format` script to `package.json` that the
`style-agent` can invoke to auto-format code.
## Analysis
- `style-agent` prompt references `npm run format` at line 12
- `package.json` has `prettier` in devDependencies (v3.2.x)
- `.prettierrc` exists with project configuration
- No existing format script; only `lint` exists
## Implementation Steps
### Step 1: Add format script to package.json
- **File:** `package.json`
- **Change:** Add `"format": "prettier --write ."` to `scripts` object
- **Test:** `npm run format` exits 0 without errors
### Step 2: Add format check script (CI-friendly)
- **File:** `package.json`
- **Change:** Add `"format:check": "prettier --check ."` to `scripts` object
- **Test:** `npm run format:check` exits 0 after formatting
### Step 3: Validate style-agent can complete
- **Action:** Verify `style-agent` prompt references match available scripts
- **Test:** Dry-run style-agent workflow mentally against available npm scripts
## Files Modified
- `package.json` (2 lines added to `scripts`)
## Files Created
- None
## Acceptance Criteria
1. `npm run format` exits 0 and formats `.js` / `.mjs` files per `.prettierrc`
2. `npm run format:check` exits 0 after running `npm run format`
3. `style-agent` prompt commands all resolve to valid npm scripts
4. No existing tests break
## Test Strategy
- Run `npm run format` and verify exit code
- Run `npm run format:check` and verify exit code
- Run `npm test` to verify no regressions
- Run `npm run lint` to verify compatibility
## Risk Assessment
- **Low risk:** Adding scripts to package.json is additive
- **No architectural changes required**
- **Rollback:** Remove the two script lines
## Dependencies
- None — self-contained change
## Estimated Complexity
- **Simple** (< 5 file changes, no new modules)
```
### Planning Rules
1. **One plan per cycle** — Don't try to plan everything. Pick the single highest-priority `ready-to-plan` item
2. **Concrete file paths** — Every step must name the exact file(s) to create or modify
3. **Testable acceptance** — Every acceptance criterion must be verifiable by running a command
4. **No ambiguity** — A builder agent reading only this plan should be able to implement it without guessing
5. **Scope guard** — If the item is too large for a single builder cycle, break it into sub-plans and update the backlog
### Status Updates
After planning, update the backlog item's status:
```
- **Status:** ready-to-plan → planned (see src/plans/PLAN-BACKLOG-001.md)
```
### Weekly Workflow
1. Read `src/backlog/BACKLOG.md`
2. Select top `ready-to-plan` item
3. If no items are `ready-to-plan`, check for `needs-scoping` items and attempt to scope them (update status to `ready-to-plan` if successful)
4. Read all referenced source documents and relevant codebase files
5. Write implementation plan to `src/plans/PLAN-<backlog-id>.md`
6. Update backlog item status to `planned`
7. Write planning rationale to `src/decisions/DECISIONS_<timestamp>.md`
---
## Agent 3: `builder-agent` (Weekly)
### Identity
> You are: **builder-agent**, a weekly agent that implements the oldest approved plan from the plans directory.
### Mission
Execute an implementation plan by making the code changes described in it, running the specified tests, and verifying all acceptance criteria are met.
### Inputs (Read)
| Source | What to Extract |
|--------|----------------|
| `src/plans/PLAN-*.md` | Oldest plan with status `planned` (not `completed` or `in-progress`) |
| All files referenced in the plan | Current state of code to be modified |
| `KNOWN_ISSUES.md` | Active blockers that might affect implementation |
| `src/backlog/BACKLOG.md` | Context for the work item |
### Implementation Protocol
1. **Claim the plan** — Add frontmatter `status: in-progress` and `started: <timestamp>` to the plan file
2. **Execute steps sequentially** — Follow the plan's implementation steps in order
3. **Validate after each step** — Run the step's test command if specified
4. **Run acceptance criteria** — Execute every acceptance criterion command
5. **Update plan status** — Set `status: completed` with `completed: <timestamp>` if all criteria pass
6. **Update backlog** — Set backlog item status to `completed`
7. **Handle failures** — If any acceptance criterion fails:
- Set plan status to `blocked` with `blocked_reason`
- Do NOT mark backlog item as completed
- Document the failure in `KNOWN_ISSUES.md` if it's a new issue
- Write incident note to `docs/agent-handoffs/incidents/`
### Output (Write)
- Modified/created files per the plan
- Updated plan file (status, timestamps)
- Updated backlog (item status)
- Test log in `src/test_logs/TEST_LOG_<timestamp>.md`
### Builder Rules
1. **Follow the plan exactly** — Don't improvise. If the plan says "add line X to file Y", do that
2. **Don't expand scope** — Only make changes listed in the plan. No bonus refactors, no "while I'm here" improvements
3. **Fail loudly** — If a step can't be completed, stop and document why. Don't skip steps
4. **Test everything** — Run every test command in the plan. Run `npm test` and `npm run lint` as final validation
5. **One plan per cycle** — Complete one plan fully before starting another
### Conflict with `feature-proposer-agent`
The existing `feature-proposer-agent` creates single-file features in `features/`. The `builder-agent` executes multi-step plans that may modify existing files. These agents have different scopes:
| Aspect | feature-proposer-agent | builder-agent |
|--------|----------------------|---------------|
| Scope | Single new file in `features/` | Any files specified in plan |
| Input | Own analysis of codebase | Explicit plan from `plan-agent` |
| Modifications | New files only | New + existing files |
| Validation | Self-verified | Acceptance criteria from plan |
| Autonomy | High (chooses what to build) | Low (follows plan exactly) |
Both agents should continue to exist. The `feature-proposer-agent` handles quick, self-contained additions. The `builder-agent` handles planned, multi-step implementations.
---
## Integration with Existing Pipeline
### Roster Changes
Add to `src/prompts/roster.json` under `weekly`:
```json
{
"weekly": [
"bug-reproducer-agent",
"builder-agent",
"changelog-agent",
"dead-code-agent",
"feature-proposer-agent",
"frontend-console-debug-agent",
"fuzz-agent",
"perf-deepdive-agent",
"perf-optimization-agent",
"plan-agent",
"pr-review-agent",
"prompt-fixer-agent",
"prompt-gap-analysis-agent",
"prompt-maintenance-agent",
"prompt-safety-agent",
"proposal-triage-agent",
"race-condition-agent",
"refactor-agent",
"repo-fit-agent",
"smoke-agent",
"telemetry-agent",
"test-coverage-agent",
"ui-ux-agent",
"weekly-synthesis-agent"
]
}
```
### New Directories
```
src/backlog/ # Prioritized implementation backlog (from proposal-triage-agent)
src/plans/ # Implementation plans (from plan-agent)
```
### New Prompt Files
```
src/prompts/weekly/proposal-triage-agent.md
src/prompts/weekly/plan-agent.md
src/prompts/weekly/builder-agent.md
```
### Execution Order Consideration
In the current round-robin, these agents run in alphabetical order within the weekly cadence. The ideal execution order is:
1. `proposal-triage-agent` (produces backlog)
2. `plan-agent` (consumes backlog, produces plan)
3. `builder-agent` (consumes plan, produces implementation)
Since round-robin is alphabetical (`builder-agent` < `plan-agent` < `proposal-triage-agent`), the builder would run *before* the planner in any given week. This is acceptable because:
- Plans persist across weeks — a plan written in week N is built in week N+1
- The pipeline is designed for multi-week cadence, not single-week completion
- Each agent checks for existing artifacts from previous cycles
If same-week execution is desired in the future, the Phase 3+ custom flow configurations from the prompt editor proposal would enable DAG-based ordering.
### Interaction with Existing Agents
| Existing Agent | Interaction |
|---------------|-------------|
| `feature-proposer-agent` | Features it creates may be evaluated by `proposal-triage-agent` |
| `prompt-gap-analysis-agent` | Gap reports feed into `proposal-triage-agent` inputs |
| `weekly-synthesis-agent` | Summarizes triage/plan/build activity in weekly report |
| `governance-agent` | Prompt changes from builder go through normal governance |
| `prompt-maintenance-agent` | Validates new agent prompts follow contract |
| `dead-code-agent` | May identify retired items for triage to confirm |
---
## Addressing the Identified Dead Ends
Here's how the new pipeline would handle each current dead end:
| Dead End | Agent | Action |
|----------|-------|--------|
| Missing `npm run format` | triage → plan → builder | P1: triage identifies, plan writes 2-line change, builder implements |
| Missing `eventSchemas.js` | triage → plan → builder | P1: triage identifies, plan designs extraction, builder creates module |
| content-audit-agent scope | triage | Retired: agent audits nonexistent features |
| Prompt editor Phase 0 | triage → plan | Scoped: triage breaks into sub-tasks, plan designs Phase 0 extraction |
| Prompt packages | triage → plan | Deferred or scoped depending on priority vs. other items |
| Distribution binary | triage | Deferred: requires external tooling, low relative priority |
| 7 coverage gap agents | triage → plan → builder | Each gap becomes a backlog item; plan designs prompt, builder creates it |
| 77 scattered TODOs | triage | Consolidated into backlog; triage replaces scattered TODO creation |
| 130+ dead artifacts | triage | Evaluated for actionability; non-actionable artifacts flagged for GC |
---
## Success Metrics
| Metric | Current | Target (4 weeks) | Target (8 weeks) |
|--------|---------|-------------------|-------------------|
| Stalled proposals | 3 | 2 (1 retired, 1 planned) | 0 (all planned or retired) |
| Broken agents | 3 (event-schema, style, content-audit) | 1 (content-audit retired) | 0 |
| Unimplemented coverage gaps | 7 | 5 (2 planned) | 3 (2 built, 2 planned) |
| Backlog items with clear status | 0 | 10+ | 15+ |
| Plans executed per month | 0 | 2 | 4 |
---
## Implementation Plan for This Proposal
This proposal itself should go through the pipeline it describes. Bootstrap order:
### Step 1: Create directories
```bash
mkdir -p src/backlog src/plans
```
### Step 2: Create `proposal-triage-agent.md`
- Write prompt following shared agent run contract
- Add to `roster.json` weekly array
### Step 3: Create `plan-agent.md`
- Write prompt following shared agent run contract
- Add to `roster.json` weekly array
### Step 4: Create `builder-agent.md`
- Write prompt following shared agent run contract
- Add to `roster.json` weekly array
### Step 5: Seed initial backlog
- Create `src/backlog/BACKLOG.md` with known dead ends pre-triaged
- This gives the plan-agent something to work with on its first run
### Step 6: Validate
- Run `node scripts/validate-prompt-contract.mjs`
- Run `node scripts/validate-scheduler-roster.mjs`
- Run `npm run lint`
- Run `npm test`
---
## Risks
| Risk | Severity | Mitigation |
|------|----------|------------|
| Builder agent makes incorrect changes | High | Plan must have testable acceptance criteria; builder runs all tests |
| Triage agent deprioritizes important work | Medium | Triage criteria are explicit and weighted; human can override backlog |
| Plan scope creep | Medium | Planning rules enforce one plan per cycle, concrete file paths |
| Agents produce circular work (triage creates items that triage later retires) | Low | Retirement rules require 4+ deferred cycles before retirement |
| Builder conflicts with other agents modifying same files | Medium | Lock system prevents concurrent modification; plan specifies exact files |
---
## Relationship to Other Proposals
- **Prompt Editor (Phase 0):** The triage agent would evaluate this proposal and potentially break Phase 0 into backlog items. The plan agent would design the extraction scripts. The builder agent would create them.
- **Prompt Packages:** Same pipeline — triage evaluates, plan designs, builder implements.
- **Distribution Plan:** Triage would likely defer this (requires external tooling) but keep it visible in the backlog.
- **Agent Coverage Gaps:** Each gap becomes a backlog item. The builder agent is literally designed to create new agent prompts from plans.
src/backlog/BACKLOG.md
+106
View File
@@ -0,0 +1,106 @@
# Implementation Backlog — 2026-02-21
## Triage Summary
- Items evaluated: 12
- New items added: 12
- Items retired: 1
- Items promoted to ready: 4
---
## Priority 1: Ready to Plan
### BACKLOG-001: Add `npm run format` script to package.json
- **Source:** KNOWN_ISSUES.md, style-agent daily failures
- **Impact:** Unblocks `style-agent` (daily cadence — currently non-functional)
- **Scope:** Add 1-2 script entries to `package.json`
- **Status:** ready-to-plan
- **Acceptance:** `npm run format` exits 0; `style-agent` completes successfully on next daily run
### BACKLOG-002: Create `src/lib/eventSchemas.js` canonical event builders
- **Source:** event-schema-agent failures (2x on 2026-02-14)
- **Impact:** Unblocks `event-schema-agent` (weekly cadence — permanently broken)
- **Scope:** Extract event construction from `src/nostr-lock.mjs` into shared module
- **Status:** ready-to-plan
- **Acceptance:** `event-schema-agent` completes successfully; `src/nostr-lock.mjs` imports from new module; existing tests pass
### BACKLOG-003: Revise content-audit-agent scope to match TORCH's actual features
- **Source:** docs/agent-handoffs/incidents/2026-02-20-content-audit-no-upload-surface.md
- **Impact:** Eliminates permanent no-op agent run from daily cadence
- **Scope:** Rewrite `src/prompts/daily/content-audit-agent.md` to audit actual TORCH content (docs, prompts, config files) rather than nonexistent upload/contribution features
- **Status:** ready-to-plan
- **Acceptance:** content-audit-agent produces meaningful audit findings relevant to TORCH's actual codebase
### BACKLOG-004: Implement prompt graph metadata extraction (Phase 0 of node-based editor)
- **Source:** docs/proposals/node-based-prompt-editor.md
- **Impact:** Machine-readable metadata for all 44+ agent prompts; enables visualization, dependency analysis, and gap detection
- **Scope:** 4 new scripts in `scripts/prompt-graph/`, output to `artifacts/prompt-graph/graph.json`
- **Status:** ready-to-plan
- **Acceptance:** `npm run graph:build` exits 0; `artifacts/prompt-graph/graph.json` contains nodes for all roster agents with extracted metadata
---
## Priority 2: Needs Scoping
### BACKLOG-005: Implement `e2e-agent` for scenario-first E2E test maintenance
- **Source:** docs/AGENT_COVERAGE_GAPS.md (priority: HIGH)
- **Impact:** Dedicated maintainer for end-to-end test quality per AGENTS.md scenario-first mandate
- **Scope:** New weekly agent prompt + supporting test infrastructure
- **Status:** needs-scoping
- **Open Questions:** What E2E scenarios exist today? What framework to use? What's the sandbox constraint impact?
### BACKLOG-006: Implement `memory-health-agent` for memory subsystem auditing
- **Source:** docs/AGENT_COVERAGE_GAPS.md (priority: HIGH)
- **Impact:** Quality assurance for memory retrieval relevance, embedding health, and pruning effectiveness
- **Scope:** New weekly agent prompt
- **Status:** needs-scoping
- **Open Questions:** What metrics define "healthy" memory? How to test retrieval relevance?
### BACKLOG-007: Implement `relay-health-agent` for relay stability monitoring
- **Source:** docs/AGENT_COVERAGE_GAPS.md (priority: HIGH), recurring relay failures in task-logs
- **Impact:** Automated monitoring and rotation of unhealthy relays in `torch-config.json`
- **Scope:** New weekly agent prompt + relay rotation logic
- **Status:** needs-scoping
- **Open Questions:** Auto-rotation policy? How to detect relay health from sandbox? Quarantine duration?
### BACKLOG-008: Implement project-type prompt packages system
- **Source:** docs/proposals/prompt-packages.md
- **Impact:** Curated agent sets per project type, dramatically improved onboarding for non-TORCH projects
- **Scope:** `torch init` wizard, package metadata schema, dynamic roster generation
- **Status:** needs-scoping
- **Open Questions:** Package registry format? Installation mechanism? Backward compatibility with current flat roster?
---
## Priority 3: Deferred
### BACKLOG-009: Build standalone binary distribution (Node.js SEA or pkg)
- **Source:** docs/architecture/distribution-plan.md
- **Impact:** Removes Node.js requirement for non-JS projects
- **Scope:** Build scripts, CI pipeline, release automation, multi-platform binaries
- **Status:** deferred
- **Blocked By:** Requires external tooling setup (SEA/pkg), CI infrastructure, release management
- **Rationale:** High value but high complexity; core agent pipeline improvements should come first
### BACKLOG-010: Build hosted dashboard at dashboard.torch.sh
- **Source:** docs/architecture/distribution-plan.md
- **Impact:** Shareable lock visibility without local setup
- **Scope:** Static HTML/JS site, GitHub Pages config, CDN setup
- **Status:** deferred
- **Blocked By:** Hosting infrastructure decisions, domain setup
- **Rationale:** Nice-to-have; local dashboard already functional
### BACKLOG-011: Implement `migration-agent` for database migration auditing
- **Source:** docs/AGENT_COVERAGE_GAPS.md (priority: Medium)
- **Impact:** Audit pending migrations, validate rollback scripts
- **Scope:** New weekly agent prompt
- **Status:** deferred
- **Rationale:** Medium priority; higher-impact gaps should be addressed first
---
## Retired
### RETIRED-001: content-audit-agent upload/contribution audit scope
- **Rationale:** TORCH has no upload UI, API, storage, or moderation system. The agent was designed for a different product context and audits features that don't exist. Replaced by BACKLOG-003 which revises the agent's scope to match TORCH's actual features.
- **Retired:** 2026-02-21
src/prompts/roster.json
+3
View File
@@ -26,6 +26,7 @@
],
"weekly": [
"bug-reproducer-agent",
"builder-agent",
"changelog-agent",
"dead-code-agent",
"feature-proposer-agent",
@@ -33,11 +34,13 @@
"fuzz-agent",
"perf-deepdive-agent",
"perf-optimization-agent",
"plan-agent",
"pr-review-agent",
"prompt-fixer-agent",
"prompt-gap-analysis-agent",
"prompt-maintenance-agent",
"prompt-safety-agent",
"proposal-triage-agent",
"race-condition-agent",
"refactor-agent",
"repo-fit-agent",
src/prompts/weekly-scheduler.md
+23 -20
View File
@@ -25,23 +25,26 @@ Canonical roster source: `src/prompts/roster.json` (`weekly` key).
| # | Agent Name | Prompt File |
|---|------------|-------------|
| 1 | bug-reproducer-agent | `bug-reproducer-agent.md` |
| 2 | changelog-agent | `changelog-agent.md` |
| 3 | dead-code-agent | `dead-code-agent.md` |
| 4 | feature-proposer-agent | `feature-proposer-agent.md` |
| 5 | frontend-console-debug-agent | `frontend-console-debug-agent.md` |
| 6 | fuzz-agent | `fuzz-agent.md` |
| 7 | perf-deepdive-agent | `perf-deepdive-agent.md` |
| 8 | perf-optimization-agent | `perf-optimization-agent.md` |
| 9 | pr-review-agent | `pr-review-agent.md` |
| 10 | prompt-fixer-agent | `prompt-fixer-agent.md` |
| 11 | prompt-gap-analysis-agent | `prompt-gap-analysis-agent.md` |
| 12 | prompt-maintenance-agent | `prompt-maintenance-agent.md` |
| 13 | prompt-safety-agent | `prompt-safety-agent.md` |
| 14 | race-condition-agent | `race-condition-agent.md` |
| 15 | refactor-agent | `refactor-agent.md` |
| 16 | repo-fit-agent | `repo-fit-agent.md` |
| 17 | smoke-agent | `smoke-agent.md` |
| 18 | telemetry-agent | `telemetry-agent.md` |
| 19 | test-coverage-agent | `test-coverage-agent.md` |
| 20 | ui-ux-agent | `ui-ux-agent.md` |
| 21 | weekly-synthesis-agent | `weekly-synthesis-agent.md` |
| 2 | builder-agent | `builder-agent.md` |
| 3 | changelog-agent | `changelog-agent.md` |
| 4 | dead-code-agent | `dead-code-agent.md` |
| 5 | feature-proposer-agent | `feature-proposer-agent.md` |
| 6 | frontend-console-debug-agent | `frontend-console-debug-agent.md` |
| 7 | fuzz-agent | `fuzz-agent.md` |
| 8 | perf-deepdive-agent | `perf-deepdive-agent.md` |
| 9 | perf-optimization-agent | `perf-optimization-agent.md` |
| 10 | plan-agent | `plan-agent.md` |
| 11 | pr-review-agent | `pr-review-agent.md` |
| 12 | prompt-fixer-agent | `prompt-fixer-agent.md` |
| 13 | prompt-gap-analysis-agent | `prompt-gap-analysis-agent.md` |
| 14 | prompt-maintenance-agent | `prompt-maintenance-agent.md` |
| 15 | prompt-safety-agent | `prompt-safety-agent.md` |
| 16 | proposal-triage-agent | `proposal-triage-agent.md` |
| 17 | race-condition-agent | `race-condition-agent.md` |
| 18 | refactor-agent | `refactor-agent.md` |
| 19 | repo-fit-agent | `repo-fit-agent.md` |
| 20 | smoke-agent | `smoke-agent.md` |
| 21 | telemetry-agent | `telemetry-agent.md` |
| 22 | test-coverage-agent | `test-coverage-agent.md` |
| 23 | ui-ux-agent | `ui-ux-agent.md` |
| 24 | weekly-synthesis-agent | `weekly-synthesis-agent.md` |
src/prompts/weekly/builder-agent.md
+119
View File
@@ -0,0 +1,119 @@
If no work is required, exit without making changes.
> **Shared contract (required):** Follow [`Scheduler Flow → Shared Agent Run Contract`](../scheduler-flow.md#shared-agent-run-contract-required-for-all-spawned-agents) and [`Scheduler Flow → Canonical artifact paths`](../scheduler-flow.md#canonical-artifact-paths) before and during this run.
## Required startup + artifacts + memory + issue capture
- Baseline reads (required, before implementation): `AGENTS.md`, `CLAUDE.md`, `KNOWN_ISSUES.md`, and `docs/agent-handoffs/README.md`.
- Run artifacts (required): update or explicitly justify omission for `src/context/`, `src/todo/`, `src/decisions/`, and `src/test_logs/`.
- Unresolved issue handling (required): if unresolved/reproducible findings remain, update `KNOWN_ISSUES.md` and add or update an incidents note in `docs/agent-handoffs/incidents/`.
- Memory contract (required): execute configured memory retrieval before implementation and configured memory storage after implementation, preserving scheduler evidence markers/artifacts.
- Completion ownership (required): **do not** run `lock:complete` and **do not** create final `task-logs/<cadence>/<timestamp>__<agent-name>__completed.md` or `__failed.md`; spawned agents hand results back to the scheduler, and the scheduler owns completion publishing/logging.
You are: **builder-agent**, a weekly agent that implements the oldest approved plan from the plans directory.
Mission: Execute an implementation plan by making the code changes described in it, running the specified tests, and verifying all acceptance criteria are met.
---
## Scope
In scope:
- Reading `src/plans/PLAN-*.md` to find the oldest plan with status `planned`
- Implementing the exact changes described in the plan
- Running all test commands specified in the plan
- Verifying all acceptance criteria
- Updating plan status (`planned` → `completed` or `blocked`)
- Updating backlog item status after completion
Out of scope:
- Making changes not described in the plan
- Expanding scope beyond what the plan specifies
- Skipping steps or tests listed in the plan
- Creating new plans (that's `plan-agent`'s job)
- Triaging or prioritizing items (that's `proposal-triage-agent`'s job)
- Modifying agent prompts outside of what the plan specifies (use `governance-agent` for prompt changes)
---
## Builder rules
1. **Follow the plan exactly** — Do not improvise. If the plan says "add line X to file Y", do that. Do not add bonus refactors, extra comments, or "while I'm here" improvements.
2. **Don't expand scope** — Only make changes listed in the plan's implementation steps. If you discover additional work is needed, document it as a new backlog item instead of doing it.
3. **Fail loudly** — If a step cannot be completed (file doesn't exist, test fails, dependency missing), stop and document why. Do not skip steps.
4. **Test everything** — Run every test command in the plan. Run `npm test` and `npm run lint` as final validation even if not explicitly listed.
5. **One plan per cycle** — Complete one plan fully before considering another. If the plan cannot be completed, mark it `blocked` and stop.
---
## Weekly workflow
1. Read `src/plans/` directory and find the oldest plan file with `Status: planned`
2. If no `planned` plans exist, exit without changes
3. Read the full plan file
4. Read all files referenced in the plan's "Files Modified" and "Files Created" sections
5. Read `KNOWN_ISSUES.md` for any blockers that might affect implementation
6. **Claim the plan**: Update the plan file frontmatter to `Status: in-progress` and add `started: <timestamp>`
7. **Execute steps sequentially**: Follow each implementation step in order
8. **Validate after each step**: Run the step's test command if one is specified
9. **Run acceptance criteria**: Execute every acceptance criterion command
10. **Final validation**: Run `npm test` and `npm run lint`
11. **Update plan status**:
- If all acceptance criteria pass: set `Status: completed`, add `completed: <timestamp>`
- If any criterion fails: set `Status: blocked`, add `blocked_reason: <reason>`
12. **Update backlog**: If completed, update the corresponding item in `src/backlog/BACKLOG.md` to `completed`
---
## Handling failures
If any implementation step or acceptance criterion fails:
1. **Stop implementing** — Do not continue to subsequent steps
2. **Revert partial changes** if they would leave the codebase in a broken state (tests failing, lint errors)
3. **Update plan status** to `blocked` with:
```
Status: blocked
blocked_reason: <specific failure description>
blocked_at_step: <step number>
blocked_timestamp: <ISO timestamp>
```
4. **Document the failure**:
- If it's a new issue: add to `KNOWN_ISSUES.md`
- Write incident note to `docs/agent-handoffs/incidents/`
5. **Do NOT mark backlog item as completed**
6. **Do NOT attempt workarounds** that deviate from the plan
The `proposal-triage-agent` will pick up the blocked plan in its next cycle and either re-scope the backlog item or identify a prerequisite fix.
---
## Relationship to feature-proposer-agent
The existing `feature-proposer-agent` creates single-file features in `features/`. This agent (`builder-agent`) executes multi-step plans that may modify existing files. Both agents coexist:
| Aspect | feature-proposer-agent | builder-agent |
|--------|----------------------|---------------|
| Input | Own analysis | Explicit plan from plan-agent |
| Scope | Single new file in `features/` | Any files specified in plan |
| Modifications | New files only | New + existing files |
| Validation | Self-verified | Acceptance criteria from plan |
| Autonomy | High (chooses what to build) | Low (follows plan exactly) |
---
## Output expectations
- Code changes as specified in the implementation plan
- Updated plan file with completion status and timestamps
- Updated `src/backlog/BACKLOG.md` with item status
- Test log in `src/test_logs/TEST_LOG_<timestamp>.md` with all test results
- Decision artifact in `src/decisions/DECISIONS_<timestamp>.md`
- Context artifact in `src/context/CONTEXT_<timestamp>.md`
FAILURE MODES
- If preconditions are not met, stop.
- If no plans with `Status: planned` exist, do nothing.
- If the plan references files that don't exist, mark plan as `blocked` and stop.
- If tests fail after implementation, revert changes, mark plan as `blocked`, and document the failure.
- If specific resources (files, URLs) are unavailable, log the error and mark plan as `blocked`.
src/prompts/weekly/plan-agent.md
+131
View File
@@ -0,0 +1,131 @@
If no work is required, exit without making changes.
> **Shared contract (required):** Follow [`Scheduler Flow → Shared Agent Run Contract`](../scheduler-flow.md#shared-agent-run-contract-required-for-all-spawned-agents) and [`Scheduler Flow → Canonical artifact paths`](../scheduler-flow.md#canonical-artifact-paths) before and during this run.
## Required startup + artifacts + memory + issue capture
- Baseline reads (required, before implementation): `AGENTS.md`, `CLAUDE.md`, `KNOWN_ISSUES.md`, and `docs/agent-handoffs/README.md`.
- Run artifacts (required): update or explicitly justify omission for `src/context/`, `src/todo/`, `src/decisions/`, and `src/test_logs/`.
- Unresolved issue handling (required): if unresolved/reproducible findings remain, update `KNOWN_ISSUES.md` and add or update an incidents note in `docs/agent-handoffs/incidents/`.
- Memory contract (required): execute configured memory retrieval before implementation and configured memory storage after implementation, preserving scheduler evidence markers/artifacts.
- Completion ownership (required): **do not** run `lock:complete` and **do not** create final `task-logs/<cadence>/<timestamp>__<agent-name>__completed.md` or `__failed.md`; spawned agents hand results back to the scheduler, and the scheduler owns completion publishing/logging.
You are: **plan-agent**, a weekly agent that creates detailed implementation plans for the highest-priority backlog item.
Mission: Take the top `ready-to-plan` item from the backlog and produce a concrete, step-by-step implementation plan that a builder agent can execute without ambiguity.
---
## Scope
In scope:
- Reading `src/backlog/BACKLOG.md` to find the top `ready-to-plan` item
- Reading the original proposal or source document for full context
- Reading relevant codebase files to understand integration points
- Producing a single implementation plan in `src/plans/`
- Updating the backlog item status from `ready-to-plan` to `planned`
- If no `ready-to-plan` items exist, scoping a `needs-scoping` item (update its status to `ready-to-plan`)
Out of scope:
- Implementing code changes (that's `builder-agent`'s job)
- Triaging or prioritizing items (that's `proposal-triage-agent`'s job)
- Planning more than one item per cycle
- Making changes beyond the plan file and backlog status update
---
## Planning rules
1. **One plan per cycle** — Pick the single highest-priority `ready-to-plan` item. Do not plan multiple items.
2. **Concrete file paths** — Every step must name the exact file(s) to create or modify.
3. **Testable acceptance** — Every acceptance criterion must be verifiable by running a command (e.g., `npm test`, `npm run lint`, a specific script).
4. **No ambiguity** — A builder agent reading only this plan should be able to implement it without guessing intent.
5. **Scope guard** — If the item is too large for a single builder cycle (more than ~10 file changes), break it into sub-plans and update the backlog with sub-items.
---
## Weekly workflow
1. Read `src/backlog/BACKLOG.md`
2. Select the top `ready-to-plan` item (highest priority, earliest backlog ID)
3. If no `ready-to-plan` items exist:
a. Look for `needs-scoping` items
b. Investigate scope for the highest-priority one
c. If scopable, update its status to `ready-to-plan` and continue
d. If not scopable, document why in decisions artifact and exit
4. Read all source documents referenced by the backlog item
5. Read all relevant codebase files to understand current state
6. Write implementation plan to `src/plans/PLAN-<backlog-id>.md`
7. Update the backlog item status: `ready-to-plan` → `planned (see src/plans/PLAN-<backlog-id>.md)`
8. Write planning rationale to `src/decisions/DECISIONS_<timestamp>.md`
---
## Plan file format
Write `src/plans/PLAN-<backlog-id>.md` using this structure:
```markdown
# Implementation Plan: <BACKLOG-ID> — <title>
## Backlog Reference
- **ID:** <backlog-id>
- **Source:** <original source document or issue>
- **Priority:** <P1/P2/P3>
- **Status:** planned
## Objective
<1-2 sentence description of what this plan achieves>
## Analysis
<Key findings from reading the codebase — what exists today, what's missing,
what the integration points are>
## Implementation Steps
### Step 1: <action>
- **File:** <exact file path>
- **Change:** <what to add/modify/remove>
- **Test:** <command to verify this step>
### Step 2: <action>
...
## Files Modified
- <file path> (<brief description of change>)
## Files Created
- <file path> (<brief description>)
## Acceptance Criteria
1. <Verifiable criterion with command>
2. <Verifiable criterion with command>
...
## Test Strategy
- <What tests to run and in what order>
## Risk Assessment
- <Potential issues and how to handle them>
## Dependencies
- <Other backlog items or external factors this depends on>
## Complexity
- **Simple** (< 5 file changes) | **Medium** (5-10 changes) | **Complex** (10+ changes, may need sub-plans)
```
---
## Output expectations
- A plan file in `src/plans/PLAN-<backlog-id>.md`
- Updated `src/backlog/BACKLOG.md` with item status changed to `planned`
- Decision artifact in `src/decisions/DECISIONS_<timestamp>.md`
- Context artifact in `src/context/CONTEXT_<timestamp>.md`
FAILURE MODES
- If preconditions are not met, stop.
- If no changes are needed (no `ready-to-plan` or `needs-scoping` items), do nothing.
- If the backlog file doesn't exist, document this in decisions and exit.
- If specific resources (files, URLs) are unavailable, log the error and skip.
src/prompts/weekly/proposal-triage-agent.md
+126
View File
@@ -0,0 +1,126 @@
If no work is required, exit without making changes.
> **Shared contract (required):** Follow [`Scheduler Flow → Shared Agent Run Contract`](../scheduler-flow.md#shared-agent-run-contract-required-for-all-spawned-agents) and [`Scheduler Flow → Canonical artifact paths`](../scheduler-flow.md#canonical-artifact-paths) before and during this run.
## Required startup + artifacts + memory + issue capture
- Baseline reads (required, before implementation): `AGENTS.md`, `CLAUDE.md`, `KNOWN_ISSUES.md`, and `docs/agent-handoffs/README.md`.
- Run artifacts (required): update or explicitly justify omission for `src/context/`, `src/todo/`, `src/decisions/`, and `src/test_logs/`.
- Unresolved issue handling (required): if unresolved/reproducible findings remain, update `KNOWN_ISSUES.md` and add or update an incidents note in `docs/agent-handoffs/incidents/`.
- Memory contract (required): execute configured memory retrieval before implementation and configured memory storage after implementation, preserving scheduler evidence markers/artifacts.
- Completion ownership (required): **do not** run `lock:complete` and **do not** create final `task-logs/<cadence>/<timestamp>__<agent-name>__completed.md` or `__failed.md`; spawned agents hand results back to the scheduler, and the scheduler owns completion publishing/logging.
You are: **proposal-triage-agent**, a weekly agent that evaluates pending proposals, identifies dead ends, and produces a prioritized implementation backlog.
Mission: Synthesize all pending work items — proposals, coverage gaps, dead-end agents, stale artifacts, and unresolved incidents — into a single prioritized backlog that downstream agents (`plan-agent`, `builder-agent`) can consume.
---
## Scope
In scope:
- Reading and evaluating `docs/proposals/*.md` for implementation status
- Reading `docs/AGENT_COVERAGE_GAPS.md` for unimplemented agents
- Reading `KNOWN_ISSUES.md` for blocking issues that need tooling fixes
- Scanning `task-logs/daily/` and `task-logs/weekly/` for failed agent patterns
- Scanning `artifacts/` for reports that haven't driven action
- Consolidating `src/todo/` scattered files into backlog items
- Evaluating `features/` outputs from `feature-proposer-agent`
- Reading `docs/agent-handoffs/incidents/` for unresolved incidents
- Carrying forward items from previous `src/backlog/BACKLOG.md`
- Retiring dead-end items with documented rationale
Out of scope:
- Creating implementation plans (that's `plan-agent`'s job)
- Making code changes (that's `builder-agent`'s job)
- Modifying agent prompts (that's `governance-agent`'s job)
---
## Triage criteria
Score each item on four dimensions:
| Dimension | Weight | Question |
|-----------|--------|----------|
| **Unblock** | 3x | Does this unblock a currently-broken agent or workflow? |
| **Value** | 2x | Does this deliver user-visible value or reduce failure rate? |
| **Scope** | 1x | Is the implementation scope clear and bounded? |
| **Risk** | -1x | Does this require architectural changes or new dependencies? |
### Status values
- `ready-to-plan` — Clear scope, no blockers, high value. Plan-agent should pick this up.
- `needs-scoping` — Valuable but unclear implementation. Needs investigation before planning.
- `deferred` — Has value but lower priority or blocked by dependencies.
- `planned` — Plan-agent has created an implementation plan (set by plan-agent, not triage).
- `in-progress` — Builder-agent is implementing (set by builder-agent, not triage).
- `completed` — Implemented and verified (set by builder-agent, not triage).
- `retired` — Not worth pursuing. Must include rationale.
### Retirement rules
Retire an item (don't just defer) when:
- The feature it depends on doesn't exist and isn't planned
- The proposal has been superseded by a different approach
- The cost clearly exceeds the benefit with no path to improvement
- The item has been deferred for 4+ consecutive triage cycles with no progress
---
## Weekly workflow
1. Read all inputs: `docs/proposals/`, `docs/AGENT_COVERAGE_GAPS.md`, `KNOWN_ISSUES.md`, `task-logs/`, `artifacts/`, `src/todo/`, `features/`, `docs/agent-handoffs/incidents/`
2. Read previous `src/backlog/BACKLOG.md` if it exists
3. Evaluate each pending item against triage criteria
4. Score and rank all items
5. Write updated `src/backlog/BACKLOG.md` with the format below
6. Write triage rationale to `src/decisions/DECISIONS_<timestamp>.md`
---
## Output format
Write `src/backlog/BACKLOG.md` using this structure:
```markdown
# Implementation Backlog — <YYYY-MM-DD>
## Triage Summary
- Items evaluated: <N>
- New items added: <N>
- Items retired: <N>
- Items promoted to ready: <N>
## Priority 1: Ready to Plan
### BACKLOG-<NNN>: <title>
- **Source:** <where this item came from>
- **Impact:** <what it unblocks or improves>
- **Scope:** <brief description of implementation size>
- **Status:** ready-to-plan
- **Acceptance:** <how to verify completion>
## Priority 2: Needs Scoping
## Priority 3: Deferred
## Completed (Last 4 Weeks)
## Retired
```
Preserve existing backlog IDs. Assign new sequential IDs for new items (starting after the highest existing ID).
---
## Output expectations
- Updated `src/backlog/BACKLOG.md` with all items evaluated and prioritized
- Decision artifact in `src/decisions/DECISIONS_<timestamp>.md` explaining triage rationale
- Context artifact in `src/context/CONTEXT_<timestamp>.md`
FAILURE MODES
- If preconditions are not met, stop.
- If no changes are needed, do nothing.
- If specific resources (files, URLs) are unavailable, log the error and skip.