Repository navigation
feat: organize agent work output into task-scoped folders (.squad/work/{issue}-{slug}/) #707
Closed as not planned
Description
Problem
When agents work on issues, research tasks, or side work, they drop output files (screenshots, PDFs, scripts, JSON, markdown reports) directly in the repo root or random locations. Over time this creates a mess — hundreds of unorganized files with no connection to the issue that produced them.
Example of what happens today:
C:\temp\tamresearch1\
├── ISSUE_342_ANALYSIS.md ← good name, wrong location
├── captcha-py-step0.png ← no idea what issue this belongs to
├── captcha-py-step1.png
├── extract_pdf.py ← from which task?
├── email_body.html ← which email?
├── pr12-full-diff.txt
├── hebrew-podcast-final.mp3
├── mvp-summit-screenshots\ ← at least this got a folder
├── blog-part1-final.md
├── ... hundreds more files ...
Proposed Solution
Agents should organize work output into task-scoped folders with a clear naming convention:
.squad/work/
├── 1752-passover-worksheets/ ← issue #1752
│ ├── 1.pdf
│ ├── extract_pdf.py
│ ├── math_links.txt
│ └── email_body.html
├── 678-git-notes-poc/ ← issue #678
│ ├── state-backend-test-results.md
│ └── architecture-diagram.md
├── research-mvp-summit-book/ ← no issue, descriptive name
│ ├── screenshots/
│ ├── all_summaries.py
│ └── Book-of-News-V3.pdf
└── 587-coordinator-restraint/ ← issue #587
└── analysis.md
Naming Convention
{issue-number}-{kebab-case-slug}/ when linked to an issue
{descriptive-slug}/ when no issue exists (research, side work)
Implementation
- Coordinator instruction — add to
squad.agent.md: "When spawning agents for issue work, set the work output directory to.squad/work/{issue}-{slug}/" - Agent spawn prompt — include the output directory path so agents know where to write
- Ralph awareness — Ralph should create the work folder when claiming an issue
- Cleanup rule — work folders for closed issues can be archived or deleted after N days
What This Does NOT Change
.squad/agents/— agent charters and history stay where they are.squad/decisions/— decisions stay in their current location.squad/orchestration-log/— logs stay in their current location- Only task output artifacts (files agents produce as deliverables) go in work folders
Related
- PRD: Versioned file layout manifest - single source of truth for directory structure #670 (versioned file layout manifest) — work/ would be part of the manifest
- RFC: Git-Notes State Solution — solve state destruction, VCS removal, and layout manifest in one architectural change #678 (StateBackend) — work folders are runtime artifacts, not state
Activity
github-actions commentedon Sep 10, 2026
🔄 Ralph — Auto-Triage
Assigned to: Procedures
Reason: Matched routing keyword(s): prompt, architecture, Agent charters
Source: routing-rule
github-actions commentedon Sep 10, 2026
🔄 Ralph — Auto-Triage
Assigned to: Procedures
Reason: Matched routing keyword(s): prompt, architecture, Agent charters
Source: routing-rule
github-actions commentedon Sep 11, 2026
🔄 Ralph — Auto-Triage
Assigned to: Procedures
Reason: Matched routing keyword(s): prompt, architecture, Agent charters
Source: routing-rule
github-actions commentedon Sep 11, 2026
🔄 Ralph — Auto-Triage
Assigned to: Procedures
Reason: Matched routing keyword(s): prompt, architecture, Agent charters
Source: routing-rule
github-actions commentedon Sep 11, 2026
🔄 Ralph — Auto-Triage
Assigned to: Procedures
Reason: Matched routing keyword(s): prompt, architecture, Agent charters
Source: routing-rule
github-actions commentedon Sep 11, 2026
🔄 Ralph — Auto-Triage
Assigned to: Procedures
Reason: Matched routing keyword(s): prompt, architecture, Agent charters
Source: routing-rule
github-actions commentedon Sep 13, 2026
🔄 Ralph — Auto-Triage
Assigned to: architect
Reason: No module, routing, or role keyword match — routed to Lead/Architect
Source: lead-fallback
github-actions commentedon Sep 24, 2026
📋 Assigned to agent-orchestration-dev (Agent Orchestration Engineer)
Issue: #707 — feat: organize agent work output into task-scoped folders (.squad/work/{issue}-{slug}/)
agent-orchestration-dev will pick this up in the next Copilot session.
bradygaster commentedon Nov 5, 2026
Closing during 2.0 board triage (owner decision). The idea is evaluated, with prior art and an opinion, in the roll-up issue #2390. Original text remains here for reference.