tools-only 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:
ARTIFACT:{TYPE}({SCOPE_OR_ID})
Common artifact types used in this infrastructure doc (extend as needed):
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):
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
┌─────────────────────────────────────────────────────────────┐
│ 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:
- Each stage produces canonical
ARTIFACT:*tokens (optionally materialized as.sam/artifacts/{stage}/...in a filesystem backend) - Agents communicate via messages (optionally materialized as
.sam/messages/...in a filesystem backend) - Git worktrees isolate concurrent work per stage
- MCP server exposes tools/resources for artifact access
- 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
.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
---
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:
# 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
# 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:
┌─────────────────────────────────────────────────────────────┐
│ 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:
---
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:
---
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:
---
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)