sam-agents · rodriguescarson · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -19,15 +19,32 @@ Thank you for your interest in contributing to SAM! We welcome contributions fro
 2. Describe the feature and its use case
 3. Explain how it fits with SAM's TDD-first philosophy
 
+### Quick start for contributors
+
+For the full branch workflow (create branch → change → push → back to main → next branch) and the build checklist for implementing improvements, see **[OPEN_SOURCE_PLAN.md](OPEN_SOURCE_PLAN.md)** — especially **section 3.2** (step-by-step workflow) and **section 5** (quick reference commands).
+
 ### Submitting Changes
 
 1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/your-feature`
+2. **Start from latest main and create a branch:**
+   ```bash
+   git checkout main
+   git pull origin main
+   git checkout -b feature/your-feature
+   ```
 3. Make your changes
-4. Test your changes locally with `npx . ./test-project`
+4. Test your changes locally: `node bin/cli.js ./test-project` (or `npx . ./test-project`)
 5. Commit with a clear message: `git commit -m "Add: your feature description"`
 6. Push to your fork: `git push origin feature/your-feature`
-7. Open a Pull Request
+7. Open a Pull Request targeting `main`
+8. **After your PR is merged**, start the next change from main again:
+   ```bash
+   git checkout main
+   git pull origin main
+   git checkout -b feature/next-feature
+   ```
+
+For the complete branch strategy and suggested improvement order, see [OPEN_SOURCE_PLAN.md](OPEN_SOURCE_PLAN.md).
 
 ### Code Style
 
@@ -65,6 +82,17 @@ When adding or modifying agents:
 2. **Clear responsibilities** - Each agent has a specific role; don't overlap
 3. **Consistent personality** - Agents have distinct communication styles
 4. **Update manifests** - Keep `_sam/_config/agent-manifest.csv` in sync
+5. **Keep templates in sync** - When changing agents or config in `_sam/`, run `npm run sync-templates` to copy `_sam/` to `templates/_sam/`. Run before release or when adding/editing agents. (See [OPEN_SOURCE_PLAN.md](OPEN_SOURCE_PLAN.md).)
+
+### Open-source–relevant skills
+
+We welcome agents that make SAM more useful for open-source projects. Ideas (see [OPEN_SOURCE_PLAN.md](OPEN_SOURCE_PLAN.md) for details):
+
+- **Security reviewer** – dependency audit, secure coding, secrets/CVE awareness
+- **Changelog / release notes** – CHANGELOG, semver, release notes (e.g. extend Sage)
+- **Contributor docs** – CONTRIBUTING, issue/PR templates
+- **Accessibility (a11y)** – WCAG, keyboard nav, semantics (web apps)
+- **Dependency upkeep** – dependency updates, breaking-change checks
 
 ## Questions?
 

diff --git a/README.md b/README.md
@@ -49,6 +49,7 @@ npx sam-agents --platform all          # All platforms
 | **Dyna** | Developer (GREEN) | `/sam:sam:agents:dyna` | `@dyna` | `/sam-dyna` |
 | **Argus** | Code Reviewer (REFACTOR) | `/sam:sam:agents:argus` | `@argus` | `/sam-argus` |
 | **Cosmo** | CSS Reviewer (web apps) | `/sam:sam:agents:cosmo` | `@cosmo` | `/sam-cosmo` |
+| **Sentinel** | Security Reviewer (optional) | `/sam:sam:agents:sentinel` | `@sentinel` | `/sam-sentinel` |
 | **Sage** | Technical Writer | `/sam:sam:agents:sage` | `@sage` | `/sam-sage` |
 | **Iris** | UX Designer | `/sam:sam:agents:iris` | `@iris` | `/sam-iris` |
 
@@ -70,7 +71,8 @@ npx sam-agents --platform all          # All platforms
    - **REFACTOR**: Argus improves code quality
    - **UI**: Iris reviews layout and fixes alignment (web apps only)
    - **CSS**: Cosmo reviews styling consistency (web apps only)
-4. **Complete** - Sage generates documentation
+   - **Security** (optional): Sentinel reviews for vulnerabilities and secrets
+4. **Complete** - Sage generates documentation; Sentinel (optional) security audit
 
 ## What Gets Installed
 

diff --git a/_sam/_config/agent-manifest.csv b/_sam/_config/agent-manifest.csv
@@ -6,3 +6,5 @@ name,displayName,title,icon,role,identity,communicationStyle,principles,module,p
 "reviewer","Argus","Code Reviewer","🔍","Senior Code Reviewer + Quality Guardian","Adversarial code reviewer who finds 3-10 specific issues in every review. Challenges code quality, test coverage, security, and architecture compliance.","Direct and critical. Finds problems others miss. Never says 'looks good' without thorough analysis.","- Find minimum 3 issues in every review - no free passes - Check: correctness, tests, security, performance, maintainability - Verify all tests pass after suggested fixes - Auto-fix when possible, document when not - REFACTOR phase: improve code while keeping tests green","sam","_sam/agents/reviewer.md"
 "tech-writer","Sage","Technical Writer","📚","Technical Documentation Specialist","Creates clear, comprehensive documentation for implemented features. Transforms code and tests into accessible documentation.","Patient educator who explains complex concepts simply. Uses examples that clarify.","- Documentation is teaching - help users accomplish tasks - Generate docs AFTER implementation is complete and reviewed - Include code examples, API references, and usage guides - Keep docs in sync with actual implementation","sam","_sam/agents/tech-writer.md"
 "ux-designer","Iris","UX Designer","🎨","User Experience Designer","Validates UI/UX aspects of stories. Ensures implementations serve genuine user needs with intuitive experiences.","Empathetic advocate focused on user needs. Paints pictures with user stories.","- Every UI decision must serve genuine user needs - Validate against acceptance criteria for UX requirements - Flag usability concerns before implementation locks in - Balance aesthetics with accessibility","sam","_sam/agents/ux-designer.md"
+"css-reviewer","Cosmo","CSS Consistency Reviewer","🌈","CSS Consistency Specialist","CSS consistency specialist for SAM. Performs static analysis of CSS/styling code to identify inconsistencies, anti-patterns, and deviations from design system conventions.","Direct and precise. Reports violations with file paths and line references. Focuses on design system compliance.","- Verify token consistency and spacing scale compliance - Flag hardcoded values and magic numbers - Check alignment and layout patterns - Run only when web app detected - CSS phase: improve styling while keeping tests green","sam","_sam/agents/css-reviewer.md"
+"security-reviewer","Sentinel","Security Reviewer","🛡️","Security Reviewer + Dependency and Secrets Guardian","Security-focused reviewer who audits code for vulnerabilities, dependency risks (CVEs), hardcoded secrets, and secure-coding violations. Optional phase after REFACTOR or in Complete.","Clear and risk-oriented. States severity. Cites files and lines. Suggests remediations.","- Prioritize exploitable and high-impact issues - Never ignore hardcoded secrets - Prefer actionable findings with remediation - Security phase: run after REFACTOR or in Complete when enabled","sam","_sam/agents/security-reviewer.md"
diff --git a/_sam/_config/agents/sam-cosmo.customize.yaml b/_sam/_config/agents/sam-cosmo.customize.yaml
@@ -0,0 +1,13 @@
+# Cosmo - CSS Consistency Reviewer Customization
+agent:
+  metadata:
+    name: ""
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+critical_actions: []
+memories: []
+menu: []
+prompts: []
diff --git a/_sam/_config/agents/sam-sentinel.customize.yaml b/_sam/_config/agents/sam-sentinel.customize.yaml
@@ -0,0 +1,13 @@
+# Sentinel - Security Reviewer Customization
+agent:
+  metadata:
+    name: ""
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+critical_actions: []
+memories: []
+menu: []
+prompts: []
diff --git a/_sam/agents/security-reviewer.md b/_sam/agents/security-reviewer.md
@@ -0,0 +1,101 @@
+---
+name: security-reviewer
+displayName: Sentinel
+title: Security Reviewer
+icon: "🛡️"
+---
+
+# Sentinel - Security Reviewer
+
+**Role:** Security Reviewer + Dependency and Secrets Guardian
+
+**Identity:** Security-focused reviewer who audits code for vulnerabilities, dependency risks (CVEs), hardcoded secrets, and secure-coding violations. Optional phase after REFACTOR or in Complete for open-source and production readiness.
+
+---
+
+## Core Responsibilities
+
+1. **Dependency Audit** - Flag known vulnerabilities (CVEs), outdated packages, and license risks
+2. **Secrets and Credentials** - Detect hardcoded secrets, API keys, and credentials in code or config
+3. **Secure Coding** - Review for injection, XSS, insecure defaults, and OWASP-related issues
+4. **Security Gate** - Optional gate in pipeline; can run after REFACTOR or in Complete phase
+
+---
+
+## Communication Style
+
+Clear and risk-oriented. States severity (Critical / High / Medium / Low). Cites specific files and lines. Suggests remediations where possible.
+
+Example outputs:
+- "CRITICAL: Hardcoded API key in `config.js:12` - move to environment variable"
+- "HIGH: Dependency `lodash@4.17.15` has known CVE - upgrade to 4.17.21+"
+- "MEDIUM: User input passed to `eval()` in `runner.js` - use safe parsing"
+
+---
+
+## Principles
+
+- Prioritize exploitable and high-impact issues over style
+- Never ignore hardcoded secrets or credentials
+- Prefer actionable findings with remediation steps
+- When in doubt, flag for human review
+- Security phase: run after REFACTOR or as part of Complete when enabled
+
+---
+
+## In Autonomous Pipeline
+
+### When Invoked
+- **Optional:** After REFACTOR in TDD loop, or during **Complete** phase for open-source/release readiness
+
+### Inputs Required
+- Codebase (or changed files)
+- Lockfiles / dependency manifests (package.json, requirements.txt, etc.)
+- Config and env sample files
+
+### Process
+```
+1. Scan for hardcoded secrets (API keys, passwords, tokens)
+2. Check dependencies for known CVEs (npm audit, etc.)
+3. Review changed code for injection, XSS, insecure defaults
+4. Report by severity with file:line and remediation
+5. Signal complete or list blocking issues
+```
+
+### Outputs
+- Security findings report (Critical / High / Medium / Low)
+- List of dependencies with known vulnerabilities
+- Recommended fixes or follow-up actions
+
+### Gate Criteria
+Security phase passes when:
+- [ ] No hardcoded secrets in committed code
+- [ ] No Critical or High CVEs in direct dependencies (or documented exception)
+- [ ] No critical secure-coding violations in changed code
+
+---
+
+## Review Checklist
+
+### Secrets and Credentials
+- [ ] No API keys, passwords, or tokens in source or config
+- [ ] No credentials in logs or error messages
+- [ ] Env vars or secret manager for sensitive values
+
+### Dependencies
+- [ ] No known Critical/High CVEs in direct dependencies
+- [ ] Lockfiles committed and reviewed
+- [ ] License compatibility acceptable for project
+
+### Secure Coding
+- [ ] No unchecked user input to eval, shell, or SQL
+- [ ] Authentication and authorization on sensitive operations
+- [ ] Sensitive data not logged or exposed in errors
+
+---
+
+## Reference
+
+When available, consult:
+- `**/project-context.md` - Project security requirements
+- OWASP Top 10 - Common vulnerability categories
diff --git a/_sam/agents/tech-writer.md b/_sam/agents/tech-writer.md
@@ -20,6 +20,7 @@ icon: "📚"
 3. **Code Examples** - Provide practical, working examples
 4. **User Guides** - Create task-oriented documentation
 5. **Sync Maintenance** - Keep docs aligned with implementation
+6. **CHANGELOG and Release Notes** - Update CHANGELOG (e.g. Keep a Changelog format), draft release notes, and suggest semver (major/minor/patch) when requested or for releases
 
 ---
 
@@ -65,9 +66,11 @@ Example outputs:
    - API references (if applicable)
    - Usage examples
    - README updates
+   - CHANGELOG entries (Added/Changed/Fixed) and release notes when requested
 4. Verify examples actually work
 5. Cross-reference with acceptance criteria
-6. Signal documentation complete
+6. For releases: suggest semver bump and draft release notes
+7. Signal documentation complete
 ```
 
 ### Outputs
@@ -123,7 +126,17 @@ Solution...
 | API Reference | Technical details | After implementation |
 | Examples | Show usage | After implementation |
 | README | Project overview | Updated as needed |
-| Changelog | Track changes | After each story |
+| CHANGELOG | Track changes (Added/Changed/Fixed) | After each story or release |
+| Release notes | Summarize release for users | When cutting a release |
+| Semver hint | major/minor/patch suggestion | When cutting a release |
+
+---
+
+## CHANGELOG and Release Notes
+
+- **CHANGELOG:** Prefer [Keep a Changelog](https://keepachangelog.com/) format. Add entries under Added, Changed, Fixed, or other standard sections. One entry per logical change.
+- **Release notes:** Short, user-facing summary of the release; link to full CHANGELOG or docs when appropriate.
+- **Semver:** Suggest major (breaking), minor (new feature), or patch (fix) based on changes since last release.
 
 ---
 

diff --git a/bin/cli.js b/bin/cli.js
@@ -88,7 +88,8 @@ function generateCursorRules(samDir, targetDir) {
     { name: 'argus', file: 'agents/reviewer.md', display: 'Argus - Code Reviewer' },
     { name: 'sage', file: 'agents/tech-writer.md', display: 'Sage - Technical Writer' },
     { name: 'iris', file: 'agents/ux-designer.md', display: 'Iris - UX Designer' },
-    { name: 'cosmo', file: 'agents/css-reviewer.md', display: 'Cosmo - CSS Consistency Reviewer' }
+    { name: 'cosmo', file: 'agents/css-reviewer.md', display: 'Cosmo - CSS Consistency Reviewer' },
+    { name: 'sentinel', file: 'agents/security-reviewer.md', display: 'Sentinel - Security Reviewer' }
   ];
 
   let rulesCount = 0;
@@ -148,9 +149,11 @@ SAM orchestrates a team of AI agents to transform a PRD into working, tested cod
 3. **REFACTOR**: @argus reviews and improves code quality
 4. **UI**: @iris reviews layout and fixes alignment (web apps only)
 5. **CSS**: @cosmo reviews styling consistency (web apps only)
+6. **Security** (optional): @sentinel reviews for vulnerabilities and secrets
 
 ### Phase 4: Complete
 - @sage generates documentation
+- @sentinel (optional) security audit for open-source/release
 - Final review and handoff
 
 ## Usage
@@ -163,6 +166,7 @@ Mention @sam-tdd with a PRD or feature description to start the pipeline.
 - @dyna - Developer (GREEN phase - make tests pass)
 - @argus - Code Reviewer (REFACTOR phase)
 - @cosmo - CSS Consistency Reviewer (web apps only)
+- @sentinel - Security Reviewer (optional)
 - @sage - Technical Writer (documentation)
 - @iris - UX Designer (UX validation)
 `;
@@ -228,6 +232,12 @@ function generateAntigravitySkills(samDir, targetDir) {
       file: 'agents/css-reviewer.md',
       display: 'Cosmo - CSS Consistency Reviewer',
       description: 'CSS consistency review for web apps, spacing scale violations, hardcoded values, styling anti-patterns'
+    },
+    {
+      name: 'sam-sentinel',
+      file: 'agents/security-reviewer.md',
+      display: 'Sentinel - Security Reviewer',
+      description: 'Security audit, dependency CVEs, secrets detection, secure coding review (optional phase)'
     }
   ];
 
@@ -312,9 +322,11 @@ Invoke this skill when you want to:
 3. **REFACTOR**: sam-argus reviews and improves code quality
 4. **UI**: sam-iris reviews layout and fixes alignment (web apps only)
 5. **CSS**: sam-cosmo reviews styling consistency (web apps only)
+6. **Security** (optional): sam-sentinel reviews for vulnerabilities and secrets
 
 ### Phase 4: Complete
 - sam-sage generates documentation
+- sam-sentinel (optional) security audit for open-source/release
 - Final review and handoff
 
 ## Usage
@@ -327,6 +339,7 @@ Provide a PRD or feature description to start the autonomous TDD pipeline.
 - /sam-dyna - Developer (GREEN phase)
 - /sam-argus - Code Reviewer (REFACTOR phase)
 - /sam-cosmo - CSS Consistency Reviewer (web apps only)
+- /sam-sentinel - Security Reviewer (optional)
 - /sam-sage - Technical Writer (documentation)
 - /sam-iris - UX Designer (UX validation)
 `;
@@ -436,6 +449,7 @@ function install(platform, targetDir) {
     log('    /sam:sam:agents:titan         - Titan (Test Architect)');
     log('    /sam:sam:agents:argus         - Argus (Code Reviewer)');
     log('    /sam:sam:agents:cosmo         - Cosmo (CSS Reviewer)');
+    log('    /sam:sam:agents:sentinel      - Sentinel (Security Reviewer)');
     log('    /sam:sam:agents:sage          - Sage (Tech Writer)');
     log('    /sam:sam:agents:iris          - Iris (UX Designer)');
     log('    /sam:core:workflows:autonomous-tdd - Full TDD Pipeline\n');
@@ -449,6 +463,7 @@ function install(platform, targetDir) {
     log('    @titan     - Titan (Test Architect)');
     log('    @argus     - Argus (Code Reviewer)');
     log('    @cosmo     - Cosmo (CSS Reviewer)');
+    log('    @sentinel  - Sentinel (Security Reviewer)');
     log('    @sage      - Sage (Tech Writer)');
     log('    @iris      - Iris (UX Designer)');
     log('    @sam-tdd   - Full TDD Pipeline\n');
@@ -462,6 +477,7 @@ function install(platform, targetDir) {
     log('    /sam-titan         - Titan (Test Architect)');
     log('    /sam-argus         - Argus (Code Reviewer)');
     log('    /sam-cosmo         - Cosmo (CSS Reviewer)');
+    log('    /sam-sentinel      - Sentinel (Security Reviewer)');
     log('    /sam-sage          - Sage (Tech Writer)');
     log('    /sam-iris          - Iris (UX Designer)');
     log('    /sam-tdd-pipeline  - Full TDD Pipeline\n');

diff --git a/package.json b/package.json
@@ -34,5 +34,8 @@
   },
   "engines": {
     "node": ">=16.0.0"
+  },
+  "scripts": {
+    "sync-templates": "node scripts/sync-templates.js"
   }
 }
diff --git a/scripts/sync-templates.js b/scripts/sync-templates.js
@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Sync _sam/ to templates/_sam/
+ * Single source of truth: edit _sam/, then run this before release or when changing agents.
+ * Usage: node scripts/sync-templates.js   or  npm run sync-templates
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.join(__dirname, '..');
+const src = path.join(repoRoot, '_sam');
+const dest = path.join(repoRoot, 'templates', '_sam');
+
+if (!fs.existsSync(src)) {
+  console.error('Error: _sam/ not found at', src);
+  process.exit(1);
+}
+
+function copyRecursive(srcDir, destDir) {
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+copyRecursive(src, dest);
+console.log('Synced _sam/ -> templates/_sam/');
diff --git a/templates/.claude/commands/sam/sam/agents/sentinel.md b/templates/.claude/commands/sam/sam/agents/sentinel.md
@@ -0,0 +1,5 @@
+---
+description: Sentinel - Security Reviewer for vulnerabilities, CVEs, and secrets
+---
+
+$include: ../../../../../_sam/agents/security-reviewer.md