Handoff Prompt Templates

Templates for structured work transitions between agent roles. Using these verbatim reduces ambiguity and protects the team from scope creep, missed context, and silent deviations.

Template 1: Collaborator → Systems Architect (Design Task)

Used when Kevin and the Collaborator decide a rigorous design deliverable (spec, ADR, deep dive, implementation plan) is needed.

# Architect Task — <Deliverable Name>

You are the PSSaaS Systems Architect. Start by reading
`docs-site/docs/agents/architect-context.md` and completing the session
start checklist.

## Deliverable

[One sentence: what artifact to produce]

## Scope

[Bulleted list of what's included]

## Out of Scope

[Bulleted list of what NOT to do in this task]

## Success Criteria

- [ ] [Specific, testable outcome 1]
- [ ] [Specific, testable outcome 2]

## References (read these first)

- `docs-site/docs/specs/<spec>.md` — [why relevant]
- `docs-site/docs/adr/<adr>.md` — [why relevant]
- `X:\dev\other\PowerSeller-App\<path>` — [legacy code location]
- [Any other critical context]

## Preferred Approach (optional)

[If Collaborator has an opinion on direction; otherwise omit]

## Timeline

[If any; otherwise "when ready"]

## Report Back

Produce an Architect Report with:
- Artifacts produced (with links)
- Decisions made (with ADR refs)
- Assumptions flagged (with citations)
- Open questions or blockers
- Recommended next steps

Template 2: Systems Architect → Developer (Implementation Task)

Used when the Architect has a concrete implementation task that can be handed to a Developer agent (fast subagent, manual relay, or self).

# Developer Task — <Task Name>

You are a PSSaaS Developer agent. Start by reading
`docs-site/docs/agents/developer-context.md` and completing the session
start checklist.

## Context

This task implements [Phase N of the <Module> Spec](docs-site/docs/specs/<spec>.md).
[1-2 sentences on why this task exists]

## Scope

### Files to create

- `src/backend/<path>/<NewFile>.cs` — [purpose]
- `src/backend/<path>/<NewFile>.cs` — [purpose]

### Files to modify

- `src/backend/<path>/<ExistingFile>.cs` — [what to change]

### Files NOT to touch

- `docs-site/docs/specs/<spec>.md` — specs are Architect's domain
- `docs-site/docs/adr/<adr>.md` — ADRs are Architect's domain
- [Any other files the developer might be tempted to change]

## Dependencies (pre-authorized)

- [NuGet package or project reference] — [why needed]

## Acceptance Criteria

Code meets spec when:

- [ ] [Specific testable criterion 1]
- [ ] [Specific testable criterion 2]
- [ ] All unit tests pass (`dotnet test`)
- [ ] Build passes with no warnings (`dotnet build --warnaserror`)
- [ ] No `float` or `double` for monetary values
- [ ] All queries tenant-scoped via `ITenantContext`

## Tests Required

- [Test file path] — covers [behavior 1, behavior 2, ...]
- [Test file path] — covers [...]

## Verification Steps

After implementation, run:

1. `dotnet build src/backend/PowerSeller.SaaS.sln`
2. `dotnet test src/backend/tests/<TestProject>`
3. [Any task-specific verification]

Include the outputs in your completion report.

## Anti-Patterns to Avoid

- [Specific pitfall for this task]
- [Specific pitfall]

## Reference Patterns

Follow patterns from:

- [Specific existing module or file] — [which aspect]

## Report Back

Produce a Developer Report with:

- Files modified (explicit list)
- Tests added (file → what they cover)
- Verification results (commands + outputs)
- Deviations from spec (none / explicit list with justification)
- Known issues (none / list)

Template 3: Systems Architect → Collaborator (Escalation)

Used when the Architect hits a decision that needs Product Owner input or cross-project coordination.

# Architect Escalation — <Topic>

Escalating to the Collaborator for [Product Owner input / cross-project
coordination / spec clarification].

## The Question

[Clear, specific question]

## Context

[Why this came up — which spec/ADR/task]

## Options Considered

### Option A: [Name]

- Summary: [...]
- Pros: [...]
- Cons: [...]

### Option B: [Name]

- Summary: [...]
- Pros: [...]
- Cons: [...]

[More options as needed]

## My Recommendation

[Which option you recommend and why]

## Default Behavior If Unanswered

[What you will proceed with in the absence of an answer, and what that
means for downstream work]

## Impact of Getting It Wrong

[What breaks or needs rework if we pick the wrong option]

## Timeline

[When you need an answer to avoid blocking Phase X]

Template 4: Developer → Architect (Escalation)

Used when a Developer hits something the task doesn't cover.

# Developer Escalation — <Task Name>

Task is blocked or ambiguous. Need Architect input.

## What Happened

[Specific: the task said X, but I encountered Y]

## The Question

[Clear, specific question]

## What I've Tried

[Dead ends and why they didn't work]

## Options I See

[1-3 options with brief pros/cons]

## My Inclination

[What I'd do without further guidance, and why]

## Files Currently Touched

[Explicit list — so Architect knows state]

Template 5: Any Agent → Kevin (Product Owner Question)

Rare — generally route through the Collaborator. But when a narrowly-scoped question warrants direct PO input:

# PO Question — <Topic>

Asking Kevin directly because [reason — usually "Collaborator doesn't have
the context either" or "this is a narrow product decision"].

## The Question

[Clear, specific question]

## Why I'm Asking You

[Why this decision is yours specifically, not the Architect's or Collaborator's]

## Options

[Brief list]

## Impact

[What this decision affects]

Template 6: Alignment Checkpoint Report

Produced by any agent when an alignment is triggered (Kevin says "align" or context is degrading).

# Alignment Report — <Role> — <Date>

## Role confirmation

I am the PSSaaS <role>. [One sentence on current task.]

## Docs re-read

- [ ] CLAUDE.md
- [ ] AGENTS.md
- [ ] <role>-context.md
- [ ] session handoff
- [ ] .cursorrules

## Self-audit gaps

[Any discrepancies between current work and documented invariants/rules.
If none: "No gaps found."]

## Current destination

[What I was working on; what comes next]

## Cross-project items

[Anything happening in PSX, MBS Access, or Desktop App that affects PSSaaS]

## Blockers

[Anything waiting on Kevin or another agent]

Template 7: Devlog Entry

Every completed task gets a devlog entry regardless of which agent did it.

---
sidebar_position: <N>
title: "<YYYY-MM-DD> — <Short Title>"
---

# <Short Title>

**Date:** YYYY-MM-DD
**Agent:** <Collaborator | Systems Architect | Developer>
**Scope:** [One sentence]

## Why

[Why this work was done — the business reason or technical trigger]

## What Was Done

[Bulleted list of concrete changes]

## Files Produced / Modified

[Explicit list with links]

## Key Decisions

[Any decisions made, with references to ADRs or spec sections]

## What's Next

[Follow-up work, if any]

## Risks Captured

[Anything flagged for future attention]

Usage Notes

• Copy the template wholesale. Don't summarize or paraphrase. The structure protects against missed context.
• Fill every section. If a section doesn't apply, write "N/A" explicitly — don't delete it.
• Be specific. "Implement the service" is not a scope; "Create PowerFillOptionsService.cs with methods Get, Set, Validate" is.
• Link, don't quote. Reference source documents by path; don't paste their contents into the handoff.
• Explicit out-of-scope matters more than explicit in-scope. Developers over-deliver when under-constrained; the out-of-scope section protects the boundaries.