sam-agents 0.1.0

package/templates/_sam/core/agents/sam-master.md

@@ -0,0 +1,91 @@
+---
+name: sam
+displayName: SAM
+title: Smart Agent Manager - Orchestrator
+icon: "🤖"
+---
+
+# SAM - Smart Agent Manager
+
+**Role:** Master Orchestrator + Pipeline Controller
+
+**Identity:** SAM is the master orchestrator for autonomous development pipelines. Coordinates specialized agents (Atlas, Dyna, Titan, Argus, Sage, Iris) through TDD cycles, manages state, and ensures quality gates are enforced.
+
+---
+
+## Core Responsibilities
+
+1. **Pipeline Orchestration** - Coordinate agents through the autonomous TDD pipeline
+2. **State Management** - Track progress in pipeline-status.yaml
+3. **Gate Enforcement** - Ensure quality gates are passed before proceeding
+4. **Agent Coordination** - Invoke the right agent at the right time
+5. **Error Handling** - Manage retries and escalations
+
+---
+
+## Communication Style
+
+Direct and systematic, focused on pipeline execution and agent coordination. Presents clear status updates and orchestrates workflows efficiently.
+
+---
+
+## Principles
+
+- Orchestrate agents through RED-GREEN-REFACTOR cycles without human intervention
+- Enforce quality gates: tests must fail before impl, pass after
+- Track state meticulously in pipeline-status.yaml
+- Escalate only when max retries exceeded
+- Never skip phases - TDD discipline is mandatory
+
+---
+
+## Pipeline Phases
+
+### Phase 1: Validation
+- Validate PRD completeness
+- Check technical feasibility (Architect)
+- Verify acceptance criteria are testable
+
+### Phase 2: Planning
+- Generate epics and stories from PRD
+- Initialize sprint-status tracking
+- Prioritize story order
+
+### Phase 3: TDD Loop (per story)
+1. **RED** - Titan (Test Architect) writes failing tests
+2. **GREEN** - Dyna (Developer) implements until tests pass
+3. **REFACTOR** - Argus (Reviewer) reviews and improves
+
+### Phase 4: Completion
+- Verify all stories complete
+- Generate documentation (Sage - Tech Writer)
+- Produce final report
+
+---
+
+## State Tracking
+
+SAM Master maintains state in `sdocs/autonomous-runs/<run-id>/pipeline-status.yaml`:
+
+```yaml
+run_id: <timestamp>
+prd_path: <path-to-prd>
+current_phase: validation|planning|implementation|completion
+current_story: <story-id>
+stories:
+  - id: story-1
+    status: pending|red|green|refactor|done
+    retry_count: 0
+    tests_written: false
+    tests_passing: false
+    review_passed: false
+```
+
+---
+
+## Escalation Rules
+
+- **Max 3 retries** per story phase before escalation
+- **Blocking errors** escalate immediately
+- **Ambiguous requirements** halt pipeline with clear error
+- Escalation produces detailed report for human review

package/templates/_sam/core/config.yaml

@@ -0,0 +1,31 @@
+# SAM - Smart Agent Manager
+# Core Configuration
+# Version: 1.0.0
+
+# User Settings
+user_name: Santosh
+communication_language: English
+document_output_language: English
+
+# Output Configuration
+output_folder: "{project-root}/sdocs"
+
+# Pipeline Settings
+autonomous_mode: true
+max_retry_attempts: 3
+tdd_enforced: true
+
+# Agent Manifest Location
+agent_manifest_path: "{project-root}/_sam/_config/agent-manifest.csv"
+
+# Workflow Settings
+default_workflow: autonomous-tdd
+standalone_mode: false  # Allows chaining without human prompts
+
+# Gate Configurations
+gates:
+  prd_validation: true
+  tests_must_fail_before_impl: true
+  tests_must_pass_after_impl: true
+  code_review_required: true
+  coverage_threshold: 80

package/templates/_sam/core/workflows/autonomous-tdd/steps/step-01-validate-prd.md

@@ -0,0 +1,213 @@
+---
+step: 1
+name: validate-prd
+description: Validate PRD completeness and technical feasibility
+agents: [architect, ux-designer]
+---
+
+# Step 1: Validate PRD
+
+**Purpose:** Ensure the PRD is complete, technically feasible, and has testable acceptance criteria before proceeding with development.
+
+---
+
+## ENTRY CONDITIONS
+
+- PRD file path provided
+- PRD file exists and is readable
+- Pipeline status initialized
+
+---
+
+## PROCESS
+
+### 1.1 Load and Parse PRD
+
+```
+1. Read PRD file from provided path
+2. Extract:
+   - Project/feature name
+   - Objectives
+   - Features/requirements
+   - Acceptance criteria
+   - Technical constraints (if any)
+   - UX requirements (if any)
+3. Store parsed data in pipeline context
+```
+
+### 1.2 Architect Review (Winston)
+
+**Invoke Architect agent to assess:**
+
+```yaml
+architect_review:
+  technical_feasibility:
+    - Can each feature be implemented?
+    - Are there technical blockers?
+    - What technologies/patterns required?
+
+  risks_and_dependencies:
+    - External dependencies?
+    - Integration points?
+    - Scalability concerns?
+
+  testability:
+    - Are acceptance criteria testable?
+    - Can we write automated tests?
+    - Any criteria needing clarification?
+
+  effort_assessment:
+    - Rough complexity estimate
+    - Suggested story breakdown
+```
+
+**Architect Output Format:**
+
+```markdown
+## Technical Feasibility Review
+
+### Overall Assessment: [APPROVED / NEEDS_REVISION / BLOCKED]
+
+### Feature Analysis
+| Feature | Feasible | Concerns | Notes |
+|---------|----------|----------|-------|
+| Feature 1 | Yes | None | Straightforward |
+| Feature 2 | Yes | Minor | Needs API design |
+
+### Risks Identified
+1. [Risk 1] - Mitigation: [...]
+2. [Risk 2] - Mitigation: [...]
+
+### Dependencies
+- [Dependency 1]
+- [Dependency 2]
+
+### Testability Assessment
+- All AC testable: [Yes/No]
+- Clarification needed: [List items]
+
+### Recommendation
+[Proceed / Revise PRD / Block with reason]
+```
+
+### 1.3 UX Review (Sally) - If UI Present
+
+**Invoke UX Designer agent if PRD contains UI requirements:**
+
+```yaml
+ux_review:
+  user_flow:
+    - Is user journey clear?
+    - Are interactions defined?
+
+  accessibility:
+    - Accessibility requirements stated?
+    - WCAG compliance level?
+
+  design_requirements:
+    - Design specs available?
+    - Style guide referenced?
+
+  testability:
+    - Can UX criteria be tested?
+    - Automation possible?
+```
+
+**UX Output Format:**
+
+```markdown
+## UX Requirements Review
+
+### Overall Assessment: [APPROVED / NEEDS_REVISION]
+
+### User Flow Analysis
+- Primary flow clear: [Yes/No]
+- Edge cases defined: [Yes/No]
+
+### Accessibility
+- Requirements stated: [Yes/No]
+- Recommendations: [...]
+
+### Design Completeness
+- Sufficient for implementation: [Yes/No]
+- Missing elements: [List]
+
+### Recommendation
+[Proceed / Revise PRD]
+```
+
+### 1.4 Consolidate Validation Results
+
+```yaml
+validation_result:
+  status: "passed|failed"
+  architect_approval: true|false
+  ux_approval: true|false|not_applicable
+
+  blocking_issues: []
+  warnings: []
+  clarifications_needed: []
+
+  recommendation: "proceed|revise|block"
+```
+
+---
+
+## UPDATE STATE
+
+```yaml
+# Update pipeline-status.yaml
+validation:
+  status: "passed"  # or "failed"
+  completed_at: "<timestamp>"
+  architect_approval: true
+  ux_approval: true
+  issues:
+    - type: "warning"
+      description: "..."
+    - type: "clarification"
+      description: "..."
+```
+
+---
+
+## EXIT CONDITIONS
+
+### Pass → Proceed to Phase 2
+- Architect approves technical feasibility
+- UX approves (if applicable)
+- No blocking issues
+- All AC deemed testable
+
+### Fail → Halt Pipeline
+- Technical feasibility blocked
+- Critical UX issues
+- Untestable acceptance criteria
+
+**On Failure:**
+```yaml
+# Generate validation failure report
+validation_failure_report:
+  prd_path: "<path>"
+  blocking_issues:
+    - issue: "..."
+      agent: "architect|ux-designer"
+      recommendation: "..."
+
+  action_required: "Revise PRD and re-run pipeline"
+```
+
+---
+
+## AUTONOMOUS BEHAVIOR
+
+In autonomous mode:
+- **No human prompts** - proceed or fail based on gates
+- **Document everything** - all decisions logged
+- **Clear failure reports** - actionable feedback if blocked
+
+---
+
+## NEXT STEP
+
+On validation pass → Load `step-02-generate-stories.md`

package/templates/_sam/core/workflows/autonomous-tdd/steps/step-02-generate-stories.md

@@ -0,0 +1,266 @@
+---
+step: 2
+name: generate-stories
+description: Generate epics and user stories from validated PRD
+agents: [sam-master]
+---
+
+# Step 2: Generate Stories
+
+**Purpose:** Break down the validated PRD into implementable epics and user stories with clear, testable acceptance criteria.
+
+---
+
+## ENTRY CONDITIONS
+
+- Phase 1 validation passed
+- PRD parsed and available in context
+- Architect recommendations available
+
+---
+
+## PROCESS
+
+### 2.1 Analyze PRD Structure
+
+```
+1. Identify major feature areas (candidates for epics)
+2. Group related requirements
+3. Identify dependencies between features
+4. Note technical constraints from architect review
+```
+
+### 2.2 Create Epics
+
+**For each major feature area:**
+
+```yaml
+epic:
+  id: "epic-1"
+  title: "User Authentication"
+  description: "All features related to user authentication and session management"
+  prd_sections: ["3.1", "3.2"]  # Reference to PRD sections
+  stories: []  # To be populated
+  dependencies: []  # Other epics this depends on
+```
+
+### 2.3 Break Down into Stories
+
+**For each epic, create user stories:**
+
+```markdown
+# Story: epic-1-story-1
+
+## Title
+User can log in with email and password
+
+## Epic
+User Authentication (epic-1)
+
+## User Story
+As a registered user
+I want to log in with my email and password
+So that I can access my account
+
+## Acceptance Criteria
+
+### AC1: Successful Login
+- GIVEN a registered user with valid credentials
+- WHEN they submit email and password
+- THEN they are authenticated and redirected to dashboard
+
+### AC2: Invalid Credentials
+- GIVEN a user with invalid credentials
+- WHEN they submit email and password
+- THEN they see an error message "Invalid email or password"
+- AND they remain on the login page
+
+### AC3: Empty Fields
+- GIVEN the login form
+- WHEN user submits with empty email or password
+- THEN they see validation error for the empty field(s)
+
+## Technical Notes
+- Use JWT for session management (per architect)
+- Rate limit: 5 attempts per minute
+
+## Tasks
+- [ ] Task 1: Create login API endpoint
+- [ ] Task 2: Implement credential validation
+- [ ] Task 3: Generate and return JWT
+- [ ] Task 4: Create login form component
+- [ ] Task 5: Handle error states
+
+## Dependencies
+- None (first story)
+
+## Status
+pending
+```
+
+### 2.4 Story Sizing and Ordering
+
+**Apply sizing heuristics:**
+
+| Size | Criteria |
+|------|----------|
+| Small | 1-3 tasks, single component, ≤1 day |
+| Medium | 4-6 tasks, multiple components, 1-2 days |
+| Large | 7+ tasks, consider splitting |
+
+**Ordering rules:**
+1. Dependencies first
+2. Foundation before features
+3. Happy path before edge cases
+4. Core functionality before polish
+
+### 2.5 Write Story Files
+
+**Create story files in run directory:**
+
+```
+sdocs/autonomous-runs/<run-id>/stories/
+├── epic-1-story-1.md
+├── epic-1-story-2.md
+├── epic-2-story-1.md
+└── ...
+```
+
+**Story file template:**
+
+```markdown
+---
+id: epic-1-story-1
+epic: epic-1
+title: "User can log in with email and password"
+status: pending
+priority: 1
+size: medium
+dependencies: []
+---
+
+# User can log in with email and password
+
+## User Story
+As a registered user
+I want to log in with my email and password
+So that I can access my account
+
+## Acceptance Criteria
+
+### AC1: Successful Login
+- GIVEN a registered user with valid credentials
+- WHEN they submit email and password
+- THEN they are authenticated and redirected to dashboard
+
+### AC2: Invalid Credentials
+- GIVEN a user with invalid credentials
+- WHEN they submit email and password
+- THEN they see an error message "Invalid email or password"
+- AND they remain on the login page
+
+### AC3: Empty Fields Validation
+- GIVEN the login form
+- WHEN user submits with empty email or password
+- THEN they see validation error for the empty field(s)
+
+## Technical Notes
+[Notes from architect review]
+
+## Tasks
+- [ ] Task 1: Create login API endpoint
+- [ ] Task 2: Implement credential validation
+- [ ] Task 3: Generate and return JWT
+- [ ] Task 4: Create login form component
+- [ ] Task 5: Handle error states
+
+## Test Coverage
+- [ ] Acceptance tests (RED phase)
+- [ ] Unit tests (GREEN phase)
+
+## Review Checklist
+- [ ] Code review passed
+- [ ] All tests passing
+- [ ] No security issues
+```
+
+---
+
+## UPDATE STATE
+
+```yaml
+# Update pipeline-status.yaml
+current_phase: "implementation"
+stories:
+  - id: "epic-1-story-1"
+    title: "User can log in with email and password"
+    epic: "epic-1"
+    status: "pending"
+    priority: 1
+    file_path: "stories/epic-1-story-1.md"
+
+  - id: "epic-1-story-2"
+    title: "User can reset password"
+    epic: "epic-1"
+    status: "pending"
+    priority: 2
+    file_path: "stories/epic-1-story-2.md"
+    dependencies: ["epic-1-story-1"]
+```
+
+---
+
+## VALIDATION
+
+Before proceeding, verify:
+
+- [ ] All PRD features have corresponding stories
+- [ ] Each story has ≥1 acceptance criterion
+- [ ] Acceptance criteria follow GIVEN-WHEN-THEN format
+- [ ] Dependencies are acyclic (no circular deps)
+- [ ] Stories are appropriately sized
+- [ ] Priority order respects dependencies
+
+---
+
+## OUTPUT SUMMARY
+
+```markdown
+## Story Generation Complete
+
+### Epics Created: 3
+1. epic-1: User Authentication (4 stories)
+2. epic-2: Dashboard (3 stories)
+3. epic-3: Settings (2 stories)
+
+### Stories Created: 9
+| ID | Title | Size | Dependencies |
+|----|-------|------|--------------|
+| epic-1-story-1 | User can log in | M | None |
+| epic-1-story-2 | User can reset password | M | story-1 |
+| ... | ... | ... | ... |
+
+### Implementation Order
+1. epic-1-story-1 (no deps)
+2. epic-1-story-2 (after story-1)
+3. ...
+
+### Ready for TDD Loop
+Proceeding to Phase 3: Implementation
+```
+
+---
+
+## AUTONOMOUS BEHAVIOR
+
+In autonomous mode:
+- Generate all stories without prompts
+- Apply sensible defaults for sizing
+- Order by dependencies automatically
+- Proceed to Phase 3 immediately upon completion
+
+---
+
+## NEXT STEP
+
+On story generation complete → Load `step-03-tdd-loop.md`