diff --git a/docs/proposals/plan-agent-architecture.md b/docs/proposals/plan-agent-architecture.md new file mode 100644 index 0000000..c8dcc99 --- /dev/null +++ b/docs/proposals/plan-agent-architecture.md @@ -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 — + +## Triage Summary +- Items evaluated: +- New items added: +- Items retired (dead end): +- Items promoted to ready: + +## Priority 1: Ready to Plan + + +### 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 + + +### 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 + + +## Retired (Dead Ends) + + +### 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_.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-.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-.md` +6. Update backlog item status to `planned` +7. Write planning rationale to `src/decisions/DECISIONS_.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: ` 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: ` 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_.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. diff --git a/src/backlog/BACKLOG.md b/src/backlog/BACKLOG.md new file mode 100644 index 0000000..d067b69 --- /dev/null +++ b/src/backlog/BACKLOG.md @@ -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 diff --git a/src/prompts/roster.json b/src/prompts/roster.json index 9fe4dda..ef39f74 100644 --- a/src/prompts/roster.json +++ b/src/prompts/roster.json @@ -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", diff --git a/src/prompts/weekly-scheduler.md b/src/prompts/weekly-scheduler.md index 983b268..6a3944d 100644 --- a/src/prompts/weekly-scheduler.md +++ b/src/prompts/weekly-scheduler.md @@ -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` | diff --git a/src/prompts/weekly/builder-agent.md b/src/prompts/weekly/builder-agent.md new file mode 100644 index 0000000..ceeb614 --- /dev/null +++ b/src/prompts/weekly/builder-agent.md @@ -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//____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: ` +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: ` + - If any criterion fails: set `Status: blocked`, add `blocked_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: + blocked_at_step: + blocked_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_.md` with all test results +- Decision artifact in `src/decisions/DECISIONS_.md` +- Context artifact in `src/context/CONTEXT_.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`. diff --git a/src/prompts/weekly/plan-agent.md b/src/prompts/weekly/plan-agent.md new file mode 100644 index 0000000..5a246ef --- /dev/null +++ b/src/prompts/weekly/plan-agent.md @@ -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//____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-.md` +7. Update the backlog item status: `ready-to-plan` → `planned (see src/plans/PLAN-.md)` +8. Write planning rationale to `src/decisions/DECISIONS_.md` + +--- + +## Plan file format + +Write `src/plans/PLAN-.md` using this structure: + +```markdown +# Implementation Plan: — + +## 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. diff --git a/src/prompts/weekly/proposal-triage-agent.md b/src/prompts/weekly/proposal-triage-agent.md new file mode 100644 index 0000000..582c04d --- /dev/null +++ b/src/prompts/weekly/proposal-triage-agent.md @@ -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.