docs: Add quick-start and branch workflow to CONTRIBUTING

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?
 

_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"

_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: []

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"

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: []