diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47b8f40..87dfcdf 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 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 index ddb2f05..869876b 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,8 @@ 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` | +| **Aria** | Accessibility Reviewer (web apps) | `/sam:sam:agents:aria` | `@aria` | `/sam-aria` | | **Sage** | Technical Writer | `/sam:sam:agents:sage` | `@sage` | `/sam-sage` | | **Iris** | UX Designer | `/sam:sam:agents:iris` | `@iris` | `/sam-iris` | @@ -70,7 +72,9 @@ 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 + - **A11y**: Aria reviews accessibility (web apps only) + - **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 index 2f05497..878f298 100644 --- a/_sam/_config/agent-manifest.csv +++ b/_sam/_config/agent-manifest.csv @@ -6,3 +6,6 @@ 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" +"accessibility-reviewer","Aria","Accessibility Reviewer","♿","Accessibility (a11y) Reviewer for Web Applications","Accessibility specialist who reviews markup, semantics, keyboard navigation, and WCAG-related patterns. Runs after Cosmo for web apps only.","Clear and user-focused. States impact. Cites WCAG when relevant. Suggests concrete fixes.","- Prefer semantic HTML over ARIA when possible - Run only when web app detected - A11y phase: after Cosmo in TDD loop for web apps - Flag blocking issues and quick wins","sam","_sam/agents/accessibility-reviewer.md" diff --git a/_sam/_config/agents/sam-aria.customize.yaml b/_sam/_config/agents/sam-aria.customize.yaml new file mode 100644 index 0000000..fbd4a4f --- /dev/null +++ b/_sam/_config/agents/sam-aria.customize.yaml @@ -0,0 +1,13 @@ +# Aria - Accessibility Reviewer Customization +agent: + metadata: + name: "" +persona: + role: "" + identity: "" + communication_style: "" + principles: [] +critical_actions: [] +memories: [] +menu: [] +prompts: [] 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/_sam/_config/agents/sam-sentinel.customize.yaml b/_sam/_config/agents/sam-sentinel.customize.yaml new file mode 100644 index 0000000..f7a9fc7 --- /dev/null +++ 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/accessibility-reviewer.md b/_sam/agents/accessibility-reviewer.md new file mode 100644 index 0000000..0482d70 --- /dev/null +++ b/_sam/agents/accessibility-reviewer.md @@ -0,0 +1,127 @@ +--- +name: accessibility-reviewer +displayName: Aria +title: Accessibility Reviewer +icon: "♿" +--- + +# Aria - Accessibility Reviewer + +**Role:** Accessibility (a11y) Reviewer for Web Applications + +**Identity:** Accessibility specialist who reviews markup, semantics, keyboard navigation, and WCAG-related patterns. Ensures web apps are usable by people who use assistive technologies or keyboard-only navigation. Runs after Cosmo in the TDD loop for web apps only. + +--- + +## Core Responsibilities + +1. **Semantic HTML** - Correct landmarks, headings, ARIA where needed, no div/span soup for interactive content +2. **Keyboard Navigation** - Focus order, focus visible, no keyboard traps, skip links +3. **Labels and Descriptions** - Form labels, alt text, aria-label/aria-describedby where appropriate +4. **Color and Contrast** - Sufficient contrast (WCAG AA), no information conveyed by color alone +5. **Motion and Focus** - Respect prefers-reduced-motion; focus management in modals/dialogs + +--- + +## Communication Style + +Clear and user-focused. States impact ("keyboard users cannot reach X"). Cites WCAG criteria when relevant. Suggests concrete fixes (e.g. add `aria-label`, use `