refactor(sops): reorganize .agents/ directory structure and update defaults

[jlhood]

Issue #, if available:

Description of changes:

Reorganizes the default directory structure for Agent SOPs to separate reference documentation (worth pinning in context) from transient working files.

Changes

Directory Structure

New .agents/ layout:

• planning/{project_name}/ - PDD outputs (pin these with /context add)
• tasks/{project_name}/ - Code tasks from code-task-generator
• scratchpad/{project_name}/ - Code-assist working files (don't pin)

SOP Updates

pdd.sop.md:

• Add project_name parameter to create project-specific subdirectories
• Default project_dir now .agents/planning/{project_name}
• Change Q → Kiro in context add instruction

codebase-summary.sop.md:

• Default output_dir now .agents/summary
• Default consolidate changed from false to true
• Add merge behavior for existing consolidated files (preserves manual edits)

code-task-generator.sop.md:

• Default output_dir now .agents/tasks/{project_name}
• Add project_name parameter

code-assist.sop.md:

• Default documentation_dir now .agents/scratchpad/{project_name}
• Add project_name parameter
• Simplify internal paths (remove redundant /implementation/ subdirectory)

Motivation

Previously, all SOP artifacts went into a single directory, causing context pollution when users pinned planning docs with glob patterns. This separation allows pinning reference docs without including transient implementation artifacts.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[Unshure]

nit: We may want to add .agents to the gitignore too: https://github.com/strands-agents/agent-sop/blob/main/.gitignore

[Unshure]

Trying to parse out why the project_name is under .agents/tasks is a bit unintuitive at first glance. Maybe we can update the readme or something to mention the expected filesystem structure when using these sops?

.agents/
├── planning/
│   └── {project_name}/
├── tasks/
│   └── {project_name}/
└── scratchpad/
    └── {project_name}/
        └── {task_name}/

[jlhood]

Yeah I think it's easy to look at this and wonder why it isn't .agents/{project_name}/*. My reasoning is:

1. The dir hierarchy is organized in terms of level of persistence of each set of artifacts, i.e., separating into dirs by what users are likely to want to commit.
   1. summary/ docs are written by codebase-summary SOP and are super useful for both humans and agents. I recommend always checking this into source code
   2. planning/ docs are written by the pdd SOP and can be useful to commit to capture important decisions, designs, alternatives considered, etc that usually get lost in traditional software processes.
   3. tasks/ docs are written by code-task-generator and users might want to commit them to source code, but they can also be written to issues in an issue tracker.
   4. scratchpad/ is just for the agent to write notes (code-assist writes all its files to this dir) and should generally be added to .gitignore
2. The PDD family of agent SOPs is highly flexible and can be used across tasks of varying complexity/ambiguity. This means for lower complexity tasks, you may only run code-assist which only writes to scratchpad/. For larger changes/features, you will likely run pdd, code-task-generator and code-assist in which case you'll have docs in all of the corresponding dirs, but for smaller more straightforward tasks, you may only run code-assist. In the latter case, you wouldn't want top-level project folders created.

Open to feedback but logging my rationale here and will update the README to reflect it to help users understand the layout.

[jlhood]

nit: We may want to add .agents to the gitignore too: https://github.com/strands-agents/agent-sop/blob/main/.gitignore

I added .agents/scratchpad to fit with our own guidance