# SAM Infrastructure Layer Specification

> The SAM Infrastructure Layer provides persistent state management, agent coordination, and artifact lifecycle management for the Stateless Agent Methodology.

- Skill: `tools-only/sam-infrastructure-layer-specification` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/sam-infrastructure-layer-specification`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/sam-infrastructure-layer-specification/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/sam-infrastructure-layer-specification

---

# SAM Infrastructure Layer Specification

## Overview

The SAM Infrastructure Layer provides persistent state management, agent coordination, and artifact lifecycle management for the Stateless Agent Methodology. It enables agents to work asynchronously across sessions while maintaining consistency, traceability, and recoverability.

**Core principle**: SAM treats Claude as a stateless function. The infrastructure layer compensates by externalizing all state to git, filesystem, and optional databases.

### Storage-agnostic semantic tokens (canonical identifiers)

This document may show concrete filenames/paths (e.g. `.sam/artifacts/.../*.md`) as _one possible filesystem-backed implementation_. Those paths are **not** canonical. The canonical representation is a semantic token that can be backed by files, a database, a queue, git notes, etc.

**Core token pattern**:

```text
ARTIFACT:{TYPE}({SCOPE_OR_ID})
```

**Common artifact types used in this infrastructure doc (extend as needed)**:

```text
ARTIFACT:REQUIREMENTS(SCOPE:...)
ARTIFACT:INTERVIEW(INTERVIEW:...)
ARTIFACT:CODEBASE_ANALYSIS(SCOPE:...)
ARTIFACT:RESEARCH(SCOPE:...)
ARTIFACT:ARCH(SCOPE:...)
ARTIFACT:ADR(DECISION:...)
ARTIFACT:PLAN(SCOPE:...)
ARTIFACT:TASK(TASK:...)
ARTIFACT:EXECUTION(TASK:...)
ARTIFACT:TEST_RESULTS(TASK:...)
ARTIFACT:REVIEW(TASK:...)
ARTIFACT:VERIFICATION(SCOPE:...)
ARTIFACT:RELEASE_NOTES(SCOPE:...)
ARTIFACT:HANDOFF(SCOPE:...)
ARTIFACT:MESSAGE(MSG:...)
```

**Disambiguators (consistent with `stateless-software-engineering-framework.md`)**:

```text
CTX:WINDOW | CTX:CODEBASE | CTX:CONVERSATION | CTX:INTEGRATION
PREREQ:AVAILABLE | PREREQ:DERIVABLE | PREREQ:MISSING | PREREQ:CONFIDENCE(0.0-1.0)
EXEC:SEQUENTIAL | EXEC:PARALLEL | EXEC:WAVE
VERIFY:SELF | VERIFY:BOUNDARY | VERIFY:FORENSIC | VERIFY:FINAL
```

**Policy alignment**:

- The workflow explicitly avoids tool blocking and approval gates. Approval is frontloaded via explicit agreement on desired outcome + objectives + acceptance criteria. After that, progress is gated only by prerequisite completeness (`PREREQ:*`) and check outcomes (`VERIFY:*`), not by “permission to use tools”.

### Integration with 7-Stage SAM Pipeline

```text
┌─────────────────────────────────────────────────────────────┐
│                 SAM Infrastructure Layer                     │
│  ┌─────────────┬─────────────┬──────────────┬─────────────┐ │
│  │ Meta-Message│  Artifact   │ Git Worktree │ MCP Server  │ │
│  │   System    │   Storage   │  Integration │  Interface  │ │
│  └─────────────┴─────────────┴──────────────┴─────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            ↓
    ┌──────────────────────────────────────────────────┐
    │         7-Stage SAM Pipeline                      │
    ├──────────────────────────────────────────────────┤
    │ 1. Discovery & Interview                          │
    │    ↓ ARTIFACT:REQUIREMENTS(SCOPE:...) (e.g. requirements.md, interviews/) │
    │ 2. Context Gathering                              │
    │    ↓ ARTIFACT:CODEBASE_ANALYSIS(SCOPE:...) (e.g. codebase-analysis/, patterns/) │
    │ 3. Research & Learning                            │
    │    ↓ ARTIFACT:RESEARCH(SCOPE:...) (e.g. research-{topic}.md)              │
    │ 4. Design & Architecture                          │
    │    ↓ ARTIFACT:ARCH(SCOPE:...) + ARTIFACT:ADR(DECISION:...) (e.g. architecture.md, adr-{id}.md) │
    │ 5. Planning                                       │
    │    ↓ ARTIFACT:PLAN(SCOPE:...) + ARTIFACT:TASK(TASK:...) (e.g. plan.md, task-{id}.md) │
    │ 6. Implementation & Validation                    │
    │    ↓ ARTIFACT:EXECUTION(TASK:...) + ARTIFACT:TEST_RESULTS(TASK:...) (e.g. execution-log.md, test-results.md) │
    │ 7. Delivery                                       │
    │    → ARTIFACT:VERIFICATION(SCOPE:...) + ARTIFACT:RELEASE_NOTES(SCOPE:...) (e.g. verification.md, release-notes.md) │
    └──────────────────────────────────────────────────┘
```

**Data flow**:

1. Each stage produces canonical `ARTIFACT:*` tokens (optionally materialized as `.sam/artifacts/{stage}/...` in a filesystem backend)
2. Agents communicate via messages (optionally materialized as `.sam/messages/...` in a filesystem backend)
3. Git worktrees isolate concurrent work per stage
4. MCP server exposes tools/resources for artifact access
5. SQLite index (optional) provides fast artifact search

## Architecture

### Component 1: Meta-Messaging System

**Purpose**: Enable async agent-to-agent communication and progress tracking across sessions

**Design**: Hybrid TodoWrite + mailbox system

#### Message Queue Structure

```text
.sam/messages/
├── inbox/              # Incoming messages per agent
│   ├── discovery/
│   │   └── msg-{id}.md
│   ├── context/
│   ├── research/
│   ├── design/
│   ├── planning/
│   ├── implementation/
│   └── delivery/
├── outbox/             # Sent messages per agent
│   └── [same structure]
└── archive/            # Processed messages
    └── {year}/{month}/
        └── msg-{id}.md
```

#### Message Schema

```yaml
---
id: msg-{{ timestamp }}-{{ uuid }}
from: {{ agent_name }}           # Sending agent
to: {{ agent_name | "broadcast" | "orchestrator" }}
type: {{ message_type }}         # See Message Types below
priority: {{ low | normal | high | critical }}
timestamp: {{ iso8601 }}
related_artifacts: [{{ artifact_id1 }}, {{ artifact_id2 }}]
stage: {{ 1-7 }}
status: {{ pending | delivered | acknowledged | archived }}
---

# {{ Message Subject }}

{{ markdown_body }}

## Metadata

- **Triggered by**: {{ event_or_condition }}
- **Expected action**: {{ action_required }}
- **Deadline**: {{ timestamp | "none" }}

## Related Context

{{ optional_context }}
```

#### Message Types (Example Set)

**Note**: These message types are **examples** to illustrate the meta-messaging capabilities. Implementations should define message types that fit their specific workflow needs. The infrastructure supports arbitrary message types as long as agents subscribe/publish consistently.

**Example message types** (customize for your workflow):

| Type                  | Purpose                            | Sender → Receiver       | Example                                                                   |
| --------------------- | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------- |
| `progress`            | Progress update                    | Agent → Orchestrator    | "Context gathering 60% complete, 15 files analyzed"                       |
| `checkpoint`          | Quality gate reached               | Agent → Orchestrator    | "Quality gate reached: awaiting deterministic check outputs (tests/lint)" |
| `blocking`            | Work blocked                       | Agent → Orchestrator    | "Cannot proceed: Auth method not specified in requirements"               |
| `completion`          | Stage/task complete                | Agent → Orchestrator    | "Discovery stage complete: 12 requirements documented"                    |
| `delegation`          | Task assignment                    | Orchestrator → Agent    | "Begin context gathering for auth module"                                 |
| `query`               | Information request                | Agent → Agent           | "Design agent: What auth patterns exist in codebase?"                     |
| `response`            | Query answer                       | Agent → Agent           | "Context agent: OAuth2 + JWT patterns found in 3 services"                |
| `validation_request`  | Artifact validation                | Agent → Validator       | "Review ARTIFACT:PLAN(SCOPE:auth_service) (e.g. design-auth-service.md)"  |
| `validation_result`   | Validation outcome                 | Validator → Agent       | "Plan review complete: 2 minor suggestions; needs follow-up tasks"        |
| `verification_issue`  | Issue found in verification        | Verifier → Design       | "Missing error handling in auth flow, conflicts with security ADR-003"    |
| `regression_detected` | Regression found in implementation | Verifier → Design       | "New auth code breaks existing user sessions, violates requirement FR-12" |
| `gap_identified`      | Missing functionality/docs         | Verifier → Design       | "No documentation for JWT token refresh, needed for operator runbook"     |
| `design_revision`     | Design update required             | Design → Planning       | "Updated ADR-003 with error handling patterns, requires 3 new tasks"      |
| `plan_update`         | Plan revised with new tasks        | Planning → Orchestrator | "Added tasks 46-48 for error handling, ready for assignment"              |

**Extending message types**:

Projects should define additional message types based on their specific needs:

```yaml
# Example: Custom message types for a data pipeline project
custom_message_types:
  - type: data_quality_issue
    sender: data_validator
    receiver: data_architect
    purpose: "Data validation failures that need schema revision"

  - type: schema_revision
    sender: data_architect
    receiver: pipeline_planner
    purpose: "Schema changes that require pipeline updates"

  - type: performance_degradation
    sender: performance_monitor
    receiver: optimization_specialist
    purpose: "Performance issues requiring architectural review"

  - type: cost_threshold_exceeded
    sender: cost_monitor
    receiver: resource_planner
    purpose: "Cloud costs exceed budget, need resource optimization"
```

**Design principle**: Message types are **not hardcoded** in the infrastructure. The message schema supports arbitrary `type` fields. Agents declare their subscriptions in `.sam/config/subscriptions.yaml`, creating a flexible pub/sub system.

#### TodoWrite Integration

**Progress tracking file**: `.sam/messages/todos/stage-{n}/progress.md`

```markdown
# Stage {{ stage_number }} Progress

## Tasks

- [x] Task 1: Interview stakeholders
  - Completed: 2025-01-27 14:30
  - Artifact: ARTIFACT:INTERVIEW(INTERVIEW:001) (e.g. interview-001.md)
- [ ] Task 2: Document requirements
  - Status: In progress (70%)
  - Blocker: None
  - Artifact: ARTIFACT:REQUIREMENTS(SCOPE:...) (e.g. requirements.md) (draft)

## Checkpoints

- [x] CHECKPOINT(goal-contract): Desired outcome + objectives + acceptance criteria agreed
  - Confirmed: 2025-01-27 15:00
- [ ] CHECKPOINT(decision): Requirements prioritization
  - Pending: Awaiting user input on P0 vs P1 features (part of frontloaded goal agreement)

## Blockers

- None
```

#### Feedback Loop Architecture

**Critical Pattern**: Verification and validation are independent of task execution and create feedback loops to design/planning stages.

**Problem**: Traditional linear pipelines (Design → Plan → Implement → Verify) don't handle discovered issues well:

- Verification finds missing error handling → needs new design decisions
- Validation discovers regressions → needs architectural reassessment
- Testing reveals gaps in requirements → needs holistic design update

**Solution**: Meta-messaging enables asynchronous feedback loops where verification/validation agents communicate directly with design/planning agents, bypassing the orchestrator's linear flow.

**Feedback Loop Types**:

```text
┌─────────────────────────────────────────────────────────────┐
│                    Feedback Loop 1:                          │
│              Verification Issues → Design                     │
│                                                              │
│  Stage 7 (Verifier)                                          │
│      ↓ verification_issue                                    │
│  Stage 4 (Design)                                            │
│      ↓ design_revision                                       │
│  Stage 5 (Planning)                                          │
│      ↓ plan_update                                           │
│  Stage 6 (Implementation) - new tasks                        │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    Feedback Loop 2:                          │
│             Regression Detection → Design                    │
│                                                              │
│  Stage 7 (Verifier)                                          │
│      ↓ regression_detected                                   │
│  Stage 4 (Design) - holistic assessment                      │
│      ↓ design_revision (may update multiple ADRs)           │
│  Stage 5 (Planning)                                          │
│      ↓ plan_update (creates remediation tasks)               │
│  Stage 6 (Implementation)                                    │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    Feedback Loop 3:                          │
│           Documentation Gaps → Design                        │
│                                                              │
│  Stage 7 (Verifier)                                          │
│      ↓ gap_identified                                        │
│  Stage 4 (Design)                                            │
│      ↓ query (to Context agent: "What patterns exist?")      │
│  Stage 2 (Context)                                           │
│      ↓ response (pattern analysis)                           │
│  Stage 4 (Design)                                            │
│      ↓ design_revision (new ADR for docs pattern)            │
│  Stage 5 (Planning)                                          │
│      ↓ plan_update (documentation tasks)                     │
│  Stage 6 (Implementation)                                    │
└─────────────────────────────────────────────────────────────┘
```

**Message Schema for Feedback**:

```yaml
---
id: msg-verification-issue-001
from: verifier
to: design
type: verification_issue
priority: high
timestamp: 2025-01-27T15:30:00Z
related_artifacts:
  - verification-001.md    # Verification report
  - task-045.md           # Task that was implemented
  - adr-003.md            # Related design decision
stage: 7
status: pending
---

# Verification Issue: Missing Error Handling in Auth Flow

## Issue Summary

During Stage 7 verification, discovered missing error handling in JWT authentication
flow implemented in task-045.

## Specific Problems

1. **Conflict with ADR-003**: ADR-003 mandates graceful degradation for auth failures,
   but implementation throws unhandled exceptions

2. **Requirement Violation**: FR-12 requires user-friendly error messages, but
   implementation exposes stack traces to users

3. **Missing Edge Cases**:
   - Expired JWT tokens → no refresh logic
   - Malformed tokens → crashes service
   - Network timeouts → no retry mechanism

## Impact

- **Severity**: High (security + UX)
- **Affected Components**: Auth service, API gateway
- **User Impact**: Service crashes on invalid tokens
- **Security Risk**: Stack traces leak implementation details

## Artifacts

- **Verification report**: `.sam/artifacts/delivery/verification-001.md`
- **Test failures**: `.sam/artifacts/delivery/test-results/test-auth-errors.md`
- **Original task**: `.sam/artifacts/planning/tasks/task-045.md`
- **Related ADR**: `.sam/artifacts/design/decisions/adr-003-auth-error-handling.md`

## Requested Action

Design agent: Please assess holistically based on current architecture and plan:

1. Does ADR-003 need revision to be more explicit about error handling patterns?
2. Should we create a new ADR for standardized error response format?
3. What error handling patterns exist in the codebase (query Context agent)?
4. Are there other auth-related tasks that need similar updates?

## Context for Design Assessment

This is not just a bug fix - it reveals a gap in our architecture decisions.
The original ADR-003 mentioned "graceful degradation" but didn't specify:

- What constitutes an auth error vs. system error
- How to distinguish retryable vs. permanent failures
- What information to log vs. expose to users
- How to handle cascading auth failures across services
```

**Design Agent Response Pattern**:

```yaml
---
id: msg-design-revision-001
from: design
to: planning
type: design_revision
priority: high
timestamp: 2025-01-27T16:45:00Z
related_artifacts:
  - adr-003-rev-2.md      # Revised ADR
  - adr-007-new.md        # New ADR for error responses
  - verification-001.md   # Original issue
stage: 4
status: pending
---

# Design Revision: Authentication Error Handling

## Holistic Assessment

After reviewing verification issue from task-045 and consulting Context agent
about existing patterns, identified systemic gap in error handling architecture.

## Design Updates

### 1. Revised ADR-003 (Authentication Strategy)

**Change**: Added explicit error handling section with:

- Error taxonomy (auth error vs. system error vs. user error)
- Retry policies (exponential backoff for network, no retry for invalid credentials)
- Logging requirements (structured logs with correlation IDs)
- User-facing error messages (generic messages, detailed logs for ops)

**Artifact**: `.sam/artifacts/design/decisions/adr-003-auth-strategy-rev-2.md`

### 2. New ADR-007 (Error Response Format)

**Rationale**: Error handling pattern should be consistent across all services,
not just auth. Created new cross-cutting ADR.

**Decisions**:

- RFC 7807 Problem Details for HTTP APIs
- Structured error codes (e.g., `AUTH_TOKEN_EXPIRED`, `AUTH_TOKEN_MALFORMED`)
- Correlation ID in all error responses
- Sanitized error messages (never expose stack traces)

**Artifact**: `.sam/artifacts/design/decisions/adr-007-error-response-format.md`

### 3. Existing Patterns Analysis

Consulted Context agent (msg-query-001) about existing error handling:

- **Finding**: 3 services already use RFC 7807, 2 use custom format
- **Decision**: Standardize on RFC 7807, migrate custom implementations
- **Impact**: Requires tasks for user-service and payment-service

## Required Planning Updates

These design changes require new tasks:

1. **Task: Implement error handling in auth service** (fixes task-045)
   - Priority: P0 (blocks verification)
   - Estimated: 2-3 hours
   - Dependencies: None

2. **Task: Create RFC 7807 error handler library** (new shared component)
   - Priority: P0 (needed by auth task)
   - Estimated: 4-5 hours
   - Dependencies: None

3. **Task: Refactor user-service error responses** (standardization)
   - Priority: P1 (can be done after auth)
   - Estimated: 2 hours
   - Dependencies: Task 2 complete

4. **Task: Refactor payment-service error responses** (standardization)
   - Priority: P1
   - Estimated: 2 hours
   - Dependencies: Task 2 complete

5. **Task: Add error handling documentation** (operator runbook)
   - Priority: P0 (gaps identified by verifier)
   - Estimated: 3 hours
   - Dependencies: Tasks 1-2 complete

## Architecture Impact

- **New shared library**: RFC 7807 error handler (reusable across services)
- **Breaking change**: NO (error format is additive, existing clients unaffected)
- **Migration path**: Gradual rollout, service by service
- **Rollback plan**: New library is opt-in, can disable per service

## Request to Planning Agent

Please update plan with 5 new tasks above. Task 1 is P0 and blocks verification
completion. Tasks 3-4 are P1 and can be scheduled for next iteration.
```

**Planning Agent Response Pattern**:

````yaml
---
id: msg-plan-update-001
from: planning
to: orchestrator
type: plan_update
priority: high
timestamp: 2025-01-27T17:15:00Z
related_artifacts:
  - plan-rev-3.md           # Updated plan
  - task-046.md             # New task
  - task-047.md             # New task
  - task-048.md             # New task
  - task-049.md             # New task
  - task-050.md             # New task
  - design-revision-001.md  # Design update that triggered this
stage: 5
status: pending
---

# Plan Update: Authentication Error Handling

## Plan Revision

Updated plan to incorporate design changes from ADR-003 revision and new ADR-007.

**Artifact**: `.sam/artifacts/planning/plan-rev-3.md`

## New Tasks Created

### Task-046: Implement error handling in auth service [P0]

**Artifact**: `.sam/artifacts/planning/tasks/task-046.md`

**Description**: Fix authentication error handling to comply with ADR-003 rev-2
and ADR-007. Replace unhandled exceptions with proper error responses.

**Acceptance Criteria**:

- [ ] Expired JWT → 401 with `AUTH_TOKEN_EXPIRED` error code
- [ ] Malformed JWT → 401 with `AUTH_TOKEN_MALFORMED` error code
- [ ] Network timeout → 503 with retry-after header
- [ ] All errors use RFC 7807 format
- [ ] No stack traces in error responses
- [ ] Correlation IDs in all error responses
- [ ] Structured logs with error context

**Dependencies**: Task-047 (RFC 7807 library)

**Estimated effort**: 2-3 hours

**Blocks**: Verification completion (verification-issue-001)

---

### Task-047: Create RFC 7807 error handler library [P0]

**Artifact**: `.sam/artifacts/planning/tasks/task-047.md`

**Description**: Create shared library implementing RFC 7807 Problem Details
format for consistent error responses across all services.

**Acceptance Criteria**:

- [ ] Implements RFC 7807 Problem Details JSON format
- [ ] Supports structured error codes (e.g., AUTH_TOKEN_EXPIRED)
- [ ] Automatic correlation ID generation
- [ ] Stack trace sanitization (never expose to client)
- [ ] Integration with existing logging framework
- [ ] Unit tests with 90%+ coverage
- [ ] Documentation with usage examples

**Dependencies**: None

**Estimated effort**: 4-5 hours

**Blocks**: Task-046, Task-048, Task-049

---

### Task-048: Refactor user-service error responses [P1]

**Artifact**: `.sam/artifacts/planning/tasks/task-048.md`

**Description**: Migrate user-service from custom error format to RFC 7807
using new error handler library.

**Acceptance Criteria**:

- [ ] All endpoints use RFC 7807 error handler
- [ ] Backward compatibility verified (no breaking changes)
- [ ] Error codes mapped to structured format
- [ ] Integration tests updated
- [ ] Error response documentation updated

**Dependencies**: Task-047 complete

**Estimated effort**: 2 hours

**Priority**: P1 (can defer to next iteration)

---

### Task-049: Refactor payment-service error responses [P1]

**Artifact**: `.sam/artifacts/planning/tasks/task-049.md`

**Description**: Migrate payment-service from custom error format to RFC 7807.

**Acceptance Criteria**: [Similar to Task-048]

**Dependencies**: Task-047 complete

**Estimated effort**: 2 hours

**Priority**: P1 (can defer to next iteration)

---

### Task-050: Add error handling documentation [P0]

**Artifact**: `.sam/artifacts/planning/tasks/task-050.md`

**Description**: Document error handling patterns in operator runbook (addresses
gap identified in verification-001).

**Acceptance Criteria**:

- [ ] Error code reference table
- [ ] Troubleshooting guide for common auth errors
- [ ] Log correlation ID lookup instructions
- [ ] Retry policy documentation
- [ ] Examples of error responses

**Dependencies**: Task-046, Task-047 complete

**Estimated effort**: 3 hours

**Blocks**: Verification completion (gap-identified issue)

---

## Task Dependencies

```text
Task-047 (RFC 7807 library)
    ↓
    ├─→ Task-046 (Auth error handling) [P0]
    ├─→ Task-048 (User service) [P1]
    └─→ Task-049 (Payment service) [P1]

Task-046 + Task-047
    ↓
Task-050 (Documentation) [P0]
````

## Updated Plan Status

- **Total tasks**: 50 (was 45)
- **P0 tasks remaining**: 3 (Task-046, Task-047, Task-050)
- **P1 tasks remaining**: 2 (Task-048, Task-049)
- **Estimated time to P0 completion**: 9-11 hours
- **Blocking verification**: Yes (verification cannot complete until P0 tasks done)

## Ready for Assignment

Tasks 046-050 are now ready for implementation agent assignment. Task-047 should
be assigned first (no dependencies), then Task-046 and Task-050 in parallel.

````

**Key Architectural Principles**:

1. **Independent verification**: Stage 7 verifiers don't report to orchestrator for permission,
   they send issues directly to Stage 4 design agents

2. **Holistic design assessment**: Design agents assess issues in context of full architecture,
   not just as isolated bugs

3. **Cascading updates**: Design revisions trigger planning updates, which create new tasks,
   which feed back into implementation

4. **Asynchronous loops**: Feedback loops run concurrently with forward progress,
   don't block the main pipeline

5. **Priority propagation**: Issues marked high-priority cascade that priority through
   design revision → plan update → task creation

#### Agent Subscription Model

**Configuration**: `.sam/config/subscriptions.yaml`

```yaml
subscriptions:
  # Discovery agents subscribe to orchestrator delegations
  discovery:
    subscribe_to:
      - type: delegation
        from: orchestrator
        stage: 1
    publish:
      - type: progress
        to: orchestrator
      - type: completion
        to: orchestrator

  # Context agents subscribe to discovery completion + design queries
  context:
    subscribe_to:
      - type: completion
        from: discovery
      - type: query
        from: design
        topic: "codebase patterns"
    publish:
      - type: progress
        to: orchestrator
      - type: response
        to: [design, planning]

  # Design agents subscribe to context completion + research results + FEEDBACK LOOPS
  design:
    subscribe_to:
      - type: completion
        from: [context, research]
      - type: response
        from: context
      # FEEDBACK LOOP SUBSCRIPTIONS:
      - type: verification_issue
        from: verifier
        priority: high
      - type: regression_detected
        from: verifier
        priority: critical
      - type: gap_identified
        from: verifier
        priority: medium
    publish:
      - type: query
        to: context
      - type: validation_request
        to: validators
      # FEEDBACK LOOP PUBLICATIONS:
      - type: design_revision
        to: planning
        trigger: verification_issue | regression_detected | gap_identified

  # Planning agents subscribe to design completion + FEEDBACK LOOPS
  planning:
    subscribe_to:
      - type: completion
        from: design
      # FEEDBACK LOOP SUBSCRIPTIONS:
      - type: design_revision
        from: design
        priority: high
    publish:
      - type: completion
        to: orchestrator
      # FEEDBACK LOOP PUBLICATIONS:
      - type: plan_update
        to: orchestrator
        trigger: design_revision

  # Verification agents subscribe to implementation completion + PUBLISH FEEDBACK
  verifier:
    subscribe_to:
      - type: completion
        from: implementation
    publish:
      - type: completion
        to: orchestrator
      # FEEDBACK LOOP PUBLICATIONS (direct to design, bypassing orchestrator):
      - type: verification_issue
        to: design
        condition: "Issue conflicts with architecture or violates requirement"
      - type: regression_detected
        to: design
        condition: "Implementation breaks existing functionality"
      - type: gap_identified
        to: design
        condition: "Missing documentation or functionality needed for production"
```

#### Message Delivery Protocol

1. **Send**: Agent writes message to recipient's `inbox/` directory
2. **Notify**: (Optional) Create `.sam/messages/.notify` flag file
3. **Read**: Recipient agent reads inbox on activation
4. **Acknowledge**: Recipient moves message from inbox to `archive/`
5. **Response**: If query, recipient sends response message

#### Persistence Strategy

**Primary**: Filesystem (markdown files)

**Advantages**:

- Human-readable message history
- Git versioning for message audit trail
- Simple grep/find for message search
- No database setup required

**Optional enhancement**: SQLite message index for fast queries

```sql
CREATE TABLE messages (
    id TEXT PRIMARY KEY,
    from_agent TEXT NOT NULL,
    to_agent TEXT NOT NULL,
    type TEXT NOT NULL,
    priority TEXT NOT NULL,
    stage INTEGER,
    timestamp TIMESTAMP NOT NULL,
    status TEXT NOT NULL,
    file_path TEXT NOT NULL,
    FOREIGN KEY (stage) REFERENCES stages(id)
);

CREATE INDEX idx_inbox ON messages(to_agent, status)
    WHERE status = 'pending';
CREATE INDEX idx_type ON messages(type, timestamp);
```

### Component 2: YAML Configuration System

**Purpose**: Declarative agent-task association, capability definition, and workflow specification

#### Agent Definition Schema

**File**: `.sam/agents/{agent-name}.yaml`

```yaml
agent:
  # Identity
  name: {{ agent_name }}
  persona: {{ role_description }}
  version: {{ semver }}

  # SAM stage association
  stage:
    primary: {{ 1-7 }}      # Primary stage for this agent
    secondary: [{{ 2, 3 }}] # Can assist in these stages

  # Capabilities
  capabilities:
    - {{ capability_1 }}    # e.g., "Requirements elicitation"
    - {{ capability_2 }}    # e.g., "Stakeholder interviewing"

  # Tool requirements
  tools:
    required:               # Must have access to these tools
      - Read
      - Grep
      - Glob
      - WebSearch
    optional:               # Nice to have
      - WebFetch
      - mcp__Ref__ref_search_documentation
    restricted:             # Must NOT have access
      - Write              # Discovery is read-only
      - Edit

  # Skills to auto-load
  skills:
    load:
      - research           # Load research skill on activation
      - scientific-thinking
    optional:
      - comprehensive-researcher  # Load if available

  # Model selection
  model:
    default: sonnet-4-5    # Default model for this agent
    reasoning: opus-4-5    # For complex reasoning tasks
    quick: haiku-4-5       # For simple operations
    selection_criteria:
      - use: opus-4-5
        when: "Task requires multi-step reasoning or architectural decisions"
      - use: haiku-4-5
        when: "Task is pure retrieval with no interpretation needed"

  # Git worktree configuration
  worktree:
    enabled: true
    branch_prefix: "sam/discovery"
    sparse_checkout:
      - .sam/artifacts/discovery/
      - docs/
      - requirements/
    identity:
      name: "SAM Discovery Agent"
      email: "discovery@sam.local"

  # Workflows
  workflows:
    - name: stakeholder_interview
      trigger:
        type: delegation
        from: orchestrator
        message_contains: "interview"
      steps:
        - name: prepare_questions
          action: "Read requirements template and prepare interview questions"
        - name: conduct_interview
          action: "Engage with user for stakeholder interview"
          checkpoint: goal-contract
        - name: document_findings
          action: "Create interview-{id}.md artifact"
        - name: extract_requirements
          action: "Extract requirements from interview and update requirements.md"
        - name: notify_completion
          action: "Send completion message to orchestrator"

  # Output artifacts
  outputs:
    artifacts:
      - type: interview
        location: .sam/artifacts/discovery/interviews/
        schema: interview-schema.yaml
      - type: requirements
        location: .sam/artifacts/discovery/
        schema: requirements-schema.yaml
    messages:
      - type: progress
        frequency: "After each interview"
      - type: completion
        trigger: "All planned interviews complete"
      - type: blocking
        trigger: "Conflicting requirements detected"

  # Quality gates
  quality_gates:
    - name: requirements_completeness
      type: automated
      condition: "All P0 requirements have acceptance criteria"
    - name: requirements_consistency
      type: automated
      condition: "No conflicting requirements detected"
      validation_script: .sam/scripts/validate-requirements.py
```

#### Task-Agent Association Configuration

**File**: `.sam/config/pipeline.yaml`

```yaml
sam:
  version: "1.0"
  project: {{ project_name }}

  # Stage definitions
  stages:
    - id: 1
      name: "Discovery & Interview"
      description: "Gather requirements through stakeholder interviews"

      # Agent assignments
      agents:
        - name: discovery
          priority: primary
          activation: auto    # Auto-activate when stage starts
        - name: interview
          priority: secondary
          activation: on-demand  # Activate only if needed

      # Quality gates
      checkpoints:
        - type: goal-contract
          name: goal_agreement
          condition: "Desired outcome + objectives + acceptance criteria agreed and recorded"
          blocking: true      # Stage cannot proceed until checkpoint passes
        - type: decision
          name: scope_finalization
          condition: "Missing prerequisite info resolved (e.g., requirement prioritization P0/P1/P2)"
          blocking: true

      # Stage outputs
      outputs:
        required:
          - .sam/artifacts/discovery/requirements.md
          - .sam/artifacts/discovery/interviews/
        optional:
          - .sam/artifacts/discovery/personas.md

      # Next stage trigger
      completion_criteria:
        - "All P0 requirements documented"
        - "Goal agreement checkpoint passed"
        - "Scope finalization decision made"

    - id: 2
      name: "Context Gathering"
      description: "Analyze codebase for existing patterns and constraints"

      agents:
        - name: context-gatherer
          priority: primary
          activation: auto
          inputs:
            - .sam/artifacts/discovery/requirements.md
        - name: codebase-analyzer
          priority: primary
          activation: auto
          parallelizable: true  # Can run in parallel with context-gatherer

      checkpoints:
        - type: decision
          name: analysis_depth
          condition: "User decides: shallow, medium, or deep codebase analysis"
          options:
            - shallow: "High-level architecture and entry points only"
            - medium: "Key modules and patterns (default)"
            - deep: "Comprehensive analysis including dependencies"

      outputs:
        required:
          - .sam/artifacts/context/codebase-analysis/
          - .sam/artifacts/context/patterns/
        optional:
          - .sam/artifacts/context/dependencies.md
          - .sam/artifacts/context/tech-stack.md

      completion_criteria:
        - "Codebase analysis complete for scope defined in requirements"
        - "Existing patterns documented"
        - "Technical constraints identified"

    # ... Stages 3-7 follow same pattern

  # Global configuration
  global:
    # Model selection policy
    model_policy:
      default_primary: sonnet-4-5
      default_secondary: haiku-4-5
      allow_override: true   # Agents can override per task

    # Tool usage guidance (non-enforced)
    #
    # SAM policy alignment: no tool blocking / no approval gates. This section is
    # guidance for keeping stages focused, not a permission system.
    tool_guidance:
      stages_1_to_3:         # Discovery, Context, Research
        mode: analysis
        prefer: [Read, Grep, Glob, WebSearch, WebFetch]
        avoid: ["source-code edits (prefer writing artifacts/tokens)"]
      stages_4_to_5:         # Design, Planning
        mode: design
        prefer: [Read, Grep, Glob, Write]
        avoid: ["broad refactors (prefer producing ARTIFACT:PLAN / ARTIFACT:ADR first)"]
      stage_6:               # Implementation
        mode: implementation
        prefer: ["deterministic checks in tight loops (tests/lint/build)"]
      stage_7:               # Delivery
        mode: delivery
        prefer: [Read, Grep, Glob, Write]
        avoid: ["new feature work (prefer ARTIFACT:VERIFICATION + ARTIFACT:RELEASE_NOTES)"]

    # Checkpoint defaults
    checkpoint_defaults:
      goal-contract:
        timeout: 24h        # Max time to wait for goal agreement / missing prerequisite info
        escalation: notify
      decision:
        timeout: 48h
        escalation: notify
      human-action:
        timeout: none       # No timeout, wait indefinitely
```

#### Skill Loading Specification

**File**: `.sam/config/skill-loading.yaml`

```yaml
skill_loading:
  # Global skills (loaded for all agents)
  global:
    - CLAUDE                      # Core identity and protocols
    - subagent-contract          # Subagent boundaries and signaling
    - structured-context-protocol # SCP rule enforcement

  # Stage-specific skills
  stage_skills:
    1:  # Discovery
      - research
      - rt-ica                   # Information Completeness Assessment
    2:  # Context
      - research
      - scientific-thinking
    3:  # Research
      - research
      - comprehensive-researcher
      - scientific-thinking
    4:  # Design
      - how-to-delegate         # For orchestrating design review
      - documentation-expert    # For creating architecture docs
    5:  # Planning
      - how-to-delegate
      - gsd:plan-phase          # GSD planning patterns
    6:  # Implementation
      - python3-development     # If Python project
      - holistic-linting        # Code quality
      - commit-staged           # Git commit discipline
    7:  # Delivery
      - verify                  # Self-assessment before completion
      - am-i-complete          # Completion verification
      - is-it-done             # Final verification

  # Agent-specific skills (override stage defaults)
  agent_skills:
    discovery:
      - research
      - rt-ica
      - comprehensive-researcher  # Discovery benefits from deep research
    context-gatherer:
      - research
      - scientific-thinking
      - trace-protocol-investigator  # For systematic exploration
    codebase-analyzer:
      - code-analysis           # Custom skill for codebase analysis
      - scientific-thinking
```

#### Example Configuration Usage

**Orchestrator workflow**:

```python
# Pseudo-code: How orchestrator uses YAML config
def activate_stage(stage_id: int):
    config = load_yaml('.sam/config/pipeline.yaml')
    stage = config['stages'][stage_id - 1]

    # Check prerequisites
    if not check_completion_criteria(stage_id - 1):
        raise StageNotReadyError(f"Stage {stage_id - 1} not complete")

    # Activate agents
    for agent_config in stage['agents']:
        if agent_config['activation'] == 'auto':
            agent = load_agent_definition(agent_config['name'])
            activate_agent(agent, stage_inputs=stage.get('inputs', []))

    # Monitor checkpoints
    while not stage_complete(stage_id):
        check_quality_gates(stage['checkpoints'])
        monitor_agent_progress()

    # Verify outputs
    verify_outputs(stage['outputs']['required'])

    # Trigger next stage
    if all_criteria_met(stage['completion_criteria']):
        activate_stage(stage_id + 1)
```

### Component 3: Artifact Storage System

**Purpose**: Persistent, structured, version-controlled storage for all SAM process artifacts

#### Directory Structure

This is an **example filesystem-backed implementation**. Treat these paths as *one* possible storage backend for the canonical `ARTIFACT:*` tokens.

```text
.sam/
├── artifacts/
│   ├── discovery/
│   │   ├── requirements.md
│   │   ├── interviews/
│   │   │   ├── interview-001.md
│   │   │   ├── interview-002.md
│   │   │   └── ...
│   │   ├── personas/
│   │   │   └── persona-{role}.md
│   │   └── constraints.md
│   ├── context/
│   │   ├── codebase-analysis/
│   │   │   ├── analysis-{component}.md
│   │   │   ├── dependencies.md
│   │   │   └── entry-points.md
│   │   ├── patterns/
│   │   │   ├── pattern-{name}.md
│   │   │   └── anti-patterns.md
│   │   └── tech-stack.md
│   ├── research/
│   │   ├── research-{topic}.md
│   │   └── references/
│   │       └── reference-{id}.md
│   ├── design/
│   │  

…(truncated)