From 27cc1c54af4e15b572bc7346ef49f3d56a322c60 Mon Sep 17 00:00:00 2001 From: Carson Rodrigues Date: Mon, 9 Mar 2026 17:55:19 +0530 Subject: [PATCH 1/3] Add Cosmo to agent-manifest and sam-cosmo.customize.yaml; sync templates Made-with: Cursor --- _sam/_config/agent-manifest.csv | 1 + _sam/_config/agents/sam-cosmo.customize.yaml | 13 +++++++++++++ templates/_sam/_config/agent-manifest.csv | 1 + .../_sam/_config/agents/sam-cosmo.customize.yaml | 13 +++++++++++++ 4 files changed, 28 insertions(+) create mode 100644 _sam/_config/agents/sam-cosmo.customize.yaml create mode 100644 templates/_sam/_config/agents/sam-cosmo.customize.yaml diff --git a/_sam/_config/agent-manifest.csv b/_sam/_config/agent-manifest.csv index 2f05497..9792308 100644 --- a/_sam/_config/agent-manifest.csv +++ b/_sam/_config/agent-manifest.csv @@ -6,3 +6,4 @@ 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" diff --git a/_sam/_config/agents/sam-cosmo.customize.yaml b/_sam/_config/agents/sam-cosmo.customize.yaml new file mode 100644 index 0000000..5a94bd3 --- /dev/null +++ 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/templates/_sam/_config/agent-manifest.csv b/templates/_sam/_config/agent-manifest.csv index 2f05497..9792308 100644 --- a/templates/_sam/_config/agent-manifest.csv +++ b/templates/_sam/_config/agent-manifest.csv @@ -6,3 +6,4 @@ 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" diff --git a/templates/_sam/_config/agents/sam-cosmo.customize.yaml b/templates/_sam/_config/agents/sam-cosmo.customize.yaml new file mode 100644 index 0000000..5a94bd3 --- /dev/null +++ b/templates/_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: [] From 514526066ab96b81e5aaa9cdb36223d23c45c9d8 Mon Sep 17 00:00:00 2001 From: Carson Rodrigues Date: Mon, 9 Mar 2026 17:55:42 +0530 Subject: [PATCH 2/3] Add quick-start and branch workflow to CONTRIBUTING; link OPEN_SOURCE_PLAN Made-with: Cursor --- CONTRIBUTING.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47b8f40..75105a3 100644 --- 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 adding or changing agents, update both `_sam/` and `templates/_sam/` (and `bin/cli.js` + README when adding 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? From cbe448096cb3115b2a023f114d0bebf6a1d74997 Mon Sep 17 00:00:00 2001 From: Carson Rodrigues Date: Mon, 9 Mar 2026 17:56:02 +0530 Subject: [PATCH 3/3] Add sync-templates script and npm run sync-templates; document in CONTRIBUTING Made-with: Cursor --- CONTRIBUTING.md | 2 +- package.json | 3 +++ scripts/sync-templates.js | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 scripts/sync-templates.js diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75105a3..87dfcdf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,7 +82,7 @@ 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 adding or changing agents, update both `_sam/` and `templates/_sam/` (and `bin/cli.js` + README when adding agents). See [OPEN_SOURCE_PLAN.md](OPEN_SOURCE_PLAN.md). +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 diff --git a/package.json b/package.json index efe8ceb..772ea8c 100644 --- 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 new file mode 100644 index 0000000..4847121 --- /dev/null +++ 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/');