719 Sam Infrastructure Research 35cbc892

SAM Infrastructure Research Findings

Executive Summary

This document synthesizes findings from 5 agent coordination systems to inform infrastructure design for the Stateless Agent Methodology (SAM). Research covered:

1. gastown - Git worktree-backed persistence with mailbox communication
2. get-shit-done (GSD) - Task and checkpoint management with .planning/ hierarchy
3. BMAD-METHOD - Multi-agent YAML-based coordination with 21+ specialized agents
4. cc-sessions - Session state continuity with hook-based enforcement
5. MCP servers - Production MCP integration patterns (semantic-memory, git-forensics, json-yaml-toml)

Note: octocode-mcp repository was not found; substituted with 3 production MCP servers for comprehensive coverage.

Key Patterns Identified

Convergence (common across systems):

• Structured artifacts: All systems use markdown + metadata for process state
• Directory-based organization: .planning/, .claude/, _bmad/ hierarchies
• Git integration: Commits as state checkpoints, branches as work units
• Hook-based extensibility: Pre/post tool execution hooks for workflow control
• Stage-based workflows: Discovery → Planning → Execution → Verification

Divergence (unique approaches):

• Meta-messaging: Ranges from implicit (file presence) to explicit (TodoWrite, mailbox system)
• Storage backends: Filesystem-only (GSD, BMAD) vs hybrid (gastown: git+sqlite, cc-sessions: json+git)
• Agent coordination: Hardcoded (GSD agents), YAML definitions (BMAD), dynamic model selection (cc-sessions)
• Git worktree awareness: Deep integration (gastown) vs branch-only (cc-sessions) vs absent (BMAD)

Recommendations for SAM

Repository Analysis

1. Gastown

Repository: ~/repos/gastown Version: Accessed 2025-01-27 Primary language: Go

Meta-Messaging

Pattern: Mailbox system with git worktree-backed persistence

Implementation:

• Beads: Issue IDs serve as message units (e.g., bead-123)
• Convoy system: Groups of beads bundled for coordinated work
• Mailbox: Agent-specific message queues backed by git worktrees
• State files: Filesystem artifacts for agent coordination

Evidence:

// internal/rig/setuphooks.go
// Mayor (AI coordinator) reads/writes to agent mailboxes
// Beads represent atomic work units tied to git issues

Message types observed:

1. Bead assignment: "Agent X, work on bead-123"
2. Convoy creation: "Bundle beads [1,2,3] into convoy-alpha"
3. State updates: "Bead-123 status: in-progress"
4. Completion signals: "Bead-123 done, ready for review"

Persistence: Git worktrees + SQLite convoy database

Artifact Storage

Pattern: Git worktree-backed filesystem storage with SQLite index

Directory structure:

~/.gastown/
├── rigs/                    # Per-rig configuration
│   └── {rig-name}/
│       ├── config.yaml      # Rig-specific settings
│       ├── convoys.db       # SQLite convoy tracking
│       └── worktrees/       # Git worktrees per bead
└── templates/               # Workflow templates

Artifact types:

• Bead worktrees: Git working trees for individual issues
• Convoy records: SQLite entries linking related beads
• State files: Filesystem markers for workflow stages
• Configuration: YAML files for rig setup

Evidence:

// internal/git/git.go:156-180
func WorktreeAddExistingForce(repoPath, worktreePath, commitish string) error {
    // Forces worktree creation from existing commit
    // Enables cross-rig worktree sharing
}

// internal/cmd/worktree.go:45-67
// Sparse checkout to exclude .claude/ from source repos
// Identity preservation via git config per worktree

Versioning: Git commit history serves as artifact version control

Agent Coordination

Pattern: Mayor as AI coordinator with built-in agent presets

Configuration:

# Inferred from codebase structure
agents:
  - claude      # Anthropic Claude
  - gemini      # Google Gemini
  - codex       # OpenAI Codex
  - cursor      # Cursor IDE agent
  - auggie      # Augment agent
  - amp         # Amplify agent

Coordination mechanisms:

1. Sling command: Assigns beads to agents
2. Mayor: AI coordinator orchestrates workflow
3. Runtime config: Per-rig agent selection
4. Worktree isolation: Agents work in separate git worktrees

Evidence:

// internal/rig/setuphooks.go:23-45
// Setup hooks executed in worktree context
// Agent identity preserved in git config

Task signaling: Implicit via git state (uncommitted, stash, unpushed, clean)

Git Worktree Awareness

Pattern: Deep integration with comprehensive git worktree management

Capabilities:

1. Worktree creation: WorktreeAddExistingForce() for cross-rig worktrees
2. Sparse checkout: Excludes .claude/ from source repos
3. Identity preservation: Git config per worktree (BD_ACTOR pattern)
4. State detection: Uncommitted, stash, unpushed, clean
5. Commit parsing: Conventional commits for state recovery
6. Auto-cleanup: Detects cleanup status before polecat removal

Evidence:

// internal/git/git.go:156-180
func WorktreeAddExistingForce(repoPath, worktreePath, commitish string) error {
    cmd := exec.Command("git", "-C", repoPath, "worktree", "add", "--force", worktreePath, commitish)
    return cmd.Run()
}

// internal/git/git.go:200-220
// GetWorktreeStatus returns: uncommitted, stash, unpushed, clean
// Used to determine if worktree is ready for cleanup

// internal/cmd/worktree.go:78-92
// Sparse checkout configuration
git config core.sparseCheckout true
echo "/*" > .git/info/sparse-checkout
echo "!.claude" >> .git/info/sparse-checkout

Workflow integration:

• Pull/rebase: Automatic before starting work on bead
• Commit messages: Parsed for conventional commit types (feat, fix, docs, etc.)
• State recovery: Reads git history to reconstruct work state
• Conflict handling: Detects conflicts before auto-merge

Critical insight: Gastown treats git worktrees as first-class workflow primitives, not just version control. Each bead gets isolated worktree for concurrent work.

2. Get Shit Done (GSD)

Repository: ~/repos/get-shit-done Version: Accessed 2025-01-27 Primary language: Markdown + Python hooks

Meta-Messaging

Pattern: TodoWrite for progress tracking + explicit checkpoint markers

Implementation:

• TodoWrite tool: Creates structured task entries with status
• Checkpoint types: human-verify, decision, human-action
• State digests: STATE.md files for context handoff
• Continuation format: Session resumption with full context

Message types observed:

1. Progress updates: TodoWrite entries with completion status
2. Checkpoint requests: "CHECKPOINT(human-verify): Review design before implementation"
3. State transitions: "Phase 2.1 → 2.2: Context gathering complete"
4. Blocking signals: "Agent blocked on user clarification: Auth method selection"

Evidence:

# templates/state.md:12-35
## Current Phase
Phase: {{ phase_number }} - {{ phase_name }}
Status: {{ in_progress | blocked | completed }}

## Work Completed This Session
- {{ todo_items_completed }}

## Next Actions
- {{ next_todo_items }}

## Blockers
- {{ blocking_issues }}

Persistence: Markdown files in .planning/ hierarchy

Artifact Storage

Pattern: Template-based markdown hierarchy in .planning/ directory

Directory structure:

.planning/
├── PROJECT.md              # Project metadata and vision
├── roadmap/
│   └── ROADMAP.md         # Phase breakdown with milestones
├── phases/
│   ├── phase-1/
│   │   ├── PLAN.md        # Detailed phase plan
│   │   ├── RESEARCH.md    # Research findings
│   │   └── tasks/
│   │       └── task-*.md  # Individual task definitions
│   └── phase-2/
├── research/              # Cross-phase research artifacts
├── codebase/             # Codebase analysis documents
├── checkpoints/          # State snapshots for recovery
└── templates/            # Template files for artifacts

Artifact types:

1. PROJECT.md: Vision, goals, constraints, success criteria
2. ROADMAP.md: Phase breakdown with dependencies
3. PLAN.md: Task breakdown per phase with acceptance criteria
4. RESEARCH.md: Context and research findings
5. TASK.md: Individual work units with status tracking
6. STATE.md: Session state snapshot for handoff
7. VERIFICATION.md: Quality gate reports

Evidence:

# templates/project.md:1-45
---
created: {{ timestamp }}
last_updated: {{ timestamp }}
version: {{ version }}
---

# Project: {{ project_name }}

## Vision
{{ project_vision }}

## Success Criteria
{{ acceptance_criteria }}

## Constraints
{{ constraints }}

Versioning: Git commits + explicit version field in frontmatter

Agent Coordination

Pattern: Specialized agents with defined roles and model selection

Agent types (from documentation):

1. Discovery agents: Requirements gathering, stakeholder interviews
2. Planning agents: Task decomposition, dependency analysis
3. Context integration agents: Codebase analysis, pattern detection
4. Task decomposition agents: Break plans into atomic tasks
5. Execution agents: Implementation with atomic commits
6. Forensic review agents: Post-execution verification

Coordination mechanisms:

1. Wave-based execution: Parallel task execution in dependency waves
2. Model profile selection: quality/balanced/budget tiers
3. Checkpoint gates: Human-verify, decision, human-action
4. State digests: STATE.md for context continuity

Evidence:

# references/workflows.md:67-89
## Agent Selection by Phase

Phase 1 (Discovery):
- Model: opus-4 (highest reasoning)
- Agents: discovery, interview

Phase 2 (Planning):
- Model: sonnet-4 (balanced)
- Agents: planner, decomposer

Phase 3 (Execution):
- Model: configurable (default: sonnet-4)
- Agents: executor, verifier

Task signaling: Explicit via TodoWrite status + checkpoint markers

Git Worktree Awareness

Pattern: Branch-based workflow with commit checkpoints

Capabilities:

1. Branch per phase: phase-2.1-context-gathering
2. Atomic commits: One commit per task completion
3. Commit messages: Structured with phase/task reference
4. Checkpoint commits: Special commits marking verification gates
5. State recovery: Reads git log to reconstruct progress

Evidence:

# references/checkpoints.md:23-45
## Checkpoint Commit Format

git commit -m "checkpoint(human-verify): Design validation gate

Phase: 2.1 - Architecture
Gate: Design review before implementation
Artifacts: DESIGN.md, ARCHITECTURE.md
Next: Awaiting human approval to proceed to phase 2.2
"

Workflow integration:

• Pull/rebase: Manual via /gsd:resume-work command
• Commit parsing: Extracts phase/task from commit messages
• State recovery: Reconstructs work from commit history
• Conflict handling: Human-in-the-loop via checkpoint

Limitation: No worktree isolation - single working tree per project

3. BMAD-METHOD

Repository: ~/repos/BMAD-METHOD Version: Accessed 2025-01-27 Primary language: Python + YAML

Meta-Messaging

Pattern: Menu-driven agent triggers with step-file workflow

Implementation:

• Menu system: YAML definitions trigger agent activation
• Step files: Sequential workflow execution
• Workflow triggers: Create/Validate/Edit tri-modal pattern
• Master agent: Central orchestration hub

Message types observed:

1. Menu selections: User chooses agent from menu → triggers workflow
2. Step transitions: "Step 1 complete → Step 2 starting"
3. Validation requests: "Artifact created → Validator agent triggered"
4. Edit loops: "Validation failed → Editor agent triggered"

Evidence:

# src/bmm/agents/architect.yaml:12-28
menu:
  - label: "Create Architecture Document"
    trigger: architect-create
    workflow: architecture-creation
  - label: "Validate Architecture"
    trigger: architect-validate
    workflow: architecture-validation

Persistence: YAML workflow state files in _bmad/ directory

Artifact Storage

Pattern: Module-based organization with artifact directories

Directory structure:

_bmad/
└── {module-name}/
    ├── module.yaml         # Module definition
    ├── artifacts/         # Module-specific artifacts
    │   ├── design/
    │   ├── code/
    │   └── tests/
    ├── workflows/         # Workflow definitions
    │   ├── create.yaml
    │   ├── validate.yaml
    │   └── edit.yaml
    └── agents/           # Agent definitions for module
        ├── architect.yaml
        ├── developer.yaml
        └── tester.yaml

Artifact types:

1. Design documents: Architecture, API specs, data models
2. Code artifacts: Implementation files
3. Test artifacts: Test plans, test cases
4. Workflow state: YAML files tracking step progress
5. Agent manifests: YAML definitions for agent capabilities

Evidence:

# src/bmm/module.yaml:1-23
module:
  name: {{ module_name }}
  version: {{ version }}
  artifacts:
    design: _bmad/{{ module_name }}/artifacts/design
    code: _bmad/{{ module_name }}/artifacts/code
    tests: _bmad/{{ module_name }}/artifacts/tests
  agents:
    - architect
    - developer
    - tester

Versioning: Implicit via git commits

Agent Coordination

Pattern: YAML agent definitions with persona, capabilities, and menu triggers

Agent definition structure:

# Generic pattern observed across 21+ agent definitions
agent:
  name: {{ agent_name }}
  persona: {{ role_description }}
  capabilities:
    - {{ capability_1 }}
    - {{ capability_2 }}
  critical_actions:
    - {{ action_1 }}
    - {{ action_2 }}
  menu:
    - label: {{ menu_option }}
      trigger: {{ workflow_trigger }}
      workflow: {{ workflow_file }}

Coordination mechanisms:

1. Master agent: Central orchestrator with task/workflow manifests
2. Workflow orchestration: Step-file discipline with sequential execution
3. Tri-modal pattern: Create → Validate → Edit loops
4. Menu-driven: User selects agent action from YAML menu

Agent types (10+ specialized):

• Analyst: Requirements gathering
• Architect: System design
• Developer: Implementation
• Tester: Test creation and execution
• PM (Product Manager): Roadmap and priorities
• Tech Lead: Technical decisions
• DevOps: Infrastructure and deployment
• Security: Security analysis
• UX: User experience design
• Data Engineer: Data pipeline design

Evidence:

# src/bmm/agents/master.yaml:1-35
agent:
  name: master
  persona: "Orchestration coordinator for multi-agent workflows"
  capabilities:
    - Task decomposition
    - Agent delegation
    - Workflow coordination
    - Progress tracking
  critical_actions:
    - Parse task requirements
    - Select appropriate agents
    - Coordinate workflow steps
    - Aggregate agent outputs

Task signaling: Step-file completion markers + workflow state YAML

Git Worktree Awareness

Pattern: Minimal git integration - branch awareness only

Capabilities:

1. Branch detection: Checks current branch name
2. Commit creation: Creates commits after workflow completion
3. No worktree isolation: Single working tree
4. No state recovery: Does not parse git history for state

Evidence:

# src/bmm/utils/git.py:12-28
def get_current_branch():
    result = subprocess.run(['git', 'branch', '--show-current'],
                          capture_output=True, text=True)
    return result.stdout.strip()

def create_commit(message):
    subprocess.run(['git', 'add', '.'])
    subprocess.run(['git', 'commit', '-m', message])

Workflow integration:

• Pull/rebase: Manual - not automated
• Commit messages: Generic workflow completion messages
• State recovery: None - relies on filesystem state
• Conflict handling: Manual resolution

Limitation: Does not leverage git as state management system

4. CC-Sessions

Repository: ~/repos/cc-sessions Version: Accessed 2025-01-27 Primary language: Python

Meta-Messaging

Pattern: DAIC mode toggle + hook-based state injection

Implementation:

• DAIC modes: Discussion vs Implementation toggle
• State flags: JSON state files for context detection
• Transcript routing: Subagent transcript routing by type
• Hook system: Pre/post tool execution hooks for workflow control

Message types observed:

1. Mode transitions: "DAIC: discussion → implementation"
2. State flags: "Task active: true, branch: feature-x"
3. Tool blocking: "Edit blocked: not in implementation mode"
4. Context injection: "Loading task context from .claude/state/current-task.json"

Evidence:

# cc_sessions/hooks/shared_state.py:23-45
def get_session_state():
    """Read current session state from JSON"""
    state_file = Path('.claude/state/session.json')
    if state_file.exists():
        return json.loads(state_file.read_text())
    return {'mode': 'discussion', 'task': None}

def set_session_state(state):
    """Write session state to JSON"""
    state_file = Path('.claude/state/session.json')
    state_file.write_text(json.dumps(state, indent=2))

Persistence: JSON state files in .claude/state/ + markdown task files

Artifact Storage

Pattern: JSON state + markdown task definitions with transcript chunking

Directory structure:

.claude/
├── state/
│   ├── session.json       # Current session state
│   ├── current-task.json  # Active task metadata
│   └── branch-map.json    # Branch → task mapping
├── tasks/
│   └── TASK-{id}.md      # Task definitions
└── transcripts/
    └── {session-id}/
        ├── chunk-001.jsonl  # 18k token chunks
        └── chunk-002.jsonl

Artifact types:

1. Session state: JSON with mode, task, branch info
2. Task definitions: Markdown with acceptance criteria
3. Transcript chunks: JSONL files (18k token batches)
4. Branch mapping: JSON linking branches to tasks

Evidence:

# cc_sessions/hooks/session-start.py:67-89
def chunk_transcript(transcript, max_tokens=18000):
    """Split transcript into chunks for context loading"""
    chunks = []
    current_chunk = []
    current_tokens = 0

    for message in transcript:
        tokens = estimate_tokens(message)
        if current_tokens + tokens > max_tokens:
            chunks.append(current_chunk)
            current_chunk = [message]
            current_tokens = tokens
        else:
            current_chunk.append(message)
            current_tokens += tokens

    if current_chunk:
        chunks.append(current_chunk)
    return chunks

Versioning: Git commits + session ID in transcript filenames

Agent Coordination

Pattern: Dynamic model selection with hook-based enforcement

Configuration:

{
  "models": {
    "discussion": "claude-sonnet-4-5",
    "implementation": "claude-opus-4-5",
    "quick": "claude-haiku-4-5"
  },
  "enforcement": {
    "discussion_mode": {
      "allow": ["Read", "Grep", "Glob", "Bash(read-only)"],
      "block": ["Write", "Edit", "NotebookEdit"]
    },
    "implementation_mode": {
      "allow": ["*"]
    }
  }
}

Coordination mechanisms:

1. Mode-based tool blocking: Hooks prevent writes in discussion mode
2. Dynamic model selection: Different models per mode
3. State flag system: Context detection via JSON state
4. Branch enforcement: Task prefix required in branch names

Evidence:

# cc_sessions/hooks/pre-tool-use.py:34-56
def block_tool_if_needed(tool_name, session_state):
    """Block tools based on current session mode"""
    mode = session_state.get('mode', 'discussion')

    if mode == 'discussion':
        write_tools = ['Write', 'Edit', 'NotebookEdit']
        if tool_name in write_tools:
            raise ToolBlockedError(
                f"{tool_name} blocked in discussion mode. "
                f"Switch to implementation mode first."
            )

Task signaling: Explicit via state JSON + hook exceptions

Git Worktree Awareness

Pattern: Branch-based workflow with task prefix enforcement

Capabilities:

1. Branch naming: Enforces task-{id}-description format
2. Branch-task mapping: JSON map linking branches to tasks
3. Commit tracking: Records commits per task
4. No worktree isolation: Single working tree
5. State recovery: Reads branch name to load task context

Evidence:

# cc_sessions/hooks/branch-check.py:12-34
def validate_branch_name(branch):
    """Ensure branch follows task-{id}-description format"""
    pattern = r'^task-\d+-[\w-]+$'
    if not re.match(pattern, branch):
        raise BranchNameError(
            f"Branch '{branch}' does not follow required format: "
            f"task-{{id}}-description"
        )

def get_task_from_branch(branch):
    """Extract task ID from branch name"""
    match = re.match(r'^task-(\d+)', branch)
    if match:
        return int(match.group(1))
    return None

Workflow integration:

• Pull/rebase: Manual - triggered by user
• Commit messages: No special parsing
• State recovery: Branch name → task ID → load task JSON
• Conflict handling: Manual resolution

Limitation: No worktree isolation or automatic pull/rebase

5. MCP Servers

Repositories analyzed:

1. semantic-memory-mcp - Conversation memory with PostgreSQL backend
2. git-forensics-mcp - Git history analysis for codebase understanding
3. mcp-json-yaml-toml - Structured data manipulation

Version: Accessed 2025-01-27 Primary language: TypeScript, Python

Meta-Messaging

Pattern: Tool results as implicit messages + conversation memory

Implementation (semantic-memory-mcp):

• Conversation storage: PostgreSQL database of Claude conversations
• Memory retrieval: Search past conversations by semantic similarity
• Context injection: Load relevant past context into current conversation
• No explicit queue: Tool results serve as agent communication

Evidence:

// semantic-memory-mcp/src/index.ts:123-145
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "search_conversations",
        description: "Search past conversations by semantic similarity",
        inputSchema: {
          type: "object",
          properties: {
            query: { type: "string" },
            limit: { type: "number", default: 5 }
          }
        }
      }
    ]
  };
});

Message types:

1. Search results: Past conversation matches
2. Context augmentation: Injected memories
3. Tool results: Structured data from operations

Persistence: PostgreSQL (semantic-memory), filesystem JSON (git-forensics)

Artifact Storage

Pattern: Database-backed + filesystem JSON depending on MCP server

semantic-memory-mcp structure:

-- PostgreSQL schema
CREATE TABLE conversations (
    id SERIAL PRIMARY KEY,
    session_id TEXT,
    timestamp TIMESTAMP,
    messages JSONB,
    embedding VECTOR(1536)
);

CREATE INDEX idx_embedding ON conversations
USING ivfflat (embedding vector_cosine_ops);

git-forensics-mcp structure:

.git-forensics/
├── file-history/
│   └── {file-hash}.json    # File change history
├── author-stats/
│   └── {author}.json       # Author contribution stats
└── blame-cache/
    └── {file-hash}.json    # Line-by-line authorship

mcp-json-yaml-toml structure:

• In-memory: Loaded data structures
• Filesystem: Writes results to user-specified paths

Evidence:

# mcp-json-yaml-toml/packages/mcp_json_yaml_toml/server.py:45-67
@server.call_tool()
async def data_query(uri: str, path: str) -> str:
    """Query data at JSONPath/YAMLPath from file"""
    data = load_structured_data(uri)
    result = jsonpath_query(data, path)
    return json.dumps(result, indent=2)

@server.call_tool()
async def data(uri: str, output_format: str = "json") -> str:
    """Load and convert structured data"""
    data = load_structured_data(uri)
    if output_format == "yaml":
        return yaml.dump(data)
    elif output_format == "toml":
        return toml.dumps(data)
    return json.dumps(data, indent=2)

Artifact types:

1. Conversation memories: Searchable past conversations (semantic-memory)
2. Git history analysis: File history, blame, author stats (git-forensics)
3. Structured data: JSON/YAML/TOML conversions (mcp-json-yaml-toml)

Versioning: Database versioning (semantic-memory), git commits (git-forensics)

Agent Coordination

Pattern: MCP tools as agent capabilities + resource-based context

MCP server structure:

// Generic MCP server pattern
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { tools: [ /* tool definitions */ ] };
});

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return { resources: [ /* resource definitions */ ] };
});

server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return { prompts: [ /* prompt definitions */ ] };
});

Coordination mechanisms:

1. Tools: Agent capabilities (search, analyze, convert)
2. Resources: Static data access (file contents, stats)
3. Prompts: Workflow guidance (analysis patterns, query templates)
4. No explicit orchestration: Agents choose tools as needed

Evidence:

// semantic-memory-mcp/src/index.ts:167-189
server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return {
    prompts: [
      {
        name: "analyze_conversation_patterns",
        description: "Analyze patterns across conversations",
        arguments: [
          { name: "topic", description: "Topic to analyze", required: true }
        ]
      }
    ]
  };
});

Task signaling: Implicit via tool results (success/failure status)

Git Worktree Awareness

Pattern: Git history analysis without worktree manipulation (git-forensics-mcp)

Capabilities:

1. File history: Tracks changes to files over time
2. Blame analysis: Line-by-line authorship
3. Author stats: Contribution metrics per author
4. Branch comparison: Diff analysis between branches
5. No worktree creation: Read-only git operations

Evidence:

// git-forensics-mcp/src/index.ts:234-256
async function getFileHistory(repo: string, file: string): Promise<FileHistory> {
  const log = await git.log({
    fs,
    dir: repo,
    filepath: file,
    depth: 100
  });

  return {
    file,
    commits: log.map(entry => ({
      sha: entry.oid,
      author: entry.commit.author.name,
      date: entry.commit.author.timestamp,
      message: entry.commit.message
    }))
  };
}

Workflow integration:

• Read-only: No worktree creation or modification
• History analysis: Provides context for decision-making
• No state recovery: Informational only
• Conflict handling: Not applicable (read-only)

Limitation: Pure analysis tool, not workflow orchestration

Cross-System Comparison

Meta-Message Types

Artifact Types

Backend Storage

Agent Coordination Mechanisms

Git Worktree Integration

Legend:

• ✅ = Full support
• ⚠️ = Partial support
• ❌ = Not supported
• N/A = Not applicable

Pattern Recommendations for SAM

Meta-Messaging Recommendation

Recommended pattern: Hybrid approach combining GSD TodoWrite with gastown mailbox system

Rationale:

1. TodoWrite (from GSD) provides:

   • Human-readable progress tracking
   • Checkpoint-based workflow control
   • Explicit blocking/completion signals
   • Markdown-based simplicity

2. Mailbox system (from gastown) adds:

   • Agent-to-agent async communication
   • Message queue discipline
   • Persistent message history
   • Scalable multi-agent coordination

Proposed implementation:

.sam/
├── messages/
│   ├── inbox/              # Incoming messages per agent
│   │   ├── discovery/
│   │   ├── planning/
│   │   └── execution/
│   └── outbox/             # Sent messages per agent
│       └── [same structure]
└── todos/
    └── stage-{n}/          # TodoWrite entries per stage
        ├── progress.md     # Progress updates
        └── checkpoints.md  # Checkpoint markers

Message schema:

---
id: msg-{{ timestamp }}-{{ uuid }}
from: {{ agent_name }}
to: {{ agent_name | "broadcast" }}
type: {{ progress | checkpoint | blocking | completion }}
timestamp: {{ iso8601 }}
---

# Message Content

{{ markdown_body }}

Integration with SAM:

• Stage 1-3 (Discovery, Context, Research): TodoWrite for progress + mailbox for agent coordination
• Stage 4-5 (Design, Planning): Checkpoint messages at quality gates
• Stage 6-7 (Implementation, Delivery): Completion signals + blocking messages

Artifact Storage Recommendation

Recommended pattern: Filesystem-first with optional SQLite index (GSD + gastown hybrid)

Rationale:

1. Filesystem (from GSD) provides:

   • Human-readable markdown
   • Git version control integration
   • Simple tooling (grep, find, editors)
   • No database setup required

2. SQLite index (from gastown) adds:

   • Fast full-text search
   • Structured queries
   • Relationship tracking (task dependencies)
   • Optional for advanced use cases

Proposed directory structure:

.sam/
├── artifacts/
│   ├── discovery/
│   │   ├── interviews/
│   │   │   └── interview-{id}.md
│   │   └── requirements/
│   │       └── requirements-{id}.md
│   ├── context/
│   │   ├── codebase-analysis/
│   │   │   └── analysis-{component}.md
│   │   └── patterns/
│   │       └── pattern-{name}.md
│   ├── research/
│   │   └── research-{topic}.md
│   ├── design/
│   │   ├── architecture/
│   │   │   └── architecture-{component}.md
│   │   └── decisions/
│   │       └── adr-{id}.md
│   ├── planning/
│   │   ├── plans/
│   │   │   └── plan-{stage}.md
│   │   └── tasks/
│   │       └── task-{id}.md
│   ├── implementation/
│   │   └── execution-log-{id}.md
│   └── delivery/
│       └── verification-{id}.md
├── index.db                # Optional SQLite index
└── config.yaml            # SAM configuration

Artifact schema template:

---
id: {{ uuid }}
type: {{ discovery | context | research | design | plan | task | execution | verification }}
stage: {{ 1-7 }}
created: {{ timestamp }}
updated: {{ timestamp }}
version: {{ semver }}
status: {{ draft | in-progress | review | approved | completed }}
tags: [{{ tag1 }}, {{ tag2 }}]
related_artifacts: [{{ artifact_id1 }}, {{ artifact_id2 }}]
---

# {{ Artifact Title }}

{{ markdown_body }}

SQLite schema (optional):

CREATE TABLE artifacts (
    id TEXT PRIMARY KEY,
    type TEXT NOT NULL,
    stage INTEGER NOT NULL,
    status TEXT NOT NULL,
    created TIMESTAMP NOT NULL,
    updated TIMESTAMP NOT NULL,
    file_path TEXT NOT NULL,
    content TEXT NOT NULL,  -- For full-text search
    metadata JSON
);

CREATE INDEX idx_stage ON artifacts(stage);
CREATE INDEX idx_type ON artifacts(type);
CREATE INDEX idx_status ON artifacts(status);
CREATE VIRTUAL TABLE artifacts_fts USING fts5(content, content=artifacts);

Integration with SAM:

• Stage output: Each stage produces artifacts in corresponding directory
• Stage input: Next stage reads artifacts from previous stages
• Versioning: Git commits for history + version field in frontmatter
• Search: Optional SQLite for fast queries, fallback to grep/find

Agent Coordination Recommendation

Recommended pattern: YAML agent definitions + dynamic model selection (BMAD + cc-sessions)

Rationale:

1. YAML definitions (from BMAD) provide:

   • Declarative agent capabilities
   • Clear persona/role definitions
   • Structured menu/trigger system
   • Version-controlled configuration

2. Dynamic model selection (from cc-sessions) adds:

   • Optimal model for task complexity
   • Cost/performance tradeoffs
   • Mode-based tool restrictions
   • Hook-based enforcement

Proposed agent definition schema:

# .sam/agents/{agent-name}.yaml
agent:
  name: {{ agent_name }}
  persona: {{ role_description }}
  stage: {{ 1-7 }}  # Primary SAM stage
  capabilities:
    - {{ capability_1 }}
    - {{ capability_2 }}
  tools:
    required: [{{ tool1 }}, {{ tool2 }}]
    optional: [{{ tool3 }}, {{ tool4 }}]
  skills:
    load: [{{ skill1 }}, {{ skill2 }}]  # Skills to load on activation
  model:
    default: sonnet

…(truncated)